The problem baggage was created to solve.

In a monolith, an application is one big program. If the code at the top of a request knows the customer’s name, any function deeper in the same program can simply read it from a shared variable or an object passed along. When the same application is split into many small services running on different machines, that shared memory disappears. Each service only sees the message that arrived at its own door, and anything the earlier service knew is gone unless someone deliberately sends it along.

There are many facts that are interesting to every service in the chain but that do not naturally belong in the business message itself. Think of the identifier of the tenant in a multi-tenant product, the name of an experiment variation a user was assigned, a flag that says the request came from an internal test, or the geographic region where the request first entered the system. Changing every API in every service to carry these extra fields would be slow, error-prone, and would clutter the contracts between teams.

Distributed tracing already has a related trick

OpenTelemetry already solves a similar problem for tracing. To connect the spans produced by different services into one trace, each service passes a small trace context to the next, containing the trace identifier and the parent span identifier. This is called context propagation. Baggage reuses the same machinery, so once you understand how the trace context hops from service to service, you already understand most of how baggage hops too. The difference is in what is carried and why.

A set of name and value pairs that belongs to the request, not to any one service.

Baggage is a collection of key and value pairs, called entries, that is attached to the current context of a request and made available to every service the request touches. A key might be a short name like tenant.id and the value might be acme-corp. Both are strings. Any service in the chain can read the entries, add new ones, change values, or remove entries. Whatever the final set looks like is what gets forwarded to the next service.

Baggage is not the same as attributes

New learners often confuse baggage with span attributes. An attribute is a label recorded on a piece of telemetry, such as a span, to describe it for later analysis. It is written once and shipped to the observability backend. Baggage, by contrast, is a label that travels forward with the request so that downstream code can see it while the request is still alive. Baggage entries do not turn into attributes by themselves. If you want them to appear on spans or logs, you have to copy them there on purpose, a topic we cover in Chapter 11.

Before baggage can cross the network, it first has to live somewhere inside a single process.

Inside one service, OpenTelemetry keeps request-scoped information in an object called the context. You can picture the context as an invisible backpack that follows the current unit of work. The active span lives in this backpack. Baggage lives in this backpack too. Functions deep inside your program can ask for the current context and look inside without anyone having to pass the backpack through every method call explicitly.

How does the backpack stay with the work? That depends on the language. In some languages it is attached to the current thread. In others it follows an asynchronous call chain through a special storage mechanism the runtime provides. In languages without such a mechanism, programmers pass the context explicitly as a parameter. The OpenTelemetry Context API hides most of these differences behind common operations for getting the current context, attaching a new one, and detaching it when the work is done.

Contexts are treated as immutable

A key design choice is that baggage is not edited in place. When you set a new entry, the API gives you back a new context that includes the change, and you then make that new context the current one. The old context is unchanged. This sounds fussy, but it prevents a whole class of bugs where one piece of code accidentally modifies the baggage seen by another piece of code running at the same time.

Two small operations move context across a process boundary.

A context cannot travel over a network as it is, because it is an in-memory object that only makes sense inside one process. To cross a boundary, the useful parts must be turned into text and placed on the outgoing message, and on the other side that text must be turned back into a context. The component that does both jobs is called a propagator.

flowchart LR
  A["Context with baggage in Service A"] --> B["Propagator inject"]
  B --> C["Carrier such as request headers"]
  C --> D["Network"]
  D --> E["Carrier arrives at Service B"]
  E --> F["Propagator extract"]
  F --> G["Context with baggage in Service B"]
        

Why a separate propagator at all

The propagator is a plug-in point. Because the instrumentation libraries only know how to ask a propagator to inject and extract, they work with any wire format. The format used for baggage is the W3C Baggage standard, handled by a propagator often named the W3C baggage propagator. A different propagator could be swapped in without touching the instrumentation, which is how OpenTelemetry stays compatible with older formats from other tracing systems.

Who calls inject and extract

In most real applications, you never call these operations yourself. Instrumentation libraries for web frameworks and HTTP clients do it for you. When your service makes an outgoing call through an instrumented client, the library calls inject. When an incoming request reaches an instrumented server, the library calls extract and makes the resulting context current before your handler runs. That is why baggage often works with no extra code beyond setting and reading the entries.

