isabella232 / opentracing-basic

Basic OpenTracing bridge library for Java

Basic OpenTracing API Implementation for Java

Introduction

The OpenTracing API for Java defines the interfaces for how a user interacts with a compliant OpenTracing back-end but leaves it up to the OpenTracing backend implementation to fulfill the API requirements. When creating simple bridge implementations, tracing data ETL operations, or integrating OpenTracing support in constrained environments this can amount to a significant effort in order to define and consistently adhere to the API.

The goal of this library is to attempt to implement the generic semantics of the OpenTracing API and allow for the main implementation details to be provided into the library by the consumer.

Status

This project is currently in beta. The API should be considered to be unstable and the implementation is not yet optimized.

Obtaining the Library

This library is distributed via both jcenter and maven central repositories. The latest version number is represented in the "Download" badge at the top of this page. To use the library, include it as a dependency in your project as follows:

Gradle:

dependencies {
    compile 'com.ebay.opentracing:opentracing-basic:${version}'
}

Maven:

<dependencies>
    <dependency>
        <groupId>com.ebay.opentracing</groupId>
        <artifactId>opentracing-basic</artifactId>
        <version>${version}</version>
    </dependency>
</dependencies>

Usage

At a high level, the use of this library requires the developer to do the following:

1. Define a "trace context" object which encapsulates the data which is specific to the tracing implementation back-end (e.g., Trace ID, Span ID, sampling information, etc.). This "trace context" object may be a plain old Java object (POJO). An example implementation is provided in the test code: TestTraceContext
2. Create an implementation of the TraceContextHandler interface which creates instances of InternalSpanContext<?> which integrate the custom trace context data. An example implementation is provided in the test code: TestTraceContextHandler
3. Create an implementation of the FinishedSpanReceiver interface to take finished spans' data and use the data as appropriate for the consumer's use case. An example implementation is provided in the test code:

Once the above have been setup, usage of the library may be as simple as the following:

TraceContextHandler traceContextHandler = ...
FinishedSpanReceiver receiver = ...
Tracer tracer = new BasicTracerBuilder<>(traceContextHandler, receiver)
    .build();

try (Scope scope = tracer.buildSpan("operation").startActive(true)) {
    // Measured work
}

Optional Features

Formatters

To achieve cross-process operation, one or more implementation(s) of the Formatter interface may be supplied in order to define how the trace/span context is applied to a data carrier of a particular type. Once defined, the formatter should be registered at Tracer- creation time as in the following example, replacing the Format with the appropriate type.

Tracer tracer = new BasicTracerBuilder<>(traceContextHandler, receiver)
    .registerFormatter(Format.Builtin.TEXT_MAP, formatter)
    .build();

The Basic Tracer implementation will then leverage the provided formatter for inject and extract operations.

Span Initiators

When the tracer implementation is creating a new span instance, it provides the opportunity to hook into the creation process by providing a SpanInitiator instance. This allows integration at the front-end of the span whereas the span receiver allows for integration at the back-end.

When called, the initiator should leverage the provided initiator context to create and return the Span instance. The initiator instance can use this opportunity to decorate or populate data within the span before being used at the call point.

Custom initiators are registered with the Tracer though the BasicTracerBuilder:

SpanInitiator initiator = ...
Tracer tracer = new BasicTracerBuilder<>(traceContextHandler, receiver)
    .spanInitiator(initiator)
    .build();

References

• OpenTracing - A vendor-neutral open standard for distributed tracing
• OpenTracing Specification
• OpenTracing Semantic Conventions