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 during gradual migrations or partial rollouts.

This page focuses on propagation issues (traceparent / tracestate) and clarifies which mixing patterns are supported and which are discouraged.

You might observe one or more of the following:

• 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 between spans are missing when traffic crosses between:

  • OpenTelemetry-instrumented services and Elastic APM agents.
  • New and very old Elastic APM agents in the same call chain.

OpenTelemetry propagates trace context using the W3C Trace Context standard headers:

• traceparent
• tracestate

All modern Elastic APM agents use W3C Trace Context as the primary propagation standard by default.

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

• Inbound: Agents first read the W3C headers. If those are missing, they fall back to the legacy elastic-apm-traceparent header.
• Outbound: Agents inject both W3C headers and the legacy header to support mixed fleets during migrations.

Propagation problems typically occur when:

• Very old Elastic APM agent versions (pre‑W3C) are still present.
• Legacy propagation was turned off too early.
• Trace continuation is misconfigured to restart traces.
• Two independent tracing SDKs run in the same process and compete for instrumentation and context.

When combining OpenTelemetry with Elastic APM agents, some patterns work well while others can cause propagation issues.

Elastic APM agents provide an OpenTelemetry Bridge, which allows you to use the OpenTelemetry API for manual instrumentation while keeping the Elastic APM agent as the active tracer and exporter.

With the bridge:

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

This pattern is available in most major agents (Java, .NET, Node.js, Python).

Use this option when you:

• Want to write vendor‑neutral manual instrumentation using the OTel API.
• Still rely on Elastic APM agent auto‑instrumentation and features.

Avoid running a complete OpenTelemetry SDK implementation together with an Elastic APM agent in the same process. This pattern is unnecessary and causes problems.

Running both together leads to:

• Double instrumentation and increased overhead.
• Trace fragmentation (two different trace IDs for the same request).
• Conflicts during startup (bytecode instrumentation, environment variables, exporters).

In this setup, each SDK might attempt to manage context and propagation independently, breaking distributed tracing.

If you want a fully OpenTelemetry‑native setup, use Elastic Distribution of OpenTelemetry (EDOT) instead of the Elastic APM agent.

• Standardize on W3C Trace Context across all services.
• Upgrade old agents early in migration projects.
• Use only one tracing implementation per process (Elastic APM agent or OpenTelemetry SDK, not both).
• Use the OpenTelemetry Bridge when combining OTel API with Elastic agents.
• Prefer EDOT for fully OpenTelemetry‑native deployments.
• Validate cross-service tracing in staging before rolling out partially.

• W3C Trace Context specification — Official W3C spec defining traceparent and tracestate headers for distributed trace context propagation.
• Contrib OpenTelemetry propagation documentation — OpenTelemetry guide on context propagation and how W3C Trace Context is used.
• Elastic APM OpenTelemetry Bridge documentation (Java) — Example Elastic APM OpenTelemetry Bridge docs; similar per‑agent pages exist (for example, .NET).