jaeger

package module
v2.15.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Oct 10, 2018 License: Apache-2.0 Imports: 28 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 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 glide and semantic versioning when including this library into an application. For example, Jaeger backend imports this library like this:

- package: github.com/uber/jaeger-client-go
  version: ^2.7.0

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

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.15.0"

	// 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

	// 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 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 

func BuildJaegerProcessThrift(span *Span) *j.Process

BuildJaegerProcessThrift creates a thrift Process type.

func BuildJaegerThrift 

func BuildJaegerThrift(span *Span) *j.Span

BuildJaegerThrift builds jaeger span based on internal span.

func BuildZipkinThrift 

func BuildZipkinThrift(s *Span) *z.Span

BuildZipkinThrift builds thrift span based on internal span.

func ConvertLogsToJaegerTags 

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

ConvertLogsToJaegerTags converts log Fields into jaeger tags.

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.

Types

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 

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 

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 

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.

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 by doing nothing.

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"`

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

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

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

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

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

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

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

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

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

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

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

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

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

	// Number of times the Sampler succeeded to retrieve and update sampling strategy
	SamplerUpdated metrics.Counter `metric:"sampler_updates" tags:"result=ok"`

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

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

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

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

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

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

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

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

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

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 

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 

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

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

type ProcessSetter 

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 

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 

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

Span implements opentracing.Span

func (*Span) BaggageItem 

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

BaggageItem implements BaggageItem() of opentracing.SpanContext

func (*Span) Context 

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

Context implements opentracing.Span API

func (*Span) Finish 

func (s *Span) Finish()

Finish implements opentracing.Span API

func (*Span) FinishWithOptions 

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

FinishWithOptions implements opentracing.Span API

func (*Span) Log 

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

Log implements opentracing.Span API

func (*Span) LogEvent 

func (s *Span) LogEvent(event string)

LogEvent implements opentracing.Span API

func (*Span) LogEventWithPayload 

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

LogEventWithPayload implements opentracing.Span API

func (*Span) LogFields 

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

LogFields implements opentracing.Span API

func (*Span) LogKV 

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

LogKV implements opentracing.Span API

func (*Span) OperationName 

func (s *Span) OperationName() string

OperationName allows retrieving current operation name.

func (*Span) SetBaggageItem 

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

SetBaggageItem implements SetBaggageItem() of opentracing.SpanContext

func (*Span) SetOperationName 

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

SetOperationName sets or changes the operation name.

func (*Span) SetTag 

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

SetTag implements SetTag() of opentracing.Span

func (*Span) String 

func (s *Span) String() string

func (*Span) Tracer 

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

Tracer implements opentracing.Span API

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) 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 added in v1.4.1 

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 

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

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

Tracer implements opentracing.Tracer.

func (*Tracer) Close 

func (t *Tracer) Close() error

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

func (*Tracer) Extract 

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

Extract implements Extract() method of opentracing.Tracer

func (*Tracer) Inject 

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

Inject implements Inject() method of opentracing.Tracer

func (*Tracer) StartSpan 

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

StartSpan implements StartSpan() method of opentracing.Tracer.

func (*Tracer) Tags 

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 

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 

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 compatiblity.
 Package zipkin comprises Zipkin functionality for Zipkin compatiblity.

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.