Jaeger Bindings for Java OpenTracing API

Overview

Build Status Coverage Status Released Version javadoc FOSSA Status

Jaeger's Tracing Instrumentation Library for Java

  • Intended to be used with Jaeger backend, but can also be configured to send traces to Zipkin.
  • Implements OpenTracing Java API.
  • Supports Java 1.6 and above

Package rename to io.jaegertracing

The group ID com.uber.jaeger has been deprecated and moved to a different repository. Please switch to io.jaegertracing, as the old group ID will be maintained only for bug fixes.

Contributing and Developing

Please see CONTRIBUTING.md.

Core Modules

Click through for more detailed docs on specific modules.

  • jaeger-client: the module that instrumented applications should usually include
  • jaeger-core: the core implementation of the OpenTracing API Java Docs
  • jaeger-thrift: set of components that send data to the backend

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.

Please use the latest version: Released Version

In the usual case, you just need to include the following dependency to your project:

<dependency>
    <groupId>io.jaegertracing</groupId>
    <artifactId>jaeger-client</artifactId>
    <version>$jaegerVersion</version>
</dependency>

This will bring a concrete sender, such as jaeger-thrift, as well as the jaeger-tracerresolver and jaeger-core.

Thrift version conflicts

The Jaeger Java Client uses org.apache.thrift:libthrift:0.11.0. By default, declaring a dependency on the jaeger-thrift module will bring a non-shaded version of Thrift (and others). A shaded version of the dependency is available with the classifier shadow.

Instantiating the Tracer

Please see jaeger-core/README.

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

License

Apache 2.0 License.

