Using OpenTelemetry Instrumentation Libraries with Datadog SDKs
Instrumentation is the process of adding code to your application to capture and report observability data.
Automatic instrumentation is a way to instrument applications and libraries without modifying their source code.
Both OpenTelemetry and Datadog provide automatic instrumentation in their SDKs.
Datadog SDKs support adding OpenTelemetry instrumentation libraries to their existing automatic instrumentation.
This provides observability for libraries not covered by Datadog SDKs without changing SDKs.
Prerequisites
Before adding OpenTelemetry instrumentation libraries, set the DD_TRACE_OTEL_ENABLED environment variable to true.
When replacing a Datadog instrumentation with its OpenTelemetry equivalent, disable the
Datadog instrumentation to avoid duplicate spans in the trace.
DD_TRACE_OTEL_ENABLED is not required for the Datadog Go SDK.
Language support
| Language | Minimum version |
|---|
| Java | 1.35.0 |
| Python | 2.10.0 |
| Ruby | 2.1.0 |
| Go | 1.65.0 |
| Node.js | 4.3.0 |
| PHP | 0.94.0 |
| .NET | 2.53.0 |
Compatibility requirements
The Datadog Java SDK supports library instrumentations using OpenTelemetry’s instrumentation API and javaagent extension API.
Each instrumentation must be packaged as an OpenTelemetry extension in its own JAR.
OpenTelemetry provides an example extension project that registers a custom instrumentation for Servlet 3 classes.
The Datadog SDK for Java also accepts select individual instrumentation JARs produced by OpenTelemetry’s opentelemetry-java-instrumentation
build, for example the CFX instrumentation JAR.
OpenTelemetry incubator APIs are not supported.
Setup
To use an OpenTelemetry instrumentation with the Datadog Java SDK:
- Set the
dd.trace.otel.enabled system property or the DD_TRACE_OTEL_ENABLED environment variable to true. - Copy the OpenTelemetry extension JAR containing the instrumentation to the same container as the application.
- Set the
otel.javaagent.extensions system property or the OTEL_JAVAAGENT_EXTENSIONS environment variable to the extension JAR path.
Configuration
The following configuration options have system property and environment variable equivalents.
If the same key type is set for both, the system property takes priority.
Set system properties as JVM flags.
dd.trace.otel.enabled- Environment Variable:
DD_TRACE_OTEL_ENABLED
Default: false
Must be set to true to enable use of OpenTelemetry instrumentations. otel.javaagent.extensions- Environment Variable:
OTEL_JAVAAGENT_EXTENSIONS
Default: false
A comma-separated list of paths to extension JAR files or folders containing extension JAR files.
OpenTelemetry’s Agent Configuration page describes additional properties that are also recognized by the Datadog SDK.
Verified OpenTelemetry extensions
Further reading
Additional helpful documentation, links, and articles:
