Software Development

Headstart Framework: Traceability For RESTful Calls

We can start small with the Headstart Framework and leverage its traceability for RESTful calls for Microservices. In a nutshell, traceability means we associate a unique identifier to an individual request. Also, this identifier can group related requests forming a logical transaction. With traceability, we could generate a flow of requests across services and trace them by unique identifiers.

Headstart Framework HTTP Headers for Traceability

With Headstart Framework, the traceability for RESTful calls revolves around a set of HTTP headers, as shown below.

Header nameHeader TypeOptionalDescription
X-Request-Correlation-IDRequestYesWe can use this identifier to group related RESTful calls for traceability. For instance, a user request going through several Microservices must use the same unique identifier.
X-Request-IDRequestYesA unique ID that is used for each individual request.
X-Response-Correlation-IDResponseAvailable if X-Request-Correlation-ID was provided in the request.This correlation ID has the same value as the request correlation ID.
X-Response-IDRespnseAvailable if X-Request-ID was provided in the request.The response ID has the same value as the request ID.

These HTTP headers are optional. If we provide values for any HTTP request headers, we get the same values for the associated HTTP response headers. For example, we get an HTTP response header X-Response-Correlation-ID with the same value we sent for X-Request-Correlation-ID. The same goes for the X-Request-ID and X-Response-ID.

API Level Traceability

These traceability identifiers are useless unless we capture the RESTful call requests flow. Once we caught them, we could generate a graphical data flow map. We can capture the requests flow using Spring Cloud Sleuth and create a visual data flow map with Zipkin.

Alternatively, we could check every log file. Then, look for values we associated with our X-Request-Correlation-ID or X-Request-ID headers. However, we do not recommend this approach when working with containerized services or applications.

Headstart Framework Traceability Across Services

Assume we have two services – Product Catalog and Inventory – and the former does RESTful calls to the latter. How can we propagate the value of HTTP request header X-Request-Correlation-ID?

We can use the injectable Trace facade. Consider the following controller code snippet within the Headstart application (as an IAM)

Then, we could make a HTTP calls passing the values from the Trace facade’s methods getRequestCorrelationId()  and getRequestId(). These methods return String values representing X-Request-Collection-ID and X-Request-ID.  Similarly, we can use the exact implementation when services use the headstart-iam-adapter dependency

Got comments, or suggestions? Please visit our Facebook page!

You Might Also Like