Sampler behaviour and dispatch
(trace/sdk.md §Sampler L329-L460).
A sampler decides whether a span should be recorded and/or sampled (propagated). Custom samplers implement this behaviour.
All sampler methods are safe for concurrent use, satisfying spec
trace/sdk.md L1284 — "Sampler — ShouldSample and
GetDescription MUST be safe to be called concurrently."
Public API
| Function / Callback | Role |
|---|---|
new/1 | SDK (lifecycle) — initialises a sampler from {module, opts} |
should_sample/7 | SDK (OTel API MUST) — trace/sdk.md §ShouldSample L342-L406 |
description/1 | SDK (OTel API MUST) — trace/sdk.md §GetDescription L408-L417 |
@callback setup/1 | SDK (lifecycle) |
@callback should_sample/7 | SDK (OTel API MUST) |
@callback description/1 | SDK (OTel API MUST) |
Built-in samplers
Otel.SDK.Trace.Sampler.AlwaysOn— every span sampledOtel.SDK.Trace.Sampler.AlwaysOff— every span droppedOtel.SDK.Trace.Sampler.ParentBased— defer to parent's sampled bitOtel.SDK.Trace.Sampler.TraceIdRatioBased— probabilistic by trace_id
Deferred Development-status features
- AlwaysRecord sampler decorator. Spec
trace/sdk.mdL608-L630 (Status: Development, added v1.51 #4699) defines a sampler decorator that wraps any sampler and forcesrecord_only(recording without propagation) when the inner sampler returnsdrop. Not implemented — no in-tree consumer. When stabilised it will live asOtel.SDK.Trace.Sampler.AlwaysRecord.
References
- OTel Trace SDK §Sampler:
opentelemetry-specification/specification/trace/sdk.mdL329-L460
Summary
Callbacks
Returns a human-readable description of the sampler.
Initializes sampler configuration from options.
Returns a sampling decision for a span to be created.
Functions
Returns the sampler's description.
Creates a sampler from a spec.
Invokes the sampler's should_sample callback.
Types
@type attributes() :: %{required(String.t()) => primitive_any()}
@type config() :: term()
@type description() :: String.t()
@type opts() :: term()
@type primitive_any() :: primitive() | [primitive_any()] | %{required(String.t()) => primitive_any()}
@type sampling_decision() :: :drop | :record_only | :record_and_sample
@type sampling_result() :: {sampling_decision(), attributes(), Otel.API.Trace.TraceState.t()}
@type t() :: {module(), description(), config()}
Callbacks
@callback description(config :: config()) :: description()
Returns a human-readable description of the sampler.
Initializes sampler configuration from options.
@callback should_sample( ctx :: Otel.API.Ctx.t(), trace_id :: Otel.API.Trace.TraceId.t(), links :: [Otel.API.Trace.Link.t()], name :: String.t(), kind :: Otel.API.Trace.SpanKind.t(), attributes :: attributes(), config :: config() ) :: sampling_result()
Returns a sampling decision for a span to be created.
Functions
@spec description(sampler :: t()) :: description()
Returns the sampler's description.
Creates a sampler from a spec.
Accepts {module, opts} and returns {module, description, config}.
@spec should_sample( sampler :: t(), ctx :: Otel.API.Ctx.t(), trace_id :: Otel.API.Trace.TraceId.t(), links :: [Otel.API.Trace.Link.t()], name :: String.t(), kind :: Otel.API.Trace.SpanKind.t(), attributes :: attributes() ) :: sampling_result()
Invokes the sampler's should_sample callback.