Categorygithub.com/jhorowitz/jaeger-client-go
modulepackage
2.0.0+incompatible
Repository: https://github.com/jhorowitz/jaeger-client-go.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
23
Dependents
0
Files
2.1k SLOC

# README

GoDoc Build Status Coverage Status OpenTracing 1.0 Enabled

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] (https://github.com/opentracing/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.g. these OpenZipkin tracers.

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

License

The MIT License.

# Packages

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
Package transport defines various transports that can be used with RemoteReporter to send spans out of process.
No description provided by the author
Package zipkin comprises Zipkin functionality for Zipkin compatiblity.

# Functions

ContextFromString reconstructs the Context encoded in a string.
NewAdaptiveSampler adaptiveSampler is a delegating sampler that applies both probabilisticSampler and rateLimitingSampler via the guaranteedThroughputProbabilisticSampler.
NewCompositeReporter creates a reporter that ignores all reported spans.
NewConstSampler creates a ConstSampler.
NewGuaranteedThroughputProbabilisticSampler returns a delegating sampler that applies both probabilisticSampler and rateLimitingSampler.
NewInMemoryReporter creates a reporter that stores spans in memory.
NewLoggingReporter creates a reporter that logs all reported spans to provided logger.
NewMetrics creates a new Metrics struct and initializes it.
NewNullMetrics creates a new Metrics struct that won't report any metrics.
NewNullReporter creates a no-op reporter that ignores all reported spans.
NewProbabilisticSampler creates a sampler that randomly samples a certain percentage of traces specified by the samplingRate, in the range between 0.0 and 1.0.
NewRateLimitingSampler creates a sampler that samples at most maxTracesPerSecond.
NewRemotelyControlledSampler creates a sampler that periodically pulls the sampling strategy from an HTTP sampling server (e.g.
NewRemoteReporter creates a new reporter that sends spans out of process by means of Sender.
NewSpanContext creates a new instance of SpanContext.
NewTracer creates Tracer implementation that reports tracing to Jaeger.
SpanIDFromString creates a SpanID from a hexadecimal string.
TraceIDFromString creates a TraceID from a hexadecimal string.

# Constants

JaegerBaggageHeader is the name of the HTTP header that is used to submit baggage.
JaegerClientVersion is the version of the client library reported as Span tag.
JaegerClientVersionTagKey is the name of the tag used to report client version.
JaegerDebugHeader is the name of HTTP header or a TextMap carrier key which, if found in the carrier, forces the trace to be sampled as "debug" trace.
SamplerParamTagKey reports the parameter of the sampler, like sampling probability.
SamplerTypeConst is the type of sampler that always makes the same decision.
SamplerTypeLowerBound is the type of sampler that samples only up to a fixed number of traces per second.
SamplerTypeProbabilistic is the type of sampler that samples traces with a certain fixed probability.
SamplerTypeRateLimiting is the type of sampler that samples only up to a fixed number of traces per second.
SamplerTypeRemote is the type of sampler that polls Jaeger agent for sampling strategy.
SamplerTypeTagKey reports which sampler was used on the root span.
SpanContextFormat is a constant used as OpenTracing Format.
TraceBaggageHeaderPrefix is the prefix for http headers used to propagate baggage.
TracerHostnameTagKey used to report host name of the process.
TracerStateHeaderName is the http header name used to propagate tracing context.
ZipkinSpanFormat is an OpenTracing carrier format constant.

# Variables

NullLogger is implementation of the Logger interface that delegates to default `log` package.
ReporterOptions is a factory for all available ReporterOption's.
SamplerOptions is a factory for all available SamplerOption's.
StdLogger is implementation of the Logger interface that delegates to default `log` package.
TracerOptions is a factory for all available TracerOption's.

# Structs

ConstSampler is a sampler that always makes the same decision.
GuaranteedThroughputProbabilisticSampler is a sampler that leverages both probabilisticSampler and rateLimitingSampler.
InMemoryReporter is used for testing, and simply collects spans in memory.
Metrics is a container of all stats emitted by Jaeger tracer.
ProbabilisticSampler is a sampler that randomly samples a certain percentage of traces.
RemotelyControlledSampler is a delegating sampler that polls a remote server for the appropriate sampling strategy, constructs a corresponding sampler and delegates to it for sampling decisions.
SpanContext represents propagated span identity and state.
Tag a simple key value wrapper.
TraceID represents unique 128bit identifier of a trace.

# Interfaces

ExtractableZipkinSpan is a type of Carrier used for integration with Zipkin-aware RPC frameworks (like TChannel).
Extractor is responsible for extracting SpanContext instances from a format-specific "carrier" object.
InjectableZipkinSpan is a type of Carrier used for integration with Zipkin-aware RPC frameworks (like TChannel).
Injector is responsible for injecting SpanContext instances in a manner suitable for propagation via a format-specific "carrier" object.
Logger provides an abstract interface for logging from Reporters.
Reporter is called by the tracer when a span is completed to report the span to the tracing collector.
Sampler decides whether a new trace should be sampled or not.

# Type aliases

ReporterOption is a function that sets some option on the reporter.
SamplerOption is a function that sets some option on the sampler.
SpanID represents unique 64bit identifier of a span.
TracerOption is a function that sets some option on the tracer.