Baggage is a small collection of name and value pairs that is attached to a request and carried across every service the request visits.

A set of labels that travels

Baggage in OpenTelemetry is a set of key and value pairs, such as “customer tier equals premium” or “region equals europe”. It is part of the request’s context, the invisible package that follows the request through your code. When one service calls another over the network, the baggage is written into the outgoing message, and the receiving service reads it back out. Every service in the chain can look at the baggage, add to it, or remove from it.

Not telemetry, but a helper for telemetry

This is the first thing to understand clearly: baggage is not itself telemetry. It does not show up in your traces, logs, or metrics on its own. It is a delivery service for small facts. What you do with the facts, such as copying them onto spans or using them to decide behavior, is up to you.

Every feature exists because of a pain. Let us look at the pain that baggage removes.

Facts known at the front, needed at the back

Many facts are known only at the beginning of a request. The front door knows which customer plan is being used, which mobile app version sent the request, and which experiment group the user is in. But the services deep in the chain, such as pricing, recommendations, or payment, may want exactly these facts. A payment service that wants to add a “premium customer” label to its telemetry cannot see the original login. It sees only a request from the order service.

The awkward alternatives

• Ask again. Each service looks up the customer record again. It works, but it adds extra calls, extra load, and extra delay for every request.
• Add a parameter to every call. Every function and every API between services must carry the extra field, even those that never use it. Changing hundreds of interfaces is slow and error-prone.
• Invent your own header. Every team invents a different header and a different format, and nothing works with anything else.

Baggage replaces all of these with one standard, agreed way. Put the facts in once, near the front. The SDK and the propagation rules carry them everywhere the request goes, with no change to function signatures and no extra lookups.

A short history

The idea is older than OpenTelemetry. The earlier OpenTracing project had “baggage items” that were attached to a span’s context and traveled with it. OpenCensus had a similar idea called tags. When these projects merged to form OpenTelemetry, baggage was redesigned as its own feature, separate from spans, so that it can be used even when no tracing is active.

A small set of words appears in every discussion of baggage. Learn them once, and the rest of the guide will be easy.

The word “bag”

A good way to remember the word is to keep the picture of a bag with tags. The bag can be passed from hand to hand. Anybody holding it can look inside, put a new tag in, or take a tag out. And because it travels with the traveler, it reaches every stop.

Beginners often mix up baggage with several neighbors. Each does a different job. Let us separate them carefully.

The easy way to tell them apart

What exactly is inside the bag? Each entry is small and simple, and the rules about size and format keep it that way on purpose.

Rules that keep the bag small and safe

• Text only. Both keys and values are text. Numbers and flags are written as text.
• Size limits. The standard sets minimum limits that every implementation must support, roughly on the order of dozens of entries and a few kilobytes in total. Going beyond the limits means that some entries may be dropped.
• Unchangeable once built. A baggage object cannot be edited in place. Setting a value creates a new baggage object with the change, and that new object is placed into the context.
• One value per key. If you set the same key again, the new value replaces the old one.

When baggage crosses a network, it must be written into the message in a format that every service understands. That format is a public standard.

The baggage header

The standard for carrying baggage is the W3C Baggage format. For web requests, it uses an HTTP header named baggage. The value of the header is a comma-separated list of entries, written as key, an equals sign, and value. For example, a header could carry “customer.tier=premium” and “region=eu” together, separated by a comma. Special characters in values are percent-encoded so that they cannot break the format. An entry’s optional metadata is added after a semicolon.

flowchart LR
    GW["API Gateway sets customer tier and region"] -- "baggage header" --> OS["Order Service reads and forwards"]
    OS -- "baggage header" --> PS["Payment Service reads"]
    OS -- "baggage header" --> IS["Inventory Service reads"]

Read the figure from left to right. The gateway puts the labels in at the start. The order service receives them, can read them, and passes them on to both the payment and inventory services. Nobody had to write any special code to look up the customer tier again.

Same idea for other protocols

HTTP is only one road. For gRPC, the baggage rides in the call’s metadata. For message queues, it rides in the message’s properties or headers. The idea never changes: the propagator writes the entries into the carrier on the way out, and reads them from the carrier on the way in. Only the type of carrier is different.

