jaeger

package module
v2.18.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 16, 2019 License: Apache-2.0 Imports: 29 Imported by: 0

README

GoDoc Build Status Coverage Status OpenTracing 1.0 Enabled

Jaeger Bindings for Go OpenTracing API

Instrumentation library that implements an OpenTracing Go Tracer for Jaeger (https://jaegertracing.io).

IMPORTANT: The library's import path is based on its original location under github.com/uber. Do not try to import it as github.com/jaegertracing, it will not compile. We might revisit this in the next major release.

  • ✅ import "github.com/uber/jaeger-client-go"
  • ❌ import "github.com/jaegertracing/jaeger-client-go"

How to Contribute

Please see CONTRIBUTING.md.

Installation

We recommended using a dependency manager like dep and semantic versioning when including this library into an application. For example, Jaeger backend imports this library like this:

[[constraint]]
  name = "github.com/uber/jaeger-client-go"
  version = "2.17"

If you instead want to use the latest version in master, you can pull it via go get. Note that during go get you may see build errors due to incompatible dependencies, which is why we recommend using semantic versions for dependencies. The error may be fixed by running make install (it will install dep if you don't have it):

go get -u github.com/uber/jaeger-client-go/
cd $GOPATH/src/github.com/uber/jaeger-client-go/
git submodule update --init --recursive
make install

Initialization

See tracer initialization examples in godoc and config/example_test.go.

Environment variables

The tracer can be initialized with values coming from environment variables. None of the env vars are required and all of them can be overriden via direct setting of the property on the configuration object.

Property Description
JAEGER_SERVICE_NAME The service name
JAEGER_AGENT_HOST The hostname for communicating with agent via UDP
JAEGER_AGENT_PORT The port for communicating with agent via UDP
JAEGER_ENDPOINT The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces
JAEGER_USER Username to send as part of "Basic" authentication to the collector endpoint
JAEGER_PASSWORD Password to send as part of "Basic" authentication to the collector endpoint
JAEGER_REPORTER_LOG_SPANS Whether the reporter should also log the spans
JAEGER_REPORTER_MAX_QUEUE_SIZE The reporter's maximum queue size
JAEGER_REPORTER_FLUSH_INTERVAL The reporter's flush interval, with units, e.g. "500ms" or "2s" (valid units)
JAEGER_SAMPLER_TYPE The sampler type
JAEGER_SAMPLER_PARAM The sampler parameter (number)
JAEGER_SAMPLER_MANAGER_HOST_PORT The HTTP endpoint when using the remote sampler, i.e. http://jaeger-agent:5778/sampling
JAEGER_SAMPLER_MAX_OPERATIONS The maximum number of operations that the sampler will keep track of
JAEGER_SAMPLER_REFRESH_INTERVAL How often the remotely controlled sampler will poll jaeger-agent for the appropriate sampling strategy, with units, e.g. "1m" or "30s" (valid units)
JAEGER_TAGS A comma separated list of name = value tracer level tags, which get added to all reported spans. The value can also refer to an environment variable using the format ${envVarName:default}, where the :default is optional, and identifies a value to be used if the environment variable cannot be found
JAEGER_DISABLED Whether the tracer is disabled or not. If true, the default opentracing.NoopTracer is used.
JAEGER_RPC_METRICS Whether to store RPC metrics

By default, the client sends traces via UDP to the agent at localhost:6831. Use JAEGER_AGENT_HOST and JAEGER_AGENT_PORT to send UDP traces to a different host:port. If JAEGER_ENDPOINT is set, the client sends traces to the endpoint via HTTP, making the JAEGER_AGENT_HOST and JAEGER_AGENT_PORT unused. If JAEGER_ENDPOINT is secured, HTTP basic authentication can be performed by setting the JAEGER_USER and JAEGER_PASSWORD environment variables.

Closing the tracer via io.Closer

The constructor function for Jaeger Tracer returns the tracer itself and an io.Closer instance. It is recommended to structure your main() so that it calls the Close() function on the closer before exiting, e.g.

tracer, closer, err := cfg.NewTracer(...)
defer closer.Close()

This is especially useful for command-line tools that enable tracing, as well as for the long-running apps that support graceful shutdown. For example, if your deployment system sends SIGTERM instead of killing the process and you trap that signal to do a graceful exit, then having defer closer.Closer() ensures that all buffered spans are flushed.

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:jaeger.traces, state:started, sampled:y. See metrics.go file for the full list and descriptions of emitted metrics.

The monitoring backend is represented by the metrics.Factory interface from package "github.com/uber/jaeger-lib/metrics". An implementation of that interface can be passed as an option to either the Configuration object or the Tracer constructor, for example:

import (
    "github.com/uber/jaeger-client-go/config"
    "github.com/uber/jaeger-lib/metrics/prometheus"
)

    metricsFactory := prometheus.New()
    tracer, closer, err := config.Configuration{
        ServiceName: "your-service-name",
    }.NewTracer(
        config.Metrics(metricsFactory),
    )

By default, a no-op metrics.NullFactory 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.

Besides the zap implementation bundled with this package there is also a go-kit one in the jaeger-lib repository.

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 that 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 the supported transports include:

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:

if span := opentracing.SpanFromContext(ctx); span != nil {
    span.SetBaggageItem("key", "value")
}

Another service downstream of that can retrieve the baggage in a similar way:

if span := opentracing.SpanFromContext(ctx); span != nil {
    val := span.BaggageItem("key")
    println(val)
}
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.

SelfRef

Jaeger Tracer supports an additional reference type call Self. This allows a caller to provide an already established SpanContext. This allows loading and continuing spans/traces from offline (ie log-based) storage. The Self reference bypasses trace and span id generation.

Usage requires passing in a SpanContext and the jaeger Self reference type:

span := tracer.StartSpan(
    "continued_span",
    SelfRef(yourSpanContext),
)
...
defer span.finish()

License

Apache 2.0 License.

Documentation

Overview

Package jaeger implements an OpenTracing (http://opentracing.io) Tracer. It is currently using Zipkin-compatible data model and can be directly itegrated with Zipkin backend (http://zipkin.io).

For integration instructions please refer to the README:

https://github.com/uber/jaeger-client-go/blob/master/README.md

Index

Constants

View Source 
const (
	// JaegerClientVersion is the version of the client library reported as Span tag.
	JaegerClientVersion = "Go-2.18.1"

	// JaegerClientVersionTagKey is the name of the tag used to report client version.
	JaegerClientVersionTagKey = "jaeger.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.
	// The value of the header is recorded as the tag on the root span, so that the
	// trace can be found in the UI using this value as a correlation ID.
	JaegerDebugHeader = "jaeger-debug-id"

	// JaegerBaggageHeader is the name of the HTTP header that is used to submit baggage.
	// It differs from TraceBaggageHeaderPrefix in that it can be used only in cases where
	// a root span does not exist.
	JaegerBaggageHeader = "jaeger-baggage"

	// TracerHostnameTagKey used to report host name of the process.
	TracerHostnameTagKey = "hostname"

	// TracerIPTagKey used to report ip of the process.
	TracerIPTagKey = "ip"

	// TracerUUIDTagKey used to report UUID of the client process.
	TracerUUIDTagKey = "client-uuid"

	// SamplerTypeTagKey reports which sampler was used on the root span.
	SamplerTypeTagKey = "sampler.type"

	// SamplerParamTagKey reports the parameter of the sampler, like sampling probability.
	SamplerParamTagKey = "sampler.param"

	// TraceContextHeaderName is the http header name used to propagate tracing context.
	// This must be in lower-case to avoid mismatches when decoding incoming headers.
	TraceContextHeaderName = "uber-trace-id"

	// TracerStateHeaderName is deprecated.
	// Deprecated: use TraceContextHeaderName
	TracerStateHeaderName = TraceContextHeaderName

	// TraceBaggageHeaderPrefix is the prefix for http headers used to propagate baggage.
	// This must be in lower-case to avoid mismatches when decoding incoming headers.
	TraceBaggageHeaderPrefix = "uberctx-"

	// SamplerTypeConst is the type of sampler that always makes the same decision.
	SamplerTypeConst = "const"

	// SamplerTypeRemote is the type of sampler that polls Jaeger agent for sampling strategy.
	SamplerTypeRemote = "remote"

	// SamplerTypeProbabilistic is the type of sampler that samples traces
	// with a certain fixed probability.
	SamplerTypeProbabilistic = "probabilistic"

	// SamplerTypeRateLimiting is the type of sampler that samples
	// only up to a fixed number of traces per second.
	SamplerTypeRateLimiting = "ratelimiting"

	// SamplerTypeLowerBound is the type of sampler that samples
	// at least a fixed number of traces per second.
	SamplerTypeLowerBound = "lowerbound"

	// DefaultUDPSpanServerHost is the default host to send the spans to, via UDP
	DefaultUDPSpanServerHost = "localhost"

	// DefaultUDPSpanServerPort is the default port to send the spans to, via UDP
	DefaultUDPSpanServerPort = 6831

	// DefaultSamplingServerPort is the default port to fetch sampling config from, via http
	DefaultSamplingServerPort = 5778

	// DefaultMaxTagValueLength is the default max length of byte array or string allowed in the tag value.
	DefaultMaxTagValueLength = 256
)
View Source 
const SpanContextFormat formatKey = iota

SpanContextFormat is a constant used as OpenTracing Format. Requires *SpanContext as carrier. This format is intended for interop with TChannel or other Zipkin-like tracers.

View Source 
const ZipkinSpanFormat = "zipkin-span-format"

ZipkinSpanFormat is an OpenTracing carrier format constant

Variables

View Source 
var (
	// DefaultSamplingServerURL is the default url to fetch sampling config from, via http
	DefaultSamplingServerURL = fmt.Sprintf("http://localhost:%d/sampling", DefaultSamplingServerPort)
)
View Source 
var NullLogger = &nullLogger{}

NullLogger is implementation of the Logger interface that delegates to default `log` package

View Source 
var ReporterOptions reporterOptions

ReporterOptions is a factory for all available ReporterOption's

View Source 
var SamplerOptions samplerOptions

SamplerOptions is a factory for all available SamplerOption's

View Source 
var StdLogger = &stdLogger{}

StdLogger is implementation of the Logger interface that delegates to default `log` package

View Source 
var TracerOptions tracerOptions

TracerOptions is a factory for all available TracerOption's

Functions

func BuildJaegerProcessThrift added in v2.7.0 

func BuildJaegerProcessThrift(span *Span) *j.Process

BuildJaegerProcessThrift creates a thrift Process type.

func BuildJaegerThrift added in v2.7.0 

func BuildJaegerThrift(span *Span) *j.Span

BuildJaegerThrift builds jaeger span based on internal span.

func BuildZipkinThrift added in v2.7.0 

func BuildZipkinThrift(s *Span) *z.Span

BuildZipkinThrift builds thrift span based on internal span.

func ConvertLogsToJaegerTags added in v2.7.0 

func ConvertLogsToJaegerTags(logFields []log.Field) []*j.Tag

ConvertLogsToJaegerTags converts log Fields into jaeger tags.

func EnableFirehose added in v2.17.0 

func EnableFirehose(s *Span)

EnableFirehose enables firehose flag on the span context

func NewTracer 

func NewTracer(
	serviceName string,
	sampler Sampler,
	reporter Reporter,
	options ...TracerOption,
) (opentracing.Tracer, io.Closer)

NewTracer creates Tracer implementation that reports tracing to Jaeger. The returned io.Closer can be used in shutdown hooks to ensure that the internal queue of the Reporter is drained and all buffered spans are submitted to collectors.

func SelfRef added in v2.17.0 

func SelfRef(ctx SpanContext) opentracing.SpanReference

SelfRef creates an opentracing compliant SpanReference from a jaeger SpanContext. This is a factory function in order to encapsulate jaeger specific types.

Types

type BinaryPropagator added in v2.16.0 

type BinaryPropagator struct {
	// contains filtered or unexported fields
}

BinaryPropagator is a combined Injector and Extractor for Binary format

func NewBinaryPropagator added in v2.16.0 

func NewBinaryPropagator(tracer *Tracer) *BinaryPropagator

NewBinaryPropagator creates a combined Injector and Extractor for Binary format

func (*BinaryPropagator) Extract added in v2.16.0 

func (p *BinaryPropagator) Extract(abstractCarrier interface{}) (SpanContext, error)

Extract implements Extractor of BinaryPropagator

func (*BinaryPropagator) Inject added in v2.16.0 

func (p *BinaryPropagator) Inject(
	sc SpanContext,
	abstractCarrier interface{},
) error

Inject implements Injector of BinaryPropagator

type ConstSampler 

type ConstSampler struct {
	Decision bool
	// contains filtered or unexported fields
}

ConstSampler is a sampler that always makes the same decision.

func (*ConstSampler) Close 

func (s *ConstSampler) Close()

Close implements Close() of Sampler.

func (*ConstSampler) Equal 

func (s *ConstSampler) Equal(other Sampler) bool

Equal implements Equal() of Sampler.

func (*ConstSampler) IsSampled 

func (s *ConstSampler) IsSampled(id TraceID, operation string) (bool, []Tag)

IsSampled implements IsSampled() of Sampler.

type ContribObserver added in v2.9.0 

type ContribObserver interface {
	// Create and return a span observer. Called when a span starts.
	// If the Observer is not interested in the given span, it must return (nil, false).
	// E.g :
	//     func StartSpan(opName string, opts ...opentracing.StartSpanOption) {
	//         var sp opentracing.Span
	//         sso := opentracing.StartSpanOptions{}
	//         if spanObserver, ok := Observer.OnStartSpan(span, opName, sso); ok {
	//             // we have a valid SpanObserver
	//         }
	//         ...
	//     }
	OnStartSpan(sp opentracing.Span, operationName string, options opentracing.StartSpanOptions) (ContribSpanObserver, bool)
}

ContribObserver can be registered with the Tracer to receive notifications about new Spans. Modelled after github.com/opentracing-contrib/go-observer.

type ContribSpanObserver added in v2.9.0 

type ContribSpanObserver interface {
	OnSetOperationName(operationName string)
	OnSetTag(key string, value interface{})
	OnFinish(options opentracing.FinishOptions)
}

ContribSpanObserver is created by the Observer and receives notifications about other Span events. This interface is meant to match github.com/opentracing-contrib/go-observer, via duck typing, without directly importing the go-observer package.

type ExtractableZipkinSpan 

type ExtractableZipkinSpan interface {
	TraceID() uint64
	SpanID() uint64
	ParentID() uint64
	Flags() byte
}

ExtractableZipkinSpan is a type of Carrier used for integration with Zipkin-aware RPC frameworks (like TChannel). It does not support baggage, only trace IDs.

type Extractor 

type Extractor interface {
	// Extract decodes a SpanContext instance from the given `carrier`,
	// or (nil, opentracing.ErrSpanContextNotFound) if no context could
	// be found in the `carrier`.
	Extract(carrier interface{}) (SpanContext, error)
}

Extractor is responsible for extracting SpanContext instances from a format-specific "carrier" object. Typically the extraction will take place on the server side of an RPC boundary, but message queues and other IPC mechanisms are also reasonable places to use an Extractor.

type GuaranteedThroughputProbabilisticSampler 

type GuaranteedThroughputProbabilisticSampler struct {
	// contains filtered or unexported fields
}

GuaranteedThroughputProbabilisticSampler is a sampler that leverages both probabilisticSampler and rateLimitingSampler. The rateLimitingSampler is used as a guaranteed lower bound sampler such that every operation is sampled at least once in a time interval defined by the lowerBound. ie a lowerBound of 1.0 / (60 * 10) will sample an operation at least once every 10 minutes.

The probabilisticSampler is given higher priority when tags are emitted, ie. if IsSampled() for both samplers return true, the tags for probabilisticSampler will be used.

func NewGuaranteedThroughputProbabilisticSampler 

func NewGuaranteedThroughputProbabilisticSampler(
	lowerBound, samplingRate float64,
) (*GuaranteedThroughputProbabilisticSampler, error)

NewGuaranteedThroughputProbabilisticSampler returns a delegating sampler that applies both probabilisticSampler and rateLimitingSampler.

func (*GuaranteedThroughputProbabilisticSampler) Close 

func (s *GuaranteedThroughputProbabilisticSampler) Close()

Close implements Close() of Sampler.

func (*GuaranteedThroughputProbabilisticSampler) Equal 

func (s *GuaranteedThroughputProbabilisticSampler) Equal(other Sampler) bool

Equal implements Equal() of Sampler.

func (*GuaranteedThroughputProbabilisticSampler) IsSampled 

func (s *GuaranteedThroughputProbabilisticSampler) IsSampled(id TraceID, operation string) (bool, []Tag)

IsSampled implements IsSampled() of Sampler.

type HeadersConfig added in v2.10.0 

type HeadersConfig struct {
	// 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.
	// The value of the header is recorded as the tag on the root span, so that the
	// trace can be found in the UI using this value as a correlation ID.
	JaegerDebugHeader string `yaml:"jaegerDebugHeader"`

	// JaegerBaggageHeader is the name of the HTTP header that is used to submit baggage.
	// It differs from TraceBaggageHeaderPrefix in that it can be used only in cases where
	// a root span does not exist.
	JaegerBaggageHeader string `yaml:"jaegerBaggageHeader"`

	// TraceContextHeaderName is the http header name used to propagate tracing context.
	// This must be in lower-case to avoid mismatches when decoding incoming headers.
	TraceContextHeaderName string `yaml:"TraceContextHeaderName"`

	// TraceBaggageHeaderPrefix is the prefix for http headers used to propagate baggage.
	// This must be in lower-case to avoid mismatches when decoding incoming headers.
	TraceBaggageHeaderPrefix string `yaml:"traceBaggageHeaderPrefix"`
}

HeadersConfig contains the values for the header keys that Jaeger will use. These values may be either custom or default depending on whether custom values were provided via a configuration.

func (*HeadersConfig) ApplyDefaults added in v2.16.0 

func (c *HeadersConfig) ApplyDefaults() *HeadersConfig

ApplyDefaults sets missing configuration keys to default values

type InMemoryReporter 

type InMemoryReporter struct {
	// contains filtered or unexported fields
}

InMemoryReporter is used for testing, and simply collects spans in memory.

func NewInMemoryReporter 

func NewInMemoryReporter() *InMemoryReporter

NewInMemoryReporter creates a reporter that stores spans in memory. NOTE: the Tracer should be created with options.PoolSpans = false.

func (*InMemoryReporter) Close 

func (r *InMemoryReporter) Close()

Close implements Close() method of Reporter

func (*InMemoryReporter) GetSpans 

func (r *InMemoryReporter) GetSpans() []opentracing.Span

GetSpans returns accumulated spans as a copy of the buffer.

func (*InMemoryReporter) Report 

func (r *InMemoryReporter) Report(span *Span)

Report implements Report() method of Reporter by storing the span in the buffer.

func (*InMemoryReporter) Reset 

func (r *InMemoryReporter) Reset()

Reset clears all accumulated spans.

func (*InMemoryReporter) SpansSubmitted 

func (r *InMemoryReporter) SpansSubmitted() int

SpansSubmitted returns the number of spans accumulated in the buffer.

type InjectableZipkinSpan 

type InjectableZipkinSpan interface {
	SetTraceID(traceID uint64)
	SetSpanID(spanID uint64)
	SetParentID(parentID uint64)
	SetFlags(flags byte)
}

InjectableZipkinSpan is a type of Carrier used for integration with Zipkin-aware RPC frameworks (like TChannel). It does not support baggage, only trace IDs.

type Injector 

type Injector interface {
	// Inject takes `SpanContext` and injects it into `carrier`. The actual type
	// of `carrier` depends on the `format` passed to `Tracer.Inject()`.
	//
	// Implementations may return opentracing.ErrInvalidCarrier or any other
	// implementation-specific error if injection fails.
	Inject(ctx SpanContext, carrier interface{}) error
}

Injector is responsible for injecting SpanContext instances in a manner suitable for propagation via a format-specific "carrier" object. Typically the injection will take place across an RPC boundary, but message queues and other IPC mechanisms are also reasonable places to use an Injector.

type Logger 

type Logger interface {
	// Error logs a message at error priority
	Error(msg string)

	// Infof logs a message at info priority
	Infof(msg string, args ...interface{})
}

Logger provides an abstract interface for logging from Reporters. Applications can provide their own implementation of this interface to adapt reporters logging to whatever logging library they prefer (stdlib log, logrus, go-logging, etc).

type Metrics 

type Metrics struct {
	// Number of traces started by this tracer as sampled
	TracesStartedSampled metrics.Counter `metric:"traces" tags:"state=started,sampled=y" help:"Number of traces started by this tracer as sampled"`

	// Number of traces started by this tracer as not sampled
	TracesStartedNotSampled metrics.Counter `metric:"traces" tags:"state=started,sampled=n" help:"Number of traces started by this tracer as not sampled"`

	// Number of externally started sampled traces this tracer joined
	TracesJoinedSampled metrics.Counter `metric:"traces" tags:"state=joined,sampled=y" help:"Number of externally started sampled traces this tracer joined"`

	// Number of externally started not-sampled traces this tracer joined
	TracesJoinedNotSampled metrics.Counter `metric:"traces" tags:"state=joined,sampled=n" help:"Number of externally started not-sampled traces this tracer joined"`

	// Number of sampled spans started by this tracer
	SpansStartedSampled metrics.Counter `metric:"started_spans" tags:"sampled=y" help:"Number of sampled spans started by this tracer"`

	// Number of unsampled spans started by this tracer
	SpansStartedNotSampled metrics.Counter `metric:"started_spans" tags:"sampled=n" help:"Number of unsampled spans started by this tracer"`

	// Number of spans finished by this tracer
	SpansFinished metrics.Counter `metric:"finished_spans" help:"Number of spans finished by this tracer"`

	// Number of errors decoding tracing context
	DecodingErrors metrics.Counter `metric:"span_context_decoding_errors" help:"Number of errors decoding tracing context"`

	// Number of spans successfully reported
	ReporterSuccess metrics.Counter `metric:"reporter_spans" tags:"result=ok" help:"Number of spans successfully reported"`

	// Number of spans not reported due to a Sender failure
	ReporterFailure metrics.Counter `metric:"reporter_spans" tags:"result=err" help:"Number of spans not reported due to a Sender failure"`

	// Number of spans dropped due to internal queue overflow
	ReporterDropped metrics.Counter `metric:"reporter_spans" tags:"result=dropped" help:"Number of spans dropped due to internal queue overflow"`

	// Current number of spans in the reporter queue
	ReporterQueueLength metrics.Gauge `metric:"reporter_queue_length" help:"Current number of spans in the reporter queue"`

	// Number of times the Sampler succeeded to retrieve sampling strategy
	SamplerRetrieved metrics.Counter `metric:"sampler_queries" tags:"result=ok" help:"Number of times the Sampler succeeded to retrieve sampling strategy"`

	// Number of times the Sampler failed to retrieve sampling strategy
	SamplerQueryFailure metrics.Counter `metric:"sampler_queries" tags:"result=err" help:"Number of times the Sampler failed to retrieve sampling strategy"`

	// Number of times the Sampler succeeded to retrieve and update sampling strategy
	SamplerUpdated metrics.Counter `` /* 127-byte string literal not displayed */

	// Number of times the Sampler failed to update sampling strategy
	SamplerUpdateFailure metrics.Counter `metric:"sampler_updates" tags:"result=err" help:"Number of times the Sampler failed to update sampling strategy"`

	// Number of times baggage was successfully written or updated on spans.
	BaggageUpdateSuccess metrics.Counter `metric:"baggage_updates" tags:"result=ok" help:"Number of times baggage was successfully written or updated on spans"`

	// Number of times baggage failed to write or update on spans.
	BaggageUpdateFailure metrics.Counter `metric:"baggage_updates" tags:"result=err" help:"Number of times baggage failed to write or update on spans"`

	// Number of times baggage was truncated as per baggage restrictions.
	BaggageTruncate metrics.Counter `metric:"baggage_truncations" help:"Number of times baggage was truncated as per baggage restrictions"`

	// Number of times baggage restrictions were successfully updated.
	BaggageRestrictionsUpdateSuccess metrics.Counter `metric:"baggage_restrictions_updates" tags:"result=ok" help:"Number of times baggage restrictions were successfully updated"`

	// Number of times baggage restrictions failed to update.
	BaggageRestrictionsUpdateFailure metrics.Counter `metric:"baggage_restrictions_updates" tags:"result=err" help:"Number of times baggage restrictions failed to update"`

	// Number of times debug spans were throttled.
	ThrottledDebugSpans metrics.Counter `metric:"throttled_debug_spans" help:"Number of times debug spans were throttled"`

	// Number of times throttler successfully updated.
	ThrottlerUpdateSuccess metrics.Counter `metric:"throttler_updates" tags:"result=ok" help:"Number of times throttler successfully updated"`

	// Number of times throttler failed to update.
	ThrottlerUpdateFailure metrics.Counter `metric:"throttler_updates" tags:"result=err" help:"Number of times throttler failed to update"`
}

Metrics is a container of all stats emitted by Jaeger tracer.

func NewMetrics 

func NewMetrics(factory metrics.Factory, globalTags map[string]string) *Metrics

NewMetrics creates a new Metrics struct and initializes it.

func NewNullMetrics 

func NewNullMetrics() *Metrics

NewNullMetrics creates a new Metrics struct that won't report any metrics.

type Observer deprecated added in v2.2.0 

type Observer interface {
	OnStartSpan(operationName string, options opentracing.StartSpanOptions) SpanObserver
}

Observer can be registered with the Tracer to receive notifications about new Spans.

Deprecated: use jaeger.ContribObserver instead.

type ProbabilisticSampler 

type ProbabilisticSampler struct {
	// contains filtered or unexported fields
}

ProbabilisticSampler is a sampler that randomly samples a certain percentage of traces.

func NewProbabilisticSampler 

func NewProbabilisticSampler(samplingRate float64) (*ProbabilisticSampler, error)

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.

It relies on the fact that new trace IDs are 63bit random numbers themselves, thus making the sampling decision without generating a new random number, but simply calculating if traceID < (samplingRate * 2^63). TODO remove the error from this function for next major release

func (*ProbabilisticSampler) Close 

func (s *ProbabilisticSampler) Close()

Close implements Close() of Sampler.

func (*ProbabilisticSampler) Equal 

func (s *ProbabilisticSampler) Equal(other Sampler) bool

Equal implements Equal() of Sampler.

func (*ProbabilisticSampler) IsSampled 

func (s *ProbabilisticSampler) IsSampled(id TraceID, operation string) (bool, []Tag)

IsSampled implements IsSampled() of Sampler.

func (*ProbabilisticSampler) SamplingRate 

func (s *ProbabilisticSampler) SamplingRate() float64

SamplingRate returns the sampling probability this sampled was constructed with.

type Process added in v2.12.0 

type Process struct {
	Service string
	UUID    string
	Tags    []Tag
}

Process holds process specific metadata that's relevant to this client.

type ProcessSetter added in v2.12.0 

type ProcessSetter interface {
	SetProcess(process Process)
}

ProcessSetter sets a process. This can be used by any class that requires the process to be set as part of initialization. See internal/throttler/remote/throttler.go for an example.

type Reference added in v2.7.0 

type Reference struct {
	Type    opentracing.SpanReferenceType
	Context SpanContext
}

Reference represents a causal reference to other Spans (via their SpanContext).

type RemotelyControlledSampler 

type RemotelyControlledSampler struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

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.

func NewRemotelyControlledSampler 

func NewRemotelyControlledSampler(
	serviceName string,
	opts ...SamplerOption,
) *RemotelyControlledSampler

NewRemotelyControlledSampler creates a sampler that periodically pulls the sampling strategy from an HTTP sampling server (e.g. jaeger-agent).

func (*RemotelyControlledSampler) Close 

func (s *RemotelyControlledSampler) Close()

Close implements Close() of Sampler.

func (*RemotelyControlledSampler) Equal 

func (s *RemotelyControlledSampler) Equal(other Sampler) bool

Equal implements Equal() of Sampler.

func (RemotelyControlledSampler) InitialSampler 

func (RemotelyControlledSampler) InitialSampler(sampler Sampler) SamplerOption

InitialSampler creates a SamplerOption that sets the initial sampler to use before a remote sampler is created and used.

func (*RemotelyControlledSampler) IsSampled 

func (s *RemotelyControlledSampler) IsSampled(id TraceID, operation string) (bool, []Tag)

IsSampled implements IsSampled() of Sampler.

func (RemotelyControlledSampler) Logger 

func (RemotelyControlledSampler) Logger(logger Logger) SamplerOption

Logger creates a SamplerOption that sets the logger used by the sampler.

func (RemotelyControlledSampler) MaxOperations 

func (RemotelyControlledSampler) MaxOperations(maxOperations int) SamplerOption

MaxOperations creates a SamplerOption that sets the maximum number of operations the sampler will keep track of.

func (RemotelyControlledSampler) Metrics 

func (RemotelyControlledSampler) Metrics(m *Metrics) SamplerOption

Metrics creates a SamplerOption that initializes Metrics on the sampler, which is used to emit statistics.

func (RemotelyControlledSampler) SamplingRefreshInterval 

func (RemotelyControlledSampler) SamplingRefreshInterval(samplingRefreshInterval time.Duration) SamplerOption

SamplingRefreshInterval creates a SamplerOption that sets how often the sampler will poll local agent for the appropriate sampling strategy.

func (RemotelyControlledSampler) SamplingServerURL 

func (RemotelyControlledSampler) SamplingServerURL(samplingServerURL string) SamplerOption

SamplingServerURL creates a SamplerOption that sets the sampling server url of the local agent that contains the sampling strategies.

type Reporter 

type Reporter interface {
	// Report submits a new span to collectors, possibly asynchronously and/or with buffering.
	Report(span *Span)

	// Close does a clean shutdown of the reporter, flushing any traces that may be buffered in memory.
	Close()
}

Reporter is called by the tracer when a span is completed to report the span to the tracing collector.

func NewCompositeReporter 

func NewCompositeReporter(reporters ...Reporter) Reporter

NewCompositeReporter creates a reporter that ignores all reported spans.

func NewLoggingReporter 

func NewLoggingReporter(logger Logger) Reporter

NewLoggingReporter creates a reporter that logs all reported spans to provided logger.

func NewNullReporter 

func NewNullReporter() Reporter

NewNullReporter creates a no-op reporter that ignores all reported spans.

func NewRemoteReporter 

func NewRemoteReporter(sender Transport, opts ...ReporterOption) Reporter

NewRemoteReporter creates a new reporter that sends spans out of process by means of Sender. Calls to Report(Span) return immediately (side effect: if internal buffer is full the span is dropped). Periodically the transport buffer is flushed even if it hasn't reached max packet size. Calls to Close() block until all spans reported prior to the call to Close are flushed.

type ReporterOption 

type ReporterOption func(c *reporterOptions)

ReporterOption is a function that sets some option on the reporter.

type Sampler 

type Sampler interface {
	// IsSampled decides whether a trace with given `id` and `operation`
	// should be sampled. This function will also return the tags that
	// can be used to identify the type of sampling that was applied to
	// the root span. Most simple samplers would return two tags,
	// sampler.type and sampler.param, similar to those used in the Configuration
	IsSampled(id TraceID, operation string) (sampled bool, tags []Tag)

	// Close does a clean shutdown of the sampler, stopping any background
	// go-routines it may have started.
	Close()

	// Equal checks if the `other` sampler is functionally equivalent
	// to this sampler.
	// TODO remove this function. This function is used to determine if 2 samplers are equivalent
	// which does not bode well with the adaptive sampler which has to create all the composite samplers
	// for the comparison to occur. This is expensive to do if only one sampler has changed.
	Equal(other Sampler) bool
}

Sampler decides whether a new trace should be sampled or not.

func NewAdaptiveSampler 

func NewAdaptiveSampler(strategies *sampling.PerOperationSamplingStrategies, maxOperations int) (Sampler, error)

NewAdaptiveSampler returns a delegating sampler that applies both probabilisticSampler and rateLimitingSampler via the guaranteedThroughputProbabilisticSampler. This sampler keeps track of all operations and delegates calls to the respective guaranteedThroughputProbabilisticSampler.

func NewConstSampler 

func NewConstSampler(sample bool) Sampler

NewConstSampler creates a ConstSampler.

func NewRateLimitingSampler 

func NewRateLimitingSampler(maxTracesPerSecond float64) Sampler

NewRateLimitingSampler creates a sampler that samples at most maxTracesPerSecond. The distribution of sampled traces follows burstiness of the service, i.e. a service with uniformly distributed requests will have those requests sampled uniformly as well, but if requests are bursty, especially sub-second, then a number of sequential requests can be sampled each second.

type SamplerOption 

type SamplerOption func(options *samplerOptions)

SamplerOption is a function that sets some option on the sampler

type Span added in v2.3.0 

type Span struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Span implements opentracing.Span

func (*Span) BaggageItem added in v2.3.0 

func (s *Span) BaggageItem(key string) string

BaggageItem implements BaggageItem() of opentracing.SpanContext

func (*Span) Context added in v2.3.0 

func (s *Span) Context() opentracing.SpanContext

Context implements opentracing.Span API

func (*Span) Duration added in v2.17.0 

func (s *Span) Duration() time.Duration

Duration returns span duration

func (*Span) Finish added in v2.3.0 

func (s *Span) Finish()

Finish implements opentracing.Span API After finishing the Span object it returns back to the allocator unless the reporter retains it again, so after that, the Span object should no longer be used because it won't be valid anymore.

func (*Span) FinishWithOptions added in v2.3.0 

func (s *Span) FinishWithOptions(options opentracing.FinishOptions)

FinishWithOptions implements opentracing.Span API

func (*Span) Log added in v2.3.0 

func (s *Span) Log(ld opentracing.LogData)

Log implements opentracing.Span API

func (*Span) LogEvent added in v2.3.0 

func (s *Span) LogEvent(event string)

LogEvent implements opentracing.Span API

func (*Span) LogEventWithPayload added in v2.3.0 

func (s *Span) LogEventWithPayload(event string, payload interface{})

LogEventWithPayload implements opentracing.Span API

func (*Span) LogFields added in v2.3.0 

func (s *Span) LogFields(fields ...log.Field)

LogFields implements opentracing.Span API

func (*Span) LogKV added in v2.3.0 

func (s *Span) LogKV(alternatingKeyValues ...interface{})

LogKV implements opentracing.Span API

func (*Span) OperationName added in v2.3.0 

func (s *Span) OperationName() string

OperationName allows retrieving current operation name.

func (*Span) Release added in v2.17.0 

func (s *Span) Release()

Release decrements object counter and return to the allocator manager when counter will below zero

func (*Span) Retain added in v2.17.0 

func (s *Span) Retain() *Span

Retain increases object counter to increase the lifetime of the object

func (*Span) SetBaggageItem added in v2.3.0 

func (s *Span) SetBaggageItem(key, value string) opentracing.Span

SetBaggageItem implements SetBaggageItem() of opentracing.SpanContext

func (*Span) SetOperationName added in v2.3.0 

func (s *Span) SetOperationName(operationName string) opentracing.Span

SetOperationName sets or changes the operation name.

func (*Span) SetTag added in v2.3.0 

func (s *Span) SetTag(key string, value interface{}) opentracing.Span

SetTag implements SetTag() of opentracing.Span

func (*Span) SpanContext added in v2.17.0 

func (s *Span) SpanContext() SpanContext

SpanContext returns span context

func (*Span) StartTime added in v2.17.0 

func (s *Span) StartTime() time.Time

StartTime returns span start time

func (*Span) String added in v2.3.0 

func (s *Span) String() string

func (*Span) Tags added in v2.17.0 

func (s *Span) Tags() opentracing.Tags

Tags returns tags for span

func (*Span) Tracer added in v2.3.0 

func (s *Span) Tracer() opentracing.Tracer

Tracer implements opentracing.Span API

type SpanAllocator added in v2.17.0 

type SpanAllocator interface {
	Get() *Span
	Put(*Span)
}

SpanAllocator abstraction of managign span allocations

type SpanContext 

type SpanContext struct {
	// contains filtered or unexported fields
}

SpanContext represents propagated span identity and state

func ContextFromString 

func ContextFromString(value string) (SpanContext, error)

ContextFromString reconstructs the Context encoded in a string

func NewSpanContext 

func NewSpanContext(traceID TraceID, spanID, parentID SpanID, sampled bool, baggage map[string]string) SpanContext

NewSpanContext creates a new instance of SpanContext

func (*SpanContext) CopyFrom 

func (c *SpanContext) CopyFrom(ctx *SpanContext)

CopyFrom copies data from ctx into this context, including span identity and baggage. TODO This is only used by interop.go. Remove once TChannel Go supports OpenTracing.

func (SpanContext) ForeachBaggageItem 

func (c SpanContext) ForeachBaggageItem(handler func(k, v string) bool)

ForeachBaggageItem implements ForeachBaggageItem() of opentracing.SpanContext

func (SpanContext) IsDebug 

func (c SpanContext) IsDebug() bool

IsDebug indicates whether sampling was explicitly requested by the service.

func (SpanContext) IsFirehose added in v2.17.0 

func (c SpanContext) IsFirehose() bool

IsFirehose indicates whether the firehose flag was set

func (SpanContext) IsSampled 

func (c SpanContext) IsSampled() bool

IsSampled returns whether this trace was chosen for permanent storage by the sampling mechanism of the tracer.

func (SpanContext) IsValid 

func (c SpanContext) IsValid() bool

IsValid indicates whether this context actually represents a valid trace.

func (SpanContext) ParentID 

func (c SpanContext) ParentID() SpanID

ParentID returns the parent span ID of this span context

func (SpanContext) SpanID 

func (c SpanContext) SpanID() SpanID

SpanID returns the span ID of this span context

func (SpanContext) String 

func (c SpanContext) String() string

func (SpanContext) TraceID 

func (c SpanContext) TraceID() TraceID

TraceID returns the trace ID of this span context

func (SpanContext) WithBaggageItem 

func (c SpanContext) WithBaggageItem(key, value string) SpanContext

WithBaggageItem creates a new context with an extra baggage item.

type SpanID 

type SpanID uint64

SpanID represents unique 64bit identifier of a span

func SpanIDFromString 

func SpanIDFromString(s string) (SpanID, error)

SpanIDFromString creates a SpanID from a hexadecimal string

func (SpanID) String 

func (s SpanID) String() string

type SpanObserver deprecated added in v2.2.0 

type SpanObserver interface {
	OnSetOperationName(operationName string)
	OnSetTag(key string, value interface{})
	OnFinish(options opentracing.FinishOptions)
}

SpanObserver is created by the Observer and receives notifications about other Span events.

Deprecated: use jaeger.ContribSpanObserver instead.

type Tag 

type Tag struct {
	// contains filtered or unexported fields
}

Tag is a simple key value wrapper. TODO deprecate in the next major release, use opentracing.Tag instead.

type TextMapPropagator added in v2.16.0 

type TextMapPropagator struct {
	// contains filtered or unexported fields
}

TextMapPropagator is a combined Injector and Extractor for TextMap format

func NewHTTPHeaderPropagator added in v2.16.0 

func NewHTTPHeaderPropagator(headerKeys *HeadersConfig, metrics Metrics) *TextMapPropagator

NewHTTPHeaderPropagator creates a combined Injector and Extractor for HTTPHeaders format

func NewTextMapPropagator added in v2.16.0 

func NewTextMapPropagator(headerKeys *HeadersConfig, metrics Metrics) *TextMapPropagator

NewTextMapPropagator creates a combined Injector and Extractor for TextMap format

func (*TextMapPropagator) Extract added in v2.16.0 

func (p *TextMapPropagator) Extract(abstractCarrier interface{}) (SpanContext, error)

Extract implements Extractor of TextMapPropagator

func (*TextMapPropagator) Inject added in v2.16.0 

func (p *TextMapPropagator) Inject(
	sc SpanContext,
	abstractCarrier interface{},
) error

Inject implements Injector of TextMapPropagator

type TraceID 

type TraceID struct {
	High, Low uint64
}

TraceID represents unique 128bit identifier of a trace

func TraceIDFromString 

func TraceIDFromString(s string) (TraceID, error)

TraceIDFromString creates a TraceID from a hexadecimal string

func (TraceID) IsValid 

func (t TraceID) IsValid() bool

IsValid checks if the trace ID is valid, i.e. not zero.

func (TraceID) String 

func (t TraceID) String() string

type Tracer added in v2.8.0 

type Tracer struct {
	// contains filtered or unexported fields
}

Tracer implements opentracing.Tracer.

func (*Tracer) Close added in v2.8.0 

func (t *Tracer) Close() error

Close releases all resources used by the Tracer and flushes any remaining buffered spans.

func (*Tracer) Extract added in v2.8.0 

func (t *Tracer) Extract(
	format interface{},
	carrier interface{},
) (opentracing.SpanContext, error)

Extract implements Extract() method of opentracing.Tracer

func (*Tracer) Inject added in v2.8.0 

func (t *Tracer) Inject(ctx opentracing.SpanContext, format interface{}, carrier interface{}) error

Inject implements Inject() method of opentracing.Tracer

func (*Tracer) StartSpan added in v2.8.0 

func (t *Tracer) StartSpan(
	operationName string,
	options ...opentracing.StartSpanOption,
) opentracing.Span

StartSpan implements StartSpan() method of opentracing.Tracer.

func (*Tracer) Tags added in v2.8.0 

func (t *Tracer) Tags() []opentracing.Tag

Tags returns a slice of tracer-level tags.

type TracerOption 

type TracerOption func(tracer *Tracer)

TracerOption is a function that sets some option on the tracer

type Transport added in v2.7.0 

type Transport interface {
	// Append converts the span to the wire representation and adds it
	// to sender's internal buffer.  If the buffer exceeds its designated
	// size, the transport should call Flush() and return the number of spans
	// flushed, otherwise return 0. If error is returned, the returned number
	// of spans is treated as failed span, and reported to metrics accordingly.
	Append(span *Span) (int, error)

	// Flush submits the internal buffer to the remote server. It returns the
	// number of spans flushed. If error is returned, the returned number of
	// spans is treated as failed span, and reported to metrics accordingly.
	Flush() (int, error)

	io.Closer
}

Transport abstracts the method of sending spans out of process. Implementations are NOT required to be thread-safe; the RemoteReporter is expected to only call methods on the Transport from the same go-routine.

func NewUDPTransport added in v2.7.0 

func NewUDPTransport(hostPort string, maxPacketSize int) (Transport, error)

NewUDPTransport creates a reporter that submits spans to jaeger-agent

Source Files

View all Source files

Directories

Path Synopsis
client
common
endtoend
log
server
thrift/tracetest
internal
baggage
baggage/remote
spanlog
throttler
throttler/remote
log
zap
Package rpcmetrics implements an Observer that can be used to emit RPC metrics.
 Package rpcmetrics implements an Observer that can be used to emit RPC metrics.
thrift-gen
agent
baggage
jaeger
sampling
zipkincore
Package transport defines various transports that can be used with RemoteReporter to send spans out of process.
 Package transport defines various transports that can be used with RemoteReporter to send spans out of process.
zipkin
Package zipkin provides various Transports that can be used with RemoteReporter for submitting traces to Zipkin backend.
 Package zipkin provides various Transports that can be used with RemoteReporter for submitting traces to Zipkin backend.
Package zipkin comprises Zipkin functionality for Zipkin compatibility.
 Package zipkin comprises Zipkin functionality for Zipkin compatibility.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.