Zipkin is a distributed tracing system
Java JavaScript CSS HTML Shell Batchfile
Latest commit 25a2007 Nov 24, 2017 @adriancole adriancole Forwards api base for the UI (#1818)
This forwards /api -> /zipkin/api so the UI can start using the v2 api.

See #1802
Permalink
Failed to load latest commit information.
.github Adds issue template to hopefully reduce the Q/A issues opened (#1496) Jan 21, 2017
.mvn/wrapper Bumps versions, notably kafka and spring-boot Nov 7, 2017
benchmarks [maven-release-plugin] prepare for next development iteration Nov 14, 2017
circleci Extracts v2 library Sep 12, 2017
src/etc Automagically deal with copyright year updates Jan 3, 2016
travis Fixes release pattern Jun 29, 2017
zipkin-autoconfigure Forwards api base for the UI (#1818) Nov 24, 2017
zipkin-collector [maven-release-plugin] prepare for next development iteration Nov 14, 2017
zipkin-guava [maven-release-plugin] prepare for next development iteration Nov 14, 2017
zipkin-junit [maven-release-plugin] prepare for next development iteration Nov 14, 2017
zipkin-server Forwards api base for the UI (#1818) Nov 24, 2017
zipkin-storage Pretties cassandra3 toString and backfills tests (#1797) Nov 16, 2017
zipkin-ui Fixes context root bug on i18n Nov 24, 2017
zipkin-zookeeper [maven-release-plugin] prepare for next development iteration Nov 14, 2017
zipkin Guard against long strings and byte arrays when encoding spans to thr… ( Nov 22, 2017
zipkin2 [maven-release-plugin] prepare for next development iteration Nov 14, 2017
.editorconfig Add .editorconfig and make sure we use LF (not CRLF) for line endings ( Jun 5, 2017
.gitattributes Explicitly sets line endings to LF for source, doc and configuration (#… May 16, 2017
.gitignore Add a Kafka 0.10+ compatible collector and attempt to integrate into … May 17, 2017
.settings.xml Attempts to satisfy license plugin Feb 2, 2017
.travis.yml Fixes archive download link for kafka Nov 20, 2017
LICENSE Initial commit Aug 3, 2015
README.md Require JDK 8 with enforcer plugin (#1803) Nov 17, 2017
RELEASE.md Polishes release configuration (#1493) Jan 17, 2017
circle.yml Disables services in CircleCI redundantly tested with Travis Jun 15, 2017
mvnw Bumps versions, notably kafka and spring-boot Nov 7, 2017
mvnw.cmd Bumps versions, notably kafka and spring-boot Nov 7, 2017
pom.xml Require JDK 8 with enforcer plugin (#1803) Nov 17, 2017

README.md

Gitter chat Build Status Download

zipkin

Zipkin is a distributed tracing system. It helps gather timing data needed to troubleshoot latency problems in microservice architectures. It manages both the collection and lookup of this data. Zipkin’s design is based on the Google Dapper paper.

This project includes a dependency-free library and a spring-boot server. Storage options include in-memory, JDBC (mysql), Cassandra, and Elasticsearch.

Quick-start

The quickest way to get started is to fetch the latest released server as a self-contained executable jar. Note that the Zipkin server requires minimum JRE 8. For example:

wget -O zipkin.jar 'https://search.maven.org/remote_content?g=io.zipkin.java&a=zipkin-server&v=LATEST&c=exec'
java -jar zipkin.jar

You can also start Zipkin via Docker.

docker run -d -p 9411:9411 openzipkin/zipkin

Once you've started, browse to http://your_host:9411 to find traces!

Check out the zipkin-server documentation for configuration details, or docker-zipkin for how to use docker-compose.

Core Library

The core library is used by both Zipkin instrumentation and the Zipkin server. Its minimum Java language level is 6, in efforts to support those writing agent instrumentation.

This includes built-in codec for Zipkin's v1 and v2 json formats. A direct dependency on gson (json library) is avoided by minifying and repackaging classes used. The result is a 155k jar which won't conflict with any library you use.

Ex.

// All data are recorded against the same endpoint, associated with your service graph
localEndpoint = Endpoint.newBuilder().serviceName("tweetie").ip("192.168.0.1").build()
span = Span.newBuilder()
    .traceId("d3d200866a77cc59")
    .id("d3d200866a77cc59")
    .name("targz")
    .localEndpoint(localEndpoint)
    .timestamp(epochMicros())
    .duration(durationInMicros)
    .putTag("compression.level", "9");

// Now, you can encode it as json
bytes = SpanBytesEncoder.JSON_V2.encode(span);

Note: The above is just an example, most likely you'll want to use an existing tracing library like Brave

Storage Component

Zipkin includes a StorageComponent, used to store and query spans and dependency links. This is used by the server and those making custom servers, collectors, or span reporters. For this reason, storage components have minimal dependencies; many run on Java 7.

Ex.

// this won't create network connections
storage = ElasticsearchStorage.newBuilder()
                              .hosts(asList("http:/myelastic:9200")).build();

// prepare a call
traceCall = storage.spanStore().getTrace("d3d200866a77cc59");

// execute it synchronously or asynchronously
trace = traceCall.execute();

// clean up any sessions, etc
storage.close();

In-Memory

The InMemoryStorage component is packaged in zipkin's core library. It is not persistent, nor viable for realistic work loads. Its purpose is for testing, for example starting a server on your laptop without any database needed.

MySQL

The MySQLStorage component currently is only tested with MySQL 5.6-7. It is designed to be easy to understand, and get started with. For example, it deconstructs spans into columns, so you can perform ad-hoc queries using SQL. However, this component has known performance issues: queries will eventually take seconds to return if you put a lot of data into it.

Cassandra v3

The Cassandra v3 component is tested against Cassandra 3.11+. It stores spans using UDTs, such that they appear like the v2 Zipkin model in cqlsh. It is designed for scale. For example, it uses a combination of SASI and manually implemented indexes to make querying larger data more performant. This store requires a spark job to aggregate dependency links.

Cassandra Legacy

The Cassandra Legacy component is tested against Cassandra 2.2+. It stores spans as opaque thrifts which means you can't read them in cqlsh. However, it is designed for scale. For example, it has manually implemented indexes to make querying larger data more performant. This store requires a spark job to aggregate dependency links.

Elasticsearch

The ElasticsearchHttpStorage component is tested against Elasticsearch 2.x and 5.x. It stores spans as json and has been designed for larger scale. This store requires a spark job to aggregate dependency links.

Running the server from source

The zipkin server receives spans via HTTP POST and respond to queries from its UI. It can also run collectors, such as Scribe or Kafka.

To run the server from the currently checked out source, enter the following. JDK 8 is required.

# Build the server and also make its dependencies
$ ./mvnw -DskipTests --also-make -pl zipkin-server clean install
# Run the server
$ java -jar ./zipkin-server/target/zipkin-server-*exec.jar

Artifacts

Library Releases

Releases are uploaded to Bintray.

Library Snapshots

Snapshots are uploaded to JFrog after commits to master.

Docker Images

Released versions of zipkin-server are published to Docker Hub as openzipkin/zipkin. See docker-zipkin for details.

Javadocs

http://zipkin.io/zipkin contains versioned folders with JavaDocs published on each (non-PR) build, as well as releases.