---

Getting Started   •   Getting Involved   •   Getting In Touch

Contributing   •   Scope   •   Roadmap

---

OpenTelemetry Instrumentation for Java

This project provides a Java agent JAR that can be attached to any Java 8+ application and dynamically injects bytecode to capture telemetry from a number of popular libraries and frameworks. You can export the telemetry data in a variety of formats. You can also configure the agent and exporter via command line arguments or environment variables. The net result is the ability to gather telemetry data from a Java application without code changes.

Getting Started

Download the latest version.

This package includes the instrumentation agent as well as instrumentations for all supported libraries and all available data exporters. The package provides a completely automatic, out-of-the-box experience.

Enable the instrumentation agent using the -javaagent flag to the JVM.

java -javaagent:path/to/opentelemetry-javaagent-all.jar \
     -jar myapp.jar

By default, the OpenTelemetry Java agent uses OTLP exporter configured to send data to OpenTelemetry collector at localhost:55680.

Configuration parameters are passed as Java system properties (-D flags) or as environment variables. See below for a full list of environment variables. For example:

java -javaagent:path/to/opentelemetry-javaagent-all.jar \
     -Dotel.exporter=zipkin \
     -jar myapp.jar

Specify the external exporter JAR file using the otel.exporter.jar system property:

java -javaagent:path/to/opentelemetry-javaagent-all.jar \
     -Dotel.exporter.jar=path/to/external-exporter.jar \
     -jar myapp.jar

Configuration parameters (subject to change!)

Note: These parameter names are very likely to change over time, so please check back here when trying out a new version! Please report any bugs or unexpected behavior you find.

Exporters

The following configuration properties are common to all exporters:

System property	Environment variable	Purpose
otel.exporter	OTEL_EXPORTER	The exporter to be used. Use a comma-separated list for multiple exporters. Currently does not support multiple metric exporters. Default is otlp.

OTLP exporter (both span and metric exporters)

A simple wrapper for the OpenTelemetry Protocol (OTLP) span and metric exporters of opentelemetry-java.

System property	Environment variable	Description
otel.exporter=otlp (default)	OTEL_EXPORTER=otlp	Select the OpenTelemetry exporter (default)
otel.exporter.otlp.endpoint	OTEL_EXPORTER_OTLP_ENDPOINT	The OTLP endpoint to connect to. Default is localhost:55680.
otel.exporter.otlp.insecure	OTEL_EXPORTER_OTLP_INSECURE	Whether to enable client transport security for the connection
otel.exporter.otlp.headers	OTEL_EXPORTER_OTLP_HEADERS	Key-value pairs separated by semicolons to pass as request headers
otel.exporter.otlp.timeout	OTEL_EXPORTER_OTLP_TIMEOUT	The maximum waiting time allowed to send each batch. Default is 1000.

To configure the service name for the OTLP exporter, add the service.name key to the OpenTelemetry Resource (see below), e.g. OTEL_RESOURCE_ATTRIBUTES=service.name=myservice.

Jaeger exporter

A simple wrapper for the Jaeger exporter of opentelemetry-java. This exporter uses gRPC for its communications protocol.

System property	Environment variable	Description
otel.exporter=jaeger	OTEL_EXPORTER=jaeger	Select the Jaeger exporter
otel.exporter.jaeger.endpoint	OTEL_EXPORTER_JAEGER_ENDPOINT	The Jaeger gRPC endpoint to connect to. Default is localhost:14250.
otel.exporter.jaeger.service.name	OTEL_EXPORTER_JAEGER_SERVICE_NAME	The service name of this JVM instance. Default is unknown.

Jaeger Thrift over HTTP exporter

A simple wrapper for the Jaeger exporter, but using Thrift encoded payloads over HTTP.

System property	Environment variable	Description
otel.exporter=jaeger-thrift	OTEL_EXPORTER=jaeger-thrift	Select the Jaeger HTTP Thrift exporter
otel.exporter.jaeger.endpoint	OTEL_EXPORTER_JAEGER_ENDPOINT	The Jaeger HTTP endpoint to send thrift data to. Default is http://localhost:14268/api/traces.
otel.exporter.jaeger.service.name	OTEL_EXPORTER_JAEGER_SERVICE_NAME	The service name of this JVM instance. Default is unknown.

Zipkin exporter

A simple wrapper for the Zipkin exporter of opentelemetry-java. It sends JSON in Zipkin format to a specified HTTP URL.

