Jaeger Bindings for Go OpenTracing API.
Go Makefile Other
Latest commit 62d8e62 Jan 20, 2017 @yurishkuro yurishkuro committed on GitHub Bump version to 2.x and add missing features
Permalink
Failed to load latest commit information.
config Allow users to configure samplingRefreshInterval (#75) Jan 19, 2017
crossdock Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
idl @ 5054a00 Update idl (#63) Oct 31, 2016
internal/spanlog Upgrade to the new K/V Span logging API (#42) Sep 27, 2016
scripts Update make fmt to automatically add license (#74) Jan 12, 2017
testutils Update make fmt to automatically add license (#74) Jan 12, 2017
thrift-gen Update idl (#63) Oct 31, 2016
thrift Rename thrift/gen to thrift-gen May 31, 2016
transport Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
utils Update make fmt to automatically add license (#74) Jan 12, 2017
zipkin Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
.gitignore Rename thrift/gen to thrift-gen May 31, 2016
.gitmodules Upgrade thrift to match tchannel, remove unused dependencies Jun 1, 2016
.travis.yml Remove call to Github API to get current branch name (#48) Sep 29, 2016
CHANGELOG.md Bump version to 2.x and add missing features Jan 20, 2017
CONTRIBUTING.md Update make fmt to automatically add license (#74) Jan 12, 2017
LICENSE Update make fmt to automatically add license (#74) Jan 12, 2017
Makefile Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
README.md Support Zipkin HTTP B3 propagation format (#72) Jan 20, 2017
constants.go Add adaptive sampler (#57) Oct 21, 2016
constants_test.go Update make fmt to automatically add license (#74) Jan 12, 2017
context.go Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
context_test.go Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
doc.go Add package documentation for introduction on godoc.org Jun 1, 2016
glide.lock Include subpackage dependency opentracing-go/log (#68) Dec 14, 2016
glide.yaml Include subpackage dependency opentracing-go/log (#68) Dec 14, 2016
interop.go Implement immutable SpanContext (#27) Aug 5, 2016
logger.go Migrate from internal repostory May 20, 2016
logger_test.go Update make fmt to automatically add license (#74) Jan 12, 2017
metrics.go Add update function to adaptive sampler (#59) Oct 28, 2016
metrics_test.go Update make fmt to automatically add license (#74) Jan 12, 2017
propagation.go Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
propagation_test.go Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
reporter.go Add Zipkin HTTP transport (#50) Oct 5, 2016
reporter_test.go Fix logic for traces started/joined metric (#53) Oct 14, 2016
sampler.go Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
sampler_options.go Allow users to configure samplingRefreshInterval (#75) Jan 19, 2017
sampler_test.go Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
span.go Update sampler API in preparation for adaptive sampling logic (#55) Oct 21, 2016
span_test.go Update make fmt to automatically add license (#74) Jan 12, 2017
stats_reporter.go Fix logic for traces started/joined metric (#53) Oct 14, 2016
stats_reporter_test.go Update make fmt to automatically add license (#74) Jan 12, 2017
thrift_span.go Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
thrift_span_test.go Update make fmt to automatically add license (#74) Jan 12, 2017
tracer.go Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
tracer_options.go Upgrade to the new K/V Span logging API (#42) Sep 27, 2016
tracer_test.go Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
zipkin.go Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017
zipkin_test.go Replace uint64 trace/spanID with 128bit/64bit strong types (#79) Jan 20, 2017

README.md

GoDoc Build Status Coverage Status OpenTracing Compatible

Jaeger Bindings for Go OpenTracing API

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

Initialization

import (
    "github.com/opentracing/opentracing-go"
    "github.com/uber/jaeger-client-go/config"
)

type AppConfig struct {
    ...
    Tracing config.Configuration
    ...
}

func main() {
    cfg := loadAppConfig() // e.g. from a yaml file

    tracer, closer, err := cfg.Tracing.New("your-service-name", nil)
    // check err
    defer closer.Close()

    opentracing.InitGlobalTracer(tracer)
    ...
}

Metrics & Monitoring

The tracer emits a number of different metrics, defined in metrics.go. The monitoring backend is expected to support tag-based metric names, e.g. instead of statsd-style string names like counters.my-service.jaeger.spans.started.sampled, the metrics are defined by a short name and a collection of key/value tags, for example: name:traces, state:started, sampled:true.

The monitoring backend is represented by the StatsReporter interface. An implementation of that interface should be passed to the New method during tracer initialization:

    stats := // create StatsReporter implementation
    tracer := config.Tracing.New("your-service-name", stats)

By default, a no-op NullStatsReporter is used.

Logging

The tracer can be configured with an optional logger, which will be used to log communication errors, or log spans if a logging reporter option is specified in the configuration. The logging API is abstracted by the Logger interface. A logger instance implementing this interface can be set on the Config object before calling the New method.

Instrumentation for Tracing

Since this tracer is fully compliant with OpenTracing API 1.0, all code instrumentation should only use the API itself, as described in the opentracing-go documentation.

Features

Reporters

A "reporter" is a component receives the finished spans and reports them to somewhere. Under normal circumstances, the Tracer should use the default RemoteReporter, which sends the spans out of process via configurable "transport". For testing purposes, one can use an InMemoryReporter that accumulates spans in a buffer and allows to retrieve them for later verification. Also available are NullReporter, a no-op reporter that does nothing, a LoggingReporter which logs all finished spans using their String() method, and a CompositeReporter that can be used to combine more than one reporter into one, e.g. to attach a logging reporter to the main remote reporter.

Span Reporting Transports

The remote reporter uses "transports" to actually send the spans out of process. Currently two supported transports are Thrift over UDP and Thrift over TChannel. More transports will be added in the future.

The only data format currently used is Zipkin Thrift 1.x span format, which allows easy integration of the tracer with Zipkin backend.

Sampling

The tracer does not record all spans, but only those that have the sampling bit set in the flags. When a new trace is started and a new unique ID is generated, a sampling decision is made whether this trace should be sampled. The sampling decision is propagated to all downstream calls via the flags field of the trace context. The following samplers are available:

  1. RemotelyControlledSampler uses one of the other simpler samplers and periodically updates it by polling an external server. This allows dynamic control of the sampling strategies.
  2. ConstSampler always makes the same sampling decision for all trace IDs. it can be configured to either sample all traces, or to sample none.
  3. ProbabilisticSampler uses a fixed sampling rate as a probability for a given trace to be sampled. The actual decision is made by comparing the trace ID with a random number multiplied by the sampling rate.
  4. RateLimitingSampler can be used to allow only a certain fixed number of traces to be sampled per second.

Baggage Injection

The OpenTracing spec allows for baggage, which are key value pairs that are added to the span context and propagated throughout the trace. An external process can inject baggage by setting the special HTTP Header jaeger-baggage on a request

curl -H "jaeger-baggage: key1=value1, key2=value2" http://myhost.com

Baggage can also be programatically set inside your service by doing the following

span.SetBaggageItem("key", "value")

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 (
    "github.com/opentracing/opentracing-go"
    "github.com/opentracing/opentracing-go/ext"
)

span := opentracing.SpanFromContext(ctx)
ext.SamplingPriority.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.

Zipkin HTTP B3 compatible header propagation

Jaeger Tracer supports Zipkin B3 Propagation HTTP headers, which are used by a lot of Zipkin tracers. This means that you can use Jaeger in conjunction with e.ge these OpenZipkin tracers.

However it is not the default propagation format, see here how to set it up.

License

The MIT License.