lightstep-tracer-java
The LightStep distributed tracing library for Android and the standard Java runtime environment.
Getting started: Android
The Android library is hosted on Bintray, jcenter, and Maven Central. The Bintray lightstep-tracer-android project contains additional installation and setup information for using the library with various build systems such as Ivy and Maven.
Gradle
In most cases, modifying your build.gradle
with the below is all that is required:
repositories {
jcenter() // OR mavenCentral()
}
dependencies {
compile 'com.lightstep.tracer:lightstep-tracer-android:VERSION'
}
- Be sure to replace
VERSION
with the current version of the library - The artifact is published to both
jcenter()
andmavenCentral()
. Use whichever you prefer.
Update your AndroidManifest.xml
Ensure the app's AndroidManifest.xml
has the following (under the <manifest>
tag):
<!-- Permissions required to make http calls -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Initializing the LightStep Tracer
// Import the OpenTracing interfaces
import io.opentracing.Span;
import io.opentracing.Tracer;
// ...
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Initialize LightStep tracer implementation in the main activity
// (or anywhere with a valid android.content.Context).
this.tracer = new com.lightstep.tracer.android.Tracer(
this,
new com.lightstep.tracer.shared.Options.OptionsBuilder()
.withAccessToken("{your_access_token}")
.build()
);
// Start and finish a Span
Span span = this.tracer.buildSpan("my_span").start();
this.doSomeWorkHere();
span.finish();
Getting started: JRE
The JRE library is hosted on Bintray, jcenter, and Maven Central. The Bintray lightstep-tracer-jre project contains additional installation and setup information for using the library with various build systems such as Ivy and Maven.
Maven
<dependency>
<groupId>com.lightstep.tracer</groupId>
<artifactId>lightstep-tracer-jre</artifactId>
<version> VERSION </version>
</dependency>
- Be sure to replace
VERSION
with the current version of the library
Gradle
In most cases, modifying your build.gradle
with the below is all that is required:
repositories {
mavenCentral() // OR jcenter()
}
dependencies {
compile 'com.lightstep.tracer:lightstep-tracer-jre:VERSION'
}
- Be sure to replace
VERSION
with the current version of the library - The artifact is published to both
jcenter()
andmavenCentral()
. Use whichever you prefer.
Initializing the LightStep Tracer
// Important the OpenTracing interfaces
import io.opentracing.Span;
import io.opentracing.Tracer;
// ...
// Initialize the OpenTracing Tracer with LightStep's implementation
Tracer tracer = new com.lightstep.tracer.jre.JRETracer(
new com.lightstep.tracer.shared.Options.OptionsBuilder()
.withAccessToken("{your_access_token}")
.build()
);
// Start and finish a Span
Span span = this.tracer.buildSpan("my_span").start();
this.doSomeWorkHere();
span.finish();
API Documentation
Tracing instrumentation should use the OpenTracing APIs to stay portable and in sync with the standard:
For reference, the generated LightStep documentation is also available:
Options
Setting a custom component name
To set the name used in the LightStep UI for this instance of the Tracer, call withComponentName()
on the OptionsBuilder
object:
options = new com.lightstep.tracer.shared.Options.OptionsBuilder()
.withAccessToken("{your_access_token}")
.withComponentName("your_custom_name")
.build();
Disabling the reporting loop
By default, the Java library does a report of any buffered data on a fairly regular interval. To disable this behavior and rely only on explicit calls to flush()
to report data, initialize with:
options = new com.lightstep.tracer.shared.Options.OptionsBuilder()
.withAccessToken("{your_access_token}")
.withDisableReportingLoop(true)
.build();
To then manually flush by using the LightStep tracer object directly:
// Flush any buffered tracing data
((com.lightstep.tracer.android.Tracer)tracer).flush();
Flushing the report at exit
In order to send a final flush of the data prior to exit, clients should manually flush by using the LightStep tracer object as described above.
Development info
See DEV.md for information on contributing to this instrumentation library.