opentelemetry-java-instrumentation/README.md

OpenTelemetry Auto-Instrumentation for Java

Introduction

This project provides a Java agent that can be attached to any Java 7+ application and dynamically injects bytecode to capture telemetry from a number of popular libraries and frameworks.

Supported Java libraries and frameworks

Library/Framework	Versions
Akka HTTP	10.0+
Apache HttpAsyncClient	4.0+
Apache HttpClient	2.0+
AWS SDK	1.11.x and 2.2.0+
Cassandra Driver	3.0+ (not including 4.x yet)
Couchbase Client	2.0+ (not including 3.x yet)
Dropwizard Views	0.7+
Elasticsearch API	2.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+
gRPC	1.5+
Hibernate	3.3+
HttpURLConnection	Java 7+
Hystrix	1.4+
java.util.logging	Java 7+
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+
Lettuce	5.0+
Log4j	1.1+
Logback	1.0+
MongoDB Drivers	3.3+
Netty	4.0+
OkHttp	3.0+
Play	2.4+ (not including 2.8.x yet)
Play WS	1.0+
Project Reactor	3.1+
RabbitMQ Client	2.7+
Ratpack	1.4+
RMI	Java 7+
RxJava	1.0+
Servlet	2.3+
Spark Web Framework	2.3+
Spring Data	1.8+
Spring Scheduling	3.1+
Spring Servlet MVC	3.1+
Spring Webflux	5.0+
Spymemcached	2.12+
Twilio	6.6+

Download and run

Download the latest release.

The instrumentation agent is enabled using the -javaagent flag to the JVM. Configuration parameters are passed as Java system properties (-D flags) or as environment variables. This is an example:

java -javaagent:path/to/opentelemetry-auto-<version>.jar \
     -Dota.exporter.jar=path/to/opentelemetry-auto-exporters-jaeger-<version>.jar \
     -Dota.exporter.jaeger.endpoint=localhost:14250 \
     -Dota.exporter.jaeger.service.name=shopping \
     -jar myapp.jar

Configuration parameters (subject to change!)

System property	Environment variable	Purpose
ota.exporter.jar	OTA_EXPORTER_JAR	Path to the exporter fat-jar that you want to use

Available exporters

There are three exporters available under releases.

Jaeger exporter

A simple wrapper for the Jaeger exporter of opentelemetry-java. It currently only supports gRPC as its communications protocol.

System property	Environment variable	Purpose
ota.exporter.jaeger.endpoint	OTA_EXPORTER_JAEGER_ENDPOINT	The Jaeger endpoint to connect to. Currently only gRPC is supported.
ota.exporter.jaeger.service.name	OTA_EXPORTER_JAEGER_SERVICE_NAME	The service name of this JVM instance

OTLP exporter

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

System property	Environment variable	Purpose
ota.exporter.otlp.endpoint	OTA_EXPORTER_OTLP_ENDPOINT	The OTLP endpoint to connect to.

Logging Exporter

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

System property	Environment variable	Purpose
ota.exporter.logging.prefix	OTA_EXPORTER_LOGGING_PREFIX	An optional string that is printed in front of the span name and attributes.

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 may find.

Building from source

Build using Java 8:

gradle assemble

and then you can find the java agent artifact at java-agent/build/lib/opentelemetry-auto-<version>.jar.