Baggage and Cross-Cutting Concerns
You'll learn how to propagate custom metadata across every span in a distributed trace, enabling context-aware decisions throughout your system.
The Core Idea
While trace context (lesson 1230) passes trace IDs and span IDs between services, baggage is a separate mechanism for propagating arbitrary key-value pairs alongside the trace. Think of it as a shared backpack that travels with every request: any service can read what's inside or add new items, and every downstream service automatically receives the contents.
Common use cases include:
- Tenant ID for multi-tenant systems (to route requests, apply quotas)
- Feature flags that affect behavior across multiple services
- User context like subscription tier or geographic region
- A/B test variants that need consistent treatment end-to-end
How It Works
Baggage travels in HTTP headers (or equivalent in other protocols) separately from trace context. A service might add tenant-id=acme-corp to baggage, and every subsequent service in the trace receives this information automatically through instrumentation.
Service A → adds baggage: tenant-id=acme-corp
↓ (propagated in headers)
Service B → reads tenant-id, adds feature-flag=new-ui
↓ (both values propagated)
Service C → reads both values, makes routing decision
Important Considerations
Baggage increases header size on every request, so keep it small. Avoid sensitive data (it's visible across service boundaries). Not all tracing systems support baggage equally—OpenTelemetry standardizes it, but implementation varies.
Key Takeaway: Baggage lets you propagate custom key-value context across all spans in a trace, enabling cross-cutting concerns like tenant routing and feature flags without explicit parameter passing.