trace

package
v1.33.0 Latest Latest
Warning

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

 Go to latest Published: Dec 12, 2024 License: Apache-2.0 Imports: 28 Imported by: 4,712

README

SDK Trace

PkgGoDev

Documentation

Overview

Package trace contains support for OpenTelemetry distributed tracing.

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

Index

Examples

Constants

View Source 
const (
	DefaultMaxQueueSize       = 2048
	DefaultScheduleDelay      = 5000
	DefaultExportTimeout      = 30000
	DefaultMaxExportBatchSize = 512
)

Defaults for BatchSpanProcessorOptions.

View Source 
const (
	// DefaultAttributeValueLengthLimit is the default maximum allowed
	// attribute value length, unlimited.
	DefaultAttributeValueLengthLimit = -1

	// DefaultAttributeCountLimit is the default maximum number of attributes
	// a span can have.
	DefaultAttributeCountLimit = 128

	// DefaultEventCountLimit is the default maximum number of events a span
	// can have.
	DefaultEventCountLimit = 128

	// DefaultLinkCountLimit is the default maximum number of links a span can
	// have.
	DefaultLinkCountLimit = 128

	// DefaultAttributePerEventCountLimit is the default maximum number of
	// attributes a span event can have.
	DefaultAttributePerEventCountLimit = 128

	// DefaultAttributePerLinkCountLimit is the default maximum number of
	// attributes a span link can have.
	DefaultAttributePerLinkCountLimit = 128
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BatchSpanProcessorOption 

type BatchSpanProcessorOption func(o *BatchSpanProcessorOptions)

BatchSpanProcessorOption configures a BatchSpanProcessor.

func WithBatchTimeout 

func WithBatchTimeout(delay time.Duration) BatchSpanProcessorOption

WithBatchTimeout returns a BatchSpanProcessorOption that configures the maximum delay allowed for a BatchSpanProcessor before it will export any held span (whether the queue is full or not).

func WithBlocking 

func WithBlocking() BatchSpanProcessorOption

WithBlocking returns a BatchSpanProcessorOption that configures a BatchSpanProcessor to wait for enqueue operations to succeed instead of dropping data when the queue is full.

func WithExportTimeout added in v0.20.0 

func WithExportTimeout(timeout time.Duration) BatchSpanProcessorOption

WithExportTimeout returns a BatchSpanProcessorOption that configures the amount of time a BatchSpanProcessor waits for an exporter to export before abandoning the export.

func WithMaxExportBatchSize 

func WithMaxExportBatchSize(size int) BatchSpanProcessorOption

WithMaxExportBatchSize returns a BatchSpanProcessorOption that configures the maximum export batch size allowed for a BatchSpanProcessor.

func WithMaxQueueSize 

func WithMaxQueueSize(size int) BatchSpanProcessorOption

WithMaxQueueSize returns a BatchSpanProcessorOption that configures the maximum queue size allowed for a BatchSpanProcessor.

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
}

BatchSpanProcessorOptions is configuration settings for a BatchSpanProcessor.

type Event added in v1.0.0 

type Event struct {
	// Name is the name of this event
	Name string

	// Attributes describe the aspects of the event.
	Attributes []attribute.KeyValue

	// DroppedAttributeCount is the number of attributes that were not
	// recorded due to configured limits being reached.
	DroppedAttributeCount int

	// Time at which this event was recorded.
	Time time.Time
}

Event is a thing that happened during a Span's lifetime.

type IDGenerator added in v0.15.0 

type IDGenerator interface {

	// NewIDs returns a new trace and span ID.
	NewIDs(ctx context.Context) (trace.TraceID, trace.SpanID)

	// NewSpanID returns a ID for a new span in the trace with traceID.
	NewSpanID(ctx context.Context, traceID trace.TraceID) trace.SpanID
}

IDGenerator allows custom generators for TraceID and SpanID. 

