Using Instana to capture custom HTTP headers

Instana introduces the next generation of APM, which provides a comprehensive view of your application architecture and distributed call patterns. This approach is especially relevant when you deal with highly-distributed environments and microservice environments.

From Instana release 1.0.223, you can configure custom HTTP headers that can be used to improve filtering and analysis of your web requests to trace all your end-to-end transactions.

How custom HTTP headers can help

Sometimes you want to filter or group your web requests or transactions based on custom attributes.

For example, if you want to track a user transaction based on a custom reference ID, and need to see a list of orders from a particular user for your application that deals with order management. You can achieve your goal by using Instana’s custom HTTP header feature. Add the userId attribute as an HTTP header in each request, and add those header details in the Instana agent configuration.

Restrictions:

• All tracers capture request headers on HTTP entries (HTTP calls that the instrumented process receives).
• Some, but not all tracers capture response headers on HTTP entries. See the following details.
• Some, but not all tracers capture request and response headers on HTTP exits (HTTP calls where the instrumented process is the client). See the following details.
• If the same header is present as a request header and a response header, one of the two values might not be captured by the tracer.

Configurations

By default, Instana doesn’t collect HTTP headers when it traces HTTP calls, but this feature can be enabled by using the agent configuration file.

1. Change the General Tracing Settings of the Instana agent in the agent configuration file to add the list of extra HTTP headers that need to be captured by Instana as follows:

The values are case-insensitive. The headers that are collected are shown in the callee details section. You can also use the header names and their values to search for calls and traces on Instana UI or by using the API. In addition, the headers can be used for service configuration.

2. Add your custom HTTP headers that need to be captured by Instana. In the following example, a sample Spring Boot pet-clinic application is used, and an additional HTTP header x-reference-id is added:

3. The custom headers are shown as part of the trace details in the Detailed Trace View page.

You can group the traces based on the custom header.

If you want to find more about Instana host agent configurations, refer to the document.