Getting Started   •   Getting Involved   •   Getting In Touch

Contributing   •   Scope   •   Roadmap

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.

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 http:https://localhost:4317.

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

Learn how to add custom instrumentation in the Manually Instrumenting section.

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.

The following configuration properties are common to all exporters:

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

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.

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

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

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

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

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

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

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.

Supported values for otel.trace.sampler are

• "always_on": AlwaysOnSampler
• "always_off": AlwaysOffSampler
• "traceidratio": TraceIdRatioBased. otel.trace.sampler.arg sets the ratio.
• "parentbased_always_on": ParentBased(root=AlwaysOnSampler)
• "parentbased_always_off": ParentBased(root=AlwaysOffSampler)
• "parentbased_traceidratio": ParentBased(root=TraceIdRatioBased). otel.trace.sampler.arg sets the ratio.

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

⚠️ 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; if you intend to use the @WithSpan annotation, also include the opentelemetry-extension-annotations dependency.

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

dependencies {
    implementation('io.opentelemetry:opentelemetry-api:0.15.0')
    implementation('io.opentelemetry:opentelemetry-extension-annotations:0.15.0')
}

A common need when instrumenting an application is to capture additional application-specific or business-specific information as additional attributes to an existing span from the automatic instrumentation. Grab the current span with Span.current() and use the setAttribute() methods:

import io.opentelemetry.api.trace.Span;

// ...

Span span = Span.current();
span.setAttribute(..., ...);

Another common situation is to capture a span around an existing first-party code method. The @WithSpan annotation makes this straightforward:

import io.opentelemetry.extension.annotations.WithSpan;

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

Each time the application invokes the annotated method, it creates a span that denote its duration and provides any thrown exceptions. Unless specified as an argument to the annotation, the span name will be <className>.<methodName>.

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.

This is a way to to create a span around a first-party code method without using @WithSpan.

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 and use the Tracer, Scope and Span interfaces to instrument your application.

These are the supported libraries and frameworks:

^† OpenTelemetry support provided by the library

These are the supported application servers:

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

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

See Suppressing specific auto-instrumentation

See Logger MDC auto-instrumentation

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.

See GA Requirements

See CONTRIBUTING.md.

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

• John Watson, Splunk
• Mateusz Rzeszutek, Splunk
• Pavol Loffay, Traceable.ai

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!