Method Limit

modules/generator/registry/per_label_limiter.go:81–133

Limit applies the per-label cardinality limit to the given labels. Labels whose estimated cardinality exceeds the configured max have their value replaced with __cardinality_overflow__.

(lbls labels.Labels)

// Labels whose estimated cardinality exceeds the configured max have their
// value replaced with __cardinality_overflow__.
func (s *PerLabelLimiter) Limit(lbls labels.Labels) labels.Labels {
	// do maintenance check as the first thing to ensure maxCardinality
	// is refreshed from runtime overrides. without this,
	// a limiter that starts disabled would never be enabled without restart.
	s.doPeriodicMaintenance()

	// maxCardinality is zero, so limiter is disabled, return labels as is
	if s.maxCardinality.Load() == 0 {
		return lbls
	}

	s.mtx.Lock()
	defer s.mtx.Unlock()

	// Defer builder creation until we actually need to modify a label.
	// In the common case (no overflow), we avoid the allocations entirely.
	var builder *labels.Builder
	lbls.Range(func(l labels.Label) {
		// skip over the metadata labels
		if schema.IsMetadataLabel(l.Name) {
			return
		}

		state := s.getOrCreateState(l.Name)

		// we always insert the ORIGINAL value to hash even while overflowing,
		// which prevents the estimate from artificially dropping.
		// It will make sure that recovery (label going back under limit) only happens when the
		// actual incoming data has lower cardinality AND the old sketches have been rotated out.
		//
		// If we inserted the overflowValue, then the estimate would drop and cause oscillation:
		// over limit -> Add overflowValue -> estimate drops -> under limit -> real values -> over limit ->...
		// Insert acquires its own internal mu lock on the sketch.
		state.sketch.Insert(xxhash.Sum64String(l.Value))

		// we are over the limit, replace label value and capture the metric
		if state.overLimit {
			// Lazy init: only create once, so previous Set calls are preserved
			// when multiple labels overflow in the same series
			if builder == nil {
				builder = labels.NewBuilder(lbls)
			}
			builder.Set(l.Name, overflowValue)
			metricLabelValuesLimited.WithLabelValues(s.tenant, l.Name).Inc()
		}
	})

	// No labels were limited, return the original labels as is.
	if builder == nil {
		return lbls
	}
	return builder.Labels()
}

func (s *PerLabelLimiter) getOrCreateState(labelName string) *labelCardinalityState {
	state, ok := s.labelsState[labelName]