OpenTelemetry .NET Automatic Instrumentation

This project adds OpenTelemetry instrumentation to .NET applications without having to modify their source code.

---

⚠️ The following documentation refers to the in-development version of OpenTelemetry .NET Automatic Instrumentation. Docs for the latest version (0.5.0) can be found here.

---

OpenTelemetry .NET Automatic Instrumentation is built on top of OpenTelemetry .NET:

• Core components: 1.4.0-rc.2
• System.Diagnostics.DiagnosticSource: 7.0.0 referencing System.Runtime.CompilerServices.Unsafe: 6.0.0

You can find all references in OpenTelemetry.AutoInstrumentation.csproj and OpenTelemetry.AutoInstrumentation.AdditionalDeps/Directory.Build.props.

To automatically instrument applications, the OpenTelemetry .NET Automatic Instrumentation does the following:

1. Injects and configures the OpenTelemetry .NET SDK into the application.
2. Adds OpenTelemetry Instrumentation to key packages and APIs used by the application.

You can enable the OpenTelemetry .NET Automatic Instrumentation as a .NET Profiler to inject additional instrumentations of this project at runtime, using a technique known as monkey-patching. When enabled, the OpenTelemetry .NET Automatic Instrumentation generates traces for libraries that don't already generate traces using the OpenTelemetry .NET SDK.

See design.md for an architectural overview.

Status

The versioning information and stability guarantees can be found in the versioning documentation.

Compatibility

OpenTelemetry .NET Automatic Instrumentation attempts to work with all officially supported operating systems and versions of .NET, and .NET Framework.

Versions lower than .NET Framework 4.6.2 are not supported.

.NET Core 3.1 is not supported. 0.4.0-beta.1 is the latest version supporting it.

CI tests run against the following operating systems:

• macOS Big Sur 11
• Microsoft Windows Server 2022
• Ubuntu 20.04 LTS
• Alpine

Instrumented libraries and frameworks

See config.md#instrumented-libraries-and-frameworks.

Get started

Install

Download and extract the appropriate binaries from the latest release.

The path where you put the binaries is referenced as $INSTALL_DIR

Instrument a .NET application

When running your application, make sure to:

1. Set the resources.
2. Set the environment variables from the table below.

Environment variable	.NET version	Value
COR_ENABLE_PROFILING	.NET Framework	1
COR_PROFILER	.NET Framework	{918728DD-259F-4A6A-AC2B-B85E1B658318}
COR_PROFILER_PATH_32	.NET Framework	$INSTALL_DIR/win-x86/OpenTelemetry.AutoInstrumentation.Native.dll
COR_PROFILER_PATH_64	.NET Framework	$INSTALL_DIR/win-x64/OpenTelemetry.AutoInstrumentation.Native.dll
CORECLR_ENABLE_PROFILING	.NET	1
CORECLR_PROFILER	.NET	{918728DD-259F-4A6A-AC2B-B85E1B658318}
CORECLR_PROFILER_PATH	.NET on Linux glibc	$INSTALL_DIR/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
CORECLR_PROFILER_PATH	.NET on Linux musl	$INSTALL_DIR/linux-musl-x64/OpenTelemetry.AutoInstrumentation.Native.so
CORECLR_PROFILER_PATH	.NET on macOS	$INSTALL_DIR/osx-x64/OpenTelemetry.AutoInstrumentation.Native.dylib
CORECLR_PROFILER_PATH_32	.NET on Windows	$INSTALL_DIR/win-x86/OpenTelemetry.AutoInstrumentation.Native.dll
CORECLR_PROFILER_PATH_64	.NET on Windows	$INSTALL_DIR/win-x64/OpenTelemetry.AutoInstrumentation.Native.dll
DOTNET_ADDITIONAL_DEPS	.NET	$INSTALL_DIR/AdditionalDeps
DOTNET_SHARED_STORE	.NET	$INSTALL_DIR/store
DOTNET_STARTUP_HOOKS	.NET	$INSTALL_DIR/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
OTEL_DOTNET_AUTO_HOME	All versions	$INSTALL_DIR
OTEL_DOTNET_AUTO_INTEGRATIONS_FILE	All versions	$INSTALL_DIR/integrations.json

