LightStep Documentation

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

Get Started    

Auto-Instrument With 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.


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

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

  1. Download the JAR file from Maven:

  2. For a static attach, use the -javaagent vm argument to start up your app.
    For example, if your app is named myapp.jar, you’d use this command:
    java -javaagent:opentracing-specialagent-1.1.1.jar -jar myapp.jar

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

    Attach the agent.
    For JDK1.8:
    java -Xbootclasspath/a:$JAVA_HOME/lib/tools.jar -jar opentracing-specialagent-1.1.0.jar <PID>

    For JDK1.9 and later:
    java -jar opentracing-specialagent-1.1.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

Configuration properties can be set on the command line.

  1. Set the verbose property.
    By default, all plugins except Concurrent have this property set to false.

    To set all plugins to true:

    To set individual plugins to true:

  2. Set the tracer to LightStep:

  3. Disable a plugin (all are installed by default):

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

Auto-Instrument With SpecialAgent

Suggested Edits are limited on API Reference Pages

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