package trace

Import Path
	go.opentelemetry.io/otel/trace (on go.dev)

Dependency Relation
	imports 11 packages, and imported by 2 packages


Involved Source Files

	    config.go
	    context.go
	
		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. In 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()
				// ...
			}
		
		# API Implementations
		
		This package does not conform to the standard Go versioning policy; all of its
		interfaces may have methods added to them without a package major version bump.
		This non-standard API evolution could surprise an uninformed implementation
		author. They could unknowingly build their implementation in a way that would
		result in a runtime panic for their users that update to the new API.
		
		The API is designed to help inform an instrumentation author about this
		non-standard API evolution. It requires them to choose a default behavior for
		unimplemented interface methods. There are three behavior choices they can
		make:
		
		  - Compilation failure
		  - Panic
		  - Default to another implementation
		
		All interfaces in this API embed a corresponding interface from
		[go.opentelemetry.io/otel/trace/embedded]. If an author wants the default
		behavior of their implementations to be a compilation failure, signaling to
		their users they need to update to the latest version of that implementation,
		they need to embed the corresponding interface from
		[go.opentelemetry.io/otel/trace/embedded] in their implementation. For
		example,
		
			import "go.opentelemetry.io/otel/trace/embedded"
		
			type TracerProvider struct {
				embedded.TracerProvider
				// ...
			}
		
		If an author wants the default behavior of their implementations to panic, they
		can 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 that
		contain runtime panics when users update to newer versions of
		[go.opentelemetry.io/otel/trace], which may be done with a trasitive
		dependency.
		
		Finally, an author can embed another implementation in theirs. The embedded
		implementation will be used for methods not defined by the author. For example,
		an author who wants to default to silently dropping the call can use
		[go.opentelemetry.io/otel/trace/noop]:
		
			import "go.opentelemetry.io/otel/trace/noop"
		
			type TracerProvider struct {
				noop.TracerProvider
				// ...
			}
		
		It is strongly recommended that authors only embed
		[go.opentelemetry.io/otel/trace/noop] if they choose this default behavior.
		That implementation is the only one OpenTelemetry authors can guarantee will
		fully implement all the API interfaces when a user updates their API.

	    nonrecording.go
	    noop.go
	    trace.go
	    tracestate.go


