Repository: prometheus/prometheus
File: promql/engine.go (Go)

Code before:
// HashRatioSampler uses Hash(labels.String()) / maxUint64 as a "deterministic"
// value in [0.0, 1.0].
// It is a utility used for limit_ratio aggregations.
type HashRatioSampler struct{}

var ratiosampler RatioSampler = NewHashRatioSampler()

func NewHashRatioSampler() *HashRatioSampler {
	return &HashRatioSampler{}
}

func (s *HashRatioSampler) sampleOffset(_ int64, sample *Sample) float64 {
	return s.SampleOffsetByLabels(sample.Metric)
}

// SampleOffsetByLabels returns a deterministic sampling offset in the range [0, 1)
// derived from the hash of the provided metric labels.
//
// The offset is computed by normalizing the 64-bit hash value of the label set
// to a float64 fraction of math.MaxUint64. This ensures that metrics with the
// same label set always produce the same offset, while different label sets
// produce uniformly distributed offsets suitable for sampling decisions.
//
// Note that this function allows for the actual labels.Labels to be passed in,
// by passing the need to pass in a Sample. This allows downstream projects, such as
// Mimir to leverage this offset directly.
func (*HashRatioSampler) SampleOffsetByLabels(metric labels.Labels) float64 {
	const (
		float64MaxUint64 = float64(math.MaxUint64)
	)
	return float64(metric.Hash()) / float64MaxUint64
}

// AddRatioSample returns a bool indicating if the sampling offset for the given sample is
// within the given ratio limit.
//
// See SampleOffsetByLabels() for further details on the sample offset.
// See AddRatioSampleWithOffset() for further details on the ratioLimit and sampling offset comparison.
func (s *HashRatioSampler) AddRatioSample(ratioLimit float64, sample *Sample) bool {
	sampleOffset := s.sampleOffset(sample.T, sample)
	return s.AddRatioSampleWithOffset(ratioLimit, sampleOffset)
}

// AddRatioSampleWithOffset reports whether the given sampling offset falls within
// the specified ratio limit.
//
// The ratioLimit must be in the range [-1, 1]. The sampleOffset should be derived
// using SampleOffsetByLabels().
//
// When ratioLimit >= 0, the function returns true if sampleOffset < ratioLimit.
// When ratioLimit < 0, the function returns true if sampleOffset >= 1 + ratioLimit.

Review comment (suggestion):
I wouldn't call out Mimir in particular here.

It's also a bit weird to explain this relative to the "normal" case of passing in a `Sample`, which actually only exists in an unexported method.

Now that I'm looking at this in more detail, I have some other thoughts:

The `sampleOffset` method is only used once. And there is no implementation that uses the timestamp argument.

I would say, let's do the following:
- Kick out `sampleOffset` altogether (including removing it from the `RatioSampler` interface.
- Rename `SampleOffsetByLablels` to `SampleOffset` and add it to the `RatioSampler` interface.
- Adjust the one call site for `sampleOffset` to use the new `SampleOffset` with the one change of the call's argument from `sample` to `sample.Metric()`.

Code after:
	AddRatioSampleWithOffset(ratioLimit, sampleOffset float64) bool
}

// HashRatioSampler uses Hash(labels.String()) / maxUint64 as a "deterministic"
// value in [0.0, 1.0].
// It is a utility used for limit_ratio aggregations.
type HashRatioSampler struct{}

var ratiosampler RatioSampler = NewHashRatioSampler()

func NewHashRatioSampler() *HashRatioSampler {
	return &HashRatioSampler{}
}

// SampleOffset returns a deterministic sampling offset in the range [0, 1)
// derived from the hash of the provided metric labels.
//
// The offset is computed by normalizing the 64-bit hash value of the label set
// to a float64 fraction of math.MaxUint64. This ensures that metrics with the
// same label set always produce the same offset, while different label sets
// produce uniformly distributed offsets suitable for sampling decisions.
func (*HashRatioSampler) SampleOffset(metric *labels.Labels) float64 {
	const (
		float64MaxUint64 = float64(math.MaxUint64)
	)
	return float64(metric.Hash()) / float64MaxUint64
}

// AddRatioSample returns a bool indicating if the sampling offset for the given sample is
// within the given ratio limit.
//
// See SampleOffset() for further details on the sample offset.
// See AddRatioSampleWithOffset() for further details on the ratioLimit and sampling offset comparison.
func (s *HashRatioSampler) AddRatioSample(ratioLimit float64, sample *Sample) bool {
	sampleOffset := s.SampleOffset(&sample.Metric)
	return s.AddRatioSampleWithOffset(ratioLimit, sampleOffset)
}

// AddRatioSampleWithOffset reports whether the given sampling offset falls within
// the specified ratio limit.
//
// The ratioLimit must be in the range [-1, 1]. The sampleOffset should be derived
// using SampleOffset().
//
// When ratioLimit >= 0, the function returns true if sampleOffset < ratioLimit.
// When ratioLimit < 0, the function returns true if sampleOffset >= 1 + ratioLimit.
//
// Note that this method could be moved into AddRatioSample and removed from the Prometheus codebase,
// but it is useful for downstream projects using this code as a library.
func (*HashRatioSampler) AddRatioSampleWithOffset(ratioLimit, sampleOffset float64) bool {
	// If ratioLimit >= 0: add sample if sampleOffset is lesser than ratioLimit