Distributed tracing at a glance: spans, parent IDs, and W3C Trace Context

What it is

A trace records a request as it passes through several services. It is a tree of spans. The OpenTelemetry documentation lists what a span contains: a name, a parent span ID (empty for the root span), start and end timestamps, a span context (trace ID and span ID), attributes, events, links, and a status. Each span also has a kind (Client, Server, Internal, Producer, or Consumer), which tells the backend how to assemble the tree: the parent of a server span is often a remote client span.

The tree only forms if the IDs cross process boundaries. The W3C Trace Context recommendation defines the HTTP header traceparent for this purpose: version-trace-id-parent-id-trace-flags. The trace ID is 32 lowercase hexadecimal characters (16 bytes), the parent ID is 16 hex characters (the caller's span ID), and the flags byte currently carries one bit, sampled. A second header, tracestate, holds vendor-specific data. The recommendation describes two levels of support: a tool must at least pass both headers on so that traces do not break, or it can participate by creating its own span and rewriting the parent ID. The OpenTelemetry page on context propagation describes the same mechanism: the caller passes the trace ID and span ID, and the callee creates a child span with the caller's span as its parent.

Why it matters

Logs from ten services describe ten separate events; a trace shows which of them belong to one request, in what order, and where the time went. Without propagation, each service starts its own root span, and the backend shows fragments that cannot be connected.

How to apply

• Create a server span for every incoming request, and a client span for every outgoing call, published message, and database query; framework instrumentation libraries do this automatically.
• Propagate the context through everything, not only over HTTP: put traceparent into the headers of queue messages and into the payload of background jobs, and restore it in the consumer.
• Write the trace ID into every log line of the request so that logs and traces can be linked.
• Choose span names with low cardinality (GET /users/{id}, not the concrete URL); put variable parts into attributes.
• Services without a tracing SDK pass traceparent and tracestate on unchanged.

Pitfalls

At asynchronous boundaries (thread pools, timers, batching writers), the context is lost unless the library or the code explicitly carries it along. The sampled flag is a hint from the caller; making a separate sampling decision in each service produces traces with missing spans. Clock skew between hosts can make a child span start before its parent. A public edge should deliberately decide whether to continue a trace supplied by an arbitrary client.