jaeger

package module
v2.29.1+incompatible Latest Latest
Warning

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

 Go to latest Published: May 24, 2021 License: Apache-2.0 Imports: 35 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, if it is built from a config that was created via FromEnv(). None of the env vars are required and all of them can be overridden 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 (default localhost).
JAEGER_AGENT_PORT The port for communicating with agent via UDP (default 6831).
JAEGER_ENDPOINT The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. If specified, the agent host/port are ignored.
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" true or false (default false).
JAEGER_REPORTER_MAX_QUEUE_SIZE The reporter's maximum queue size (default 100).
JAEGER_REPORTER_FLUSH_INTERVAL The reporter's flush interval, with units, e.g. 500ms or 2s (valid units; default 1s).
JAEGER_REPORTER_ATTEMPT_RECONNECTING_DISABLED When true, disables udp connection helper that periodically re-resolves the agent's hostname and reconnects if there was a change (default false).
JAEGER_REPORTER_ATTEMPT_RECONNECT_INTERVAL Controls how often the agent client re-resolves the provided hostname in order to detect address changes (valid units; default 30s).
JAEGER_SAMPLER_TYPE The sampler type: remote, const, probabilistic, ratelimiting (default remote). See also https://www.jaegertracing.io/docs/latest/sampling/.
JAEGER_SAMPLER_PARAM The sampler parameter (number).
JAEGER_SAMPLER_MANAGER_HOST_PORT (deprecated) The HTTP endpoint when using the remote sampler.
JAEGER_SAMPLING_ENDPOINT The URL for the sampling configuration server when using sampler type remote (default http://127.0.0.1:5778/sampling).
JAEGER_SAMPLER_MAX_OPERATIONS The maximum number of operations that the sampler will keep track of (default 2000).
JAEGER_SAMPLER_REFRESH_INTERVAL How often the remote sampler should poll the configuration server for the appropriate sampling strategy, e.g. "1m" or "30s" (valid units; default 1m).
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:defaultValue}.
JAEGER_DISABLED Whether the tracer is disabled or not. If true, the opentracing.NoopTracer is used (default false).
JAEGER_RPC_METRICS Whether to store RPC metrics, true or false (default false).

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.Close() 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.
Delayed sampling

Version 2.20 introduced the ability to delay sampling decisions in the life cycle of the root span. It involves several features and architectural changes:

  • Shared sampling state: the sampling state is shared across all local (i.e. in-process) spans for a given trace.
  • New SamplerV2 API allows the sampler to be called at multiple points in the life cycle of a span:
    • on span creation
    • on overwriting span operation name
    • on setting span tags
    • on finishing the span
  • Final/non-final sampling state: the new SamplerV2 API allows the sampler to indicate if the negative sampling decision is final or not (positive sampling decisions are always final). If the decision is not final, the sampler will be called again on further span life cycle events, like setting tags.

