Documentation

Web & HTTP Toolkits

When measuring the performance of a web application (or any other HTTP-based application) there is a good chance that your main subject of interest is going to be the latency of the request-response cycles for the services your application provides and/or the performance of the HTTP request your application sends to other services using the HTTP client. That should ring a bell if you already visited our tracing core concepts section: Yes, you can use Kamon’s tracing facilities to measure the performance of the services you provide (traces) and the services you call (segments).

When we bring support for a Web or HTTP Toolkit in Kamon, we are talking about prodividing bytecode instrumentation and/or “native” tools to achieve at least the following functionality:

Automatically Manage Traces for Incoming Requests

This is just about starting a trace when a request comes into your application and finishing it when a response is sent back to the client. Seems simple and like it’s not a big deal, but this is the little bit of instrumentation that let’s you measure the latency behaviour of your application, as experienced by your users.

Automatically Manage Segments for Outgoing Requests

Segments kick in if the framework or library you are using comes with an HTTP client. The operation is simple: if you send a HTTP request to another service while under the scope of a trace, then a new segment will be automatically started and finished when the response to that service comes back.

The automatically generated segments will have http-client as category and the name and library attributes will depend on the instrumentation specifics, you can check out the details for this in the framework-specific sections.

Automatically Propagate the Trace Token

When this feature is enabled, our instrumentation will automatically try to propagate the current trace’s token across services by including a X-Trace-Token header in both requests sent to other services and responses generated by your application.

On the server side, when a incoming request contains the X-Trace-Token header, the new TraceContext created to track the request will use the same token included in the header, instead of creating a new one.

On the client side, the X-Trace-Token header will be automatically included in requests sent to other services if the request is sent within a trace.

The main goal on including this feature is that, even while Kamon doesn’t support distributed tracing (yet) you can still opt for a simple approach of including the trace token in your logs and aggregate them with tools like Kibana. Then, searching for a single trace token can give you the logs of all interactions related to that trace across your entire fleet of servers.

All the functionality described here is provided for both Spray and Play!, look at their specific sections for more details on how to control and customize their behaviour.