trace

type Carrier ¶

type Carrier interface {
	Get(key string) string
	Set(key, value string)
}

Carrier is the two-method surface a header set has to present for a span context to travel through it.

It is exactly http.Header's Get/Set pair, on purpose and to the letter, so `trace.Inject(ctx, req.Header)` compiles with no adapter — and so this package still imports no net/http, which would drag an HTTP opinion into a contract that also has to serve a message queue and a gRPC metadata map.

IFACE-PLUGIN: it is FROZEN at two methods (ADR 0039). Adding a third — Del, Values, a multi-value read — would break every downstream two-method double at compile time with no deprecation window, and every one of those additions is reachable as a sibling interface instead. Two is also what makes http.Header satisfy it structurally, which is the whole ergonomics.

type EventValue ¶

type EventValue struct {
	// Time is when it happened. An unset instant encodes as 0, which is what
	// the schema means by an unknown timestamp.
	Time time.Time
	// Name is the event's low-cardinality label.
	Name string
	// Attrs are the event's typed dimensions, sorted by Key.
	Attrs []coremetrics.AttrValue
}

EventValue is one thing that happened at an instant during a span, rather than over an interval — `opentelemetry/proto/trace/v1.Span.Event`.

An event is not a cheap child span, and the distinction is worth stating because the wrong choice is invisible until a trace is unreadable: an event has no identity, no duration and no children, so nothing can be a child of it and nothing can link to it. Use one for a moment worth marking on a span's timeline (a retry, a cache miss, an exception); use a child span for work that took time.

func (e EventValue) Normalized() EventValue

type ExporterName ¶

type ExporterName string

ExporterName is the typed key under which a SpanExporter registers (e.g. "otlpjson"). The zero value ExporterName("") is reserved invalid.

The registry is deliberately the same shape as core/metrics' — named, reached by blank-importing the exporter's package, config-addressable. It EARNS its keep here for the reason it earns it there and for one more: ADR 0051 §Decision 5 requires the OTLP/HTTP emitter to be absent from it, and "absent from the registry" is only a statement anyone can check if there is a registry to be absent from. A test pins that absence.

func AvailableExporters() []ExporterName

func (n ExporterName) String() string

type LinkValue ¶

type LinkValue struct {
	// Context identifies the linked span. A link whose context is invalid is
	// dropped rather than emitted — it names nothing.
	Context SpanContextValue
	// Attrs describe the relationship, sorted by Key.
	Attrs []coremetrics.AttrValue
}

LinkValue points at a span that is causally related to this one but is not its parent — `opentelemetry/proto/trace/v1.Span.Link`.

The canonical case is a batch: one consumer span processes fifty messages produced by fifty different traces. Making any one of them the parent would be a lie about forty-nine, and making the batch a child of all fifty is not a tree. A link says "related, elsewhere" without claiming ancestry.

It carries a whole SpanContextValue rather than a loose trace-id/span-id pair because the linked context's tracestate and sampled bit are part of what a backend needs: a link into a trace that was never sampled points at spans nobody stored.

func (l LinkValue) IsValid() bool

func (l LinkValue) Normalized() LinkValue

type Sampler ¶

type Sampler func(params SamplingParams) bool

Sampler decides whether a span is recorded and exported. It reports true to keep the span, false to drop it.

It is a FUNC port, not an interface, applying ADR 0041 structurally: a published func type cannot grow a method at all, so there is no widening to forbid and no sibling to invent later.

The decision is taken ONCE, at the root ¶

This is the load-bearing rule of the whole domain and it is not a convention — it is what the `sampled` bit of traceparent is FOR. A Tracer consults a Sampler only when it is starting a root span; every child, in this process or in any process downstream, inherits the answer through SpanContextValue.IsSampled.

Deciding per span produces a trace with holes in the middle, and a trace with holes is worse than no trace: a span whose parent was dropped becomes an orphan a backend renders as its own root, so one request appears as several unrelated ones and the latency of the whole is unrecoverable. The failure is also invisible at the point that causes it — the process that dropped the parent shows nothing wrong at all.

A Sampler is therefore consulted on ROOT spans only. That is a property of the Tracer, stated here because this is where a reader will look for it.

Concurrency ¶

A Sampler MUST be safe for concurrent use and MUST NOT block: it runs inline on the goroutine starting the span, before any work the span measures.

type SamplingParams ¶

type SamplingParams struct {
	// Parent is the context this span descends from, or the invalid zero
	// value when this is a root.
	Parent SpanContextValue
	// TraceID is the trace the new span belongs to.
	TraceID TraceID
	// Name is the span's operation name.
	Name string
	// Kind is the span's relationship to its neighbours.
	Kind SpanKind
	// Attrs are the attributes supplied at Start, sorted by Key. Attributes
	// added AFTER Start are invisible here — the decision has already been
	// taken by then, which is the price of taking it once.
	Attrs []coremetrics.AttrValue
	// Links are the links supplied at Start.
	Links []LinkValue
}

SamplingParams is everything a Sampler sees. It describes a span that does not exist yet, which is the point: the decision is taken before the span is created, so an unsampled span costs no recording at all.

TraceID is present and Parent may not be. On a ROOT span the trace id has just been minted and there is no parent; on a CHILD it is the parent's, inherited unchanged. A ratio sampler reads it either way, which is what makes the same sampler usable at both ends without a special case.

type Span ¶

type Span interface {
	// SpanContext returns the span's identity — what Inject propagates.
	SpanContext() SpanContextValue
	// SetAttrs adds or replaces typed dimensions on the span.
	SetAttrs(attrs ...coremetrics.AttrValue)
	// AddEvent records a timestamped point inside the span.
	AddEvent(name string, attrs ...coremetrics.AttrValue)
	// SetStatus records the operation's outcome.
	SetStatus(code StatusCode, message string)
	// End closes the span and hands it to the Tracer's SpanSink.
	End()
}

Span is one live, recording span.

IFACE-PLUGIN: FROZEN at five methods (ADR 0039). Two things a reader will expect and not find, each deliberate:

• There is no RecordError. It would have to decide what an error's TYPE is, which is a judgement about the caller's error model, and it is expressible as one AddEvent call. pkg/v1/trace ships it as a HELPER over this port instead, which is exactly the shape that does not freeze a decision into a port.
• End takes no timestamp. A span that ends at a time other than "now" is either replaying history or working around a clock, and both want a sibling interface rather than a parameter every caller has to pass a zero value to.

Every method is safe for concurrent use and every one is a NO-OP on an unsampled span, so instrumentation costs nothing when sampling is off. End is idempotent: the second call is ignored rather than emitting the span twice.

type SpanContextValue ¶

type SpanContextValue struct {
	// TraceID identifies the whole trace. Shared by every span in it.
	TraceID TraceID
	// SpanID identifies this span within the trace.
	SpanID SpanID
	// Flags is the traceparent flag byte, kept EXACTLY as received. Undefined
	// bits are masked at format time (TraceFlags.Sanitized), never on receipt.
	Flags TraceFlags
	// State is the tracestate list travelling beside the traceparent. It is
	// propagated verbatim; this SDK adds no entry of its own.
	State StateValue
	// Remote reports whether this context was EXTRACTED from a carrier rather
	// than created in this process. OTLP carries the fact as a span flag, and
	// a backend needs it to tell "my caller" from "my own parent span".
	Remote bool
}

SpanContextValue is the immutable identity of a span: what traceparent and tracestate carry between two processes, and what a child span inherits.

It is a VALUE, not a handle. A span context can be copied, compared field by field and stored on a context.Context without any of it referring back to a live span — which is what makes propagation across a process boundary the same operation as propagation across a function call.

The zero value is the INVALID context, and that is deliberate rather than incidental: an all-zero TraceID is exactly what W3C Trace Context §3.2.2.3 declares invalid, so "no trace here" and "a trace nobody may join" are one value with one spelling. Every consumer therefore has exactly one check to make — IsValid — instead of a nil test and a validity test that can disagree.

func Extract(carrier Carrier) SpanContextValue

func ParseTraceParent(header string) (context SpanContextValue, err error)

func SpanContextFromContext(ctx context.Context) SpanContextValue

func (c SpanContextValue) IsSampled() bool

func (c SpanContextValue) IsValid() bool

func (c SpanContextValue) WithState(state StateValue) SpanContextValue

type SpanExporter ¶

type SpanExporter interface {
	Name() ExporterName
	Export(spans SpansValue) error
}

SpanExporter ships a batch of finished spans to a backend. Implementations MUST be safe for concurrent use.

IFACE-PLUGIN: the registry stores plug-in exporters behind this interface; concrete exporter types stay unexported per package.

func LookupExporter(name ExporterName) (e SpanExporter, ok bool)

func RegisterExporter(e SpanExporter) SpanExporter

type SpanID ¶

type SpanID [SpanIDLen]byte

SpanID identifies one span within a trace: 8 bytes, 16 lowercase hex digits. The all-zero value is invalid for the same normative reason TraceID's is (§3.2.2.4), and is additionally how "this span has no parent" is spelled — a root span's ParentSpanID is the zero value, which OTLP encodes as an omitted parentSpanId.

func ParseSpanID(text string) (id SpanID, err error)

func (s SpanID) IsValid() bool

func (s SpanID) String() string

type SpanKind ¶

type SpanKind int32

SpanKind says how a span relates to its parent and its children, which is what lets a backend assemble a latency waterfall instead of a flat list.

The five values and their integers are opentelemetry/proto/trace/v1.Span.SpanKind, copied from the schema so the OTLP encoder emits the integer directly (OTLP/JSON encodes an enum as its NUMBER, never as its name).

const (
	// SpanKindUnspecified is SPAN_KIND_UNSPECIFIED (0). It is the zero value,
	// and the schema's own comment says an implementation should set INTERNAL
	// instead — so it CLAMPS rather than travels (ADR 0031 §clamp): a span
	// created with no stated kind is doing work inside this process, which is
	// what INTERNAL means. Nothing this SDK emits carries it.
	SpanKindUnspecified SpanKind = iota
	// SpanKindInternal is SPAN_KIND_INTERNAL (1): work inside one process,
	// with no remote counterpart.
	SpanKindInternal
	// SpanKindServer is SPAN_KIND_SERVER (2): handling an inbound synchronous
	// request. Its parent is normally a remote CLIENT span.
	SpanKindServer
	// SpanKindClient is SPAN_KIND_CLIENT (3): making an outbound synchronous
	// request and waiting for it.
	SpanKindClient
	// SpanKindProducer is SPAN_KIND_PRODUCER (4): enqueuing a message whose
	// handling happens later, and elsewhere.
	SpanKindProducer
	// SpanKindConsumer is SPAN_KIND_CONSUMER (5): handling a message that was
	// enqueued earlier. Its parent finished long before it started, which is
	// why it is not simply a SERVER span.
	SpanKindConsumer
)

func (k SpanKind) Resolved() SpanKind

func (k SpanKind) String() string

type SpanParams ¶

type SpanParams struct {
	// Kind is the span's relationship to its neighbours. The zero value
	// resolves to SpanKindInternal (SpanKind.Resolved).
	Kind SpanKind
	// Attrs are the dimensions known at Start. They are the ONLY ones a
	// Sampler sees, so anything the sampling decision depends on belongs here
	// rather than in a later SetAttrs.
	Attrs []coremetrics.AttrValue
	// Links point at causally related spans in other traces.
	Links []LinkValue
	// StartTime overrides the span's start instant. The zero value means
	// "now", which is what every caller but a replaying one wants — and it is
	// a CLAMP rather than a refusal because "now" is a description of what the
	// tracer does, not a value chosen on the caller's behalf (ADR 0031).
	StartTime time.Time
}

SpanParams are the facts a span is born with.

It is a struct rather than a variadic option list because an option type is a published func the SDK would then have to freeze (ADR 0039), and because the zero value has to be usable: SpanParams{} is an INTERNAL span starting now with no attributes, which is the common case and reads as one at the call site.

type SpanSink ¶

type SpanSink func(span SpanValue)

SpanSink receives every span that ends and was sampled. It is where a Tracer hands its output, and it is a func port for the reason Sampler is.

It is the seam a batching processor would occupy (ADR 0051 §Deferred): a batch is a SpanSink that buffers and forwards, which is why the port is one span at a time rather than a slice — a sink that took slices would force every non-batching consumer to allocate one.

