Observability for APIs: Request IDs and Trace Context

One id carried through every service turns a failed request into one search instead of ten.

A request that fails in a system of several services leaves a line in each service's log, and nothing to connect them unless every line carries the same id. A request id is returned to the client and logged with every line; trace context, standardised by the W3C as the traceparent header, carries one trace id from service to service so a tracing tool can rebuild the whole request.

One request through three services, with the same trace id on every hop

The traceparent header. It has four parts separated by hyphens: a version, 00; a 32-character trace id, the same for the whole request; a 16-character parent id, identifying the span, the unit of work, that made this call; and flags, such as 01 for sampled. An example from the W3C specification is 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01.

What each service does. Keep the trace id it received; create its own span with a new span id; and send the same trace id to each downstream call, with its own span id as the parent. A service that starts a new trace id breaks the chain, and one that forwards the header unchanged makes the tracing tool attach every call to the wrong parent.

What the client sees. Return the request id in a response header, and include it in every error body, so a support ticket that quotes it leads straight to the logs. The trace ids in the diagram are shortened, and the values are illustrative.

So give every request one id from its first service to its last, and hand that id back to the client.

← → move through sections and cards