OpenTracing Java Bridge for Zipkin

This library is a Java bridge between the Brave/Zipkin Api and OpenTracing. It allows its users to write portable (in the OpenTracing sense) instrumentation that's translated into Brave instrumentation transparently.

Compatibility

opentracing-api has broken compatibility on most releases, which limits the ability for this project to provide a large version range.

Here are the versions currently available, noting only the latest version of opentracing-api is likely to have new work in this repository.

Required Reading

In order to understand OpenTracing Api, one must first be familiar with the OpenTracing project and terminology more generally.

To understand how Zipkin and Brave work, you can look at Zipkin Architecture and Brave Api documentation.

Setup

Firstly, you need a Tracer, configured to report to Zipkin.

// Configure a reporter, which controls how often spans are sent
//   (the dependency is io.zipkin.reporter2:zipkin-sender-okhttp3)
sender = OkHttpSender.create("http://127.0.0.1:9411/api/v2/spans");
spanReporter = AsyncReporter.create(sender);

// If you want to support baggage, create a field you would like to
// propagate and configure it with `BaggagePropagation`
COUNTRY_CODE = BaggageField.create("country-code");

// Baggage does not need to be sent remotely via headers, but if you configure
// with `addRemoteField()`, it will be
propagationFactory = BaggagePropagation.newFactoryBuilder(B3Propagation.FACTORY)
                                       .addRemoteField(COUNTRY_CODE)
                                       .build()

// Now, create a Brave tracing component with the service name you want to see in Zipkin.
//   (the dependency is io.zipkin.brave:brave)
braveTracing = Tracing.newBuilder()
                      .localServiceName("my-service")
                      .propagationFactory(propagationFactory)
                      .spanReporter(spanReporter)
                      .build();

// use this to create an OpenTracing Tracer
tracer = BraveTracer.create(braveTracing);
countryCode = span.getBaggageItem(COUNTRY_CODE.name());

// You can later unwrap the underlying Brave Api as needed
braveTracing = tracer.unwrap();
countryCode = COUNTRY_CODE.get(span.unwrap().context());

Note: If you haven't updated to a server running the Zipkin v2 api, you can use the old Zipkin format like this:

sender = OkHttpSender.json("http://127.0.0.1:9411/api/v1/spans");
spanReporter = AsyncReporter.builder(sender).build(SpanEncoder.JSON_V1);

Artifacts

The artifact published is brave-opentracing under the group ID io.opentracing.brave

Library Releases

Releases are at Sonatype and Maven Central

Library Snapshots

Snapshots are uploaded to Sonatype after commits to master.