Jaeger Bindings for Java OpenTracing API
Java Other
Latest commit f027bc7 Dec 21, 2016 @vprithvi vprithvi committed on GitHub Remove sampling strategy (#118)
Permalink
Failed to load latest commit information.
config/checkstyle Record sampling strategy as span tags (#40) Sep 6, 2016
gradle Add codecov-io for code coverage (#113) Dec 14, 2016
idl @ 157a5e7 Implement Crossdock TChannel requests (#33) Aug 26, 2016
jaeger-apachehttpclient Add codecov-io for code coverage (#113) Dec 14, 2016
jaeger-context Add codecov-io for code coverage (#113) Dec 14, 2016
jaeger-core Remove sampling strategy (#118) Dec 22, 2016
jaeger-crossdock Add codecov-io for code coverage (#113) Dec 14, 2016
jaeger-dropwizard Add codecov-io for code coverage (#113) Dec 14, 2016
jaeger-jaxrs2 Add codecov-io for code coverage (#113) Dec 14, 2016
jaeger-thrift Publish a shadow jar with thrift 0.9.2 (#83) Oct 26, 2016
jaeger-zipkin Add codecov-io for code coverage (#113) Dec 14, 2016
travis/docker-thrift Downgrade to thrift 0.9.2 (#73) Oct 7, 2016
.gitignore Fix .gitignore (#77) Oct 17, 2016
.gitmodules Initial commit Jul 10, 2016
.travis.yml Add codecov-io for code coverage (#113) Dec 14, 2016
CHANGELOG.rst Preparing release 0.17.0 Dec 2, 2016
Makefile Fix checkstyle and use google style guide (#51) Sep 13, 2016
README.md Add codecov-io for code coverage (#113) Dec 14, 2016
RELEASE.md Add codecov-io for code coverage (#113) Dec 14, 2016
build.gradle Add codecov-io for code coverage (#113) Dec 14, 2016
gradlew Add codecov-io for code coverage (#113) Dec 14, 2016
gradlew.bat Add codecov-io for code coverage (#113) Dec 14, 2016
license-template Initial commit Jul 10, 2016
settings.gradle Add support for Apache Http Client (#63) Sep 27, 2016

README.md

Build Status Coverage Status Released Version

Jaeger Bindings for Java OpenTracing API

This is a client side library that implements Java OpenTracing API, with Zipkin-compatible data model.

Core Modules

Click through for more detailed docs on specific modules.

Add-on Modules

Importing Dependencies

All artifacts are published to Maven Central. Snapshot artifacts are also published to Sonatype. Follow these instructions to add the snapshot repository to your build system.

Add the required dependencies to your project. Usually, this would only be the add-ons you require. Please use the latest version: Released Version

For e.g, to depend on the core jaeger library, you'd include the following

<dependency>
    <groupId>com.uber.jaeger</groupId>
    <artifactId>jaeger-core</artifactId>
    <version>$jaegerVersion</version>
</dependency>

Thrift version conflicts

Jaeger client uses org.apache.thrift:libthrift:0.9.2. If your project depends on a different version of libthrift, it is recommended that you use the shaded jaeger-thrift jar we publish which packages it's own libthrift.

To depend on the shaded jar, add the following to your maven build. Note that this is only supported for a jaeger version >= 0.15.0

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.uber.jaeger</groupId>
      <artifactId>jaeger-thrift</artifactId>
      <classifier>thrift92</classifier>
      <version>$jaegerVersion</version>
    </dependency>
  </dependencies>
</dependencyManagement>

In-process Context Propagation

jaeger-context defines ThreadLocalTraceContext implementation of TraceContext that can be used for propagating the current tracing Span throughout the application without changing the application's code. However, if the application is starting new threads or is using thread pools, the thread-local context is not going to be carried over into the execution in the next thread. To maintain context propagation, a wrapper TracedExecutorService is provided that automatically transfers the context onto the new threads.

ExecutorService instrumentedExecutorService = TracingUtils.tracedExecutor(wrappedExecutorService);

Testing

When testing tracing instrumentation it is often useful to make sure that all spans are being captured, which is not the case in production configurations where heavy sampling is applied by default. The following configuration can be provided to affect which sampling is applied to the new traces:

sampler:
   type: const # can either be const, probabilistic, or ratelimiting
   param: 1  # can either be an integer, a double, or an integer

The valid values for type are:

  • const: configures a sampler that always makes the same decision for new traces depending on the param: always no for param=0, always yes otherwise.
  • probabilistic: configures a sampler that samples traces with probability equal to param (must be between 0.0 and 1.0)
  • ratelimiting: configures a samlper that samples traces with a certain rate per second equal to param

Debug Traces (Forced Sampling)

Programmatically

The OpenTracing API defines a sampling.priority standard tag that can be used to affect the sampling of a span and its children:

import io.opentracing.tag.Tags;

Tags.SAMPLING_PRIORITY.set(span, (short) 1);

Via HTTP Headers

Jaeger Tracer also understands a special HTTP Header jaeger-debug-id, which can be set in the incoming request, e.g.

curl -H "jaeger-debug-id: some-correlation-id" http://myhost.com

When Jaeger sees this header in the request that otherwise has no tracing context, it ensures that the new trace started for this request will be sampled in the "debug" mode (meaning it should survive all downsampling that might happen in the collection pipeline), and the root span will have a tag as if this statement was executed:

span.setTag("jaeger-debug-id", "some-correlation-id")

This allows using Jaeger UI to find the trace by this tag.

Developing

  1. git submodule init update
  2. ./gradlew googleJavaFormat clean test

Code Style

This project uses google java style. It is recommended to set up a git precommit hook as follows.

cat>.git/hooks/pre-commit
#!/bin/sh
#
# Pre-commit hooks
# Format code using the google formatter
echo "pre-commit code format"
./gradlew googleJavaFormat
^D
chmod a+x .git/hooks/pre-commit

You can also setup the IntelliJ plugin to reformat code from within your IDE

Lombok

This project uses Lombok to reduce boilerplate. You can setup the IntelliJ plugin to add IDE support.

License

The MIT License.