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
- func RegisterSpanProcessor(e SpanProcessor)
- func UnregisterSpanProcessor(s SpanProcessor)
- type BatchSpanProcessor
- type BatchSpanProcessorOption
- type BatchSpanProcessorOptions
- type Config
- type Provider
- type ProviderOption
- type ProviderOptions
- type Sampler
- type SamplingDecision
- type SamplingParameters
- type SamplingResult
- type SimpleSpanProcessor
- type SpanProcessor
Constants ¶
const ( DefaultMaxQueueSize = 2048 DefaultBatchTimeout = 5000 * time.Millisecond DefaultMaxExportBatchSize = 512 )
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 ¶
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 ¶
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 ¶
func WithBatcher(b export.SpanBatcher, bopts ...BatchSpanProcessorOption) ProviderOption
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 ParentSample ¶
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 ¶
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.
Source Files
Directories