Correlation IDs
Correlation ids tag each request with a unique identifier propagated across every hop, stitching logs, errors, and messages from many services into one causal timeline.
Definition
A correlation id is a unique per-request identifier generated at entry and propagated through every downstream call, queue message, and job — via headers, message properties, or context. Logs and events carrying the same id assemble into the request full story. W3C Trace Context standardizes the modern form: traceparent carries trace and span ids with propagation rules.
Context and scope
The precursor to distributed tracing and still its substrate: request id in headers, message correlation properties, and async context propagation all implement it. Required for cross-service log search.
Common misconceptions
- Correlation ids are legacy tracing — they are the propagation mechanism tracing builds on; spans add structure and timing on top of the same ids
- Generating an id per hop works — each hop must propagate the incoming id, not mint a new one, or the chain fragments
- Ids must be globally unique forever — uniqueness within the retention window suffices; ids also need low collision probability, not cryptographic secrecy
Anti-patterns
- Generating new ids at internal service boundaries and losing the causal chain
- Propagating ids over HTTP but dropping them at queue hops, splitting synchronous and async halves
- Putting correlation ids in URLs where they leak into logs, referrers, and user shares
Related concepts
Related examples
Authoritative source
What it is
One user action fans out across ten services and three queues. Without a shared identifier, reconstructing the action requires timestamps and luck. With one, it is a query.
How it works
The entry point mints an id and stores it in request context. Outgoing calls copy it to headers; queue producers copy it to message properties; workers restore it before processing. Async runtimes need context propagation — thread-locals break across task boundaries. W3C traceparent formalizes the header and its versioning.
When to implement
Before you need it: retrofitting ids through a service fleet is far costlier than emitting them from day one. Every new hop — a queue, a cron job, a webhook — must adopt propagation or the chain silently breaks there.
Pitfalls
Propagation gaps are invisible until the incident: test that ids survive each middleware, serializer, and queue hop in integration suites. Ids in URLs become user-shareable and leak into external referrers. Retries that reuse the id preserve causality; retries that mint new ids fragment it — decide explicitly per flow.