Want to use OpenTelemetry instead? Read these docs to get started!

If your app is written in Java, you can get started quickly with Lightstep. Download the Java SpecialAgent, then configure it to communicate with your Lightstep Satellites. When you deploy your app, all supported third-party framework libraries (like the Elasticsearch client, RxJava, or the Kafka client) will begin sending trace data to Lightstep. The SpecialAgent also collects and reports on infrastructure metrics, communicating directly with the Lightstep Engine.

To ensure you can access all Lightstep functionality, including infrastructure metrics reporting, update the SpecialAgent to the latest release. To update, simply follow the instructions for installing the SpecialAgent. No code changes are needed.

Installation can be static or dynamic, allowing you to install without requiring the application’s source code to be modified or re-compiled.

Supported Java Versions

Java versions 1.7 or later are supported.

Install the Agent

Download the JAR file from Maven.

Configure the Agent to Send Data to Lightstep

To send data from your system to Lightstep, you need to configure the agent to point to your Satellites.

To configure the agent:

  1. Configure the agent to point to the Lightstep Satellites by setting these environment variables. Use the right values, depending on if you are using on-premise, Lightstep public, or Developer Mode Satellites.

Start tabs

On-Premise Satellites

1
2
3
4
5
6
7
8
9
10
# Options for On Premise Satellites

-Dsa.exporter=lightstep
-Dls.collectorHost=$(your_load_balancer_DNS_name_or_IP_address)
-Dls.collectorProtocol=$(your_satellite_protocol)
-Dls.collectorPort=$(your_satellite_port)
-Dls.accessToken=$(your_Lightstep_token)
-Dls.componentName=${your_service_name}
-Dls.propagator=b3
-Dls.tags="environment=qa-21,version=0.0.201"

Public Satellites

1
2
3
4
5
6
7
8
9
10
# Options for Lightstep Public Satellites

-Dsa.exporter=lightstep
-Dls.collectorHost=ingest.lightstep.com
-Dls.collectorProtocol=https
-Dls.collectorPort=443
-Dls.accessToken=$(your_Lightstep_token)
-Dls.componentName=${your_service_name}
-Dls.propagator=b3
-Dls.tags="environment=qa-21,version=0.0.201"

Developer Mode

1
2
3
4
5
6
7
8
9
10
# Options for Lightstep Public Satellites

-Dsa.exporter=lightstep
-Dls.collectorHost=localhost
-Dls.collectorProtocol=https
-Dls.collectorPort=8360
-Dls.accessToken=$developer
-Dls.componentName=${your_service_name}
-Dls.propagator=b3
-Dls.tags="environment=qa-21,version=0.0.201"

End code tabs

Note the following:

  • Your access token is shown in Project Settings. It tells Lightstep which project the agent should send data to.
  • The host and port values for on-premise satellites is your pool address, found in your configuration file.
  • The tags variable allows you to set global tags on all traces.
  • Lightstep recommends using B3 headers for trace propagation as the default, especially on hybrid deployments, as it is the most widely supported header at this time.

Configure Metrics Reporting

Along with the SpecialAgent collecting telemetry data to report on performance issues and other contextual information to help you with root cause analysis, Lightstep can also ingest and report on infrastructure metrics for a service to further assist in your investigations.

To ensure you can access all Lightstep functionality, including infrastructure metrics reporting, update the SpecialAgent to the latest release. To update, simply follow the instructions for installing the SpecialAgent. No code changes are needed.

The following infrastructure metrics are sent to Lightstep:

  • CPU Usage (%)
  • Memory (%)
  • Network (bytes)

  • Garbage Collection (GC) Count
  • GC Time
  • Heap Size

These metrics are displayed when you compare performance of a service over two different time periods.

Machine metrics are enabled by default. However, if you use a proxy, you need to set this environment variable to point to the Lightstep endpoint.

-Dls.metricsUrl=http://localhost:8126/metrics
or
-Dls.metricsUrl=<scheme>://<proxy_host>:<proxy_port>/metrics

If you don’t want metrics reported, you can configure the SpecialAgent to turn it off.

To turn metrics off:

Set the following environment variable:
-Dls.disableMetricsReporting=true

Run the Java Special Agent

You can install the agent statically (you will need to restart your app) or dynamically (you can install while the app is running).

Static

For a static attach, use the -javaagent argument to start up your app.

1
2
3
4
java <application_name>
<options>
-javaagent:$(full_path_to_special_agent_jar)
-jar $(full_path_to_your_jar_file)

Dynamic

For a dynamic attach, you need to determine your application’s PID and then attach the agent.

Run jps in a shell to get your PID.

Make sure the SpecialAgent version is correct for your installation.

JDK 1.9 and later:

1
-jar opentracing-specialagent-<version>.jar <PID>

JDK 1.8:

1
2
-Xbootclasspath/a:$JAVA_HOME/lib/tools.jar
-jar opentracing-specialagent-<version>.jar <PID>

