Before we meet the Composite Propagator, we need to understand the problem it solves. It starts with how modern software is built.

Years ago, many applications were a single large program, often called a monolith. When a user clicked a button, one program handled everything: it checked the login, read the database, and built the page. If something went wrong, an engineer could open one set of logs and follow the story from start to finish.

Today, many companies split their software into many small programs called services, which talk to each other over the network. This style is called microservices. One click on a shopping website might touch a login service, a product service, a pricing service, a stock service, a payment service and a recommendation service. Each one runs on its own machines, written by its own team, and often in its own programming language.

This design has big benefits. Teams can work independently, and busy parts of the system can be scaled up without touching the rest. But it creates a new difficulty: when the website is slow, which of the six services is to blame? Each service sees only its own small piece of the story. Nobody sees the whole journey.

What observability needs

Observability is the ability to understand what is happening inside a system by looking at the information it sends out. One of the most useful kinds of information for distributed systems is the trace, which is a record of the full journey of one request through all the services it touched. To build a trace, every service must agree on one thing: the identity of the journey. If service A and service B both handle the same user request but label it with different identities, the monitoring tool will show two unrelated stories instead of one.

That agreement is not automatic. It has to be passed from service to service, riding along with the request itself, usually inside the invisible header lines of an internet message. The part of OpenTelemetry that does this passing is called a propagator. And when a system needs to pass the identity in more than one format at the same time, OpenTelemetry offers the Composite Propagator.

Three small words appear everywhere in tracing. Learn them once and the rest of this guide becomes easy.

Span

A span is a record of one piece of work, such as “the payment service charged the card” or “the database answered a query.” A span has a name, a start time, an end time, and some extra details called attributes. Think of a span as one line in a diary that says what happened and how long it took.

Trace

A trace is a collection of spans that all belong to the same request. If a customer’s checkout touched six services, the trace holds the spans from all six, arranged like a family tree. The first span is the parent, the work it triggered creates child spans, and those can have children of their own. The whole tree shows exactly where time was spent.

Trace identifier and span identifier

Every trace has a unique trace ID, a long random number. Every span inside it has its own span ID. When a service calls another service, it tells the next service two things: “we are in trace number such-and-such” and “the span that called you is span number so-and-so.” The second service then creates its own span as a child of the caller’s span. That is how the family tree is built across the network.

Context

In OpenTelemetry, context is a small bag of information that travels along with a piece of work. Inside one program, the context is carried automatically, often by the programming language’s runtime. The bag holds, among other things, the identity of the current span. Think of it as the badge that a visitor wears while walking around a building. Every room can look at the badge and know who the visitor is.

A second kind of information can ride in the same bag: baggage. Baggage is a set of simple key and value pairs, such as “customer tier equals gold” or “region equals europe,” that you want every downstream service to see. We will return to baggage in a later chapter.

Inside one program, the context travels easily. The hard part is when the work crosses the network. This chapter explains how that crossing works.

When service A calls service B, the call is sent as a message over the network. The two services are different programs, possibly on different continents. They do not share memory, so the context bag in service A simply does not exist in service B. For the trace to continue, the information in the bag must be written into the message, sent along, and then read out again at the other side.

This process of carrying the context across a boundary is called context propagation. It has two halves, and the OpenTelemetry names for them are worth remembering.

• Inject means taking the current context and writing it into the outgoing message. The sender does this just before the message leaves.
• Extract means reading the context back out of the incoming message. The receiver does this as soon as the message arrives.

The thing that holds the information while it travels is called a carrier. For a web call, the carrier is the set of HTTP headers. For a message queue, the carrier is the message’s metadata fields. For a remote procedure call, the carrier is the call’s metadata. Whatever the transport, the carrier is simply a place where small named text values can be stored.

sequenceDiagram
  participant A as Service A
  participant B as Service B
  participant C as Service C
  Note over A: Span A is active
  A->>B: Request with trace headers injected
  Note over B: Extract headers, start Span B as child of Span A
  B->>C: Request with trace headers injected
  Note over C: Extract headers, start Span C as child of Span B
  C-->>B: Response
  B-->>A: Response
    

