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:

Configuring the agent

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

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:

System property: otel.javaagent.configuration-fileEnvironment variable: OTEL_JAVAAGENT_CONFIGURATION_FILE

Description: Path to valid Java properties file which contains the agent configuration.

Extensions

You can enable extensions by setting the following property:

System property: otel.javaagent.extensionsEnvironment variable: OTEL_JAVAAGENT_EXTENSIONS

Description: Path to an extension jar file or folder, containing jar files. If pointing to a folder, every jar file in that folder will be treated as separate, independent extension.

Java agent logging output

The agent’s logging output can be configured by setting the following property:

System property: otel.javaagent.loggingEnvironment variable: OTEL_JAVAAGENT_LOGGING

Description: The Java agent logging mode. The following 3 modes are supported:

  • simple: The agent will print out its logs using the standard error stream. Only INFO or higher logs will be printed. This is the default Java agent logging mode.
  • none: The agent will not log anything - not even its own version.
  • application: The agent will attempt to redirect its own logs to the instrumented application's slf4j logger. This works the best for simple one-jar applications that do not use multiple classloaders; Spring Boot apps are supported as well. The Java agent output logs can be further configured using the instrumented application's logging configuration (e.g. logback.xml or log4j2.xml). Make sure to test that this mode works for your application before running it in a production environment.

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.

System property: otel.instrumentation.common.peer-service-mappingEnvironment variable: OTEL_INSTRUMENTATION_COMMON_PEER_SERVICE_MAPPING

Description: Used to specify a mapping from host names or IP addresses to peer services, as a comma-separated list of <host_or_ip>=<user_assigned_name> pairs. The peer service is added as an attribute to a span whose host or IP address match the mapping.

For example, if set to the following:

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

Then, requests to 1.2.3.4 will have a peer.service attribute of cats-service and requests to dogs-abcdef123.serverlessapis.com will have an attribute of dogs-api.

Since Java agent version 1.31.0, it is possible to provide a port and a path to define a peer.service.

For example, if set to the following:

1.2.3.4:443=cats-service,dogs-abcdef123.serverlessapis.com:80/api=dogs-api

Then, requests to 1.2.3.4 will have no override for peer.service attribute, while 1.2.3.4:443 will have have peer.service of cats-service and requests to dogs-abcdef123.serverlessapis.com:80/api/v1 will have an attribute of 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:

System property: otel.instrumentation.common.db-statement-sanitizer.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_DB_STATEMENT_SANITIZER_ENABLED

Default: true
Description: Enables the DB statement sanitization.

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:

System property: otel.instrumentation.http.client.capture-request-headersEnvironment variable: OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_REQUEST_HEADERS

Description: A comma-separated list of HTTP header names. HTTP client instrumentations will capture HTTP request header values for all configured header names.

System property: otel.instrumentation.http.client.capture-response-headersEnvironment variable: OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_RESPONSE_HEADERS

Description: A comma-separated list of HTTP header names. HTTP client instrumentations will capture HTTP response header values for all configured header names.

System property: otel.instrumentation.http.server.capture-request-headersEnvironment variable: OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS

Description: A comma-separated list of HTTP header names. HTTP server instrumentations will capture HTTP request header values for all configured header names.

System property: otel.instrumentation.http.server.capture-response-headersEnvironment variable: OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_RESPONSE_HEADERS

Description: A comma-separated list of HTTP header names. HTTP server instrumentations will capture HTTP response header values for all configured header names.

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:

System property: otel.instrumentation.servlet.experimental.capture-request-parametersEnvironment variable: OTEL_INSTRUMENTATION_SERVLET_EXPERIMENTAL_CAPTURE_REQUEST_PARAMETERS

Description: A comma-separated list of request parameter names.

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:

System property: otel.instrumentation.messaging.experimental.receive-telemetry.enabledEnvironment variable: OTEL_INSTRUMENTATION_MESSAGING_EXPERIMENTAL_RECEIVE_TELEMETRY_ENABLED