A SpanSink MUST be safe for concurrent use: spans end on whichever goroutine was doing the work. It runs on that goroutine, so a slow sink slows the request it is observing.

type SpanValue ¶

type SpanValue struct {
	// Context identifies this span: trace-id, span-id, flags, tracestate.
	Context SpanContextValue
	// Parent identifies the span this one descends from. The zero value means
	// this is a root span.
	Parent SpanContextValue
	// Name is the low-cardinality operation label a backend groups on.
	Name string
	// Kind is the span's relationship to its neighbours, already resolved —
	// never SpanKindUnspecified on a span a Tracer produced.
	Kind SpanKind
	// StartTime opens the interval the span covers.
	StartTime time.Time
	// EndTime closes it. A span whose EndTime is unset never ended, and no
	// exporter in this SDK will ship one.
	EndTime time.Time
	// Attrs are the span's typed dimensions, sorted by Key.
	Attrs []coremetrics.AttrValue
	// Events are timestamped points inside the interval, in the order they
	// were recorded.
	Events []EventValue
	// Links point at causally related spans in other traces.
	Links []LinkValue
	// Status is the recorded outcome, already resolved.
	Status StatusValue
}

SpanValue is a completed span: the OpenTelemetry trace data model's `Span` message, in Go.

It is IMMUTABLE and it is what a live Span becomes at End. Splitting the two is what keeps an exporter from ever seeing a span mid-flight: the recording type has mutators and no exporter can reach it, this one has no mutators and is all an exporter is given.

Two fields are whole SpanContextValues rather than loose identifiers, and both pay for themselves:

• Context carries the trace-id, the span-id, the sampled bit and the tracestate as ONE value — the same value that travelled in the traceparent, so nothing has to be reassembled to know what was propagated.
• Parent carries its own Remote flag, which is the only place the fact is recorded that this span's parent ran in another process. OTLP has a field for exactly that (`flags`, SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK), and a backend uses it to tell a service boundary from an internal call.

A root span's Parent is the invalid zero value, which OTLP encodes as an omitted parentSpanId — the schema's own spelling for "no parent".

func (s SpanValue) Duration() time.Duration

func (s SpanValue) IsRoot() bool

type SpansValue ¶

type SpansValue struct {
	// Resource identifies the producer, carried once for the whole payload.
	Resource coremetrics.ResourceValue
	// Scope identifies the instrumentation, carried once for the whole
	// payload.
	Scope coremetrics.ScopeValue
	// Spans are the finished spans, in the order they ended. That order is
	// stable and is what makes an exporter's output diffable; it is NOT
	// causal — a parent ends after its children.
	Spans []SpanValue
}

SpansValue is a batch of finished spans plus the two facts that describe all of them at once — the OTLP payload hierarchy flattened into one Go value.

It is the trace counterpart of metrics' SnapshotValue and it is shaped by the same rule (ADR 0044 §Decision 9): an OTLP encoder must be able to walk it WITHOUT regrouping or reconstruction.

SpansValue            -> resourceSpans[0]
  .Resource           ->   .resource.attributes
  .Scope              ->   .scopeSpans[0].scope {name, version}
  .Spans[i]           ->   .scopeSpans[0].spans[]

The two single-element levels are single because one Tracer has exactly one Resource and one Scope, exactly as one Meter does.

It carries NO StartTime/Time pair, and that absence is the model rather than an omission: a metrics snapshot is one window shared by every point, while every span carries its own interval. Copying a payload-level window down onto a span would overwrite the only timestamps a trace has.

func (s SpansValue) IsEmpty() bool

type StateValue ¶

type StateValue struct {
	// contains filtered or unexported fields
}

StateValue is the parsed `tracestate` header: an ORDERED list of vendor entries, leftmost first.

The order is load-bearing and is the reason this is not a map. §3.5 states it twice over: "the order of unmodified key/value pairs MUST be preserved" and "modified keys SHOULD be moved to the beginning (left) of the list", because the leftmost entry is the system that touched the trace most recently. A map would lose exactly that, and lose it silently.

The value is IMMUTABLE: Insert and Delete return a new StateValue rather than mutating the receiver, so a span context handed to a handler cannot be edited underneath the caller that produced it. The zero value is a valid empty list.

