trace

package
v0.0.0-...-52b58a3 Latest Latest
Warning

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

 Go to latest Published: Jan 31, 2022 License: Apache-2.0, Apache-2.0, Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package trace contains support for OpenTelemetry distributed tracing.

This package is currently in a pre-GA phase. Backwards incompatible changes may be introduced in subsequent minor version releases as we work to track the evolving OpenTelemetry specification and user feedback.

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

Index

Constants

View Source 
const (
	DefaultMaxQueueSize       = 2048
	DefaultBatchTimeout       = 5000 * time.Millisecond
	DefaultExportTimeout      = 30000 * time.Millisecond
	DefaultMaxExportBatchSize = 512
)
View Source 
const (
	// DefaultAttributeCountLimit is the default maximum allowed span attribute count.
	DefaultAttributeCountLimit = 128

	// DefaultEventCountLimit is the default maximum allowed span event count.
	DefaultEventCountLimit = 128

	// DefaultLinkCountLimit is the default maximum allowed span link count.
	DefaultLinkCountLimit = 128

	// DefaultAttributePerEventCountLimit is the default maximum allowed attribute per span event count.
	DefaultAttributePerEventCountLimit = 128

	// DefaultAttributePerLinkCountLimit is the default maximum allowed attribute per span link count.
	DefaultAttributePerLinkCountLimit = 128
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BatchSpanProcessorOption 

type BatchSpanProcessorOption func(o *BatchSpanProcessorOptions)

func WithBatchTimeout 

func WithBatchTimeout(delay time.Duration) BatchSpanProcessorOption

func WithBlocking 

func WithBlocking() BatchSpanProcessorOption

func WithExportTimeout 

func WithExportTimeout(timeout time.Duration) 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

	// ExportTimeout specifies the maximum duration for exporting spans. If the timeout
	// is reached, the export will be cancelled.
	// The default value of ExportTimeout is 30000 msec.
	ExportTimeout 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 IDGenerator 

type IDGenerator interface {
	NewIDs(ctx context.Context) (trace.TraceID, trace.SpanID)
	NewSpanID(ctx context.Context, traceID trace.TraceID) trace.SpanID
}

IDGenerator allows custom generators for TraceID and SpanID.

type ParentBasedSamplerOption 

type ParentBasedSamplerOption interface {
	Apply(*config)
	// contains filtered or unexported methods
}

ParentBasedSamplerOption configures the sampler for a particular sampling case.

func WithLocalParentNotSampled 

func WithLocalParentNotSampled(s Sampler) ParentBasedSamplerOption

WithLocalParentNotSampled sets the sampler for the case of local parent which is not sampled.

func WithLocalParentSampled 

func WithLocalParentSampled(s Sampler) ParentBasedSamplerOption

WithLocalParentSampled sets the sampler for the case of sampled local parent.

func WithRemoteParentNotSampled 

func WithRemoteParentNotSampled(s Sampler) ParentBasedSamplerOption

WithRemoteParentNotSampled sets the sampler for the case of remote parent which is not sampled.

func WithRemoteParentSampled 

func WithRemoteParentSampled(s Sampler) ParentBasedSamplerOption

WithRemoteParentSampled sets the sampler for the case of sampled remote parent.

type ReadOnlySpan 

type ReadOnlySpan interface {
	Name() string
	SpanContext() trace.SpanContext
	Parent() trace.SpanContext
	SpanKind() trace.SpanKind
	StartTime() time.Time
	EndTime() time.Time
	Attributes() []attribute.KeyValue
	Links() []trace.Link
	Events() []trace.Event
	StatusCode() codes.Code
	StatusMessage() string
	Tracer() trace.Tracer
	IsRecording() bool
	InstrumentationLibrary() instrumentation.Library
	Resource() *resource.Resource
	Snapshot() *SpanSnapshot
	// contains filtered or unexported methods
}

ReadOnlySpan allows reading information from the data structure underlying a trace.Span. It is used in places where reading information from a span is necessary but changing the span isn't necessary or allowed. TODO: Should we make the methods unexported? The purpose of this interface is controlling access to `span` fields, not having multiple implementations.

type ReadWriteSpan 

type ReadWriteSpan interface {
	trace.Span
	ReadOnlySpan
}

ReadWriteSpan exposes the same methods as trace.Span and in addition allows reading information from the underlying data structure. This interface exposes the union of the methods of trace.Span (which is a "write-only" span) and ReadOnlySpan. New methods for writing or reading span information should be added under trace.Span or ReadOnlySpan, respectively.

type Sampler 

type Sampler interface {
	ShouldSample(parameters 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 ParentBased 

func ParentBased(root Sampler, samplers ...ParentBasedSamplerOption) Sampler

ParentBased returns a composite sampler which behaves differently, based on the parent of the span. If the span has no parent, the root(Sampler) is used to make sampling decision. If the span has a parent, depending on whether the parent is remote and whether it is sampled, one of the following samplers will apply: - remoteParentSampled(Sampler) (default: AlwaysOn) - remoteParentNotSampled(Sampler) (default: AlwaysOff) - localParentSampled(Sampler) (default: AlwaysOn) - localParentNotSampled(Sampler) (default: AlwaysOff)

func TraceIDRatioBased 

func TraceIDRatioBased(fraction float64) Sampler

TraceIDRatioBased samples a given fraction of traces. Fractions >= 1 will always sample. Fractions < 0 are treated as zero. To respect the parent trace's `SampledFlag`, the `TraceIDRatioBased` sampler should be used as a delegate of a `Parent` sampler.

type SamplingDecision 

type SamplingDecision uint8

SamplingDecision indicates whether a span is dropped, recorded and/or sampled. 

const (
	// Drop will not record the span and all attributes/events will be dropped
	Drop SamplingDecision = iota

	// Record indicates the span's `IsRecording() == true`, but `Sampled` flag
	// *must not* be set
	RecordOnly

	// RecordAndSample has span's `IsRecording() == true` and `Sampled` flag
	// *must* be set
	RecordAndSample
)

Valid sampling decisions

type SamplingParameters 

type SamplingParameters struct {
	ParentContext context.Context
	TraceID       trace.TraceID
	Name          string
	Kind          trace.SpanKind
	Attributes    []attribute.KeyValue
	Links         []trace.Link
}

SamplingParameters contains the values passed to a Sampler.

type SamplingResult 

type SamplingResult struct {
	Decision   SamplingDecision
	Attributes []attribute.KeyValue
	Tracestate trace.TraceState
}

SamplingResult conveys a SamplingDecision, set of Attributes and a Tracestate.

type SpanExporter 

type SpanExporter interface {
	// ExportSpans exports a batch of SpanSnapshots.
	//
	// This function is called synchronously, so there is no concurrency
	// safety requirement. However, due to the synchronous calling pattern,
	// it is critical that all timeouts and cancellations contained in the
	// passed context must be honored.
	//
	// Any retry logic must be contained in this function. The SDK that
	// calls this function will not implement any retry logic. All errors
	// returned by this function are considered unrecoverable and will be
	// reported to a configured error Handler.
	ExportSpans(ctx context.Context, ss []*SpanSnapshot) error
	// Shutdown notifies the exporter of a pending halt to operations. The
	// exporter is expected to preform any cleanup or synchronization it
	// requires while honoring all timeouts and cancellations contained in
	// the passed context.
	Shutdown(ctx context.Context) error
}

SpanExporter handles the delivery of SpanSnapshot structs to external receivers. This is the final component in the trace export pipeline.

type SpanLimits 

type SpanLimits struct {
	// AttributeCountLimit is the maximum allowed span attribute count.
	AttributeCountLimit int

	// EventCountLimit is the maximum allowed span event count.
	EventCountLimit int

	// LinkCountLimit is the maximum allowed span link count.
	LinkCountLimit int

	// AttributePerEventCountLimit is the maximum allowed attribute per span event count.
	AttributePerEventCountLimit int

	// AttributePerLinkCountLimit is the maximum allowed attribute per span link count.
	AttributePerLinkCountLimit int
}

SpanLimits represents the limits of a span.

type SpanProcessor 

type SpanProcessor interface {
	// OnStart is called when a span is started. It is called synchronously
	// and should not block.
	OnStart(parent context.Context, s ReadWriteSpan)

	// OnEnd is called when span is finished. It is called synchronously and
	// hence not block.
	OnEnd(s ReadOnlySpan)

	// Shutdown is called when the SDK shuts down. Any cleanup or release of
	// resources held by the processor should be done in this call.
	//
	// Calls to OnStart, OnEnd, or ForceFlush after this has been called
	// should be ignored.
	//
	// All timeouts and cancellations contained in ctx must be honored, this
	// should not block indefinitely.
	Shutdown(ctx context.Context) error

	// ForceFlush exports all ended spans to the configured Exporter that have not yet
	// been exported.  It should only be called when absolutely necessary, such as when
	// using a FaaS provider that may suspend the process after an invocation, but before
	// the Processor can export the completed spans.
	ForceFlush(ctx context.Context) error
}

SpanProcessor is a processing pipeline for spans in the trace signal. SpanProcessors registered with a TracerProvider and are called at the start and end of a Span's lifecycle, and are called in the order they are registered.

func NewBatchSpanProcessor 

func NewBatchSpanProcessor(exporter SpanExporter, options ...BatchSpanProcessorOption) SpanProcessor

NewBatchSpanProcessor creates a new SpanProcessor that will send completed span batches to the exporter with the supplied options.

If the exporter is nil, the span processor will preform no action.

func NewSimpleSpanProcessor 

func NewSimpleSpanProcessor(exporter SpanExporter) SpanProcessor

NewSimpleSpanProcessor returns a new SpanProcessor that will synchronously send completed spans to the exporter immediately.

type SpanSnapshot 

type SpanSnapshot struct {
	SpanContext trace.SpanContext
	Parent      trace.SpanContext
	SpanKind    trace.SpanKind
	Name        string
	StartTime   time.Time
	// The wall clock time of EndTime will be adjusted to always be offset
	// from StartTime by the duration of the span.
	EndTime       time.Time
	Attributes    []attribute.KeyValue
	MessageEvents []trace.Event
	Links         []trace.Link
	StatusCode    codes.Code
	StatusMessage string

	// DroppedAttributeCount contains dropped attributes for the span itself.
	DroppedAttributeCount    int
	DroppedMessageEventCount int
	DroppedLinkCount         int

	// ChildSpanCount holds the number of child span created for this span.
	ChildSpanCount int

	// Resource contains attributes representing an entity that produced this span.
	Resource *resource.Resource

	// InstrumentationLibrary defines the instrumentation library used to
	// provide instrumentation.
	InstrumentationLibrary instrumentation.Library
}

SpanSnapshot is a snapshot of a span which contains all the information collected by the span. Its main purpose is exporting completed spans. Although SpanSnapshot fields can be accessed and potentially modified, SpanSnapshot should be treated as immutable. Changes to the span from which the SpanSnapshot was created are NOT reflected in the SpanSnapshot.

type TracerProvider 

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

func NewTracerProvider 

func NewTracerProvider(opts ...TracerProviderOption) *TracerProvider

NewTracerProvider returns a new and configured TracerProvider.

By default the returned TracerProvider is configured with:

  • a ParentBased(AlwaysSample) Sampler
  • a random number IDGenerator
  • the resource.Default() Resource
  • the default SpanLimits.

The passed opts are used to override these default values and configure the returned TracerProvider appropriately.

func (*TracerProvider) ForceFlush 

func (p *TracerProvider) ForceFlush(ctx context.Context) error

ForceFlush immediately exports all spans that have not yet been exported for all the registered span processors.

func (*TracerProvider) RegisterSpanProcessor 

func (p *TracerProvider) RegisterSpanProcessor(s SpanProcessor)

RegisterSpanProcessor adds the given SpanProcessor to the list of SpanProcessors

func (*TracerProvider) Shutdown 

func (p *TracerProvider) Shutdown(ctx context.Context) error

Shutdown shuts down the span processors in the order they were registered.

func (*TracerProvider) Tracer 

func (p *TracerProvider) Tracer(name string, opts ...trace.TracerOption) trace.Tracer

Tracer returns a Tracer with the given name and options. If a Tracer for the given name and options does not exist it is created, otherwise the existing Tracer is returned.

If name is empty, DefaultTracerName is used instead.

This method is safe to be called concurrently.

func (*TracerProvider) UnregisterSpanProcessor 

func (p *TracerProvider) UnregisterSpanProcessor(s SpanProcessor)

UnregisterSpanProcessor removes the given SpanProcessor from the list of SpanProcessors

type TracerProviderConfig 

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

TracerProviderConfig

type TracerProviderOption 

type TracerProviderOption func(*TracerProviderConfig)

func WithBatcher 

func WithBatcher(e SpanExporter, opts ...BatchSpanProcessorOption) TracerProviderOption

WithBatcher registers the exporter with the TracerProvider using a BatchSpanProcessor configured with the passed opts.

func WithIDGenerator 

func WithIDGenerator(g IDGenerator) TracerProviderOption

WithIDGenerator returns a TracerProviderOption that will configure the IDGenerator g as a TracerProvider's IDGenerator. The configured IDGenerator is used by the Tracers the TracerProvider creates to generate new Span and Trace IDs.

If this option is not used, the TracerProvider will use a random number IDGenerator by default.

func WithResource 

func WithResource(r *resource.Resource) TracerProviderOption

WithResource returns a TracerProviderOption that will configure the Resource r as a TracerProvider's Resource. The configured Resource is referenced by all the Tracers the TracerProvider creates. It represents the entity producing telemetry.

If this option is not used, the TracerProvider will use the resource.Default() Resource by default.

func WithSampler 

func WithSampler(s Sampler) TracerProviderOption

WithSampler returns a TracerProviderOption that will configure the Sampler s as a TracerProvider's Sampler. The configured Sampler is used by the Tracers the TracerProvider creates to make their sampling decisions for the Spans they create.

If this option is not used, the TracerProvider will use a ParentBased(AlwaysSample) Sampler by default.

func WithSpanLimits 

func WithSpanLimits(sl SpanLimits) TracerProviderOption

WithSpanLimits returns a TracerProviderOption that will configure the SpanLimits sl as a TracerProvider's SpanLimits. The configured SpanLimits are used used by the Tracers the TracerProvider and the Spans they create to limit tracing resources used.

If this option is not used, the TracerProvider will use the default SpanLimits.

func WithSpanProcessor 

func WithSpanProcessor(sp SpanProcessor) TracerProviderOption

WithSpanProcessor registers the SpanProcessor with a TracerProvider.

func WithSyncer 

func WithSyncer(e SpanExporter) TracerProviderOption

WithSyncer registers the exporter with the TracerProvider using a SimpleSpanProcessor.

Source Files

View all Source files

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.