OpenTelemetry provides a Java agent that dynamically injects bytecode to capture telemetry from a number of popular libraries and frameworks. This guide explains how to install OpenTelemetry Java and export the trace data into Lightstep.

Requirements

  • Java version 7 or newer
  • A Lightstep account. If you don’t already have one, you can create a free account here.
  • An Access Token for the Lightstep project you would like to use.
  • An app to add OpenTelemetry to. You can use this one or use your own.

Install OpenTelemetry

Download two .jar files, one for OpenTelemetry Java Agent v0.2.2 and one for Lightstep Exporter v0.2.0.

Run OpenTelemetry

Start tabs

Public Satellites

1
2
3
4
5
export OTA_EXPORTER_JAR="/path/to/lightstep-opentelemetry-auto-exporter-0.2.0.jar"
export LIGHTSTEP_COMPONENT_NAME="my-app-name"
export LIGHTSTEP_ACCESS_TOKEN="my-access-token"
java -javaagent:/path/to/opentelemetry-auto-0.2.2.jar \
-jar my_application.jar

On-Premise Satellites

1
2
3
4
5
6
export OTA_EXPORTER_JAR="/path/to/lightstep-opentelemetry-auto-exporter-0.2.0.jar"
export LIGHTSTEP_COMPONENT_NAME="my-app-name"
export LIGHTSTEP_ACCESS_TOKEN="my-access-token"
export LIGHTSTEP_COLLECTOR_HOST="my-host-name"
java -javaagent:path/to/opentelemetry-auto-0.2.2.jar \
-jar my_application.jar

Developer Mode

1
2
3
4
5
6
export OTA_EXPORTER_JAR="/path/to/lightstep-opentelemetry-auto-exporter-0.2.0.jar"
export LIGHTSTEP_COMPONENT_NAME="my-app-name"
export LIGHTSTEP_ACCESS_TOKEN="developer"
export LIGHTSTEP_COLLECTOR_HOST="localhost"
java -javaagent:path/to/opentelemetry-auto-0.2.2.jar \
-jar my_application.jar

End code tabs

  1. Configure the Lightstep Exporter via environment variables.
    • OTA_EXPORTER_JAR the path to the lightstep-opentelemetry-auto-exporter jar.
    • LIGHTSTEP_SERVICE_NAME: Name of your service.
    • LIGHTSTEP_ACCESS_TOKEN: Access Token for your Lightstep project.
  2. On-premise Satellite users only: configure your Satellite Pool host and port values.
    • LIGHTSTEP_COLLECTOR_HOST: Satellite hostname (on-prem only).
    • LIGHTSTEP_COLLECTOR_PORT: Satellite port (on-prem only).
    • LIGHTSTEP_COLLECTOR_PROTOCOL: http or https.
  3. The above environment variables can also be set as system properties. The complete list of configuration options can be found here.

  4. Once your environment variables are set, run your application with the OpenTelemetry Java Agent by setting thejavaagent argument to the path of the opentelemetry-auto-0.2.2.jar file.

Available Instrumentation

OpenTelemetry Java currently supports the frameworks and libraries listed in the README.

View Traces in Lightstep

Now that your app is running, you can view the telemetry data in Lightstep.

  1. Trigger an action in your app that generates a web request.

  2. In Lightstep, click on the Explorer view. Explorer view

  3. Click on any span in the Trace Analysis table. Spans in the Trace Analysis table

  4. View the trace and any metadata produced by the telemetry. Trace view

Learn more about using Lightstep by following one of our learning paths.

Troubleshooting

Check that the exporter was installed

If the java agent and the lightstep exporter are correctly installed, the following line will be printed to the console:

1
[opentelemetry.auto.trace 2020-04-04 12:00:00:000 -0700] [main] INFO io.opentelemetry.auto.tooling.TracerInstaller - Installed span exporter: com.lightstep.opentelemetry.exporter.LightstepSpanExporter

Watch out for magic quotes

Sometimes, when configuring the start command in a text editor, regular quotation marks “” can be replaced with unicode quotation marks “”. This will cause the command to fail.

For example, the following command will fail due to several quotation marks being switched to unicode. Echh!!

1
2
3
4
5
export OTA_EXPORTER_JAR=“lightstep-opentelemetry-auto-exporter-0.2.0.jar"
export LIGHTSTEP_SERVICE_NAME=“pet-sounds”
export LIGHTSTEP_ACCESS_TOKEN="05137244f31c795a90417deceef6bc28"
java -javaagent:opentelemetry-auto-0.2.2.jar \
-jar target/*.jar

Logging to the console

If you are not seeing any data, you can verify that spans are being created by using the Logging Exporter to view the data in your console.

  1. Download the logging exporter
  2. Run the app with the -javaagent argument to install the OpenTelemetry agent, and the ota.exporter.jarsystem property to specify the logging exporter.
1
2
3
java -javaagent:path/to/opentelemetry-auto-0.2.2.jar \
     -Dota.exporter.jar=path/to/opentelemetry-auto-exporters-logging-0.2.2.jar \
     -jar myapp.jar

The output should look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
[opentelemetry.auto.trace +0200] [main] INFO
io.opentelemetry.auto.tooling.TracerInstaller - Installed span exporter:
io.opentelemetry.auto.exporters.logging.LoggingExporter
...
Logging Exporter: HTTP GET 4345317177e5828d http.status_code=200
net.peer.port=50028 servlet.path="/" http.url="http://127.0.0.1:8080/"
net.peer.ip="127.0.0.1" http.method="GET"
span.origin.type="com.mycompany.otelexample.SimpleServer$SimpleServlet"
Logging Exporter: HTTP GET 9a46b4a56d74c61f http.url="http://127.0.0.1:8080/"
net.peer.name="127.0.0.1" http.status_code=200
net.peer.port=8080 http.method="GET"
bye
Logging Exporter: HTTP GET 551613b8094cc07a http.url="http://127.0.0.1:8080/"
net.peer.name="127.0.0.1" http.status_code=200
net.peer.port=8080 http.method="GET"
bye
Logging Exporter: HTTP GET 995ce4bd4be5f516 http.status_code=200
net.peer.port=50028 servlet.path="/" http.url="http://127.0.0.1:8080/"
net.peer.ip="127.0.0.1" http.method="GET"
span.origin.type="com.mycompany.otelexample.SimpleServer$SimpleServlet"
Logging Exporter: HTTP GET 1da987bd58a8b185 http.status_code=200
net.peer.port=50028 servlet.path="/" http.url="http://127.0.0.1:8080/"
net.peer.ip="127.0.0.1" Logging Exporter: HTTP GET 80f07e526564ac79
http.method="GET" http.url="http://127.0.0.1:8080/"
net.peer.name="127.0.0.1" http.status_code=span.origin.type="com.mycompany.otelexample.SimpleServer$SimpleServlet"
200 net.peer.port=8080 http.method="GET"
bye
...