open-telemetry / opentelemetry-dotnet-instrumentation

OpenTelemetry .NET Automatic Instrumentation 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.14.1) can be found in opentelemetry.io or versioned README. --- Quick start If you'd like to try the instrumentation on an existing application before learning more about the configuration options and the project, use the recommended installation method described 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. > [!NOTE] > The NuGet packages are the recommended way to deploy automatic instrumentation, > but they can't be used in all cases. See Limitations > for details. To see the telemetry from your application directly on the standard output, set the following environment variables to before launching your application: • • • For a demo using , clone this repository and follow the examples/demo/README.md. Components OpenTelemetry .NET Automatic Instrumentation is built on top of OpenTelemetry .NET: • Core components: • : referencing : 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. Status The versioning information and stability guarantees can be found in the versioning documentation. 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 . 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 Stream 9 x64 • macOS Sonoma 14 ARM64 • Microsoft Windows Server 2022 x64 • Microsoft Windows Server 2025 x64 • Ubuntu 22.04 LTS x64 • Ubuntu 22.04 LTS ARM64 Instrumented libraries and frameworks See config.md#instrumented-libraries-and-frameworks. Get started Considerations on scope Instrumenting applications is supported through NuGet packages. Note that a application is automatically generated in .NET 7+ whenever the or command is used with a Runtime Identifier (RID) parameter, for example when or is used when running the command. Install using NuGet packages The NuGet packages are the recommended way to deploy automatic instrumentation, but they can't be used in all cases. To install using the NuGet packages, see Using the OpenTelemetry.AutoInstrumentation NuGet packages. See Limitations for incompatible scenarios. Install manually To install the automatic instrumentation manually, download and extract the appropriate binaries from the latest release. > [!NOTE] > The path where you put the binaries is referenced as . Instrument a .NET application When running your application, make sure to: • Set the resources. • Set the environment variables from the table below. > [!NOTE] > Some settings can be omitted on .NET. For more information, see config.md. | Environment variable | .NET version | Value | |----------------------------|---------------------|---------------------------------------------------------------------------| | | .NET Framework | | | | .NET Framework | | | | .NET Framework | | | | .NET Framework | | | | .NET | | | | .NET | | | | .NET on Linux glibc | | | | .NET on Linux musl | | | | .NET on macOS | | | | .NET on Windows | | | | .NET on Windows | | | | .NET | | | | .NET | | | | .NET | | | | All versions | | > [!IMPORTANT] > Starting in .NET 8, the environment variable disables all diagnostics, including the CLR Profiler facility which is needed to launch the instrumentation, if not using .NET Startup hooks. Ensure that , or if you'd like to limit diagnostics only to the CLR Profiler, you may set both and while setting other diagnostics features to 0. See this issue for more guidance. Shell scripts You can install OpenTelemetry .NET Automatic Instrumentation and instrument your .NET application using the provided Shell scripts. > [!NOTE] > On macOS is required. Example usage: NOTE: for air-gapped environments you can provide either the installation archive directly with: or the folder with the archives, this has the added benefit that the install script will determine the correct archive to choose. script uses environment variables as parameters: | Parameter | Description | Required | Default value | |-------------------------|---------------------------------------------------------------------------------|----------|-----------------------------| | | Location where binaries are to be installed | No | | | | Possible values: , , , | No | *Calculated* | | | Possible values for Linux: , | No | *Calculated* | | | (deprecated) prefer | No | | | | Folder to download the archive to. Will use local archive if it already exists | No | or | | | Full path the archive to use for installation. (ideal for air-gapped scenarios) | No | *Calculated* | | | Version to download | No | | instrument.sh script uses environment variables as parameters: | Parameter…