opentelemetry.sdk.trace.sampling

For general information about sampling, see the specification.

OpenTelemetry provides two types of samplers:

A StaticSampler always returns the same sampling result regardless of the conditions. Both possible StaticSamplers are already created:

  • Always sample spans: ALWAYS_ON

  • Never sample spans: ALWAYS_OFF

A TraceIdRatioBased sampler makes a random sampling result based on the sampling probability given.

If the span being sampled has a parent, ParentBased will respect the parent delegate sampler. Otherwise, it returns the sampling result from the given root sampler.

Currently, sampling results are always made during the creation of the span. However, this might not always be the case in the future (see OTEP #115).

Custom samplers can be created by subclassing Sampler and implementing Sampler.should_sample as well as Sampler.get_description.

Samplers are able to modify the opentelemetry.trace.span.TraceState of the parent of the span being created. For custom samplers, it is suggested to implement Sampler.should_sample to utilize the parent span context’s opentelemetry.trace.span.TraceState and pass into the SamplingResult instead of the explicit trace_state field passed into the parameter of Sampler.should_sample.

To use a sampler, pass it into the tracer provider constructor. For example:

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    ConsoleSpanExporter,
    SimpleSpanProcessor,
)
from opentelemetry.sdk.trace.sampling import TraceIdRatioBased

# sample 1 in every 1000 traces
sampler = TraceIdRatioBased(1/1000)

# set the sampler onto the global tracer provider
trace.set_tracer_provider(TracerProvider(sampler=sampler))

# set up an exporter for sampled spans
trace.get_tracer_provider().add_span_processor(
    SimpleSpanProcessor(ConsoleSpanExporter())
)

# created spans will now be sampled by the TraceIdRatioBased sampler
with trace.get_tracer(__name__).start_as_current_span("Test Span"):
    ...

The tracer sampler can also be configured via environment variables OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG (only if applicable). The list of known values for OTEL_TRACES_SAMPLER are:

  • always_on - Sampler that always samples spans, regardless of the parent span’s sampling decision.

  • always_off - Sampler that never samples spans, regardless of the parent span’s sampling decision.

  • traceidratio - Sampler that samples probabalistically based on rate.

  • parentbased_always_on - (default) Sampler that respects its parent span’s sampling decision, but otherwise always samples.

  • parentbased_always_off - Sampler that respects its parent span’s sampling decision, but otherwise never samples.

  • parentbased_traceidratio - Sampler that respects its parent span’s sampling decision, but otherwise samples probabalistically based on rate.

Sampling probability can be set with OTEL_TRACES_SAMPLER_ARG if the sampler is traceidratio or parentbased_traceidratio, when not provided rate will be set to 1.0 (maximum rate possible).

Prev example but with environment vairables. Please make sure to set the env OTEL_TRACES_SAMPLER=traceidratio and OTEL_TRACES_SAMPLER_ARG=0.001.

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    ConsoleSpanExporter,
    SimpleSpanProcessor,
)

trace.set_tracer_provider(TracerProvider())

# set up an exporter for sampled spans
trace.get_tracer_provider().add_span_processor(
    SimpleSpanProcessor(ConsoleSpanExporter())
)

# created spans will now be sampled by the TraceIdRatioBased sampler with rate 1/1000.
with trace.get_tracer(__name__).start_as_current_span("Test Span"):
    ...
class opentelemetry.sdk.trace.sampling.Decision(value)[source]

Bases: enum.Enum

An enumeration.

DROP = 0
RECORD_ONLY = 1
RECORD_AND_SAMPLE = 2
is_recording()[source]
is_sampled()[source]
class opentelemetry.sdk.trace.sampling.SamplingResult(decision, attributes=None, trace_state=None)[source]

Bases: object

A sampling result as applied to a newly-created Span.

Parameters
class opentelemetry.sdk.trace.sampling.Sampler[source]

Bases: abc.ABC

abstract should_sample(parent_context, trace_id, name, kind=None, attributes=None, links=None, trace_state=None)[source]
Return type

SamplingResult

abstract get_description()[source]
Return type

str

class opentelemetry.sdk.trace.sampling.StaticSampler(decision)[source]

Bases: opentelemetry.sdk.trace.sampling.Sampler

Sampler that always returns the same decision.

should_sample(parent_context, trace_id, name, kind=None, attributes=None, links=None, trace_state=None)[source]
Return type

SamplingResult

get_description()[source]
Return type

str

opentelemetry.sdk.trace.sampling.ALWAYS_OFF = <opentelemetry.sdk.trace.sampling.StaticSampler object>

Sampler that never samples spans, regardless of the parent span’s sampling decision.

opentelemetry.sdk.trace.sampling.ALWAYS_ON = <opentelemetry.sdk.trace.sampling.StaticSampler object>

Sampler that always samples spans, regardless of the parent span’s sampling decision.

class opentelemetry.sdk.trace.sampling.TraceIdRatioBased(rate)[source]

Bases: opentelemetry.sdk.trace.sampling.Sampler

Sampler that makes sampling decisions probabilistically based on rate.

Parameters

rate (float) – Probability (between 0 and 1) that a span will be sampled

TRACE_ID_LIMIT = 18446744073709551615
classmethod get_bound_for_rate(rate)[source]
Return type

int

property rate
Return type

float

property bound
Return type

int

should_sample(parent_context, trace_id, name, kind=None, attributes=None, links=None, trace_state=None)[source]
Return type

SamplingResult

get_description()[source]
Return type

str

class opentelemetry.sdk.trace.sampling.ParentBased(root, remote_parent_sampled=<opentelemetry.sdk.trace.sampling.StaticSampler object>, remote_parent_not_sampled=<opentelemetry.sdk.trace.sampling.StaticSampler object>, local_parent_sampled=<opentelemetry.sdk.trace.sampling.StaticSampler object>, local_parent_not_sampled=<opentelemetry.sdk.trace.sampling.StaticSampler object>)[source]

Bases: opentelemetry.sdk.trace.sampling.Sampler

If a parent is set, applies the respective delegate sampler. Otherwise, uses the root provided at initialization to make a decision.

Parameters
  • root (Sampler) – Sampler called for spans with no parent (root spans).

  • remote_parent_sampled (Sampler) – Sampler called for a remote sampled parent.

  • remote_parent_not_sampled (Sampler) – Sampler called for a remote parent that is not sampled.

  • local_parent_sampled (Sampler) – Sampler called for a local sampled parent.

  • local_parent_not_sampled (Sampler) – Sampler called for a local parent that is not sampled.

should_sample(parent_context, trace_id, name, kind=None, attributes=None, links=None, trace_state=None)[source]
Return type

SamplingResult

get_description()[source]
opentelemetry.sdk.trace.sampling.DEFAULT_OFF = <opentelemetry.sdk.trace.sampling.ParentBased object>

Sampler that respects its parent span’s sampling decision, but otherwise never samples.

opentelemetry.sdk.trace.sampling.DEFAULT_ON = <opentelemetry.sdk.trace.sampling.ParentBased object>

Sampler that respects its parent span’s sampling decision, but otherwise always samples.

class opentelemetry.sdk.trace.sampling.ParentBasedTraceIdRatio(rate)[source]

Bases: opentelemetry.sdk.trace.sampling.ParentBased

Sampler that respects its parent span’s sampling decision, but otherwise samples probabalistically based on rate.