What actually travels between services when baggage is injected.

For HTTP, baggage travels in a header simply named baggage. The value of the header is a list of entries separated by commas. Each entry is a name, an equals sign, and a value. An entry may also have extra properties, added after a semicolon. This format is defined by a W3C specification so that services built with different languages, libraries, and even different vendors can all read each other’s baggage.

The size limits you should know

The W3C specification describes limits that every implementation is expected to support at minimum: up to 180 name and value pairs, up to 4096 bytes for a single pair, and up to 8192 bytes for the whole header. If a request carries more than that, implementations may drop entries to stay inside the limits. In practice, web servers, proxies, and gateways often impose their own header size limits, so a very large baggage header may be rejected well before it reaches the specification limit.

A story that shows every step of propagation in order.

Let us follow a request through an online store. A customer taps the Buy button. The request lands first at an edge gateway, which forwards it to an orders service, which then calls a payments service. The gateway knows the customer’s subscription tier and the region the request came from, and wants the later services to know too.

sequenceDiagram
  participant U as Customer
  participant G as Gateway
  participant O as Orders service
  participant P as Payments service
  U->>G: Buy request, no baggage
  Note over G: Sets tier and region in baggage
  G->>O: Request plus baggage header
  Note over O: Extracts baggage, adds experiment name
  O->>P: Request plus extended baggage header
  Note over P: Extracts baggage, reads tier, region, experiment
  P-->>O: Response without baggage
  O-->>G: Response without baggage
  G-->>U: Final response
        

Two lessons hiding in this story

First, propagation is transitive. A service that receives baggage and then makes its own outgoing calls will pass the baggage along automatically, along with any changes it made. The middle service did not have to know that payments existed in order to help payments receive the data. Second, propagation is one directional. The response headers going back up the chain do not carry baggage by default. If orders adds something, the gateway does not learn about it through baggage.

Three related ideas that are easy to mix up.

When a request travels across services, several different kinds of data may ride along or be recorded. The trace context is the data that stitches spans together into one trace. Baggage is the user-defined data that rides along for the benefit of the application. Span attributes are the descriptions recorded on telemetry. They are cousins, but they have different jobs and different rules.

Baggage works even when a trace is not sampled

Tracing systems often sample, which means only a fraction of requests have their spans recorded. The sampling decision is part of the trace context. Baggage is separate. Even when a request is not sampled, the baggage still travels, because it exists for the application and not for the trace backend. This is why baggage can power features such as routing or experiments reliably for every request, while spans are only kept for some of them.

Baggage does not need a trace at all

Because baggage rides in its own header and its own part of the context, you can use it in a system that has tracing turned off, as long as the baggage propagator is configured. Many teams use this to build lightweight cross-service signals without adopting full tracing.

Baggage only crosses a boundary if the propagator is turned on at both ends.

A frequent source of confusion is that baggage seems to vanish between services for no reason. In most cases the cause is configuration, not a bug. For baggage to survive a hop, the sending service must have a propagator that knows how to inject baggage, and the receiving service must have a propagator that knows how to extract it. If either side is missing, the chain breaks silently.

Composite propagators

Real systems usually need more than one propagator at once, for example one for trace context and one for baggage. OpenTelemetry supports this through a composite propagator that runs several propagators in order, each handling its own header. The standard configuration lists the propagators to use, and the specification names the default list as the trace context propagator followed by the baggage propagator. Many SDKs read this list from an environment variable named OTEL_PROPAGATORS, so operators can change it without touching code.

Auto-instrumentation versus manual wiring

When you use automatic instrumentation, such as an agent that attaches to your application, the HTTP and messaging libraries are already wrapped, and inject and extract are performed for you using the configured propagators. When you write instrumentation by hand, or when you use a library that has no instrumentation, you must call the propagator yourself at the boundary, supplying the carrier and its getter and setter.

The same inject and extract idea works for every kind of carrier.

HTTP is the most common path, but services also talk through remote procedure calls, message queues, event streams, and scheduled jobs. The propagation idea is the same in each case. The propagator needs a carrier that can hold text labels, and a getter and setter that know how to use it.

Time gaps change the meaning

