This project adds OpenTelemetry instrumentation to .NET applications without having to modify their source code.
Warning The following documentation refers to the in-development version of OpenTelemetry .NET Automatic Instrumentation. Docs for the latest version (1.0.0) can be found here.
If you'd like to try the instrumentation on an existing application before learning more about the configuration options and the project, follow the instructions at Using the OpenTelemetry.AutoInstrumentation NuGet packages or use the appropriate install script:
- On Linux and macOS, use the shell scripts.
- On Windows, use the PowerShell module.
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 a demo using docker compose
, clone this repository and
follow the examples/demo/README.md.
OpenTelemetry .NET Automatic Instrumentation is built on top of OpenTelemetry .NET:
- Core components:
1.6.0
System.Diagnostics.DiagnosticSource
:7.0.2
referencingSystem.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:
- Injects and configures the OpenTelemetry .NET SDK into the application.
- 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.
The versioning information and stability guarantees can be found in the versioning documentation.
OpenTelemetry .NET Automatic Instrumentation attempts to work with all officially supported operating systems and versions of .NET.
The minimal supported version of
.NET Framework
is 4.6.2
.
CI tests run against the following operating systems:
See config.md#instrumented-libraries-and-frameworks.
Note ARM architectures are not supported yet, see #2181.
Instrumenting self-contained
applications is supported through NuGet packages.
Note that a self-contained
application is
automatically generated in .NET 7.0 whenever the dotnet publish
or dotnet build
command is used with a Runtime Identifier (RID) parameter, for example when -r
or --runtime
is used when running the command.
Until version v0.6.0-beta.1
(inclusive) there were issues instrumenting
the dotnet
CLI. To build and launch an instrumented application, take the
following into account if you are using one of the affected versions:
- Don't set the automatic instrumentation environment variables in the same session
used to run the
dotnet
tool. - Don't launch the application to be instrumented using
dotnet run
ordotnet <dll>
. Build the application in an isolated shell, without the automatic instrumentation environment variables set, and use a separate session with the automatic instrumentation variables to directly launch the executable.
Download and extract the appropriate binaries from the latest release.
Note The path where you put the binaries is referenced as
$INSTALL_DIR
When running your application, make sure to:
- Set the resources.
- 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 |
Note Some settings can be omitted on .NET. For more information, see config.md.
You can install OpenTelemetry .NET Automatic Instrumentation and instrument your .NET application using the provided Shell scripts.
Note On macOS
coreutils
is required.
Example usage:
# Download the bash script
curl -sSfL https://raw.githubusercontent.com/open-telemetry/opentelemetry-dotnet-instrumentation/v1.0.0/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
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 | 1.0.0 |
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 Windows, you should install OpenTelemetry .NET Automatic Instrumentation and instrument your .NET application using the provided PowerShell module. Example usage (run as administrator):
# Download the module
$module_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-dotnet-instrumentation/v1.0.0-rc.2/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:
# List all available commands
Get-Command -Module OpenTelemetry.DotNet.Auto
# Get command's usage information
Get-Help Install-OpenTelemetryCore -Detailed
Warning The PowerShell module works only on PowerShell 5.1 which is the one installed by default on Windows.
You can find our demonstrative example that uses Docker Compose here.
You can also consider using the Kubernetes Operator for OpenTelemetry Collector.
See windows-service-instrumentation.md.
See config.md.
See manual-instrumentation.md.
See troubleshooting.md.
See CONTRIBUTING.md.
See CONTRIBUTING.md.
Maintainers (@open-telemetry/dotnet-instrumentation-maintainers):
- Chris Ventura, New Relic
- Paulo Janotti, Splunk
- Piotr Kiełkowicz, Splunk
- Rajkumar Rangaraj, Microsoft
- Robert Pająk, Splunk
- Zach Montoya, Datadog
Approvers (@open-telemetry/dotnet-instrumentation-approvers):
- Rasmus Kuusmann, Splunk
Emeritus Maintainer/Approver/Triager:
Learn more about roles in the community repository.