﻿---
title: Trace context headers not propagating between OpenTelemetry and Elastic APM
description: Troubleshoot trace propagation when migrating from Elastic APM agents to OpenTelemetry.
url: https://www.elastic.co/elastic/docs-builder/docs/2975/troubleshoot/ingest/opentelemetry/edot-sdks/trace-context-propagation
products:
  - Elastic Cloud Serverless
  - Elastic Distribution of OpenTelemetry SDK
  - Elastic Observability
applies_to:
  - Serverless Observability projects: Generally available
  - Elastic Stack: Generally available
---

# 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.
<important>
  Mixing OpenTelemetry and non-OpenTelemetry (Elastic APM agent) configurations is not officially supported. This guide is only intended for troubleshooting trace context propagation during gradual migrations or partial instrumentation.
</important>

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.

## Migration strategy overview

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](#about-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](https://www.elastic.co/elastic/docs-builder/docs/2975/solutions/observability/apm/opentelemetry).

### About the OpenTelemetry Bridge

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.

## Symptoms

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


## Causes

In mixed OpenTelemetry and Elastic APM environments, propagation issues typically stem from header handling or configuration mismatches.
OpenTelemetry uses the [W3C Trace Context](https://www.w3.org/TR/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–specific trace continuation behavior

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.
<note>
  This trace continuation behavior is specific to Elastic APM agents. There is currently no equivalent feature in OpenTelemetry or EDOT.
</note>


### Workaround for OpenTelemetry / EDOT

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.

## Resolution

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.
<stepper>
  <step title="Ensure all Elastic agents support W3C Trace Context">
    Verify that any Elastic APM agents in the call path meet the minimum W3C-compatible versions:

    | Agent    | Minimum version |
    |----------|-----------------|
    | Java     | 1.14.0          |
    | .NET     | 1.3.0           |
    | Node.js  | 3.4.0           |
    | Python   | 5.4.0           |
    | Go       | 1.6.0           |
    | Ruby     | 3.5.0           |
    | PHP      | 1.0.0           |
    | RUM (JS) | 5.0.0           |
    Upgrading agents is often the most effective first step to reduce compatibility issues.
  </step>

  <step title="Keep dual-propagation turned on in mixed environments">
    In environments where OpenTelemetry SDKs (W3C-only) coexist with Elastic agents:
    - Keep `elastic-apm-traceparent` turned on for Elastic agents.
    - Allow agents to emit both W3C and legacy headers.
    This maximizes compatibility and has negligible overhead.If you use an HTTP proxy, gateway, or load balancer, ensure that the following are forwarded unchanged:
    - `traceparent`
    - `tracestate`
    - `elastic-apm-traceparent`
    Some proxies require explicit configuration to allow custom headers.
  </step>

  <step title="Review trace continuation settings on Elastic agents">
    If traces unexpectedly restart:
    - Confirm the trace continuation strategy (`continue`, `restart`, `restart_external`).
    - Ensure the chosen strategy matches your contrib service topology.
    Misconfigured continuation settings can cause valid traces to be intentionally restarted.
  </step>
</stepper>


## Best practices

- 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.


## Resources

- [W3C Trace Context specification](https://www.w3.org/TR/trace-context/)
- [Contrib OpenTelemetry context propagation documentation](https://opentelemetry.io/docs/concepts/context-propagation/)