Before talking about danger, we need to know exactly what we are protecting.

The simple definition

Baggage is a set of name and value pairs that travels along with a request as it moves from service to service. For example, the pair customer.tier with the value premium can be set once at the front door. Every service that handles the request afterward can read it, without having to ask a database or call another service. Baggage is part of OpenTelemetry’s idea of context, the bundle of facts that follows a request through a system, which also carries the trace identifiers that link steps together.

Why teams like it

Baggage solves a real problem. Suppose a request starts at a web server and passes through ten services. Only the first knows which experiment group the user belongs to. Without baggage, each of the other nine would need to look it up, or every developer would need to pass the value through every function call and every message by hand. With baggage, the first service sets it once and the framework carries it along. Common uses include experiment groups, region names, request priorities, plan tiers, and flags that help with debugging.

Why it needs special care

Four properties make baggage riskier than most other request data.

To defend a road, you must know where it goes. Here is the route baggage takes.

Inside one service: the context

Within a single running program, baggage lives in the context, a small container that is passed along with the current piece of work. Code can read entries from it, and can create a new version with extra entries. The baggage itself is never changed in place. Adding an entry produces a fresh copy, so earlier holders of the old copy are not surprised.

Between services: the propagator

When a service makes a call to another service, a component called a propagator writes the baggage into the outgoing message. For web calls, it appears as a header named baggage. The header is a list of entries separated by commas, each written as a name, an equals sign, and a value, with optional extra properties after a semicolon. Values are percent-encoded so that special characters survive the trip. On the receiving side, a matching propagator reads the header and rebuilds the baggage in the new service’s context.

Propagators are usually switched on for you. In many OpenTelemetry setups, the default configuration propagates both the trace context and baggage. Instrumentation libraries for web servers, web clients, remote procedure calls, and message systems call the propagators automatically. So a developer can set an entry in one place and, without writing any more code, see it appear in dozens of services.

flowchart LR
  CL["Client"] -->|"baggage header"| GW["Edge gateway"]
  GW -->|"baggage header"| A["Service A"]
  A -->|"baggage header"| B["Service B"]
  A -->|"baggage header"| C["Service C"]
  A -->|"message attributes"| Q["Message queue"]
  Q --> W["Background worker"]
  B -->|"baggage header"| EXT["Outside partner API"]
    

Figure 1 shows how far the tags can travel. The client sends a request to the edge gateway. The gateway forwards it to Service A, which calls B and C, puts a message on a queue for a background worker, and finally B contacts an outside partner. At every arrow, the baggage may be written out again. Notice that two of those arrows, to the queue and to the outside partner, leave the part of the system you fully control.

Other carriers: remote procedure calls and messages

Web headers are only one carrier. Remote procedure call systems carry baggage in call metadata, which works much like headers. Message systems carry it in message headers or attributes, so it is stored with the message. Some environments, such as serverless functions or batch schedulers, pass context through event fields or environment settings. The names and shapes differ, but the idea is the same everywhere: a small set of text entries rides alongside the real data, written by one side and read by the other. Whenever you meet a new carrier, ask the same three questions. Who can write to it? Who can read it? How long does it stay?

Limits on size

The standard that defines the baggage header sets minimum limits that every implementation should support, in the range of about sixty-four entries, a few thousand bytes for each entry, and roughly eight thousand bytes in total. Implementations may drop entries that go over their limits. Web servers and proxies also have their own caps on the total size of headers, commonly somewhere between eight and sixteen thousand bytes, though this varies. Check the current specification and your own infrastructure for exact numbers. These limits matter for security, as Chapter 7 shows.

One of the most common confusions is thinking that baggage automatically becomes part of traces, logs, and metrics. It does not, but it often gets there anyway.

On its own, baggage is only context. It is not written onto spans, log lines, or metric points. This is good news, because it means that putting an entry in baggage does not by itself send the value to your tracing vendor. But there are several ways it ends up in places you may not expect.

Two surfaces to protect

It helps to picture two surfaces. The wire surface is everything that moves between systems: headers, message fields, and the logs of devices in between. The telemetry surface is everything that is stored for later: spans, logs, and metrics that received a copy of a baggage value. A good defense watches both. Closing one door while leaving the other open gives only the feeling of safety.

