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.

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 and Elastic APM agents
  • New and legacy Elastic APM agents in the same call chain
  • Different versions of APM agents in the same call chain

In mixed OpenTelemetry and Elastic APM environments, propagation issues typically stem from header 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:

• Older (pre‑W3C) Elastic agents 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.

Before going fully OTel-native, you can use the OpenTelemetry Bridge offered by Elastic agents as a transitional solution:

The bridge lets you use the OpenTelemetry API for manual instrumentation while still using an Elastic APM agent for auto‑instrumentation and exporting.

With the bridge:

• The Elastic agent implements the OpenTelemetry API.
• Spans created through the OTel API become native Elastic spans.
• Parent–child relationships are preserved across manual and auto‑instrumentation.

The bridge is available in major Elastic agents (Java, .NET, Node.js, Python). Prefer moving to Elastic Distribution of OpenTelemetry (OTel-native) when you can.

Do not run a full OpenTelemetry SDK in the same process as an Elastic APM agent.

This setup causes:

• Duplicate instrumentation and added overhead.
• Trace fragmentation (conflicting trace IDs).
• Startup conflicts (instrumentation, exporters, environment variables).

Each SDK might try to manage propagation independently, breaking distributed tracing. For an OpenTelemetry-native setup, use Elastic Distribution of OpenTelemetry instead of mixing SDKs.

The preferred resolution is to complete your migration to OpenTelemetry and use Elastic Distribution of OpenTelemetry (OTel-native). However, if you are still in a gradual migration and need traces to connect across mixed services, the following steps might help.

• Use Elastic Distribution of OpenTelemetry for full OTel support and to avoid mixed-configuration issues.
• If you are in a gradual migration: standardize on W3C Trace Context across services and upgrade older agents early.
• Use one tracing implementation per process (Elastic agent or OpenTelemetry SDK). Avoid mixing SDKs.
• If you must mix APIs during a transition, use the OpenTelemetry Bridge temporarily and plan to move to Elastic Distribution of OpenTelemetry.
• Validate cross-service tracing in staging before partial rollouts.

• W3C Trace Context specification
• Contrib OpenTelemetry context propagation documentation
• Elastic APM OpenTelemetry Bridge (Java)
• Elastic APM OpenTelemetry Bridge (.NET)
• Elastic APM OpenTelemetry Bridge (Node.js)
• Elastic APM OpenTelemetry Bridge (Python)