correlationId

A correlation identifier, or CorrelationId, is a unique value attached to a unit of work as it moves through a system of distributed components. It serves to associate related events, messages, and logs that originate from the same transaction or request, enabling end-to-end visibility across service boundaries.

The primary purpose of a CorrelationId is to facilitate troubleshooting, monitoring, and diagnostics. By carrying a single identifier across heterogeneous components, developers and operators can assemble logs and traces from multiple services to reconstruct the path of a request, detect bottlenecks, and correlate errors with their originating context. In practice, it is commonly used in microservices architectures, event-driven systems, and message queues.

Propagation and generation are central to effective use. The CorrelationId is typically generated at the edge of the system or at the entry point of a request, often as a UUID or a time-based identifier, and then propagated through outgoing requests, message headers, and event metadata. If downstream components receive a request without one, a new CorrelationId may be generated to preserve continuity. Clients and services should consistently pass the identifier along every hop and log it with every event.

Relation to other concepts varies by implementation. The CorrelationId is not a substitute for detailed distributed tracing or for per-span identifiers used by tracing systems, but it complements them by providing a simple, cross-cutting thread of context. Common best practices include ensuring consistent propagation, avoiding leakage of sensitive data, and handling missing identifiers gracefully.

Limitations include potential for noise if not managed, overhead in logging, and the need for standardization across teams and services to maximize effectiveness.