X-Correlation-Id
The HTTP X-Correlation-Id header is an unofficial HTTP header carrying a unique identifier for tracking a single user action or transaction across multiple services in a distributed system.
Note
The "X-" naming convention for HTTP headers, "X" referring to "experimental", has been deprecated and needs to be transitioned to the formal naming convention for HTTP headers.
Usage
Microservice architectures split a single user action into multiple internal service calls. A profile update triggers a write to the user service, a notification dispatch, and an audit log entry. Without a shared identifier, correlating these operations across separate log streams is tedious and error-prone.
The X-Correlation-Id header solves this by carrying a single identifier from the first point of entry through every downstream service call. The gateway or first service receiving the request generates the identifier and attaches the header. Each subsequent service extracts the value, includes the identifier in log output, and forwards the same header to any further downstream calls. The result is a single thread linking all log entries and spans related to one transaction.
The header appears as both a request and response header. Services propagate the value on outgoing requests and echo the value back in the response so the original caller has a reference for support tickets or debugging.
The X-Correlation-Id header serves a different purpose than X-Request-Id. A request ID identifies a single HTTP call between two services. A correlation ID identifies the entire transaction spanning multiple HTTP calls. A single user action generates one correlation ID and potentially many request IDs. The W3C Traceparent header offers a standardized alternative with built-in span hierarchy and sampling flags.
Values
UUID
The value is typically a UUID v4 string in the standard 8-4-4-4-12 hyphenated format. Most implementations generate a new UUID at the entry point and propagate the same value through all downstream calls. Some implementations use a 32-character hex string without hyphens.
Example
A response from a web application includes the correlation ID as a UUID v4 string. Every internal service call triggered by this request logged the same identifier, making cross-service debugging straightforward.
X-Correlation-Id: 6221f191-10ed-4e5f-8b7b-d2cea7482c71
A different transaction produces a different UUID. The value changes per user action, not per HTTP call.
X-Correlation-Id: a5740217-0e19-409e-a6f2-ad9059024912
Some implementations use a 32-character hex string without the standard UUID hyphenation.
X-Correlation-Id: 9a928dd19f8a3905126de50590494eac
Pairing X-Correlation-Id with X-Request-Id gives full visibility. The correlation ID ties all calls in the transaction together. The request ID identifies the specific hop.
X-Correlation-Id: 4008d81c-1a5a-42f3-8d37-70695a47b243
X-Request-Id: b7e4c3f0-9821-4a1e-af52-d18e6b3c72a4
Takeaway
The X-Correlation-Id header carries a transaction identifier across service boundaries, linking all log entries and spans from a single user action into one traceable chain. The W3C Traceparent header is the standardized alternative for new distributed tracing implementations.