package trace
Import Path
go.opentelemetry.io/otel/api/trace (on go.dev)
Dependency Relation
imports 12 packages, and imported by 5 packages
Involved Source Files
api.go
b3_propagator.go
context.go
doc.go
noop_span.go
noop_trace.go
noop_trace_provider.go
span_context.go
trace_context_propagator.go
Package-Level Type Names (total 25, in which 22 are exported)
B3 propagator serializes SpanContext to/from B3 Headers.
This propagator supports both versions of B3 headers,
1. Single Header:
b3: {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}
2. Multiple Headers:
x-b3-traceid: {TraceId}
x-b3-parentspanid: {ParentSpanId}
x-b3-spanid: {SpanId}
x-b3-sampled: {SamplingState}
x-b3-flags: {DebugFlag}
InjectEncoding are the B3 encodings used when injecting trace
information. If no encoding is specified (i.e. `B3Unspecified`)
`B3MultipleHeader` will be used as the default.
Extract extracts a context from the supplier if it contains B3 headers.
( T) GetAllKeys() []string
Inject injects a context into the supplier as B3 headers.
The parent span ID is omitted because it is not tracked in the
SpanContext.
T : go.opentelemetry.io/otel/api/propagation.HTTPExtractor
T : go.opentelemetry.io/otel/api/propagation.HTTPInjector
T : go.opentelemetry.io/otel/api/propagation.HTTPPropagator
B3Encoding is a bitmask representation of the B3 encoding type.
supports returns if e has o bit(s) set.
func B3Encoding.supports(o B3Encoding) bool
const B3MultipleHeader
const B3SingleHeader
const B3Unspecified
EndConfig provides options to set properties of span at the time of ending
the span.
EndTime time.Time
EndOption applies changes to EndConfig that sets options when the span is ended.
func WithEndTime(t time.Time) EndOption
func NoopSpan.End(options ...EndOption)
func Span.End(options ...EndOption)
ErrorConfig provides options to set properties of an error event at the time it is recorded.
StatusCode codes.Code
Timestamp time.Time
ErrorOption applies changes to ErrorConfig that sets options when an error event is recorded.
func WithErrorStatus(s codes.Code) ErrorOption
func WithErrorTime(t time.Time) ErrorOption
func NoopSpan.RecordError(ctx context.Context, err error, opts ...ErrorOption)
func Span.RecordError(ctx context.Context, err error, opts ...ErrorOption)
ID is a unique identity of a trace.
IsValid checks whether the trace ID 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
T : database/sql/driver.Validator
T : encoding/json.Marshaler
T : expvar.Var
T : fmt.Stringer
T : context.stringer
T : runtime.stringer
func IDFromHex(h string) (ID, error)
var nilTraceID
Link is used to establish relationship between two spans within the same Trace or
across different Traces. Few examples of Link usage.
1. Batch Processing: A batch of elements may contain elements associated with one
or more traces/spans. Since there can only be one parent SpanContext, Link is
used to keep reference to SpanContext of all elements in the batch.
2. Public Endpoint: A SpanContext in incoming client request on a public endpoint
is untrusted from service provider perspective. In such case it is advisable to
start a new trace with appropriate sampling decision.
However, it is desirable to associate incoming SpanContext to new trace initiated
on service provider side so two traces (from Client and from Service Provider) can
be correlated.
Attributes []label.KeyValue
SpanContext SpanContext
SpanContext.SpanID SpanID
SpanContext.TraceFlags byte
SpanContext.TraceID ID
HasSpanID checks if the span context has a valid span ID.
HasTraceID checks if the span context has a valid trace ID.
IsSampled returns if the sampling bit is set in the trace flags.
IsValid checks if the span context is valid. A valid span context
has a valid trace ID and a valid span ID.
isDebug returns if the debug bit is set in the trace flags.
isDeferred returns if the deferred bit is set in the trace flags.
T : database/sql/driver.Validator
Tracer returns noop implementation of Tracer.
T : Provider
AddEvent does nothing.
AddEventWithTimestamp does nothing.
End does nothing.
IsRecording always returns false for NoopSpan.
RecordError does nothing.
SetAttribute does nothing.
SetAttributes does nothing.
SetError does nothing.
SetName does nothing.
SetStatus does nothing.
SpanContext returns an invalid span context.
Tracer returns noop implementation of Tracer.
T : Span
Start starts a noop span.
T : Tracer
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.
NoopProvider
*go.opentelemetry.io/otel/api/global/internal.traceProvider
func go.opentelemetry.io/otel/api/global.TraceProvider() Provider
func go.opentelemetry.io/otel/api/global/internal.TraceProvider() Provider
func go.opentelemetry.io/otel/api/global.SetTraceProvider(tp Provider)
func go.opentelemetry.io/otel/api/global/internal.SetTraceProvider(tp Provider)
AddEvent adds an event to the span.
AddEventWithTimestamp adds an event with a custom timestamp
to the span.
End completes the span. No updates are allowed to span after it
ends. The only exception is setting status of the span.
IsRecording returns true if the span is active and recording events is enabled.
RecordError records an error as a span event.
Set singular span attribute, with type inference.
Set span attributes
SetName sets the name of the span.
SetStatus sets the status of the span in the form of a code
and a message. SetStatus overrides the value of previous
calls to SetStatus on the Span.
The default span status is OK, so it is not necessary to
explicitly set an OK status on successful Spans unless it
is to add an OK message or to override a previous status on the Span.
SpanContext returns span context of the span. Returned SpanContext is usable
even after the span ends.
Tracer returns tracer used to create this span. Tracer cannot be nil.
NoopSpan
func SpanFromContext(ctx context.Context) Span
func NoopTracer.Start(ctx context.Context, name string, opts ...StartOption) (context.Context, Span)
func Tracer.Start(ctx context.Context, spanName string, opts ...StartOption) (context.Context, Span)
func go.opentelemetry.io/otel.Tracer.Start(ctx context.Context, spanName string, opts ...StartOption) (context.Context, Span)
func ContextWithSpan(ctx context.Context, span Span) context.Context
SpanContext contains basic information about the span - its trace
ID, span ID and trace flags.
SpanID SpanID
TraceFlags byte
TraceID ID
HasSpanID checks if the span context has a valid span ID.
HasTraceID checks if the span context has a valid trace ID.
IsSampled returns if the sampling bit is set in the trace flags.
IsValid checks if the span context is valid. A valid span context
has a valid trace ID and a valid span ID.
isDebug returns if the debug bit is set in the trace flags.
isDeferred returns if the deferred bit is set in the trace flags.
T : database/sql/driver.Validator
func EmptySpanContext() SpanContext
func RemoteSpanContextFromContext(ctx context.Context) SpanContext
func NoopSpan.SpanContext() SpanContext
func Span.SpanContext() SpanContext
func extractMultiple(traceID, spanID, parentSpanID, sampled, flags string) (SpanContext, error)
func extractSingle(contextHeader string) (SpanContext, error)
func TraceContext.extract(supplier propagation.HTTPSupplier) SpanContext
func ContextWithRemoteSpanContext(ctx context.Context, sc SpanContext) context.Context
func LinkedTo(sc SpanContext, attrs ...label.KeyValue) StartOption
var empty
SpanID is a unique identify of a span in a trace.
IsValid checks whether the span ID is valid. A valid span ID 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
T : database/sql/driver.Validator
T : encoding/json.Marshaler
T : expvar.Var
T : fmt.Stringer
T : context.stringer
T : runtime.stringer
func SpanIDFromHex(h string) (SpanID, error)
var nilSpanID
SpanKind represents the role of a Span inside a Trace. Often, this defines how a Span
will be processed and visualized by various backends.
String returns the specified name of the SpanKind in lower-case.
T : expvar.Var
T : fmt.Stringer
T : context.stringer
T : runtime.stringer
func ValidateSpanKind(spanKind SpanKind) SpanKind
func ValidateSpanKind(spanKind SpanKind) SpanKind
func WithSpanKind(sk SpanKind) StartOption
const SpanKindClient
const SpanKindConsumer
const SpanKindInternal
const SpanKindProducer
const SpanKindServer
const SpanKindUnspecified
StartConfig provides options to set properties of span at the time of starting
a new span.
Attributes []label.KeyValue
Links []Link
NewRoot bool
Record bool
SpanKind SpanKind
StartTime time.Time
StartOption applies changes to StartConfig that sets options at span start time.
func LinkedTo(sc SpanContext, attrs ...label.KeyValue) StartOption
func WithAttributes(attrs ...label.KeyValue) StartOption
func WithNewRoot() StartOption
func WithRecord() StartOption
func WithSpanKind(sk SpanKind) StartOption
func WithStartTime(t time.Time) StartOption
func NoopTracer.Start(ctx context.Context, name string, opts ...StartOption) (context.Context, Span)
func Tracer.Start(ctx context.Context, spanName string, opts ...StartOption) (context.Context, Span)
func go.opentelemetry.io/otel.Tracer.Start(ctx context.Context, spanName string, opts ...StartOption) (context.Context, Span)
TraceContext propagates SpanContext in W3C TraceContext format.
( T) Extract(ctx context.Context, supplier propagation.HTTPSupplier) context.Context
( T) GetAllKeys() []string
( T) Inject(ctx context.Context, supplier propagation.HTTPSupplier)
( T) extract(supplier propagation.HTTPSupplier) SpanContext
T : go.opentelemetry.io/otel/api/propagation.HTTPExtractor
T : go.opentelemetry.io/otel/api/propagation.HTTPInjector
T : go.opentelemetry.io/otel/api/propagation.HTTPPropagator
Start a span.
NoopTracer
*go.opentelemetry.io/otel/api/global/internal.tracer
func NoopProvider.Tracer(_ string, _ ...TracerOption) Tracer
func NoopSpan.Tracer() Tracer
func Provider.Tracer(instrumentationName string, opts ...TracerOption) Tracer
func Span.Tracer() Tracer
func go.opentelemetry.io/otel/api/global.Tracer(name string) Tracer
TracerConfig contains options for a Tracer.
InstrumentationVersion is the version of the library providing
instrumentation.
TracerOption configures a TracerConfig option.
func WithInstrumentationVersion(version string) TracerOption
func NoopProvider.Tracer(_ string, _ ...TracerOption) Tracer
func Provider.Tracer(instrumentationName string, opts ...TracerOption) Tracer
Package-Level Functions (total 22, in which 19 are exported)
ContextWithRemoteSpanContext creates a new context with a remote
span context set to the passed span context.
ContextWithSpan creates a new context with a current span set to
the passed span.
DefaultHTTPPropagator returns the default trace HTTP propagator.
EmptySpanContext is meant for internal use to return invalid span
context during error conditions.
IDFromHex returns a TraceID from a hex string if it is compliant
with the w3c trace-context specification.
See more at https://www.w3.org/TR/trace-context/#trace-id
LinkedTo allows instantiating a Span with initial Links.
RemoteSpanContextFromContext returns the remote span context stored
in the context.
SpanFromContext returns the current span stored in the context.
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
ValidateSpanKind returns a valid span kind value. This will coerce
invalid values into the default value, SpanKindInternal.
WithAttributes sets attributes to span. These attributes provides additional
data about the span.
Multiple `WithAttributes` options appends the attributes preserving the order.
WithEndTime sets the end time of the span to provided time t, when it is ended.
WithErrorStatus indicates the span status that should be set when recording an error event.
WithErrorTime sets the time at which the error event should be recorded.
WithInstrumentationVersion sets the instrumentation version for a Tracer.
WithNewRoot specifies that the current span or remote span context
in context passed to `Start` should be ignored when deciding about
a parent, which effectively means creating a span with new trace
ID. The current span and the remote span context may be added as
links to the span by the implementation.
WithRecord specifies that the span should be recorded.
Note that the implementation may still override this preference,
e.g., if the span is a child in an unsampled trace.
WithSpanKind specifies the role a Span on a Trace.
WithStartTime sets the start time of the span to provided time t, when it is started.
In absence of this option, wall clock time is used as start time.
This option is typically used when starting of the span is delayed.
Package-Level Variables (total 16, none are exported)
Package-Level Constants (total 37, in which 17 are exported)
B3MultipleHeader is a B3 encoding that uses multiple headers to
transmit tracing information all prefixed with `x-b3-`.
B3SingleHeader is a B3 encoding that uses a single header named `b3`
to transmit tracing information.
B3Unspecified is an unspecified B3 encoding.
const ErrInvalidHexID errorConst = "trace-id and span-id can only contain [0-9a-f] characters, all lower... const ErrInvalidSpanIDLength errorConst = "hex encoded span-id must have length equals to 16" const ErrInvalidTraceIDLength errorConst = "hex encoded trace-id must have length equals to 32" const ErrNilSpanID errorConst = "span-id can't be all zero" const ErrNilTraceID errorConst = "trace-id can't be all zero"
FlagsDebug is a bitmask with the debug bit set.
FlagsDeferred is a bitmask with the deferred bit set. A SpanContext
with the deferred bit set means the sampling decision has been
defered to the receiver.
FlagsSampled is a bitmask with the sampled bit set. A SpanContext
with the sampling bit set means the span is sampled.
As a convenience, these match the proto definition, see
opentelemetry/proto/trace/v1/trace.proto
The unspecified value is not a valid `SpanKind`. Use
`ValidateSpanKind()` to coerce a span kind to a valid
value.
 |
The pages are generated with Golds v0.3.2-preview. (GOOS=darwin GOARCH=amd64) Golds is a Go 101 project developed by Tapir Liu. PR and bug reports are welcome and can be submitted to the issue list. Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds. |