type Link struct {
	// SpanContext of the linked Span.
	SpanContext trace.SpanContext

	// Attributes describe the aspects of the link.
	Attributes []attribute.KeyValue

	// DroppedAttributeCount is the number of attributes that were not
	// recorded due to configured limits being reached.
	DroppedAttributeCount int
}

Link is the relationship between two Spans. The relationship can be within the same Trace or across different Traces.

type ParentBasedSamplerOption added in v0.12.0 

type ParentBasedSamplerOption interface {
	// contains filtered or unexported methods
}

ParentBasedSamplerOption configures the sampler for a particular sampling case.

func WithLocalParentNotSampled added in v0.12.0 

func WithLocalParentNotSampled(s Sampler) ParentBasedSamplerOption

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

func WithLocalParentSampled added in v0.12.0 

func WithLocalParentSampled(s Sampler) ParentBasedSamplerOption

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

func WithRemoteParentNotSampled added in v0.12.0 

func WithRemoteParentNotSampled(s Sampler) ParentBasedSamplerOption

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

func WithRemoteParentSampled added in v0.12.0 

func WithRemoteParentSampled(s Sampler) ParentBasedSamplerOption

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

type ReadOnlySpan added in v0.16.0 

type ReadOnlySpan interface {
	// Name returns the name of the span.
	Name() string
	// SpanContext returns the unique SpanContext that identifies the span.
	SpanContext() trace.SpanContext
	// Parent returns the unique SpanContext that identifies the parent of the
	// span if one exists. If the span has no parent the returned SpanContext
	// will be invalid.
	Parent() trace.SpanContext
	// SpanKind returns the role the span plays in a Trace.
	SpanKind() trace.SpanKind
	// StartTime returns the time the span started recording.
	StartTime() time.Time
	// EndTime returns the time the span stopped recording. It will be zero if
	// the span has not ended.
	EndTime() time.Time
	// Attributes returns the defining attributes of the span.
	// The order of the returned attributes is not guaranteed to be stable across invocations.
	Attributes() []attribute.KeyValue
	// Links returns all the links the span has to other spans.
	Links() []Link
	// Events returns all the events that occurred within in the spans
	// lifetime.
	Events() []Event
	// Status returns the spans status.
	Status() Status
	// InstrumentationScope returns information about the instrumentation
	// scope that created the span.
	InstrumentationScope() instrumentation.Scope
	// InstrumentationLibrary returns information about the instrumentation
	// library that created the span.
	// Deprecated: please use InstrumentationScope instead.
	InstrumentationLibrary() instrumentation.Library //nolint:staticcheck // This method needs to be define for backwards compatibility
	// Resource returns information about the entity that produced the span.
	Resource() *resource.Resource
	// DroppedAttributes returns the number of attributes dropped by the span
	// due to limits being reached.
	DroppedAttributes() int
	// DroppedLinks returns the number of links dropped by the span due to
	// limits being reached.
	DroppedLinks() int
	// DroppedEvents returns the number of events dropped by the span due to
	// limits being reached.
	DroppedEvents() int
	// ChildSpanCount returns the count of spans that consider the span a
	// direct parent.
	ChildSpanCount() int
	// 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.

Warning: methods may be added to this interface in minor releases.

type ReadWriteSpan added in v0.16.0 

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.

Warning: methods may be added to this interface in minor releases.

type Sampler 

type Sampler interface {

	// ShouldSample returns a SamplingResult based on a decision made from the
	// passed parameters.
	ShouldSample(parameters SamplingParameters) SamplingResult

	// Description returns information describing the Sampler.
	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 added in v0.12.0 

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

ParentBased returns a sampler decorator which behaves differently, based on the parent of the span. If the span has no parent, the decorated 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 added in v0.12.0 

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 added in v0.20.0 

type SpanExporter interface {

	// ExportSpans exports a batch of spans.
	//
	// 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, spans []ReadOnlySpan) error

	// Shutdown notifies the exporter of a pending halt to operations. The
	// exporter is expected to perform 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 spans to external receivers. This is the final component in the trace export pipeline.

type SpanLimits added in v0.18.0 

type SpanLimits struct {
	// AttributeValueLengthLimit is the maximum allowed attribute value length.
	//
	// This limit only applies to string and string slice attribute values.
	// Any string longer than this value will be truncated to this length.
	//
	// Setting this to a negative value means no limit is applied.
	AttributeValueLengthLimit int

	// AttributeCountLimit is the maximum allowed span attribute count. Any
	// attribute added to a span once this limit is reached will be dropped.
	//
	// Setting this to zero means no attributes will be recorded.
	//
	// Setting this to a negative value means no limit is applied.
	AttributeCountLimit int

	// EventCountLimit is the maximum allowed span event count. Any event
	// added to a span once this limit is reached means it will be added but
	// the oldest event will be dropped.
	//
	// Setting this to zero means no events we be recorded.
	//
	// Setting this to a negative value means no limit is applied.
	EventCountLimit int

	// LinkCountLimit is the maximum allowed span link count. Any link added
	// to a span once this limit is reached means it will be added but the
	// oldest link will be dropped.
	//
	// Setting this to zero means no links we be recorded.
	//
	// Setting this to a negative value means no limit is applied.
	LinkCountLimit int

	// AttributePerEventCountLimit is the maximum number of attributes allowed
	// per span event. Any attribute added after this limit reached will be
	// dropped.
	//
	// Setting this to zero means no attributes will be recorded for events.
	//
	// Setting this to a negative value means no limit is applied.
	AttributePerEventCountLimit int

	// AttributePerLinkCountLimit is the maximum number of attributes allowed
	// per span link. Any attribute added after this limit reached will be
	// dropped.
	//
	// Setting this to zero means no attributes will be recorded for links.
	//
	// Setting this to a negative value means no limit is applied.
	AttributePerLinkCountLimit int
}

SpanLimits represents the limits of a span.

func NewSpanLimits added in v1.5.0 

func NewSpanLimits() SpanLimits

NewSpanLimits returns a SpanLimits with all limits set to the value their corresponding environment variable holds, or the default if unset.

• AttributeValueLengthLimit: OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT (default: unlimited)

• AttributeCountLimit: OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT (default: 128)

• EventCountLimit: OTEL_SPAN_EVENT_COUNT_LIMIT (default: 128)

• AttributePerEventCountLimit: OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT (default: 128)

• LinkCountLimit: OTEL_SPAN_LINK_COUNT_LIMIT (default: 128)

• AttributePerLinkCountLimit: OTEL_LINK_ATTRIBUTE_COUNT_LIMIT (default: 128)

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.

Example (Annotated) 
package main

import (
	"context"
	"fmt"

	"go.opentelemetry.io/otel/attribute"
)

/*
Sometimes information about a runtime environment can change dynamically or be
delayed from startup. Instead of continuously recreating and distributing a
TracerProvider with an immutable Resource or delaying the startup of your
application on a slow-loading piece of information, annotate the created spans
dynamically using a SpanProcessor.
*/

var (
	// owner represents the owner of the application. In this example it is
	// stored as a simple string, but in real-world use this may be the
	// response to an asynchronous request.
	owner    = "unknown"
	ownerKey = attribute.Key("owner")
)

// Annotator is a SpanProcessor that adds attributes to all started spans.
type Annotator struct {
	// AttrsFunc is called when a span is started. The attributes it returns
	// are set on the Span being started.
	AttrsFunc func() []attribute.KeyValue
}

func (a Annotator) OnStart(_ context.Context, s ReadWriteSpan) { s.SetAttributes(a.AttrsFunc()...) }
func (a Annotator) Shutdown(context.Context) error             { return nil }
func (a Annotator) ForceFlush(context.Context) error           { return nil }
func (a Annotator) OnEnd(s ReadOnlySpan) {
	attr := s.Attributes()[0]
	fmt.Printf("%s: %s\n", attr.Key, attr.Value.AsString())
}

func main() {
	a := Annotator{
		AttrsFunc: func() []attribute.KeyValue {
			return []attribute.KeyValue{ownerKey.String(owner)}
		},
	}
	tracer := NewTracerProvider(WithSpanProcessor(a)).Tracer("annotated")

	// Simulate the situation where we want to annotate spans with an owner,
	// but at startup we do not now this information. Instead of waiting for
	// the owner to be known before starting and blocking here, start doing
	// work and update when the information becomes available.
	ctx := context.Background()
	_, s0 := tracer.Start(ctx, "span0")

	// Simulate an asynchronous call to determine the owner succeeding. We now
	// know that the owner of this application has been determined to be
	// Alice. Make sure all subsequent spans are annotated appropriately.
	owner = "alice"

	_, s1 := tracer.Start(ctx, "span1")
	s0.End()
	s1.End()

}

Output:

owner: unknown
owner: alice
Example (Filtered) 
package main

import (
	"context"
	"time"
)

// DurationFilter is a SpanProcessor that filters spans that have lifetimes
// outside of a defined range.
type DurationFilter struct {
	// Next is the next SpanProcessor in the chain.
	Next SpanProcessor

	// Min is the duration under which spans are dropped.
	Min time.Duration
	// Max is the duration over which spans are dropped.
	Max time.Duration
}

func (f DurationFilter) OnStart(parent context.Context, s ReadWriteSpan) {
	f.Next.OnStart(parent, s)
}
func (f DurationFilter) Shutdown(ctx context.Context) error   { return f.Next.Shutdown(ctx) }
func (f DurationFilter) ForceFlush(ctx context.Context) error { return f.Next.ForceFlush(ctx) }
func (f DurationFilter) OnEnd(s ReadOnlySpan) {
	if f.Min > 0 && s.EndTime().Sub(s.StartTime()) < f.Min {
		// Drop short lived spans.
		return
	}
	if f.Max > 0 && s.EndTime().Sub(s.StartTime()) > f.Max {
		// Drop long lived spans.
		return
	}
	f.Next.OnEnd(s)
}

// InstrumentationBlacklist is a SpanProcessor that drops all spans from
// certain instrumentation.
type InstrumentationBlacklist struct {
	// Next is the next SpanProcessor in the chain.
	Next SpanProcessor

	// Blacklist is the set of instrumentation names for which spans will be
	// dropped.
	Blacklist map[string]bool
}

func (f InstrumentationBlacklist) OnStart(parent context.Context, s ReadWriteSpan) {
	f.Next.OnStart(parent, s)
}
func (f InstrumentationBlacklist) Shutdown(ctx context.Context) error { return f.Next.Shutdown(ctx) }
func (f InstrumentationBlacklist) ForceFlush(ctx context.Context) error {
	return f.Next.ForceFlush(ctx)
}

func (f InstrumentationBlacklist) OnEnd(s ReadOnlySpan) {
	if f.Blacklist != nil && f.Blacklist[s.InstrumentationScope().Name] {
		// Drop spans from this instrumentation
		return
	}
	f.Next.OnEnd(s)
}

type noopExporter struct{}

func (noopExporter) ExportSpans(context.Context, []ReadOnlySpan) error { return nil }
func (noopExporter) Shutdown(context.Context) error                    { return nil }

func main() {
	exportSP := NewSimpleSpanProcessor(noopExporter{})

	// Build a SpanProcessor chain to filter out all spans from the pernicious
	// "naughty-instrumentation" dependency and only allow spans shorter than
	// an minute and longer than a second to be exported with the exportSP.
	filter := DurationFilter{
		Next: InstrumentationBlacklist{
			Next: exportSP,
			Blacklist: map[string]bool{
				"naughty-instrumentation": true,
			},
		},
		Min: time.Second,
		Max: time.Minute,
	}

	_ = NewTracerProvider(WithSpanProcessor(filter))
	// ...
}

Output:

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 perform no action.

func NewSimpleSpanProcessor 

func NewSimpleSpanProcessor(exporter SpanExporter) SpanProcessor

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

This SpanProcessor is not recommended for production use. The synchronous nature of this SpanProcessor makes it good for testing, debugging, or showing examples of other features, but it will be slow and have a high computation resource usage overhead. The BatchSpanProcessor is recommended for production use instead.

type Status added in v1.0.0 

type Status struct {
	// Code is an identifier of a Spans state classification.
	Code codes.Code
	// Description is a user hint about why that status was set. It is only
	// applicable when Code is Error.
	Description string
}

Status is the classified state of a Span.

type TracerProvider added in v0.12.0 

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

TracerProvider is an OpenTelemetry TracerProvider. It provides Tracers to instrumentation so it can trace operational flow through a system.

func NewTracerProvider added in v0.12.0 

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 added in v0.19.0 

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 added in v0.12.0 

func (p *TracerProvider) RegisterSpanProcessor(sp SpanProcessor)

RegisterSpanProcessor adds the given SpanProcessor to the list of SpanProcessors.

func (*TracerProvider) Shutdown added in v0.14.0 

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

Shutdown shuts down TracerProvider. All registered span processors are shut down in the order they were registered and any held computational resources are released. After Shutdown is called, all methods are no-ops.

func (*TracerProvider) Tracer added in v0.12.0 

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 added in v0.12.0 

func (p *TracerProvider) UnregisterSpanProcessor(sp SpanProcessor)

UnregisterSpanProcessor removes the given SpanProcessor from the list of SpanProcessors.

type TracerProviderOption added in v0.12.0 

type TracerProviderOption interface {
	// contains filtered or unexported methods
}

TracerProviderOption configures a TracerProvider.

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 added in v0.15.0 

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 WithRawSpanLimits added in v1.5.0 

func WithRawSpanLimits(limits SpanLimits) TracerProviderOption

WithRawSpanLimits returns a TracerProviderOption that configures a TracerProvider to use these limits. These limits bound any Span created by a Tracer from the TracerProvider.

The limits will be used as-is. Zero or negative values will not be changed to the default value like WithSpanLimits does. Setting a limit to zero will effectively disable the related resource it limits and setting to a negative value will mean that resource is unlimited. Consequentially, this means that the zero-value SpanLimits will disable all span resources. Because of this, limits should be constructed using NewSpanLimits and updated accordingly.

If this or WithSpanLimits are not provided, the TracerProvider will use the limits defined by environment variables, or the defaults if unset. Refer to the NewSpanLimits documentation for information about this relationship.

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 added in v0.19.0 

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.

This option overrides the Sampler configured through the OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG environment variables. If this option is not used and the sampler is not configured through environment variables or the environment contains invalid/unsupported configuration, the TracerProvider will use a ParentBased(AlwaysSample) Sampler by default.

func WithSpanLimits deprecated added in v0.19.0 

func WithSpanLimits(sl SpanLimits) TracerProviderOption

WithSpanLimits returns a TracerProviderOption that configures a TracerProvider to use the SpanLimits sl. These SpanLimits bound any Span created by a Tracer from the TracerProvider.

If any field of sl is zero or negative it will be replaced with the default value for that field.

If this or WithRawSpanLimits are not provided, the TracerProvider will use the limits defined by environment variables, or the defaults if unset. Refer to the NewSpanLimits documentation for information about this relationship.

Deprecated: Use WithRawSpanLimits instead which allows setting unlimited and zero limits. This option will be kept until the next major version incremented release.

func WithSpanProcessor added in v0.12.0 

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.

This is not recommended for production use. The synchronous nature of the SimpleSpanProcessor that will wrap the exporter make it good for testing, debugging, or showing examples of other feature, but it will be slow and have a high computation resource usage overhead. The WithBatcher option is recommended for production use instead.

Source Files

View all Source files

Directories

Path Synopsis
Package tracetest is a testing helper package for the SDK.
 Package tracetest is a testing helper package for the SDK.

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.