Skip to main content
Sumo Logic

Java OpenTelemetry auto-instrumentation

Perhaps the most convenient way to start capturing telemetry from Java (or, generally speaking, JVM) is to incorporate OpenTelemetry Instrumentation for Java. It automatically detects when one of the popular libraries is being used in the service and injects the instrumentation without writing any code. It’s also possible to mix automatic instrumentation with manual instrumentation if needed. This method works for all Java 7+ JVMs.

Installation

The Java agent and configuration needs to be provided for each of the monitored service instances. The address of the OpenTelemetry Collector (or Collector/Agent) needs to be prepared first (OPENTELEMETRY_COLLECTOR_HOSTNAME) and the desired name of the service (SERVICE_NAME). 

Step 1 - Download and distribute the agent JAR

The most recent version of the agent should be downloaded and distributed to each of the service hosts or containers, as the JVM will need access to it.

Step 2 - Update the JVM configuration (valid for versions 0.7.0 - 0.8.0)

Either of the following options could be used as the template, with the following changes:

  • The path to the javaagent JAR file needs to replaced with the location of the file downloaded and distributed in step 1.

  • OPENTELEMETRY_COLLECTOR_HOSTNAME must be provided with the location of the OpenTelemetry Collector/Agent or centralized collector (depending on which one is used). Refer to the following setup instructions if you don't have yet collector installed:

  • SERVICE_NAME needs to be replaced with the name used for the identification of the service.

Option 1 - leveraging environment variables

The following environment variables need to be made accessible by JVM:

JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent-all.jar"
OTEL_OTLP_ENDPOINT=OPENTELEMETRY_COLLECTOR_HOSTNAME:55680
OTEL_EXPORTER=otlp
OTEL_RESOURCE_ATTRIBUTES="service.name=SERVICE_NAME"

Option 2 - changing the java command line

The command line of the service needs to be appended with the following attributes:

java -javaagent:path/to/opentelemetry-javaagent-all.jar \
    -Dotel.exporter=otlp \
    -Dotel.otlp.endpoint=OPENTELEMETRY_COLLECTOR_HOSTNAME:55680 \
    -Dotel.resource.attributes="service.name=SERVICE_NAME" \

Step 3 (optional) - confirming that the instrumentation was installed

After starting the service with instrumentation enabled, the following log lines are to be expected in the console:

[opentelemetry.auto.trace 2020-08-26 12:15:10:343 +0200] [main] INFO io.opentelemetry.auto.tooling.TracerInstaller - Installed span exporter: io.opentelemetry.exporters.otlp.OtlpGrpcSpanExporter

[opentelemetry.auto.trace 2020-08-26 12:15:10:348 +0200] [main] INFO io.opentelemetry.auto.tooling.VersionLogger - opentelemetry-javaagent - version: 0.7.0~227bde87c

Custom tags configuration

If the default tags are not providing enough relevant data you can add custom tags or attributes into spans. Follow these steps:

Step 1 - Satisfy project dependencies - add opentelemetry-sdk library
  • Maven projects

<!-- https://mvnrepository.com/artifact/io.opentelemetry/opentelemetry-api -->
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk</artifactId>
    <version>0.8.0</version>
</dependency>

  • Gradle projects

dependencies {
 compile 'io.opentelemetry:opentelemetry-sdk:0.8.0'
}

Step 2 - Import dependencies in the application Java class file

import io.opentelemetry.OpenTelemetry;
import io.opentelemetry.trace.Tracer;

Step 3 - Declare the TRACER variable in the class

It is important to provide the class name into the OpenTelemetry.getTracer() method.

private static final Tracer TRACER = OpenTelemetry.getTracer(CLASS_NAME.class.toString());

Step 4 - Add custom tag into span

TRACER.getCurrentSpan().setAttribute("foo", "bar");