Package-Level Type Names (total 34, in which 22 are exported)


	/* sort exporteds by:  |  */
	
		EventConfig is a group of options for an Event.

		
			
		
			
				Attributes describe the associated qualities of an Event.

			
				StackTrace checks whether stack trace capturing is enabled.

			
				Timestamp is a time in an Event life-cycle.

		
			func NewEventConfig(options ...EventOption) EventConfig


	
		EventOption applies span event options to an EventConfig.

		
			
		
			 SpanEndEventOption (interface)
			 SpanEventOption (interface)
			 SpanStartEventOption (interface)
			
		
			func NewEventConfig(options ...EventOption) EventConfig
			func Span.AddEvent(name string, options ...EventOption)
			func Span.RecordError(err error, options ...EventOption)


	
		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.

		
			
				AddEvent adds an event with the provided name and options.

			
				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.

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

			
				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.

			
				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.

			
				SetName sets the Span name.

			
				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.

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

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

			
		
			
		
			 Span : go.opentelemetry.io/otel/trace/embedded.Span
		
			func SpanFromContext(ctx context.Context) Span
			func Tracer.Start(ctx context.Context, spanName string, opts ...SpanStartOption) (context.Context, Span)
		
			func ContextWithSpan(parent context.Context, span Span) context.Context


	
		SpanConfig is a group of options for a Span.

		
			
		
			
				Attributes describe the associated qualities of a Span.

			
				Links are the associations a Span has with other Spans.

			
				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.

			
				SpanKind is the role a Span has in a trace.

			
				StackTrace checks whether stack trace capturing is enabled.

			
				Timestamp is a time in a Span life-cycle.

		
			func NewSpanEndConfig(options ...SpanEndOption) SpanConfig
			func NewSpanStartConfig(options ...SpanStartOption) SpanConfig


	
		SpanContext contains identifying trace information about a Span.

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

			
				HasSpanID checks if the SpanContext has a valid SpanID.

			
				HasTraceID checks if the SpanContext has a valid TraceID.

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

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

			
				IsValid returns if the SpanContext is valid. A valid span context has a
				valid TraceID and SpanID.

			
				MarshalJSON implements a custom marshal function to encode a SpanContext.

			
				SpanID returns the SpanID from the SpanContext.

			
				TraceFlags returns the flags from the SpanContext.

			
				TraceID returns the TraceID from the SpanContext.

			
				TraceState returns the TraceState from the SpanContext.

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

			
				WithSpanID returns a new SpanContext with the SpanID replaced.

			
				WithTraceFlags returns a new SpanContext with the TraceFlags replaced.

			
				WithTraceID returns a new SpanContext with the TraceID replaced.

			
				WithTraceState returns a new SpanContext with the TraceState replaced.

		
			 SpanContext : encoding/json.Marshaler
		
			func NewSpanContext(config SpanContextConfig) SpanContext
			func SpanContextFromContext(ctx context.Context) SpanContext
			func Span.SpanContext() SpanContext
			func SpanContext.WithRemote(remote bool) SpanContext
			func SpanContext.WithSpanID(spanID SpanID) SpanContext
			func SpanContext.WithTraceFlags(flags TraceFlags) SpanContext
			func SpanContext.WithTraceID(traceID TraceID) SpanContext
			func SpanContext.WithTraceState(state TraceState) SpanContext
		
			func ContextWithRemoteSpanContext(parent context.Context, rsc SpanContext) context.Context
			func ContextWithSpanContext(parent context.Context, sc SpanContext) context.Context
			func SpanContext.Equal(other SpanContext) bool


	
		SpanContextConfig contains mutable fields usable for constructing
		an immutable SpanContext.

		
			Remote bool
			SpanID SpanID
			TraceFlags TraceFlags
			TraceID TraceID
			TraceState TraceState
		
			func NewSpanContext(config SpanContextConfig) SpanContext


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

		
			
		
			 SpanEventOption (interface)
			
		
			 SpanEndEventOption : EventOption
			 SpanEndEventOption : SpanEndOption
		
			func WithStackTrace(b bool) SpanEndEventOption


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

		
			
		
			 SpanEndEventOption (interface)
			 SpanEventOption (interface)
			 SpanOption (interface)
			
		
			func NewSpanEndConfig(options ...SpanEndOption) SpanConfig
			func Span.End(options ...SpanEndOption)


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

		
			
		
			
		
			 SpanEventOption : EventOption
			 SpanEventOption : SpanEndEventOption
			 SpanEventOption : SpanEndOption
			 SpanEventOption : SpanOption
			 SpanEventOption : SpanStartEventOption
			 SpanEventOption : SpanStartOption
		
			func WithTimestamp(t time.Time) SpanEventOption


	
		SpanID is a unique identity of a span in a trace.

		
			
				IsValid checks whether the SpanID is valid. A valid SpanID does not consist
				of zeros only.

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

			
				String returns the hex string representation form of a SpanID.

		
			 SpanID : encoding/json.Marshaler
			 SpanID : fmt.Stringer
			
		
			func SpanIDFromHex(h string) (SpanID, error)
			func SpanContext.SpanID() SpanID
		
			func SpanContext.WithSpanID(spanID SpanID) SpanContext
		
			


	
		SpanKind is the role a Span plays in a Trace.

		
			
				String returns the specified name of the SpanKind in lower-case.

		
			 SpanKind : fmt.Stringer
			
		
			func ValidateSpanKind(spanKind SpanKind) SpanKind
			func (*SpanConfig).SpanKind() SpanKind
		
			func ValidateSpanKind(spanKind SpanKind) SpanKind
			func WithSpanKind(kind SpanKind) SpanStartOption
		
			const SpanKindClient
			const SpanKindConsumer
			const SpanKindInternal
			const SpanKindProducer
			const SpanKindServer
			const SpanKindUnspecified


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

		
			
		
			 SpanEventOption (interface)
			
		
			 SpanOption : SpanEndOption
			 SpanOption : SpanStartOption


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

		
			
		
			 SpanEventOption (interface)
			
		
			 SpanStartEventOption : EventOption
			 SpanStartEventOption : SpanStartOption
		
			func WithAttributes(attributes ...attribute.KeyValue) SpanStartEventOption


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

		
			
		
			 SpanEventOption (interface)
			 SpanOption (interface)
			 SpanStartEventOption (interface)
			
		
			func WithLinks(links ...Link) SpanStartOption
			func WithNewRoot() SpanStartOption
			func WithSpanKind(kind SpanKind) SpanStartOption
		
			func NewSpanStartConfig(options ...SpanStartOption) SpanConfig
			func Tracer.Start(ctx context.Context, spanName string, opts ...SpanStartOption) (context.Context, Span)


	
		TraceFlags contains flags that can be set on a SpanContext.

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

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

			
				String returns the hex string representation form of TraceFlags.

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

		
			 TraceFlags : encoding/json.Marshaler
			 TraceFlags : fmt.Stringer
			
		
			func SpanContext.TraceFlags() TraceFlags
			func TraceFlags.WithSampled(sampled bool) TraceFlags
		
			func SpanContext.WithTraceFlags(flags TraceFlags) SpanContext
		
			const FlagsSampled


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

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

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

			
				String returns the hex string representation form of a TraceID.

		
			 TraceID : encoding/json.Marshaler
			 TraceID : fmt.Stringer
			
		
			func TraceIDFromHex(h string) (TraceID, error)
			func SpanContext.TraceID() TraceID
		
			func SpanContext.WithTraceID(traceID TraceID) SpanContext
		
			


	
		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.

		
			
				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.

			
		
			
		
			 Tracer : go.opentelemetry.io/otel/trace/embedded.Tracer
		
			func TracerProvider.Tracer(name string, options ...TracerOption) Tracer


	
		TracerConfig is a group of options for a Tracer.

		
			
		
			
				InstrumentationAttributes returns the attributes associated with the library
				providing instrumentation.

			
				InstrumentationVersion returns the version of the library providing instrumentation.

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

		
			func NewTracerConfig(options ...TracerOption) TracerConfig


	
		TracerOption applies an option to a TracerConfig.

		
			
		
			
		
			func WithInstrumentationAttributes(attr ...attribute.KeyValue) TracerOption
			func WithInstrumentationVersion(version string) TracerOption
			func WithSchemaURL(schemaURL string) TracerOption
		
			func NewTracerConfig(options ...TracerOption) TracerConfig
			func TracerProvider.Tracer(name string, options ...TracerOption) 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.

		
			
				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.

			
		
			
		
			 TracerProvider : go.opentelemetry.io/otel/trace/embedded.TracerProvider
		
			func NewNoopTracerProvider() TracerProvider
			func Span.TracerProvider() TracerProvider


	
		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.

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

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

			
				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.

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

			
				MarshalJSON marshals the TraceState into JSON.

			
				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.

		
			 TraceState : encoding/json.Marshaler
			 TraceState : fmt.Stringer
			
		
			func ParseTraceState(tracestate string) (TraceState, error)
			func SpanContext.TraceState() TraceState
			func TraceState.Delete(key string) TraceState
			func TraceState.Insert(key, value string) (TraceState, error)
		
			func SpanContext.WithTraceState(state TraceState) SpanContext


	


