Configuring tracers by using the agent configuration file

You can configure tracer-specific settings by using the agent configuration file (instanaAgentDir/etc/instana/configuration.yaml) if the agent is installed on a host. These configurations control how Instana tracers capture and process tracing data across your monitored applications.

For a detailed list of all the Instana configuration parameters, see Instana Helm chart.

For Instana deployments on Kubernetes, see Configuring the Kubernetes agent by using the configuration file.

For general agent configuration options, see Configuring host agents by using the agent configuration file.

Note:
The format of the agent configuration file is YAML, which is sensitive to blank spaces. Therefore, make sure to not use unnecessary spaces in the file. To create an indentation, use only two blank spaces.

Capturing custom HTTP headers

By default, Instana doesn't collect HTTP headers when it traces HTTP calls.

If required, you can enable this feature by applying the following configuration in the agent configuration file:

com.instana.tracing:
  extra-http-headers:
    - 'x-request-id'
    - 'x-loadtest-id'
    - ...

The values are case-insensitive. The headers that are collected are shown in the call details (in the Call details section). You can also use the header names and their values to search for calls and traces (in the UI or by using the API) and for service configuration.

This feature currently has the following restrictions:

  • All tracers capture request headers on HTTP entries (HTTP calls that the instrumented process receives).
  • Some tracers might capture response headers on HTTP entries. For more information, see Table 1.
  • Some tracers might capture request and response headers on HTTP exits (HTTP calls where the instrumented process is the client). For more information, see Table 1.
  • 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.
Table 1. Tracer request and response header information
Tracer Request Headers on HTTP Entries Response Headers on HTTP Entries Request Headers on HTTP Exits Response Headers on HTTP Exits
Go ✅ ✅ ✅ ✅
Java ✅ ✅1 ❌ ❌
.NET ✅ ✅ ✅ ✅
Node.js ✅ ✅ ✅ ✅
PHP ✅ ❌ ❌ ❌
NGINX ✅ ❌ — —
Python ✅ ✅ ✅ ✅
Ruby ✅ ✅ ✅ ✅
HTTPd ✅ ❌ — —

Configuring Kafka trace correlation headers

You can configure the format for Kafka trace correlation headers that are used by Instana tracers by using the setting com.instana.tracing.kafka.header-format. Valid values are binary, string, or both. See the following example:

com.instana.tracing:
  kafka:
    header-format: string # possible values: binary, both, string

You must not disable the Kafka trace correlation entirely. However, if you need to disable the Kafka trace correlation entirely, then set com.instana.tracing.kafka.trace-correlation: false. See the following example:

com.instana.tracing:
  kafka:
    trace-correlation: false
Note:
Many Kafka connectors use SimpleHeaderConverter as the default mechanism for handling Kafka message headers. This converter can fail when processing Instana tracing headers, as it attempts to deserialize header values into native types, which might trigger numeric overflow errors. To resolve this issue, configure the Kafka Connect to use StringConverter: 
header.converter=org.apache.kafka.connect.storage.StringConverter

For more information, see Kafka Header Migration.

Disabling tracing

You can disable tracing for specific span type (frameworks, libraries, or instrumentations) or entire groups of libraries (span category). For example, to exclude the redis package from tracing entirely or disable tracing for all logging-related libraries, use the disable configuration option.

Note:
This feature is not yet supported by all tracers.

To configure this setting, define the types or categories that you want to disable under the com.instana.tracing.disable section in your agent configuration file, as shown in the following example:

com.instana.tracing:
  disable:
    redis: true         # Disable Redis
    console: false      # Keep console enabled
    logging: true       # Disable the entire logging category

where:

  • true: Disables tracing for the specified type or category.
  • false: Explicitly keeps the specified type or category enabled.

In the preceding example, the configuration disables all instrumentations within the logging category, except for console, which is explicitly enabled. Additionally, the configuration also excludes all redis related spans from tracing. No spans are collected or reported for any disabled libraries or categories.

Support information

The following table lists the tracers that support disabling traces:

