trace

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Nov 20, 2020 License: Apache-2.0 Imports: 7 Imported by: 7,557

Documentation

Overview

Package trace provides an implementation of the tracing part of the OpenTelemetry API.

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.

To participate in distributed traces a Span needs to be created for the operation being performed as part of a traced workflow. It its simplest form: 

var tracer trace.Tracer

func init() {
	tracer = otel.Tracer("instrumentation/package/name")
}

func operation(ctx context.Context) {
	var span trace.Span
	ctx, span = tracer.Start(ctx, "operation")
	defer span.End()
	// ...
}

A Tracer is unique to the instrumentation and is used to create Spans. Instrumentation should be designed to accept a TracerProvider from which it can create its own unique Tracer. Alternatively, the registered global TracerProvider from the go.opentelemetry.io/otel package can be used as a default. 

const (
	name    = "instrumentation/package/name"
	version = "0.1.0"
)

type Instrumentation struct {
	tracer trace.Tracer
}

func NewInstrumentation(tp trace.TracerProvider) *Instrumentation {
	if tp == nil {
		tp = otel.TracerProvider()
	}
	return &Instrumentation{
		tracer: tp.Tracer(name, trace.WithInstrumentationVersion(version)),
	}
}

func operation(ctx context.Context, inst *Instrumentation) {
	var span trace.Span
	ctx, span = inst.tracer.Start(ctx, "operation")
	defer span.End()
	// ...
}

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

Variables

This section is empty.

Functions

func ContextWithRemoteSpanContext 

func ContextWithRemoteSpanContext(parent context.Context, remote SpanContext) context.Context

ContextWithRemoteSpanContext returns a copy of parent with a remote set as the remote span context.

func ContextWithSpan 

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

ContextWithSpan returns a copy of parent with span set to current.

Types

type EventOption 

type EventOption interface {
	ApplyEvent(*SpanConfig)
}

EventOption applies span event options to a SpanConfig.

type InstrumentationOption 

type InstrumentationOption interface {
	TracerOption
}

InstrumentationOption is an interface for applying instrumentation specific options.

func WithInstrumentationVersion 

func WithInstrumentationVersion(version string) InstrumentationOption

WithInstrumentationVersion sets the instrumentation version.

type LifeCycleOption 

type LifeCycleOption interface {
	SpanOption
	EventOption
}

LifeCycleOption applies span life-cycle options to a SpanConfig. These options set values releated to events in a spans life-cycle like starting, ending, experiencing an error and other user defined notable events.

func WithAttributes 

func WithAttributes(attributes ...label.KeyValue) LifeCycleOption

WithAttributes adds the attributes related to a span life-cycle event. These attributes are used to describe the work a Span represents when this option is provided to a Span's start or end events. Otherwise, these attributes provide additional information about the event being recorded (e.g. error, state change, processing progress, system event).

If multiple of these options are passed the attributes of each successive option will extend the attributes instead of overwriting. There is no guarantee of uniqueness in the resulting attributes.

func WithTimestamp 

func WithTimestamp(t time.Time) LifeCycleOption

WithTimestamp sets the time of a Span life-cycle moment (e.g. started, stopped, errored). 

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

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

For example, a Link is used in the following situations:

  1. Batch Processing: A batch of operations may contain operations associated with one or more traces/spans. Since there can only be one parent SpanContext, a Link is used to keep reference to the SpanContext of all operations in the batch.
  2. Public Endpoint: A SpanContext for an in incoming client request on a public endpoint should be considered untrusted. In such a case, a new trace with its own identity and sampling decision needs to be created, but this new trace needs to be related to the original trace in some form. A Link is used to keep reference to the original SpanContext and track the relationship.

type Span 