All supported OpenTracing plugins are now installed! If you did a dynamic attachment and the third-party apps that have plugins are running, you’ll immediately start to see spans in Lightstep. If you did a static attach, you’ll get spans as soon as your apps are all running.

Read the next section to learn how to configure SpecialAgent to tune the amount of data sent.

Configure Java SpecialAgent Plugins

Java SpecialAgent supports many plugins out of the box. You can add the following additional configuration properties on the command line for plugin configuration.

Set the verbose property

By default, all plugins except Concurrent have this property set to false.

To set all plugins to true:
-Dsa.instrumentation.plugins.verbose=true

Or to set individual plugins to true: -Dsa.instrumentation.plugin.${RULE_NAME_PATTERN}.verbose=true

The ${RULE_NAME_PATTERN} is the artifactId of the plugin, and is shown in the table, below.

Disable a plugin

All plugins are installed by default. You can disable any you don’t need:
-Dsa.instrumentation.plugin.${RULE_NAME_PATTERN}.disable

The ${RULE_NAME_PATTERN} is the artifactId of the plugin, and is shown in the table, below.

Enable a plugin

All plugins are installed by default. If you’ve disabled a plugin, you can re-enable it: -Dsa.instrumentation.plugin.${RULE_NAME_PATTERN}.enable

The ${RULE_NAME_PATTERN} is the artifactId of the plugin, and is shown in the table, below.

What’s Auto-Instrumented

Following are the supported plugins that are auto-instrumented when you run your app.

OpenTracing PluginSpecialAgent RuleMin VersionMax Version
Akka Actorakka:actor2.5.02.5.25
Akka Http Clientakka:http10.1.010.1.0
Apache Camelcamel2.24.02.24.2
Apache HttpClientapache:httpclient4.44.5.9
Async Http Clientasynchttpclient2.7.02.10.1
AWS SDKaws:sdk:11.11.791.11.570
 aws:sdk:22.1.42.7.15
Cassandra Drivercassandra:driver:33.0.03.7.2
 cassandra:driver:44.0.04.2.0
Elasticsearch Client
 
elasticsearch:client-transport
elasticsearch:client-rest
6.4.0
 
7.3.1
 
Feignfeign9.0.010.4.0
Grizzly AsyncHttpClientgrizzly:ahc1.151.15
Grizzly HTTP Servergrizzly:http-server2.3.352.3.35
GRPCgrpc1.6.01.23.0
Hazelcasthazelcast3.123.12.4
Java Concurrent API [java.util.concurrent]concurrent1.511
Java JDBC API [java.sql]jdbc3.14.3
Java JMS API [javax.jms]jms:11.11.1
 jms:22.02.0a
Java Servlet API [javax.servlet]servlet2.33.1
    Jetty 7.6.21.v201609089.2.15.v20160210
    Tomcat 7.0.659.0.27
Java Thread [java.lang.Thread]thread1.011
JAX-RS Clientjax-rs2.02.1
Jedis Clientjedis2.7.03.1.0
Kafka Clientkafka:client1.1.02.3.0
Lettuce Clientlettuce:5.05.0.0.RELEASE5.0.5.RELEASE
 lettuce:5.15.1.0.M15.1.8.RELEASE
 lettuce:5.25.2.0.RELEASE5.2.0.RELEASE
MongoDB Drivermongo:driver3.9.03.11.0
OkHttpokhttp3.5.04.2.2
Play Frameworkplay2.6.02.7.3
RabbitMQ Clientrabbitmq:client5.0.05.7.3
Reactorreactor3.2.3.RELEASE3.2.3.RELEASE
Redissonredisson3.11.03.11.5
RxJava 2rxjava:22.1.02.2.12
Spring Boot JMSspring:jms1.5.22.RELEASE2.1.8.RELEASE
Spring Boot Kafkaspring:kafka2.1.0.RELEASE2.1.8.RELEASE
Spring Boot Messagingspring:messaging2.1.0.RELEASE2.1.8.RELEASE
Spring Boot RabbitMQspring:rabbitmq2.0.0.RELEASE2.1.8.RELEASE
Spring Boot WebFluxspring:webflux2.1.0.RELEASE2.1.8.RELEASE
Spring Boot WebSocket STOMPspring:websocket2.1.0.RELEASE2.1.8.RELEASE
Spring [@Async] and @Scheduledspring:scheduling1.5.22.RELEASE2.1.8.RELEASE
Spring Webspring:web:33.0.3.RELEASE3.2.18.RELEASE
 spring:web:4.04.0.0.RELEASE4.0.9.RELEASE
 spring:web:4.x4.1.0.RELEASE4.3.25.RELEASE
 spring:web:55.0.0.RELEASE5.1.9.RELEASE
Spring Web MVCspring:webmvc:33.0.2.RELEASE3.2.18.RELEASE
 spring:webmvc:44.0.0.RELEASE4.3.25.RELEASE
 spring:webmvc:55.0.0.RELEASE5.1.9.RELEASE
Spymemcachedspymemcached2.11.02.12.3
Thriftthrift0.10.00.12.0
Zuulzuul1.0.02.1.8