trace

package
v0.6.1 Latest Latest
Warning

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

Go to latest
Published: Jun 18, 2020 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package trace contains support for OpenTelemetry distributed tracing.

The following assumes a basic familiarity with OpenTelemetry concepts. See https://opentelemetry.io.

Index

Constants

View Source
const (
	DefaultMaxQueueSize       = 2048
	DefaultBatchTimeout       = 5000 * time.Millisecond
	DefaultMaxExportBatchSize = 512
)
View Source
const (
	// DefaultMaxEventsPerSpan is default max number of message events per span
	DefaultMaxEventsPerSpan = 128

	// DefaultMaxAttributesPerSpan is default max number of attributes per span
	DefaultMaxAttributesPerSpan = 32

	// DefaultMaxLinksPerSpan is default max number of links per span
	DefaultMaxLinksPerSpan = 32
)

Variables

This section is empty.

Functions

func RegisterSpanProcessor

func RegisterSpanProcessor(e SpanProcessor)

RegisterSpanProcessor adds to the list of SpanProcessors that will receive sampled trace spans.

func UnregisterSpanProcessor

func UnregisterSpanProcessor(s SpanProcessor)

UnregisterSpanProcessor removes from the list of SpanProcessors the SpanProcessor that was registered with the given name.

Types

type BatchSpanProcessor

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

BatchSpanProcessor implements SpanProcessor interfaces. It is used by exporters to receive export.SpanData asynchronously. Use BatchSpanProcessorOptions to change the behavior of the processor.

func NewBatchSpanProcessor

func NewBatchSpanProcessor(e export.SpanBatcher, opts ...BatchSpanProcessorOption) (*BatchSpanProcessor, error)

NewBatchSpanProcessor creates a new instance of BatchSpanProcessor for a given export. It returns an error if exporter is nil. The newly created BatchSpanProcessor should then be registered with sdk using RegisterSpanProcessor.

func (*BatchSpanProcessor) OnEnd

func (bsp *BatchSpanProcessor) OnEnd(sd *export.SpanData)

OnEnd method enqueues export.SpanData for later processing.

func (*BatchSpanProcessor) OnStart

func (bsp *BatchSpanProcessor) OnStart(sd *export.SpanData)

OnStart method does nothing.

func (*BatchSpanProcessor) Shutdown

func (bsp *BatchSpanProcessor) Shutdown()

Shutdown flushes the queue and waits until all spans are processed. It only executes once. Subsequent call does nothing.

type BatchSpanProcessorOption

type BatchSpanProcessorOption func(o *BatchSpanProcessorOptions)

func WithBatchTimeout

func WithBatchTimeout(delay time.Duration) BatchSpanProcessorOption

func WithBlocking

func WithBlocking() BatchSpanProcessorOption

func WithMaxExportBatchSize

func WithMaxExportBatchSize(size int) BatchSpanProcessorOption

func WithMaxQueueSize

func WithMaxQueueSize(size int) BatchSpanProcessorOption

type BatchSpanProcessorOptions

type BatchSpanProcessorOptions struct {
	// MaxQueueSize is the maximum queue size to buffer spans for delayed processing. If the
	// queue gets full it drops the spans. Use BlockOnQueueFull to change this behavior.
	// The default value of MaxQueueSize is 2048.
	MaxQueueSize int

	// BatchTimeout is the maximum duration for constructing a batch. Processor
	// forcefully sends available spans when timeout is reached.
	// The default value of BatchTimeout is 5000 msec.
	BatchTimeout time.Duration

	// MaxExportBatchSize is the maximum number of spans to process in a single batch.
	// If there are more than one batch worth of spans then it processes multiple batches
	// of spans one batch after the other without any delay.
	// The default value of MaxExportBatchSize is 512.
	MaxExportBatchSize int

	// BlockOnQueueFull blocks onEnd() and onStart() method if the queue is full
	// AND if BlockOnQueueFull is set to true.
	// Blocking option should be used carefully as it can severely affect the performance of an
	// application.
	BlockOnQueueFull bool
}

type Config

type Config struct {
	// DefaultSampler is the default sampler used when creating new spans.
	DefaultSampler Sampler

	// IDGenerator is for internal use only.
	IDGenerator internal.IDGenerator

	// MaxEventsPerSpan is max number of message events per span
	MaxEventsPerSpan int

	// MaxAnnotationEventsPerSpan is max number of attributes per span
	MaxAttributesPerSpan int

	// MaxLinksPerSpan is max number of links per span
	MaxLinksPerSpan int

	// Resource contains attributes representing an entity that produces telemetry.
	Resource *resource.Resource
}

Config represents the global tracing configuration.

type Provider

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

func NewProvider

func NewProvider(opts ...ProviderOption) (*Provider, error)

NewProvider creates an instance of trace provider. Optional parameter configures the provider with common options applicable to all tracer instances that will be created by this provider.

func (*Provider) ApplyConfig

func (p *Provider) ApplyConfig(cfg Config)

