OpenTelemetry traces with OneAgent

Opt-In

Dynatrace OneAgent code modules for Java, .NET, PHP, Node.js, and Go automatically collect OpenTelemetry span data and integrate it into end-to-end distributed traces.

The OpenTelemetry with OneAgent code module enables you to:

Gain insights into third-party libraries or frameworks that aren’t natively covered by OneAgent but which come with OpenTelemetry pre-instrumentation.
Enrich monitoring data with project-specific additions (for example, custom instrumentation that adds business data or the capture of developer-specific diagnostics points).
Stitch together independent, unrelated transactions to extend end-to-end traces (for instance, by adding vendor-neutral custom instrumentation to gain business-process-specific or domain-specific end-to-end transactional insights).

The quality of the OpenTelemetry spans captured by OneAgent depends on the quality of instrumentation provided by the third-party library.

Prerequisites

Monitoring framework	Versions
OpenTelemetry	1.0 - 1.3, 1.4 - 1.26
OpenTracing	0.33, 0.32, 0.31

The OpenTelemetry Go version that OneAgent supports changes frequently because OpenTelemetry for Go is not yet stable. When an OpenTelemetry Go release candidate is available, the corresponding OneAgent support will stabilize.

Monitoring framework	Versions
OpenTelemetry	1.0 - 1.7, 1.8 - 1.11.0, 1.11.1 - 1.15

Monitoring framework	Versions
OpenTelemetry	1

Monitoring framework	Versions
OpenTelemetry	0.0.9¹, 0.0.10¹, 0.0.11¹, 0.0.12¹, 0.0.13¹, 0.0.14¹, 0.0.15¹
¹ OpenTelemetry for PHP is in the Alpha release stage and isn't stable enough for long-term OneAgent support. Consequently, we can only support the latest version of OpenTelemetry for PHP available at the time of OneAgent release. This will change when OpenTelemetry for PHP reaches the GA release stage.

Monitoring framework	Versions
OpenTelemetry	1.0.1+

Monitoring framework	Versions
OpenTelemetry	1.0.1+

Enable OpenTelemetry integration in OneAgent code module

OneAgent automatically taps into traces exposed via OpenTelemetry custom- or pre-instrumentation and sends the telemetry data to the Dynatrace platform.

OpenTelemetry Java

To enable OpenTelemetry Java

In the Dynatrace menu, go to Settings > Prefences > OneAgent features.
Find and enable OpenTelemetry (Java).

Existing tracers are replaced and will no longer work after you enable OpenTelemetry Java.

OpenTelemetry Go

To enable OpenTelemetry Go

In the Dynatrace menu, go to Settings > Prefences > OneAgent features.
Find and enable OpenTelemetry (Go).

For OneAgent version 1.217 and earlier, the OpenTelemetry Go Sensor propagates Dynatrace context across processes only if Send W3C Trace Context HTTP headers is enabled.

In the Dynatrace menu, go to Settings > Server-side service monitoring > Deep monitoring.
Expand Distributed tracing.
Turn on Send W3C trace context HTTP headers.

Existing tracers are not affected by OneAgent OpenTelemetry for Go support.

OpenTelemetry Node.js

To enable OpenTelemetry Node.js

In the Dynatrace menu, go to Settings > Prefences > OneAgent features.
Find and enable OpenTelemetry (Node.js).

OpenTelemetry PHP

To enable OpenTelemetry PHP

In the Dynatrace menu, go to Settings > Prefences > OneAgent features.
Find and enable OpenTelemetry (PHP).

Existing tracers are replaced and will no longer work after you enable OpenTelemetry for PHP.

OpenTelemetry .NET

To enable OpenTelemetry .NET

In the Dynatrace menu, go to Settings > Prefences > OneAgent features.
Find and enable OpenTelemetry (.NET).

Existing tracers are not affected by OneAgent OpenTelemetry for .NET support.

See Span settings for all configuration options.

Export to third-party backends while using OneAgent

In earlier versions, OneAgent took control over OpenTelemetry data and disabled other configured exporters. This is no longer the case as of OneAgent version 1.261; exports to third parties are available across all languages supported by OneAgent (Go, Java, JavaScript, .NET, and PHP).

While OpenTelemetry traces are always exported to other backends as is, a small data adjustment takes place when your OneAgent-instrumented application starts a fresh OpenTelemetry trace. This applies only to new traces and not when a trace is continued via context propagation.

In that case, OneAgent may have already created a new trace object when OpenTelemetry was initialized. If these two traces (with separate IDs) are not reconciled, telemetry data might be duplicated or fragmented. To mitigate this and still keep Dynatrace PurePath traces consistent, OneAgent uses the following approach:

The OpenTelemetry trace ID takes precedence in exports to third parties
On the Dynatrace backend, the PurePath trace ID is assigned instead

To enable correlation between these two IDs, Dynatrace creates additional span links for each span, linking to the OpenTelemetry trace.

The ID rewrite applies only to newly started traces (not context propagation) and to the OpenTelemetry SDKs for Go, Java, JavaScript, and PHP, and not to .NET.

Limitations

Java

In versions earlier than 1.259, OneAgent replaces installed global OpenTelemetry SDK components TracerProvider, Propagator, and ContextManager. Therefore, with OpenTelemetry Java enabled, traces are no longer seen by this SDK or exported to backends like Jaeger.
When both OneAgent and OpenTelemetry sensors are present for the same technology, you may experience the following limitations:
- Duplicate nodes in distributed traces
- Additional overhead

Go

OneAgent can only instrument Tracer implementation of the default OpenTelemetry SDK.
When both OneAgent and OpenTelemetry sensors are present for the same technology, you may experience the following limitations:
- Duplicate nodes in distributed traces
- Additional overhead

Node.js

In versions earlier than 1.261, OneAgent replaces installed global OpenTelemetry SDK components TracerProvider, Propagator, and ContextManager. Therefore, with OpenTelemetry Node.js enabled, traces are no longer seen by this SDK or exported to backends like Jaeger.
When OneAgent and OpenTelemetry instrument the same module (such as HTTP or GRPC), you may experience the following limitations:
- Duplicate nodes in distributed traces
- Disconnected distributed traces
- Additional overhead

All languages

OneAgent captures OpenTelemetry resource attributes only if they are provided via the OTEL\_SERVICE\_NAME and OTEL\_RESOURCE\_ATTRIBUTES environment variables. When using the OpenTelemetry trace ingest API, this limitation doesn't apply.
You can't create request attributes (commonly used for trace searching and filtering) based on OpenTelemetry resource attributes.