A threat model is simply an honest answer to three questions: what are we protecting, who might hurt it, and how?

What we are protecting

• Private information about customers, staff, and the company itself.
• Correct decisions, such as who may do what and how much each customer pays.
• Availability, meaning that systems stay up and fast.
• Budget, since telemetry that grows without limit costs money.
• Trust in the data, so dashboards and investigations are not misled.

Who might hurt it

The trust zones

flowchart LR
  subgraph U["Untrusted zone"]
    C["Browsers and apps"]
    P["Partner systems"]
  end
  subgraph E["Edge zone"]
    G["Edge gateway"]
  end
  subgraph I["Internal zone"]
    S1["Service A"]
    S2["Service B"]
    Q["Message queue"]
  end
  subgraph X["Outside vendors"]
    V["Payment and analytics APIs"]
  end
  C -->|"baggage may be forged"| G
  P -->|"baggage may be forged"| G
  G -->|"cleaned baggage"| S1
  S1 --> S2
  S1 --> Q
  S2 -->|"baggage may leak"| V
    

The picture in Figure 2 shows the most important idea in this guide. There are boundaries, and every boundary needs a guard. Incoming baggage from outside is untrusted input. Outgoing baggage to outside is a possible information leak. Inside, even trusted services can be wrong or compromised, so a little caution is still wise.

Three short attack stories

The free upgrade. A curious customer opens the browser’s developer tools and sees that a request includes a baggage entry about their plan. They change the value from “basic” to “premium” and resend the request. A service downstream sees “premium” and unlocks a feature. No password was stolen, and no bug in the usual sense was found. The system simply believed a note.

The loud neighbor. An attacker discovers that a baggage entry called “debug” makes services write detailed logs. They send it on every request. Log volume grows tenfold, storage fills, and the logging system slows down. Meanwhile, the extra detail also writes values from other customers’ requests into logs that a wider group can read.

The quiet leak. No attacker at all. A team adds a customer reference to baggage for tracing. A year later, a new feature calls an analytics vendor through a library that uses the same web client. For months the vendor receives the reference with every call. Nobody notices until an audit asks which outside companies hold customer references.

These stories share a pattern: the harm came from ordinary features working as designed, in places the designers had not pictured.

Six kinds of trouble in plain words

The next chapters take these one at a time, and add a few that are special to baggage, such as injection into other systems, noisy telemetry, and data that leaks between requests.

The most common baggage problem is not a clever attack. It is a helpful developer putting the wrong thing in the bag.

A made-up story

Imagine a company called Harbor Foods, a name invented for this guide. A support engineer wants to see the email address of the affected customer in every service’s logs, to speed up investigations. So the login service sets a baggage entry user.email. A week later, the checkout service calls an outside shipping partner. The instrumentation attaches the baggage header, as it does to every outgoing call. The partner’s servers now receive the customer’s email address with every request, whether or not the partner has any right to it, and the partner’s access logs keep it for ninety days. Nobody at Harbor Foods did anything on purpose. The leak was the sum of three reasonable decisions.

The ways leaks happen

• Outbound calls to third parties. Payment gateways, mapping services, analytics tools, and shipping partners are all just “downstream calls” to the instrumentation.
• Infrastructure logs. Load balancers, gateways, and web servers can record headers. Anything in a header may end up in a log that many people can search.
• Telemetry copies. When baggage is copied onto spans and log lines, the value is stored in the observability system, often with broad access and long retention.
• Error pages and debugging tools. Debug output and error reports sometimes print all headers.
• Browsers. If a browser application attaches baggage to requests, then the user, and anyone with access to their device, can read it. Browser applications also need the server to explicitly allow the baggage header across origins, and that permission should not be given to every site.

Giving support teams what they need, safely

The usual reason people put private values in baggage is a good one: they want to find a customer’s requests quickly. There are safer ways to give support that power. Carry a short, random request reference that identifies the request but says nothing about the person. Store the link between that reference and the customer in a protected system, with access limited to support staff and a record of who looked. Support then searches by reference, and an engineer who reads a trace or a log sees only a meaningless code. If the reference leaks, little is lost, because it cannot be used without the protected link.

What counts as sensitive

If anyone can write on the tag, nobody should believe the tag when something important is at stake.

The core problem

