package trace

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

Index ¶

• Constants
• func ContextWithRemoteSpanContext(ctx context.Context, sc core.SpanContext) context.Context
• func ContextWithSpan(ctx context.Context, span Span) context.Context
• func DefaultHTTPPropagator() propagation.HTTPPropagator
• func RemoteSpanContextFromContext(ctx context.Context) core.SpanContext
• type B3
• func (b3 B3) Extract(ctx context.Context, supplier propagation.HTTPSupplier) context.Context
• func (b3 B3) GetAllKeys() []string
• func (b3 B3) Inject(ctx context.Context, supplier propagation.HTTPSupplier)
• type Decision
• type EndConfig
• type EndOption
• func WithEndTime(t time.Time) EndOption
• type ErrorConfig
• type ErrorOption
• func WithErrorStatus(s codes.Code) ErrorOption
• func WithErrorTime(t time.Time) ErrorOption
• type Link
• type NoopProvider
• func (p NoopProvider) Tracer(name string) Tracer
• type NoopSpan
• func (NoopSpan) AddEvent(ctx context.Context, name string, attrs ...core.KeyValue)
• func (NoopSpan) AddEventWithTimestamp(ctx context.Context, timestamp time.Time, name string, attrs ...core.KeyValue)
• func (NoopSpan) End(options ...EndOption)
• func (NoopSpan) IsRecording() bool
• func (NoopSpan) RecordError(ctx context.Context, err error, opts ...ErrorOption)
• func (NoopSpan) SetAttributes(attributes ...core.KeyValue)
• func (NoopSpan) SetError(v bool)
• func (NoopSpan) SetName(name string)
• func (NoopSpan) SetStatus(status codes.Code, msg string)
• func (NoopSpan) SpanContext() core.SpanContext
• func (NoopSpan) Tracer() Tracer
• type NoopTracer
• func (NoopTracer) Start(ctx context.Context, name string, opts ...StartOption) (context.Context, Span)
• func (t NoopTracer) WithSpan(ctx context.Context, name string, body func(context.Context) error, opts ...StartOption) error
• type Provider
• type Sampler
• func AlwaysOffSampler() Sampler
• func AlwaysOnSampler() Sampler
• type Span
• func SpanFromContext(ctx context.Context) Span
• type SpanKind
• func ValidateSpanKind(spanKind SpanKind) SpanKind
• func (sk SpanKind) String() string
• type StartConfig
• type StartOption
• func LinkedTo(sc core.SpanContext, attrs ...core.KeyValue) StartOption
• func WithAttributes(attrs ...core.KeyValue) StartOption
• func WithNewRoot() StartOption
• func WithRecord() StartOption
• func WithSpanKind(sk SpanKind) StartOption
• func WithStartTime(t time.Time) StartOption
• type TraceContext
• func (tc TraceContext) Extract(ctx context.Context, supplier propagation.HTTPSupplier) context.Context
• func (TraceContext) GetAllKeys() []string
• func (TraceContext) Inject(ctx context.Context, supplier propagation.HTTPSupplier)
• type Tracer

Constants ¶

const (
	B3SingleHeader       = "X-B3"
	B3DebugFlagHeader    = "X-B3-Flags"
	B3TraceIDHeader      = "X-B3-TraceId"
	B3SpanIDHeader       = "X-B3-SpanId"
	B3SampledHeader      = "X-B3-Sampled"
	B3ParentSpanIDHeader = "X-B3-ParentSpanId"
)

Functions ¶

func ContextWithRemoteSpanContext ¶

func ContextWithRemoteSpanContext(ctx context.Context, sc core.SpanContext) context.Context

ContextWithRemoteSpanContext creates a new context with a remote span context set to the passed span context.

func ContextWithSpan ¶

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

ContextWithSpan creates a new context with a current span set to the passed span.

func DefaultHTTPPropagator ¶

func DefaultHTTPPropagator() propagation.HTTPPropagator

DefaultHTTPPropagator returns the default trace HTTP propagator.

func RemoteSpanContextFromContext ¶

func RemoteSpanContextFromContext(ctx context.Context) core.SpanContext

RemoteSpanContextFromContext returns the remote span context stored in the context.

Types ¶

type B3 ¶

type B3 struct {
	SingleHeader bool
}

B3 propagator serializes core.SpanContext to/from B3 Headers. This propagator supports both version of B3 headers,

1. Single Header : X-B3: {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}
2. Multiple Headers: X-B3-TraceId: {TraceId} X-B3-ParentSpanId: {ParentSpanId} X-B3-SpanId: {SpanId} X-B3-Sampled: {SamplingState} X-B3-Flags: {DebugFlag}

If SingleHeader is set to true then X-B3 header is used to inject and extract. Otherwise, separate headers are used to inject and extract.

func (B3) Extract ¶