Follow the figure from top to bottom. Service A has an active span. Before calling service B, it injects the trace information into the request headers. Service B extracts that information as soon as the request arrives, and starts its own span as a child of A’s span. When B calls C, the same dance repeats. In the end, all three spans share the same trace ID and form one connected tree.

What happens when propagation fails

If service B does not extract the headers, or if it cannot understand them, it behaves as though the request just appeared out of nowhere. It starts a brand new trace with a brand new trace ID. Now the monitoring tool shows two separate traces: one that ends at A, and one that starts at B. This is called a broken trace or an orphan. Broken traces are among the most common and most frustrating problems in distributed monitoring, and the Composite Propagator exists to prevent a major class of them.

Now we meet the star of the supporting cast. A propagator is the component that actually performs the inject and extract steps.

A propagator is a small object with a very focused job. It knows one specific format for writing context into a carrier, and the same format for reading it back. It has three abilities, which come directly from the OpenTelemetry specification.

Getters and setters

A propagator has to work with many kinds of carriers: web headers, queue messages, remote call metadata and more. It cannot know the details of each one. So OpenTelemetry gives it two tiny helpers. A setter knows how to write one named value into this particular kind of carrier. A getter knows how to read one named value from it, and how to list the available names. The propagator only talks to the getter and setter, which is why the same propagator works for web calls, queues and anything else.

One propagator, one format

A simple propagator speaks only one format. The propagator for the W3C Trace Context standard writes and reads the headers defined by that standard. The propagator for B3, an older format from the Zipkin tracing project, writes and reads B3 headers. Each one is a specialist. If your whole company uses one format, you need only one propagator, and life is simple.

But real companies are rarely that tidy. Some services were built five years ago and emit one format. Some were built last year and emit another. Some are bought products that you cannot change at all. When a request must pass through all of them, a single specialist is not enough. That is the gap the Composite Propagator fills, and we will meet it properly in Chapter 6, after we look at the formats themselves.

Several formats exist for writing trace context into messages. Knowing the main ones helps you understand why a composite is so often needed.

Why so many?

Distributed tracing grew up in many places at once. Google, Twitter, Uber, Amazon and others each built their own tools before there was any standard. Each tool invented its own header names and value layouts. Companies adopted whichever tool was available when they needed it, and then lived with it for years. Later, the industry agreed on the W3C Trace Context standard, and OpenTelemetry chose it as its default. But agreeing on a new standard does not instantly change the thousands of services already running.

A quick look at the default format

The W3C traceparent header is a single line made of four parts separated by dashes: a version number, the 32-character trace ID, the 16-character ID of the parent span, and a two-character flags field. The flags field includes a “sampled” bit that tells the downstream services whether this trace is being recorded. The companion tracestate header lets different vendors add their own small notes without breaking each other. Because the standard is open and simple, many languages, frameworks, proxies and cloud services understand it directly.

Now we can give a clear definition and unpack it piece by piece.

A Composite Propagator is a propagator that is built out of other propagators. It does not know any trace format by itself. Instead, it holds a list of ordinary propagators, such as one for W3C Trace Context, one for W3C Baggage and one for B3, and it presents them to the rest of the system as if they were a single propagator. When asked to inject, it asks every propagator in its list to inject. When asked to extract, it asks every propagator in its list to extract.

The OpenTelemetry specification states the idea in simple terms: an implementation must offer a way to group several propagators, which may come from different cross-cutting concerns, so that they can be used together as one entity. The word “composite” comes from a classic software design idea, where a group of objects is treated exactly like a single object.

Why this is useful

The rest of your instrumentation, such as the web framework plugin or the queue client plugin, only knows how to talk to one global propagator. It does not know how to juggle a list. The Composite Propagator solves this by wrapping the list in a single object. The plugin calls inject once, and the composite fans that call out to every member. Nothing else in your program has to change.