The baggage header arrives from the network. Whoever sent the request decides what it says. There is no signature, no proof of origin, and no check that the entry matches reality. A service that reads customer.tier=premium has learned only that somebody claimed the customer is premium. If that somebody was a browser or a script, the claim is worthless.

Attacks that follow

• Privilege claims. An attacker sends an entry such as an admin flag or a tenant name, hoping a service will treat it as true.
• Free upgrades. An entry that changes pricing, limits, or features is a gift to anyone who guesses its name.
• Cost and load tricks. A “debug” or “verbose” flag that switches on expensive behavior lets an outsider make your systems work harder, or write more logs, at will.
• Skipping safeguards. A flag like “skip cache” or “skip checks”, added for convenience in testing, may still be honored in production.
• Tampering from inside. A compromised internal service can rewrite entries for everyone downstream, and the downstream services cannot tell.
• Guessable names. Attackers can try common names, since baggage names are visible in documentation, code, and traffic.

The rule: hints, not decisions

The safe way to think is that baggage can carry hints, never decisions. A hint helps a service do something a little smarter, such as choosing which experiment text to show. A decision is something that must be right for the system to be secure or correct, such as who is allowed to see which data, or how much to charge. Decisions must be made from facts the service can verify: an authenticated identity, a verified token, or a record in a trusted database.

Stale and replayed claims

Even an honest value can become false. A request captured today can be replayed tomorrow by anyone who saw it, carrying yesterday’s entries. A stored message may carry a plan tier that has changed. Because baggage has no timestamp and no expiry, a service cannot tell how old a claim is. Another reason to keep decisions out of baggage: the world changes, and the tag does not.

Making honest values more believable

The edge gateway should remove any baggage coming from untrusted clients and, where needed, set fresh values itself from facts it has verified. That way, inside the system, an entry that was set by the gateway can be trusted somewhat more than an entry that arrived from outside, because the outside entries were never allowed through. Where a value must be trusted by several services, the safest design is not baggage at all, but a signed token that carries the claim and that every service verifies.

A single large header is a nuisance. The same header repeated across a hundred internal calls is an attack.

Why baggage can be used as a megaphone

An incoming request becomes many outgoing requests as it passes through a system. A page that looks simple to a user may cause dozens of internal calls. Each internal call carries the baggage header. If an attacker sends a large baggage header once, your own systems will copy it onto every call, multiplying its size across your internal network, your proxies, and your logs. The attacker spends a little. You spend a lot.

flowchart TD
  ATK["One request with an 8 KB baggage header"] --> GW["Edge gateway"]
  GW --> A["Service A"]
  A --> L1["40 calls, each carrying 8 KB"]
  L1 --> L2["Each call causes 3 more calls, 120 in total, each carrying 8 KB"]
    

A worked example

The numbers are invented for teaching, but the shape is real. A small stream of cheap requests creates a heavy stream of internal traffic, plus extra work for parsing headers, writing logs, and, if the value is copied to telemetry, storing it. The attacker needs no special skill.

Trim, reject, or pass through?

When the edge meets an oversized or odd header, it has three choices. It can trim it, keeping only the allowed entries that fit. It can reject the whole request with an error. Or it can pass it through unchanged. Passing through is the unsafe choice and should be used almost never. Trimming is friendly to real users, because an honest client with one extra entry still gets served. Rejecting is better for clearly malformed or hostile input, because it gives the sender a clear signal and saves work. A common mix is to trim ordinary excess and reject headers that cannot be parsed or that exceed a much higher hard limit. Whatever you choose, count each outcome.

Other size problems

• Rejections. If the total headers grow past a proxy’s cap, requests may fail with errors. An oversized baggage header can therefore break real users’ requests, not just the attacker’s.
• Silent dropping. Implementations may silently drop entries above their limits, so important entries could disappear without any message.
• Memory. Many small entries cost parsing time and memory at every hop.
• Growth by accident. Even without attackers, teams may add entries over years until the header is big and nobody knows why.

The defense: strict, small limits at the edge

Choose your own limits, much smaller than the standard’s maximums, and enforce them where requests enter. A sample policy might allow no more than ten entries, no more than sixty-four characters per name and value, and no more than five hundred bytes in total. Anything over the limit is either trimmed to the allowed entries or removed whole. Then internal services enforce the same limits again when they add entries, so that a growing system cannot creep upward. With the policy above, the same attack from the worked example would add at most five hundred bytes per call instead of eight thousand, a sixteen-fold reduction, and would be easy to notice in monitoring.

