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 span’s sampling result. Otherwise, it returns the sampling result from the given delegate 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.

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,
    SimpleExportSpanProcessor,
)
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(
    SimpleExportSpanProcessor(ConsoleSpanExporter())
)

# created spans will now be sampled by the TraceIdRatioBased sampler
with trace.get_tracer(__name__).start_as_current_span("Test Span"):
    ...
class opentelemetry.sdk.trace.sampling.Decision[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, 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, attributes=None, links=None, trace_state=None)[source]
Return type

SamplingResult

get_description()[source]
Return type

str

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

Bases: opentelemetry.sdk.trace.sampling.Sampler

Sampler that makes sampling decisions probabalistically based on rate, while also respecting the parent span sampling decision.

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, attributes=None, links=None, trace_state=None)[source]
Return type

SamplingResult

get_description()[source]
Return type

str

class opentelemetry.sdk.trace.sampling.ParentBased(delegate)[source]

Bases: opentelemetry.sdk.trace.sampling.Sampler

If a parent is set, follows the same sampling decision as the parent. Otherwise, uses the delegate provided at initialization to make a decision.

Parameters

delegate (Sampler) – The delegate sampler to use if parent is not set.

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

SamplingResult

get_description()[source]
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.

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.