type Span interface {
	// Tracer returns the Tracer that created the Span. Tracer MUST NOT be
	// nil.
	Tracer() Tracer

	// End completes the Span. The Span is considered complete and ready to be
	// delivered through the rest of the telemetry pipeline after this method
	// is called. Therefore, updates to the Span are not allowed after this
	// method has been called.
	End(options ...SpanOption)

	// AddEvent adds an event with the provided name and options.
	AddEvent(name string, options ...EventOption)

	// IsRecording returns the recording state of the Span. It will return
	// true if the Span is active and events can be recorded.
	IsRecording() bool

	// RecordError records an error as a Span event.
	RecordError(err error, options ...EventOption)

	// SpanContext returns the SpanContext of the Span. The returned
	// SpanContext is usable even after the End has been called for the Span.
	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.
	SetStatus(code codes.Code, msg string)

	// SetName sets the Span name.
	SetName(name string)

	// SetAttributes sets kv as attributes of the Span. If a key from kv
	// already exists for an attribute of the Span it will be overwritten with
	// the value contained in kv.
	SetAttributes(kv ...label.KeyValue)
}

Span is the individual component of a trace. It represents a single named and timed operation of a workflow that is traced. A Tracer is used to create a Span and it is then up to the operation the Span represents to properly end the Span when the operation itself ends.

func SpanFromContext 

func SpanFromContext(ctx context.Context) Span

SpanFromContext returns the current span from ctx, or noop span if none set.

type SpanConfig 

type SpanConfig struct {
	// Attributes describe the associated qualities of a Span.
	Attributes []label.KeyValue
	// Timestamp is a time in a Span life-cycle.
	Timestamp time.Time
	// Links are the associations a Span has with other Spans.
	Links []Link
	// Record is the recording state of a Span.
	Record bool
	// NewRoot identifies a Span as the root Span for a new trace. This is
	// commonly used when an existing trace crosses trust boundaries and the
	// remote parent span context should be ignored for security.
	NewRoot bool
	// SpanKind is the role a Span has in a trace.
	SpanKind SpanKind
}

SpanConfig is a group of options for a Span.

func NewEventConfig 

func NewEventConfig(options ...EventOption) *SpanConfig

NewEventConfig applies all the EventOptions to a returned SpanConfig. If no timestamp option is passed, the returned SpanConfig will have a Timestamp set to the call time, otherwise no validation is performed on the returned SpanConfig.

func NewSpanConfig 

func NewSpanConfig(options ...SpanOption) *SpanConfig

NewSpanConfig applies all the options to a returned SpanConfig. No validation is performed on the returned SpanConfig (e.g. no uniqueness checking or bounding of data), it is left to the SDK to perform this action.

type SpanContext 

type SpanContext struct {
	TraceID    TraceID
	SpanID     SpanID
	TraceFlags byte
}

SpanContext contains identifying trace information about a Span.

func RemoteSpanContextFromContext 

func RemoteSpanContextFromContext(ctx context.Context) SpanContext

RemoteSpanContextFromContext returns the remote span context from ctx.

func SpanContextFromContext 

func SpanContextFromContext(ctx context.Context) SpanContext

SpanContextFromContext returns the current SpanContext from ctx, or an empty SpanContext if none set.

func (SpanContext) HasSpanID 

func (sc SpanContext) HasSpanID() bool

HasSpanID checks if the SpanContext has a valid SpanID.

func (SpanContext) HasTraceID 

func (sc SpanContext) HasTraceID() bool

HasTraceID checks if the SpanContext has a valid TraceID.

func (SpanContext) IsDebug 

func (sc SpanContext) IsDebug() bool

IsDebug returns if the debug bit is set in the trace flags.

func (SpanContext) IsDeferred 

func (sc SpanContext) IsDeferred() bool

IsDeferred returns if the deferred bit is set in the trace flags.

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 returns if the SpanContext is valid. A valid span context has a valid TraceID and SpanID.

type SpanID 

type SpanID [8]byte

SpanID is a unique identity 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 SpanID is valid. A valid SpanID 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 is the role a Span plays in a Trace. 

