> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Span Sampling
> Explains OpenTelemetry span sampling, timing, common samplers, and head versus tail sampling, plus configuration to control telemetry volume, cost, and trace consistency.
In this lesson, we explain span sampling in OpenTelemetry: what it is, why it matters, where it applies, common samplers, and how to configure head-based sampling. Sampling controls which spans are recorded and exported so you can retain meaningful telemetry while reducing cost, load, and noise.
A span is the basic unit of a trace. Sampling is the mechanism that decides whether a span (and usually its associated trace) is recorded or dropped. Effective sampling improves signal-to-noise, lowers network and storage costs, and keeps backend systems performant.
Why sampling timing matters
* Sampling decisions are normally made at span creation time (head-based sampling). Making decisions at the source reduces the amount of telemetry transmitted and processed.
* The sampling decision affects child spans and downstream services—propagating a consistent decision prevents partial traces from being stored.
* Delaying decisions (tail-based sampling) allows using whole-trace attributes to make smarter sampling choices but requires collecting more data up-front and is typically implemented in the Collector.
Where sampling applies
* The sampler evaluates the current span at creation time and decides whether it should be recorded.
* Sampling decisions commonly propagate to child spans: if a parent is not sampled, child spans are typically dropped to keep trace consistency.
* Trace flags (for example, the sampled bit in the trace context) carry the sampling choice across process boundaries so the distributed system respects the decision end-to-end.
Built-in samplers (OpenTelemetry SDKs)
The following samplers are commonly available across OpenTelemetry SDKs. Use the option that best balances visibility and cost for your environment.
| Sampler | Purpose / Use Case | Example |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| AlwaysOnSampler | Records every span. Best for development, debugging, or short-lived environments where full visibility is required. | `AlwaysOnSampler()` |
| AlwaysOffSampler | Records no spans. Useful to keep instrumentation hooks enabled while disabling telemetry. | `AlwaysOffSampler()` |
| TraceIdRatioBasedSampler | Samples a fixed fraction of traces (head-based). Good for scalable production sampling (e.g., 10% or 20%). | `TraceIdRatioBased(0.2)` |
| ParentBasedSampler | Adopts the parent's sampling decision if present; otherwise falls back to a configured root sampler. Useful for distributed systems to maintain consistent downstream behavior. | `ParentBased(root=TraceIdRatioBased(0.2))` |
Configuring head-based sampling (SDK and environment)
Python SDK examples:
* Configure TraceIdRatioBased sampler at the SDK level for 20% sampling:
```python theme={null}
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.sampling import TraceIdRatioBased
provider = TracerProvider(sampler=TraceIdRatioBased(0.2)) # 20% sampling
```
* Combine ParentBased with TraceIdRatioBased as a fallback (parent decision preferred):
```python theme={null}
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.sampling import ParentBased, TraceIdRatioBased
# ParentBased uses the parent's decision if present; otherwise it falls back to TraceIdRatioBased.
provider = TracerProvider(sampler=ParentBased(root=TraceIdRatioBased(0.2)))
```
Agent / auto-instrumentation environment variables
For auto-instrumentation or agent-based setups you can change sampling without modifying application code. Example to set trace-id-ratio sampling to 20%:
```bash theme={null}
OTEL_TRACES_SAMPLER=traceidratio
OTEL_TRACES_SAMPLER_ARG=0.2
```
Head-based sampling makes the decision at span creation time (in the SDK). Tail-based sampling can make decisions later based on whole-trace information; tail-based sampling is typically implemented in the OpenTelemetry Collector.
Avoid AlwaysOn in high-volume production unless you have capacity for the inbound throughput, storage, and query costs. Use rate-limited or ratio-based sampling for scalable production environments.
Recap — best practices and recommendations
* Use AlwaysOn for complete visibility during development and troubleshooting.
* Use AlwaysOff to disable tracing while keeping instrumentation code intact.
* Use TraceIdRatioBased or ParentBased with a ratio fallback for production to reduce telemetry volume while preserving representative traces.
* Prefer making sampling decisions as close to the source as possible to minimize unnecessary network and backend load. If you need whole-trace signals (for anomaly detection or root-cause across entire traces), consider tail-based sampling implemented in the Collector.
Tail-based sampling
Tail-based sampling uses whole-trace attributes (durations, error rates, aggregated metrics) to decide which traces to keep. It typically runs in the OpenTelemetry Collector or a dedicated backend to avoid making suboptimal head-based decisions when trace-wide context is required. Tail-based approaches incur higher upfront collection cost but can yield more targeted sampling decisions for complex production use cases.
Links and references
* OpenTelemetry Tracing Concepts: [https://opentelemetry.io/docs/concepts/signals/traces/](https://opentelemetry.io/docs/concepts/signals/traces/)
* OpenTelemetry Collector: [https://opentelemetry.io/docs/collector/](https://opentelemetry.io/docs/collector/)
* SDK sampling configuration: [https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/](https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/)