Baggage in Distributed Tracing

WHY IT EXISTS Sometimes a downstream service needs a piece of context that was only known at the very edge of the system, like which customer tier made the request or which A/B variant is active. Passing it explicitly through every function signature and API call is invasive. Baggage exists to carry that context implicitly along the trace.

THE MENTAL MODEL Think of baggage as a small envelope of key-value pairs that rides along with the request everywhere it goes. You drop a value in at one service, and any later service in the call chain can open the envelope and read it, without the intervening services having to know or forward it manually. It is distinct from span attributes, which are local to one span and do not travel.

HOW IT WORKS When a service makes a downstream call, the tracing library serializes baggage into propagation headers, in OpenTelemetry a dedicated baggage header, alongside the trace context. The receiving service deserializes it back into its context, and the cycle repeats on each hop. Because it is part of context propagation, it flows automatically wherever trace context flows, including across process and network boundaries.

WHEN IT MATTERS Baggage matters when several services need shared request-scoped context for routing, sampling decisions, or enriching their own telemetry, for example tagging every span downstream with the originating tenant. It matters in the other direction too: because every key-value pair is copied into headers on every hop, you must keep baggage small and never put secrets or PII in it, since it spreads to all participating services including third parties.

ONE CONCRETE EXAMPLE An API gateway sets baggage tenant id equal to a customer identifier. Ten services later, a database access layer reads that baggage value to choose the right shard and to tag its own spans, even though none of the intermediate services touched or forwarded the value explicitly. If someone naively added a full auth token to baggage, it would now be exposed on every downstream hop, illustrating the leak risk.