.NET zero-code instrumentation

Use the OpenTelemetry .NET Automatic Instrumentation to send traces and metrics from .NET applications and services to observability backends without having to modify their source code.

To learn how to instrument your service or application code, read Manual instrumentation.

Compatibility

OpenTelemetry .NET Automatic Instrumentation should work with all officially supported operating systems and versions of .NET.

The minimal supported version of .NET Framework is 4.6.2.

Supported processor architectures are:

• x86
• AMD64 (x86-64)
• ARM64 (Experimental)

CI tests run against the following operating systems:

• Alpine x64
• Alpine ARM64
• Debian x64
• Debian ARM64
• CentOS 7 x64 (.NET 8 is not supported)
• macOS Big Sur 11 x64
• Microsoft Windows Server 2022 x64
• Ubuntu 20.04 LTS x64
• Ubuntu 22.04 LTS ARM64

Setup

To instrument a .NET application automatically, download and run the installer script for your operating system.

Linux and macOS

Download and run the .sh script:

# Download the bash script
curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O

# Install core files
sh ./otel-dotnet-auto-install.sh

# Enable execution for the instrumentation script
chmod +x $HOME/.otel-dotnet-auto/instrument.sh

# Setup the instrumentation for the current shell session
. $HOME/.otel-dotnet-auto/instrument.sh

# Run your application with instrumentation
OTEL_SERVICE_NAME=myapp OTEL_RESOURCE_ATTRIBUTES=deployment.environment=staging,service.version=1.0.0 ./MyNetApp

brew install coreutils

Windows (PowerShell)

On Windows, use the PowerShell module as an Administrator:

# PowerShell 5.1 or higher is required
# Download the module
$module_url = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path -UseBasicParsing

# Import the module to use its functions
Import-Module $download_path

# Install core files (online vs offline method)
Install-OpenTelemetryCore
Install-OpenTelemetryCore -LocalPath "C:\Path\To\OpenTelemetry.zip"

# Set up the instrumentation for the current PowerShell session
Register-OpenTelemetryForCurrentSession -OTelServiceName "MyServiceDisplayName"

# Run your application with instrumentation
.\MyNetApp.exe

# You can get usage information by calling the following commands

# List all available commands
Get-Command -Module OpenTelemetry.DotNet.Auto

# Get command's usage information
Get-Help Install-OpenTelemetryCore -Detailed

Instrument a Windows Service running a .NET application

Use the OpenTelemetry.DotNet.Auto.psm1 PowerShell module to set up automatic instrumentation for a Windows Service:

# Import the module
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Install core files
Install-OpenTelemetryCore

# Set up your Windows Service instrumentation
Register-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName" -OTelServiceName "MyServiceDisplayName"

Configuration for Windows Service

For .NET Framework applications you can configure the most common OTEL_ settings (like OTEL_RESOURCE_ATTRIBUTES) via appSettings in App.config.

The alternative is to set environment variables for the Windows Service in the Windows Registry.

The registry key of a given Windows Service (named $svcName) is located under:

HKLM\SYSTEM\CurrentControlSet\Services\$svcName

The environment variables are defined in a REG_MULTI_SZ (multiline registry value) called Environment in the following format:

Var1=Value1
Var2=Value2

Instrument an ASP.NET application deployed on IIS

Use the OpenTelemetry.DotNet.Auto.psm1 PowerShell module to set up automatic instrumentation for IIS:

# Import the module
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Install core files
Install-OpenTelemetryCore

# Setup IIS instrumentation
Register-OpenTelemetryForIIS

Configuration for ASP.NET applications

For ASP.NET application you can configure the most common OTEL_ settings (like OTEL_SERVICE_NAME) via appSettings in Web.config.

If a service name is not explicitly configured, one will be generated for you. If the application is hosted on IIS in .NET Framework this will use SiteName\VirtualDirectoryPath ex: MySite\MyApp

For ASP.NET Core application you can use the <environmentVariable> elements inside the <aspNetCore> block of your Web.config file to set configuration via environment variables.

Advanced configuration

You can add the <environmentVariables> in applicationHost.config to set environment variables for given application pools.

Consider setting common environment variables, for all applications deployed to IIS by setting the environment variables for W3SVC and WAS Windows Services.

NuGet package

You can instrument self-contained applications using the NuGet packages. See NuGet packages for more information.

Instrument a container

For an example of Docker container instrumentation, see the example on GitHub.

You can also use the OpenTelemetry Operator for Kubernetes.

Configuring the agent

To see the full range of configuration options, see Configuration and settings.

Log to trace correlation

OpenTelemetry .NET SDK automatically correlates logs to trace data. When logs are emitted in the context of an active trace, trace context fields TraceId, SpanId, TraceState are automatically populated.

The following are logs produced by the sample console application:

"logRecords": [
    {
        "timeUnixNano": "1679392614538226700",
        "severityNumber": 9,
        "severityText": "Information",
        "body": {
            "stringValue": "Success! Today is: {Date:MMMM dd, yyyy}"
        },
        "flags": 1,
        "traceId": "21df288eada1ce4ace6c40f39a6d7ce1",
        "spanId": "a80119e5a05fed5a"
    }
]

For more information, see:

• OpenTelemetry .NET SDK
• OpenTelemetry Specification

Supported libraries and frameworks

The OpenTelemetry .NET Automatic Instrumentation supports a wide variety of libraries. For a complete list, see Instrumentations.

Troubleshooting

To see the telemetry from your application directly on the standard output, set the following environment variables to true before launching your application:

• OTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLED
• OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED
• OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED

For general troubleshooting steps and solutions to specific issues, see Troubleshooting.

Next steps

After you have automatic instrumentation configured for your app or service, you might want to send custom traces and metrics or add manual instrumentation to collect custom telemetry data.