Java

The OpenTracing Java API lives and closely follows the naming of the components as defined in the specification.

The repository contains four main artifacts:

  • opentracing-api: the main API. No dependencies.
  • opentracing-noop: no-op implementation of the interfaces of the main API, which, as the name implies, do nothing. Depends on opentracing-api.
  • opentracing-mock: mock layer for testing. Contains a MockTracer that simply saves the Spans to memory. Depends on opentracing-api and opentracing.noop.
  • opentracing-util: Utility classes, such as the GlobalTracer and a default implementation of ScopeManager based on thread-local storage. Depends on all the previous artifacts.

An additional artifact exists for testing and trying out new features of the API, called opentracing-testbed, which can be used when developing the main API, but otherwise of no use for the OpenTracing consumers.

More information on the classes contained in each artifact below.

Installation

Packages exist for Maven and Gradle, which can be installed as follows:

Maven:

  1. <dependency>
  2.     <groupId>io.opentracing</groupId>
  3.     <artifactId>opentracing-api</artifactId>
  4.     <version>VERSION</version>
  5. </dependency>

Gradle:

  1. compile group: 'io.opentracing', name: 'opentracing-api', version: 'VERSION'

Replace opentracing-api with the opentracing-noop, opentracing-mock or opentracing-util to install the remaining artifacts. When installing more than one artifact, provide the same VERSION for all of them to avoid deployment being broken.

Main API

The main OpenTracing API declares all the main components as interfaces, which additional helper classes, such as Tracer, Span, SpanContext, Scope, ScopeManager and Format (used to define common SpanContext extraction/injection formats).

Consumers will most of the time consume only this part of the API, with potentially using the opentracing-mock artifact for testing and opentracing-util for utility classes.

OpenTracing Community Contributions.

Besides the official API, there are also several libraries under opentracing-contrib, including generic helpers like the TracerResolver and framework instrumentation libraries, such as Java Web Servlet Filter and Spring Cloud.

Quick Start

An easy way to get quickly started, and get familiar with the API is to use io.opentracing.mock.MockTracer to create Spans and inspect them afterwards, as the resulting MockSpans will expose a lot of information that a normal Span would not.

  1. import java.util.Map;
  2. import io.opentracing.mock.MockTracer;
  3. import io.opentracing.mock.MockSpan;
  4. import io.opentracing.tags.Tags;
  6. // Initialize MockTracer with the default values.
  7. MockTracer tracer = new MockTracer();
  9. // Create a new Span, representing an operation.
  10. MockSpan span = tracer.buildSpan("foo").start();
  12. // Add a tag to the Span.
  13. span.setTag(Tags.COMPONENT, "my-own-application");
  15. // Finish the Span.
  16. span.finish();
  18. // Analyze the saved Span.
  19. System.out.println("Operation name = " + span.operationName());
  20. System.out.println("Start = " + span.startMicros());
  21. System.out.println("Finish = " + span.finishMicros());
  23. // Inspect the Span's tags.
  24. Map<String, Object> tags = span.tags();