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.
You can install the agent statically (you will need to restart your app) or dynamically (you can install while the app is running).
Download the JAR file from Maven:
For a static attach, use the
-javaagent vmargument 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
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.
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.
Configuration properties can be set on the command line.
By default, all plugins except Concurrent have this property set to
To set all plugins to
To set individual plugins to
Set the tracer to LightStep and set your LightStep Satellite properties, replacing LS_TOKEN with your Project Access Tokens:
-Dsa.tracer=lightstep -Dls.collectorHost=collector.lightstep.com -Dls.collectorProtocol=https -Dls.collectorPort=443 -Dls.accessToken=$(LS_TOKEN)
Disable a plugin (all are installed by default):
artifactIdof the plugin, for example: