.NET zero-code instrumentation

Send traces and metrics from .NET applications and services.

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:

CI tests run against the following operating systems:

Setup

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

Linux and macOS

Download, verify, and run the .sh script:

# Download the installer into a private directory
version="v1.17.0"
repository="open-telemetry/opentelemetry-dotnet-instrumentation"
release_workflow="$repository/.github/workflows/release.yml"
download_dir="$(mktemp -d "${TMPDIR:-/tmp}/otel-dotnet-auto-installer.XXXXXX")"
installer="$download_dir/otel-dotnet-auto-install.sh"
trap 'rm -rf "$download_dir"' 0

# Download, verify, and run the installer as a single conditional chain so a
# failed download or verification prevents the installer from running
curl -sSfL "https://github.com/$repository/releases/download/$version/otel-dotnet-auto-install.sh" -o "$installer" &&
  gh release verify-asset "$version" "$installer" --repo "$repository" &&
  gh attestation verify "$installer" \
    --repo "$repository" \
    --signer-workflow "$release_workflow" \
    --source-ref "refs/tags/$version" &&
  VERSION="$version" sh "$installer"

# 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.name=staging,service.version=1.0.0 ./MyNetApp

For air-gapped environments, verify the archive before transferring it and explicitly skip the installer’s online verification. You can provide the archive directly with:

SKIP_RELEASE_VERIFICATION=true LOCAL_PATH=<PATH_TO_ARCHIVE> sh ./otel-dotnet-auto-install.sh

Alternatively, provide the folder with the files, and the install script determines the correct file to use:

SKIP_RELEASE_VERIFICATION=true DOWNLOAD_DIR=<PATH_TO_FOLDER_WITH_FILES> sh ./otel-dotnet-auto-install.sh

Windows (PowerShell)

On Windows, use the PowerShell module as an Administrator.

# PowerShell 5.1 is required
#Requires -PSEdition Desktop

$version = "v1.17.0"
$repository = "open-telemetry/opentelemetry-dotnet-instrumentation"
$release_workflow = "$repository/.github/workflows/release.yml"
$skip_release_verification = $false

# Use a unique directory protected by the Program Files access controls.
$program_files = [System.Environment]::GetFolderPath([System.Environment+SpecialFolder]::ProgramFiles)
$download_dir = Join-Path $program_files "OpenTelemetry .NET AutoInstrumentation Download $([System.Guid]::NewGuid().ToString("N"))"
$download_path = Join-Path $download_dir "OpenTelemetry.DotNet.Auto.psm1"
$module_url = "https://github.com/$repository/releases/download/$version/OpenTelemetry.DotNet.Auto.psm1"

New-Item -ItemType Directory -Path $download_dir -ErrorAction Stop | Out-Null

try {
    Invoke-WebRequest -Uri $module_url -OutFile $download_path -UseBasicParsing

    if ($skip_release_verification) {
        Write-Warning "Release verification is skipped. Downloaded PowerShell code and binaries will not be verified."
    }
    else {
        $github_cli = Get-Command gh.exe -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
        if (-not $github_cli) {
            throw "The GitHub CLI ('gh') is required. Install it from https://cli.github.com/ or explicitly set `$skip_release_verification to `$true."
        }

        & $github_cli.Source release verify-asset $version $download_path --repo $repository
        if ($LASTEXITCODE -ne 0) {
            throw "GitHub release verification failed for the PowerShell module."
        }

        & $github_cli.Source attestation verify $download_path `
            --repo $repository `
            --signer-workflow $release_workflow `
            --source-ref "refs/tags/$version"
        if ($LASTEXITCODE -ne 0) {
            throw "GitHub artifact attestation verification failed for the PowerShell module."
        }
    }

    # Import the module only after successful verification.
    Import-Module $download_path

    # To install from a previously downloaded Windows archive, add:
    # -LocalPath "C:\Path\To\OpenTelemetry.zip"
    Install-OpenTelemetryCore -SkipReleaseVerification:$skip_release_verification -ErrorAction Stop

    # Cache the verified module for updates and uninstallation.
    Copy-Item -LiteralPath $download_path -Destination (Get-OpenTelemetryInstallDirectory) -Force
}
finally {
    if (Test-Path -LiteralPath $download_dir) {
        Remove-Item -LiteralPath $download_dir -Force -Recurse
    }
}

# 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 applications 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:

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, add console to the following environment variables value before launching your application:

  • OTEL_TRACES_EXPORTER
  • OTEL_METRICS_EXPORTER
  • OTEL_LOGS_EXPORTER

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.

Uninstall

Linux and macOS

On Linux and macOS, the installation steps only affect the current shell session so no explicit uninstallation is required.

Windows (PowerShell)

On Windows, use the PowerShell module as an Administrator.

# PowerShell 5.1 is required
#Requires -PSEdition Desktop

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

# If IIS was previously registered, unregister it
Unregister-OpenTelemetryForIIS

# If Windows services were previously registered, unregister them
Unregister-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName"

# Finally, uninstall OpenTelemetry instrumentation
Uninstall-OpenTelemetryCore
Getting Started

Get telemetry for your app in less than 5 minutes!

Available instrumentations

OpenTelemetry .NET Automatic Instrumentation supported libraries.

Configuration and settings

Create custom traces and metrics

Custom traces and metrics using .NET automatic instrumentation.

Using the OpenTelemetry.AutoInstrumentation NuGet packages

Troubleshooting .NET automatic instrumentation issues


Last modified September 23, 2026: Update docs after OTel .NET Auto 1.17.0 release (#11819) (352930da)