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.

Headers Helix reads on ingest
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.