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-mock: mock layer for testing. Contains a MockTracer that simply saves the Spans to memory. Depends on
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.
Packages exist for
Gradle, which can be installed as follows:
<dependency> <groupId>io.opentracing</groupId> <artifactId>opentracing-api</artifactId> <version>VERSION</version> </dependency>
compile group: 'io.opentracing', name: 'opentracing-api', version: 'VERSION'
opentracing-api with the
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.
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.
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.
import java.util.Map; import io.opentracing.mock.MockTracer; import io.opentracing.mock.MockSpan; import io.opentracing.tags.Tags; // Initialize MockTracer with the default values. MockTracer tracer = new MockTracer(); // Create a new Span, representing an operation. MockSpan span = tracer.buildSpan("foo").start(); // Add a tag to the Span. span.setTag(Tags.COMPONENT, "my-own-application"); // Finish the Span. span.finish(); // Analyze the saved Span. System.out.println("Operation name = " + span.operationName()); System.out.println("Start = " + span.startMicros()); System.out.println("Finish = " + span.finishMicros()); // Inspect the Span's tags. Map<String, Object> tags = span.tags();