What it can combine

There are two main reasons to combine propagators, and they are different in nature.

Both reasons use the same tool. The Composite Propagator does not care whether its members carry different kinds of information or the same information in different clothing.

The idea is simple, and so is the machinery. Let us open it up and watch inject, extract and fields in action.

graph LR
  A["Active Context: trace identity and baggage"] --> B["Composite Propagator"]
  B --> C["W3C Trace Context Propagator"]
  B --> D["W3C Baggage Propagator"]
  B --> E["B3 Propagator"]
  C --> F["Carrier: traceparent and tracestate headers"]
  D --> F
  E --> F
  F --> G["Outgoing Request"]
    

Inject: one call, many writes

On the sending side, the composite receives the current context, the carrier and the setter. It then loops over its members in order and asks each one to inject. Each member writes its own header or headers into the same carrier. When the loop finishes, the carrier holds the trace information in every format on the list. The outgoing request therefore carries, for example, the W3C headers and the B3 header side by side.

Extract: one call, many reads

On the receiving side, the composite receives the incoming carrier, the getter and a starting context. It loops over its members in order. Each member looks in the carrier for the headers of its own format. If it finds valid ones, it creates a new context that includes what it found and returns it. If it finds nothing, or finds something broken, it returns the context it was given, unchanged. The composite hands the result of one member to the next member as its starting context. After the loop, the final context is returned to the caller.

Fields: the combined list

The third ability, fields, is also combined. The composite returns the union of the field names of all its members, with duplicates removed. If one member uses traceparent and tracestate, another uses baggage, and another uses b3, the composite reports all four names. Tools that need to know which carrier entries are “propagation entries,” for example to clear stale ones before reusing a message, rely on this combined list.

The order of the list is not just a detail. It decides what happens when two formats disagree.

Imagine a request that arrives carrying two sets of trace headers, and the two sets describe different traces. This can happen, for example, when one proxy added an X-Ray header while an application behind it had already added W3C headers. What should the receiving service believe?

The specification does not give the composite a clever way to decide. It simply runs the members in order. Because each extract step starts from the context returned by the previous step, a later member that finds valid data will typically overwrite what an earlier member found. In practice, this means that the last member in the list that finds valid trace information wins. Implementations differ in small details, so check your SDK’s documentation, but this is the common behavior.

How to choose the order

• Put your preferred, most trusted format last for extraction. In many modern setups, that is the W3C Trace Context format, which is the standard.
• Remember that injection order barely matters. All members write into different headers, so the order of writing does not change what is sent. The order only matters for reading.
• Be consistent across services. If service A prefers format X and service B prefers format Y, then in a conflict they might continue different traces. Agree on one order and publish it as a company rule.
• Avoid unnecessary members. Every extra member adds work and creates more chances for conflict. Add only the formats that you really meet in your environment.

The best news about the Composite Propagator is that it is usually easy to set up. Often you can do it with a single setting and no code at all.

The environment variable way

OpenTelemetry defines a standard environment variable called OTEL_PROPAGATORS. You set it to a comma-separated list of format names, and the SDK builds a composite propagator from them automatically. The names defined by the specification include tracecontext, baggage, b3, b3multi, jaeger, xray, ottrace and none. Not every SDK supports every name, and some of them need an extra package to be installed.

If you do not set the variable, SDKs normally default to a list of tracecontext and baggage, which is itself a composite of two propagators. Setting the variable to none turns propagation off completely, which is almost never what you want in production.

The setup-in-code way

If you prefer to configure the SDK in code, or if you need a custom propagator, every language lets you build the composite yourself and register it as the global propagator. The pattern is always the same in spirit: create the individual propagators, hand the list to the composite builder, and register the result with the OpenTelemetry API. After that, all instrumentation in the process uses it. The details of the method names differ between languages, so consult the official documentation of your SDK.

Where the configuration must happen

The propagator must be registered before any instrumentation starts handling requests, ideally during application start-up. If a web framework plugin was initialized earlier and cached the old global propagator, it might keep using the old one. Many beginners lose hours to this ordering problem, so make configuration the very first step of start-up.

Let us follow one request through a company where old and new services live side by side, and see the composite at work at every handoff.

graph LR
  U["User Mobile App"] -->|"W3C headers"| G["API Gateway with composite: W3C, Baggage, B3"]
  G -->|"W3C and B3 headers"| L["Legacy Billing Service reads B3 only"]
  G -->|"W3C and B3 headers"| N["New Orders Service reads W3C only"]
  L -->|"B3 header"| D["Legacy Database Proxy"]
  N -->|"W3C headers"| P["Payments Service with composite: W3C, Baggage, B3"]
  P -->|"W3C and B3 headers"| L
    

In the figure, the mobile app speaks the modern W3C format. The API gateway has a composite with three members, so it understands the incoming W3C headers and it also writes B3 headers when calling the old billing service. The legacy billing service reads B3 only, which is fine, because it receives B3. The new orders service reads W3C only, which is also fine, because it receives W3C. Later, the payments service calls the legacy billing service again, and its own composite writes both formats.

The old services never learned anything new. The new services never had to carry the burden of the old formats. The only places that needed the composite were the points where the two worlds meet.

The life of a trace across handoffs

• Start. The first service that receives no usable headers becomes the root. It creates a new trace ID.
• Each hop. A service extracts what it can understand, creates a child span, and injects headers in all configured formats before calling the next service.
• Translation. When the formats differ, the composite effectively translates the identity from one dialect into another. The trace ID stays the same, only the clothing changes.
• End. Each service sends its spans to the monitoring backend, where they are joined by the shared trace ID into one tree.

Here are the situations where engineers most often reach for a Composite Propagator. The scenarios are illustrative examples meant to build intuition, not descriptions of any particular company’s internal systems.

Migration is the number one reason teams learn about the Composite Propagator. Here is a safe, calm way to move a whole company from an older format to the W3C standard without breaking a single trace.

The danger in any format change is the “big bang.” If you switch every service to the new format at the same moment, you need perfect coordination, and anything that goes wrong breaks everything. If you switch services one by one with no overlap, then every service that has switched cannot talk tracing to the services that have not, and traces break at the seams. The composite lets you replace the big bang with a gentle, three-phase slide.

How to know when you are done

The hardest question in a migration is “is anyone still using the old format?” You can answer it with data. Add a small measurement in a shared library or in your gateway that counts how many incoming requests carry only the old headers and none of the new ones. When the count falls to zero for a long enough time, you can retire the old format. Without this kind of evidence, teams often keep old formats alive for years just because nobody dares to remove them.

So far we focused on trace identity. But the composite also carries a second kind of information, which brings both power and responsibility.

Baggage is a set of simple key and value pairs that travel with the request across services. For example, you might set a key named customer.tier with the value gold at the front door of your system. Every service downstream, no matter how deep, can read that value from the context without anyone passing it as an argument through every function call.

The W3C Baggage format sends these pairs in a header named baggage, as a comma-separated list. It is a separate standard from trace context, and in OpenTelemetry it has its own propagator. That is why the default list is two members: one for trace identity and one for baggage. The composite carries both in the same pass.

What baggage is not

Baggage is not automatically attached to spans or metrics. The fact that a value is in the baggage means it is available to code that looks at the context. If you want a baggage value to appear as an attribute on spans, you have to add a step that copies it, for example a span processor or an explicit line in your instrumentation. Many people expect the copy to happen automatically and are surprised when it does not.

Why baggage deserves extra care

• It goes everywhere. Baggage is sent on every outgoing call that uses the propagator, including calls to services owned by other companies. Anything you put in it can be seen by every recipient.
• It uses network space. Each item adds bytes to every request on every hop. The W3C standard suggests limits on the number of entries and total size, and servers and proxies may reject headers that are too large.
• It is easy to forge. Anyone who can send a request to your public edge can send a baggage header of their own choosing. Never trust baggage values for security decisions without checking them.