Some settings can be omitted on .NET. For more information, see config.md.

Shell scripts

You can install OpenTelemetry .NET Automatic Instrumentation and instrument your .NET application using the provided Shell scripts. Example usage:

curl -sSfL https://raw.githubusercontent.com/open-telemetry/opentelemetry-dotnet-instrumentation/v0.5.1-beta.3/otel-dotnet-auto-install.sh -O
sh ./otel-dotnet-auto-install.sh
. $HOME/.otel-dotnet-auto/instrument.sh
OTEL_SERVICE_NAME=myapp OTEL_RESOURCE_ATTRIBUTES=deployment.environment=staging,service.version=1.0.0 dotnet run

otel-dotnet-auto-install.sh script uses environment variables as parameters:

Parameter	Description	Required	Default value
OTEL_DOTNET_AUTO_HOME	Location where binaries are to be installed	No	$HOME/.otel-dotnet-auto
OS_TYPE	Possible values: linux-glibc, linux-musl, macos, windows	No	Calculated
TMPDIR	Temporary directory used when downloading the files	No	$(mktemp -d)
VERSION	Version to download	No	v0.5.1-beta.3

instrument.sh script uses environment variables as parameters:

Parameter	Description	Required	Default value
ENABLE_PROFILING	Whether to set the .NET CLR Profiler, possible values: true, false	No	true
OTEL_DOTNET_AUTO_HOME	Location where binaries are to be installed	No	$HOME/.otel-dotnet-auto
OS_TYPE	Possible values: linux-glibc, linux-musl, macos, windows	No	Calculated

On macOS coreutils is required.

PowerShell module (Windows)

On Windows, you should install OpenTelemetry .NET Automatic Instrumentation and instrument your .NET application using the provided PowerShell module. Example usage (run as administrator):

# Download and import the module
$module_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-dotnet-instrumentation/v0.5.1-beta.3/OpenTelemetry.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path
Import-Module $download_path

# Install core files
Install-OpenTelemetryCore

# Setup IIS instrumentation
Register-OpenTelemetryForIIS

# Setup your Windows Service instrumentation
Register-OpenTelemetryForWindowsService -WindowsServiceName "MyServiceName" -OTelServiceName "MyServiceDisplayName"

# Setup environment to start instrumentation from the current PowerShell session
Register-OpenTelemetryForCurrentSession -OTelServiceName "MyServiceDisplayName"

# Get current installation location
Get-OpenTelemetryInstallDirectory

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

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

⚠️ Register for IIS and Windows Service performs a service restart.

Instrument a container

You can find our demonstrative example that uses Docker Compose here.

You can also consider using the Kubernetes Operator for OpenTelemetry Collector.

Instrument a Windows Service running a .NET application

See windows-service-instrumentation.md.

Instrument an ASP.NET application deployed on IIS

See iis-instrumentation.md.

Configuration

See config.md.

Manual instrumentation

See manual-instrumentation.md.

Troubleshooting

See troubleshooting.md.

Contact

See CONTRIBUTING.md.

Contributing

See CONTRIBUTING.md.

Community Roles

Maintainers (@open-telemetry/dotnet-instrumentation-maintainers):

• Chris Ventura, New Relic
• Paulo Janotti, Splunk
• Rajkumar Rangaraj, Microsoft
• Robert Pająk, Splunk
• Zach Montoya, Datadog

Approvers (@open-telemetry/dotnet-instrumentation-approvers):

• Piotr Kiełkowicz, Splunk
• Rasmus Kuusmann, Splunk

Emeritus Maintainer/Approver/Triager:

• Colin Higgins
• Greg Paperin
• Kevin Gosse
• Lucas Pimentel-Ordyna
• Mike Goldsmith
• Tony Redondo

Learn more about roles in the community repository.