open-telemetry
/
opentelemetry-dotnet-instrumentation
mirror of https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
opentelemetry-dotnet-instru.../docs/README.md

301 lines
14 KiB
Markdown
Raw Blame History

# OpenTelemetry .NET Automatic Instrumentation
[![Slack](https://img.shields.io/badge/slack-@cncf/otel--dotnet--auto--instr-brightgreen.svg?logo=slack)](https://cloud-native.slack.com/archives/C01NR1YLSE7)
This project adds [OpenTelemetry instrumentation](https://opentelemetry.io/docs/concepts/instrumenting/#automatic-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.2](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest))
can be found in [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/docs/instrumentation/net/automatic)
or [here](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/v1.0.2/docs/README.md).
---
## Quick start
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](./using-the-nuget-packages.md#using-the-opentelemetryautoinstrumentation-nuget-packages)
or use the appropriate install script:
- On Linux and macOS, use the [shell scripts](#shell-scripts).
- On Windows, use the [PowerShell module](#powershell-module-windows).
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](../examples/demo/README.md).
## Components
OpenTelemetry .NET Automatic Instrumentation is built on top of
[OpenTelemetry .NET](https://github.com/open-telemetry/opentelemetry-dotnet):
- [Core components](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/VERSIONING.md#core-components):
[`1.6.0`](https://github.com/open-telemetry/opentelemetry-dotnet/releases/tag/core-1.6.0)
- `System.Diagnostics.DiagnosticSource`: [`7.0.2`](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource/7.0.2)
referencing `System.Runtime.CompilerServices.Unsafe`: [`6.0.0`](https://www.nuget.org/packages/System.Runtime.CompilerServices.Unsafe/6.0.0)
You can find all references in
[OpenTelemetry.AutoInstrumentation.csproj](../src/OpenTelemetry.AutoInstrumentation/OpenTelemetry.AutoInstrumentation.csproj)
and [OpenTelemetry.AutoInstrumentation.AdditionalDeps/Directory.Build.props](../src/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](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry/README.md#opentelemetry-net-sdk)
into the application.
1. Adds [OpenTelemetry Instrumentation](https://opentelemetry.io/docs/concepts/instrumenting/)
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](https://en.wikipedia.org/wiki/Monkey_patch). 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](design.md) for an architectural overview.
## Status
The versioning information and stability guarantees
can be found in the [versioning documentation](versioning.md).
## Compatibility
OpenTelemetry .NET Automatic Instrumentation attempts to work with all officially
supported operating systems and versions of
[.NET](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core).
The minimal supported version of
[.NET Framework](https://dotnet.microsoft.com/download/dotnet-framework)
is `4.6.2`.
CI tests run against the following operating systems:
- [Alpine](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docker/alpine.dockerfile)
- [CentOS 7](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docker/centos-build.dockerfile)
- [macOS Big Sur 11](https://github.com/actions/runner-images/blob/main/images/macos/macos-11-Readme.md)
- [Microsoft Windows Server 2022](https://github.com/actions/runner-images/blob/main/images/win/Windows2022-Readme.md)
- [Ubuntu 20.04 LTS](https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2004-Readme.md)
### Instrumented libraries and frameworks
See [config.md#instrumented-libraries-and-frameworks](config.md#instrumented-libraries-and-frameworks).
## Get started
> **Note**
> ARM architectures are not supported yet,
> see [#2181](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/issues/2181).
### Considerations on scope
Instrumenting [`self-contained`](https://learn.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained)
applications is supported through [NuGet packages](./using-the-nuget-packages.md).
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.
### Install
Download and extract the appropriate binaries from
[the latest release](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest).
> **Note**
> 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](config.md#resources).
1. 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](config.md#net-clr-profiler).
### Shell scripts
You can install OpenTelemetry .NET Automatic Instrumentation
and instrument your .NET application using the provided Shell scripts.
> **Note**
> On macOS [`coreutils`](https://formulae.brew.sh/formula/coreutils) is required.
Example usage:
```sh
# Download the bash script
curl -sSfL https://raw.githubusercontent.com/open-telemetry/opentelemetry-dotnet-instrumentation/v1.0.2/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.2` |
[instrument.sh](../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* |
### 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):
```powershell
# Download the module
$module_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-dotnet-instrumentation/v1.0.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:
```powershell
# 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.
## Instrument a container
You can find our demonstrative example
that uses Docker Compose [here](../examples/demo).
You can also consider using
the [Kubernetes Operator for OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-operator).
## Instrument a Windows Service running a .NET application
See [windows-service-instrumentation.md](windows-service-instrumentation.md).
## Instrument an ASP.NET application deployed on IIS
See [iis-instrumentation.md](iis-instrumentation.md).
## Configuration
See [config.md](config.md).
### Manual instrumentation
See [manual-instrumentation.md](manual-instrumentation.md).
## Log to trace correlation
See [log-trace-correlation.md](log-trace-correlation.md).
## Troubleshooting
See [troubleshooting.md](troubleshooting.md).
## Contact
See [CONTRIBUTING.md](CONTRIBUTING.md).
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## Community Roles
[Maintainers](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer)
([@open-telemetry/dotnet-instrumentation-maintainers](https://github.com/orgs/open-telemetry/teams/dotnet-instrumentation-maintainers)):
- [Chris Ventura](https://github.com/nrcventura), New Relic
- [Paulo Janotti](https://github.com/pjanotti), Splunk
- [Piotr Kiełkowicz](https://github.com/Kielek), Splunk
- [Rajkumar Rangaraj](https://github.com/rajkumar-rangaraj), Microsoft
- [Robert Pająk](https://github.com/pellared), Splunk
- [Zach Montoya](https://github.com/zacharycmontoya), Datadog
[Approvers](https://github.com/open-telemetry/community/blob/main/community-membership.md#approver)
([@open-telemetry/dotnet-instrumentation-approvers](https://github.com/orgs/open-telemetry/teams/dotnet-instrumentation-approvers)):
- [Rasmus Kuusmann](https://github.com/RassK), Splunk
[Emeritus
Maintainer/Approver/Triager](https://github.com/open-telemetry/community/blob/main/community-membership.md#emeritus-maintainerapprovertriager):
- [Colin Higgins](https://github.com/colin-higgins)
- [Greg Paperin](https://github.com/macrogreg)
- [Kevin Gosse](https://github.com/kevingosse)
- [Lucas Pimentel-Ordyna](https://github.com/lucaspimentel)
- [Mike Goldsmith](https://github.com/MikeGoldsmith)
- [Tony Redondo](https://github.com/tonyredondo)
Learn more about roles in the [community repository](https://github.com/open-telemetry/community/blob/main/community-membership.md).
Reference in New Issue View Git Blame Copy Permalink