• Stars
    star
    2,327
  • Rank 19,228 (Top 0.4 %)
  • Language
    Java
  • License
    Apache License 2.0
  • Created about 11 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Java distributed tracing implementation compatible with Zipkin backend services.

Gitter chat Build Status Maven Central

Brave

Brave is a distributed tracing instrumentation library. Brave typically intercepts production requests to gather timing data, correlate and propagate trace contexts. While typically trace data is sent to Zipkin server, third-party plugins are available to send to alternate services such as Amazon X-Ray.

This repository includes dependency-free Java libraries and instrumentation for common components used in production services. For example, this includes trace filters for Servlet and log correlation for Apache Log4J.

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

Snapshots are uploaded to Sonatype which synchronizes with Maven Central

Library Snapshots

Snapshots are uploaded to Sonatype 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 property brave.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.

More Repositories

1

zipkin

Zipkin is a distributed tracing system
Java
16,769
star
2

zipkin-go

Zipkin distributed tracing library for go.
Go
604
star
3

zipkin-js

Zipkin instrumentation for Node.js and browsers
JavaScript
561
star
4

b3-propagation

Repository that describes and sometimes implements B3 propagation
518
star
5

zipkin4net

A .NET client library for Zipkin
C#
341
star
6

zipkin-php

Zipkin instrumentation for PHP
PHP
270
star
7

brave-example

A collection of examples how to use brave instrumentation in various frameworks and libraries.
Java
210
star
8

zipkin-dependencies

Spark job that aggregates zipkin spans for use in the UI
Java
174
star
9

zipkin-reporter-java

Shared library for reporting zipkin spans on transports such as http or kafka
Java
122
star
10

zipkin-ruby

zipkin-tracer ruby gem
Ruby
98
star
11

zipkin-gcp

Reporters and collectors for use in Google Cloud Platform
Java
89
star
12

zipkin-aws

Reporters and collectors for use in Amazon's cloud
Java
69
star
13

zipkin-php-example

See how much time php services spend on an http request
PHP
59
star
14

zipkin-api

Zipkin's language independent model and HTTP Api Definitions
Thrift
59
star
15

zipkin-js-example

Example project that shows how to use zipkin with javascript
JavaScript
58
star
16

zipkin-finagle

Integration between Finagle tracing to Zipkin transports such as http and kafka
Java
40
star
17

openzipkin.github.io

content for https://zipkin.io
HTML
39
star
18

zipkin-browser-extension

Chrome and Firefox browser extensions for Zipkin
JavaScript
25
star
19

pyramid_zipkin-example

See how much time python services spend on an http request
Python
14
star
20

brave-cassandra

Tracing instrumentation for Cassandra and the DataStax Java Driver
Java
12
star
21

docker-java

A small Docker image based on azul/zulu-openjdk-alpine
Shell
11
star
22

zipkin-api-example

Example of how to use the OpenApi/Swagger api spec
Go
9
star
23

brave-karaf

Karaf integration and tests for Brave (java Zipkin tracer)
Java
6
star
24

zipkin-layout-factory

Spring Boot Layout Factory for Zipkin Server derivatives
Shell
6
star
25

zipkin-support

repository for support questions raised as issues
4
star
26

zipkin-ruby-example

Ruby
4
star
27

docker-alpine

Alpine Linux base layer for Zipkin Docker images
Shell
3
star
28

zipkin-release

Documentation and templates used for projects released the same way as OpenZipkin
Python
1
star