Automatic tracking correlated HTTP requests
Arcus Web API already contained the necessary middleware components to receive and parse the HTTP correlation from incoming requests and use it throughout the application. The Request-Id and X-Transaction-ID request headers are used to determine by what ID the parent of this request (sender) is identifying itself (Request-Id) and by what ID this whole HTTP interaction should be identified (X-Transaction-ID). This will eventually result in an HTTP correlation model that is accessible anywhere in the application. What v1.6 adds, however, is how we send and track such a correlated HTTP request.
To put things in perspective, here is a diagram of such interactions. In this example, the user interacts with service A which calls service B to answer the client’s request.
This diagram shows a fully correlated HTTP interaction. For a more in-depth explanation, see our official documentation page to understand each step of the interaction. Right now, we are only going to focus on the third interaction arrow, which is how service A can contact service B with automatic HTTP correlation and tracking.
HTTP message handler registration
Sending HTTP requests in a .NET application with a dependency injection system usually happens via the built-in HTTP client factory. A simple call to services.AddHttpClient() will make sure that there is a HttpClient available in your application. The added value of using injected clients is that additional configuration, authentication etc. only has to be set up once and is centralized in the application. The HTTP client can be extended with your configuration and authentication by using the composable HTTP message handlers. That is why we added an HTTP message handler that does the correlation and tracking for you.
To make sure that all the injected HTTP clients will add correlation to their request, the following additions have to be made:
Now, what happens when the injected HttpClient is used with this additional HTTP message handler? Internally, two things happen: firstly, the available HTTP correlation in the application will be used to enrich the outgoing HTTP request with the necessary correlation headers. As shown in the diagram, the request will have two headers: Request-Id and X-Transaction-ID. Secondly, the request will be tracked as an HTTP dependency and will be available as such if Application Insights is configured.
The complexity of HTTP correlation is hard to explain and even harder to get right in your application. That is why we have chosen to use this approach, as it hides all the infrastructure from your application code so that consumers only have to focus on the request’s contents.
HTTP client extensions
Not all applications can use the built-in HTTP client factory. Certain scenarios require you to send a correlated HTTP request outside the boundaries of an API. In any case, there are many places where the previous approach would not work. In those cases, we have made sure that consumers can still benefit from an easier way of sending and tracking correlated HTTP requests.
Starting from v1.6, the library has several extensions on the HttpClient.SendAsync method that takes in all the necessary information that would otherwise be extracted from a dependency injection system. Two things are required: access to the application’s correlation model (CorrelationInfo) and a logger instance. Internally, the same things happen as with the HTTP message handler, which is reflected in the required parameters that the extension takes in.
Both the HTTP message handler and the HTTP client extensions are configurable. Which request headers should be used for the HTTP correlation, how the HTTP dependency will be logged, it is all made configurable for your needs. See our official feature documentation for more information on both approaches and how to use them in your application.
Bonus: open exception handling middleware
Arcus WebAPI v1.6 focuses mostly on finishing the service-to-service correlation features. However, we do have a small but useful bonus feature in this release.
Exception handling via middleware is one of the oldest features in this library. The purpose and implementation are straightforward: manage unhandled exceptions. The component makes sure that any uncaught exceptions are handled and logged, whilst returning an HTTP failure code to the client.
However, the HTTP failure code was static for exceptions that the middleware component didn’t recognize, which means that different custom application failures that rely on exceptions all resulted in the same general HTTP failure code (which was 500 InternalServerError). In some scenarios, this is not enough and is obscure for the client.
v1.6 changed this by opening up the internal structure and letting the consumer decide how a certain type of exception affects the returned HTTP response. The following example show how each type of exception can have its HTTP failure code:
Notice that the middleware component is now also letting the consumer decide how the caught exception is logged. We have made sure that the default HTTP failure code is passed along as we internally also catch the BadHttpRequestException, which will result in 400 BadRequest as default status code. In all other cases, we still use the 500 InternalServerError as default.
Registering your custom middleware component happens with an overload of the general exception handling middleware:
This feature is small but makes our provided functionality more customizable and useful in our application, which is what Arcus is all about.
Conclusion
Service-to-service correlation is a large and complex topic that spans multiple Arcus repositories. In this post, we have explained only a small piece of the correlation puzzle. Expect a more in-depth user guide on how to integrate service-to-service correlation in your application soon.
Arcus WebAPI v1.6 has also many internal improvements that were too vast to explain here. Upgrade to this version to experience all these cool new changes in your application. See our feature documentation to explore what we have to offer.
If you have any questions, remarks, comments, or just want to discuss something with us, feel free to contact the Arcus team at Codit.
Thanks for reading!
-The Arcus team
Subscribe to our RSS feed