Package-Level Functions (total 28, in which 25 are exported)


	
		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.


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


	
		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.


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


	
		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.


	
		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.


	
		NewSpanContext constructs a SpanContext using values from the provided
		SpanContextConfig.


	
		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.


	
		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.


	
		NewTracerConfig applies all the options to a returned TracerConfig.


	
		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.


	
		SpanContextFromContext returns the current Span's SpanContext.


	
		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.


	
		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


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


	
		ValidateSpanKind returns a valid span kind value.  This will coerce
		invalid values into the default value, SpanKindInternal.


	
		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.


	
		WithInstrumentationAttributes sets the instrumentation attributes.
		
		The passed attributes will be de-duplicated.


	
		WithInstrumentationVersion sets the instrumentation version.


	
		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.


	
		WithSchemaURL sets the schema URL for the Tracer.


	
		WithSpanKind sets the SpanKind of a Span.


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


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


	


Package-Level Variables (total 6, none are exported)

	


Package-Level Constants (total 23, in which 7 are exported)


	
		FlagsSampled is a bitmask with the sampled bit set. A SpanContext
		with the sampling bit set means the span is sampled.


	
		SpanKindClient is a SpanKind for a Span that represents the operation
		of client making a request to a server.


	
		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.


	
		SpanKindInternal is a SpanKind for a Span that represents an internal
		operation within an application.


	
		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.


	
		SpanKindServer is a SpanKind for a Span that represents the operation
		of handling a request from a client.


	
		SpanKindUnspecified is an unspecified SpanKind and is not a valid
		SpanKind. SpanKindUnspecified should be replaced with SpanKindInternal
		if it is received.