Default: false
Description: Enables the consumer message receive telemetry.

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.

System property: otel.instrumentation.common.enduser.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_ENDUSER_ENABLED

Default: false
Description: Common flag for enabling/disabling enduser attributes.

System property: otel.instrumentation.common.enduser.id.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_ENDUSER_ID_ENABLED

Default: false
Description: Determines whether to capture enduser.id semantic attribute.

System property: otel.instrumentation.common.enduser.role.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_ENDUSER_ROLE_ENABLED

Default: false
Description: Determines whether to capture enduser.role semantic attribute.

System property: otel.instrumentation.common.enduser.scope.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_ENDUSER_SCOPE_ENABLED

Default: false
Description: Determines whether to capture enduser.scope semantic attribute.

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:

System property: otel.instrumentation.spring-security.enduser.role.granted-authority-prefixEnvironment variable: OTEL_INSTRUMENTATION_SPRING_SECURITY_ENDUSER_ROLE_GRANTED_AUTHORITY_PREFIX

Default: ROLE_
Description: Prefix of granted authorities identifying roles to capture in the enduser.role semantic attribute.

System property: otel.instrumentation.spring-security.enduser.scope.granted-authority-prefixEnvironment variable: OTEL_INSTRUMENTATION_SPRING_SECURITY_ENDUSER_SCOPE_GRANTED_AUTHORITY_PREFIX

Default: SCOPE_
Description: Prefix of granted authorities identifying scopes to capture in the enduser.scopes semantic attribute.

Suppressing specific auto-instrumentation

Disabling the agent entirely

System property: otel.javaagent.enabledEnvironment variable: OTEL_JAVAAGENT_ENABLED

Description: Set the value to false to disable 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.

System property: otel.instrumentation.common.default-enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED

Description: Set to false to disable all instrumentation in the agent.

System property: otel.instrumentation.[name].enabledEnvironment variable: OTEL_INSTRUMENTATION_[NAME]_ENABLED

Description: Set to true to enable each desired instrumentation individually.

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.

System property: otel.instrumentation.[name].enabledEnvironment variable: OTEL_INSTRUMENTATION_[NAME]_ENABLED

Description: Set to false to suppress agent instrumentation of specific libraries, where [name] is the corresponding instrumentation name:

Library/FrameworkInstrumentation name
Additional methods tracingmethods
Additional tracing annotationsexternal-annotations
Akka Actorakka-actor
Akka HTTPakka-http
Apache Axis2axis2
Apache Camelcamel
Apache Cassandracassandra
Apache CXFcxf
Apache DBCPapache-dbcp
Apache Dubboapache-dubbo
Apache Geodegeode
Apache HttpAsyncClientapache-httpasyncclient
Apache HttpClientapache-httpclient
Apache Kafkakafka
Apache MyFacesjsf-myfaces
Apache Pekko Actorpekko-actor
Apache Pekko HTTPpekko-http
Apache Pulsarpulsar
Apache RocketMQrocketmq-client
Apache Struts 2struts
Apache Tapestrytapestry
Apache Tomcattomcat
Apache Wicketwicket
Armeriaarmeria
AsyncHttpClient (AHC)async-http-client
AWS Lambdaaws-lambda
AWS SDKaws-sdk
Azure SDKazure-core
Couchbasecouchbase
C3P0c3p0
Dropwizard Viewsdropwizard-views
Dropwizard Metricsdropwizard-metrics
Eclipse Grizzlygrizzly
Eclipse Jerseyjersey
Eclipse Jettyjetty
Eclipse Jetty HTTP Clientjetty-httpclient
Eclipse Metrometro
Eclipse Mojarrajsf-mojarra
Eclipse Vert.x HttpClientvertx-http-client
Eclipse Vert.x Kafka Clientvertx-kafka-client
Eclipse Vert.x RxJavavertx-rx-java
Eclipse Vert.x Webvertx-web
Elasticsearch clientelasticsearch-transport
Elasticsearch REST clientelasticsearch-rest
Google Guavaguava
Google HTTP clientgoogle-http-client
Google Web Toolkitgwt
Grailsgrails
GraphQL Javagraphql-java
GRPCgrpc
Hibernatehibernate
HikariCPhikaricp
Java HTTP Clientjava-http-client
Java HttpURLConnectionhttp-url-connection
Java JDBCjdbc
Java JDBC DataSourcejdbc-datasource
Java RMIrmi
Java Runtimeruntime-telemetry
Java Servletservlet
java.util.concurrentexecutors
java.util.loggingjava-util-logging
JAX-RS (Client)jaxrs-client
JAX-RS (Server)jaxrs
JAX-WSjaxws
JBoss Logging Appenderjboss-logmanager-appender
JBoss Logging MDCjboss-logmanager-mdc
JMSjms
Jodd HTTPjodd-http
JSPjsp
K8s Clientkubernetes-client
kotlinx.coroutineskotlinx-coroutines
Log4j Appenderlog4j-appender
Log4j MDC (1.x)log4j-mdc
Log4j Context Data (2.x)log4j-context-data
Logback Appenderlogback-appender
Logback MDClogback-mdc
Micrometermicrometer
MongoDBmongo
Netflix Hystrixhystrix
Nettynetty
OkHttpokhttp
OpenLibertyliberty
OpenTelemetry Extension Annotationsopentelemetry-extension-annotations
OpenTelemetry Instrumentation Annotationsopentelemetry-instrumentation-annotations
OpenTelemetry APIopentelemetry-api
Oracle UCPoracle-ucp
OSHI (Operating System and Hardware Information)oshi
Play Frameworkplay
Play WS HTTP Clientplay-ws
Quartzquartz
R2DBCr2dbc
RabbitMQ Clientrabbitmq
Ratpackratpack
ReactiveX RxJavarxjava
Reactorreactor
Reactor Nettyreactor-netty
Redis Jedisjedis
Redis Lettucelettuce
Rediscalarediscala
Redissonredisson
Restletrestlet
Scala ForkJoinPoolscala-fork-join
Spark Web Frameworkspark
Spring Batchspring-batch
Spring Corespring-core
Spring Dataspring-data
Spring JMSspring-jms
Spring Integrationspring-integration
Spring Kafkaspring-kafka
Spring RabbitMQspring-rabbit
Spring RMIspring-rmi
Spring Schedulingspring-scheduling
Spring Webspring-web
Spring WebFluxspring-webflux
Spring Web MVCspring-webmvc
Spring Web Servicesspring-ws
Spymemcachedspymemcached
Tomcat JDBCtomcat-jdbc
Twilio SDKtwilio
Twitter Finatrafinatra
Undertowundertow
Vaadinvaadin
Vibur DBCPvibur-dbcp
ZIOzio

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.

System property: otel.instrumentation.common.experimental.controller-telemetry.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_EXPERIMENTAL_CONTROLLER_TELEMETRY_ENABLED

Default: true
Description: Enables the controller telemetry.

System property: otel.instrumentation.common.experimental.view-telemetry.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_EXPERIMENTAL_VIEW_TELEMETRY_ENABLED

Default: true
Description: Enables the view telemetry.

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:

System property: otel.instrumentation.experimental.span-suppression-strategyEnvironment variable: OTEL_INSTRUMENTATION_EXPERIMENTAL_SPAN_SUPPRESSION_STRATEGY

Description: The Java agent span suppression strategy. The following 3 strategies are supported:

  • semconv: The agent will suppress duplicate semantic conventions. This is the default behavior of the Java agent.
  • span-kind: The agent will suppress spans with the same kind (except INTERNAL).
  • none: The agent will not suppress anything at all. We do not recommend using this option for anything other than debug purposes, as it generates lots of duplicate telemetry data.

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.