trace

package module
v1.7.0 Latest Latest
Warning

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

 Go to latest Published: Apr 28, 2022 License: Apache-2.0 Imports: 10 Imported by: 7,548

Documentation

Overview

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

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 = TraceFlags(0x01)
)

Variables

This section is empty.

Functions

func ContextWithRemoteSpanContext 

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

ContextWithRemoteSpanContext returns a copy of parent with rsc set explicly as a remote SpanContext and as the current Span. The Span implementation that wraps rsc is non-recording and performs no operations other than to return rsc as the SpanContext from the SpanContext method.

func ContextWithSpan 

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

ContextWithSpan returns a copy of parent with span set as the current Span.

func ContextWithSpanContext added in v0.20.0 

func ContextWithSpanContext(parent context.Context, sc SpanContext) context.Context

ContextWithSpanContext returns a copy of parent with sc as the current Span. The Span implementation that wraps sc is non-recording and performs no operations other than to return sc as the SpanContext from the SpanContext method.

Types

type EventConfig added in v1.0.0 

type EventConfig struct {
	// contains filtered or unexported fields
}

EventConfig is a group of options for an Event.

func NewEventConfig 

func NewEventConfig(options ...EventOption) EventConfig

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

func (*EventConfig) Attributes added in v1.0.0 

func (cfg *EventConfig) Attributes() []attribute.KeyValue

Attributes describe the associated qualities of an Event.

func (*EventConfig) StackTrace added in v1.0.0 

func (cfg *EventConfig) StackTrace() bool

StackTrace checks whether stack trace capturing is enabled.

func (*EventConfig) Timestamp added in v1.0.0 

func (cfg *EventConfig) Timestamp() time.Time

Timestamp is a time in an Event life-cycle.

type EventOption 

type EventOption interface {
	// contains filtered or unexported methods
}

EventOption applies span event options to an EventConfig. 

type Link struct {
	// SpanContext of the linked Span.
	SpanContext SpanContext

	// Attributes describe the aspects of the link.
	Attributes []attribute.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.

func LinkFromContext added in v1.0.0 

func LinkFromContext(ctx context.Context, attrs ...attribute.KeyValue) Link

LinkFromContext returns a link encapsulating the SpanContext in the provided ctx.

type Span 

type Span interface {
	// 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 ...SpanEndOption)

	// 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 will record err as an exception span event for this span. An
	// additional call to SetStatus is required if the Status of the Span should
	// be set to Error, as this method does not change the Span status. If this
	// span is not being recorded or err is nil then this method does nothing.
	RecordError(err error, options ...EventOption)

	// SpanContext returns the SpanContext of the Span. The returned SpanContext
	// is usable even after the End method has been called for the Span.
	SpanContext() SpanContext

	// SetStatus sets the status of the Span in the form of a code and a
	// description, overriding previous values set. The description is only
	// included in a status when the code is for an error.
	SetStatus(code codes.Code, description 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 ...attribute.KeyValue)

	// TracerProvider returns a TracerProvider that can be used to generate
	// additional Spans on the same telemetry pipeline as the current Span.
	TracerProvider() TracerProvider
}

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.

Warning: methods may be added to this interface in minor releases.

func SpanFromContext 

func SpanFromContext(ctx context.Context) Span

SpanFromContext returns the current Span from ctx.

If no Span is currently set in ctx an implementation of a Span that performs no operations is returned.

type SpanConfig 

type SpanConfig struct {
	// contains filtered or unexported fields
}

SpanConfig is a group of options for a Span.

func NewSpanEndConfig added in v1.0.0 

func NewSpanEndConfig(options ...SpanEndOption) SpanConfig

NewSpanEndConfig 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.

func NewSpanStartConfig added in v1.0.0 

func NewSpanStartConfig(options ...SpanStartOption) SpanConfig

NewSpanStartConfig 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.

func (*SpanConfig) Attributes 

func (cfg *SpanConfig) Attributes() []attribute.KeyValue

Attributes describe the associated qualities of a Span. 

func (cfg *SpanConfig) Links() []Link

Links are the associations a Span has with other Spans.

func (*SpanConfig) NewRoot 

func (cfg *SpanConfig) NewRoot() 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.

func (*SpanConfig) SpanKind 

func (cfg *SpanConfig) SpanKind() SpanKind

SpanKind is the role a Span has in a trace.

func (*SpanConfig) StackTrace added in v1.0.0 

func (cfg *SpanConfig) StackTrace() bool

StackTrace checks whether stack trace capturing is enabled.

func (*SpanConfig) Timestamp 

func (cfg *SpanConfig) Timestamp() time.Time

Timestamp is a time in a Span life-cycle.

type SpanContext 

type SpanContext struct {
	// contains filtered or unexported fields
}

SpanContext contains identifying trace information about a Span.

func NewSpanContext added in v0.19.0 

func NewSpanContext(config SpanContextConfig) SpanContext

NewSpanContext constructs a SpanContext using values from the provided SpanContextConfig.

func SpanContextFromContext 

func SpanContextFromContext(ctx context.Context) SpanContext

SpanContextFromContext returns the current Span's SpanContext.

func (SpanContext) Equal added in v0.19.0 

func (sc SpanContext) Equal(other SpanContext) bool

Equal is a predicate that determines whether two SpanContext values are equal.

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) IsRemote added in v0.19.0 

