Java distributed tracing implementation compatible with Zipkin backend services.
Clone or download
Latest commit 37b07b3 Dec 12, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Updates build to JDK 11 (#806) Oct 17, 2018
.github Corrects to the normal zipkin contributing file (#468) Aug 12, 2017
.mvn/wrapper Updates notably to most recent zipkin to align dependency tree (#841) Dec 5, 2018
brave-bom [maven-release-plugin] prepare for next development iteration Dec 12, 2018
brave-tests [maven-release-plugin] prepare for next development iteration Dec 12, 2018
brave [maven-release-plugin] prepare for next development iteration Dec 12, 2018
build-support Removes all deprecated things (Brave v5) (#708) May 22, 2018
context Credit on JFR Dec 12, 2018
instrumentation [maven-release-plugin] prepare for next development iteration Dec 12, 2018
spring-beans [maven-release-plugin] prepare for next development iteration Dec 12, 2018
src/it Rewrites all major Brave instrumentation using new apis (#350) May 6, 2017
travis Uses travis to deploy instead of CircleCI Jan 25, 2018
.gitignore Adds gRPC client and server interceptors Mar 15, 2016
.settings.xml Uses OpenZipkin deploy process and migrates to io.zipkin.brave group … May 19, 2016
.travis.yml Adds JDK Flight Recorder context correlation (#843) Dec 12, 2018
HACKING.md Makes implicit change culture transparent (#287) Dec 10, 2016
LICENSE Update LICENSE (Apache 2.0). Apr 28, 2013
README.md Explicitly notes version policy and corrects some pom glitches (#757) Aug 15, 2018
RELEASE.md Uses travis to deploy instead of CircleCI Jan 25, 2018
mvnw Bumps versions to latest (#739) Jul 27, 2018
mvnw.cmd Bumps versions to latest (#739) Jul 27, 2018
pom.xml [maven-release-plugin] prepare for next development iteration Dec 12, 2018

README.md

Build Status Maven Central Gitter chat

Brave

Brave is a library used to capture latency information about distributed operations. It reports this data to Zipkin as spans.

Zipkin is based on Dapper. Dapper (dutch) = Brave (english)... So, that's where the name comes from.

You can look at our example project for how to trace a simple web application.

What's included

Brave's dependency-free tracer library works against JRE6+. This is the underlying api that instrumentation use to time operations and add tags that describe them. This library also includes code that parses X-B3-TraceId headers.

Most users won't write tracing code directly. Rather, they reuse instrumentation others have written. Check our instrumentation and Zipkin's list before rolling your own. Common tracing libraries like JDBC, Servlet and Spring already exist. Instrumentation written here are tested and benchmarked.

If you are trying to trace legacy applications, you may be interested in Spring XML Configuration. This allows you to setup tracing without any custom code.

You may want to put trace IDs into your log files, or change thread local behavior. Look at our context libraries, for integration with tools such as SLF4J.

Version Compatibility policy

All Brave libraries match the minimum Java version of what's being traced or integrated with, and adds no 3rd party dependencies. The goal is to neither impact your projects' choices, nor subject your project to dependency decisions made by others.

For example, even including a basic reporting library, zipkin-sender-urlconnection, Brave transitively includes no json, logging, protobuf or thrift dependency. This means zero concern if your application chooses a specific version of SLF4J, Gson or Guava. Moreover, the entire dependency tree including basic reporting in json, thrift or protobuf is less than 512KiB of jars.

There is a floor Java version of 1.6, which allows older JREs and older Android runtimes, yet may limit some applications. For example, Servlet 2.5 works with Java 1.5, but due to Brave being 1.6, you will not be able to trace Servlet 2.5 applications until you use at least JRE 1.6.

All integrations set their associated library to "provided" scope. This ensures Brave doesn't interfere with the versions you choose.

Some libraries update often which leads to api drift. In some cases, we test versions ranges to reduce the impact of this. For example, we test gRPC and Kafka against multiple library versions.

Artifacts

All artifacts publish to the group ID "io.zipkin.brave". We use a common release version for all components.

Library Releases

Releases are uploaded to Bintray and synchronized to Maven Central

Library Snapshots

Snapshots are uploaded to JFrog after commits to master.

Version alignments

When using multiple brave components, you'll want to align versions in one place. This allows you to more safely upgrade, with less worry about conflicts.

You can use our Maven instrumentation BOM (Bill of Materials) for this:

Ex. in your dependencies section, import the BOM like this:

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.zipkin.brave</groupId>
        <artifactId>brave-bom</artifactId>
        <version>${brave.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

Now, you can leave off the version when choosing any supported instrumentation. Also any indirect use will have versions aligned:

<dependency>
  <groupId>io.zipkin.brave</groupId>
  <artifactId>brave-instrumentation-okhttp3</artifactId>
</dependency>

With the above in place, you can use the properties brave.version, zipkin-reporter.version or zipkin.version to override dependency versions coherently. This is most commonly to test a new feature or fix.

Note: If you override a version, always double check that your version is valid (equal to or later) than what you are updating. This will avoid class conflicts.