Observability & Tracing · OpenTelemetry course

Lesson 02

Context propagation: traceparent & baggage

Lesson 1 left one thing unexplained: how does payment-service know it belongs to a trace that started in gateway? Nothing is shared between those two JVMs except an HTTP request. So the answer has to be in the request. This lesson opens that request and reads the two headers that make distributed tracing possible.

The problem: a request leaves the process

One word: headers. There is no magic, no shared database, no coordination service. The tracing context is serialised into HTTP headers on the way out and parsed back out of them on the way in. OpenTelemetry calls that whole mechanism context propagation, and the component that does it is a propagator.^{[context propagation]}

The propagator is the only reason a trace survives a process boundary. Default format across the ecosystem: W3C Trace Context. [src]

In Spring Boot 3.x you never call inject/extract yourself — the instrumentation on RestTemplate, WebClient and Spring MVC does it for you. That is precisely why a trace "just works" across services once the dependencies are right.

traceparent, dissected

Here is a real one. Four fields, separated by hyphens, all lowercase hex:^[w3c]

Two details worth burning in:

• parent-id is the caller's span ID, not the callee's. The receiving service mints a new span ID and records this value as its parent. That is exactly the parent=9c41de arrow you saw in the Lesson 1 span tree — now you know which byte on the wire carried it.
• trace-flags carries the sampling decision. 01 means the caller recorded this trace, so downstream services should too. The decision is made once, at the start, and everyone downstream honours it — which is why a head sampling probability set on one service quietly governs the whole request path.

There is a sibling header, tracestate, which carries vendor-specific key/value pairs alongside traceparent (max 32 entries). You will rarely touch it; it exists so multiple tracing systems can coexist on one request without trampling each other.^[w3c]

Baggage — the key/values that ride along

Realistically two, and both are bad: thread tenantId through every method signature and every HTTP client in four services, or simply don't have it. Baggage is the third option. It is a key/value store that propagates alongside the trace context — set it once at the edge, read it anywhere downstream.^[baggage]

“Is baggage a signal?” — the honest answer

You will see baggage called “not a signal” all over the internet, and Lesson 1 leaned on that shorthand. It is worth being precise, because the shorthand is wrong on the letter and right on the spirit.

On the letter: OpenTelemetry's own Signals page says “OpenTelemetry currently supports:” and then lists four items — Traces, Metrics, Logs, Baggage. It lives at /docs/concepts/signals/baggage/. By the project's own taxonomy, baggage is in the list.^[signals]

On the spirit: the baggage page itself opens by defining it as “Contextual information that is passed between signals” — a description no one would write about traces. And every property that makes traces, metrics and logs alike is missing from baggage:

So the accurate sentence is: baggage is listed as a signal, but it is the only one that carries no telemetry. Nothing you put in baggage ever reaches Jaeger or Dynatrace on its own — which is exactly the trap in the next section.

The trap: baggage is not span attributes

This is the one that costs people an afternoon. You set tenantId in baggage at the gateway, open Jaeger expecting to filter traces by it, and it is nowhere to be found. The value propagated perfectly. It was simply never recorded onto a span.

OpenTelemetry states it plainly: baggage "is a separate key-value store and is unassociated with attributes on spans, metrics, or logs without explicitly adding them."^[baggage]

Attributes attach to one span and travel to the backend. Baggage attaches to the request and travels to the next service. Opposite directions — that is the whole confusion in one line.

To make baggage visible in your backend you must explicitly read it and set it as a span attribute. Some languages ship a Baggage Span Processor to automate that; in Spring Boot, the tag-fields property below does it for you.

On the wire

W3C standardises a lowercase baggage header, separate from the trace context spec:^{[w3c baggage]}

In your Spring Boot 3.x stack

Everything lives under management.tracing.baggage.*, auto-wired by Actuator, enabled by default:^{[boot props]}

Three notes specific to your stack, because you are on the OTel bridge and not Brave:

• local-fields does not work for you. The Boot property docs say it outright: "Local fields are not supported with OpenTelemetry." It is a Brave-only feature.
• correlation.fields is the log-correlation payoff Lesson 1 pointed at. It pushes baggage into the MDC, so tenantId appears in every log line of the request, in every service — not just in the trace.
• No span in scope, no baggage. Micrometer is blunt: "When there's no span in scope, there will never be any baggage — even if you make it current." Outside a request, or when the trace was not sampled, your get() can come back null. Code defensively.^[micrometer]

Why "no secrets in baggage" is a hard rule

It is not tidiness. Instrumentation propagates baggage automatically on every outbound call the rest of the request tree makes — including calls to third parties. OpenTelemetry warns that "sensitive baggage items can be shared with unintended resources, like third-party APIs," and that "there are no built-in integrity checks to ensure that baggage items are yours" — so anything upstream can inject keys you will then read as trusted.^[baggage]

W3C's rule is the one to memorise: ensure "no proprietary or confidential information is stored in baggage, or … that baggage isn't present in requests that cross trust-boundaries."^{[w3c baggage]}

Prove it — recall drill

Primary source — read this next

Ten minutes on OpenTelemetry → Concepts → Context propagation, then skim the header grammar in the W3C Trace Context spec. The spec is short and unusually readable — you only need §3.2.