Let us follow the baggage from the moment code sets it to the moment another service reads it.

sequenceDiagram
    participant A as Service A Code
    participant B as Baggage API
    participant C as Context
    participant P as Propagator
    participant H as HTTP Client
    participant S as Service B
    A->>B: Set customer tier to premium
    B->>C: New baggage placed in context
    A->>H: Call Service B
    H->>P: Inject context into headers
    P->>C: Read baggage
    P-->>H: Add baggage header
    H->>S: Request with baggage header
    S->>S: Propagator extracts baggage into context
    S->>S: Service B code reads customer tier

Notice that the baggage API and the propagator are separate parts. The API is the part your code touches, to set and read entries. The propagator is the part that moves the baggage in and out of messages. If the propagator for baggage is not enabled, your code will set values successfully, but nothing will cross the network.

The baggage API is deliberately tiny. Knowing its four basic moves is enough to use it well.

Making the change take effect

Because baggage is unchangeable, building a new bag is only half the job. The new bag must be placed into the context, and the context must be made current, so that code running after the change, and outgoing calls, see it. Most SDKs provide a way to do this for a specific stretch of code, called a scope. Inside the scope, the new baggage is visible. When the scope ends, the earlier baggage returns.

Where to set it

The best place to set baggage is at the entrance of the request, for example in the gateway or the first service. Setting it deep in the chain still works, but it reaches only the services that are called after that point, not those that were called earlier.

Removing before you hand over

Sometimes you want to stop an entry from going any further, for example before calling a third-party service. You build a bag without that entry, and use it only for that outgoing call. The entry is not lost for the rest of your own code, if you keep the original bag for other work.

The true power of baggage appears when a request crosses many services. Each service can read what the earlier ones wrote, and add its own notes for the later ones.

sequenceDiagram
    participant U as User App
    participant G as API Gateway
    participant O as Order Service
    participant P as Payment Service
    participant R as Recommendation Service
    U->>G: HTTP request
    Note over G: Sets customer tier and app version
    G->>O: Request with baggage header
    Note over O: Reads tier and adds experiment group
    O->>P: Request with tier, version, and group
    Note over P: Reads tier for risk rules
    O->>R: Request with tier, version, and group
    Note over R: Reads group to choose an algorithm
    P-->>O: Response
    R-->>O: Response
    O-->>G: Response
    G-->>U: Response

Three kinds of actions

Branches do not mix

When the order service calls both the payment and recommendation services, each call carries its own copy of the baggage. If the payment service adds a new entry, the recommendation service will not see it, because they are separate branches of the request. Baggage flows downward, along the direction of the calls. It does not flow back upward in the response, and it does not flow sideways between sibling calls.

Modern programs do many things at once, and requests often hop through queues. Baggage lives in the context, so it follows the same rules as every other piece of context.

Inside one process

When code hands work to another thread or task, the context must be carried along. If it is not, the new worker starts with an empty context, with no active span and no baggage. Many instrumentation libraries and automatic agents wrap the common thread pools so that the context moves with the work. When you write your own concurrency, check that you pass it on.

Through a message queue

With queues, the sender and receiver do not talk directly. The sender puts a message in, and the receiver takes it out later. The propagator writes the baggage into the message’s headers on the way in, and reads it from the headers on the way out. The receiver can then rebuild the context, even if hours have passed.

flowchart LR
    PR["Producer Service sets baggage"] --> IN["Propagator writes baggage into message headers"]
    IN --> Q["Message Queue holds the message"]
    Q --> OUT["Consumer reads message headers"]
    OUT --> EX["Propagator rebuilds baggage in the context"]
    EX --> CO["Consumer code reads the entries"]

This is the point where most beginners are surprised. Putting something in baggage does not make it visible in your traces, logs, or metrics.

The surprise

When a service exports spans, the exporter sends the span’s own fields: IDs, name, times, status, and attributes. It does not look inside the baggage. The baggage stays in the context and in the headers. If you want an entry to appear on telemetry, something must read it from the baggage and write it into the telemetry deliberately.

