Before learning the idea, let us feel the problem it solves.

One click, many programs

Imagine you tap “Place order” in a food delivery app. Behind that single tap, many separate programs may do work: a gateway receives the request, an order service records it, a payment service charges your card, and a notification service sends you a message. These programs may run on different machines, in different countries, and may be written in different languages.

Each program can easily record its own timing. But how do we know that the payment record at 7:02 pm belongs to the same order as the gateway record at 7:02 pm? Thousands of other customers are ordering at the same moment. Matching records by time alone would be like trying to find your luggage at a huge airport by guessing.

The need for a shared identity

What we need is a label that is created at the start of the journey and carried along to every step. Every step must stamp that same label on its own records. We also need each step to have its own identity, so we can tell step three from step four. And we need a few small extra facts, such as whether the journey is being recorded. Together, these facts make up the span context.

First the short answer, then the pieces one by one.

Let us first recall two words. A trace is the complete journey of one request through your system. A span is one timed step inside that journey, such as “charge the card.” A span has many details: a name, a start time, an end time, attributes, events and a status.

A span context is the small part of a span that identifies it and lets it be connected to other spans. It is the part that can safely travel from one program to another. It is immutable, which means it cannot be changed once it is created. It is also serializable, which means it can be turned into a short piece of text and sent across the network.

What is inside a span context?

A span context has a small number of fields. Each one has a clear job.

flowchart TD
    SPAN["Span"] --> DET["Details for this process only"]
    SPAN --> SC["Span Context"]
    DET --> D1["Name"]
    DET --> D2["Start and end time"]
    DET --> D3["Attributes and events"]
    DET --> D4["Status"]
    SC --> F1["Trace ID"]
    SC --> F2["Span ID"]
    SC --> F3["Trace Flags"]
    SC --> F4["Trace State"]
    SC --> F5["Is Remote"]
    

Each field is small, but each has a careful design behind it.

Trace ID: the shared journey number

The trace ID is a random 128-bit number. To get a feel for how big that is, there are about 340 undecillion possible values, which is a number with 39 digits. Because the values are chosen at random, the chance that two different journeys ever receive the same trace ID is so small that, for real systems, you can safely ignore it. No central office is needed to hand out IDs. Every program can create one on its own.

A trace ID made only of zeros is not allowed. It is treated as invalid, a bit like an empty passport.

Span ID: the step number

The span ID is a random 64-bit number. It only needs to be unique inside its own trace, because it is always used together with the trace ID. As with the trace ID, all zeros means invalid. When a new span is created, it receives a fresh span ID. When the next service calls onward, the caller’s span ID becomes the parent that the next span points to.

Trace flags: the small switches

Trace flags are stored in a single byte. The most important switch is the sampled flag. When it is on, it says “this trace is being kept, so please record your part too.” When it is off, it says “this trace is not being kept, so you may skip detailed recording.” This one bit lets every service in a journey agree on a decision made at the start, without needing to talk to each other.

Newer versions of the W3C standard also define a flag that says the trace ID was generated randomly in a way that other systems can trust for sampling decisions. Support for this varies, so check what your tools support.

Trace state: vendor notes

The trace state is a short, ordered list of key and value pairs. It exists so that different vendors and systems can pass their own small pieces of information along the journey without breaking the standard fields. For example, a sampling system might record the probability it used. The list is limited in size, and systems must pass along entries they do not understand rather than throwing them away.

Is remote: where did this come from?

This field is not sent over the network. It is set by the receiver. When a service extracts a span context from an incoming request, it marks it as remote. When the context was created inside the same program, it is not remote. This helps systems know whether a parent span lives in this process or somewhere else, which is useful for deciding things like the kind of span to create.

Beginners often use these two words as if they meant the same thing. They do not.

This is a clever design. Spans can be large and rich, but only the tiny identity card needs to cross network borders. That keeps request headers small and lets each service keep its detailed story to itself, sending it later to the backend.

Where do these IDs come from, and what happens when a child span is created?

The root span: starting a new journey

When a request arrives and there is no incoming context, the SDK creates a root span. It asks an ID generator for a brand new trace ID and a brand new span ID. It also asks the sampler whether to record this trace, and sets the sampled flag based on the answer.

Child spans: continuing the journey

When code starts a new span while another span is active, the SDK looks at the current context to find the parent. The child then follows a simple set of rules.

flowchart TD
    R["Root span: Place order"] -->|"Same Trace ID. New Span ID."| C1["Child span: Check stock"]
    R -->|"Same Trace ID. New Span ID."| C2["Child span: Charge card"]
    C2 -->|"Same Trace ID. New Span ID."| G1["Grandchild span: Call card provider"]
    

This is the reason the span context exists.

A span context only lives inside one program’s memory. To keep a trace whole across the network, it must be written into the outgoing request and read back by the receiver. Writing it is called inject. Reading it is called extract. The tool that does this work is a propagator.

sequenceDiagram
    participant G as API Gateway
    participant O as Order Service
    participant Q as Message Queue
    participant E as Email Worker
    G->>G: Create root span and span context
    G->>O: Inject span context into request header
    O->>O: Extract span context and mark it remote
    O->>O: Create child span with same trace ID and new span ID
    O->>Q: Inject span context into message headers
    Q->>E: Deliver message with headers
    E->>E: Extract span context and create consumer span
    

The standard format: W3C Trace Context

By default, OpenTelemetry uses the W3C Trace Context standard. It defines a request header named traceparent. It has four parts separated by dashes: a version, the trace ID, the span ID of the caller, and the flags. An example value looks like this:

