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    

Instrument 3rd Party Libraries with Java SpecialAgent

If your application runs on Java and uses common third-party framework libraries like the Elasticsearch client, RxJava, or the Kafka client, then you can use the Java SpecialAgent to automatically instrument your framework. You can have end-to-end tracing without adding your own code.

SpecialAgent is a Java Agent that automatically connects third-party libraries you have in your system to available OpenTracing plugins that provide instrumentation for those libraries - the same code you would add by hand. Using Java’s instrumentation mechanism, the plugins modify the byte-code to insert instrumentation for dynamic tracing.

The Agent also installs and configures the LightStep tracer to collect data generated from the instrumented code created by the plugins.

Here’s a list of available plugins that SpecialAgent installs (you can disable any of the plugins you don’t need). All you need to do is install the agent - trace data appears in LighStep without any other configuration or instrumentation code needed.

Because SpecialAgent is from the OSS community, new plugins are being created all the time. You can create your own if you need to!

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

You can learn more about the Java SpecialAgent here.

Prerequisites

This agent works only with applications that are Java-based, running version 1.7 or later.

Install Java SpecialAgent

Configure the Tracer Options

Set the tracer to LightStep and set your LightStep Satellite properties, replacing LS_TOKEN with your Project Access Token:

Use the right code for your LightStep Environment!

When initializing the tracer, you pass in properties to the LightStep Satellites that collect the span data. Be sure to use the correct confguration for your LightStep Satellite environment - on-premise or the LightStep public Satellite pool.

# 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) 
# Options for LightStep Public Satellites

-Dsa.tracer=lightstep 
-Dls.collectorHost=ingest.lightstep.com 
-Dls.collectorProtocol=https 
-Dls.collectorPort=443 
-Dls.accessToken=$(your_LightStep_token) 

Run the Java SpecialAgent

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.

java 
-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) 
-javaagent:$(path_to_special_agent) 
-jar $(path_to_your_jar_file)
java 
-Dsa.tracer=lightstep 
-Dls.collectorHost=collector.lightstep.com 
-Dls.collectorProtocol=https 
-Dls.collectorPort=443 
-Dls.accessToken=$(your_LightStep_token) 
-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.

For JDK1.8:

java 
-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) 
-Xbootclasspath/a:$JAVA_HOME/lib/tools.jar 
-jar opentracing-specialagent-1.4.0.jar <PID>
java 
-Dsa.tracer=lightstep 
-Dls.collectorHost=ingest.lightstep.com 
-Dls.collectorProtocol=https 
-Dls.collectorPort=443 
-Dls.accessToken=$(your_LightStep_token) 
-Xbootclasspath/a:$JAVA_HOME/lib/tools.jar 
-jar opentracing-specialagent-1.4.0.jar <PID>

For JDK1.9 and later:

java 
-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) 
-jar opentracing-specialagent-1.4.0.jar <PID>
java 
-Dsa.tracer=lightstep 
-Dls.collectorHost=ingest.lightstep.com 
-Dls.collectorProtocol=https 
-Dls.collectorPort=443 
-Dls.accessToken=$(your_LightStep_token) 
-jar opentracing-specialagent-1.4.0.jar <PID>

All 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.

  1. 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.${PLUGIN_NAME}.verbose=true

  2. Disable a plugin (all are installed by default):
    -Dsa.instrumentation.plugin.${PLUGIN_NAME}.enable=false

    The ${PLUGIN_NAME} is the artifactId of the plugin, for example:
    opentracing-specialagent-okhttp or opentracing-specialagent-web-servlet-filter

Instrument 3rd Party Libraries with Java SpecialAgent


Suggested Edits are limited on API Reference Pages

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