A baggage value is text that someone else chose. When your code pastes that text into something else, the writer gets a say in what happens.

Where baggage values often get pasted

Decode first, then validate

Baggage values are percent-encoded on the wire. A harmless-looking string such as “%0A” decodes into a line break. This means that a check done on the encoded text may miss what the decoded text contains. The right order is to decode once, then validate the decoded text against a strict pattern, and never decode twice.

Log forging in plain words

Logs are often read as a story, one line at a time. If a baggage value contains a line break followed by text that looks like a log line, the log now contains a line that nobody’s code wrote. An attacker can use this to invent events, such as a successful login, or to bury real events under noise. The remedy is simple. Write values into structured fields, so that the logging system stores them as data, and strip control characters before they get anywhere near a log.

Prefer small, fixed shapes

The safest values are ones that can be checked against a short list: “region equals one of five known codes”, “tier equals one of four known names”. Convert the incoming text into a fixed type, such as an enumeration, at the moment of reading. If the text does not match, treat the value as missing. This turns free text, which is dangerous, into a choice from a menu, which is not.

Copying baggage onto spans, logs, and metrics is useful, and it hands an outsider the pen that writes in your observability tools.

Why teams copy baggage into telemetry

Baggage is a convenient way to label telemetry with business facts. If every span carries the plan tier, then engineers can ask “are premium customers slower?” Many SDKs offer a baggage span processor that copies entries onto every span. The idea is good. The risk is in which entries, and who chose their values.

Cardinality: the explosion of unique values

Cardinality means the number of different values that a label can take. Metric systems create a separate time series for every combination of label values. A label with five possible values is cheap. A label that an outsider can set to anything creates a new series for every request.

Take an example. Say five services each produce twenty metrics. If baggage copies a label that could take one million different values, the number of series could grow to five times twenty times one million, or one hundred million series. No metrics backend is built for that. Costs jump, queries slow, and the system may refuse more data or fall over. An attacker who knows that a label is copied can do this on purpose by sending random values. The same thing can also happen by accident when a developer adds a user ID to baggage.

Finding the attribute that is exploding

When costs or slowness appear, the cause is usually a single attribute. Ask your telemetry system for the number of distinct values per attribute over the last hour, sorted from highest to lowest. An attribute with thousands of values per hour that you expected to have five is the culprit. Trace it back to its source: a baggage copy rule, a library setting, or a new code change. Then remove the rule and add a limit so the problem cannot return quietly.

Other kinds of poisoning

• Skewed experiments. If an experiment group comes from baggage, an outsider can send fake groups, and your analysis counts them.
• Wrong cost reports. If cost labels come from baggage, a service can claim another team’s name and shift the bill.
• Misleading dashboards. Fake values can hide real problems, or create false alarms.
• Indexing load. Tracing backends that index attributes can be slowed by endless new attribute values or huge ones.
• Hidden messages. Long values can smuggle text, such as links, into tools that display attributes to staff.

Defenses

Sometimes the danger is not an attacker at all. It is a note that was left behind and read by the wrong person.

How the context follows the work

The current context is usually tied to the current thread or task. Frameworks switch the context on when a request begins and off when it ends. That works well as long as each piece of work runs entirely on its own. Trouble starts when work jumps between threads, is delayed, or is reused.

Common causes

• Thread pools and reused workers. If a worker picks up a task and the context from an earlier task is still attached, the new task runs with the wrong baggage.
• Scopes that never close. Code that makes a context current but forgets to detach it in all paths, especially on errors, leaves it behind.
• Async callbacks and futures. A callback may run later, in another thread, with either no context or a stale one, depending on how the framework carries it.
• Global or shared variables. A context stored in a shared place, such as a cache or a singleton, is visible to every request.
• Background jobs started from requests. A job that inherits the context of the request that started it keeps that baggage for its whole life, which may be hours.
• Connection reuse. Rarely, code stores request details on a long-lived connection object.

What it looks like

