Module: OpenTelemetry::SDK::Trace::Samplers

Defined in:
lib/opentelemetry/sdk/trace/samplers.rb,
lib/opentelemetry/sdk/trace/samplers/result.rb,
lib/opentelemetry/sdk/trace/samplers/decision.rb,
lib/opentelemetry/sdk/trace/samplers/probability_sampler.rb

Overview

The Samplers module contains the sampling logic for OpenTelemetry. The reference implementation provides a ProbabilitySampler, ALWAYS_ON, ALWAYS_OFF, and ALWAYS_PARENT.

Custom samplers can be provided by SDK users. The required interface is a callable with the signature:

(trace_id:, span_id:, parent_context:, hint:, links:, name:, kind:, attributes:) -> Result

Where:

Returns:

  • (Result) —

    The sampling result.

Defined Under Namespace

Modules: Decision Classes: ProbabilitySampler, Result

Constant Summary collapse

ALWAYS_ON =

Ignores all values in hint and returns a Result with Decision::RECORD_AND_SAMPLED.

->(trace_id:, span_id:, parent_context:, hint:, links:, name:, kind:, attributes:) { RECORD_AND_SAMPLED }
ALWAYS_OFF =

Ignores all values in hint and returns a Result with Decision::NOT_RECORD.

->(trace_id:, span_id:, parent_context:, hint:, links:, name:, kind:, attributes:) { NOT_RECORD }
ALWAYS_PARENT =

Ignores all values in hint and returns a Result with Decision::RECORD_AND_SAMPLED if the parent context is sampled or Decision::NOT_RECORD otherwise, or if there is no parent context. rubocop:disable Style/Lambda

->(trace_id:, span_id:, parent_context:, hint:, links:, name:, kind:, attributes:) do
  if parent_context&.trace_flags&.sampled?
    RECORD_AND_SAMPLED
  else
    NOT_RECORD
  end
end

Class Method Summary collapse

Class Method Details

.probability(probability, ignore_hints: [OpenTelemetry::Trace::SamplingHint::RECORD], ignore_parent: false, apply_probability_to: :root_spans_and_remote_parent) ⇒ Object

Returns a new sampler. The probability of sampling a trace is equal to that of the specified probability.

Parameters:

  • probability (Numeric) —

    The desired probability of sampling. Must be within [0.0, 1.0].

  • ignore_hints (optional Enumerable<Symbol>) (defaults to: [OpenTelemetry::Trace::SamplingHint::RECORD]) —

    Sampling hints to ignore. Defaults to ignore Trace::SamplingHint::RECORD.

  • ignore_parent (optional Boolean) (defaults to: false) —

    Whether to ignore parent sampling. Defaults to not ignore parent sampling.

  • apply_probability_to (optional Symbol) (defaults to: :root_spans_and_remote_parent) —

    Whether to apply probability sampling to root spans, root spans and remote parents, or all spans. Allowed values include :root_spans, :root_spans_and_remote_parent, and :all_spans. Defaults to :root_spans_and_remote_parent.

Raises:

  • (ArgumentError) —

    if probability is out of range

  • (ArgumentError) —

    if ignore_hints contains invalid hints

  • (ArgumentError) —

    if apply_probability_to is not one of the allowed symbols



89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/opentelemetry/sdk/trace/samplers.rb', line 89

def self.probability(probability,
                     ignore_hints: [OpenTelemetry::Trace::SamplingHint::RECORD],
                     ignore_parent: false,
                     apply_probability_to: :root_spans_and_remote_parent)
  raise ArgumentError, 'probability must be in range [0.0, 1.0]' unless (0.0..1.0).include?(probability)
  raise ArgumentError, 'ignore_hints' unless (ignore_hints.to_a - SAMPLING_HINTS).empty?
  raise ArgumentError, 'apply_probability_to' unless APPLY_PROBABILITY_TO_SYMBOLS.include?(apply_probability_to)

  ProbabilitySampler.new(probability,
                         ignore_hints: ignore_hints.to_a,
                         ignore_parent: ignore_parent,
                         apply_to_remote_parent: apply_probability_to != :root_spans,
                         apply_to_all_spans: apply_probability_to == :all_spans)
end