The LightStep distributed tracing library for Android and JRE
Java Shell Makefile
Clone or download
Latest commit 25c6e9f Aug 7, 2018

README.md

lightstep-tracer-java

Download Circle CI MIT license

The LightStep distributed tracing library for the standard Java runtime environment.

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>

<dependency>
   <groupId>com.lightstep.tracer</groupId>
   <artifactId>tracer-grpc</artifactId>
   <version> VERSION </version>
</dependency>

<dependency>
      <groupId>io.grpc</groupId>
      <artifactId>grpc-netty</artifactId>
      <version>1.4.0</version>
</dependency>

<dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-tcnative-boringssl-static</artifactId>
      <version>2.0.5.Final</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'
    compile 'com.lightstep.tracer:tracer-grpc:VERSION'
}
  • Be sure to replace VERSION with the current version of the library
  • The artifact is published to both jcenter() and mavenCentral(). 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.jre.JRETracer)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.

Disabling default clock correction

By default, the Java library performs clock correction based on timestamp information provided in the spans. To disable this behavior, initialize with:

options = new com.lightstep.tracer.shared.Options.OptionsBuilder()
                      .withAccessToken("{your_access_token}")
                      .withClockSkewCorrection(false)
                      .build();

Advanced Option: Transport and Serialization Protocols

By following the above configuration, the tracer will send information to LightStep using GRPC and Protocol Buffers which is the recommended configuration. If there are no specific transport protocol needs you have, there is no need to change this default.

There are two options for transport protocols:

  • Protocol Buffers over GRPC - The recommended, default, and most performant solution.
  • [ EXPERIMENTAL ] Protocol Buffers over HTTP using OkHttp - New transport protocol supported for use cases where GRPC isn't an option. In order to enable HTTP you will need to configure the LightStep collectors receiving the data to accept HTTP traffic. Reach out to LightStep for support in this.

You can configure the tracer to support HTTP by replacing com.lightstep.tracer:tracer-grpc with com.lightstep.tracer:tracer-okhttp when including the tracer dependency. i.e.

Maven

<dependency>
  <groupId>com.lightstep.tracer</groupId>
  <artifactId>lightstep-tracer-jre</artifactId>
  <version> VERSION </version>
</dependency>

<dependency>
   <groupId>com.lightstep.tracer</groupId>
   <artifactId>tracer-okhttp</artifactId>
   <version> VERSION </version>
</dependency>

Gradle

repositories {
    mavenCentral() // OR jcenter()
}
dependencies {
    compile 'com.lightstep.tracer:lightstep-tracer-jre:VERSION'
    compile 'com.lightstep.tracer:tracer-okhttp:VERSION'
}

Development info

See DEV.md for information on contributing to this instrumentation library.