A support agent searching logs for customer A sees log lines labeled with customer B’s tenant. A background job for tenant A writes a record that is tagged for tenant B. A premium flag from a previous request switches on features for the next customer. These bugs are hard to find because they appear only under load, when threads are busy and reused.

Defenses

• Always close scopes. Use the language’s safe pattern so that the scope is released even when errors occur.
• Use context-aware executors. Wrap thread pools and schedulers with the helpers that carry context explicitly, and test them.
• Start clean. At the beginning of each incoming request, and at the start of each background job, begin with a fresh context.
• Keep context out of shared state. Never store baggage or context in global places.
• Do not use baggage for tenant identity. Tenant isolation should come from verified identity, so that a bleed cannot cause a cross-tenant leak of real data.
• Test under concurrency. Run tests that fire many parallel requests with different baggage values, and assert that each request only ever sees its own.

A web call is over in a moment. A message in a queue can sit for days, and baggage sits with it.

flowchart LR
  P["Producer service"] -->|"baggage copied into message headers"| Q["Queue stores messages for days"]
  Q --> C1["Consumer reads soon"]
  Q --> DLQ["Dead letter queue read by operators"]
  Q --> MIR["Mirror to analytics or a partner"]
  Q --> C2["Consumer reads much later with stale values"]
    

What changes with messages

Messaging instrumentation usually copies the context, including baggage, into the message’s headers or attributes. That turns a short-lived tag into stored data. It is now written to disk, copied to replicas, backed up, and visible to everyone who can read the queue. It may also be moved to places you did not plan.

An example of the slow burn

Suppose an order service puts a message on a queue and a shipping service reads it two days later because of a backlog. The message carries baggage from the original request, including a flag that said “expedited” at the time. The customer cancelled the expedited option an hour later, but the flag lives on. The shipping service honors it and the company pays for faster delivery nobody wanted. Nothing was hacked. The system simply believed an old note.

Specific risks

• Stale claims. A message created when a customer was on a premium plan may be processed after the plan ended, and the baggage still says premium.
• Replays and retries. Failed messages are retried and sent to dead-letter queues, where operators or tools may inspect them and see every baggage entry.
• Mirroring and exports. Messages are often copied to analytics systems, other regions, and partners, taking baggage with them.
• Restored backups. Restoring data into a test environment may bring production baggage with it.
• Batches. A consumer that reads fifty messages at once has fifty different baggage sets. Which one applies to the batch? Using any single one is a mistake.
• Limits. Messaging systems cap how many attributes a message can carry. Baggage may squeeze out other, more important attributes.

Defenses

• Decide on purpose. By default, do not copy baggage into messages. Allow only specific keys, on specific topics, where there is a clear need.
• Prefer explicit fields. If the consumer needs a fact, put it in the message body with the same access controls as the rest of the message, and have the consumer re-check anything that matters.
• Treat stored baggage as old. Never use values from messages to make decisions without re-verification.
• Use links for batches. When a consumer processes many messages together, record links to each message’s trace, rather than adopting one parent context and its baggage.
• Keep retention short for queues and dead-letter queues, and restrict who may read them.
• Scrub before copying data out. When messages go to analytics, partners, or test systems, remove baggage first.

Baggage is data about people and businesses. The rules that apply to other data apply to it too.

Privacy laws and company policies are written about personal data, which means any information that can identify a person directly or indirectly. They rarely care which technical mechanism carries the data. If baggage includes a customer number, a device ID, a precise location, or anything that could be linked back to a person, then baggage is carrying personal data, and the usual duties apply. This guide cannot give legal advice, and rules differ by country and industry, so involve your privacy and legal teams. The principles below are the common ground.

Retention and deletion in practice

People may ask a company to delete the personal data it holds about them. If baggage values have been copied into logs and traces, deletion becomes a search through many systems, each with its own storage and backups. The easy cure is prevention: if no personal data was ever stored there, there is nothing to delete. If some was stored, shorter retention in telemetry stores limits how long the problem lasts, and a registry of where each key was copied tells you where to look.

The simplest path

The easiest way to comply is to keep personal data out of baggage completely. If a service really needs to know something about the user, it can look it up from a trusted store using the verified identity, with all the access control and record keeping that store already has. This keeps baggage in the clear-cut category of “harmless hints”, and keeps your list of personal data flows short and easy to explain.

Instead of reacting to every threat one by one, ask four simple questions before any entry is allowed.

flowchart TD
  Q1{"Would it hurt if a stranger read it"} -->|"yes"| N1["Do not put it in baggage"]
  Q1 -->|"no"| Q2{"Will any decision depend on it being true"}
  Q2 -->|"yes"| N2["Use a verified token or a trusted lookup"]
  Q2 -->|"no"| Q3{"Is it small, with a fixed set of values"}
  Q3 -->|"no"| N3["Use a short opaque ID or leave it out"]
  Q3 -->|"yes"| Q4{"Must it reach outside partners"}
  Q4 -->|"yes"| N4["Send it as an explicit field in the partner interface"]
  Q4 -->|"no"| OK["Allowed in baggage. Add it to the registry"]
    

Reading the flow

First question: would it hurt if a stranger read it? Secrets, personal data, and internal structure fail at once. Second: will any decision depend on it being true? If yes, baggage is the wrong tool, because it cannot be trusted. Third: is it small and from a fixed set? That keeps size and cardinality under control, and makes validation easy. Fourth: must it reach outside partners? If so, do not rely on automatic header propagation. Send it deliberately, as a documented field that the partner agrees to receive.

The gray areas

Some entries are neither clearly safe nor clearly dangerous. A coarse location such as a country is usually fine, but a city or postcode may identify a small group. A plan tier is fine, but a plan tier plus an exact signup date may point to one person. An experiment cohort is fine, but a cohort name that reveals a product not yet announced is a business secret. When in doubt, move up one level of coarseness, or leave the entry out. It is far easier to add an entry later than to withdraw one that has already spread.

Good and bad entries

The cheapest place to stop forged or oversized baggage is the door, before it enters a thousand hallways.

flowchart LR
  NET["Internet"] --> WAF["Web application firewall with header size rules"]
  WAF --> EDGE["Edge gateway: strip, allow list, set trusted values"]
  EDGE --> MESH["Internal services with a validation helper"]
  MESH --> EGR["Egress proxy: remove baggage for outside hosts"]
  EGR --> OUT["Outside partners"]
  MESH --> OBS["Telemetry with allow listed baggage copies"]
  MESH --> MQ["Queues with allow listed baggage only"]
    

What the gateway should do

Where to do it

The same job can be done by a reverse proxy, an API gateway, a service mesh ingress, a content delivery network’s edge functions, or a small piece of gateway code. Most of these can remove or overwrite request headers by rule. Choose the layer that already sits in front of all your traffic, so there is no side door. If different entry points exist, such as a public gateway and a partner gateway, each needs its own policy, because the trust level differs.

Partner traffic needs its own door

Some businesses exchange requests with partners who legitimately need to send or receive a few context entries, for example a shared correlation hint. Treat such partners as a separate trust zone with a separate entrance, not as the general public. Identify them strongly, for example with client certificates. Write down the exact keys that may be accepted from each partner, and the exact keys that may be sent to each partner. Reject everything else. Review the list on a schedule, because partnerships and their needs change.

Do the same for the trace context

The same reasoning protects the trace identifiers and the sampling flag that travel beside baggage. Outsiders who can set those can also force expensive sampling or confuse traces. A gateway that starts fresh trace context for untrusted callers closes both holes with one rule.

The edge is the first guard, not the only one. Services should still be careful with what they read and what they write.

Why inside defenses still matter

Edge rules can have gaps. A side entrance may exist, a partner may be allowed some entries, an internal service may be compromised, or a rule may fail to deploy. If every internal service trusts every entry just because “the edge checks everything”, then one gap becomes a full failure. Layered defense means each service keeps its own small guard.

One shared helper for every read and write

The most useful single control is a small shared library, owned by one team, which all services use instead of calling the raw baggage functions. It does the careful work in one place.

Make the safe way the easy way

• Lint rules. A rule in the build that flags direct use of the raw baggage functions outside the shared helper, with a short explanation of what to use instead.
• Namespaced keys. Names start with a short owner prefix, so that two teams cannot accidentally use the same key for different meanings, and so that readers know whom to ask.
• Code review checklists. Any change that adds a new key or a new copy of baggage into telemetry gets a security and privacy look.
• Known caller identity. When services authenticate to each other, for example with mutual certificates from a service mesh, a service knows who sent a request. Entries then become “claims made by service X”, which is somewhat more reliable than anonymous text, though still not proof of truth.

