JarCastingOpenTracing 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.
| Version | opentracing-api version |
|---|---|
| 0.34.0+ | 0.32.0, 0.33.0 |
| 0.33.13 | 0.31.0 |
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.
