~/notes/correlation-id

Correlation ID

An opaque identifier used to associate messages and logs that belong to the same logical exchange.

Jul 11, 2026

A correlation ID connects an asynchronous response to the request that caused it. The requester generates the identifier, stores it with the pending operation, and includes it in the outbound message. The responder copies it into the response without assigning business meaning to it.

Correlation IDs should be:

  • unique within the retention window;
  • treated as opaque values;
  • propagated unchanged across request and response messages;
  • included in structured logs and operational events;
  • validated for length and format at trust boundaries;
  • expired after the operation reaches a terminal state and its retention period ends.

A random UUID is usually sufficient. A database-generated operation ID can also work when it is created before publication.

Persist Before Publishing

Store the pending operation before sending the request. Otherwise a fast response can arrive before the requester has created the state needed to match it. Systems that must atomically persist state and publish a message commonly use a transactional outbox.

The stored record normally includes the correlation ID, operation status, request fingerprint, creation time, deadline, and result location. This record lets another instance recover after a process restart.

A correlation ID is not automatically:

  • a trace ID, which joins telemetry spans across a distributed trace;
  • an idempotency key, which lets a receiver recognize repeated attempts at one logical operation;
  • a message ID, which identifies one particular message delivery.

One value can sometimes serve more than one purpose, but keeping the semantics distinct prevents retention, privacy, and deduplication rules from becoming coupled.

In Asynchronous Request-Response, correlation answers “which operation does this response belong to?” Idempotency answers “have I already applied this operation?”

Linked References

Asynchronous Request-Response note
"...or a message. A typical lifecycle is: 1. The requester creates a unique Correlation ID or operation ID. 2. The receiver validates and durably records the request...."
RabbitMQ Reply Queues note
"...RabbitMQ request-reply sends a request with a reply-to address and a Correlation ID. The responder publishes its result to that address and copies the..."