A review checklist for a new key

• Does the purpose fit in one sentence, and does someone own the key?
• Does it pass the four questions of Chapter 13?
• What is the exact set of allowed values, or the exact pattern and maximum length?
• Who sets it, and who reads it, and what does each reader do with it?
• Will it reach any outside party, any queue, or any stored telemetry?
• What happens if the value is missing, wrong, or hostile? The answer should be “nothing important”.
• When will the owner review whether the key is still needed?

Who is allowed to set what

The last guard stands at the door that leads out, making sure nothing leaves that should stay inside.

The main rule

Do not send baggage to outside parties unless there is a written reason. Outside parties include payment gateways, mapping and messaging providers, analytics tools, advertising networks, and every software-as-a-service product that your code calls. They did not ask for your internal hints, they may log them, and you may be unable to make them delete them later.

Where leaks hide

• Vendor libraries. A payment company’s client library uses an ordinary web client, which the instrumentation wraps, so the baggage header goes along.
• Webhooks and callbacks. Calls from your system to a customer’s server carry the header too.
• Redirects. A redirect that moves a call from your domain to another may carry headers across.
• Health checks and probes that call external monitoring services.

Ways to stop it

Using two of these together is wise. The proxy catches what the code forgets, and the code-level control protects when a service runs in a place without the proxy, such as a developer’s laptop or a new environment.

When a partner needs data

If a partner truly needs a fact that you currently keep in baggage, give it to them on purpose. Add a documented field to the partner interface, send only that field, describe it in the contract, and agree on how long they keep it. That turns an accidental leak into a deliberate, reviewable data share.

Once a value is copied from baggage into a stored span, log, or metric, it lives as long as that data does. Choose carefully what to copy.

Copy with intent

Instead of “copy everything”, define a short list of baggage keys that are useful for analysis and safe to store. Only those are copied, to spans and logs. Everything else is left behind in the context. Each key on the list should have an owner and a reason in the registry.

Label the origin

A useful habit is to place copied values under a clear name prefix, so that anyone reading a trace can tell at a glance that the value came from baggage and was not measured or verified by the service. For example, a name such as baggage.region tells an analyst to treat the value as a hint. This simple labeling prevents the mistake of treating a forged flag as a fact in an investigation.

Where each signal stands

Second line of defense: the Collector

Even when applications are careful, mistakes happen. The OpenTelemetry Collector can act as a safety net. Rules can remove attributes whose names are not on the approved list, mask values that match patterns such as email addresses, or delete anything that carries the origin prefix but is not registered. SDKs also have limits for the length of attribute values and the number of attributes per span, which can be set through configuration, such as OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT. Using both the SDK limits and the Collector rules gives two layers.

Access and retention

Telemetry stores are searched by many engineers. If baggage-derived values are stored there, apply the same access controls and retention rules as to any other data of that sensitivity. Review who can read raw traces and logs, and remove broad access that was granted just because “it is only debugging data”.

Rules written on paper protect nothing unless someone owns them. A registry is the simplest tool for ownership.

What a registry is

A baggage registry is a list, kept in version control, of every key allowed in your systems. Each key has a row that answers the questions a security reviewer would ask. The registry also feeds the code: allow lists in the edge gateway, the shared helper, the telemetry copier, and the egress filter are all generated from it, so that there is one source of truth.

flowchart LR
  A["Proposal with purpose and data class"] --> B["Security and privacy review"]
  B -->|"approved"| C["Added to the registry and allow lists"]
  B -->|"rejected"| X["Use another design"]
  C --> D["Used in services and monitored"]
  D --> E["Periodic review"]
  E -->|"still needed"| D
  E -->|"unused"| F["Retired and removed"]
    

The lifecycle in practice

A team that wants a new key opens a short proposal that fills in the registry row. Security and privacy reviewers check it with the four questions from Chapter 13. If approved, the registry change is merged, and generated allow lists roll out to the edge, the helper, and the telemetry rules. Monitoring then shows how often the key is seen. Every quarter, owners confirm their keys. Keys that nobody reads are retired, and the retirement is made real by removing them from the allow lists and the code. This habit keeps the baggage small, which is itself a security measure.