System property	Environment variable	Description
otel.exporter=zipkin	OTEL_EXPORTER=zipkin	Select the Zipkin exporter
otel.exporter.zipkin.endpoint	OTEL_EXPORTER_ZIPKIN_ENDPOINT	The Zipkin endpoint to connect to. Default is http://localhost:9411/api/v2/spans. Currently only HTTP is supported.
otel.exporter.zipkin.service.name	OTEL_EXPORTER_ZIPKIN_SERVICE_NAME	The service name of this JVM instance. Default is unknown.

Prometheus exporter

A simple wrapper for the Prometheus exporter of opentelemetry-java.

System property	Environment variable	Description
otel.exporter=prometheus	OTEL_EXPORTER=prometheus	Select the Prometheus exporter
otel.exporter.prometheus.port	OTEL_EXPORTER_PROMETHEUS_PORT	The local port used to bind the prometheus metric server. Default is 9464.
otel.exporter.prometheus.host	OTEL_EXPORTER_PROMETHEUS_HOST	The local address used to bind the prometheus metric server. Default is 0.0.0.0.

Logging exporter

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

System property	Environment variable	Description
otel.exporter=logging	OTEL_EXPORTER=logging	Select the logging exporter
otel.exporter.logging.prefix	OTEL_EXPORTER_LOGGING_PREFIX	An optional string printed in front of the span name and attributes.

Propagator

The propagators determine which distributed tracing header formats are used, and which baggage propagation header formats are used.

System property	Environment variable	Description
otel.propagators	OTEL_PROPAGATORS	The propagators to be used. Use a comma-separated list for multiple propagators. Supported propagators are tracecontext, baggage, b3, b3multi, jaeger, ottracer, and xray. Default is tracecontext,baggage (W3C).

OpenTelemetry Resource

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

System property	Environment variable	Description
otel.resource.attributes	OTEL_RESOURCE_ATTRIBUTES	Specify resource attributes in the following format: key1=val1,key2=val2,key3=val3

Peer service name

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

System property	Environment variable	Description
otel.endpoint.peer.service.mapping	OTEL_ENDPOINT_PEER_SERVICE_MAPPING	Used to specify a mapping from hostnames or IP addresses to peer services, as a comma-separated list of host=name pairs. The peer service is added as an attribute to a span whose host or IP match the mapping. For example, if set to 1.2.3.4=cats-service,dogs-abcdef123.serverlessapis.com=dogs-api, 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.

Batch span processor

System property	Environment variable	Description
otel.bsp.schedule.delay	OTEL_BSP_SCHEDULE_DELAY	The interval, in milliseconds, between two consecutive exports. Default is 5000.
otel.bsp.max.queue	OTEL_BSP_MAX_QUEUE	The maximum queue size. Default is 2048.
otel.bsp.max.export.batch	OTEL_BSP_MAX_EXPORT_BATCH	The maximum batch size. Default is 512.
otel.bsp.export.timeout	OTEL_BSP_EXPORT_TIMEOUT	The maximum allowed time, in milliseconds, to export data. Default is 30000.
otel.bsp.export.sampled	OTEL_BSP_EXPORT_SAMPLED	Whether only sampled spans should be exported. Default is true.

Trace config

System property	Environment variable	Description
otel.config.sampler.probability	OTEL_CONFIG_SAMPLER_PROBABILITY	Sampling probability between 0 and 1. Default is 1.
otel.config.max.attrs	OTEL_CONFIG_MAX_ATTRS	The maximum number of attributes per span. Default is 32.
otel.config.max.events	OTEL_CONFIG_MAX_EVENTS	The maximum number of events per span. Default is 128.
otel.config.max.links	OTEL_CONFIG_MAX_LINKS	The maximum number of links per span. Default is 32
otel.config.max.event.attrs	OTEL_CONFIG_MAX_EVENT_ATTRS	The maximum number of attributes per event. Default is 32.
otel.config.max.link.attrs	OTEL_CONFIG_MAX_LINK_ATTRS	The maximum number of attributes per link. Default is 32.

Interval metric reader

System property	Environment variable	Description
otel.imr.export.interval	OTEL_IMR_EXPORT_INTERVAL	The interval, in milliseconds, between pushes to the exporter. Default is 60000.

Customizing the OpenTelemetry SDK

Customizing the SDK is highly advanced behavior and is 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 automatic instrumentation runs in a different 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 needs 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 must specify the io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.spi.TraceProvider to the name of the class that implements the SPI.

Supported Java libraries and frameworks