A second header, tracestate, carries the trace state. Because both headers follow an open standard, a Java service can call a Go service, which calls a Python service, and the trace stays whole. Other formats are also supported through propagator plugins, such as B3 from the Zipkin world, the Jaeger format, and the AWS X-Ray header. These help during migrations.

Messages, not just web calls

Span contexts do not only travel in web requests. For message queues and event streams, the context is placed in the message’s own headers or properties. The consumer extracts it and creates a span that either continues the same trace or, for batch processing, links back to the original. This is how a trace can follow an order from the web page, through a queue, all the way to the email worker that runs minutes later.

The flag that lets hundreds of services agree without a meeting.

Recording every trace in a large system is very expensive. Sampling means keeping only some traces. The key challenge is agreement. If the gateway decides to keep a trace but the payment service decides to drop its part, the trace will have holes. The sampled flag solves this by carrying the first decision to everyone downstream.

flowchart TD
    A["Request arrives"] --> B{"Valid incoming span context?"}
    B -->|No| C["Create root span and let the sampler decide"]
    B -->|Yes| D{"Sampled flag on?"}
    D -->|Yes| E["Record this span and pass flag on"]
    D -->|No| F["Do not record details but still pass context on"]
    C --> G["Set sampled flag on the new span context"]
    G --> H["Call next service with the flag"]
    E --> H
    F --> H
    

The usual sampler used in production is called a parent-based sampler. Its rule is simple: if there is a parent, follow the parent’s decision. If there is no parent, make a fresh decision, for example by keeping ten percent of traces.

Recording versus sampled: two different ideas

These two words sound similar, but they are separate. A span that is recording collects details like attributes and events inside the program. A span that is sampled carries the flag that says the trace will be kept and exported. In most setups, the two go together, but they can differ. A program can record a span locally for its own use, for example to compute local metrics, without marking the trace as sampled for others.

Tail sampling and the flag

Some systems decide after the trace is finished, called tail sampling. In that case, spans are usually recorded and exported to a central processing point, which then decides what to keep. The sampled flag is less meaningful there, because the real decision is made later. This is why it is important to know which style your own system uses.

A clever detail in the design that protects your traces.

The OpenTelemetry API is separate from the SDK. If a program uses only the API and no SDK is installed, the tracing calls do nothing, which is called no-op. You might expect that this would break trace connections, since nothing is recorded. But the design is smarter than that.

When the API has no SDK behind it, it returns a non-recording span that simply wraps the incoming span context. This means that even a service with no real tracing setup will still pass the trace identity along to the services it calls. A trace can therefore survive an uninstrumented hop in the middle of a journey.

Because it is small and standard, many parts of OpenTelemetry borrow it.

Three ways to carry information, each for a different purpose.

A common beginner mistake is trying to put business data, such as a customer ID, into the span context or the trace state. The span context is for identity. If downstream services need business hints, use baggage carefully. If you only need the detail for searching later, use attributes on the span.

A design this small has big strengths, and a few honest limits.

Key trade-offs

The span context is public information in transit, and it comes from the outside world.

When span contexts get lost, the symptoms are easy to spot if you know where to look.

• Many tiny traces: if your traces mostly contain just one or two spans, context is probably being dropped between services.
• Orphan spans: spans that point to a parent that never shows up suggest that the parent was dropped, not sampled, or lost in transit.
• Roots in the wrong place: if root spans appear deep inside your system and not at the edge, an upstream hop is failing to pass the context on.
• Invalid context counts: count how often incoming headers are missing or malformed at your gateways.
• Log correlation rate: measure what share of log lines carry a trace ID. A low share points to missing logging integration.
• Header size: watch for unusually large trace state or baggage, which can cause rejected requests at proxies.
• Sampling consistency: check that the sampled share matches your plan. Large differences may signal forced sampling or broken parent-based rules.

Habits to copy and traps to avoid.

Good design patterns

Anti-patterns

A practical checklist for keeping your traces whole.

Best practices

• Use the standard format. Keep W3C Trace Context as your default, and add other formats only where old systems need them.
• Check every hop. Gateways, proxies, load balancers and service meshes must allow trace headers through.
• Allow headers in browsers. When a web page calls your API from another domain, make sure the cross-origin rules allow the trace headers.
• Propagate through queues. Always place the context in message headers, and extract it in consumers.
• Capture context for async work. Before starting background tasks, make sure the current context is passed in.
• Check validity. Test whether an incoming context is valid before using it as a parent.
• Use parent-based sampling. Let each service follow the first decision unless you have a strong reason not to.
• Decide a public edge policy. Choose whether to continue, restart or link incoming traces at internet-facing points.
• Add IDs to logs. Let your logging setup add trace and span IDs automatically.
• Test propagation. Add a simple end-to-end test that calls through all your key services and checks that one trace ID appears throughout.

Common mistakes beginners make

• Thinking the span context holds the span’s attributes or timing. It holds identity only.
• Believing the parent span ID is part of the span’s own context.
• Forgetting that the context must be injected into outgoing calls to services that are not instrumented automatically.
• Losing the context in thread pools and async code.
• Mixing up “recording” with “sampled.”
• Assuming trace IDs are always unique when they came from an untrusted caller.
• Putting sensitive information into trace state or baggage.

How span context ideas show up in systems you may already know.

A typical journey for a growing company

Quick answers to questions beginners ask most.

If you remember only a few things, remember these.