When a message waits in a queue for an hour, the baggage that travelled with it was true an hour ago. A feature flag, an experiment assignment, or a region may have changed since. Consumers should treat queued baggage as a snapshot of the moment the message was created, not as a live reading.

Fan-out and fan-in

When one request fans out to several downstream services, each branch receives a copy of the same baggage, and the branches may then change their copies independently. When results are merged back, there is no automatic merging of baggage. Each branch’s changes stay inside that branch, which keeps behaviour predictable but means you cannot rely on baggage to collect results.

A tour of the usual suspects when an entry does not arrive.

Baggage can be lost at two kinds of places. Inside a process, it can be lost when the context fails to follow the work. Between processes, it can be lost when a header does not make it through. Knowing the usual suspects turns a mysterious problem into a short checklist.

flowchart TD
  A["Service A sets baggage"] --> B{"Context follows the work inside A?"}
  B -->|No| X1["Lost in thread pool or async hop"]
  B -->|Yes| C{"Propagator injects baggage?"}
  C -->|No| X2["Lost by configuration"]
  C -->|Yes| D{"Intermediary keeps the header?"}
  D -->|No| X3["Stripped or truncated by proxy"]
  D -->|Yes| E{"Receiver extracts baggage?"}
  E -->|No| X4["Lost by missing server instrumentation"]
  E -->|Yes| F["Baggage arrives in Service B"]
        

Baggage reaches your code by default, but it only reaches your dashboards if you send it there.

Because baggage is not automatically copied to spans, logs, or metrics, you need a deliberate step if you want those labels to be searchable in your observability tools. The most common approach is a span processor, a small component that runs whenever a span is started and copies chosen baggage entries onto the span as attributes. Contributed implementations of this idea exist for several languages, and teams can also write their own.

Logs and metrics need care

The same idea can be applied to log records, so that every log line carries the tenant or experiment name. Metrics are different. Each distinct value of an attribute creates a new time series, so copying a high-variety baggage value into a metric can multiply storage cost sharply. Reserve metric labels for baggage with a small, fixed set of values, such as a subscription tier with three levels.

Baggage is small per request, but it is paid for on every hop.

It is tempting to think that a few hundred bytes of baggage is nothing. A single hop does not notice it. But baggage is attached to every outgoing request in a call chain, and the number of requests in a busy system is enormous. The cost is the size of the header multiplied by the number of calls, repeated millions of times per day.

Take a modest example. If a baggage header is 500 bytes and a single user action triggers twelve internal calls, that action sends about six kilobytes of baggage across the network. If the system handles ten thousand such actions every second, the baggage alone adds around sixty megabytes per second of header traffic, before counting any retries. That traffic costs bandwidth, adds a little latency per hop, and uses processing time to encode and decode.

Fan-out multiplies the cost

When one service calls twenty others in parallel, it sends twenty copies of the same baggage. When each of those calls twenty more, the copies multiply again. Wide call trees are common in recommendation, search, and aggregation systems, so baggage size is felt most in exactly the places where traffic is heaviest.

Header limits downstream

Every web server and proxy has a maximum total header size. Trace context, authentication tokens, cookies, and baggage all share that budget. Baggage that grows over time can quietly push total headers past a limit and cause requests to be rejected with confusing errors that look unrelated to telemetry.

Anything in baggage travels widely, so treat it like a postcard, not a sealed letter.

The most important safety fact about baggage is that it travels in plain text headers to every service that the request touches, and to every service those services call. If an instrumented service calls an external payment provider, a mapping service, or any other third party, the baggage header may go with it, unless you deliberately stop it. Everyone along that path can read every entry.

Outbound leakage

When services call outside your organisation, check whether the HTTP client instrumentation also injects baggage into those calls. If so, third parties receive your internal labels. Teams usually prevent this by configuring propagation to apply only to approved destinations, by using an egress gateway that removes the header, or by using a client without baggage injection for external calls.

Inbound forgery

The reverse is just as important. Any outside caller can add a baggage header to a request sent to your public endpoint. If your services believe the incoming baggage blindly, an attacker could claim to be a premium customer or an internal test. The edge of your system, where the public meets the private, should either discard incoming baggage from untrusted sources or validate it before allowing it to continue.