func (b3 B3) Extract(ctx context.Context, supplier propagation.HTTPSupplier) context.Context

Extract retrieves B3 Headers from the supplier

func (B3) GetAllKeys ¶

func (b3 B3) GetAllKeys() []string

func (B3) Inject ¶

func (b3 B3) Inject(ctx context.Context, supplier propagation.HTTPSupplier)

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 EndConfig ¶

type EndConfig struct {
	EndTime time.Time
}

EndConfig provides options to set properties of span at the time of ending the span.

type EndOption ¶

type EndOption func(*EndConfig)

EndOption applies changes to EndConfig that sets options when the span is ended.

func WithEndTime ¶

func WithEndTime(t time.Time) EndOption

WithEndTime sets the end time of the span to provided time t, when it is ended.

type ErrorConfig ¶

type ErrorConfig struct {
	Timestamp  time.Time
	StatusCode codes.Code
}

ErrorConfig provides options to set properties of an error event at the time it is recorded.

type ErrorOption ¶

type ErrorOption func(*ErrorConfig)

ErrorOption applies changes to ErrorConfig that sets options when an error event is recorded.

func WithErrorStatus ¶

func WithErrorStatus(s codes.Code) ErrorOption

WithErrorStatus indicates the span status that should be set when recording an error event.

func WithErrorTime ¶

func WithErrorTime(t time.Time) ErrorOption

WithErrorTime sets the time at which the error event should be recorded.

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, name string, attrs ...core.KeyValue)

AddEvent does nothing.

func (NoopSpan) AddEventWithTimestamp ¶

func (NoopSpan) AddEventWithTimestamp(ctx context.Context, timestamp time.Time, name 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) RecordError ¶

func (NoopSpan) RecordError(ctx context.Context, err error, opts ...ErrorOption)

RecordError does nothing.

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, msg string)

SetStatus does nothing.

func (NoopSpan) SpanContext ¶

func (NoopSpan) SpanContext() core.SpanContext

SpanContext 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 ...StartOption) (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, opts ...StartOption) 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 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 core.SpanID,
		spanName string,
		spanKind SpanKind,
		attributes []core.KeyValue,
		links []Link,
	) 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 AlwaysOffSampler ¶

func AlwaysOffSampler() Sampler

func AlwaysOnSampler ¶

func AlwaysOnSampler() 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, name string, attrs ...core.KeyValue)
	// AddEventWithTimestamp adds an event with a custom timestamp
	// to the span.
	AddEventWithTimestamp(ctx context.Context, timestamp time.Time, name string, attrs ...core.KeyValue)

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

	// RecordError records an error as a span event.
	RecordError(ctx context.Context, err error, opts ...ErrorOption)

	// 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 in the form of a code
	// and a message.  SetStatus overrides the value of previous
	// calls to SetStatus on the Span.
	//
	// The default span status is OK, so it is not necessary to
	// explicitly set an OK status on successful Spans unless it
	// is to add an OK message or to override a previous status on the Span.
	SetStatus(codes.Code, string)

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

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

func SpanFromContext ¶

func SpanFromContext(ctx context.Context) Span

SpanFromContext returns the current span stored in the context.

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 StartConfig ¶

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

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

type StartOption ¶

type StartOption func(*StartConfig)

StartOption applies changes to StartConfig that sets options at span start time.

func LinkedTo ¶

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

LinkedTo allows instantiating a Span with initial Links.

func WithAttributes ¶

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

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

func WithNewRoot ¶

func WithNewRoot() StartOption

WithNewRoot specifies that the current span or remote span context in context passed to `Start` should be ignored when deciding about a parent, which effectively means creating a span with new trace ID. The current span and the remote span context may be added as links to the span by the implementation.

func WithRecord ¶

func WithRecord() StartOption

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) StartOption

WithSpanKind specifies the role a Span on a Trace.

func WithStartTime ¶

func WithStartTime(t time.Time) StartOption

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 TraceContext ¶

type TraceContext struct{}

TraceContext propagates SpanContext in W3C TraceContext format.

func (TraceContext) Extract ¶

func (tc TraceContext) Extract(ctx context.Context, supplier propagation.HTTPSupplier) context.Context

func (TraceContext) GetAllKeys ¶

func (TraceContext) GetAllKeys() []string

func (TraceContext) Inject ¶

func (TraceContext) Inject(ctx context.Context, supplier propagation.HTTPSupplier)

type Tracer ¶

type Tracer interface {
	// Start a span.
	Start(ctx context.Context, spanName string, opts ...StartOption) (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,
		opts ...StartOption,
	) error
}

Source Files ¶

always_off_sampler.go always_on_sampler.go api.go b3_propagator.go context.go doc.go noop_span.go noop_trace.go noop_trace_provider.go sampler.go trace_context_propagator.go

Directories ¶