Choosing whether to include baggage at all

If you do not use baggage, you can leave the baggage member out of the list. Many teams keep it because the default includes it and because it may be used by libraries without their knowledge. If you keep it, consider stripping unknown baggage at your public edge, so that outside callers cannot inject values into your internal system.

A design pattern is a proven way of solving a problem that keeps coming back. These are the patterns teams use most often with composite propagators.

The custom propagator pattern in more detail

Sometimes the format you need does not exist as a ready-made propagator. Maybe your company built an in-house tracing tool a decade ago and still has services that depend on it. OpenTelemetry lets you write your own propagator by implementing the same three abilities: inject, extract and fields. Once written, you register it as a member of the composite, and the framework instrumentation uses it without any special treatment.

The responsibilities of a custom propagator are narrow. When extracting, it must never throw an error on bad input, because incoming headers come from the outside world and can contain anything. It must return the unchanged context when it finds nothing valid. When injecting, it must only write the fields it announced in its fields list. If you follow these rules, your custom member will sit comfortably beside the standard ones.

The edge sanitizing pattern in more detail

Anyone on the internet can send your public endpoint a request with a trace header of their own making. If your gateway blindly continues that trace, outsiders can influence your traces: they can mark traces as “sampled” to make you record more data than you planned, or send huge baggage to eat your resources. A cautious approach is for the gateway to ignore incoming trace headers from untrusted sources and start a fresh trace, optionally recording the incoming identity as a link on the new trace. Internal services, which are trusted, then use the composite normally.

The Composite Propagator is a very helpful tool, but it is not free. An honest look at both sides helps you use it wisely.

The central trade-off: compatibility versus simplicity

Each format you add makes your system understandable to more neighbors, but each one also costs a little: more bytes on every call, more code in every service, more cases to test. The best composite is the smallest composite that still keeps your traces whole. A common rule of thumb is to allow only formats that you can name a concrete service or product for. If you cannot point to a real user of a format, remove it.

Composite versus other approaches

When not to use a composite

• When every service you talk to already speaks the W3C standard, because extra members only add overhead.
• When a legacy service does not forward headers at all. A composite on your side cannot save a trace that the other side drops. In that case, you might link traces instead.
• When you need to keep a very small message size, such as for tiny messages on constrained networks. Carefully consider whether the extra headers are worth their cost.

These mistakes appear again and again in real systems. Each one looks harmless, and each one can silently break traces.

These habits keep your composite small, predictable and easy to debug. Think of them as a checklist you run through whenever you touch propagation settings.

A short pre-launch checklist

• Does every service that talks to a neighbor share at least one format with that neighbor?
• Is the list the same in every environment, or are differences intended and documented?
• Is the order identical across services?
• Is the propagator registered before any instrumentation starts?
• Has the public edge been configured to handle untrusted headers safely?
• Are there tests that send a request through at least one old-format service and confirm the trace stays connected?

The idea is the same everywhere, but each language and tool has its own way of naming and building it. Knowing the general shape helps you find the right page of the documentation quickly.

OpenTelemetry has official SDKs for many programming languages. They all follow the same specification, so a composite behaves the same way in all of them: write every member’s headers on the way out, read every member’s headers on the way in, and report the combined list of fields. What differs is the spelling of the names and the place where you plug the composite in.

What stays the same

• The composite has no format of its own. It only forwards calls to its members.
• Extraction runs members in the order given, so later members can override earlier ones.
• The fields list is the combined set of all members’ fields.
• The composite never throws on malformed headers. Bad input is simply ignored.

What differs

• Which formats come built in. The W3C formats are almost always included. B3, Jaeger, X-Ray and others are often add-on packages, and their names and maintenance status vary between languages.
• How automatically the list is built. Some SDKs read the environment variable by default. Others need you to opt in to a configuration helper.
• Global versus per-component settings. Most SDKs use a single global propagator. A few libraries allow a per-client override, which can be handy for one special outgoing call but easy to forget about later.

