package trace

import "go.opentelemetry.io/otel/api/trace"

Index ¶

• func SetCurrentSpan(ctx context.Context, span Span) context.Context
• type Decision
• type EndOption
• func WithEndTime(endTime time.Time) EndOption
• type EndOptions
• type Link
• type NoopProvider
• func (p NoopProvider) Tracer(name string) Tracer
• type NoopSpan
• func (NoopSpan) AddEvent(ctx context.Context, msg string, attrs ...core.KeyValue)
• func (NoopSpan) AddEventWithTimestamp(ctx context.Context, timestamp time.Time, msg string, attrs ...core.KeyValue)
• func (NoopSpan) End(options ...EndOption)
• func (NoopSpan) IsRecording() bool
• func (NoopSpan) SetAttributes(attributes ...core.KeyValue)
• func (NoopSpan) SetError(v bool)
• func (NoopSpan) SetName(name string)
• func (NoopSpan) SetStatus(status codes.Code)
• func (NoopSpan) SpanContext() core.SpanContext
• func (NoopSpan) Tracer() Tracer
• type NoopTracer
• func (NoopTracer) Start(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)
• func (t NoopTracer) WithSpan(ctx context.Context, name string, body func(context.Context) error) error
• type Provider
• type Relation
• type RelationshipType
• type Sampler
• func AlwaysSampleSampler() Sampler
• func NeverSampleSampler() Sampler
• type Span
• func CurrentSpan(ctx context.Context) Span
• type SpanKind
• func ValidateSpanKind(spanKind SpanKind) SpanKind
• func (sk SpanKind) String() string
• type SpanOption
• func ChildOf(sc core.SpanContext) SpanOption
• func FollowsFrom(sc core.SpanContext) SpanOption
• func LinkedTo(sc core.SpanContext, attrs ...core.KeyValue) SpanOption
• func WithAttributes(attrs ...core.KeyValue) SpanOption
• func WithRecord() SpanOption
• func WithSpanKind(sk SpanKind) SpanOption
• func WithStartTime(t time.Time) SpanOption
• type SpanOptions
• type Tracer

Functions ¶

func SetCurrentSpan ¶

func SetCurrentSpan(ctx context.Context, span Span) context.Context

Types ¶

type Decision ¶

type Decision struct {
	// Sampled is set true if the span should be sampled.
	Sampled bool

	// Attributes provides insight into Sample	r's decision process.
	// It could be empty slice or nil if no attributes are recorded by the sampler.
	Attributes []core.KeyValue
}

type EndOption ¶

type EndOption func(*EndOptions)

func WithEndTime ¶

func WithEndTime(endTime time.Time) EndOption

type EndOptions ¶

type EndOptions struct {
	EndTime time.Time
}

type Link ¶

type Link struct {
	core.SpanContext
	Attributes []core.KeyValue
}

Link is used to establish relationship between two spans within the same Trace or across different Traces. Few examples of Link usage.

1. Batch Processing: A batch of elements may contain elements associated with one or more traces/spans. Since there can only be one parent SpanContext, Link is used to keep reference to SpanContext of all elements in the batch.
2. Public Endpoint: A SpanContext in incoming client request on a public endpoint is untrusted from service provider perspective. In such case it is advisable to start a new trace with appropriate sampling decision. However, it is desirable to associate incoming SpanContext to new trace initiated on service provider side so two traces (from Client and from Service Provider) can be correlated.

type NoopProvider ¶

type NoopProvider struct{}

func (NoopProvider) Tracer ¶

func (p NoopProvider) Tracer(name string) Tracer

Tracer returns noop implementation of Tracer.

type NoopSpan ¶

type NoopSpan struct {
}

func (NoopSpan) AddEvent ¶

func (NoopSpan) AddEvent(ctx context.Context, msg string, attrs ...core.KeyValue)

AddEvent does nothing.

func (NoopSpan) AddEventWithTimestamp ¶

func (NoopSpan) AddEventWithTimestamp(ctx context.Context, timestamp time.Time, msg string, attrs ...core.KeyValue)

AddEventWithTimestamp does nothing.

func (NoopSpan) End ¶

func (NoopSpan) End(options ...EndOption)

End does nothing.

func (NoopSpan) IsRecording ¶

func (NoopSpan) IsRecording() bool

IsRecording always returns false for NoopSpan.

func (NoopSpan) SetAttributes ¶

func (NoopSpan) SetAttributes(attributes ...core.KeyValue)

SetAttributes does nothing.

func (NoopSpan) SetError ¶

func (NoopSpan) SetError(v bool)

SetError does nothing.

func (NoopSpan) SetName ¶

func (NoopSpan) SetName(name string)

SetName does nothing.

func (NoopSpan) SetStatus ¶

func (NoopSpan) SetStatus(status codes.Code)

SetStatus does nothing.

func (NoopSpan) SpanContext ¶

func (NoopSpan) SpanContext() core.SpanContext

SpancContext returns an invalid span context.

func (NoopSpan) Tracer ¶

func (NoopSpan) Tracer() Tracer

Tracer returns noop implementation of Tracer.

type NoopTracer ¶

type NoopTracer struct{}

func (NoopTracer) Start ¶

func (NoopTracer) Start(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span)

Start starts a noop span.

func (NoopTracer) WithSpan ¶

func (t NoopTracer) WithSpan(ctx context.Context, name string, body func(context.Context) error) error

WithSpan wraps around execution of func with noop span.

type Provider ¶