Where teams actually find baggage valuable.

Baggage shines when a small fact known early in a request would otherwise have to be rediscovered, again and again, deep in the system. The following examples describe common patterns used in the industry. Each one relies on the same mechanism you have already learned: set at the edge, propagate downstream, read where it matters.

Habits that keep baggage healthy, and traps to stay out of.

flowchart TD
  A["Do many downstream services need this fact?"] -->|No| B["Use a normal API parameter"]
  A -->|Yes| C{"Is it safe for every internal service to read?"}
  C -->|No| D["Do not use baggage"]
  C -->|Yes| E{"Is it small and low variety?"}
  E -->|No| F["Pass an opaque identifier and look up details"]
  E -->|Yes| G["Use baggage and document the key"]
        

Patterns that work

Anti-patterns to avoid

Because failures are silent, you need to look for them on purpose.

A baggage setup that worked on the day it was launched can drift over months. New services arrive with the wrong propagator settings, a platform team changes a proxy rule, or another team adds three new entries and doubles the header size. Treat baggage like any other shared contract and give it basic monitoring.

A layered approach finds problems earlier and cheaper.

Since baggage failures are silent, a deliberate testing plan pays for itself. The idea is to prove the chain one layer at a time, starting from the smallest piece and growing towards the real environment. Each layer catches a different kind of mistake, and skipping a layer means the mistake will surface later in a more confusing form.

A calm way to troubleshoot

When an entry goes missing, resist the urge to guess. Walk the path in order, exactly as Figure 3 laid it out. Find the last place where the entry is definitely present and the first place where it is definitely absent. The problem lives in between those two points, and that narrow stretch usually contains only one library, one proxy, or one configuration file to inspect.

Short answers to the questions people ask most often.

The standard configuration lists both trace context and baggage propagators by default, so with a default SDK and instrumented libraries it usually works without extra effort. If you override the propagator list, you must make sure baggage is still included on every service.

No. Baggage travels between services with the request, not to the telemetry backend. The collector does not receive it as part of normal telemetry. To see baggage in your backend, you must copy chosen entries onto spans or logs as attributes.

No. Baggage flows with the request direction only. A service can change its own copy, and those changes flow to its own downstream calls, but the callers above it never see them through baggage.

Not strictly. Baggage uses its own header and its own part of the context, so it can work without tracing, as long as the baggage propagator is configured. In practice most teams use both together.

No. The sampling decision belongs to the trace context. Baggage keeps travelling even when the request is not sampled, which is why it is dependable for application behaviour.

The specification describes minimum supported limits of 180 pairs, 4096 bytes per pair, and 8192 bytes in total, but practical systems should stay far below that. A handful of short entries is a healthy target, and many teams set an even tighter internal budget.

Baggage itself is plain text in a header. It is protected on the wire only if the connection is encrypted, and it is readable by every service that handles the request. Never put secrets or personal data in it.

The context that carries baggage follows the unit of work only where the runtime or a wrapper makes it. When work moves to a different thread or a scheduled task, you may need a context-aware executor or an explicit step that copies the context across.

No. Anyone who can send a request can add a baggage header, so it cannot prove who someone is or what they may do. Use verified credentials and server-side checks for permissions, and use baggage only for labels and hints.

Baggage travels to other services so their code can read it during the request. A span attribute is recorded on telemetry and sent to the backend for later analysis. They only meet if you deliberately copy baggage onto a span.

Baggage lets a request carry a small set of labels from the first service to the last, without changing a single business API. Inside a process, the labels live in the context. At a boundary, a propagator injects them into a carrier such as an HTTP header, and on the other side another propagator extracts them into a fresh context. The same cycle repeats at every hop, so the labels follow the request through the whole chain, growing and changing as services add to them, always flowing in the direction of the request.

The power of baggage is also its danger. Because it rides on every call, it costs bytes at every hop, and because it is plain text that any caller can set, it must never carry secrets, never grant permissions, and never be trusted blindly at the edge. Used with discipline, a few tiny, well-documented labels, sanitised at trust boundaries and copied into telemetry through allow lists, it becomes one of the most practical tools for understanding and steering a distributed system. Like the festival wristband, it works best when it is small, simple, and means the same thing to everyone who reads it.