flowchart LR
    CX["Context with baggage"] --> BP["Baggage span processor (optional)"]
    BP --> SA["Span attributes"]
    SA --> EX["Exporter"]
    EX --> BE["Backend: searchable by customer tier"]
    CX -. "without a processor" .-> NO["Baggage never reaches the backend"]

Ways to copy baggage into telemetry

Once baggage entries are copied onto telemetry, they become powerful ways to slice and filter your data. Each signal has its own rules about which entries suit it.

The cardinality rule for metrics

Cardinality is the number of different values a label can have. A label with three values, such as free, standard, and premium, creates three series. A label with a million values, such as a user ID, creates a million series. Metrics become slow and expensive very quickly if their labels have many values. So, for metrics, copy only entries with a small and fixed set of possible values. For traces and logs, where each record stands alone, you can afford richer values.

Because baggage travels everywhere, it deserves careful choices. A good entry is small, safe, stable, and useful to more than one service.

Good fits

Poor fits

Baggage is one tool among several. Use this path of simple questions to decide whether it is the right one.

flowchart TB
    S["I have a fact about this request"] --> Q1{"Do other services need it?"}
    Q1 -- No --> A1["Span attribute on the current span"]
    Q1 -- Yes --> Q2{"Is it safe, small, and not secret?"}
    Q2 -- No --> A2["Do not use baggage: look it up securely or pass it in the API"]
    Q2 -- Yes --> Q3{"Will services use it for decisions or for telemetry only?"}
    Q3 -- Decisions --> A3["Prefer a trusted lookup. Baggage can be forged"]
    Q3 -- Telemetry --> A4["Baggage with an allowed list copied to telemetry"]

Reading the guide

Start with the fact. If no other service needs it, a plain span attribute is enough, and nothing has to travel. If other services need it, ask whether it is safe to share, small, and not secret. If it is not safe, find another way, such as a secure lookup. If it is safe, ask what it will be used for. When it is only for labeling telemetry, baggage is a great fit. When it will drive important decisions such as permissions, prefer a trusted source, since anyone can forge a header.

Let us walk through a realistic need, step by step, and see exactly where baggage helps.

The need

A shop notices that checkout is sometimes slow, and wonders whether premium customers, who have a promise of fast service, are affected more or less than free customers. Only the gateway knows the customer’s plan. The payment service, where most of the time is spent, does not.

What baggage saved

Without baggage, the payment service would have to look up the customer plan in a database for each request, or every interface between services would need a new parameter. With baggage, one entry was set once, and every service gained the ability to label its data. The example also shows the three-step discipline: set early, carry on, and copy to telemetry only what you need.

Baggage looks tiny, but it is added to every call. Small amounts, repeated millions of times, become real costs.

The arithmetic of extra bytes

Suppose your baggage holds ten entries of about forty bytes each. That is roughly 400 extra bytes on every request. If your internal services make 100,000 calls per second, that adds up to 40,000,000 bytes, or about 40 megabytes, of extra traffic every second, only for baggage. Every call also spends a bit of time writing and reading the header.

What limits exist

• The W3C standard sets minimum sizes that implementations must support, roughly on the order of dozens of entries and a few kilobytes in total. Implementations may drop entries beyond their limits.
• Web servers, proxies, and gateways have their own header size limits. A very large baggage header can cause a request to be rejected.
• Each hop reads and writes the header again, so a larger bag costs more at every hop.

The same feature that makes baggage useful, that it goes everywhere, makes it risky. Everything in the bag is sent to every service that the request calls, and that includes services you do not control.

flowchart LR
    NET["Public Internet"] --> ED["Edge: validate or strip incoming baggage"]
    ED --> IS["Internal Services share baggage"]
    IS --> TP["Third-party API: send no baggage"]
    IS --> DB["Internal database or queue"]
    IS --> LG["Logs and proxies may record headers"]

The places a bag can leak

How to stop the leaks

• Put only safe, non-secret, non-personal values into baggage. Treat it as public inside your company.
• Configure clients so that baggage and trace headers are sent only to hosts you trust, not to arbitrary outside addresses.
• Use encrypted connections between all services.
• Use an allowed list when copying baggage to telemetry.
• Review proxies and logging settings so that baggage is not recorded where it should not be.

Leaks are about what goes out. The other half of the story is what comes in. Anyone can send a request with any baggage header they like.

