Class: Datadog::Core::KnuthSampler Private

Inherits:
Object
  • Object
show all
Defined in:
lib/datadog/core/knuth_sampler.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Deterministic sampler using Knuth multiplicative hash algorithm.

This sampler provides consistent sampling decisions based on an input value, ensuring the same input always produces the same sampling decision for a given rate.

The algorithm multiplies the input by a large prime (Knuth factor), takes modulo to constrain to a fixed range, and compares against a threshold derived from the sample rate.

See Also:

Constant Summary collapse

UINT64_MAX =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Maximum unsigned 64-bit integer for uniform distribution across 64-bit input space.

(1 << 64) - 1
UINT64_MODULO =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

1 << 64
DEFAULT_KNUTH_FACTOR =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Golden ratio constant for optimal distribution.

See Also:

11400714819323198485

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(rate = 1.0, knuth_factor: DEFAULT_KNUTH_FACTOR) ⇒ KnuthSampler

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of KnuthSampler.

Parameters:

  • rate (Float) (defaults to: 1.0) —

    Sampling rate between 0.0 and 1.0 (inclusive). 0.0 means no samples are kept; 1.0 means all samples are kept. Invalid values fall back to 1.0 (sample everything).

  • knuth_factor (Integer) (defaults to: DEFAULT_KNUTH_FACTOR) —

    Multiplicative constant for hashing. Different factors produce different sampling distributions.



31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/datadog/core/knuth_sampler.rb', line 31

def initialize(rate = 1.0, knuth_factor: DEFAULT_KNUTH_FACTOR)
  @knuth_factor = knuth_factor

  rate = rate.to_f
  unless rate >= 0.0 && rate <= 1.0
    Datadog.logger.warn("Sample rate #{rate} is not between 0.0 and 1.0, falling back to 1.0")
    rate = 1.0
  end

  @rate = rate
  @threshold = @rate * UINT64_MAX
end

Instance Attribute Details

#rate ⇒ Object (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



24
25
26
 
# File 'lib/datadog/core/knuth_sampler.rb', line 24

def rate
  @rate
end

Instance Method Details

#sample?(input) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Determines if the given input should be sampled.

This method is deterministic: the same input value always produces the same result for a given sample rate and configuration.

Parameters:

  • input (Integer) —

    Value to determine sampling decision. Typically a trace ID or incrementing counter.

Returns:

  • (Boolean) —

    true if input should be sampled, false otherwise



52
53
54
 
# File 'lib/datadog/core/knuth_sampler.rb', line 52

def sample?(input)
  ((input * @knuth_factor) % UINT64_MODULO) <= @threshold
end