func (sc SpanContext) IsRemote() bool

IsRemote indicates whether the SpanContext represents a remotely-created Span.

func (SpanContext) IsSampled 

func (sc SpanContext) IsSampled() bool

IsSampled returns if the sampling bit is set in the SpanContext's TraceFlags.

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.

func (SpanContext) MarshalJSON added in v0.19.0 

func (sc SpanContext) MarshalJSON() ([]byte, error)

MarshalJSON implements a custom marshal function to encode a SpanContext.

func (SpanContext) SpanID 

func (sc SpanContext) SpanID() SpanID

SpanID returns the SpanID from the SpanContext.

func (SpanContext) TraceFlags 

func (sc SpanContext) TraceFlags() TraceFlags

TraceFlags returns the flags from the SpanContext.

func (SpanContext) TraceID 

func (sc SpanContext) TraceID() TraceID

TraceID returns the TraceID from the SpanContext.

func (SpanContext) TraceState 

func (sc SpanContext) TraceState() TraceState

TraceState returns the TraceState from the SpanContext.

func (SpanContext) WithRemote added in v0.19.0 

func (sc SpanContext) WithRemote(remote bool) SpanContext

WithRemote returns a copy of sc with the Remote property set to remote.

func (SpanContext) WithSpanID added in v0.19.0 

func (sc SpanContext) WithSpanID(spanID SpanID) SpanContext

WithSpanID returns a new SpanContext with the SpanID replaced.

func (SpanContext) WithTraceFlags added in v0.19.0 

func (sc SpanContext) WithTraceFlags(flags TraceFlags) SpanContext

WithTraceFlags returns a new SpanContext with the TraceFlags replaced.

func (SpanContext) WithTraceID added in v0.19.0 

func (sc SpanContext) WithTraceID(traceID TraceID) SpanContext

WithTraceID returns a new SpanContext with the TraceID replaced.

func (SpanContext) WithTraceState added in v0.19.0 

func (sc SpanContext) WithTraceState(state TraceState) SpanContext

WithTraceState returns a new SpanContext with the TraceState replaced.

type SpanContextConfig added in v0.19.0 

type SpanContextConfig struct {
	TraceID    TraceID
	SpanID     SpanID
	TraceFlags TraceFlags
	TraceState TraceState
	Remote     bool
}

SpanContextConfig contains mutable fields usable for constructing an immutable SpanContext.

type SpanEndEventOption added in v1.0.0 

type SpanEndEventOption interface {
	SpanEndOption
	EventOption
}

SpanEndEventOption are options that can be used at the end of a span, or with an event.

func WithStackTrace added in v1.0.0 

func WithStackTrace(b bool) SpanEndEventOption

WithStackTrace sets the flag to capture the error with stack trace (e.g. true, false).

type SpanEndOption added in v1.0.0 

type SpanEndOption interface {
	// contains filtered or unexported methods
}

SpanEndOption applies an option to a SpanConfig. These options are applicable only when the span is ended.

type SpanEventOption added in v1.0.0 

type SpanEventOption interface {
	SpanOption
	EventOption
}

SpanEventOption are options that can be used with an event or a span.

func WithTimestamp 

func WithTimestamp(t time.Time) SpanEventOption

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

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 {
	SpanStartOption
	SpanEndOption
}

SpanOption are options that can be used at both the beginning and end of a span.

type SpanStartEventOption added in v1.0.0 

type SpanStartEventOption interface {
	SpanStartOption
	EventOption
}

SpanStartEventOption are options that can be used at the start of a span, or with an event.

func WithAttributes 

func WithAttributes(attributes ...attribute.KeyValue) SpanStartEventOption

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.

type SpanStartOption added in v1.0.0 

type SpanStartOption interface {
	// contains filtered or unexported methods
}

SpanStartOption applies an option to a SpanConfig. These options are applicable only when the span is created. 

func WithLinks(links ...Link) SpanStartOption

WithLinks adds links to a Span. The links are added to the existing Span links, i.e. this does not overwrite. Links with invalid span context are ignored.

func WithNewRoot 

func WithNewRoot() SpanStartOption

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 WithSpanKind 

func WithSpanKind(kind SpanKind) SpanStartOption

WithSpanKind sets the SpanKind of a Span.

type TraceFlags added in v0.20.0 

type TraceFlags byte //nolint:revive // revive complains about stutter of `trace.TraceFlags`.

TraceFlags contains flags that can be set on a SpanContext.

func (TraceFlags) IsSampled added in v0.20.0 

func (tf TraceFlags) IsSampled() bool