Table 2. Tracers that support disabling traces
Tracer Supports Disabling Traces
Node.js ✅
Go ❌
Java ✅
Python ✅
Ruby ❌
PHP ✅
.Net ❌
NGINX ❌

Disabling W3C

By default, Instana tracers process and propagate W3C traceparent and tracestate headers for distributed trace correlation. You can disable W3C correlation, propagation, or both independently by using the agent configuration file.

Disabling W3C correlation

Disables processing of incoming W3C traceparent or tracestate headers without affecting outgoing propagation.

com.instana.tracing:
  global:
    disable-w3c-correlation: true

Disabling W3C propagation

Disables injection of W3C traceparent/tracestate headers into outgoing requests.

com.instana.tracing:
  global:
    disable-w3c-propagation: true

Disabling W3C completely

Disables both W3C correlation and propagation.

com.instana.tracing:
  global:
    disable-w3c: true

Support information

The following table lists the tracers that support disabling W3C through agent configuration:

Table 3. Tracers that support disabling W3C through agent configuration
Tracer Supported
Node.js ✅
Go ❌
Java ❌
Python ❌
Ruby ❌
PHP ❌
.NET ❌
NGINX ❌

Capturing stack traces

You can configure stack trace capturing for exit spans across all your services. By default, tracers capture the last 10 call sites for every captured exit span.

Note:
  • This feature is not yet supported by all tracers.
  • Stack traces of HTTP entry spans are typically not collected as they show only framework or runtime core code.

You can configure two aspects of stack trace capturing:

  • Stack trace length: The number of call sites to be captured.
    • Supported values: 0–500
    • Default value: 10
  • Stack trace mode: How stack traces are captured.
    • Supported values:
      • all: Collects stack trace for all exit spans (default).
      • error: Collects stack trace only for erroneous spans.
      • none: Doesn't collect stack trace.

To configure stack trace capturing, define the parameters under the com.instana.tracing.global section in your agent configuration file, as shown in the following example:

com.instana.tracing:
  global:
    stack-trace-length: 15
    stack-trace: 'error'

In the preceding example, the configuration sets the stack trace depth to 15 call sites for all exit spans and uses the error mode.

Support information

The following table lists the tracers that support configuring stack trace capturing through agent configuration:

Table 4. Tracers that support stack trace configuration
Tracer Supports Stack Trace configuration Minimum Tracer or Collector version
Node.js ✅ Instana Node.js collector 5.2.0 and later
Go ❌ —
Java ✅ Instana Java Tracer 2.0.20 and later
Python ✅ Instana Python package/sensor 3.10.0 and later
Ruby ✅ Instana Ruby gem/sensor 2.5.0 and later
PHP ✅ Instana PHP Tracer 5.9.0 and later
.Net ❌ —
NGINX ❌ —

Ignoring endpoints

You can exclude specific endpoints from tracing. For example, if you are using the redis package and want to avoid the tracing of commands, such as GET, TYPE, or others, you can use the ignore-endpoints configuration option.

Note:
The ignore endpoints feature currently has the following restrictions:
  • Only specific packages are supported.
  • Not all tracers are supported.

For more information about the specific packages and tracers that support this feature, see Support information section.

Filtering options

You can filter the traces by using the following options:

  • Filtering by method name: With this option, you can filter traces based only on method names. It is useful when you want to ignore specific operations, such as GET calls in Redis or QUERY calls in DynamoDB.
  • Filtering by method name and endpoint: With this option, you can exclude traces based on both method and specific endpoints. This option is especially useful for technologies, such as Kafka, where you can exclude traces for a specific method (for example, consume) but only for certain topics (for example, topic1 or topic2).

Filtering rules

The rules for filtering traces are as follows:

  • When a trace is ignored, all subsequent downstream traces are also ignored.
  • Use * to ignore all endpoints or methods.
  • Endpoint values (such as Kafka topic names) remain consistent across services.
  • Method names might vary depending on the programming language and technology. To determine the correct method and endpoint for your service, refer to the Instana UI.

The following Instana UI screenshot provides a visual reference for identifying the correct method and endpoint for configuration:

