Understanding a Correlation ID
A correlation ID is a unique value, typically a UUID, assigned to a request the moment it enters a system, then propagated through every downstream service call, message queue hop, and log statement associated with that request. Its sole purpose is to let engineers answer the question “show me everything related to this one request” across a distributed system where a single user action might touch a dozen services, each writing its own logs and emitting its own metrics independently.
How Correlation IDs Work
A correlation ID is usually generated by the edge of the system, such as an API gateway or the first service that receives a request, and attached as an HTTP header, commonly something like X-Correlation-ID or X-Request-ID. Every service that receives the request reads the header, includes it as a field in every structured log line it writes for that request, and forwards the same header on any downstream calls it makes, including asynchronous messages published to a queue. The result is that a single correlation ID value appears scattered across the logs of every service the request touched, letting engineers filter their log aggregation tool, such as Loki or Elasticsearch, by that one value to reconstruct the entire request’s path.
Correlation ID vs. Trace ID
In distributed tracing systems built on OpenTelemetry, the trace ID serves the same fundamental purpose as a correlation ID, and many teams now use the trace ID as their correlation ID rather than maintaining two separate identifiers. The W3C Trace Context standard defines a traceparent header that carries the trace ID automatically as part of standardized trace propagation. Using the same ID for both means a log line’s trace_id field can be clicked directly to pull up the corresponding trace in Jaeger or Tempo, and a slow span in a trace can be used to filter logs directly, without translating between two different identifier schemes.
A Concrete Debugging Scenario
A customer reports that a specific checkout attempt failed with a generic error message. Without a correlation ID, an engineer would have to guess which log lines, across the API gateway, order service, inventory service, and payment service, belong to that customer’s specific attempt, based on approximate timestamps. With a correlation ID captured from the customer’s error page or support ticket, the engineer runs a single query across the centralized log store filtering on that exact ID and instantly sees the full sequence of events across all four services in chronological order, including the exact point where the inventory service returned an out-of-stock error that the order service failed to surface clearly to the user.
Where Correlation IDs Are Used
- Synchronous HTTP calls between microservices, propagated via request headers.
- Asynchronous messaging systems like Kafka or SQS, where the ID is embedded in message metadata so consumers can log it even though there is no direct HTTP call chain.
- Batch and background jobs, where a correlation ID ties a triggering event to all the downstream processing it causes.
Trade-offs and Best Practices
- Correlation IDs are only useful if every service in the chain actually propagates them; a single service that drops the header breaks the chain for everything downstream of it.
- Standardizing on the OpenTelemetry trace ID as the correlation ID avoids maintaining two parallel identifier systems and gets tracing and logging correlation for free.
- Correlation IDs should be included in error messages surfaced to support teams or customers so a bug report can be traced directly back to the specific request in the logs.
- Frameworks and service mesh sidecars, such as those used with Istio or Linkerd, can automatically inject and propagate correlation headers, reducing the burden on individual application code.
Frequently Asked Questions
What is Correlation ID?
A correlation ID is a unique identifier generated at the start of a request and passed through every service and log line it touches, so related telemetry can be tied back to that single request across a distributed system.
How does Correlation ID work?
Correlation ID works by combining the components described in the sections above. The main page walks through the architecture, the typical use cases, and the trade-offs to weigh before adopting it.
Why does Correlation ID matter?
Teams adopt Correlation ID to ship faster, run more reliably, and reduce the cognitive load on engineers. The benefits, limits, and adjacent tools are covered in the body above.
When should you use Correlation ID?
Use Correlation ID when the problems it solves match what your team is hitting today. The page above outlines the signals that mean you should adopt it now, and the cases where a simpler approach is fine.
