Automatic Instrumentation

Supported Libraries and Frameworks

Akka HTTP10.0+
Apache HttpAsyncClient4.0+
Apache HttpClient2.0+
AWS Lambda1.0+
AWS SDK1.11.x and 2.2.0+
Cassandra Driver3.0+
Couchbase Client2.0+ (not including 3.x yet)
Dropwizard Views0.7+
Elasticsearch API5.0+ (not including 7.x yet)
Elasticsearch REST Client5.0+
Geode Client1.4+
Google HTTP Client1.19+
Grizzly2.0+ (disabled by default, see below)
Grizzly Client1.9+
HttpURLConnectionJava 7+
JAX-RS Client2.0+
JDBCJava 7+
Kubernetes Client7.0+
Lettuce4.0+ (not including 6.x yet)
Log4j 11.2+
Log4j 22.7+
MongoDB Drivers3.3+
Play2.3+ (not including 2.8.x yet)
Play WS1.0+
RabbitMQ Client2.7+
RMIJava 7+
Spark Web Framework2.3+
Spring Data1.8+
Spring Scheduling3.1+
Spring Web MVC3.1+
Spring Webflux5.0+
Twilio6.6+ (not including 8.x yet)
Vert.x RxJava23.5+

Disabled Instrumentations

Some instrumentations can produce too many spans and make traces very noisy. For this reason the following instrumentations are disabled by default:

  • jdbc-datasource which creates spans whenever java.sql.DataSource#getConnection method is called.
  • servlet-filter which creates spans around Servlet Filter methods.
  • servlet-service which creates spans around Servlet methods.

To enable them, add otel.integration.<name>.enabled system property: -Dotel.integration.jdbc-datasource.enabled=true

Grizzly Instrumentation

Whenever you use Grizzly for Servlet-based applications, you get better experience from Servlet-specific support. As these two instrumentations conflict with each other, more generic instrumentation for Grizzly http server is disabled by default. If needed, you can enable it by add the following system property: -Dotel.integration.grizzly.enabled=true

Suppressing Instrumentation

Specific Libraries

You can suppress auto-instrumentation of specific libraries by using -Dotel.integration.[id].enabled=false where id is the instrumentation id.

Specific Classes

You can also exclude specific classes from being instrumented. This can be useful for a few reasons including:

  • To completely silence spans from a given class/package.
  • As a quick workaround for an instrumentation bug, when byte code in one specific class is problematic.

This option should not be used lightly, as it can leave some instrumentation partially applied, which could have unknown side-effects.

System propertyEnvironment variablePurpose
otel.trace.classes.excludeOTEL_TRACE_CLASSES_EXCLUDESuppresses all instrumentation for specific classes, format is “my.package.MyClass,my.package2.*”

Logger MDC auto-instrumentation

The agent injects several pieces of information about the current span into each logging event’s MDC copy. As a result any services or tools that parse the application logs can correlate traces/spans with log statements.

  • traceId (same as Span.current().getSpanContext().getTraceIdAsHexString())
  • spanId (same as Span.current().getSpanContext().getSpanIdAsHexString())
  • sampled (same as Span.current().getSpanContext().isSampled())

This information can be included in log statements produced by the logging library by specifying them in the pattern/format.

Example for Spring Boot configuration (which uses logback):

logging.pattern.console = %d{yyyy-MM-dd HH:mm:ss} - %logger{36} - %msg t:%X{traceId} s:%X{spanId} %n

Supported logging libraries

Log4j 11.2+
Log4j 22.7+

Configuration Options

Configuration parameters names are very likely to change until GA.


The following configuration properties are common to all exporters:

System propertyEnvironment variablePurpose
otel.exporterOTEL_EXPORTERExporter to be used, can be a comma-separated list to use multiple exporters. Currently does not support multiple metric exporters. Defaults to otlp.

OTLP exporter (both span and metric exporters)

In order to configure the service name for the OTLP exporter, you must add key to the OpenTelemetry Resource (see below). For example:

System propertyEnvironment variablePurpose
otel.exporter=otlp (default)OTEL_EXPORTER=otlpTo select OpenTelemetry exporter (default)
otel.exporter.otlp.endpointOTEL_EXPORTER_OTLP_ENDPOINTThe OTLP endpoint to connect to, default is “localhost:55680”
otel.exporter.otlp.insecureOTEL_EXPORTER_OTLP_INSECUREWhether to enable client transport security for the connection
otel.exporter.otlp.headersOTEL_EXPORTER_OTLP_HEADERSThe key-value pairs separated by semicolon to pass as request headers
otel.exporter.otlp.timeoutOTEL_EXPORTER_OTLP_TIMEOUTThe max waiting time allowed to send each batch, default is 1000

Jaeger exporter

Currently only supports gRPC.

System propertyEnvironment variablePurpose
otel.exporter=jaegerOTEL_EXPORTER=jaegerTo select Jaeger exporter
otel.exporter.jaeger.endpointOTEL_EXPORTER_JAEGER_ENDPOINTThe Jaeger endpoint to connect to, default is “localhost:14250”, currently only gRPC is supported.
otel.exporter.jaeger.service.nameOTEL_EXPORTER_JAEGER_SERVICE_NAMEThe service name of this JVM instance, default is “unknown”.

Zipkin exporter

System propertyEnvironment variablePurpose
otel.exporter=zipkinOTEL_EXPORTER=zipkinTo select Zipkin exporter
otel.exporter.zipkin.endpointOTEL_EXPORTER_ZIPKIN_ENDPOINTThe Zipkin endpoint to connect to, default is “http://localhost:9411/api/v2/spans”. Currently only HTTP is supported.
otel.exporter.zipkin.service.nameOTEL_EXPORTER_ZIPKIN_SERVICE_NAMEThe service name of this JVM instance, default is “unknown”.

Prometheus exporter

System propertyEnvironment variablePurpose
otel.exporter=prometheusOTEL_EXPORTER=prometheusTo select Prometheus exporter
otel.exporter.prometheus.portOTEL_EXPORTER_PROMETHEUS_PORTThe local port used to bind the prometheus metric server, defaults to 9464
otel.exporter.prometheus.hostOTEL_EXPORTER_PROMETHEUS_HOSTThe local address used to bind the prometheus metric server, defaults to “”

Logging exporter

The logging exporter simply prints the name of the span along with its attributes to stdout. It is used mainly for testing and debugging.

System propertyEnvironment variablePurpose
otel.exporter=loggingOTEL_EXPORTER=loggingTo select logging exporter
otel.exporter.logging.prefixOTEL_EXPORTER_LOGGING_PREFIXAn optional string that is printed in front of the span name and attributes.


The propagator controls which distributed tracing header format is used.

If this is set to a comma-delimited list of the values, the multi-propagator will be used. The multi-propagator will try to extract the context from incoming requests using each of the configured propagator formats (in order), stopping after the first successful context extraction. The multi-propagator will inject the context into outgoing requests using all the configured propagator formats.

System propertyEnvironment variablePurpose
otel.propagatorsOTEL_PROPAGATORSDefault is “tracecontext” (W3C). Other supported values are “b3”, “b3single”, “jaeger”, “ottracer”, “xray”.

OpenTelemetry Resource

The OpenTelemetry Resource is a representation of the entity producing telemetry.

System propertyEnvironment variablePurpose
otel.resource.attributesOTEL_RESOURCE_ATTRIBUTESUsed to specify resource attributes in format: key1=val1,key2=val2,key3=val3

Peer service name

The peer service name is the name of a remote service that is being connected to. It corresponds to in the Resource for the local service.

System propertyEnvironment variablePurpose
otel.endpoint.peer.service.mappingOTEL_ENDPOINT_PEER_SERVICE_MAPPINGUsed to specify a mapping from hostnames or IP addresses to peer services, as a comma separated list of host=name pairs. The peer service name will be added as an attribute to a span whose host or IP match the mapping. For example, if set to,, requests to will have a peer.service attribute of cats-service and requests to will have one of dogs-api

Batch span processor

