Documentation

Overview

    Package trace provides tracing support.

    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.

        Types

        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.

          Most users will use the error options instead.

          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 []label.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 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 ...SpanOption)
                            
                            	// AddEvent adds an event to the span.
                            	AddEvent(ctx context.Context, name string, attrs ...label.KeyValue)
                            	// AddEventWithTimestamp adds an event with a custom timestamp
                            	// to the span.
                            	AddEventWithTimestamp(ctx context.Context, timestamp time.Time, name string, attrs ...label.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(code codes.Code, msg string)
                            
                            	// SetName sets the name of the span.
                            	SetName(name string)
                            
                            	// Set span attributes
                            	SetAttributes(kv ...label.KeyValue)
                            }

                            func SpanFromContext

                            func SpanFromContext(ctx context.Context) Span

                              SpanFromContext returns the current span stored in the context.

                              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.

                                Most users will use span options instead.

                                func NewSpanConfig

                                func NewSpanConfig(opts ...SpanOption) *SpanConfig

                                  NewSpanConfig applies all the options to a returned SpanConfig. The default value for all the fields of the returned SpanConfig are the default zero value of the type. Also, this does not perform any validation on the returned SpanConfig (e.g. no uniqueness checking or bounding of data). Instead, it is left to the implementations of the SDK to perform this action.

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

                                                                    type SpanOption interface {
                                                                    	Apply(*SpanConfig)
                                                                    }

                                                                      SpanOption applies an option to a SpanConfig.

                                                                      func WithAttributes

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

                                                                        WithAttributes adds the attributes to a span. These attributes are meant to provide additional information about the work the Span represents. The attributes are added to the existing Span attributes, i.e. this does not overwrite.

                                                                        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.

                                                                                func WithTimestamp

                                                                                func WithTimestamp(t time.Time) SpanOption

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

                                                                                  type Tracer

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

                                                                                  type TracerConfig

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

                                                                                    TracerConfig is a group of options for a Tracer.

                                                                                    Most users will use the tracer options instead.

                                                                                    func NewTracerConfig

                                                                                    func NewTracerConfig(opts ...TracerOption) *TracerConfig

                                                                                      NewTracerConfig applies all the options to a returned TracerConfig. The default value for all the fields of the returned TracerConfig are the default zero value of the type. Also, this does not perform any validation on the returned TracerConfig (e.g. no uniqueness checking or bounding of data), instead it is left to the implementations of the SDK to perform this action.

                                                                                      type TracerOption

                                                                                      type TracerOption interface {
                                                                                      	Apply(*TracerConfig)
                                                                                      }

                                                                                        TracerOption applies an options to a TracerConfig.

                                                                                        func WithInstrumentationVersion

                                                                                        func WithInstrumentationVersion(version string) TracerOption

                                                                                          WithInstrumentationVersion sets the instrumentation version for a Tracer.

                                                                                          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 NoopTracerProvider

                                                                                            func NoopTracerProvider() TracerProvider

                                                                                              NoopTracerProvider returns a noop implementation of TracerProvider. The Tracer and Spans created from the noop provider will also be noop.

                                                                                              Directories

                                                                                              Path Synopsis
                                                                                              Package tracetest provides testing utilities for tracing.
                                                                                              Package tracetest provides testing utilities for tracing.