Agent Configuration

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

Configuring with Environment Variables

In some environments, configuring via Environment Variables is more preferred. Any setting configurable with a System Property can also be configured with an Environment Variable. Many settings below include both options, but where they don’t apply the following steps to determine the correct name mapping of the desired System Property:

• Convert the System Property to uppercase.
• Replace all . and - characters with _.

For example otel.instrumentation.common.default-enabled would convert to OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED.

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).

Enable only specific instrumentation

You can disable all default auto instrumentation and selectively re-enable individual instrumentation. This may be desireable to reduce startup overhead or to have more control of which instrumentation is applied.

• Disable all instrumentation in the agent using -Dotel.instrumentation.common.default-enabled=false (or using the equivalent environment variable OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED=false).
• Enable each desired instrumentation individually using -Dotel.instrumentation.[name].enabled=true (or using the equivalent environment variable OTEL_INSTRUMENTATION_[NAME]_ENABLED) where [name] ([NAME]) is the corresponding instrumentation name below.

Note: Some instrumentation relies on other instrumentation to function properly. When selectively enabling instrumentation, be sure to enable the transitive dependencies too. Determining this dependency relationship is left as an exercise to the user.

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-instrumentation-annotations.enabled=true

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.

Instrumentation span suppression behavior

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.

By default the agent will suppress nested CLIENT spans for the same semantic convention.

By setting -Dotel.instrumentation.experimental.span-suppression-strategy you can enable a different suppression strategy.

For example, if we have a database client which uses Reactor Netty http client which uses Netty networking library, then with the default suppression strategy (semconv), 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

With suppression strategy of span-kind, we would have 1 span:

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

And with suppression strategy of none, 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