ApplyConfig changes the configuration of the provider. If a field in the configuration is empty or nil then its original value is preserved.

func (*Provider) RegisterSpanProcessor

func (p *Provider) RegisterSpanProcessor(s SpanProcessor)

RegisterSpanProcessor adds the given SpanProcessor to the list of SpanProcessors

func (*Provider) Tracer

func (p *Provider) Tracer(name string, opts ...apitrace.TracerOption) apitrace.Tracer

Tracer with the given name. If a tracer for the given name does not exist, it is created first. If the name is empty, DefaultTracerName is used.

func (*Provider) UnregisterSpanProcessor

func (p *Provider) UnregisterSpanProcessor(s SpanProcessor)

UnregisterSpanProcessor removes the given SpanProcessor from the list of SpanProcessors

type ProviderOption

type ProviderOption func(*ProviderOptions)

func WithBatcher

WithBatcher options appends the batcher to the existing list of Batchers. This option can be used multiple times. The Batchers are wrapped into BatchedSpanProcessors and registered with the provider.

func WithConfig

func WithConfig(config Config) ProviderOption

WithConfig option sets the configuration to provider.

func WithResource

func WithResource(r *resource.Resource) ProviderOption

WithResource option attaches a resource to the provider. The resource is added to the span when it is started.

func WithSyncer

func WithSyncer(syncer export.SpanSyncer) ProviderOption

WithSyncer options appends the syncer to the existing list of Syncers. This option can be used multiple times. The Syncers are wrapped into SimpleSpanProcessors and registered with the provider.

type ProviderOptions

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

ProviderOptions

type Sampler

type Sampler interface {
	ShouldSample(SamplingParameters) SamplingResult
	Description() string
}

Sampler decides whether a trace should be sampled and exported.

func AlwaysSample

func AlwaysSample() Sampler

AlwaysSample returns a Sampler that samples every trace. Be careful about using this sampler in a production application with significant traffic: a new trace will be started and exported for every request.

func NeverSample

func NeverSample() Sampler

NeverSample returns a Sampler that samples no traces.

func ParentSample

func ParentSample(fallback Sampler) Sampler

ParentSample returns a Sampler that samples a trace only if the the span has a parent span and it is sampled. If the span has parent span but it is not sampled, neither will this span. If the span does not have a parent the fallback Sampler is used to determine if the span should be sampled.

func ProbabilitySampler

func ProbabilitySampler(fraction float64) Sampler

ProbabilitySampler samples a given fraction of traces. Fractions >= 1 will always sample. If the parent span is sampled, then it's child spans will automatically be sampled. Fractions < 0 are treated as zero, but spans may still be sampled if their parent is.

type SamplingDecision

type SamplingDecision uint8

SamplingDecision indicates whether a span is recorded and sampled.

const (
	NotRecord SamplingDecision = iota
	Record
	RecordAndSampled
)

Valid sampling decisions

type SamplingParameters

type SamplingParameters struct {
	ParentContext   api.SpanContext
	TraceID         api.ID
	Name            string
	HasRemoteParent bool
	Kind            api.SpanKind
	Attributes      []kv.KeyValue
	Links           []api.Link
}

SamplingParameters contains the values passed to a Sampler.

type SamplingResult

type SamplingResult struct {
	Decision   SamplingDecision
	Attributes []kv.KeyValue
}

SamplingResult conveys a SamplingDecision and a set of Attributes.

type SimpleSpanProcessor

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

SimpleSpanProcessor implements SpanProcessor interfaces. It is used by exporters to receive SpanData synchronously when span is finished.

func NewSimpleSpanProcessor

func NewSimpleSpanProcessor(e export.SpanSyncer) *SimpleSpanProcessor

NewSimpleSpanProcessor creates a new instance of SimpleSpanProcessor for a given export.

func (*SimpleSpanProcessor) OnEnd

func (ssp *SimpleSpanProcessor) OnEnd(sd *export.SpanData)

OnEnd method exports SpanData using associated export.

func (*SimpleSpanProcessor) OnStart

func (ssp *SimpleSpanProcessor) OnStart(sd *export.SpanData)

OnStart method does nothing.

func (*SimpleSpanProcessor) Shutdown

func (ssp *SimpleSpanProcessor) Shutdown()

Shutdown method does nothing. There is no data to cleanup.

type SpanProcessor

type SpanProcessor interface {

	// OnStart method is invoked when span is started. It is a synchronous call
	// and hence should not block.
	OnStart(sd *export.SpanData)

	// OnEnd method is invoked when span is finished. It is a synchronous call
	// and hence should not block.
	OnEnd(sd *export.SpanData)

	// Shutdown is invoked when SDK shutsdown. Use this call to cleanup any processor
	// data. No calls to OnStart and OnEnd method is invoked after Shutdown call is
	// made. It should not be blocked indefinitely.
	Shutdown()
}

SpanProcessor is interface to add hooks to start and end method invocations.

Directories

Path Synopsis
Package internal provides trace internals.
Package internal provides trace internals.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL