Head-Based Sampling
Head-based sampling decides whether to record a trace at its start, before any outcome is known, and propagates that decision down the call graph.
Definition
Head-based sampling makes the keep-or-drop decision once, at the entry point of a request, and propagates it through the trace context so every downstream service records or skips consistently. Because the decision precedes execution, it cannot prioritise errors or slow requests; it can only be random, rate-based, or attribute-based on request properties known up front. Its advantage is simplicity and near-zero buffering cost.
Context and scope
The default sampling approach in most tracing SDKs, chosen when tracing overhead must be predictable and decisions must be made cheaply at high throughput.
Common misconceptions
- Head sampling cannot be tuned — it can, using rates or attributes, but never on the eventual outcome
- A low rate loses errors — errors are sampled with the same probability as successes, so a rare error may vanish
- Every service can decide independently — the decision must be propagated, or traces become inconsistent and truncated
Anti-patterns
- Setting a very low global rate and then hunting for a missing failure in production
- Letting each service re-sample, breaking trace completeness across the call graph
- Using head sampling when the only traces of interest are exceptions, where tail sampling is the right tool
Related concepts
Related examples
Authoritative source
What it is
Head-based sampling chooses at the root of a trace. The entry service applies a sampler — probabilistically, or by a rule on the incoming request — sets a sampled flag in the trace context, and every service that continues the trace honours it. No buffering, no cross-service coordination, and a decision cost that is a single comparison. The tradeoff is that the decision cannot see the outcome.
Why it matters
At high request volumes, recording every trace is neither affordable nor useful; a representative sample answers aggregate questions well. Head sampling delivers that sample with minimal runtime overhead and no dramatic change to the collector topology, which is why it remains the default. It also scales predictably: the trace volume is a known fraction of request volume, so capacity is easy to plan.
How to use it well
Choose a rate that keeps enough traces to debug typical problems, and vary it by endpoint — sampling a health check and a checkout equally wastes budget. Always sample traces that carry an explicit flag so critical flows can be captured on demand. Where errors and tail latency matter most, layer tail sampling behind the head decision rather than trying to fix it by raising the rate.