This SDK writes NO entry of its own. It is not a tracing vendor with state to carry, and inventing a key would put a name nobody registered on every outbound request; Insert exists for a consumer who IS one.

func ParseTraceState(header string) (state StateValue, err error)

func (s StateValue) Delete(key string) StateValue

func (s StateValue) Get(key string) (value string, ok bool)

func (s StateValue) Insert(key, value string) (state StateValue, err error)

func (s StateValue) Len() int

func (s StateValue) String() string

type StatusCode ¶

type StatusCode int32

StatusCode is opentelemetry/proto/trace/v1.Status.StatusCode. Three values, and the third is not the negation of the second.

const (
	// StatusUnset is STATUS_CODE_UNSET (0), the default and the overwhelmingly
	// common value. It means "no explicit judgement was recorded" — NOT "it
	// worked". A backend applies its own heuristics (an HTTP 5xx, a timeout);
	// an SDK claiming OK on the caller's behalf would suppress exactly those.
	StatusUnset StatusCode = iota
	// StatusOK is STATUS_CODE_OK (1): the developer explicitly asserted
	// success, which the specification says should override any backend
	// heuristic. It is therefore a claim, never set by this SDK on its own.
	StatusOK
	// StatusError is STATUS_CODE_ERROR (2): the operation failed.
	StatusError
)

func (c StatusCode) String() string

type StatusValue ¶

type StatusValue struct {
	// Code is the verdict.
	Code StatusCode
	// Message describes the failure. It is dropped unless Code is
	// StatusError, and it is the ONE free-text field a span carries — so it
	// must not be given a value the operator cannot see safely. It is not an
	// errs Public: a span message is read by whoever reads the trace.
	Message string
}

StatusValue is a span's recorded outcome.

The Message field is only meaningful on StatusError, and the schema says so: "message … SHOULD be used only if the code is ERROR". This type enforces it in Resolved rather than trusting the caller, because a message hanging off an OK status is the sort of thing that renders as an error in one backend's UI and vanishes in another's.

func (s StatusValue) IsUnset() bool

func (s StatusValue) Resolved() StatusValue

type TraceFlags ¶

type TraceFlags byte

TraceFlags is the 8-bit field traceparent carries as its last component.

Version 00 of the specification defines exactly one bit, and §3.2.2.5.2 is explicit about the rest: "The behavior of other flags … is not defined and is reserved for future use. Vendors MUST set those to zero." This SDK therefore MASKS on output rather than trusting what it was handed — see Sanitized.

const FlagSampled TraceFlags = 0x01

func (f TraceFlags) IsSampled() bool

func (f TraceFlags) Sanitized() TraceFlags

func (f TraceFlags) WithSampled(sampled bool) TraceFlags

type TraceID ¶

type TraceID [TraceIDLen]byte

TraceID identifies one trace: 16 bytes, rendered as 32 lowercase hex digits on the wire.

The ALL-ZERO value is invalid, and that is normative rather than stylistic — W3C Trace Context §3.2.2.3 says a receiver "MUST ignore the traceparent" when the trace-id is all zeroes, and the OTLP schema documents the same. It is therefore the zero value of this type AND its "unset" spelling, which is why IsValid exists and why nothing in this package accepts an id without asking.

func ParseTraceID(text string) (id TraceID, err error)

func (t TraceID) IsValid() bool

func (t TraceID) String() string

type Tracer ¶

type Tracer interface {
	Start(ctx context.Context, name string, params SpanParams) (child context.Context, span Span)
}

Tracer starts spans. It is the only way a span comes into existence.

IFACE-PLUGIN: it is FROZEN at one method (ADR 0039). Everything a caller might want to add — a second Start taking an explicit clock, a Flush, a Shutdown — is reachable as a sibling interface or as a method on the concrete type, and none of them is worth breaking every downstream double for.

Start returns a context carrying the new span's context, so a callee that starts its own span becomes a child without either function naming the other. The Span is returned separately rather than fished back out of the context, because a caller who has to look up the span they just created will eventually look up the wrong one.

An EMPTY name panics with InvalidSpanName: a span name is the low-cardinality operation label every backend groups on, it is a literal at the call site, and it is therefore wrong on the first call or never — the same argument that makes an unusable attribute key a panic in `metrics`.