Debugging Microservices Part II: The Correlation Identifier

Soner Çökmen
2 min readNov 11, 2019


Debugging Microservices

In the first part of this series, I mentioned how we can use the user-agent header in the microservice architecture. That method is efficient for making applications self-describing. In this article, we will focus on the correlation identifier pattern, a well-documented enterprise integration pattern that makes it easy to trace the messages and find possible problems.

The correlation identifier is a unique identifier attached to each request in architecture.

The pattern is very simple:

  • Transfer the incoming correlation identifier to outgoing requests
  • If no correlation identifier is found, generate one and follow the first step

This rule is not only for HTTP calls but messaging systems and any other RPC methods.

Because of the nature of the distributed architecture, it is very hard to find the root cause of problems. Communication is asynchronous and message execution order is not guaranteed, so we cannot sure which transaction causes a problem. In the figure below, I illustrated an example use case. The client generates a correlation identifier and each component transfer it to the next ones.

An example of using the correlation identifier

The real benefits of the correlation identifier pattern come out when used with a distributed logging system. In this scenario, each component keeps an audit log with the correlation identifier. When an error occurred in a particular component, it is easy to group related transactions and detect the root cause of the problem.

Format of the Correlation Identifier

There is no standard format for the correlation identifier. It can be a UUID or any meaningful unique identifier for the application domain. In Trendyol, we prefer using UUID as a correlation identifier.

X-Correlation-Id: aa094a45-afc4-45e6-b557-e0ed98674d66

X-Correlation-Id is a non-standard but commonly used HTTP header for correlation identifier.



Soner Çökmen

Developer @ Zalando. An average chess player who loves Italian opening.