Several other OpenTelemetry ideas sit close to propagation and are often confused with it. Putting them side by side removes the confusion.

In-band and out-of-band data

There are two very different roads that telemetry takes. Propagation travels in-band: it rides along inside the very requests and messages that your services exchange. Exporting travels out-of-band: each service separately sends its recorded spans to a collector or backend over its own connection. The two meet at the monitoring backend, which uses the shared trace ID that propagation distributed to join the spans that exporting delivered.

graph TD
  A["Service A"] -->|"in-band: request with propagated headers"| B["Service B"]
  A -->|"out-of-band: exports spans"| C["Collector"]
  B -->|"out-of-band: exports spans"| C
  C --> D["Tracing Backend"]
  D --> E["One joined trace using the shared trace ID"]
    

This picture explains why a propagation problem looks the way it does. The spans are still recorded and exported correctly, so the backend is full of data, but the shared identity was lost along the way, so the backend cannot join them. The data is there. The thread is not.

Comparing the neighbors

Sampling and propagation: a special relationship

Recording every trace in a busy system is too expensive, so systems record only a share of them. The decision is usually made once, at the start of the trace, by a sampler in the first service. All other services should follow the same decision, otherwise a trace would be recorded in some services and missing in others. The decision travels with the propagated context, in the sampled flag of the W3C trace context or the equivalent field in other formats.

This has a consequence for composites. When a composite translates between formats, the sampled decision must be translated too. Well-written propagators do this correctly. But if a legacy format lacks a sampling field, or a legacy service ignores it, then the sampling decision may be lost, and a downstream service may decide differently. This is another reason to test end-to-end paths that cross format boundaries.

Propagation headers look harmless, but they travel through every system your request touches. A little care here prevents leaks, abuse and surprise bills.

Security

Trace headers are input from the outside world, and input from the outside world should never be fully trusted. There are a few specific risks to know about.

• Forced sampling. The W3C trace flags include a “sampled” bit. An outsider who sets this bit on every request might make your system record many more traces than you planned, driving up your monitoring costs. Your public edge should decide for itself whether to honor the incoming sampling decision.
• Trace linking and confusion. An attacker can send a request with a chosen trace ID, trying to mix their requests into a real trace or to confuse investigations. Starting a fresh trace for untrusted callers, and recording the incoming identity as a link only, keeps your data clean.
• Header flooding. Extremely large baggage or oversized headers can be used to waste memory and bandwidth. Set strict limits at the edge and let your proxies reject oversized headers.
• Malformed input. A good propagator must ignore bad headers gracefully. This is why custom propagators should never throw errors when parsing, and why you should keep your propagation libraries up to date.
• Information disclosure. If your internal services send trace headers or baggage to outside partners, those partners learn identifiers from your system. Consider stripping them on calls that leave your organization.

Privacy

The trace ID and span ID are random numbers and carry no personal data. Baggage, however, is free-form text. If a developer puts an email address, an account number or a user name into baggage, it spreads to every service, every proxy log and every partner the request reaches. The safest rule is to keep baggage free from personal data and to review every key before it is allowed.

Cost

The cost of a composite propagator is small per call, but calls add up. Every member writes extra header bytes, and those bytes travel on every request and every message.

As a simple example, imagine a W3C trace parent header of about 55 characters, a B3 header of about 50 characters, and a small baggage header of 100 characters. Together that is about 200 bytes extra per call. At ten thousand calls per second, that is about two megabytes per second of header overhead, which is small but not zero. If the list grows to six formats and baggage grows to a kilobyte, the overhead can become a measurable part of network usage, and you may hit header size limits in proxies and servers.

Web calls are the easy case. Many real systems also pass work through queues, topics and schedulers. The composite works there too, but there are extra points to watch.

When a service puts a message on a queue, the work is picked up by a consumer later, maybe seconds or hours afterward, maybe on a different machine. The context cannot travel through the network connection, because there is none. Instead, the producer injects the context into the message’s metadata, and the consumer extracts it when the message is read. The carrier is the set of message headers or message attributes, depending on the queue product.

