W3C Baggage Propagation
Baggage propagates arbitrary key-value context alongside the trace context — tenant, flags, experiment cohorts — readable at every hop without carrying it in message payloads or headers by hand.
Definition
W3C Baggage is a standardized propagation header for application context: a set of key-value pairs transmitted with each request, separate from but parallel to traceparent. Any hop can read or extend it. Typical uses: tenant and account propagation, feature flag evaluation context, experiment cohort ids, request-scoped hints for downstream services.
Context and scope
Supported by OpenTelemetry context APIs across languages. Applied for consistent context-dependent behavior — routing, entitlement, experimentation — through deep call chains.
Common misconceptions
- Baggage is another word for trace attributes — trace attributes land in telemetry storage; baggage is operational context propagated in-band to running services
- Baggage should carry everything request-scoped — it travels on every request; secrets, tokens, and bulky payloads inflate every hop and leak surface
- Values are free-form — the spec defines syntax and size guidance; limits enforced at entry prevent header bloat and injection
Anti-patterns
- Carrying auth tokens in baggage and broadcasting credentials to every service and proxy in the path
- Appending keys at every hop without bounds and growing headers until middleboxes reject requests
- Trusting baggage values for security decisions without validation at the trust boundary
Related concepts
Related examples
Authoritative source
What it is
Trace context answers “which request is this” for diagnostics. Baggage answers it for behavior: the request carries its operating context — tenant, cohort, locale — so deep services act consistently without each caller threading parameters by hand.
How it works
The baggage header lists key-value pairs with defined escaping. Framework context APIs expose get, set, and remove during a request; outgoing calls serialize current baggage. Propagation must be opt-in per hop: not every external call should forward internal context.
When to use it
Multi-tenant routing, experiment cohort consistency across service boundaries, locale and compliance flags, and request-scoped hints like traffic-source for differentiated handling. Keep the key set small and explicitly versioned, because baggage is visible at every hop.
Pitfalls
Inbound baggage is attacker-controlled input in public edges: validate, bound, and whitelist before trusting. Uncontrolled growth over many hops inflates every request; entry-point enforcement of size and key limits is the guardrail. Baggage crossing to third parties via unvetted egress leaks internal context — scope propagation lists explicitly.