type Provider interface {
	// Tracer creates a named tracer that implements Tracer interface.
	// If the name is an empty string then provider uses default name.
	Tracer(name string) Tracer
}

type Relation ¶

type Relation struct {
	core.SpanContext
	RelationshipType
}

Relation is used to establish relationship between newly created span and the other span. The other span could be related as a parent or linked or any other future relationship type.

type RelationshipType ¶

type RelationshipType int

const (
	ChildOfRelationship RelationshipType = iota
	FollowsFromRelationship
)

type Sampler ¶

type Sampler interface {
	// ShouldSample returns a Decision that contains a decision whether to sample
	// or not sample the span to be created. Decision is based on a Sampler specific
	// algorithm that takes into account one or more input parameters.
	ShouldSample(
		sc core.SpanContext,
		remote bool,
		traceID core.TraceID,
		spanID uint64,
		spanName string,
	) Decision

	// Description returns of the sampler. It contains its name or short description
	// and its configured properties.
	// For example 'ProbabilitySampler:{0.00001}'
	Description() string
}

func AlwaysSampleSampler ¶

func AlwaysSampleSampler() Sampler

func NeverSampleSampler ¶

func NeverSampleSampler() Sampler

type Span ¶

type Span interface {
	// Tracer returns tracer used to create this span. Tracer cannot be nil.
	Tracer() Tracer

	// End completes the span. No updates are allowed to span after it
	// ends. The only exception is setting status of the span.
	End(options ...EndOption)

	// AddEvent adds an event to the span.
	AddEvent(ctx context.Context, msg string, attrs ...core.KeyValue)
	// AddEventWithTimestamp adds an event with a custom timestamp
	// to the span.
	AddEventWithTimestamp(ctx context.Context, timestamp time.Time, msg string, attrs ...core.KeyValue)

	// IsRecording returns true if the span is active and recording events is enabled.
	IsRecording() bool

	// SpanContext returns span context of the span. Returned SpanContext is usable
	// even after the span ends.
	SpanContext() core.SpanContext

	// SetStatus sets the status of the span. The status of the span can be updated
	// even after span ends.
	SetStatus(codes.Code)

	// SetName sets the name of the span.
	SetName(name string)

	// Set span attributes
	SetAttributes(...core.KeyValue)
}

func CurrentSpan ¶

func CurrentSpan(ctx context.Context) Span

type SpanKind ¶

type SpanKind int

SpanKind represents the role of a Span inside a Trace. Often, this defines how a Span will be processed and visualized by various backends.

const (
	// As a convenience, these match the proto definition, see
	// opentelemetry/proto/trace/v1/trace.proto
	//
	// The unspecified value is not a valid `SpanKind`.  Use
	// `ValidateSpanKind()` to coerce a span kind to a valid
	// value.
	SpanKindUnspecified SpanKind = 0
	SpanKindInternal    SpanKind = 1
	SpanKindServer      SpanKind = 2
	SpanKindClient      SpanKind = 3
	SpanKindProducer    SpanKind = 4
	SpanKindConsumer    SpanKind = 5
)

func ValidateSpanKind ¶

func ValidateSpanKind(spanKind SpanKind) SpanKind

ValidateSpanKind returns a valid span kind value. This will coerce invalid values into the default value, SpanKindInternal.

func (SpanKind) String ¶

func (sk SpanKind) String() string

String returns the specified name of the SpanKind in lower-case.

type SpanOption ¶

type SpanOption func(*SpanOptions)

SpanOption apply changes to SpanOptions.

func ChildOf ¶

func ChildOf(sc core.SpanContext) SpanOption

ChildOf. TODO: do we need this?.

func FollowsFrom ¶

func FollowsFrom(sc core.SpanContext) SpanOption

FollowsFrom. TODO: do we need this?.

func LinkedTo ¶

func LinkedTo(sc core.SpanContext, attrs ...core.KeyValue) SpanOption

LinkedTo allows instantiating a Span with initial Links.

func WithAttributes ¶

func WithAttributes(attrs ...core.KeyValue) SpanOption

WithAttributes sets attributes to span. These attributes provides additional data about the span. Multiple `WithAttributes` options appends the attributes preserving the order.

func WithRecord ¶

func WithRecord() SpanOption

WithRecord specifies that the span should be recorded. Note that the implementation may still override this preference, e.g., if the span is a child in an unsampled trace.

func WithSpanKind ¶

func WithSpanKind(sk SpanKind) SpanOption

WithSpanKind specifies the role a Span on a Trace.

func WithStartTime ¶

func WithStartTime(t time.Time) SpanOption

WithStartTime sets the start time of the span to provided time t, when it is started. In absence of this option, wall clock time is used as start time. This option is typically used when starting of the span is delayed.

type SpanOptions ¶

type SpanOptions struct {
	Attributes []core.KeyValue
	StartTime  time.Time
	Links      []Link
	Relation   Relation
	Record     bool
	SpanKind   SpanKind
}

SpanOptions provides options to set properties of span at the time of starting a new span.

type Tracer ¶

type Tracer interface {
	// Start a span.
	Start(ctx context.Context, spanName string, startOpts ...SpanOption) (context.Context, Span)

	// WithSpan wraps the execution of the fn function with a span.
	// It starts a new span, sets it as an active span in the context,
	// executes the fn function and closes the span before returning the result of fn.
	WithSpan(
		ctx context.Context,
		spanName string,
		fn func(ctx context.Context) error,
	) error
}

Source Files ¶

always_sampler.go api.go current.go doc.go never_sampler.go noop_span.go noop_trace.go noop_trace_provider.go sampler.go