Want to use OpenTelemetry instead? Read these docs to get started!

Follow these steps to configure your tracer to communicate with the Lightstep Satellites and create a single span on your service. You install both the OpenTracing API and Lightstep tracer and then use the OpenTracing and Lightstep APIs to instrument your code.

To ensure you can access all Lightstep functionality, including infrastructure metrics reporting, update your tracer to the latest release. To update, simply follow the instructions for installing the tracer. No code changes are needed.

While Lightstep offers tracers and APIs specific to its tracing software, you will still use the OpenTracing API to fully instrument your code. Be sure you have read and are familiar with both Lightstep tracers and the OpenTracing specification in your application’s language.

Java Instrumentation for OpenTracing

  1. Find your access token in Lightstep. You’ll need this to configure your Lightstep tracer.
    • Click the Project Settings button.
    • In the Access Tokens table, click the Copy icon to copy your access token to the clipboard.
  2. Install the Lightstep tracer by adding dependencies and modifying your build file as described here

    Be sure to use correct version numbers! Replace the version numbers in the code example with the correct versions for your environment.

  3. Import the Lightstep tracer and OpenTracing interfaces.

    1
    2
    3
    
    import com.lightstep.tracer.shared.Options;
    import com.lightstep.tracer.jre.JRETracer;
    import io.opentracing.Span;
    
  4. Early in your application’s initialization, configure the Lightstep tracer. As part of the configuration, you need to add your access token and add your service’s name.

    1
    2
    3
    4
    5
    6
    7
    8
    
    public class App {
      public static void main(String[] args) throws Exception {
        Options opts = new Options.OptionsBuilder()
          .withAccessToken("YOUR_ACCESS_TOKEN")
          .withComponentName("YOUR_SERVICE_NAME")
          .build();
    
    JRETracer tracer = new JRETracer(opts);
    
  5. Test that everything is connected by sending a test span. Annotate the span by adding a tag (key/value pair) and logs, then flush the tracer.

    1
    2
    3
    4
    5
    6
    
    Span span = tracer.buildSpan("handler").startActive();
    span.setTag("Lorem", "Ipsum");
    span.log("Lorem Ipsum Dolor");
    span.finish();
    
    tracer.flush(500);
    

    Full code sample:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    
    import com.lightstep.tracer.shared.Options;
    import com.lightstep.tracer.jre.JRETracer;
    import io.opentracing.Span;
    
    public class App {
        public static void main(String[] args) throws Exception {
            Options opts = new Options.OptionsBuilder()
                    .withAccessToken("YOUR_ACCESS_TOKEN")
                    .withComponentName("YOUR_SERVICE_NAME")
                    .build();
    
            JRETracer tracer = new JRETracer(opts);
    
            Span span = tracer.buildSpan("handler").start();
            span.setTag("KEY", "VALUE");
            span.log("Lorem Ipsum Dolor");
            span.finish();
    
            tracer.flush(500);
        }
    }
    
  6. Run your app.

  7. Open Lightstep. You should see your service in the Service directory list.

It may take a few moments for your service to display in the Service Directory. To see data immediately, click the Explorer tab to view data in the histogram.

Configure Metrics Reporting

Along with the tracer collecting telemetry data to report on performance issues and other contextual information to help you with root cause analysis, Lightstep can also ingest and report on infrastructure metrics for a service to further assist in your investigations.

To ensure you can access all Lightstep functionality, including infrastructure metrics reporting, update your tracer to the latest release. To update, simply follow the instructions for installing the tracer. No code changes are needed.

The following infrastructure metrics are sent to Lightstep:

  • CPU Usage (%)
  • Memory (%)
  • Network (bytes)

  • Garbage Collection (GC) Count
  • GC Time
  • Heap Size

These metrics are displayed when you compare performance of a service over two different time periods.

Machine metrics are enabled by default. However, if you use a proxy, you need to configure the endpoint option to point to the Lightstep endpoint.

1
2
3
4
5
6
7
8
9
10
11
public class App {
  public static void main(String[] args) throws Exception {
    Options opts = new Options.OptionsBuilder()
      .withAccessToken("YOUR_ACCESS_TOKEN")
      .withComponentName("YOUR_SERVICE_NAME")
      .withMetricsUrl("http://localhost:8126/metrics")
      //or you can use
      .withMetricsUrl("<scheme>://<proxy_host>:<proxy_port>/metrics")
      .build();

JRETracer tracer = new JRETracer(opts);

If you don’t want metrics reported, you can configure the tracer to turn it off.

To turn metrics off:

Set the disableMetricsReporting option to true.

1
2
3
4
5
6
7
8
9
public class App {
  public static void main(String[] args) throws Exception {
    Options opts = new Options.OptionsBuilder()
      .withAccessToken("YOUR_ACCESS_TOKEN")
      .withComponentName("YOUR_SERVICE_NAME")
      .withDisableMetricsReporting(true);
      .build();

JRETracer tracer = new JRETracer(opts);

Read the OpenTracing Java README on GitHub to learn more.