Library/Framework	Versions
Akka HTTP	10.0+
Apache HttpAsyncClient	4.1+
Apache HttpClient	2.0+
Armeria	0.99.8+
AsyncHttpClient	1.9+ (not including 2.x yet)
AWS Lambda	1.0+
AWS SDK	1.11.x and 2.2.0+
Cassandra Driver	3.0+
Couchbase Client	2.0+ (not including 3.x yet)
Dropwizard Views	0.7+
Elasticsearch API	5.0+ (not including 7.x yet)
Elasticsearch REST Client	5.0+
Finatra	2.9+
Geode Client	1.4+
Google HTTP Client	1.19+
Grizzly	2.0+ (disabled by default, see below)
gRPC	1.5+
Hibernate	3.3+
HttpURLConnection	Java 7+
http4k †	3.270.0+
Hystrix	1.4+
JAX-RS	0.5+
JAX-RS Client	2.0+
JDBC	Java 7+
Jedis	1.4+
Jetty	8.0+
JMS	1.1+
JSP	2.3+
Kafka	0.11+
khttp	0.1+
Kubernetes Client	7.0+
Lettuce	4.0+ (not including 6.x yet)
Log4j 1	1.2+
Log4j 2	2.7+
Logback	1.0+
MongoDB Drivers	3.3+
Netty	3.8+
OkHttp	3.0+
Play	2.3+ (not including 2.8.x yet)
Play WS	1.0+
RabbitMQ Client	2.7+
Ratpack	1.4+
Reactor	3.1+
Reactor Netty	0.9+ (not including 1.0)
Rediscala	1.8+
Redisson	3.0+
RMI	Java 7+
RxJava	1.0+
Servlet	2.2+
Spark Web Framework	2.3+
Spring Batch	3.0+
Spring Data	1.8+
Spring Scheduling	3.1+
Spring Web MVC	3.1+
Spring Webflux	5.0+
Spymemcached	2.12+
Struts2	2.3+
Twilio	6.6+ (not including 8.x yet)
Vert.x	3.0+
Vert.x RxJava2	3.5+

^† OpenTelemetry support provided by the library

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 the java.sql.DataSource#getConnection method is called.

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

Grizzly instrumentation

When 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 adding the following system property: -Dotel.instrumentation.grizzly.enabled=true

Suppressing specific auto-instrumentation

See Suppressing specific auto-instrumentation

Logger MDC auto-instrumentation

See Logger MDC auto-instrumentation

Manually instrumenting

⚠️ 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.

You'll need to add a dependency on the opentelemetry-api library to get started.

Maven

  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>0.11.0</version>
    </dependency>
  </dependencies>

Gradle

dependencies {
    compile('io.opentelemetry:opentelemetry-api:0.11.0')
}

Now you can use the OpenTelemetry getTracer or the @WithSpan annotation to manually instrument your Java application.

Configure the OpenTelemetry getTracer

OpenTelemetry offers a tracer to easily enable custom instrumentation throughout your application. See the OpenTelemetry Java QuickStart for an example of how to configure the tracer.

Configure a WithSpan annotation

If you want to configure custom instrumentation and don't want to use the OpenTelemetry getTracer and API directly, configure a @WithSpan annotation. Add the trace annotation to your application's code:

import io.opentelemetry.extension.annotations.WithSpan;

public class MyClass {
  @WithSpan
  public void MyLogic() {
      <...>
  }
}

You'll also need to add a dependency for this annotation:

Maven

  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-extension-annotations</artifactId>
      <version>0.11.0</version>
    </dependency>
  </dependencies>

Gradle

dependencies {
    compile('io.opentelemetry:opentelemetry-extension-annotations:0.11.0')
}

Each time the application invokes the annotated method, it creates a span that denote its duration and provides any thrown exceptions.

Suppressing @WithSpan instrumentation

Suppressing @WithSpan is useful if you have code that is over-instrumented using @WithSpan and you want to suppress some of them without modifying the code.

System property	Environment variable	Purpose
trace.annotated.methods.exclude	TRACE_ANNOTATED_METHODS_EXCLUDE	Suppress @WithSpan instrumentation for specific methods.
Format is "my.package.MyClass1[method1,method2];my.package.MyClass2[method3]"

Troubleshooting

To turn on the agent's internal debug logging:

-Dotel.javaagent.debug=true

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

Roadmap to 1.0 (GA)

See GA Requirements

Contributing

See CONTRIBUTING.md.

Approvers (@open-telemetry/java-instrumentation-approvers):

• John Watson, Splunk
• Mateusz Rzeszutek, Splunk

Maintainers (@open-telemetry/java-instrumentation-maintainers):

• Anuraag Agrawal, AWS
• Nikita Salnikov-Tarnovski, Splunk
• Trask Stalnaker, Microsoft
• Tyler Benson, DataDog

Learn more about roles in the community repository.

Thanks to all the people who already contributed!