Trace context headers not propagating between OpenTelemetry and Elastic APM

Use this guide to troubleshoot missing or broken distributed traces when combining OpenTelemetry instrumentation with Elastic APM agents.

The recommended path is to adopt an OpenTelemetry-native strategy using Elastic Distribution of OpenTelemetry. However, if you are in a transition period, this page helps you diagnose and mitigate trace context propagation issues (traceparent / tracestate) until you can complete the migration.

Completing a move to OpenTelemetry removes the mixed propagation issues described below. A typical path includes the following steps:

1. Add an OTLP endpoint and make it reachable from your applications (for example, in Elastic Cloud or your cluster).
2. Update your application to use the OpenTelemetry API instead of the Elastic APM API. The OpenTelemetry Bridge (when turned on for an Elastic agent) lets you do this while keeping the agent in place.
3. Replace Elastic APM agents with OpenTelemetry-based instrumentation (Elastic Distribution of OpenTelemetry or contrib OpenTelemetry SDKs) when you are ready to go fully OTel-native.

For setup and options, refer to OpenTelemetry with Elastic APM.

Elastic APM agents provide an OpenTelemetry API bridge that allows applications to emit traces and metrics using the OpenTelemetry API while still relying on an Elastic agent. However, the OpenTelemetry Bridge doesn't handle context propagation. It only provides API compatibility for manual instrumentation.

Use the bridge only as a short-term compatibility layer during migrations. For full OpenTelemetry support, including native propagation behavior, migrate to Elastic Distribution of OpenTelemetry.

If you are still in a mixed environment, you might observe one or more of the following issues:

• Distributed traces are broken across service boundaries.
• Downstream spans start new traces instead of continuing the existing one.
• Traces appear split or uncorrelated in the UI.
• Parent–child relationships are missing when traffic crosses between:
  • OpenTelemetry-instrumented services (including EDOT-based and contrib OpenTelemetry SDKs) and Elastic APM agents
  • Elastic APM agents that support W3C Trace Context and older, pre-W3C agents in the same call chain

In mixed OpenTelemetry and Elastic APM environments, propagation issues typically stem from header handling or configuration mismatches.

OpenTelemetry uses the W3C Trace Context standard headers:

• traceparent
• tracestate

All modern Elastic APM agents support W3C Trace Context by default.

For backward compatibility, Elastic agents also support a legacy proprietary header (elastic-apm-traceparent) and operate in dual‑propagation mode:

• Inbound: Agents first read W3C headers; if missing, they fall back to the legacy header.
• Outbound: Agents inject both W3C headers and the legacy header to support mixed environments.

Propagation issues often occur when:

• Elastic agents older than version 1.14.0 (pre-W3C) are still in use.
• Legacy propagation is turned off prematurely.
• Trace continuation is misconfigured to restart traces.
• Two tracing SDKs run in the same process and compete for instrumentation or context.

Elastic APM agents expose a trace continuation strategy that controls how incoming trace headers are handled:

• continue (default): Continue incoming traces.
• restart: Always start a new trace.
• restart_external: Restart traces only if the contrib service is not using an Elastic APM agent.

The restart_external strategy is useful when a contrib service propagates W3C headers but sends its traces to a different backend, which otherwise results in missing or misleading parent transactions.

If you need to force a downstream OpenTelemetry-instrumented service to start a new trace independently:

• Strip or reset incoming trace context headers (traceparent, tracestate) at the ingress layer (for example, in an HTTP proxy or gateway).

This prevents the downstream service from attempting to continue an incompatible contrib trace.

The preferred resolution is to complete your migration to an OpenTelemetry-native setup using Elastic Distribution of OpenTelemetry. If you are still operating in a mixed environment, the following steps can help maintain trace continuity.

• Upgrade Elastic APM agents to the latest available versions.
• Standardize on W3C Trace Context across all services.
• Keep elastic-apm-traceparent turned on for as long as mixed agents exist.
• Ensure gateways and proxies forward trace headers unchanged.
• Use one tracing implementation per process.
• Plan and validate migrations in staging environments before partial rollouts.

• W3C Trace Context specification
• Contrib OpenTelemetry context propagation documentation