Figure 1. Methods and endpoints in the UI
Instana UI screenshot of methods and endpoints configuration

Configuring endpoints to be excluded

Note:
When your system uses multiple services in different programming languages, make sure that all necessary method names are included in the agent configuration file, as they might vary from one language to another.

To configure the endpoints to be ignored, specify the endpoints that must be excluded from monitoring in the com.instana.tracing.ignore-endpoints section in your agent configuration file as shown in the following example:

com.instana.tracing:
  ignore-endpoints:

    # Filtering by Method Name
    redis:
      - 'get'
      - 'type'
    dynamodb:
      - 'query'
    kafka:
      - 'send'

    # Filtering by Method Name and Endpoint for Kafka
    kafka:
      - methods: ["consume"]
        endpoints: ["topic1", "topic2"]  # Exclude consume calls for topic1 and topic2

      - methods: ["consume", "send"]
        endpoints: ["topic3"]  # Exclude both consume and send calls for topic3

      - methods: ["*"]
        endpoints: ["topic4"]  # Exclude all methods for topic4

      - methods: ["consume"]
        endpoints: ["*"]  # Exclude consume method for all topics

In the preceding example, the following traces are ignored for the listed filtering options:

  • Filtering by method (Redis, DynamoDB, and Kafka)
    • GET and TYPE commands in Redis
    • QUERY command in DynamoDB
    • SEND method in Kafka and all downstream traces
  • Filtering by method and endpoint (Kafka only)
    • CONSUME method for topic1 and topic2 in Kafka and all downstream traces
    • CONSUME and SEND methods for topic3 in Kafka all downstream traces
    • All methods (*) for topic4 in Kafka and all downstream traces
    • CONSUME method for all topics (*) and all downstream traces

Support information

The following table lists the tracers and packages that support ignoring endpoints:

Table 5. Tracers and packages that support ignoring endpoints
Supported packages Node.js Java Go PHP Python Ruby .NET NGINX
Redis ✅ ✅ ❌ ❌ ✅ ❌ ❌ ❌
DynamoDB ✅ ✅ ❌ ❌ ✅ ❌ ❌ ❌
Kafka ✅ ✅ ❌ ❌ ✅ ❌ ❌ ❌
HTTP ✅ ❌ ❌ ❌ ❌ ❌ ❌ ❌
Note:
For Node.js, HTTP filtering applies to only incoming (entry) requests. Outgoing (exit) HTTP calls cannot be filtered.

HTTP 4xx status code error reporting

By default, Instana does not count HTTP 4xx responses as errors on HTTP calls. You can enable this behavior to monitor client errors, such as repeated 401 Unauthorized or 403 Forbidden responses.

Note:
  • This setting applies only to outgoing (exit) HTTP calls. Incoming (entry) HTTP calls are never marked as errors based on 4xx response codes, regardless of this configuration.
  • Not all tracers are supported.

The following configuration options are available under com.instana.tracing.http.exit:

  • classify-all-4xx-as-errors: Reports all 4xx responses as errors.
  • classify-as-errors: Reports only the specified 4xx status codes as errors.

When both options are set, classify-as-errors takes precedence, and only the listed codes are treated as errors. Status codes for classify-as-errors must be in the range 400–499. Any codes outside this range are ignored.

Classifying all 4xx responses as errors

To treat every 4xx response on an outgoing call as an error, add the following to your agent configuration file:

com.instana.tracing:
  http:
    exit:
      classify-all-4xx-as-errors: true

Classifying specific 4xx responses as errors

To treat only certain status codes as errors, list them under classify-as-errors:

com.instana.tracing:
  http:
    exit:
      classify-as-errors:
        - 401
        - 403

Support information

The following table lists the tracers that support HTTP 4xx status code error reporting:

Table 6. Tracers that support HTTP 4xx status code error reporting
Tracer Supported
Node.js ✅
Go ❌
Java ❌
Python ❌
Ruby ❌
PHP ✅
.NET ❌
NGINX ❌
1 Supported technologies include Servlet, Spring, Tomcat, and http4s.