const (
	// SpanKindUnspecified is an unspecified SpanKind and is not a valid
	// SpanKind. SpanKindUnspecified should be replaced with SpanKindInternal
	// if it is received.
	SpanKindUnspecified SpanKind = 0
	// SpanKindInternal is a SpanKind for a Span that represents an internal
	// operation within an application.
	SpanKindInternal SpanKind = 1
	// SpanKindServer is a SpanKind for a Span that represents the operation
	// of handling a request from a client.
	SpanKindServer SpanKind = 2
	// SpanKindClient is a SpanKind for a Span that represents the operation
	// of client making a request to a server.
	SpanKindClient SpanKind = 3
	// SpanKindProducer is a SpanKind for a Span that represents the operation
	// of a producer sending a message to a message broker. Unlike
	// SpanKindClient and SpanKindServer, there is often no direct
	// relationship between this kind of Span and a SpanKindConsumer kind. A
	// SpanKindProducer Span will end once the message is accepted by the
	// message broker which might not overlap with the processing of that
	// message.
	SpanKindProducer SpanKind = 4
	// SpanKindConsumer is a SpanKind for a Span that represents the operation
	// of a consumer receiving a message from a message broker. Like
	// SpanKindProducer Spans, there is often no direct relationship between
	// this Span and the Span that produced the message.
	SpanKindConsumer SpanKind = 5
)

As a convenience, these match the proto definition, see https://github.com/open-telemetry/opentelemetry-proto/blob/30d237e1ff3ab7aa50e0922b5bebdd93505090af/opentelemetry/proto/trace/v1/trace.proto#L101-L129

The unspecified value is not a valid `SpanKind`. Use `ValidateSpanKind()` to coerce a span kind to a valid value.

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 interface {
	ApplySpan(*SpanConfig)
}

SpanOption applies an option to a SpanConfig. 

func WithLinks(links ...Link) SpanOption

WithLinks adds links to a Span. The links are added to the existing Span links, i.e. this does not overwrite.

func WithNewRoot 

func WithNewRoot() SpanOption

WithNewRoot specifies that the Span should be treated as a root Span. Any existing parent span context will be ignored when defining the Span's trace identifiers.

func WithRecord 

func WithRecord() SpanOption

WithRecord specifies that the span should be recorded. It is important to note that implementations may override this option, i.e. if the span is a child of an un-sampled trace.

func WithSpanKind 

func WithSpanKind(kind SpanKind) SpanOption

WithSpanKind sets the SpanKind of a Span.

type TraceID 

type TraceID [16]byte

TraceID is a unique identity of a trace. nolint:golint

func TraceIDFromHex 

func TraceIDFromHex(h string) (TraceID, error)

TraceIDFromHex 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 nolint:golint

func (TraceID) IsValid 

func (t TraceID) IsValid() bool

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

func (TraceID) MarshalJSON 

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

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

func (TraceID) String 

func (t TraceID) String() string

String returns the hex string representation form of a TraceID

type Tracer 

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

Tracer is the creator of Spans.

type TracerConfig 

type TracerConfig struct {
	// InstrumentationVersion is the version of the library providing
	// instrumentation.
	InstrumentationVersion string
}

TracerConfig is a group of options for a Tracer.

func NewTracerConfig 

func NewTracerConfig(options ...TracerOption) *TracerConfig

NewTracerConfig applies all the options to a returned TracerConfig.

type TracerOption 

type TracerOption interface {
	ApplyTracer(*TracerConfig)
}

TracerOption applies an option to a TracerConfig.

type TracerProvider 

type TracerProvider 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
}

TracerProvider provides access to instrumentation Tracers.

func NewNoopTracerProvider 

func NewNoopTracerProvider() TracerProvider

NewNoopTracerProvider returns an implementation of TracerProvider that performs no operations. The Tracer and Spans created from the returned TracerProvider also perform no operations.

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.