trace

package
v0.0.0-...-a1b153e Latest Latest
Warning

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

 Go to latest Published: Jun 7, 2021 License: Apache-2.0 Imports: 12 Imported by: 2

Documentation

Index

Constants

View Source 
const (
	// FlagsSampled is a bitmask with the sampled bit set. A SpanContext
	// with the sampling bit set means the span is sampled.
	FlagsSampled = byte(0x01)
	// FlagsDeferred is a bitmask with the deferred bit set. A SpanContext
	// with the deferred bit set means the sampling decision has been
	// defered to the receiver.
	FlagsDeferred = byte(0x02)
	// FlagsDebug is a bitmask with the debug bit set.
	FlagsDebug = byte(0x04)

	ErrInvalidHexID errorConst = "trace-id and span-id can only contain [0-9a-f] characters, all lowercase"

	ErrInvalidTraceIDLength errorConst = "hex encoded trace-id must have length equals to 32"
	ErrNilTraceID           errorConst = "trace-id can't be all zero"

	ErrInvalidSpanIDLength errorConst = "hex encoded span-id must have length equals to 16"
	ErrNilSpanID           errorConst = "span-id can't be all zero"
)

Variables

This section is empty.

Functions

func ContextWithRemoteSpanContext 

func ContextWithRemoteSpanContext(ctx context.Context, sc 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.

Types

type B3 

type B3 struct {
	// InjectEncoding are the B3 encodings used when injecting trace
	// information. If no encoding is specified (i.e. `B3Unspecified`)
	// `B3MultipleHeader` will be used as the default.
	InjectEncoding B3Encoding
}

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

  1. Single Header: 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}

func (B3) Extract 

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

Extract extracts a context from the supplier if it contains B3 headers.

func (B3) GetAllKeys 

func (b3 B3) GetAllKeys() []string

func (B3) Inject 

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

Inject injects a context into the supplier as B3 headers. The parent span ID is omitted because it is not tracked in the SpanContext.

type B3Encoding 

type B3Encoding uint8

B3Encoding is a bitmask representation of the B3 encoding type. 

const (
	// B3MultipleHeader is a B3 encoding that uses multiple headers to
	// transmit tracing information all prefixed with `x-b3-`.
	B3MultipleHeader B3Encoding = 1 << iota
	// B3SingleHeader is a B3 encoding that uses a single header named `b3`
	// to transmit tracing information.
	B3SingleHeader
	// B3Unspecified is an unspecified B3 encoding.
	B3Unspecified B3Encoding = 0
)

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 []kv.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 ID 

type ID [16]byte

ID is a unique identity of a trace.

func IDFromHex 

func IDFromHex(h string) (ID, error)

IDFromHex returns a TraceID from a hex string if it is compliant with the w3c trace-context specification. See more at https://www.w3.org/TR/trace-context/#trace-id

func (ID) IsValid 

func (t ID) IsValid() bool

IsValid checks whether the trace ID is valid. A valid trace ID does not consist of zeros only.

func (ID) MarshalJSON 

func (t ID) MarshalJSON() ([]byte, error)

MarshalJSON implements a custom marshal function to encode TraceID as a hex string.

func (ID) String 

func (t ID) String() string

String returns the hex string representation form of a TraceID 

type Link struct {
	SpanContext
	Attributes []kv.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(_ string, _ ...TracerOption) Tracer

Tracer returns noop implementation of Tracer.

type NoopSpan 

type NoopSpan struct {
}

func (NoopSpan) AddEvent 

func (NoopSpan) AddEvent(ctx context.Context, name string, attrs ...kv.KeyValue)

AddEvent does nothing.

func (NoopSpan) AddEventWithTimestamp 

func (NoopSpan) AddEventWithTimestamp(ctx context.Context, timestamp time.Time, name string, attrs ...kv.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) SetAttribute 

func (NoopSpan) SetAttribute(k string, v interface{})

SetAttribute does nothing.

func (NoopSpan) SetAttributes 

func (NoopSpan) SetAttributes(attributes ...kv.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() 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 an implementation of the Tracer interface.
	// The instrumentationName must be the name of the library providing
	// instrumentation. This name may be the same as the instrumented code
	// only if that code provides built-in instrumentation. If the
	// instrumentationName is empty, then a implementation defined default
	// name will be used instead.
	Tracer(instrumentationName string, opts ...TracerOption) 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 SpanContext,
		remote bool,
		traceID ID,
		spanName string,
		spanKind SpanKind,
		attributes []kv.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 ...kv.KeyValue)
	// AddEventWithTimestamp adds an event with a custom timestamp
	// to the span.
	AddEventWithTimestamp(ctx context.Context, timestamp time.Time, name string, attrs ...kv.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() 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(...kv.KeyValue)

	// Set singular span attribute, with type inference.
	SetAttribute(string, interface{})
}

func SpanFromContext 

func SpanFromContext(ctx context.Context) Span

SpanFromContext returns the current span stored in the context.

type SpanContext 

type SpanContext struct {
	TraceID    ID
	SpanID     SpanID
	TraceFlags byte
}

SpanContext contains basic information about the span - its trace ID, span ID and trace flags.

func EmptySpanContext 

func EmptySpanContext() SpanContext

EmptySpanContext is meant for internal use to return invalid span context during error conditions.

func RemoteSpanContextFromContext 

func RemoteSpanContextFromContext(ctx context.Context) SpanContext

RemoteSpanContextFromContext returns the remote span context stored in the context.

func (SpanContext) HasSpanID 

func (sc SpanContext) HasSpanID() bool

HasSpanID checks if the span context has a valid span ID.

func (SpanContext) HasTraceID 

func (sc SpanContext) HasTraceID() bool

HasTraceID checks if the span context has a valid trace ID.

func (SpanContext) IsSampled 

func (sc SpanContext) IsSampled() bool

IsSampled returns if the sampling bit is set in the trace flags.

func (SpanContext) IsValid 

func (sc SpanContext) IsValid() bool

IsValid checks if the span context is valid. A valid span context has a valid trace ID and a valid span ID.

type SpanID 

type SpanID [8]byte

SpanID is a unique identify of a span in a trace.

func SpanIDFromHex 

func SpanIDFromHex(h string) (SpanID, error)

SpanIDFromHex returns a SpanID from a hex string if it is compliant with the w3c trace-context specification. See more at https://www.w3.org/TR/trace-context/#parent-id

func (SpanID) IsValid 

func (s SpanID) IsValid() bool

IsValid checks whether the span ID is valid. A valid span ID does not consist of zeros only.

func (SpanID) MarshalJSON 

func (s SpanID) MarshalJSON() ([]byte, error)

MarshalJSON implements a custom marshal function to encode SpanID as a hex string.

func (SpanID) String 

func (s SpanID) String() string

String returns the hex string representation form of a SpanID

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 []kv.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 SpanContext, attrs ...kv.KeyValue) StartOption

LinkedTo allows instantiating a Span with initial Links.

func WithAttributes 

func WithAttributes(attrs ...kv.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
}

type TracerConfig 

type TracerConfig struct {
	InstrumentationVersion string
}

TracerConfig contains options for a Tracer.

type TracerOption 

type TracerOption func(*TracerConfig)

TracerOption configures a TracerConfig option.

func WithInstrumentationVersion 

func WithInstrumentationVersion(version string) TracerOption

WithInstrumentationVersion sets the instrumentation version for a Tracer.

Source Files

View all Source files

Directories

Path Synopsis

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.