opentelemetry.sdk.trace.sampling¶

For general information about sampling, see the specification.

OpenTelemetry provides two types of samplers:

StaticSampler
TraceIdRatioBased

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)[source]¶

Bases: object

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

Parameters

decision (Decision) – A sampling decision based off of whether the span is recorded and the sampled flag in trace flags in the span context.
attributes (Optional[Mapping[str, Union[str, bool, int, float, Sequence[Optional[str]], Sequence[Optional[bool]], Sequence[Optional[int]], Sequence[Optional[float]]]]]) – Attributes to add to the opentelemetry.trace.Span.

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

Bases: abc.ABC

abstract should_sample(parent_context, trace_id, name, attributes=None, links=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)[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)[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)[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.