IsSampled returns if the sampling bit is set in the TraceFlags.

func (TraceFlags) MarshalJSON added in v0.20.0 

func (tf TraceFlags) MarshalJSON() ([]byte, error)

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

func (TraceFlags) String added in v0.20.0 

func (tf TraceFlags) String() string

String returns the hex string representation form of TraceFlags.

func (TraceFlags) WithSampled added in v0.20.0 

func (tf TraceFlags) WithSampled(sampled bool) TraceFlags

WithSampled sets the sampling bit in a new copy of the TraceFlags.

type TraceID 

type TraceID [16]byte

TraceID is a unique identity of a trace. nolint:revive // revive complains about stutter of `trace.TraceID`.

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:revive // revive complains about stutter of `trace.TraceIDFromHex`.

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 TraceState 

type TraceState struct {
	// contains filtered or unexported fields
}

TraceState provides additional vendor-specific trace identification information across different distributed tracing systems. It represents an immutable list consisting of key/value pairs, each pair is referred to as a list-member.

TraceState conforms to the W3C Trace Context specification (https://www.w3.org/TR/trace-context-1). All operations that create or copy a TraceState do so by validating all input and will only produce TraceState that conform to the specification. Specifically, this means that all list-member's key/value pairs are valid, no duplicate list-members exist, and the maximum number of list-members (32) is not exceeded.

func ParseTraceState added in v1.0.0 

func ParseTraceState(tracestate string) (TraceState, error)

ParseTraceState attempts to decode a TraceState from the passed string. It returns an error if the input is invalid according to the W3C Trace Context specification.

func (TraceState) Delete 

func (ts TraceState) Delete(key string) TraceState

Delete returns a copy of the TraceState with the list-member identified by key removed.

func (TraceState) Get 

func (ts TraceState) Get(key string) string

Get returns the value paired with key from the corresponding TraceState list-member if it exists, otherwise an empty string is returned.

func (TraceState) Insert 

func (ts TraceState) Insert(key, value string) (TraceState, error)

Insert adds a new list-member defined by the key/value pair to the TraceState. If a list-member already exists for the given key, that list-member's value is updated. The new or updated list-member is always moved to the beginning of the TraceState as specified by the W3C Trace Context specification.

If key or value are invalid according to the W3C Trace Context specification an error is returned with the original TraceState.

If adding a new list-member means the TraceState would have more members then is allowed, the new list-member will be inserted and the right-most list-member will be dropped in the returned TraceState.

func (TraceState) Len added in v1.0.0 

func (ts TraceState) Len() int

Len returns the number of list-members in the TraceState.

func (TraceState) MarshalJSON 

func (ts TraceState) MarshalJSON() ([]byte, error)

MarshalJSON marshals the TraceState into JSON.

func (TraceState) String 

func (ts TraceState) String() string

String encodes the TraceState into a string compliant with the W3C Trace Context specification. The returned string will be invalid if the TraceState contains any invalid members.

type Tracer 

type Tracer interface {
	// Start creates a span and a context.Context containing the newly-created span.
	//
	// If the context.Context provided in `ctx` contains a Span then the newly-created
	// Span will be a child of that span, otherwise it will be a root span. This behavior
	// can be overridden by providing `WithNewRoot()` as a SpanOption, causing the
	// newly-created Span to be a root span even if `ctx` contains a Span.
	//
	// When creating a Span it is recommended to provide all known span attributes using
	// the `WithAttributes()` SpanOption as samplers will only have access to the
	// attributes provided when a Span is created.
	//
	// Any Span that is created MUST also be ended. This is the responsibility of the user.
	// Implementations of this API may leak memory or other resources if Spans are not ended.
	Start(ctx context.Context, spanName string, opts ...SpanStartOption) (context.Context, Span)
}

Tracer is the creator of Spans.

Warning: methods may be added to this interface in minor releases.

type TracerConfig 

type TracerConfig struct {
	// contains filtered or unexported fields
}

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.

func (*TracerConfig) InstrumentationVersion 

func (t *TracerConfig) InstrumentationVersion() string

InstrumentationVersion returns the version of the library providing instrumentation.

func (*TracerConfig) SchemaURL added in v1.0.0 

func (t *TracerConfig) SchemaURL() string

SchemaURL returns the Schema URL of the telemetry emitted by the Tracer.

type TracerOption 

type TracerOption interface {
	// contains filtered or unexported methods
}

TracerOption applies an option to a TracerConfig.

func WithInstrumentationVersion 

func WithInstrumentationVersion(version string) TracerOption

WithInstrumentationVersion sets the instrumentation version.

func WithSchemaURL added in v1.0.0 

func WithSchemaURL(schemaURL string) TracerOption

WithSchemaURL sets the schema URL for the 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.
	//
	// This method must be concurrency safe.
	Tracer(instrumentationName string, opts ...TracerOption) Tracer
}

TracerProvider provides access to instrumentation Tracers.

Warning: methods may be added to this interface in minor releases.

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.