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 name | Header Type | Optional | Description |
|---|---|---|---|
| X-Request-Correlation-ID | Request | Yes | We 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-ID | Request | Yes | A unique ID that is used for each individual request. |
| X-Response-Correlation-ID | Response | Available if X-Request-Correlation-ID was provided in the request. | This correlation ID has the same value as the request correlation ID. |
| X-Response-ID | Respnse | Available 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)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | package com.turreta.headstart.service.core; import com.turreta.headstart.domain.User; import com.turreta.headstart.kernel.exception.OperationNotAllowedException; import com.turreta.headstart.kernel.facade.Trace; import com.turreta.headstart.persistence.UserRolePermissionManagementPort; import org.apache.commons.lang.StringUtils; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; @Service public class UserRolePermissionManagementService implements UserRolePermissionManagementUseCase { private final UserRolePermissionManagementPort userRolePermissionManagementPort; private Trace trace; public UserRolePermissionManagementService(UserRolePermissionManagementPort userRolePermissionManagementPort, Trace trace) { this.userRolePermissionManagementPort = userRolePermissionManagementPort; this.trace = trace; } // Omitted for brevity } |
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.