Comments
  • Drop Java 6 Compatibility

    Drop Java 6 Compatibility

    Requirement - what kind of business use case are you trying to solve?

    Allow use of Java 8 and above in client. This would simplify some of the code.

    Problem - what in Jaeger blocks you from solving the requirement?

    For some reason, we preserve Java 6 compatibility in the client. @felixbarny for why this was added last year when Java 6 is basically deprecated/ancient technology.

    Proposal - what do you suggest to solve the problem or improve the existing situation?

    Stop supporting Java 6 in future releases.

    help wanted good first issue 
    opened by isaachier 42
  • Consider using manual thrift payload generation

    Consider using manual thrift payload generation

    @adriancole did this in Zipkin by implementing thrift-like serialization manually. However, if we do this, I'd only do it along with upgrading to the new data model.

    • [ ] manual thrift serializer
    • [ ] unit tests validating that regular Thrift serializer can read the manually generated bytes payload
    enhancement 
    opened by yurishkuro 29
  • Upgrades internals to Zipkin v2 library

    Upgrades internals to Zipkin v2 library

    Which problem is this PR solving?

    The current zipkin integration encourages use of a dead version of a library (io.zipkin.reporter)

    Short description of the changes

    Recent version of io.zipkin.zipkin2:zipkin has been backported to support thrift encoding. This updates the corresponding sender here to use that, notably to migrate off the io.zipkin.reporter libraries which receive no updates.

    opened by codefromthecrypt 27
  • Persisting incomplete spans

    Persisting incomplete spans

    I have a question/ feature request:

    We want to utilize Jaeger as Tracing/Logging framework for processes and web services. It is important for us that a span gets persisted once it's created and not only when it is finished.

    Let's assume the following scenario: A process which has some substeps gets executed and runs like 5-10 minutes. The process creates a span with its name and some tags. Also, every substep creates a span. Once finished the span is being persisted with the next client flush. This means for the first span, that it's persisted after 10 minutes. To monitor the execution, it is important for us that the first span is being persisted after creation and updated when finished.

    (just to clarify: by process I mean hierarchical steps of work running in the JVM not a os process)

    I think this would be a nice feature in general as it would be possible to see long running spans and spans that never finish, cause the applications shuts down, has connectivity problems or other issues during processing that prevent it to send the span to the collector at the end.

    What do you think about this?

    enhancement 
    opened by phal0r 25
  • Automate release process

    Automate release process

    Current release process is documented in the readme and is fairly painful. The most ideal process would be to push a tag and have the release happen automatically (but I am not clear what happens to the changelog in this case). Using a make command would also be acceptable if it can do a bunch of changes in a row like bump the version, publish, bump version to snapshot again, and then automatically close & release the repo from staging to maven via sonatype.

    help wanted 
    opened by yurishkuro 25
  • Rename 'io.jaegertracing.Span' to 'io.jaegertracing.JaegerSpan'

    Rename 'io.jaegertracing.Span' to 'io.jaegertracing.JaegerSpan'

    The Span class clashes with OpenTracing's Span, which is confusing when debugging and reading code like:

    public interface Sender {
      int append(Span span) throws SenderException;
    }
    

    It's also not clear what is part of the public API and what is not.

    I suggest renaming the class io.jaegertracing.Span to io.jaegertracing.internal.JaegerSpan. This class would still extend io.opentracing.Span. Usage of JaegerSpan would be allowed only by internal components and will not be part of the public API.

    This means that the Span from the sender example above would be OpenTracing's, as well as Reporter#report(Span).

    The same applies to Tracer and SpanContext.

    opened by jpkrohling 24
  • Implement Zipkin 2 JSON Sender

    Implement Zipkin 2 JSON Sender

    The existing ZipkinSender class only supported the Thrift v1 protocol, but the new Zipkin2Sender supports both v1 and v2 JSON. Otherwise, functionality is mostly the same.

    There is some conceptually duplicate code in the Sender classes due to the use of different classes between Zipkin 1/2 but it seemed overly complicated to adapt them to a common adapter interface.

    Fixes #383.

    opened by keitwb 21
  • Release failures

    Release failures

    Travis build: https://travis-ci.org/jaegertracing/jaeger-client-java/jobs/365086226#L1333

    Errors when repsitory is closed manually:

    failureMessage | Missing SHA1: '/io/jaegertracing/jaeger-thrift/0.27.0-RC1/jaeger-thrift-0.27.0-RC1-sources.jar.sha1'
    -- | --
    failureMessage | Missing MD5: '/io/jaegertracing/jaeger-thrift/0.27.0-RC1/jaeger-thrift-0.27.0-RC1-sources.jar.md5'
    failureMessage | Missing SHA1: '/io/jaegertracing/jaeger-thrift/0.27.0-RC1/jaeger-thrift-0.27.0-RC1.pom.sha1'
    failureMessage | Missing MD5: '/io/jaegertracing/jaeger-thrift/0.27.0-RC1/jaeger-thrift-0.27.0-RC1.pom.md5'
    failureMessage | Missing SHA1: '/io/jaegertracing/jaeger-core/0.27.0-RC1/jaeger-core-0.27.0-RC1.jar.sha1'
    failureMessage | Missing MD5: '/io/jaegertracing/jaeger-core/0.27.0-RC1/jaeger-core-0.27.0-RC1.jar.md5'
    failureMessage | Missing SHA1: '/io/jaegertracing/jaeger-crossdock/0.27.0-RC1/jaeger-crossdock-0.27.0-RC1.jar.sha1'
    failureMessage | Missing MD5: '/io/jaegertracing/jaeger-crossdock/0.27.0-RC1/jaeger-crossdock-0.27.0-RC1.jar.md5'
    
    bug 
    opened by pavolloffay 21
  • Side effects of imprecise clock

    Side effects of imprecise clock

    I found an interesting problem that took some time to track down.

    Basically spans in the jaeger UI were "centered" in a weird way. Initially I thought that it's some UI issue, but after comparing the json returned by jaeger-query with cassandra it turned out that jaeger-query completely messes span start times. And by completely I mean that span taking 1ms was shifted by 3ms. Here's how it looks like:

    Alt text

    In this example "child 2" should happen as the last span inside the "parent" - should be stuck to the right edge of the parent. There's no delay because all those spans are reported by the same process.

    After digging through the jaeger code I found ClockSkew and there are two problems here:

    1. ClockSkew adjust span start times if they overlap with their parent. It does it only if parent and child are reported by different hosts, but the host is taken from "ip" tag of the process. If it's missing the default is to assume that these are different hosts.

    2. jaeger-client-java by default uses SystemClock which has millisecond precision, but timestamps reported to jaeger are in microseconds. To convert the time to micros it multiplies it by 1000:

      public long currentTimeMicros() {  return System.currentTimeMillis() * 1000; }
      

      One can think of it as rounding down exact start time to milliseconds.

      Span duration on the other hand is calculated with more precise System.nanoTime. As a result of this rounding it's possible that:

      round(parent.start) + parent.duration < round(child.start) + child.duration
      

      for children which end at the same time as the parent it happens very often.

    So - child span end time exceeds parent's finish time by between 0 and 1000 micros which in combination with missing process "ip" tag triggers clock skew adjuster. And for very long parents and very short children the adjustment is drastic (around 50% of parent duration).

    There are two options:

    1. change the default in jaeger-query
    2. better clock implementation in jaeger-client-java
    3. add "ip" process tag by default

    I guess that the default make sense so better clock implementation would be a good improvement.

    opened by mabn 21
  • Change maven group to io.jaegertracing

    Change maven group to io.jaegertracing

    As discussed on friday's call, the maven group should be changed from com.uber.jaeger to io.jaegertracing. The proposal was to make this change in the v0.22.0 branch so that it gets merged to master as part of the OT Java 0.31.0 change.

    However the implication is that the Java package would also change (as it usually follows the maven group), and this would be a breaking change - so wanted to make sure this is clear (as wasn't explicitly discussed)?

    Other option would be to make this change when moving to version 1,0.

    opened by objectiser 20
  • WIP - Add Shipkit for release management

    WIP - Add Shipkit for release management

    Signed-off-by: Juraci Paixão Kröhling [email protected]

    Which problem is this PR solving?

    • All our release problems :-)
    • Resolves #536

    Short description of the changes

    • Removed everything related to the way we did releases before
    • Added Shipkit and all it needs to do releases now
    opened by jpkrohling 19
