Skip to content

Latest commit

 

History

History
424 lines (325 loc) · 32.2 KB

README.md

File metadata and controls

424 lines (325 loc) · 32.2 KB
Raw

Getting Started   •   Getting Involved   •   Getting In Touch

Build Status GitHub release (latest by date including pre-releases) Bintray Beta

Contributing   •   Scope   •   Roadmap

OpenTelemetry Icon 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. The telemetry data can be exported in a variety of formats. In addition, the agent and exporter can be configured 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, instrumentations for all supported libraries and all available data exporters. This provides completely automatic out of the box experience.

The instrumentation agent is enabled using the -javaagent flag to the JVM.

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

By default 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 full list). For example:

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

External exporter jar can be specified via 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 may find.

Exporters

The following configuration properties are common to all exporters:

System property Environment variable Purpose
otel.exporter OTEL_EXPORTER To select exporter e.g. otlp,jaeger. Defaults to otlp
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
otel.exporter=jaeger OTEL_EXPORTER=jaeger To select Jaeger exporter
otel.jaeger.endpoint OTEL_JAEGER_ENDPOINT The Jaeger endpoint to connect to, default is "localhost:14250", currently only gRPC is supported.
otel.jaeger.service.name OTEL_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 POSTs json in Zipkin format to a specified HTTP URL.

System property Environment variable Purpose
otel.exporter=zipkin OTEL_EXPORTER=zipkin To select Zipkin exporter
otel.zipkin.endpoint OTEL_ZIPKIN_ENDPOINT The Zipkin endpoint to connect to, default is "http://localhost:9411/api/v2/spans". Currently only HTTP is supported.
otel.zipkin.service.name OTEL_ZIPKIN_SERVICE_NAME The service name of this JVM instance, default is "unknown".
OTLP exporter

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

System property Environment variable Purpose
otel.exporter=otlp (default) OTEL_EXPORTER=otlp To select OpenTelemetry exporter (default)
otel.otlp.endpoint OTEL_OTLP_ENDPOINT The OTLP endpoint to connect to, default is "localhost:55680"
otel.otlp.use.tls OTEL_OTLP_USE_TLS To use or not TLS, default is false.
otel.otlp.metadata OTEL_OTLP_METADATA The key-value pairs separated by semicolon to pass as request metadata.
otel.otlp.span.timeout OTEL_OTLP_SPAN_TIMEOUT The max waiting time allowed to send each span batch, default is 1000.

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

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 property Environment variable Purpose
otel.exporter=logging OTEL_EXPORTER=logging To select logging exporter
otel.exporter.logging.prefix OTEL_EXPORTER_LOGGING_PREFIX An optional string that is printed in front of the span name and attributes.

Propagator

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 property Environment variable Purpose
otel.propagators OTEL_PROPAGATORS Default 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 property Environment variable Purpose
otel.resource.attributes OTEL_RESOURCE_ATTRIBUTES Used 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 service.name in the Resource for the local service.

System property Environment variable Purpose
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 name will be 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 one of dogs-api

Batch span processor

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

Trace config

System property Environment variable Purpose
otel.config.sampler.probability OTEL_CONFIG_SAMPLER_PROBABILITY Sampling probability between 0 and 1 (default: 1)
otel.config.max.attrs OTEL_CONFIG_MAX_ATTRS Maximum number of attributes per span (default: 32)
otel.config.max.events OTEL_CONFIG_MAX_EVENTS Maximum number of events per span (default: 128)
otel.config.max.links OTEL_CONFIG_MAX_LINKS Maximum number of links per span (default: 32)
otel.config.max.event.attrs OTEL_CONFIG_MAX_EVENT_ATTRS Maximum number of attributes per event (default: 32)
otel.config.max.link.attrs OTEL_CONFIG_MAX_LINK_ATTRS Maximum number of attributes per link (default: 32)

Interval metric reader

System property Environment variable Purpose
otel.imr.export.interval OTEL_IMR_EXPORT_INTERVAL The 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 io.opentelemetry.javaagent.shaded.io.opentelemetry.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.0+
Apache HttpClient 2.0+
Armeria 0.99.8+
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)
Grizzly Client 1.9+
gRPC 1.5+
Hibernate 3.3+
HttpURLConnection Java 7+
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+
Rediscala 1.8+
RMI Java 7+
RxJava 1.0+
Servlet 2.2+
Spark Web Framework 2.3+
Spring Data 1.8+
Spring Scheduling 3.1+
Spring Web MVC 3.1+
Spring Webflux 5.0+
Spymemcached 2.12+
Twilio 6.6+ (not including 8.x yet)
Vert.x 3.0+
Vert.x RxJava2 3.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 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.7.0</version>
    </dependency>
  </dependencies>

Gradle

dependencies {
    compile('io.opentelemetry:opentelemetry-api:0.7.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 it.

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.extensions.auto.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-auto-annotations</artifactId>
      <version>0.7.0</version>
    </dependency>
  </dependencies>

Gradle

dependencies {
    compile('io.opentelemetry:opentelemetry-extension-auto-annotations:0.7.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

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 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:

-Dio.opentelemetry.javaagent.slf4j.simpleLogger.defaultLogLevel=debug

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):

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

Learn more about roles in the community repository.

Thanks to all the people who already contributed!