3.0 KiB
Handle adding automatic instrumentation to application with existing OpenTelemetry SDK and instrumentation references
This document explains how OpenTelemetry automatic instrumentation interacts with
applications that already include references to the OpenTelemetry SDK or instrumentation
libraries. It covers the role and impact of the OTEL_DOTNET_AUTO_SETUP_SDK
environment variable and provides troubleshooting guidance for conflicts between automatic
instrumentation and existing references. The objective is to help users understand and
effectively integrate OpenTelemetry automatic instrumentation into their applications.
Interaction with existing OpenTelemetry SDK and instrumentation references
OpenTelemetry automatic instrumentation enhances .NET applications by automatically injecting and configuring the OpenTelemetry .NET SDK and adding OpenTelemetry instrumentation to key packages and APIs that the application uses. For applications without existing OpenTelemetry references, the process is seamless. However, for applications that already include OpenTelemetry SDK or instrumentation libraries, the interaction requires careful management to avoid conflicts.
The OTEL_DOTNET_AUTO_SETUP_SDK environment variable
The OTEL_DOTNET_AUTO_SETUP_SDK environment variable plays a crucial role in
managing the interaction between OpenTelemetry automatic instrumentation and existing
OpenTelemetry references within an application. When set to true, this
environment variable instructs the automatic instrumentation to automatically set up
the OpenTelemetry SDK, ensuring that it is properly configured to work with the
instrumentation injected by the automatic instrumentation.
This automatic setup is particularly useful in scenarios where the application has its own references to OpenTelemetry libraries, as it helps to harmonize the configuration and ensure that telemetry data is collected and exported as expected.
Impact on applications
The presence of the OTEL_DOTNET_AUTO_SETUP_SDK environment variable and its
configuration can significantly impact how telemetry data is collected and
exported in applications with existing OpenTelemetry references. When enabled,
it ensures that the OpenTelemetry SDK is configured in a way that complements
the automatic instrumentation, thereby enhancing the telemetry data collected
without causing conflicts or duplication.
Troubleshooting
When there are conflicts within an application between the OpenTelemetry automatic instrumentation and existing OpenTelemetry references, try these troubleshooting steps:
- Verify that the
OTEL_DOTNET_AUTO_SETUP_SDKenvironment variable is set totrueto allow the automatic instrumentation to manage the SDK setup. - Review the application's dependencies to identify any conflicting versions of OpenTelemetry libraries and resolve them by aligning with the versions used by the automatic instrumentation.
- Consult the troubleshooting guide for additional advice on resolving specific issues related to OpenTelemetry automatic instrumentation.