Releases(v1.8.1)
  • v1.8.1(Jul 1, 2022)

  • v1.8.0(Jan 16, 2022)

  • v1.7.0(Dec 26, 2021)

    • Optimize TextMapCodec::contextFromString (#799) -- amirhadadi
    • jaeger-thrift: Shade kotlin runtime + other libraries (#801) -- ohadgur
    • Drop support for Java 1.6 and 1.7 (#802) -- Yuri Shkuro
    • Reduce locking in JaegerSpan (#795) -- amirhadadi
    • Fix repeated error logging for HttpSender (#785) -- Radek Kraus
    Source code(tar.gz)
    Source code(zip)
  • v1.5.0(Jan 25, 2021)

    • Upgrade okhttp to 4.9.0 (#749) -- Yuri Shkuro
    • Do not strip leading zeros from trace IDs (#746) -- Yuri Shkuro
    • Document how to encrypt travis secrets (#744) -- Pavol Loffay
    Source code(tar.gz)
    Source code(zip)
  • v1.4.0(Sep 7, 2020)

    • Process sampling tag before handling other tags (fixes #738) -- Audrius Butkevicius>
    • Add 'w3c' to valid JAEGER_PROPAGATION options -- by chgl
    • Allow SystemClock to recognize non-GA OpenJDK versions -- Andriy Redko
    Source code(tar.gz)
    Source code(zip)
  • v1.3.2(Aug 3, 2020)

    • Log SenderExceptions the first time they occur in a row (#729) -- Phillip Schichtel
    • Make UdpSender lazy to be able to recover from early DNS issues (#726) -- Phillip Schichtel
    Source code(tar.gz)
    Source code(zip)
  • v1.3.0(Jun 30, 2020)

    • Add MDCScopeManager for correlating logs with trace context (#718) -- Avi Maslati
    • Fix publishing jaeger-thrift shadow artifact (#704) -- Zbigniew Halas
    • Do not encode span context in HTTP_HEADERS format (#721) -- Clément MATHIEU
    • Support microseconds timestamp accuracy for JDK 9 and above (#712) -- Idan Sheinberg
    • Ignore case when extracting W3C TraceContext (#711) -- Yanming Zhou
    • Support jaeger-debug-id in TraceContextCodec (#701) -- Yanming Zhou
    • Avoid warning if traceparent not present (#698) -- Yanming Zhou
    Source code(tar.gz)
    Source code(zip)
  • v1.2.0(Mar 11, 2020)

  • v0.35.2(May 6, 2019)

  • v0.35.0(May 2, 2019)

  • v0.34.0(Mar 8, 2019)

  • v0.33.1(Jan 3, 2019)

  • v0.33.0(Dec 21, 2018)

  • v0.32.0(Oct 15, 2018)

  • v0.31.0(Aug 29, 2018)

  • v0.30.6(Aug 23, 2018)

    • Fine-tune bootstrap logging (#531, @jpkrohling)
    • Add specification version to jars, and impl-title/version & spec version to javadoc and sources jars (#533, @objectiser)
    Source code(tar.gz)
    Source code(zip)
  • v0.30.5(Aug 22, 2018)

    • Move jaeger-thrift shadow jar to its own classifier (#526, @jpkrohling)
    • Mark gson field in HttpSamplingManager as ignored for toString (#528, @jpkrohling)
    • Use abstract factory pattern to allow subclassing core Jaeger types (#509, @isaachier)
    • Use SenderFactory classloader for ServiceLoader (#523, @dbuchhorn)
    • Reduce visibility of TextMapCodec.contextFromString to package scope (#519, @isaachier)
    • Move contextFromString out of JaegerSpanContext into TextMapCodec (#517, @isaachier)
    Source code(tar.gz)
    Source code(zip)
  • v0.30.4(Aug 13, 2018)

  • v0.30.3(Jul 26, 2018)

    • Fix concurrent modification exception on logs and tags (#500, @pavolloffay)
    • Remove unwanted classes from jaeger-thrift shadowed jar (#498, @mdvorak)
    Source code(tar.gz)
    Source code(zip)
  • v0.30.2(Jul 13, 2018)

    • Do not log null spancontext references (#487, @objectiser)
    • Fix jaeger-client dependency jaeger-thrift no-shadow artifact (#486, @jpkrohling)
    Source code(tar.gz)
    Source code(zip)
  • v0.30.1(Jul 10, 2018)

    • Add "serialVersionUID" for exceptions to avoid InvalidClassException (#481, @quaff)
    • Add jaeger-client module (#479, @jpkrohling)
    • Fix wrong package declaration (#480, @quaff)
    • Make GuaranteedThroughputSampler public (#457, @quaff)
    • Fix version retrieval from jaeger.properties (#478, @jpkrohling)
    Source code(tar.gz)
    Source code(zip)
  • v0.30.0(Jul 4, 2018)

    WARNING: this release breaks compatibility with previous versions.

    The most disruptive changes are:

    1. The module jaeger-core is not bringing Thrift senders anymore. Instead, client applications should now depend on the jaeger-thrift module, which will bring the jaeger-core transitively

    2. The first step in establishing the public API was made: all classes were moved to an internal package, to signal that they are not supposed to be used directly. Classes not in the internal package are part of the new public API and compatibility should follow semver. Clients currently using the Tracer.Builder mechanism are encouraged to switch over to the Configuration approach. If you face a situation that cannot be done with this approach, do let us know.

    3. Related to the point above: we now have also a SPI package, intended to be consumed by service providers (components implementing Senders, Reporters, Samplers). If you are implementing a service, do let us know! We need your feedback before moving forward with this API.

    4. Jaeger types related to the OpenTracing standard were renamed, to avoid name clashes: io.jaegertracing.Tracer is now JaegerTracer.

    Complete list of changes:

    • Define some classes internal (#470, @jpkrohling)
    • Change return types from Jaeger Span/Tracer/Context to Jaeger types (#469, @jpkrohling)
    • Rename Jaeger's Span to JaegerSpan (#454, @jpkrohling)
    • Upgrades internals to Zipkin v2 library (#456, @adriancole)
    • Make jaeger-thrift's shaded JAR the default one (#461, @jpkrohling)
    • Treat gauge.update() parameter as new value, not delta (#463, @mdouaihy)
    • Adjust thrift shadow configuration and version (#458, @jpkrohling)
    • Remove dependency from jaeger-core to jaeger-thrift (#449, @jpkrohling)
    Source code(tar.gz)
    Source code(zip)
  • v0.29.0(Jun 7, 2018)

  • v0.28.0(May 24, 2018)

    Source code(tar.gz)
    Source code(zip)
  • v0.27.0(May 7, 2018)

    • Enable development and dependency versions to be overridden from the commandline (#397)
    • Add tests for metrics exposed via prometheus (#386)
    • Change groupid to io.jaegertracing and remove instrumentations (#375). Sources with com.uber.jaeger have been moved to https://github.com/jaegertracing/legacy-client-java
    • Remove reference to JAEGER_DISABLE_GLOBAL_TRACER (#379)
    • Avoid direct access to apache thrift from jaeger-core via transitive dependency through jaeger-thrift (#374)
    • Make some methods in HttpSender.Builder public (#376)
    Source code(tar.gz)
    Source code(zip)
  • v0.26.0(Mar 19, 2018)

    • Avoid host lookups if trace tags have already been provided (#371)
    • Update the ReporterConfig to set Sender Correctly (#370)
    • Fix for issue 366, fix deprecated code in example (#367)
    Source code(tar.gz)
    Source code(zip)
  • v0.25.0(Mar 7, 2018)

    • Consolidate codec exception handling and logs exceptions (#362)
    • Deprecated StatsReporter (#349) <Juraci Paixão Kröhling>
    • Ignores B3 headers if invalid values are provided (#355) <Juraci Paixão Kröhling>
    • Refactor public constructor API (#346)
    • Expand exception logs (#168)
    • Deprecate JerseyServerFilter#JerseyServerFilter(Tracer, TraceContext) (#352)
    • Micrometer support (#335) <Juraci Paixão Kröhling>
    • Metrics are now consistent with Go (#335) <Juraci Paixão Kröhling>
    • Updated Trace Resolver (#347)
    Source code(tar.gz)
    Source code(zip)
Owner
Jaeger - Distributed Tracing Platform
Jaeger - Distributed Tracing Platform
an open source solution to application performance monitoring for java server applications

Stagemonitor is a Java monitoring agent that tightly integrates with time series databases like Elasticsearch, Graphite and InfluxDB to analyze graphe

stagemonitor 1.7k Dec 30, 2022
A lightweight platform monitoring tool for Java VMs

Sysmon - lightweight platform monitoring for Java VMs Sysmon is a lightweight platform monitoring tool. It's designed to gather performance data (CPU,

Palantir Technologies 152 Jan 26, 2022
inspectIT is the leading Open Source APM (Application Performance Management) tool for analyzing your Java (EE) applications.

?? inspectIT OpenCensus Edition has been released ?? The inspectIT OCE project provides an improved Java agent newly developed from scratch focusing o

inspectIT 531 Dec 13, 2022
Spring MSA api gateway & service discovery with consul & Jaeger & Cassandra

Spring-Cloud-MSA 준비 Cassandra 서버를 준비한다 table.sql 파일로 keyspace와 테이블을 만들어 둔다 Consul 1.11.1버전 기준 https://www.consul.io/downloads 에서 1.11.1 버전 운영체제 맞게 다운

INSUNG CHOI 2 Nov 22, 2022
Best-of-breed OpenTracing utilities, instrumentations and extensions

OpenTracing Toolbox OpenTracing Toolbox is a collection of libraries that build on top of OpenTracing and provide extensions and plugins to existing i

Zalando SE 181 Oct 15, 2022
Best-of-breed OpenTracing utilities, instrumentations and extensions

OpenTracing Toolbox OpenTracing Toolbox is a collection of libraries that build on top of OpenTracing and provide extensions and plugins to existing i

Zalando SE 181 Oct 15, 2022
Best-of-breed OpenTracing utilities, instrumentations and extensions

OpenTracing Toolbox OpenTracing Toolbox is a collection of libraries that build on top of OpenTracing and provide extensions and plugins to existing i

Zalando SE 181 Oct 15, 2022
Java Bindings for V8

J2V8 J2V8 is a set of Java bindings for V8. J2V8 focuses on performance and tight integration with V8. It also takes a 'primitive first' approach, mea

EclipseSource 2.3k Jan 4, 2023
Java/JNI bindings to libpostal for for fast international street address parsing/normalization

jpostal These are the Java/JNI bindings to libpostal, a fast, multilingual NLP library (written in C) for parsing/normalizing physical addresses aroun

openvenues 94 Oct 15, 2022
Java Foreign Linker bindings to Lua

jpanlua Java bindings to liblua using JEP 398: Foreign Linker API. Requires JDK 16 or above. Requires -Dforeign.restricted=permit JRE flag. Exports pa

Aly Cerruti 5 Dec 24, 2021
jextract is a tool which mechanically generates Java bindings from a native library headers.

Jextract jextract is a tool which mechanically generates Java bindings from a native library headers. This tools leverages the clang C API in order to

OpenJDK 120 Dec 30, 2022
RxJava bindings for JavaFX

RxJavaFX: JavaFX bindings for RxJava Read the free eBook Learning RxJava with JavaFX to get started. RxJavaFX is a lightweight library to convert Java

ReactiveX 513 Dec 27, 2022
Custom JavaFX bindings made easy with lambdas.

EasyBind EasyBind leverages lambdas to reduce boilerplate when creating custom bindings, provides a type-safe alternative to Bindings.select* methods

Tomas Mikula 146 May 29, 2022
Clojure bindings for the Chromium Embedded Framework

clj-cef Clojure bindings for the Chromium Embedded Framework Dependency: Rationale From https://bitbucket.org/chromiumembedded/cef/src/master/ Some us

Adrian 45 Nov 2, 2022
🍏 A collection of partial JNA bindings for various macOS frameworks. (e.g. Foundation, AppKit, etc.)

JNApple ?? A collection of partial JNA bindings for various macOS frameworks. (e.g. Foundation, AppKit, etc.) Usage These are just some common example

Iridescent 3 Jun 19, 2022
RxJava bindings for Android

RxAndroid: Reactive Extensions for Android Android specific bindings for RxJava 3. This module adds the minimum classes to RxJava that make writing re

ReactiveX 19.7k Dec 28, 2022
SynchronizeFX - a library for JavaFX 2 and later that enables property bindings between different JVMs

SynchronizeFX - a library for JavaFX 2 and later that enables property bindings between different JVMs, both on a local computer and over the network.

Manuel Mauky 8 Jul 24, 2020
A Java API wrapper for the pastemyst api

Pastemyst.java What is pastemyst.java? pastemyst.java is a pastemyst API Wrapper, written in Java. The library is in early development, and all contri

YeffyCodeGit 8 Sep 28, 2022