A guard who has never been tested is only a guess. These checks turn the guess into evidence.

What to automate

Manual checks fade away. Put the cheap tests into the build, so that every change runs them: validator tests, malformed header tests, registry consistency tests, and a check that the egress rule still removes the header. Run the heavier tests, such as marker searches across all stores and the concurrency tests under load, on a regular schedule, for example every night or every week, and send failures to the owning team. Keep the exercises with human attackers for the times when you add major features or change infrastructure.

The marker trick

The leak test deserves special attention. It uses a “canary” marker, a unique value such as a random string that cannot be confused with real data. You attach it to a test request and then search everything you can reach: gateway logs, application logs, tracing storage, queue contents, and the traffic that arrives at a stand-in for an outside server. Wherever the marker appears, a path exists. Compare the results with your registry. Any place that is not allowed is a finding. Run this regularly, not just once, because every deployment may change the paths.

Practice real incidents

At least once or twice a year, run a short exercise in which one team plays an attacker who tries to use baggage to gain a premium feature, leak data to a partner, or cause an overload. The second team defends using only monitoring and runbooks. These exercises reveal gaps in dashboards and in understanding that automated tests cannot.

Defenses need eyes. Monitoring tells you when they are tested, when they fail, and when someone is probing them.

What to measure

Notice that most of these are counts and shapes, not values. Monitoring should never store the baggage values themselves, because that would copy the very data you are trying to protect into another system.

A simple dashboard

One page is enough to start. At the top, put one big number: baggage headers seen on traffic leaving to outside hosts, which should be zero. Below that, show a small chart of requests stripped or rejected at the edge, a chart of the 50th and 99th percentile of baggage size against the limit, and a table of unknown keys seen in the last day. Add one chart for the number of distinct values in each copied telemetry attribute. When someone asks how safe your baggage use is, this page answers in half a minute.

Alerts worth having

• Any baggage header seen on traffic leaving to outside hosts.
• A sudden rise in stripped or rejected baggage at the edge.
• The 99th percentile of baggage size creeping toward the limit.
• An unknown key appearing in more than a handful of requests.
• A copied attribute whose number of distinct values grows faster than expected.

When something goes wrong

Principles become real when mapped to the building blocks you actually run. Here is a map for a typical AWS-style environment. Always check current product features before relying on them.

Roll out in a safe order

After all these risks, a fair question arises: is baggage worth using at all?

The alternatives, side by side

How to decide in a meeting

When a team proposes a new baggage entry, run through a quick decision. If the value is secret or personal, the answer is no. If a decision depends on it, use a token or a lookup. If it must reach a partner, use an explicit field. If it is a small hint with a fixed set of values and has an owner, accept it and add it to the registry. This takes five minutes, and it stops the slow growth of risky entries that are only visible years later.

Trade-offs to discuss with your team

• Convenience versus control. Open, automatic baggage is the easiest to use and the hardest to control. A registry and helper add friction and add safety.
• Reach versus exposure. The wider the entries travel, the more services benefit and the more places can leak them.
• Hints versus certainty. Baggage is cheap because it is unverified. Verification costs effort, and belongs in other tools.
• One central policy versus team freedom. A central registry slows new keys down a little and prevents the slow growth of unreviewed ones.

Habits that work for many teams, and the traps that catch many teams.

Patterns that work

Anti-patterns to avoid

A short list of habits to adopt, and the slips that appear in review after review.

Best practices

• Treat baggage as untrusted input at every boundary. It is a postcard written by strangers.
• Keep it tiny. A few short, coarse entries with fixed sets of values.
• Never carry secrets or personal data. Use opaque references and trusted lookups.
• Strip at the edge and filter at the exit. The two boundaries matter most.
• Make decisions from verified facts and use baggage only for hints.
• Maintain a registry with owners, purposes, and review dates.
• Copy to telemetry with an allow list and never copy to metrics unless the values form a small fixed set.
• Test and monitor continuously. Marker tests, malformed input tests, size distributions, and egress counters.

Common mistakes and quick fixes

The guidance in this guide matches what standards bodies, tool makers, and infrastructure defaults already tell us, plus two clearly labeled made-up stories.

Short answers to the questions that come up most often.