Automatic Instrumentation

Automatic instrumentation with Java uses a Java agent JAR that can be attached to any Java 8+ application. It dynamically injects bytecode to capture telemetry from many popular libraries and frameworks. It can be used to capture telemetry data at the “edges” of an app or service, such as inbound requests, outbound HTTP calls, database calls, and so on. To learn how to manually instrument your service or app code, see Manual instrumentation.

Setup

1. Download opentelemetry-javaagent.jar from Releases of the opentelemetry-java-instrumentation repository and place the JAR in your preferred directory. The JAR file contains the agent and instrumentation libraries.

2. Add -javaagent:path/to/opentelemetry-javaagent.jar and other config to your JVM startup arguments and launch your app:

   • Directly on the startup command:

     java -javaagent:path/to/opentelemetry-javaagent.jar -Dotel.service.name=your-service-name -jar myapp.jar
     

   • Via the JAVA_TOOL_OPTIONS and other environment variables:

     export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
     export OTEL_SERVICE_NAME="your-service-name"
     java -jar myapp.jar
     

Configuring the agent

The agent is highly configurable.

One option is to pass configuration properties via the -D flag. In this example, a service name and Zipkin exporter for traces are configured:

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.service.name=your-service-name \
     -Dotel.traces.exporter=zipkin \
     -jar myapp.jar

You can also use environment variables to configure the agent:

OTEL_SERVICE_NAME=your-service-name \
OTEL_TRACES_EXPORTER=zipkin \
java -javaagent:path/to/opentelemetry-javaagent.jar \
     -jar myapp.jar

You can also supply a Java properties file and load configuration values from there:

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.javaagent.configuration-file=path/to/properties/file.properties \
     -jar myapp.jar

or

OTEL_JAVAAGENT_CONFIGURATION_FILE=path/to/properties/file.properties \
java -javaagent:path/to/opentelemetry-javaagent.jar \
     -jar myapp.jar

To see the full range of configuration options, see Agent Configuration.

Supported libraries, frameworks, application services, and JVMs

The Java agent ships with instrumentation libraries for many popular components. For the full list, see Supported libraries, frameworks, application services, and JVMs.

Troubleshooting

Next steps

After you have automatic instrumentation configured for your app or service, you might want to annotate selected methods or add manual instrumentation to collect custom telemetry data.