LightStep

LightStep Documentation

Welcome to the LightStep developer hub. You'll find comprehensive guides and documentation to help you start working with LightStep as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Java Auto-Instrumentation

If your app is written in Java, you can get started quickly with LightStep. Download the Auto-Installer, 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.

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.
# Options for On Premise Satellites

-Dsa.tracer=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}

# Options for LightStep Public Satellites

-Dsa.tracer=lightstep 
-Dls.collectorHost=ingest.lightstep.com 
-Dls.collectorProtocol=https 
-Dls.collectorPort=443 
-Dls.accessToken=$(your_LightStep_token) 
-Dls.componentName=${your_service_name}
# Options for LightStep Public Satellites

-Dsa.tracer=lightstep 
-Dls.collectorHost=localhost
-Dls.collectorProtocol=https 
-Dls.collectorPort=8360 
-Dls.accessToken=$(your_LightStep_token) 
-Dls.componentName=${your_service_name}

Where to find your access token?

Your access token is shown in Project Settings. It tells LightStep which project the agent should send data to.

Where to find the host and port values for on-premise?

This is your pool address, found in your configuration file.

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.

-javaagent:$(path_to_special_agent) 
-jar $(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.

-jar opentracing-specialagent-1.5.0.jar <PID>
-Xbootclasspath/a:$JAVA_HOME/lib/tools.jar 
-jar opentracing-specialagent-1.4.0.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 Plugin SpecialAgent Rule Min Version Max Version
Akka Actor akka:actor 2.5.0 2.5.25
Akka Http Client akka:http 10.1.0 10.1.0
Apache Camel camel 2.24.0 2.24.2
Apache HttpClient apache:httpclient 4.4 4.5.9
Async Http Client asynchttpclient 2.7.0 2.10.1
AWS SDK aws:sdk:1 1.11.79 1.11.570
aws:sdk:2 2.1.4 2.7.15
Cassandra Driver cassandra:driver:3 3.0.0 3.7.2
cassandra:driver:4 4.0.0 4.2.0
Elasticsearch Client
 
elasticsearch:client-transport
elasticsearch:client-rest
6.4.0
 
7.3.1
 
Feign feign 9.0.0 10.4.0
Grizzly AsyncHttpClient grizzly:ahc 1.15 1.15
Grizzly HTTP Server grizzly:http-server 2.3.35 2.3.35
GRPC grpc 1.6.0 1.23.0
Hazelcast hazelcast 3.12 3.12.4
Java Concurrent API [java.util.concurrent] concurrent 1.5 11
Java JDBC API [java.sql] jdbc 3.1 4.3
Java JMS API [javax.jms] jms:1 1.1 1.1
jms:2 2.0 2.0a
Java Servlet API [javax.servlet] servlet 2.3 3.1
    Jetty 7.6.21.v20160908 9.2.15.v20160210
    Tomcat 7.0.65 9.0.27
Java Thread [java.lang.Thread] thread 1.0 11
JAX-RS Client jax-rs 2.0 2.1
Jedis Client jedis 2.7.0 3.1.0
Kafka Client kafka:client 1.1.0 2.3.0
Lettuce Client lettuce:5.0 5.0.0.RELEASE 5.0.5.RELEASE
lettuce:5.1 5.1.0.M1 5.1.8.RELEASE
lettuce:5.2 5.2.0.RELEASE 5.2.0.RELEASE
MongoDB Driver mongo:driver 3.9.0 3.11.0
OkHttp okhttp 3.5.0 4.2.2
Play Framework play 2.6.0 2.7.3
RabbitMQ Client rabbitmq:client 5.0.0 5.7.3
Reactor reactor 3.2.3.RELEASE 3.2.3.RELEASE
Redisson redisson 3.11.0 3.11.5
RxJava 2 rxjava:2 2.1.0 2.2.12
Spring Boot JMS spring:jms 1.5.22.RELEASE 2.1.8.RELEASE
Spring Boot Kafka spring:kafka 2.1.0.RELEASE 2.1.8.RELEASE
Spring Boot Messaging spring:messaging 2.1.0.RELEASE 2.1.8.RELEASE
Spring Boot RabbitMQ spring:rabbitmq 2.0.0.RELEASE 2.1.8.RELEASE
Spring Boot WebFlux spring:webflux 2.1.0.RELEASE 2.1.8.RELEASE
Spring Boot WebSocket STOMP spring:websocket 2.1.0.RELEASE 2.1.8.RELEASE
Spring [@Async] and @Scheduled spring:scheduling 1.5.22.RELEASE 2.1.8.RELEASE
Spring Web spring:web:3 3.0.3.RELEASE 3.2.18.RELEASE
spring:web:4.0 4.0.0.RELEASE 4.0.9.RELEASE
spring:web:4.x 4.1.0.RELEASE 4.3.25.RELEASE
spring:web:5 5.0.0.RELEASE 5.1.9.RELEASE
Spring Web MVC spring:webmvc:3 3.0.2.RELEASE 3.2.18.RELEASE
spring:webmvc:4 4.0.0.RELEASE 4.3.25.RELEASE
spring:webmvc:5 5.0.0.RELEASE 5.1.9.RELEASE
Spymemcached spymemcached 2.11.0 2.12.3
Thrift thrift 0.10.0 0.12.0
Zuul zuul 1.0.0 2.1.8

Updated 14 days ago

Java Auto-Instrumentation


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.