Things that differ from web calls

• Limited metadata space. Some queue products limit how many separate attributes or headers a message can carry. For example, some cloud queue services allow only a small, fixed number of message attributes, such as ten, and your own application attributes share that budget. Since each propagation format may consume one or more attributes, a long composite can use up a large part of the budget. Check the limits of your queue before adding members.
• Time gaps. The consumer may run long after the producer finished. The consumer’s span is often better described as a link to the producer’s span rather than a direct child, because they are not part of the same live call.
• Many consumers. One message may fan out to many consumers. Each of them extracts the same context and starts its own span, which creates a wide tree.
• Batching. A consumer that reads a batch of messages may handle messages from many different traces in one go. It should extract from each message individually and link to each producer.
• Retries and dead-letter queues. A message may be delivered more than once. Each delivery carries the same original context, which is usually what you want.

Carriers that only allow certain characters

Some carriers restrict the characters that may appear in names and values, or treat header names as case-insensitive. A well-written getter and setter hide these differences from the propagator. If you ever write your own getter or setter for a new kind of carrier, remember to handle case-insensitive lookups and to return an empty result rather than failing when a key is missing.

A broken propagator rarely causes an error. It causes missing connections, which you only notice when you look for them. That is why deliberate testing is so valuable.

Test the composite as a unit

Build the composite exactly as production does, then run two simple checks in a test. First, inject a known context into an empty carrier and confirm that the carrier now holds the headers of every format on the list. Second, extract from a carrier that contains headers of just one format and confirm that the resulting context holds the expected trace ID and span ID. Repeat for each format. These tests are fast and catch typos in the configuration, a missing package and wrong ordering.

Test a conflict on purpose

Create a carrier with two formats that disagree, and check which one wins. Write down the result as a test. If anyone later changes the order of the list, the test will fail and point out the change in behavior, which prevents silent surprises.

Test a malformed header

Feed the composite headers that are empty, truncated, have the wrong length, or contain unexpected characters. The correct behavior is that the composite never throws an error, ignores the bad input, and either falls back to another format or leaves the context empty so a new trace begins.

Test across real services

Unit tests prove the propagator works. Only an end-to-end test proves that the real services, proxies and queues pass the headers along. In a staging environment, send a request with a recognizable trace ID through every kind of path in your system: web to web, web to queue to worker, gateway to legacy service. Then search your tracing backend for that trace ID and confirm that spans from every service appear in one tree. If a hop is missing, you have found a break before your customers did.

Sooner or later you will open a trace and find that it stops halfway, or that two traces should have been one. This chapter gives you a calm way to find the cause.

Signs of a propagation problem

• Many traces consist of a single span from one service, with no children.
• A service shows up as the root of many traces even though it is never the entry point.
• A request that clearly crosses a boundary appears as two unconnected traces, one on each side.
• Traces break only on certain paths, such as the path through one particular proxy or queue.

A troubleshooting walk-through

Suppose the trace breaks between service A and service B. Work from the sender to the receiver, one hop at a time.

Measuring propagation health over time

You can turn troubleshooting into monitoring. Many tracing backends let you count how many traces have only one span, or how many spans have no parent even though their service is never an entry point. A sudden rise in these numbers after a deployment is a strong hint that a propagation change broke something. Add this check to your release routine, and watch it for a day after any change to the propagator list.

Short, direct answers to the questions beginners ask most often.

You started with an interpreter at an international meeting and ended with a full picture of how a Composite Propagator keeps traces whole across old and new systems. Here is everything that matters in one place.

A distributed trace is only complete if every service passes the identity of the journey to the next one. That passing is done by propagators, each of which speaks one format. Real companies speak many formats at once, because systems grow over years. The Composite Propagator wraps several propagators into a single one, writing every format on the way out and reading every format on the way in. Used with care, with a small list, a consistent order, early configuration and a thoughtful public edge, it keeps your traces connected and your migrations calm.