OpenTelemetry context propagation: follow a trace across services

Understand traceparent, tracestate, and Baggage. Check how HTTP, gRPC, and message queues carry context, and diagnose where a trace splits.

Best practices
An illustration of connected systems and telemetry flows

The checkout span is visible, but the inventory request appears under a different trace ID. Both services may be exporting spans correctly. The first question is whether inventory extracted the context checkout sent.

OpenTelemetry context propagation carries trace identity across a service boundary. The receiving service extracts that identity before starting its span. The sending service injects the current span context before making the next call. That pairing is what makes the parent relationship visible later.

What actually crosses the wire

A SpanContext holds a trace ID, the current span ID, trace flags, and trace state. When a receiving service starts a child from an extracted remote context, the child keeps the trace ID, gets a new span ID, and records the remote span as its parent. Start and end times belong to each span record. The SDK marks extracted span contexts as remote. That marker stays in the SDK context. OpenTelemetry SpanContext API

Baggage carries application-defined values through a separate propagator. It is optional and does not become a span attribute automatically. For example, a service can explicitly copy an allowed release cohort to a span attribute when it needs to query by cohort.

Read a traceparent header

The W3C Trace Context Level 1 recommendation defines the 00 format as version-trace-id-parent-id-trace-flags. Consider this incoming HTTP header.

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
Field What it means at the receiver
00 Format version. ff is invalid. For a later version, Level 1 calls for a best-effort read of the recognized prefix.
4bf92f3577b34da6a3ce929d0e0e4736 Trace ID. It has 32 lowercase hexadecimal characters and cannot be all zeros.
00f067aa0ba902b7 The span ID the sender propagated. It has 16 lowercase hexadecimal characters and cannot be all zeros.
01 Flags byte. The low bit, 0x01, is the sampled flag. A set flag gives the receiver a sampling signal. Export, retention, and searchability depend on the rest of the pipeline.

The optional tracestate header carries an ordered list of vendor entries alongside a valid traceparent. The carrier and the propagator are separate concerns. Check that both sides use compatible propagators. OpenTelemetry implementations that honor OTEL_PROPAGATORS use tracecontext,baggage as the specified default. With manual setup, configure the propagator explicitly. OpenTelemetry propagator API · SDK environment variables

Match propagation to the transport

HTTP. Client instrumentation injects the context into the outgoing headers. Server middleware extracts it before starting the server span. After starting a span, carry the returned context into any subsequent call. A request built from an older context can carry the wrong parent even if its header looks valid.

gRPC. The client and server instrumentation use RPC metadata, carried in HTTP/2 headers. Inspect metadata on the receiving side of an interceptor or proxy. gRPC metadata guide

Message queues. The producer puts a message creation context into the message carrier, such as a Kafka record header. When processing a batch, the consumer extracts the context of each message and can link its processing span to all of them. A span has one parent, so choosing one producer as the parent of a batch loses the other relationships. OpenTelemetry messaging conventions use links by default. For a single message, an instrumentation may choose its creation context as the parent of the processing span. If processing already runs under a span such as an HTTP handler, keep the active parent and link to the message creation context. OpenTelemetry messaging spans

Custom protocols. Adapt your message fields into a carrier the propagator can read and write. Use its inject and extract operations, then start the receiving span with the returned context.

Find the boundary that broke

Pick one test request. At each synchronous hop, compare the outgoing traceparent with the context extracted at the next service. Check that the local server span keeps the trace ID and names the sender's span as its parent. On a queue, inspect the links as well as the parent. A linked consumer may legitimately have a different trace ID.

If the IDs change unexpectedly, look for a gateway that filters headers, an uninstrumented client, or async work started with an empty context. A public ingress can also start a fresh trace deliberately as part of its trust policy. If the IDs agree and a span is still missing, follow the recording, sampling, and export path. Check the backend's time range and filters before changing propagation settings.

Verify the trace and the logs in Guance

After sending your spans through the DataKit OTLP receiver, look up the test trace and check its synchronous parent IDs. For asynchronous processing, inspect the processing span's links in the instrumentation output. Separate traces are a valid result when the consumer uses a link.

To follow a log from the same request, emit the active trace ID in the application's logging context and configure APM log correlation. If the trace ID is already present in the log and a span is still missing from search, investigate sampling and export on that hop.

Keep baggage inside the right boundary

Check which propagators run on each outbound path. Baggage can reach another organization if an instrumented client calls a third party. Allow only the keys you intend to send, keep credentials and personal data out, and treat incoming values as untrusted. Use service identity and application authorization for access decisions. W3C Baggage

Further reading · What is OpenTelemetry? · OpenTelemetry sampling

Get a tailored plan

Contact us

Join the community

Scan with WeChat
to join the community

Try Guance

Start online and pay only for what you use.

Get started

Choose a Guance plan

Code hosting