Full lesson
Explore the full explanation, examples, and visuals at your own pace.
Part 1
The trace ID rides inside the request itself. When a user adds something to the cart, Frontend calls Product Catalog with GET /product, and that call carries the trace ID and parent ID. Without them, Product Catalog would start an unrelated trace, and the link back to its parent span would be lost. With them, both services join one trace.
Two separate ideas
Context propagation is really two ideas. Context is the trace ID and span ID that let one signal be correlated with another. Propagation is the mechanism that serializes that context and sends it between services. Usually, instrumentation libraries handle this for you, transparently.
- Context: trace ID and span ID
- Propagation: moves context between services
- Usually automatic via instrumentation libraries
W3C traceparent header
The traceparent header packs context into four dashes-separated fields. First, the version, 00. Next, the trace ID, which every span in this request shares. Then the parent ID, here the Frontend's span. Last, trace flags, 01. This is the format OpenTelemetry's default propagator uses, defined by W3C TraceContext.
# format
<version>-<trace-id>-<parent-id>-<trace-flags>
# Frontend -> Product Catalog
traceparent: 00-a0892f3577b34da6a3ce929d0e0e4736-f03067aa0ba902b7-01Inject on send, extract on receive
The carrier is whatever travels with the request. Here, that's HTTP headers. Frontend injects its context, writing the traceparent header. Product Catalog extracts it, reads the header back, and reuses the same trace ID. Then it sets f03067aa0ba902b7 as the parent of its new span, so the two spans join one trace.
Manual propagation (Python, illustrative)
General knowledgeYou'll rarely write this, because instrumentation libraries usually handle it. If none exists, the Propagators API fills the gap. On the Frontend, inject writes the traceparent header into a headers dictionary. On Product Catalog, extract rebuilds the context from the request headers, and the new span starts inside it.
from opentelemetry.propagate import inject, extract
# Frontend: before calling GET /product
headers = {}
inject(headers) # adds traceparent
# Product Catalog: on incoming request
ctx = extract(request.headers)
with tracer.start_as_current_span("GET /product", context=ctx):
...Same endpoint, different callers
Because context travels with each call, Jaeger can show both requests as spans of one trace. It also lets metrics split by caller. All callers average 300 milliseconds, but cart/add is 130, while checkout is 1703. The overall average hides that slow checkout path.
Chart values
| Caller path | Avg response (ms) |
|---|---|
| All callers | 300 |
| cart/add > product | 130 |
| checkout > product | 1703 |
Baggage: extra key-values riding alongside
Baggage is a key-value store that travels next to context. Frontend sets a clientId at the start of the request, and it's propagated to Product Catalog. But it isn't a span attribute yet. You have to read it and copy it onto the span, or let a Baggage Span Processor do that.
What belongs in baggage?
Use baggage for IDs known only at the start of a request, like user or product IDs. They let you ask which users see the slowest database calls. Never put secrets in it. Headers are visible, and baggage can reach third-party APIs.
- Good: account, user, product IDs
- Avoid: credentials, API keys, PII
- Sent in plain HTTP headers
Trust boundaries cut both ways
Context crossing a boundary is a risk in both directions. Incoming, an outside caller can send a forged traceparent header, so you may want to ignore or sanitize it at the edge. Outgoing, internal IDs and baggage can reveal your architecture, so configure propagators not to send them to third-party APIs.
Context rides in request headers: inject on send, extract on receive.
Context rides in request headers: inject on send, extract on receive. Let instrumentation handle that for you, and treat any headers crossing your boundary as untrusted.
