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)
)
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(parent context.Context, span Span) context.Context
ContextWithSpan returns a copy of parent with span set as the current Span.
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.
EventConfig is a group of options for an Event.
type EventConfig struct {
// contains filtered or unexported fields
}
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 (cfg *EventConfig) Attributes() []attribute.KeyValue
Attributes describe the associated qualities of an Event.
func (cfg *EventConfig) StackTrace() bool
StackTrace checks whether stack trace capturing is enabled.
func (cfg *EventConfig) Timestamp() time.Time
Timestamp is a time in an Event life-cycle.
EventOption applies span event options to an EventConfig.
type EventOption interface {
// contains filtered or unexported methods
}
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:
type Link struct {
// SpanContext of the linked Span.
SpanContext SpanContext
// Attributes describe the aspects of the link.
Attributes []attribute.KeyValue
}
func LinkFromContext(ctx context.Context, attrs ...attribute.KeyValue) Link
LinkFromContext returns a link encapsulating the SpanContext in the provided ctx.
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. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.
type Span interface {
// Users of the interface can ignore this. This embedded type is only used
// by implementations of this interface. See the "API Implementations"
// section of the package documentation for more information.
embedded.Span
// 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, provided the status hasn't already been set to a higher
// value before (OK > Error > Unset). 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
}
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.
SpanConfig is a group of options for a Span.
type SpanConfig struct {
// contains filtered or unexported fields
}
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(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 (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 (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 (cfg *SpanConfig) SpanKind() SpanKind
SpanKind is the role a Span has in a trace.
func (cfg *SpanConfig) StackTrace() bool
StackTrace checks whether stack trace capturing is enabled.
func (cfg *SpanConfig) Timestamp() time.Time
Timestamp is a time in a Span life-cycle.
SpanContext contains identifying trace information about a Span.
type SpanContext struct {
// contains filtered or unexported fields
}
func NewSpanContext(config SpanContextConfig) SpanContext
NewSpanContext constructs a SpanContext using values from the provided SpanContextConfig.
func SpanContextFromContext(ctx context.Context) SpanContext
SpanContextFromContext returns the current Span's SpanContext.
func (sc SpanContext) Equal(other SpanContext) bool
Equal is a predicate that determines whether two SpanContext values are equal.
func (sc SpanContext) HasSpanID() bool
HasSpanID checks if the SpanContext has a valid SpanID.
func (sc SpanContext) HasTraceID() bool
HasTraceID checks if the SpanContext has a valid TraceID.
func (sc SpanContext) IsRemote() bool
IsRemote indicates whether the SpanContext represents a remotely-created Span.
func (sc SpanContext) IsSampled() bool
IsSampled returns if the sampling bit is set in the SpanContext's TraceFlags.
func (sc SpanContext) IsValid() bool
IsValid returns if the SpanContext is valid. A valid span context has a valid TraceID and SpanID.
func (sc SpanContext) MarshalJSON() ([]byte, error)
MarshalJSON implements a custom marshal function to encode a SpanContext.
func (sc SpanContext) SpanID() SpanID
SpanID returns the SpanID from the SpanContext.
func (sc SpanContext) TraceFlags() TraceFlags
TraceFlags returns the flags from the SpanContext.
func (sc SpanContext) TraceID() TraceID
TraceID returns the TraceID from the SpanContext.
func (sc SpanContext) TraceState() TraceState
TraceState returns the TraceState from the SpanContext.
func (sc SpanContext) WithRemote(remote bool) SpanContext
WithRemote returns a copy of sc with the Remote property set to remote.
func (sc SpanContext) WithSpanID(spanID SpanID) SpanContext
WithSpanID returns a new SpanContext with the SpanID replaced.
func (sc SpanContext) WithTraceFlags(flags TraceFlags) SpanContext
WithTraceFlags returns a new SpanContext with the TraceFlags replaced.
func (sc SpanContext) WithTraceID(traceID TraceID) SpanContext
WithTraceID returns a new SpanContext with the TraceID replaced.
func (sc SpanContext) WithTraceState(state TraceState) SpanContext
WithTraceState returns a new SpanContext with the TraceState replaced.
SpanContextConfig contains mutable fields usable for constructing an immutable SpanContext.
type SpanContextConfig struct {
TraceID TraceID
SpanID SpanID
TraceFlags TraceFlags
TraceState TraceState
Remote bool
}
SpanEndEventOption are options that can be used at the end of a span, or with an event.
type SpanEndEventOption interface {
SpanEndOption
EventOption
}
func WithStackTrace(b bool) SpanEndEventOption
WithStackTrace sets the flag to capture the error with stack trace (e.g. true, false).
SpanEndOption applies an option to a SpanConfig. These options are applicable only when the span is ended.
type SpanEndOption interface {
// contains filtered or unexported methods
}
SpanEventOption are options that can be used with an event or a span.
type SpanEventOption interface {
SpanOption
EventOption
}
func WithTimestamp(t time.Time) SpanEventOption
WithTimestamp sets the time of a Span or Event life-cycle moment (e.g. started, stopped, errored).
SpanID is a unique identity of a span in a trace.
type SpanID [8]byte
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 (s SpanID) IsValid() bool
IsValid checks whether the SpanID is valid. A valid SpanID does not consist of zeros only.
func (s SpanID) MarshalJSON() ([]byte, error)
MarshalJSON implements a custom marshal function to encode SpanID as a hex string.
func (s SpanID) String() string
String returns the hex string representation form of a SpanID.
SpanKind is the role a Span plays in a Trace.
type SpanKind int
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.
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
)
func ValidateSpanKind(spanKind SpanKind) SpanKind
ValidateSpanKind returns a valid span kind value. This will coerce invalid values into the default value, SpanKindInternal.
func (sk SpanKind) String() string
String returns the specified name of the SpanKind in lower-case.
SpanOption are options that can be used at both the beginning and end of a span.
type SpanOption interface {
SpanStartOption
SpanEndOption
}
SpanStartEventOption are options that can be used at the start of a span, or with an event.
type SpanStartEventOption interface {
SpanStartOption
EventOption
}
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.
SpanStartOption applies an option to a SpanConfig. These options are applicable only when the span is created.
type SpanStartOption interface {
// contains filtered or unexported methods
}
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() 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(kind SpanKind) SpanStartOption
WithSpanKind sets the SpanKind of a Span.
TraceFlags contains flags that can be set on a SpanContext.
type TraceFlags byte //nolint:revive // revive complains about stutter of `trace.TraceFlags`.
func (tf TraceFlags) IsSampled() bool
IsSampled returns if the sampling bit is set in the TraceFlags.
func (tf TraceFlags) MarshalJSON() ([]byte, error)
MarshalJSON implements a custom marshal function to encode TraceFlags as a hex string.
func (tf TraceFlags) String() string
String returns the hex string representation form of TraceFlags.
func (tf TraceFlags) WithSampled(sampled bool) TraceFlags
WithSampled sets the sampling bit in a new copy of the TraceFlags.
TraceID is a unique identity of a trace. nolint:revive // revive complains about stutter of `trace.TraceID`.
type TraceID [16]byte
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 (t TraceID) IsValid() bool
IsValid checks whether the trace TraceID is valid. A valid trace ID does not consist of zeros only.
func (t TraceID) MarshalJSON() ([]byte, error)
MarshalJSON implements a custom marshal function to encode TraceID as a hex string.
func (t TraceID) String() string
String returns the hex string representation form of a TraceID.
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.
type TraceState struct {
// contains filtered or unexported fields
}
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 (ts TraceState) Delete(key string) TraceState
Delete returns a copy of the TraceState with the list-member identified by key removed.
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 (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 (ts TraceState) Len() int
Len returns the number of list-members in the TraceState.
func (ts TraceState) MarshalJSON() ([]byte, error)
MarshalJSON marshals the TraceState into JSON.
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.
Tracer is the creator of Spans.
Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.
type Tracer interface {
// Users of the interface can ignore this. This embedded type is only used
// by implementations of this interface. See the "API Implementations"
// section of the package documentation for more information.
embedded.Tracer
// 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)
}
TracerConfig is a group of options for a Tracer.
type TracerConfig struct {
// contains filtered or unexported fields
}
func NewTracerConfig(options ...TracerOption) TracerConfig
NewTracerConfig applies all the options to a returned TracerConfig.
func (t *TracerConfig) InstrumentationAttributes() attribute.Set
InstrumentationAttributes returns the attributes associated with the library providing instrumentation.
func (t *TracerConfig) InstrumentationVersion() string
InstrumentationVersion returns the version of the library providing instrumentation.
func (t *TracerConfig) SchemaURL() string
SchemaURL returns the Schema URL of the telemetry emitted by the Tracer.
TracerOption applies an option to a TracerConfig.
type TracerOption interface {
// contains filtered or unexported methods
}
func WithInstrumentationAttributes(attr ...attribute.KeyValue) TracerOption
WithInstrumentationAttributes sets the instrumentation attributes.
The passed attributes will be de-duplicated.
func WithInstrumentationVersion(version string) TracerOption
WithInstrumentationVersion sets the instrumentation version.
func WithSchemaURL(schemaURL string) TracerOption
WithSchemaURL sets the schema URL for the Tracer.
TracerProvider provides Tracers that are used by instrumentation code to trace computational workflows.
A TracerProvider is the collection destination of all Spans from Tracers it provides, it represents a unique telemetry collection pipeline. How that pipeline is defined, meaning how those Spans are collected, processed, and where they are exported, depends on its implementation. Instrumentation authors do not need to define this implementation, rather just use the provided Tracers to instrument code.
Commonly, instrumentation code will accept a TracerProvider implementation at runtime from its users or it can simply use the globally registered one (see https://pkg.go.dev/go.opentelemetry.io/otel#GetTracerProvider).
Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.
type TracerProvider interface {
// Users of the interface can ignore this. This embedded type is only used
// by implementations of this interface. See the "API Implementations"
// section of the package documentation for more information.
embedded.TracerProvider
// Tracer returns a unique Tracer scoped to be used by instrumentation code
// to trace computational workflows. The scope and identity of that
// instrumentation code is uniquely defined by the name and options passed.
//
// The passed name needs to uniquely identify instrumentation code.
// Therefore, it is recommended that name is the Go package name of the
// library providing instrumentation (note: not the code being
// instrumented). Instrumentation libraries can have multiple versions,
// therefore, the WithInstrumentationVersion option should be used to
// distinguish these different codebases. Additionally, instrumentation
// libraries may sometimes use traces to communicate different domains of
// workflow data (i.e. using spans to communicate workflow events only). If
// this is the case, the WithScopeAttributes option should be used to
// uniquely identify Tracers that handle the different domains of workflow
// data.
//
// If the same name and options are passed multiple times, the same Tracer
// will be returned (it is up to the implementation if this will be the
// same underlying instance of that Tracer or not). It is not necessary to
// call this multiple times with the same name and options to get an
// up-to-date Tracer. All implementations will ensure any TracerProvider
// configuration changes are propagated to all provided Tracers.
//
// If name is empty, then an implementation defined default name will be
// used instead.
//
// This method is safe to call concurrently.
Tracer(name string, options ...TracerOption) Tracer
}
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.
Deprecated: Use go.opentelemetry.io/otel/trace/noop.NewTracerProvider instead.