Forged baggage

A caller outside your company can simply add a header such as “customer tier equals premium” to their request. If your services believe it, a free user could receive premium treatment, higher limits, or access to features. Baggage is information that arrived with the request. It is not proof that the information is true.

Protective habits

• Strip or replace at the edge. At the public boundary, remove incoming baggage from unknown callers, and set your own entries from trusted sources, such as your login system.
• Use an allowed list on read. Services read only the keys they expect, and ignore the rest.
• Validate values. Accept only known values, such as the three allowed tiers, and ignore anything else.
• Keep decisions out of baggage. For permissions and billing, look up the real value from a trusted system.
• Cap size. Reject or trim baggage that is too large.

Because baggage is invisible by default, it is easy to lose control of it. A little governance keeps it healthy.

Keep an inventory

Maintain a short shared list that records every baggage key in use, who owns it, what it means, what values are allowed, and which services read it. Without this list, nobody knows what is inside the bag, and nobody dares remove anything.

What to measure

Baggage works only when the right propagator is set up. A few settings decide whether it flows, and where.

The propagators setting

OpenTelemetry has a standard environment variable named OTEL_PROPAGATORS, which lists the propagators that the SDK should use. A common default is to use both the trace context propagator and the baggage propagator. If baggage is missing from the list, the SDK will not write or read the baggage header, even if your code sets entries.

Narrowing where it goes

• Many HTTP client instrumentations let you limit the hosts that receive propagation headers, so outside addresses get nothing.
• You can configure a gateway or proxy to remove the baggage header from outbound calls to specific destinations.
• You can build the bag for a particular call, leaving out entries that the destination should not see.

Consistency across the fleet

Every service in a call chain needs the same propagator choices. If service A writes baggage but service B does not read it, the entries stop at B and the services after it never see them. Agree on one setup, and apply it through shared configuration, container images, or platform defaults, so each team does not have to remember.

Baggage is simple and powerful, and it carries real risks. A fair view includes both sides.

Decisions to make on purpose

Teams that use baggage for years find the same good habits, and the same traps.

Patterns worth copying

Anti-patterns to avoid

Keep this short list close. It prevents most of the trouble that teams meet with baggage.

Common mistakes and their fixes

When an entry is missing downstream, follow the path of the header from the point where it was set to the point where it should have been read.

First, a made-up story that shows baggage at work. Then, a look at the common ways organizations use the same idea.

Baggage is not one single box. It is a small team of parts, each with one clear job. Naming them helps you find the part that failed.

Every bag has a life: it is made, it travels, it changes, and it ends. Knowing the stages makes it easier to reason about what a given service will see.

Where the data is stored

The bag itself lives only in memory and in headers while the request is alive. It is not saved to any database by OpenTelemetry. This is good news for privacy, because there is no hidden store. The only lasting copies are the ones you create by copying entries to spans, logs, or metrics, and the ones recorded by proxies or tools that log headers.

Because baggage sits in the context, other parts of the SDK that look at the context can use it. This opens clever uses, and some warnings.

Sampling decisions

A sampler decides which traces to keep. In several SDKs, the sampler receives the parent context when a span starts. A custom sampler could read a baggage entry such as a debug marker, and decide to always keep traces for requests that carry it. This is useful for a support engineer who wants to see one specific request in full detail. Use it carefully, because anyone who can send the header can force sampling, which raises your telemetry volume and cost.

Feature flags and experiments

A feature flag is a switch that turns a feature on for some users. Many flag systems already provide their own evaluations, so you rarely need baggage to hold the flag itself. But carrying the name of an experiment variant in baggage is a good way to label telemetry. Each service stays free to look up the flag, and the label lets you compare the results across the whole request.

Routing and decisions

Some teams use baggage to hint at routing, such as sending test traffic to a test database. Be careful. Since the header can be forged, a hint in baggage can be misused to reach systems that should not be reachable. Make sure that the final decision is enforced by a trusted component, and treat baggage as a suggestion that is checked.

Quick answers to the questions people ask most often about baggage.

You started with a suitcase and a few tags. You now know how that picture maps onto requests, services, and the real risks of carrying a bag everywhere.