These new features are used in the experimental x.TagMatchingSampler, which can sample a trace based on a certain tag added to the root span or one of its local (in-process) children. The sampler can be used with another experimental x.PrioritySampler that allows multiple samplers to try to make a sampling decision, in a certain priority order.

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 span reference type call Self, which was proposed to the OpenTracing Specification (https://github.com/opentracing/specification/issues/81) but not yet accepted. This allows the caller to provide an already created SpanContext when starting a new span. The Self reference bypasses trace and span id generation, as well as sampling decisions (i.e. the sampling bit in the SpanContext.flags must be set appropriately by the caller).

The Self reference supports the following use cases:

  • the ability to provide externally generated trace and span IDs
  • appending data to the same span from different processes, such as loading and continuing spans/traces from offline (ie log-based) storage

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

span := tracer.StartSpan(
    "continued_span",
    jaeger.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.29.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://127.0.0.1:%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 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. TODO: (breaking change) move to internal package.

func BuildJaegerThrift 

func BuildJaegerThrift(span *Span) *j.Span

BuildJaegerThrift builds jaeger span based on internal span. TODO: (breaking change) move to internal package.

func BuildZipkinThrift 

func BuildZipkinThrift(s *Span) *z.Span

BuildZipkinThrift builds thrift span based on internal span. TODO: (breaking change) move to transport/zipkin and make private.

func ConvertLogsToJaegerTags 

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

ConvertLogsToJaegerTags converts log Fields into jaeger tags.

func EnableFirehose 

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. TODO (breaking change) return *Tracer only, without closer.

func SelfRef 

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 AdaptiveSamplerUpdater 

type AdaptiveSamplerUpdater struct {
	MaxOperations            int
	OperationNameLateBinding bool
}

AdaptiveSamplerUpdater is used by RemotelyControlledSampler to parse sampling configuration. Fields have the same meaning as in PerOperationSamplerParams.

func (*AdaptiveSamplerUpdater) Update 

func (u *AdaptiveSamplerUpdater) Update(sampler SamplerV2, strategy interface{}) (SamplerV2, error)

Update implements Update of SamplerUpdater.

type BinaryPropagator 

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

BinaryPropagator is a combined Injector and Extractor for Binary format

func NewBinaryPropagator 

func NewBinaryPropagator(tracer *Tracer) *BinaryPropagator

NewBinaryPropagator creates a combined Injector and Extractor for Binary format

func (*BinaryPropagator) Extract 

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

Extract implements Extractor of BinaryPropagator

func (*BinaryPropagator) Inject 

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 NewConstSampler 

func NewConstSampler(sample bool) *ConstSampler

NewConstSampler creates a ConstSampler.

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.

func (*ConstSampler) OnCreateSpan 

func (s *ConstSampler) OnCreateSpan(span *Span) SamplingDecision

func (*ConstSampler) OnFinishSpan 

func (s *ConstSampler) OnFinishSpan(span *Span) SamplingDecision

func (*ConstSampler) OnSetOperationName 

func (s *ConstSampler) OnSetOperationName(span *Span, operationName string) SamplingDecision

func (*ConstSampler) OnSetTag 

func (s *ConstSampler) OnSetTag(span *Span, key string, value interface{}) SamplingDecision

func (*ConstSampler) String 

func (s *ConstSampler) String() string

String is used to log sampler details.

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.

func (GuaranteedThroughputProbabilisticSampler) String 

func (s GuaranteedThroughputProbabilisticSampler) String() string

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.

func (*HeadersConfig) ApplyDefaults 

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 traces started by this tracer with delayed sampling
	TracesStartedDelayedSampling metrics.Counter `metric:"traces" tags:"state=started,sampled=n" help:"Number of traces started by this tracer with delayed sampling"`

	// 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 spans started by this tracer as sampled"`

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

	// Number of spans with delayed sampling started by this tracer
	SpansStartedDelayedSampling metrics.Counter `metric:"started_spans" tags:"sampled=delayed" help:"Number of spans started by this tracer with delayed sampling"`

	// Number of spans finished by this tracer
	SpansFinishedSampled metrics.Counter `metric:"finished_spans" tags:"sampled=y" help:"Number of sampled spans finished by this tracer"`

	// Number of spans finished by this tracer
	SpansFinishedNotSampled metrics.Counter `metric:"finished_spans" tags:"sampled=n" help:"Number of not-sampled spans finished by this tracer"`

	// Number of spans finished by this tracer
	SpansFinishedDelayedSampling metrics.Counter `metric:"finished_spans" tags:"sampled=delayed" help:"Number of spans with delayed sampling 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 

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 PerOperationSampler 

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

PerOperationSampler is a delegating sampler that applies GuaranteedThroughputProbabilisticSampler on a per-operation basis.

func NewAdaptiveSampler 

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

NewAdaptiveSampler returns a new PerOperationSampler. Deprecated: please use NewPerOperationSampler.

func NewPerOperationSampler 

func NewPerOperationSampler(params PerOperationSamplerParams) *PerOperationSampler

NewPerOperationSampler returns a new PerOperationSampler.

func (*PerOperationSampler) Close 

func (s *PerOperationSampler) Close()

Close invokes Close on all underlying samplers.

func (*PerOperationSampler) Equal 

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

Equal is not used. TODO (breaking change) remove this in the future

func (*PerOperationSampler) IsSampled 

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

IsSampled is not used and only exists to match Sampler V1 API. TODO (breaking change) remove when upgrading everything to SamplerV2

func (*PerOperationSampler) OnCreateSpan 

func (s *PerOperationSampler) OnCreateSpan(span *Span) SamplingDecision

OnCreateSpan implements OnCreateSpan of SamplerV2.

func (*PerOperationSampler) OnFinishSpan 

func (s *PerOperationSampler) OnFinishSpan(span *Span) SamplingDecision

OnFinishSpan implements OnFinishSpan of SamplerV2.

func (*PerOperationSampler) OnSetOperationName 

func (s *PerOperationSampler) OnSetOperationName(span *Span, operationName string) SamplingDecision

OnSetOperationName implements OnSetOperationName of SamplerV2.

func (*PerOperationSampler) OnSetTag 

func (s *PerOperationSampler) OnSetTag(span *Span, key string, value interface{}) SamplingDecision

OnSetTag implements OnSetTag of SamplerV2.

func (*PerOperationSampler) String 

func (s *PerOperationSampler) String() string

type PerOperationSamplerParams 

type PerOperationSamplerParams struct {
	// Max number of operations that will be tracked. Other operations will be given default strategy.
	MaxOperations int

	// Opt-in feature for applications that require late binding of span name via explicit call to SetOperationName.
	// When this feature is enabled, the sampler will return retryable=true from OnCreateSpan(), thus leaving
	// the sampling decision as non-final (and the span as writeable). This may lead to degraded performance
	// in applications that always provide the correct span name on trace creation.
	//
	// For backwards compatibility this option is off by default.
	OperationNameLateBinding bool

	// Initial configuration of the sampling strategies (usually retrieved from the backend by Remote Sampler).
	Strategies *sampling.PerOperationSamplingStrategies
}

PerOperationSamplerParams defines parameters when creating PerOperationSampler.

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

func (s *ProbabilisticSampler) OnCreateSpan(span *Span) SamplingDecision

func (*ProbabilisticSampler) OnFinishSpan 

func (s *ProbabilisticSampler) OnFinishSpan(span *Span) SamplingDecision

func (*ProbabilisticSampler) OnSetOperationName 

func (s *ProbabilisticSampler) OnSetOperationName(span *Span, operationName string) SamplingDecision

func (*ProbabilisticSampler) OnSetTag 

func (s *ProbabilisticSampler) OnSetTag(span *Span, key string, value interface{}) SamplingDecision

func (*ProbabilisticSampler) SamplingRate 

func (s *ProbabilisticSampler) SamplingRate() float64

SamplingRate returns the sampling probability this sampled was constructed with.

func (*ProbabilisticSampler) String 

func (s *ProbabilisticSampler) String() string

String is used to log sampler details.

func (*ProbabilisticSampler) Update 

func (s *ProbabilisticSampler) Update(samplingRate float64) error

Update modifies in-place the sampling rate. Locking must be done externally.

type ProbabilisticSamplerUpdater 

type ProbabilisticSamplerUpdater struct{}

ProbabilisticSamplerUpdater is used by RemotelyControlledSampler to parse sampling configuration.

func (*ProbabilisticSamplerUpdater) Update 

func (u *ProbabilisticSamplerUpdater) Update(sampler SamplerV2, strategy interface{}) (SamplerV2, error)

Update implements Update of SamplerUpdater.

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 RateLimitingSampler 

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

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

func NewRateLimitingSampler 

func NewRateLimitingSampler(maxTracesPerSecond float64) *RateLimitingSampler

NewRateLimitingSampler creates new RateLimitingSampler.

func (*RateLimitingSampler) Close 

func (s *RateLimitingSampler) Close()

Close does nothing.

func (*RateLimitingSampler) Equal 

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

Equal compares with another sampler.

func (*RateLimitingSampler) IsSampled 

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

IsSampled implements IsSampled() of Sampler.

func (*RateLimitingSampler) OnCreateSpan 

func (s *RateLimitingSampler) OnCreateSpan(span *Span) SamplingDecision

func (*RateLimitingSampler) OnFinishSpan 

func (s *RateLimitingSampler) OnFinishSpan(span *Span) SamplingDecision

func (*RateLimitingSampler) OnSetOperationName 

func (s *RateLimitingSampler) OnSetOperationName(span *Span, operationName string) SamplingDecision

func (*RateLimitingSampler) OnSetTag 

func (s *RateLimitingSampler) OnSetTag(span *Span, key string, value interface{}) SamplingDecision

func (*RateLimitingSampler) String 

func (s *RateLimitingSampler) String() string

String is used to log sampler details.

func (*RateLimitingSampler) Update 

func (s *RateLimitingSampler) Update(maxTracesPerSecond float64)

Update reconfigures the rate limiter, while preserving its accumulated balance. Locking must be done externally.

type RateLimitingSamplerUpdater 

type RateLimitingSamplerUpdater struct{}

RateLimitingSamplerUpdater is used by RemotelyControlledSampler to parse sampling configuration.

func (*RateLimitingSamplerUpdater) Update 

func (u *RateLimitingSamplerUpdater) Update(sampler SamplerV2, strategy interface{}) (SamplerV2, error)

Update implements Update of SamplerUpdater.

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 // used to serialize access to samplerOptions.sampler
	// 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) IsSampled 

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

IsSampled implements IsSampled() of Sampler. TODO (breaking change) remove when Sampler V1 is removed

func (*RemotelyControlledSampler) OnCreateSpan 

func (s *RemotelyControlledSampler) OnCreateSpan(span *Span) SamplingDecision

OnCreateSpan implements OnCreateSpan of SamplerV2.

func (*RemotelyControlledSampler) OnFinishSpan 

func (s *RemotelyControlledSampler) OnFinishSpan(span *Span) SamplingDecision

OnFinishSpan implements OnFinishSpan of SamplerV2.

func (*RemotelyControlledSampler) OnSetOperationName 

func (s *RemotelyControlledSampler) OnSetOperationName(span *Span, operationName string) SamplingDecision

OnSetOperationName implements OnSetOperationName of SamplerV2.

func (*RemotelyControlledSampler) OnSetTag 

func (s *RemotelyControlledSampler) OnSetTag(span *Span, key string, value interface{}) SamplingDecision

OnSetTag implements OnSetTag of SamplerV2.

func (*RemotelyControlledSampler) Sampler 

func (s *RemotelyControlledSampler) Sampler() SamplerV2

Sampler returns the currently active sampler.

func (*RemotelyControlledSampler) UpdateSampler 

func (s *RemotelyControlledSampler) UpdateSampler()

UpdateSampler forces the sampler to fetch sampling strategy from backend server. This function is called automatically on a timer, but can also be safely called manually, e.g. from tests.

type Reporter 

type Reporter interface {
	// Report submits a new span to collectors, possibly asynchronously and/or with buffering.
	// If the reporter is processing Span asynchronously then it needs to Retain() the span,
	// and then Release() it when no longer needed, to avoid span data corruption.
	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 (breaking change) remove this function. See PerOperationSampler.Equals for explanation.
	Equal(other Sampler) bool
}

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

type SamplerOption 

type SamplerOption func(options *samplerOptions)

SamplerOption is a function that sets some option on the sampler

type SamplerOptionsFactory 

type SamplerOptionsFactory struct{}

SamplerOptionsFactory is a factory for all available SamplerOption's. The type acts as a namespace for factory functions. It is public to make the functions discoverable via godoc. Recommended to be used via global SamplerOptions variable. 

var SamplerOptions SamplerOptionsFactory

SamplerOptions is a factory for all available SamplerOption's.

func (SamplerOptionsFactory) InitialSampler 

func (SamplerOptionsFactory) InitialSampler(sampler Sampler) SamplerOption

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

func (SamplerOptionsFactory) Logger 

func (SamplerOptionsFactory) Logger(logger Logger) SamplerOption

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

func (SamplerOptionsFactory) MaxOperations 

func (SamplerOptionsFactory) MaxOperations(maxOperations int) SamplerOption

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

func (SamplerOptionsFactory) Metrics 

func (SamplerOptionsFactory) Metrics(m *Metrics) SamplerOption

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

func (SamplerOptionsFactory) OperationNameLateBinding 

func (SamplerOptionsFactory) OperationNameLateBinding(enable bool) SamplerOption

OperationNameLateBinding creates a SamplerOption that sets the respective field in the PerOperationSamplerParams.

func (SamplerOptionsFactory) SamplingRefreshInterval 

func (SamplerOptionsFactory) 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 (SamplerOptionsFactory) SamplingServerURL 

func (SamplerOptionsFactory) SamplingServerURL(samplingServerURL string) SamplerOption

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

func (SamplerOptionsFactory) SamplingStrategyFetcher 

func (SamplerOptionsFactory) SamplingStrategyFetcher(fetcher SamplingStrategyFetcher) SamplerOption

SamplingStrategyFetcher creates a SamplerOption that initializes sampling strategy fetcher.

func (SamplerOptionsFactory) SamplingStrategyParser 

func (SamplerOptionsFactory) SamplingStrategyParser(parser SamplingStrategyParser) SamplerOption

SamplingStrategyParser creates a SamplerOption that initializes sampling strategy parser.

func (SamplerOptionsFactory) Updaters 

func (SamplerOptionsFactory) Updaters(updaters ...SamplerUpdater) SamplerOption

Updaters creates a SamplerOption that initializes sampler updaters.

type SamplerUpdater 

type SamplerUpdater interface {
	Update(sampler SamplerV2, strategy interface{}) (modified SamplerV2, err error)
}

SamplerUpdater is used by RemotelyControlledSampler to apply sampling strategies, retrieved from remote config server, to the current sampler. The updater can modify the sampler in-place if sampler supports it, or create a new one.

If the strategy does not contain configuration for the sampler in question, updater must return modifiedSampler=nil to give other updaters a chance to inspect the sampling strategy response.

RemotelyControlledSampler invokes the updaters while holding a lock on the main sampler.

type SamplerV2 

type SamplerV2 interface {
	OnCreateSpan(span *Span) SamplingDecision
	OnSetOperationName(span *Span, operationName string) SamplingDecision
	OnSetTag(span *Span, key string, value interface{}) SamplingDecision
	OnFinishSpan(span *Span) SamplingDecision

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

SamplerV2 is an extension of the V1 samplers that allows sampling decisions be made at different points of the span lifecycle.

type SamplerV2Base 

type SamplerV2Base struct{}

SamplerV2Base can be used by V2 samplers to implement dummy V1 methods. Supporting V1 API is required because Tracer configuration only accepts V1 Sampler for backwards compatibility reasons. TODO (breaking change) remove this in the next major release

func (SamplerV2Base) Close 

func (SamplerV2Base) Close()

Close implements Close of Sampler.

func (SamplerV2Base) Equal 

func (SamplerV2Base) Equal(other Sampler) bool

Equal implements Equal of Sampler.

func (SamplerV2Base) IsSampled 

func (SamplerV2Base) IsSampled(id TraceID, operation string) (sampled bool, tags []Tag)

IsSampled implements IsSampled of Sampler.

type SamplingDecision 

type SamplingDecision struct {
	Sample    bool
	Retryable bool
	Tags      []Tag
}

SamplingDecision is returned by the V2 samplers.

type SamplingStrategyFetcher 

type SamplingStrategyFetcher interface {
	Fetch(service string) ([]byte, error)
}

SamplingStrategyFetcher is used to fetch sampling strategy updates from remote server.

type SamplingStrategyParser 

type SamplingStrategyParser interface {
	Parse(response []byte) (interface{}, error)
}

SamplingStrategyParser is used to parse sampling strategy updates. The output object should be of the type that is recognized by the SamplerUpdaters.

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

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

Duration returns span duration

func (*Span) Finish 

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 

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

func (s *Span) Logs() []opentracing.LogRecord

Logs returns micro logs for span

func (*Span) OperationName 

func (s *Span) OperationName() string

OperationName allows retrieving current operation name.

func (*Span) References 

func (s *Span) References() []opentracing.SpanReference

References returns references for this span

func (*Span) Release 

func (s *Span) Release()

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

func (*Span) Retain 

func (s *Span) Retain() *Span

Retain increases object counter to increase the lifetime of the object

func (*Span) SetBaggageItem 

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

SetBaggageItem implements SetBaggageItem() of opentracing.SpanContext. The call is proxied via tracer.baggageSetter to allow policies to be applied before allowing to set/replace baggage keys. The setter eventually stores a new SpanContext with extended baggage: 

   span.context = span.context.WithBaggageItem(key, value)

See SpanContext.WithBaggageItem() for explanation why it's done this way.

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

func (s *Span) SpanContext() SpanContext

SpanContext returns span context

func (*Span) StartTime 

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

StartTime returns span start time

func (*Span) String 

func (s *Span) String() string

func (*Span) Tags 

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

Tags returns tags for span

func (*Span) Tracer 

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

Tracer implements opentracing.Span API

type SpanAllocator 

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

func (c SpanContext) ExtendedSamplingState(key interface{}, initValue func() interface{}) interface{}

ExtendedSamplingState returns the custom state object for a given key. If the value for this key does not exist, it is initialized via initValue function. This state can be used by samplers (e.g. x.PrioritySampler).

func (SpanContext) Flags 

func (c SpanContext) Flags() byte

Flags returns the bitmap containing such bits as 'sampled' and 'debug'.

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 

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

func (c SpanContext) IsSamplingFinalized() bool

IsSamplingFinalized indicates whether the sampling decision has been finalized.

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

func (c SpanContext) SetFirehose()

SetFirehose enables firehose mode for this trace.

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. Delete a baggage item if provided blank value.

The SpanContext is designed to be immutable and passed by value. As such, it cannot contain any locks, and should only hold immutable data, including baggage. Another reason for why baggage is immutable is when the span context is passed as a parent when starting a new span. The new span's baggage cannot affect the parent span's baggage, so the child span either needs to take a copy of the parent baggage (which is expensive and unnecessary since baggage rarely changes in the life span of a trace), or it needs to do a copy-on-write, which is the approach taken here.

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 (breaking change) deprecate in the next major release, use opentracing.Tag instead.

func NewTag 

func NewTag(key string, value interface{}) Tag

NewTag creates a new Tag. TODO (breaking change) deprecate in the next major release, use opentracing.Tag instead.

type TextMapPropagator 

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

TextMapPropagator is a combined Injector and Extractor for TextMap format

func NewHTTPHeaderPropagator 

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

NewHTTPHeaderPropagator creates a combined Injector and Extractor for HTTPHeaders format

func NewTextMapPropagator 

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

NewTextMapPropagator creates a combined Injector and Extractor for TextMap format

func (*TextMapPropagator) Extract 

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

Extract implements Extractor of TextMapPropagator

func (*TextMapPropagator) Inject 

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 

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

func (t *Tracer) Sampler() SamplerV2

Sampler returns the sampler given to the tracer at creation.

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. TODO: (breaking change) move to transport/ package.

func NewUDPTransportWithParams 

func NewUDPTransportWithParams(params UDPTransportParams) (Transport, error)

NewUDPTransportWithParams creates a reporter that submits spans to jaeger-agent. TODO: (breaking change) move to transport/ package.

type UDPTransportParams 

type UDPTransportParams struct {
	utils.AgentClientUDPParams
}

UDPTransportParams allows specifying options for initializing a UDPTransport. An instance of this struct should be passed to NewUDPTransportWithParams.

Source Files

View all Source files

Directories

Path Synopsis
client
common
endtoend
log
server
thrift/tracetest
internal
baggage
baggage/remote
reporterstats
spanlog
throttler
throttler/remote
log
zap
zap/mock_opentracing
Package mock_opentracing is a generated GoMock package.
 Package mock_opentracing is a generated GoMock package.
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.
x
Package x contains experimental functionality with no guarantees of stable APIs.
 Package x contains experimental functionality with no guarantees of stable APIs.
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.