Documentation
¶
Overview ¶
Package tracing preserves bounded W3C trace context without global providers, recording backends, request payloads or authentication capabilities.
Index ¶
- Constants
- func WithContext(ctx context.Context, value Context) (context.Context, error)
- func WithoutContext(ctx context.Context) context.Context
- type Context
- func FromContext(ctx context.Context) Context
- func New(sampled bool) (Context, error)
- func Parse(parent, state string) (Context, error)
- func Start(ctx context.Context, sampled bool) (context.Context, Context, error)
- func StartSampled(ctx context.Context, sampler Sampler) (context.Context, Context, error)
- func (c Context) Child(sampled bool) (Context, error)
- func (Context) Format(state fmt.State, _ rune)
- func (c Context) IsZero() bool
- func (c Context) LogValue() slog.Value
- func (c Context) MarshalJSON() ([]byte, error)
- func (c Context) Sampled() bool
- func (c Context) SpanID() SpanID
- func (c Context) TraceID() TraceID
- func (c Context) TraceParent() string
- func (c Context) TraceState() string
- func (c *Context) UnmarshalJSON(data []byte) error
- func (c Context) Validate() error
- func (c Context) WithState(state string) (Context, error)
- type Sampler
- type SpanID
- type TraceID
Constants ¶
const MaxParentBytes = 512
const MaxStateBytes = 512
const ParentHeader = "traceparent"
const StateHeader = "tracestate"
Variables ¶
This section is empty.
Functions ¶
func WithContext ¶
WithContext attaches a validated trace value to a nonnil context.
func WithoutContext ¶
WithoutContext starts a new trace boundary while preserving cancellation and all unrelated context values. HTTP ingress uses it to prevent a long-lived kernel span from becoming the parent of every independent incoming request.
Types ¶
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context is an immutable propagation snapshot. Trace IDs correlate operations, not users; do not infer authentication or authorization from trace metadata. Tracestate is opaque vendor data and is omitted from ordinary formatting.
func FromContext ¶
FromContext returns the attached trace context, or its zero value when absent or ctx is nil.
func Parse ¶
Parse accepts traceparent version 00 and the known prefix of future versions. Malformed parents fail without retaining their values. Invalid tracestate is discarded independently, as required by the W3C processing model. Adapters choose whether to trust propagation at their network boundary.
func Start ¶
Start derives one child operation, or starts a new root when the context has no trace. It preserves the caller's cancellation, deadlines and other values. An already-cancelled context still receives trace identity: the operation's cancellation remains the caller's concern and its observation is not dropped.
func StartSampled ¶
StartSampled is Start with a trace-ID based local sampling policy, such as RatioSampler. Incoming sampled flags never override the local decision.
func (Context) Child ¶
Child creates a new operation in the same trace. Its explicit sampling choice is local policy, not a requirement imposed by an untrusted caller's flag.
func (Context) IsZero ¶
IsZero reports whether identifiers, sampling flag, and trace state are all empty.
func (Context) LogValue ¶
LogValue keeps opaque vendor state out of structured logs even though an explicit MarshalJSON propagation snapshot includes it.
func (Context) MarshalJSON ¶
MarshalJSON is an explicit propagation boundary and includes vendor state. An absent trace should be omitted by its enclosing versioned envelope.
func (Context) TraceParent ¶
TraceParent emits the supported version 00 representation, retaining only the defined sampled flag. Zero context emits no propagation header.
func (Context) TraceState ¶
TraceState returns the trace state header value.
func (*Context) UnmarshalJSON ¶
UnmarshalJSON decodes a bounded traceparent and optional tracestate object, replacing the receiver only after validation.
type Sampler ¶
Sampler makes the local sampling decision for a new span from its trace ID. Deciding from the trace ID lets every span of one trace agree.
func RatioSampler ¶
RatioSampler samples the given fraction of traces deterministically by the random low 64 bits of the trace ID, so all processes using the same ratio agree for one trace. Zero samples nothing and one samples every trace.
type SpanID ¶
type SpanID [8]byte
SpanID is an eight-byte span identifier.
func (SpanID) MarshalText ¶
MarshalText encodes the span identifier as lowercase hexadecimal text.
func (*SpanID) UnmarshalText ¶
UnmarshalText decodes exactly 16 lowercase hexadecimal characters, replacing the receiver only on success.
type TraceID ¶
type TraceID [16]byte
TraceID is a sixteen-byte trace identifier.
func (TraceID) MarshalText ¶
MarshalText encodes the trace identifier as lowercase hexadecimal text.
func (*TraceID) UnmarshalText ¶
Text decoding supports owned diagnostics snapshots, including a zero parent ID for root spans. Propagation Context.Validate separately rejects zero IDs.
Source Files