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.
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.