Installation

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!).

pom.xml dependency:

<dependency>
    <groupId>com.lightstep.opentelemetry</groupId>
    <artifactId>opentelemetry-launcher</artifactId>
    <version>0.1.0</version>
</dependency>

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.1.0.jar \
     -jar myapp.jar

Code configuration approach:

// Install the OpenTelemetry SDK with defaults.
OpenTelemetryConfiguration.newBuilder()
                      .setServiceName("{service_name}")
                      .setAccessToken("{your_access_token}")
                      .setSpanEndpoint("{lightstep_host}")
                      .install();
 
// Get tracer
Tracer tracer = OpenTelemetry.getTracer("instrumentation-library-name", "1.0.0");

Validate Installation by Checking for Traces

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.