Spans and traces
Last updated · 7 minute read
What is a span?
A span represents a single named operation in a distributed system: a database query, an outbound HTTP request, a queue publish. Every span has a start time, a duration, an operation name, and a set of structured key-value attributes.
{
"name": "GET /checkout",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"start_unix_nano": 1774612800000000000,
"duration_ms": 148.2,
"attributes": { "http.status_code": 200, "tenant": "acme" }
}
Parent and child spans
Spans form a tree. The root span is the entry point of a request, typically the inbound HTTP handler. Each downstream operation opens a child span
whose parent_span_id points back at the caller.
TraceContext propagation
Helix uses W3C TraceContext headers, traceparent and tracestate, to carry the trace ID across service boundaries. Most
OpenTelemetry SDKs propagate these by default. Press Ctrl + K in the dashboard to jump to a trace by ID.
| Header | Required | Purpose |
|---|---|---|
traceparent |
Yes | Trace ID, parent span ID, and sampling flag. |
tracestate |
No | Vendor-specific state carried alongside the trace. |
x-helix-tenant |
No | Overrides tenant attribution for shared collectors. |
Sampling decisions
By default Helix samples at the root, before any work happens. Tail-based sampling is available on Scale plans, for cases where the decision has to wait until the full trace is known.