System propertyEnvironment variablePurpose
otel.bsp.schedule.delayOTEL_BSP_SCHEDULE_DELAYThe interval in milliseconds between two consecutive exports (default: 5000)
otel.bsp.max.queueOTEL_BSP_MAX_QUEUEMaximum queue size (default: 2048)
otel.bsp.max.export.batchOTEL_BSP_MAX_EXPORT_BATCHMaximum batch size (default: 512)
otel.bsp.export.timeoutOTEL_BSP_EXPORT_TIMEOUTMaximum allowed time in milliseconds to export data (default: 30000)
otel.bsp.export.sampledOTEL_BSP_EXPORT_SAMPLEDWhether only sampled spans should be exported (default: true)

Trace config

System propertyEnvironment variablePurpose
otel.config.sampler.probabilityOTEL_CONFIG_SAMPLER_PROBABILITYSampling probability between 0 and 1 (default: 1)
otel.config.max.attrsOTEL_CONFIG_MAX_ATTRSMaximum number of attributes per span (default: 32)
otel.config.max.eventsOTEL_CONFIG_MAX_EVENTSMaximum number of events per span (default: 128)
otel.config.max.linksOTEL_CONFIG_MAX_LINKSMaximum number of links per span (default: 32)
otel.config.max.event.attrsOTEL_CONFIG_MAX_EVENT_ATTRSMaximum number of attributes per event (default: 32) number of attributes per link (default: 32)

Interval metric reader

System propertyEnvironment variablePurpose
otel.imr.export.intervalOTEL_IMR_EXPORT_INTERVALThe interval in milliseconds between pushes to the exporter (default: 60000)

Customizing the OpenTelemetry SDK

This is highly advanced behavior and still in the prototyping phase. It may change drastically or be removed completely. Use with caution

The OpenTelemetry API exposes SPI hooks for customizing its behavior, such as the Resource attached to spans or the Sampler.

Because the auto instrumentation runs in a separate classpath than the instrumented application, it is not possible for customization in the application to take advantage of this customization. In order to provide such customization, you can provide the path to a JAR file including an SPI implementation using the system property otel.initializer.jar. Note that this JAR will need to shade the OpenTelemetry API in the same way as the agent does. The simplest way to do this is to use the same shading configuration as the agent from here. In addition, you will have to specify the to the name of the class that implements the SPI.

Manual Instrumentation

Starting with 0.6.0, and prior to version 1.0.0, opentelemetry-javaagent-all.jar only supports manual instrumentation using the opentelemetry-api version with the same version number as the Java agent you are using. Starting with 1.0.0, the Java agent will start supporting multiple (1.0.0+) versions of opentelemetry-api.

With auto-instrumentation it may be desirable to also add manual instrumentation. In this scenario, it is critical that both automatic and manual instrumentation stitch together properly. Two options exist to configure manual instrumentation with the appropriate span context:

  • @WithSpan annotation: Simply annotate the functions or methods you wish to instrument
  • getTracer: Traditional way to instrument with OpenTelemetry

Both options require a dependency on the opentelemetry-api library to get started.





dependencies {

Configure @WithSpan annotation

Add the trace annotation to your application’s code. Then, each time the application invokes the annotated method, it creates a span that denotes its duration and provides any thrown exceptions.


public class MyClass {
  public void MyLogic() {


An additional dependency is required for this annotation:

dependencies {

Suppressing @WithSpan instrumentation

This is useful in case you have code that is over-instrumented using @WithSpan, and you want to suppress some of them without modifying the code.

System propertyEnvironment variablePurpose
trace.annotated.methods.excludeTRACE_ANNOTATED_METHODS_EXCLUDESuppress @WithSpan instrumentation for specific methods, format is “my.package.MyClass1[method1,method2];my.package.MyClass2[method3]”

Configure the OpenTelemetry getTracer

See the Manual Instrumentation documentation for configuration information and examples.


To turn on the agent’s internal debug logging:


Note these logs are extremely verbose. Enable debug logging only when needed. Debug logging negatively impacts the performance of your application.