Every public name.

Why a header, an id or a span id source was refused.

One error type for the whole module: a caller parsing an inbound traceparent and a caller handing the tracer a broken source of randomness both have one thing to catch.

Samples everything, whatever the parent said. The starting point for a service whose traffic is small enough to keep whole.

The three answers a sampler can give.

Throws spans away. The default for a tracer whose owner has not decided where they go yet, and the sink a replay uses when it only cares that nothing crashes.

How much a span gave up at its limits. OpenTelemetry asks for the counts rather than for the dropped values, so a reader can tell "this span had no attributes" from "this span had three hundred and we kept 128".

Something that happened during a span: a name, when it happened, and what it carried. Events keep the order they were added in, which for timestamps handed in by the caller is not necessarily the order of those timestamps.

How much one span collects.

The defaults are OpenTelemetry's: 128 attributes, 128 events, 128 links, 128 attributes on an event, and no limit on the length of a value. They exist to keep instrumentation that loops over user data from taking the process down with it, so the counts are per span and fixed when the span starts.

A causal relationship to another span that is not this one's parent — a batch item, a message consumed later, a fan-in. The linked context travels with the link so a reader can join the two traces.

Samples nothing. Useful behind parent_based, where it is the answer for a parent that was not sampled.

Follows the parent's decision and asks root only when there is no parent.

This is the sampler to give a service, because it is what keeps a distributed trace whole: the hop that made the decision decided for the whole trace, and every later hop obeys it instead of rolling its own dice.

The specification's five rows are the five fields: root without a parent, then a parent from another process or this one, sampled or not. The default for a sampled parent is always and for an unsampled one never, so a program that names only root follows the parent.

Samples a fixed fraction of traces, decided by the trace id rather than by a coin: the same id gets the same answer on every hop, in every process, and from every service, so a trace that one service keeps is not dropped by the next.

The fraction is read off the low 64 bits of the trace id, which the specification asks for so that two rates nest: raising the rate keeps every trace the lower rate kept.

Keeps spans in memory, in the order they finished.

Meant for replays, examples and the debugging of a single request; a service wants a sink that ships spans off the process, because this one grows without bound.

What a sampler is told about the span it is deciding on.

The four things a sampler may look at are all known before the span exists: the parent, the trace id the span will carry, its name and its kind. Later changes — a better name, an attribute discovered mid-request — cannot move the decision, which is why the decision is made here and not on the finished span.

The span a caller holds: an identity fixed at creation, and fields that fill in until it is finished.

Everything that changes after creation sits behind a Ref, so one span may be filled in from the task that opened it and read from another. A non-recording span — one the sampler dropped — accepts the same calls and forgets them, which is what lets instrumented code stay the same whatever the sampler decided.

A finished span, as a Sink receives it.

It is a value, not a handle: everything in it is settled, and a sink may keep it, queue it or throw it away. Nothing here is normalised — a span may begin and end at the same nanosecond, and an event may carry a time outside the span.

What a span is about, from the point of view of the process that made it. The kind is part of the sampling input and of what a backend draws, so it is settled when the span starts.

How the operation ended, as the caller judges it.

The three values form a total order, Ok above Error above Unset, and a status is judged against that order rather than by "last write wins": Ok is final, Error may replace another Error because the message may improve, and Unset is what a span already has.

Unset means "the caller has no opinion", which is not a failure: an instrumentation library leaves it alone unless the semantic conventions say otherwise.

The identity of a span: the trace it belongs to, its own id, the flags travelling with it, and the vendor state riding along.

Ids are octets, not text: sixteen for the trace and eight for the span, as W3C Trace Context lays them out. Hexadecimal is a spelling used at the wire and in logs, and it is produced there rather than stored here.

remote is the specification's IsRemote: true for a context read off the wire, false for one this process minted. It does not travel in any header.

Vendor state travelling with the trace, as an ordered list of at most 32 list-members (W3C Trace Context §3.3.1).

It is a list, not a map: the order is what a hop writes back, the first member belongs to the closest hop, and two members may not share a key. The update operations return a new state rather than editing this one, so that a caller holding the state that arrived cannot change what it arrived as.

Makes spans, and the one place ids and the sampling decision are settled.

A tracer holds three things it cannot invent for itself: where randomness comes from, where finished spans go, and who decides whether a trace is wanted. The clock is the fourth, and it does not even reach the tracer — every call that needs a time is handed one.

One attribute value.

The arrays are separate variants rather than one array of Value because OpenTelemetry requires an array attribute to be homogeneous, and because that is what an exporter has to write: a mixed array has no single type tag.

Whether a span is wanted, and how much of it.

A caller can plug in its own: the four here are the ones the specification names, and anything with a decision — a rate limit read from configuration, a list of paths that must never be dropped — is another implementation of this.

Where finished spans go.

This is the one seam this library leaves open: exporting to OTLP, to a file, to a ring buffer that a background task drains, or to nothing at all is the caller's business, and the shapes that do it belong to whoever owns the transport. A sink is called on the task that finished the span, so an implementation that writes to a socket should hand the span to a queue rather than block the request.

A sink receives every recorded span, including the ones the sampler dropped from the trace: SpanData::sampled is the bit that separates "keep for counting" from "send to the backend".

Keys and values carried alongside a trace, ordered, with duplicates allowed.

Order is part of the data: W3C Baggage asks a hop to preserve the order of duplicate entries when it mutates the list, so this is an array rather than a map. get answers with the first member carrying a key, which is the one a reader asking "what did the caller say" wants.

What a hop takes out of a set of request headers: the trace it joins, if the request carried one, and the baggage that came with it.

One value rather than two calls, because a hop that reads one and forgets the other is a bug this shape makes hard to write: inject puts back exactly what extract found, changed only where the caller changed it.

One baggage entry: a key, a value, and any properties attached to it.

The value is stored decoded, as text. The wire form is percent-encoded ASCII, and decoding is where a hop stops caring how the value was spelled.

One metadata entry on a baggage member: key or key=value, after the ; of a list-member (W3C Baggage §3.2.2.3). The specification gives properties no meaning of their own; they are carried so a hop that does not understand one can pass it on unchanged.

One server span per HTTP request, joined to the trace the request arrived with.

The layer does three things and no more: it reads traceparent and baggage off the request, it opens a span of kind Server as a child of what it read, and it writes the resulting context back on the response. A request that carried no context starts a trace; one that carried a broken context also starts a trace, because refusing the request over a header would be worse than a missing link in the trace.

The span reaches the sink when the application returns, with the response status on it. A request the application fails is recorded as an exception event before the error is passed on to the server, which is what an ASGI server keeps.