Setup and Install OpenTelemetry Java

Get up and running with OpenTelemetry in just a few quick steps! The setup process consists of two phases--getting OpenTelemetry installed and configured, and then validating that configuration to ensure that data is being sent as expected.

This guide explains how to install, configure, and validate your OpenTelemetry setup. The OpenTelemetry Java Agent automatically captures telemetry from your application's libraries, frameworks, and environment.

Requirements

  • Java version 8 or newer.
  • A service to add OpenTelemetry to. You can use this example application or bring your own.
  • A Lightstep account, or another OpenTelemetry backend.

Need an account? Create a free Lightstep account here.

Installation

To make OpenTelemetry easier to install, we recommend the handy OTel-Launchers from Lightstep (us!).

Run OpenTelemetry

Once you’ve downloaded the launcher, you can integrate it into your application either via Java code, or by running the launcher as a javaagent from the command line.

The full list of configuration options can be found in the README.

LS Note: When connecting to Lightstep, a project Access Token is required.

Java agent approach:

export LS_ACCESS_TOKEN=your-token
export LS_SERVICE_NAME=service-name
java -javaagent:path/to/lightstep-opentelemetry-javaagent-0.8.1.jar \
     -jar myapp.jar

If automatic instrumentation is all you want, then adding the agent is all you need to do. However, at some point you will most likely want to add instrumetnation to your own application code. To do this, you need to add two dependencies to your POM file.

pom.xml dependency:

<dependency>
   <groupId>io.opentelemetry</groupId>
   <artifactId>opentelemetry-extension-auto-annotations</artifactId>
   <version>0.8.0</version>
 </dependency>
 <dependency>
   <groupId>io.opentelemetry</groupId>
   <artifactId>opentelemetry-api</artifactId>
   <version>0.8.0</version>
 </dependency>

Validate Installation

With your application running, you can now verify that you’ve installed OpenTelemetry correctly by confirming that telemetry data is being reported to your observability backend.

To do this, you need to make sure that your application is actually generating data. Applications will generally not produce traces unless they are being interacted with, and opentelemetry will often buffer data before sending it. So it may take some amount of time and interaction before your application data begins to appear in your backend..

Validate your traces in Lightstep:

  1. Trigger an action in your app that generates a web request.
  2. In Lightstep, click on the Explorer in the sidebar.
  3. Refresh your query until you see traces.
  4. View the traces and verify that important aspects of your application are captured by the trace data.

Library and Framework Support

OpenTelemetry automatically provides instrumentation for a large number of libraries and frameworks, right out of the box.

The full list of supported plugins can be found in the README.

OpenTracing Support

The OpenTracing shim allows existing OpenTracing instrumentation to report to the OpenTelemetry SDK. OpenTracing support is not enabled by default. Instructions for enabling the shim can be found in the README.

Read more about upgrading to OpenTelemetry in our OpenTracing Migration Guide.

Troubleshooting

Check that the agent was installed

If the Java agent is correctly installed, the following lines will be printed to the console:

[opentelemetry.auto.trace 2020-08-13 22:15:24:244 -0700] [main] INFO io.opentelemetry.auto.tooling.TracerInstaller - Installed span exporter: io.opentelemetry.exporters.otlp.OtlpGrpcSpanExporter
[opentelemetry.auto.trace 2020-08-13 22:15:24:250 -0700] [main] INFO io.opentelemetry.auto.tooling.PropagatorsInitializer - Added io.opentelemetry.extensions.trace.propagation.B3Propagator@7c0777b5 propagator
[opentelemetry.auto.trace 2020-08-13 22:15:24:252 -0700] [main] INFO io.opentelemetry.auto.tooling.VersionLogger - opentelemetry-javaagent - version: 0.7.0-SNAPSHOT~b659ee822

Running in Debug Mode

Set an environment variable to run the OpenTelemetry launcher in debug mode, where it logs details about the configuration and emitted spans:

export OTEL_LOG_LEVEL=debug

The output may be very verbose with some benign errors. Early in the console output, look for logs about the configuration and check that your access token is correct. Next, look for lines like the ones below, which are emitted when spans are emitted to Lightstep.

Span {
  attributes: {},
  links: [],
  events: [],
  status: { code: 0 },
  endTime: [ 1597810686, 885498645 ],
  _ended: true,
  _duration: [ 0, 43333 ],
  name: 'bar',
  spanContext: {
    traceId: 'eca3cc297720bd705e734f4941bca45a',
    spanId: '891016e5f8c134ad',
    traceFlags: 1,
    traceState: undefined
  },
  parentSpanId: 'cff3a2c6bfd4bbef',
  kind: 0,
  startTime: [ 1597810686, 885455312 ],
  resource: Resource { labels: [Object] },
  instrumentationLibrary: { name: 'example', version: '*' },
  _logger: ConsoleLogger {
    debug: [Function],
    info: [Function],
    warn: [Function],
    error: [Function]
  },
  _traceParams: {
    numberOfAttributesPerSpan: 32,
    numberOfLinksPerSpan: 32,
    numberOfEventsPerSpan: 128
  },
  _spanProcessor: MultiSpanProcessor { _spanProcessors: [Array] }
},