trace
packagemodule
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
README¶
Trace API
Documentation¶
Overview¶
Package trace provides an implementation of the tracing part of theOpenTelemetry API.
To participate in distributed traces a Span needs to be created for theoperation being performed as part of a traced workflow. In its simplest form:
var tracer trace.Tracerfunc init() {tracer = otel.Tracer("instrumentation/package/name")}func operation(ctx context.Context) {var span trace.Spanctx, 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 itcan create its own unique Tracer. Alternatively, the registered globalTracerProvider from the go.opentelemetry.io/otel package can be used asa 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.Spanctx, span = inst.tracer.Start(ctx, "operation")defer span.End()// ...}API Implementations¶
This package does not conform to the standard Go versioning policy; all of itsinterfaces may have methods added to them without a package major version bump.This non-standard API evolution could surprise an uninformed implementationauthor. They could unknowingly build their implementation in a way that wouldresult in a runtime panic for their users that update to the new API.
The API is designed to help inform an instrumentation author about thisnon-standard API evolution. It requires them to choose a default behavior forunimplemented interface methods. There are three behavior choices they canmake:
- Compilation failure
- Panic
- Default to another implementation
All interfaces in this API embed a corresponding interface fromgo.opentelemetry.io/otel/trace/embedded. If an author wants the defaultbehavior of their implementations to be a compilation failure, signaling totheir users they need to update to the latest version of that implementation,they need to embed the corresponding interface fromgo.opentelemetry.io/otel/trace/embedded in their implementation. Forexample,
import "go.opentelemetry.io/otel/trace/embedded"type TracerProvider struct {embedded.TracerProvider// ...}If an author wants the default behavior of their implementations to panic, theycan embed the API interface directly.
import "go.opentelemetry.io/otel/trace"type TracerProvider struct {trace.TracerProvider// ...}This option is not recommended. It will lead to publishing packages thatcontain runtime panics when users update to newer versions ofgo.opentelemetry.io/otel/trace, which may be done with a transitivedependency.
Finally, an author can embed another implementation in theirs. The embeddedimplementation will be used for methods not defined by the author. For example,an author who wants to default to silently dropping the call can usego.opentelemetry.io/otel/trace/noop:
import "go.opentelemetry.io/otel/trace/noop"type TracerProvider struct {noop.TracerProvider// ...}It is strongly recommended that authors only embedgo.opentelemetry.io/otel/trace/noop if they choose this default behavior.That implementation is the only one OpenTelemetry authors can guarantee willfully implement all the API interfaces when a user updates their API.
Index¶
- Constants
- func ContextWithRemoteSpanContext(parent context.Context, rsc SpanContext) context.Context
- func ContextWithSpan(parent context.Context, span Span) context.Context
- func ContextWithSpanContext(parent context.Context, sc SpanContext) context.Context
- type EventConfig
- type EventOption
- type Link
- type Span
- type SpanConfig
- type SpanContext
- func (sc SpanContext) Equal(other SpanContext) bool
- func (sc SpanContext) HasSpanID() bool
- func (sc SpanContext) HasTraceID() bool
- func (sc SpanContext) IsRemote() bool
- func (sc SpanContext) IsSampled() bool
- func (sc SpanContext) IsValid() bool
- func (sc SpanContext) MarshalJSON() ([]byte, error)
- func (sc SpanContext) SpanID() SpanID
- func (sc SpanContext) TraceFlags() TraceFlags
- func (sc SpanContext) TraceID() TraceID
- func (sc SpanContext) TraceState() TraceState
- func (sc SpanContext) WithRemote(remote bool) SpanContext
- func (sc SpanContext) WithSpanID(spanID SpanID) SpanContext
- func (sc SpanContext) WithTraceFlags(flags TraceFlags) SpanContext
- func (sc SpanContext) WithTraceID(traceID TraceID) SpanContext
- func (sc SpanContext) WithTraceState(state TraceState) SpanContext
- type SpanContextConfig
- type SpanEndEventOption
- type SpanEndOption
- type SpanEventOption
- type SpanID
- type SpanKind
- type SpanOption
- type SpanStartEventOption
- type SpanStartOption
- type TraceFlags
- type TraceID
- type TraceState
- func (ts TraceState) Delete(key string) TraceState
- func (ts TraceState) Get(key string) string
- func (ts TraceState) Insert(key, value string) (TraceState, error)
- func (ts TraceState) Len() int
- func (ts TraceState) MarshalJSON() ([]byte, error)
- func (ts TraceState) String() string
- func (ts TraceState) Walk(f func(key, value string) bool)
- type Tracer
- type TracerConfig
- type TracerOption
- type TracerProvider
Constants¶
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¶
funcContextWithRemoteSpanContext¶
func ContextWithRemoteSpanContext(parentcontext.Context, rscSpanContext)context.Context
ContextWithRemoteSpanContext returns a copy of parent with rsc set explicitlyas a remote SpanContext and as the current Span. The Span implementationthat wraps rsc is non-recording and performs no operations other than toreturn rsc as the SpanContext from the SpanContext method.
funcContextWithSpan¶
ContextWithSpan returns a copy of parent with span set as the current Span.
funcContextWithSpanContext¶added inv0.20.0
func ContextWithSpanContext(parentcontext.Context, scSpanContext)context.Context
ContextWithSpanContext returns a copy of parent with sc as the currentSpan. The Span implementation that wraps sc is non-recording and performsno operations other than to return sc as the SpanContext from theSpanContext method.
Types¶
typeEventConfig¶added inv1.0.0
type EventConfig struct {// contains filtered or unexported fields}EventConfig is a group of options for an Event.
funcNewEventConfig¶
func NewEventConfig(options ...EventOption)EventConfig
NewEventConfig applies all the EventOptions to a returned EventConfig. If notimestamp option is passed, the returned EventConfig will have a Timestampset to the call time, otherwise no validation is performed on the returnedEventConfig.
func (*EventConfig)Attributes¶added inv1.0.0
func (cfg *EventConfig) Attributes() []attribute.KeyValue
Attributes describe the associated qualities of an Event.
func (*EventConfig)StackTrace¶added inv1.0.0
func (cfg *EventConfig) StackTrace()bool
StackTrace reports whether stack trace capturing is enabled.
func (*EventConfig)Timestamp¶added inv1.0.0
func (cfg *EventConfig) Timestamp()time.Time
Timestamp is a time in an Event life-cycle.
typeEventOption¶
type EventOption interface {// contains filtered or unexported methods}EventOption applies span event options to an EventConfig.
typeLink¶
type Link struct {// SpanContext of the linked Span.SpanContextSpanContext// Attributes describe the aspects of the link.Attributes []attribute.KeyValue}Link is the relationship between two Spans. The relationship can be withinthe same Trace or across different Traces.
For example, a Link is used in the following situations:
- Batch Processing: A batch of operations may contain operationsassociated with one or more traces/spans. Since there can only be oneparent SpanContext, a Link is used to keep reference to theSpanContext of all operations in the batch.
- Public Endpoint: A SpanContext for an in incoming client request on apublic endpoint should be considered untrusted. In such a case, a newtrace with its own identity and sampling decision needs to be created,but this new trace needs to be related to the original trace in someform. A Link is used to keep reference to the original SpanContext andtrack the relationship.
typeSpan¶
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(namestring, options ...EventOption)// AddLink adds a link.// Adding links at span creation using WithLinks is preferred to calling AddLink// later, for contexts that are available during span creation, because head// sampling decisions can only consider information present during span creation.AddLink(linkLink)// 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(errerror, 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(codecodes.Code, descriptionstring)// SetName sets the Span name.SetName(namestring)// 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.//// Note that adding attributes at span creation using [WithAttributes] is preferred// to calling SetAttribute later, as samplers can only consider information// already present during span creation.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 namedand timed operation of a workflow that is traced. A Tracer is used tocreate a Span and it is then up to the operation the Span represents toproperly end the Span when the operation itself ends.
Warning: Methods may be added to this interface in minor releases. Seepackage documentation on API implementation for information on how to setdefault behavior for unimplemented methods.
funcSpanFromContext¶
SpanFromContext returns the current Span from ctx.
If no Span is currently set in ctx an implementation of a Span thatperforms no operations is returned.
typeSpanConfig¶
type SpanConfig struct {// contains filtered or unexported fields}SpanConfig is a group of options for a Span.
funcNewSpanEndConfig¶added inv1.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 uniquenesschecking or bounding of data), it is left to the SDK to perform thisaction.
funcNewSpanStartConfig¶added inv1.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 uniquenesschecking or bounding of data), it is left to the SDK to perform thisaction.
func (*SpanConfig)Attributes¶
func (cfg *SpanConfig) Attributes() []attribute.KeyValue
Attributes describe the associated qualities of a Span.
func (*SpanConfig)Links¶
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 iscommonly used when an existing trace crosses trust boundaries and theremote 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 inv1.0.0
func (cfg *SpanConfig) StackTrace()bool
StackTrace reports whether stack trace capturing is enabled.
func (*SpanConfig)Timestamp¶
func (cfg *SpanConfig) Timestamp()time.Time
Timestamp is a time in a Span life-cycle.
typeSpanContext¶
type SpanContext struct {// contains filtered or unexported fields}SpanContext contains identifying trace information about a Span.
funcNewSpanContext¶added inv0.19.0
func NewSpanContext(configSpanContextConfig)SpanContext
NewSpanContext constructs a SpanContext using values from the providedSpanContextConfig.
funcSpanContextFromContext¶
func SpanContextFromContext(ctxcontext.Context)SpanContext
SpanContextFromContext returns the current Span's SpanContext.
func (SpanContext)Equal¶added inv0.19.0
func (scSpanContext) Equal(otherSpanContext)bool
Equal reports whether two SpanContext values are equal.
func (SpanContext)HasSpanID¶
func (scSpanContext) HasSpanID()bool
HasSpanID reports whether the SpanContext has a valid SpanID.
func (SpanContext)HasTraceID¶
func (scSpanContext) HasTraceID()bool
HasTraceID reports whether the SpanContext has a valid TraceID.
func (SpanContext)IsRemote¶added inv0.19.0
func (scSpanContext) IsRemote()bool
IsRemote reports whether the SpanContext represents a remotely-created Span.
func (SpanContext)IsSampled¶
func (scSpanContext) IsSampled()bool
IsSampled reports whether the sampling bit is set in the SpanContext's TraceFlags.
func (SpanContext)IsValid¶
func (scSpanContext) IsValid()bool
IsValid reports whether the SpanContext is valid. A valid span context has avalid TraceID and SpanID.
func (SpanContext)MarshalJSON¶added inv0.19.0
func (scSpanContext) MarshalJSON() ([]byte,error)
MarshalJSON implements a custom marshal function to encode a SpanContext.
func (SpanContext)SpanID¶
func (scSpanContext) SpanID()SpanID
SpanID returns the SpanID from the SpanContext.
func (SpanContext)TraceFlags¶
func (scSpanContext) TraceFlags()TraceFlags
TraceFlags returns the flags from the SpanContext.
func (SpanContext)TraceID¶
func (scSpanContext) TraceID()TraceID
TraceID returns the TraceID from the SpanContext.
func (SpanContext)TraceState¶
func (scSpanContext) TraceState()TraceState
TraceState returns the TraceState from the SpanContext.
func (SpanContext)WithRemote¶added inv0.19.0
func (scSpanContext) WithRemote(remotebool)SpanContext
WithRemote returns a copy of sc with the Remote property set to remote.
func (SpanContext)WithSpanID¶added inv0.19.0
func (scSpanContext) WithSpanID(spanIDSpanID)SpanContext
WithSpanID returns a new SpanContext with the SpanID replaced.
func (SpanContext)WithTraceFlags¶added inv0.19.0
func (scSpanContext) WithTraceFlags(flagsTraceFlags)SpanContext
WithTraceFlags returns a new SpanContext with the TraceFlags replaced.
func (SpanContext)WithTraceID¶added inv0.19.0
func (scSpanContext) WithTraceID(traceIDTraceID)SpanContext
WithTraceID returns a new SpanContext with the TraceID replaced.
func (SpanContext)WithTraceState¶added inv0.19.0
func (scSpanContext) WithTraceState(stateTraceState)SpanContext
WithTraceState returns a new SpanContext with the TraceState replaced.
typeSpanContextConfig¶added inv0.19.0
type SpanContextConfig struct {TraceIDTraceIDSpanIDSpanIDTraceFlagsTraceFlagsTraceStateTraceStateRemotebool}SpanContextConfig contains mutable fields usable for constructingan immutable SpanContext.
typeSpanEndEventOption¶added inv1.0.0
type SpanEndEventOption interface {SpanEndOptionEventOption}SpanEndEventOption are options that can be used at the end of a span, or with an event.
funcWithStackTrace¶added inv1.0.0
func WithStackTrace(bbool)SpanEndEventOption
WithStackTrace sets the flag to capture the error with stack trace (e.g. true, false).
typeSpanEndOption¶added inv1.0.0
type SpanEndOption interface {// contains filtered or unexported methods}SpanEndOption applies an option to a SpanConfig. These options areapplicable only when the span is ended.
typeSpanEventOption¶added inv1.0.0
type SpanEventOption interface {SpanOptionEventOption}SpanEventOption are options that can be used with an event or a span.
funcWithTimestamp¶
func WithTimestamp(ttime.Time)SpanEventOption
WithTimestamp sets the time of a Span or Event life-cycle moment (e.g.started, stopped, errored).
typeSpanID¶
type SpanID [8]byte
SpanID is a unique identity of a span in a trace.
funcSpanIDFromHex¶
SpanIDFromHex returns a SpanID from a hex string if it is compliantwith the w3c trace-context specification.See more athttps://www.w3.org/TR/trace-context/#parent-id
func (SpanID)IsValid¶
IsValid reports whether the SpanID is valid. A valid SpanID does not consistof zeros only.
func (SpanID)MarshalJSON¶
MarshalJSON implements a custom marshal function to encode SpanIDas a hex string.
typeSpanKind¶
type SpanKindint
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.SpanKindUnspecifiedSpanKind = 0// SpanKindInternal is a SpanKind for a Span that represents an internal// operation within an application.SpanKindInternalSpanKind = 1// SpanKindServer is a SpanKind for a Span that represents the operation// of handling a request from a client.SpanKindServerSpanKind = 2// SpanKindClient is a SpanKind for a Span that represents the operation// of client making a request to a server.SpanKindClientSpanKind = 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.SpanKindProducerSpanKind = 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.SpanKindConsumerSpanKind = 5)
As a convenience, these match the proto definition, seehttps://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.
funcValidateSpanKind¶
ValidateSpanKind returns a valid span kind value. This will coerceinvalid values into the default value, SpanKindInternal.
typeSpanOption¶
type SpanOption interface {SpanStartOptionSpanEndOption}SpanOption are options that can be used at both the beginning and end of a span.
typeSpanStartEventOption¶added inv1.0.0
type SpanStartEventOption interface {SpanStartOptionEventOption}SpanStartEventOption are options that can be used at the start of a span, or with an event.
funcWithAttributes¶
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 thisoption is provided to a Span's start event. Otherwise, theseattributes 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 successiveoption will extend the attributes instead of overwriting. There is noguarantee of uniqueness in the resulting attributes.
typeSpanStartOption¶added inv1.0.0
type SpanStartOption interface {// contains filtered or unexported methods}SpanStartOption applies an option to a SpanConfig. These options are applicableonly when the span is created.
funcWithLinks¶
func WithLinks(links ...Link)SpanStartOption
WithLinks adds links to a Span. The links are added to the existing Spanlinks, i.e. this does not overwrite. Links with invalid span context are ignored.
funcWithNewRoot¶
func WithNewRoot()SpanStartOption
WithNewRoot specifies that the Span should be treated as a root Span. Anyexisting parent span context will be ignored when defining the Span's traceidentifiers.
funcWithSpanKind¶
func WithSpanKind(kindSpanKind)SpanStartOption
WithSpanKind sets the SpanKind of a Span.
typeTraceFlags¶added inv0.20.0
type TraceFlagsbyte//nolint:revive // revive complains about stutter of `trace.TraceFlags`.
TraceFlags contains flags that can be set on a SpanContext.
func (TraceFlags)IsSampled¶added inv0.20.0
func (tfTraceFlags) IsSampled()bool
IsSampled reports whether the sampling bit is set in the TraceFlags.
func (TraceFlags)MarshalJSON¶added inv0.20.0
func (tfTraceFlags) MarshalJSON() ([]byte,error)
MarshalJSON implements a custom marshal function to encode TraceFlagsas a hex string.
func (TraceFlags)String¶added inv0.20.0
func (tfTraceFlags) String()string
String returns the hex string representation form of TraceFlags.
func (TraceFlags)WithSampled¶added inv0.20.0
func (tfTraceFlags) WithSampled(sampledbool)TraceFlags
WithSampled sets the sampling bit in a new copy of the TraceFlags.
typeTraceID¶
type TraceID [16]byte
TraceID is a unique identity of a trace.nolint:revive // revive complains about stutter of `trace.TraceID`.
funcTraceIDFromHex¶
TraceIDFromHex returns a TraceID from a hex string if it is compliant withthe W3C trace-context specification. See more athttps://www.w3.org/TR/trace-context/#trace-idnolint:revive // revive complains about stutter of `trace.TraceIDFromHex`.
func (TraceID)IsValid¶
IsValid reports whether the trace TraceID is valid. A valid trace ID doesnot consist of zeros only.
func (TraceID)MarshalJSON¶
MarshalJSON implements a custom marshal function to encode TraceIDas a hex string.
typeTraceState¶
type TraceState struct {// contains filtered or unexported fields}TraceState provides additional vendor-specific trace identificationinformation across different distributed tracing systems. It represents animmutable list consisting of key/value pairs, each pair is referred to as alist-member.
TraceState conforms to the W3C Trace Context specification(https://www.w3.org/TR/trace-context-1). All operations that create or copya TraceState do so by validating all input and will only produce TraceStatethat conform to the specification. Specifically, this means that alllist-member's key/value pairs are valid, no duplicate list-members exist,and the maximum number of list-members (32) is not exceeded.
funcParseTraceState¶added inv1.0.0
func ParseTraceState(tsstring) (TraceState,error)
ParseTraceState attempts to decode a TraceState from the passedstring. It returns an error if the input is invalid according to the W3CTrace Context specification.
func (TraceState)Delete¶
func (tsTraceState) Delete(keystring)TraceState
Delete returns a copy of the TraceState with the list-member identified bykey removed.
func (TraceState)Get¶
func (tsTraceState) Get(keystring)string
Get returns the value paired with key from the corresponding TraceStatelist-member if it exists, otherwise an empty string is returned.
func (TraceState)Insert¶
func (tsTraceState) Insert(key, valuestring) (TraceState,error)
Insert adds a new list-member defined by the key/value pair to theTraceState. If a list-member already exists for the given key, thatlist-member's value is updated. The new or updated list-member is alwaysmoved to the beginning of the TraceState as specified by the W3C TraceContext specification.
If key or value are invalid according to the W3C Trace Contextspecification an error is returned with the original TraceState.
If adding a new list-member means the TraceState would have more membersthen is allowed, the new list-member will be inserted and the right-mostlist-member will be dropped in the returned TraceState.
func (TraceState)Len¶added inv1.0.0
func (tsTraceState) Len()int
Len returns the number of list-members in the TraceState.
func (TraceState)MarshalJSON¶
func (tsTraceState) MarshalJSON() ([]byte,error)
MarshalJSON marshals the TraceState into JSON.
func (TraceState)String¶
func (tsTraceState) String()string
String encodes the TraceState into a string compliant with the W3CTrace Context specification. The returned string will be invalid if theTraceState contains any invalid members.
func (TraceState)Walk¶added inv1.29.0
func (tsTraceState) Walk(f func(key, valuestring)bool)
Walk walks all key value pairs in the TraceState by calling fIteration stops if f returns false.
typeTracer¶
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(ctxcontext.Context, spanNamestring, opts ...SpanStartOption) (context.Context,Span)}Tracer is the creator of Spans.
Warning: Methods may be added to this interface in minor releases. Seepackage documentation on API implementation for information on how to setdefault behavior for unimplemented methods.
typeTracerConfig¶
type TracerConfig struct {// contains filtered or unexported fields}TracerConfig is a group of options for a Tracer.
funcNewTracerConfig¶
func NewTracerConfig(options ...TracerOption)TracerConfig
NewTracerConfig applies all the options to a returned TracerConfig.
func (*TracerConfig)InstrumentationAttributes¶added inv1.14.0
func (t *TracerConfig) InstrumentationAttributes()attribute.Set
InstrumentationAttributes returns the attributes associated with the libraryproviding instrumentation.
func (*TracerConfig)InstrumentationVersion¶
func (t *TracerConfig) InstrumentationVersion()string
InstrumentationVersion returns the version of the library providing instrumentation.
func (*TracerConfig)SchemaURL¶added inv1.0.0
func (t *TracerConfig) SchemaURL()string
SchemaURL returns the Schema URL of the telemetry emitted by the Tracer.
typeTracerOption¶
type TracerOption interface {// contains filtered or unexported methods}TracerOption applies an option to a TracerConfig.
funcWithInstrumentationAttributeSet¶added inv1.39.0
func WithInstrumentationAttributeSet(setattribute.Set)TracerOption
WithInstrumentationAttributeSet adds the instrumentation attributes.
If multipleWithInstrumentationAttributes orWithInstrumentationAttributeSetoptions are passed, the attributes will be merged together in the orderthey are passed. Attributes with duplicate keys will use the last value passed.
funcWithInstrumentationAttributes¶added inv1.14.0
func WithInstrumentationAttributes(attr ...attribute.KeyValue)TracerOption
WithInstrumentationAttributes adds the instrumentation attributes.
This is equivalent to callingWithInstrumentationAttributeSet with anattribute.Set created from a clone of the passed attributes.WithInstrumentationAttributeSet is recommended for more control.
If multipleWithInstrumentationAttributes orWithInstrumentationAttributeSetoptions are passed, the attributes will be merged together in the orderthey are passed. Attributes with duplicate keys will use the last value passed.
funcWithInstrumentationVersion¶
func WithInstrumentationVersion(versionstring)TracerOption
WithInstrumentationVersion sets the instrumentation version.
funcWithSchemaURL¶added inv1.0.0
func WithSchemaURL(schemaURLstring)TracerOption
WithSchemaURL sets the schema URL for the Tracer.
typeTracerProvider¶
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(namestring, options ...TracerOption)Tracer}TracerProvider provides Tracers that are used by instrumentation code totrace computational workflows.
A TracerProvider is the collection destination of all Spans from Tracers itprovides, it represents a unique telemetry collection pipeline. How thatpipeline is defined, meaning how those Spans are collected, processed, andwhere they are exported, depends on its implementation. Instrumentationauthors do not need to define this implementation, rather just use theprovided Tracers to instrument code.
Commonly, instrumentation code will accept a TracerProvider implementationat runtime from its users or it can simply use the globally registered one(seehttps://pkg.go.dev/go.opentelemetry.io/otel#GetTracerProvider).
Warning: Methods may be added to this interface in minor releases. Seepackage documentation on API implementation for information on how to setdefault behavior for unimplemented methods.
funcNewNoopTracerProviderdeprecated
func NewNoopTracerProvider()TracerProvider
NewNoopTracerProvider returns an implementation of TracerProvider thatperforms no operations. The Tracer and Spans created from the returnedTracerProvider also perform no operations.
Deprecated: Usego.opentelemetry.io/otel/trace/noop.NewTracerProviderinstead.
Source Files¶
Directories¶
| Path | Synopsis |
|---|---|
Package embedded provides interfaces embedded within the [OpenTelemetry trace API]. | Package embedded provides interfaces embedded within the [OpenTelemetry trace API]. |
internal | |
telemetry Package telemetry provides a lightweight representations of OpenTelemetry telemetry that is compatible with the OTLP JSON protobuf encoding. | Package telemetry provides a lightweight representations of OpenTelemetry telemetry that is compatible with the OTLP JSON protobuf encoding. |
Package noop provides an implementation of the OpenTelemetry trace API that produces no telemetry and minimizes used computation resources. | Package noop provides an implementation of the OpenTelemetry trace API that produces no telemetry and minimizes used computation resources. |