Agent Configuration

NOTE: subject to change!

Note: The environment variables/system properties in this document are very likely to change over time. Please check back here when trying out a new version!

Please report any bugs or unexpected behavior you find.

Contents

• SDK Autoconfiguration
• Configuring the agent
• Common instrumentation configuration
• Suppressing specific auto-instrumentation

SDK Autoconfiguration

The SDK’s autoconfiguration module is used for basic configuration of the agent. Read the docs to find settings such as configuring export or sampling.

Here are some quick links into those docs for the configuration options for specific portions of the SDK & agent:

• Exporters
  • OTLP exporter (both span and metric exporters)
  • Jaeger exporter
  • Zipkin exporter
  • Prometheus exporter
  • Logging exporter
• Trace context propagation
• OpenTelemetry Resource and service name
• Batch span processor
• Sampler
• Span limits
• Using SPI to further configure the SDK

Configuring the agent

The agent can consume configuration from one or more of the following sources (ordered from highest to lowest priority):

• system properties
• environment variables
• the configuration file
• the ConfigPropertySource SPI

Configuration file

You can provide a path to agent configuration file by setting the following property:

Extensions

You can enable extensions by setting the following property:

Common instrumentation configuration

Common settings that apply to multiple instrumentations at once.

Peer service name

The peer service name is the name of a remote service to which a connection is made. It corresponds to service.name in the Resource for the local service.

1.2.3.4=cats-service,dogs-abcdef123.serverlessapis.com=dogs-api

DB statement sanitization

The agent sanitizes all database queries/statements before setting the db.statement semantic attribute. All values (strings, numbers) in the query string are replaced with a question mark (?).

Examples:

• SQL query SELECT a from b where password="secret" will appear as SELECT a from b where password=? in the exported span;
• Redis command HSET map password "secret" will appear as HSET map password ? in the exported span.

This behavior is turned on by default for all database instrumentations. Use the following property to disable it:

Capturing HTTP request and response headers

You can configure the agent to capture predefined HTTP headers as span attributes, according to the semantic convention. Use the following properties to define which HTTP headers you want to capture:

These configuration options are supported by all HTTP client and server instrumentations.

Note: The property/environment variable names listed in the table are still experimental, and thus are subject to change.

Capturing servlet request parameters

You can configure the agent to capture predefined HTTP request parameter as span attributes for requests that are handled by Servlet API. Use the following property to define which servlet request parameters you want to capture:

Note: The property/environment variable names listed in the table are still experimental, and thus are subject to change.

Capturing consumer message receive telemetry in messaging instrumentations

You can configure the agent to capture the consumer message receive telemetry in messaging instrumentation. Use the following property to enable it:

Note that this will cause the consumer side to start a new trace, with only a span link connecting it to the producer trace.

Note: The property/environment variable names listed in the table are still experimental, and thus are subject to change.

Suppressing specific auto-instrumentation

Disabling the agent entirely

You can disable the agent using -Dotel.javaagent.enabled=false (or using the equivalent environment variable OTEL_JAVAAGENT_ENABLED=false).

Suppressing specific agent instrumentation

You can suppress agent instrumentation of specific libraries by using -Dotel.instrumentation.[name].enabled=false (or using the equivalent environment variable OTEL_INSTRUMENTATION_[NAME]_ENABLED) where name (NAME) is the corresponding instrumentation name:

Note: When using environment variables, dashes (-) should be converted to underscores (_). For example, to suppress traces from akka-actor library, set OTEL_INSTRUMENTATION_AKKA_ACTOR_ENABLED to false.

Suppressing controller and/or view spans

Some instrumentations (e.g. Spring Web MVC instrumentation) produce SpanKind.Internal spans to capture the controller and/or view execution. These spans can be suppressed using the configuration settings below, without suppressing the entire instrumentation which would also disable the instrumentation’s capturing of http.route and associated span name on the parent SpanKind.Server span.

Enable manual instrumentation only

You can suppress all auto instrumentations but have support for manual instrumentation with @WithSpan and normal API interactions by using -Dotel.instrumentation.common.default-enabled=false -Dotel.instrumentation.opentelemetry-api.enabled=true -Dotel.instrumentation.opentelemetry-annotations.enabled=true

Enable instrumentation suppression by type

Some of the libraries that this agent instruments in turn use lower-level libraries, that are also instrumented. This results in nested CLIENT spans (a span with the kind CLIENT has a child span with the same kind CLIENT). For example spans produced by Reactor Netty instrumentation will have children spans produced by Netty instrumentation. Or Dynamo DB spans produced by AWS SDK instrumentation will have children spans produced by http protocol library instrumentation.

Although OpenTelemetry specification allows such situation, such nested spans often produce duplicate data without any added benefit. For this reason this agent by default suppresses nested CLIENT spans and emits only the top-level one.

By setting -Dotel.instrumentation.experimental.outgoing-span-suppression-by-type=true you can enable a more sophisticated suppression strategy: only CLIENT spans of the same semantic convention type (e.g. DB, HTTP, RPC) will be suppressed. For example, if we have a database client which uses Reactor Netty http client which uses Netty networking library, then without any suppression we would have 3 nested spans:

• CLIENT span with database semantic attributes from the database client instrumentation
• CLIENT span with http semantic attributes from Reactor Netty instrumentation
• CLIENT span with http semantic attributes from Netty instrumentation

With default suppression, we would have 1 span:

• CLIENT span with database semantic attributes from the database client instrumentation

With suppression by type, we would have 2 nested spans:

• CLIENT span with database semantic attributes from the database client instrumentation
• CLIENT span with http semantic attributes from Reactor Netty instrumentation