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 (span, metric, and log 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

Enable Resource Providers that are disabled by default

In addition to the resource configuration from the SDK autoconfiguration, you can enable additional resource providers that are disabled by default:

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
• properties provided by the AutoConfigurationCustomizer#addPropertiesSupplier() function; using the AutoConfigurationCustomizerProvider 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:

Java agent logging output

The agent’s logging output can be configured 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

1.2.3.4:443=cats-service,dogs-abcdef123.serverlessapis.com:80/api=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 (?).

Note: JDBC bind parameters are not captured in db.statement. See the corresponding issue if you are looking to capture bind parameters.

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.

Capturing enduser attributes

You can configure the agent to capture general identity attributes (enduser.id, enduser.role, enduser.scope) from instrumentation libraries like JavaEE/JakartaEE Servlet and Spring Security.

Note: Given the sensitive nature of the data involved, this feature is turned off by default while allowing selective activation for particular attributes. You must carefully evaluate each attribute’s privacy implications before enabling the collection of the data.

Spring Security

For users of Spring Security who use custom granted authority prefixes, you can use the following properties to strip those prefixes from the enduser.* attribute values to better represent the actual role and scope names:

Suppressing specific auto-instrumentation

Disabling the agent entirely

Enable only specific instrumentation

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

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.

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 libraries that this agent instruments in turn use lower-level libraries, that are also instrumented. This would normally result in nested spans containing duplicate telemetry data. For example:

• Spans produced by the Reactor Netty HTTP client instrumentation would have duplicate HTTP client spans produced by the Netty instrumentation;
• Dynamo DB spans produced by the AWS SDK instrumentation would have children HTTP client spans produced by its internal HTTP client library (which is also instrumented);
• Spans produced by the Tomcat instrumentation would have duplicate HTTP server spans produced by the generic Servlet API instrumentation.

The Java agent prevents these situations by detecting and suppressing nested spans that duplicate telemetry data. The suppression behavior can be configured using the following configuration option:

For example, suppose we instrument a database client which internally uses the Reactor Netty HTTP client; which in turn uses Netty.

Using the default semconv suppression strategy would result in 2 nested CLIENT spans:

• CLIENT span with database client semantic attributes emitted by the database client instrumentation;
• CLIENT span with HTTP client semantic attributes emitted by the Reactor Netty instrumentation.

The Netty instrumentation would be suppressed, as it duplicates the Reactor Netty HTTP client instrumentation.

Using the suppression strategy span-kind would result in just one span:

• CLIENT span with database client semantic attributes emitted by the database client instrumentation.

Both Reactor Netty and Netty instrumentations would be suppressed, as they also emit CLIENT spans.

Finally, using the suppression strategy none would result in 3 spans:

• CLIENT span with database client semantic attributes emitted by the database client instrumentation;
• CLIENT span with HTTP client semantic attributes emitted by the Reactor Netty instrumentation;
• CLIENT span with HTTP client semantic attributes emitted by the Netty instrumentation.