You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add semantically correct PromQL limit_ratio(r, v) support to the ALB Time
Series Merge (TSM) mechanism.
For a fixed ratio, Prometheus selects each input sample independently using a
deterministic hash of its complete label set. This selection is distributive
across shards: selecting on each shard and then unioning/deduplicating the
results is equivalent to selecting from the combined input vector. However,
the inner expression must itself have correct federated semantics. For example, limit_ratio(0.1, sum by (service) (...)) must globally merge the inner sum
before applying limit_ratio.
Scope
Support literal ratios in the full PromQL range [-1, 1], including the
complementary selection semantics of negative ratios.
Support both by (...) and without (...) grouping forms, before or after
the aggregation arguments.
Support instant and range queries.
Preserve float and native-histogram samples selected by the operator.
Preserve common outer sort and sort_desc wrappers with the same range
query behavior as Prometheus.
Remove the current inaccurate-result warning for supported expressions.
Retain a clear fallback warning for parameter expressions or nested query
shapes that the TSM planner cannot evaluate globally.
Implementation guidance
Add a parsed aggregation specification for limit_ratio containing the
ratio, inner query, grouping, and optional sort wrapper.
Add a fast path for a fixed ratio over a shard-local inner expression:
allow each Prometheus shard to apply limit_ratio, then use normal TSM
union/deduplication.
For an inner aggregation that TSM can merge, rewrite the request to the
inner expression, perform its global TSM merge, and apply limit_ratio
once in the finalizer.
Make the finalizer use a Prometheus-compatible label hash and threshold:
select hash/maxUint64 < r for non-negative r, and hash/maxUint64 >= 1+r for negative r.
Hash the labels visible to PromQL after any configured TSM-only injected
labels have been handled; do not let routing-only labels change the
sample set.
Treat unsupported or shard-dependent scalar parameter expressions
conservatively. Do not silently evaluate different ratios per shard.
Ensure partial fanout failure remains visible as an incomplete-global-
result warning.
Acceptance criteria
limit_ratio(r, v) returns the same label sets and values as a single
global Prometheus-compatible query layer for supported expressions.
Positive and negative complementary ratios produce complementary sets,
modulo the documented boundary behavior.
Ratios -1, 0, and 1 match Prometheus edge-case behavior.
Results are deterministic across repeated requests and independent of
ALB pool member ordering.
Duplicate HA replicas do not cause duplicate output series.
by and without grouping work for instant and range queries.
Supported queries no longer include the current inaccurate-result
warning.
Unsupported parameter or nested-expression forms retain an explicit
warning rather than returning silently inaccurate data.
Tests
Parser tests for prefix/postfix grouping, whitespace, negative ratios,
wrappers, malformed queries, and unsupported scalar expressions.
Unit tests for the hash threshold and negative-ratio complement.
Instant- and range-finalizer tests, including sparse timestamps and
native histograms.
Multi-shard tests with disjoint data, exact HA duplicates, unequal shard
sizes, and reordered pool members.
Nested merge test such as limit_ratio(0.5, sum by (service) (requests)).
Partial-failure and capture-limit tests.
Prometheus references
limit_ratio operator documentation
defines the ratio range, deterministic pseudo-random selection, negative
ratio complement, grouping behavior, and histogram support.
PromQL aggregation evaluator (engine.go)
contains HashRatioSampler, AddRatioSampleWithOffset, and the LIMIT_RATIO aggregation path. These are the compatibility reference for
label hashing, threshold comparisons, ratio clamping, and warnings.
Support semantically correct
limit_ratioin ALB TSM fanoutParent: #1068
Summary
Add semantically correct PromQL
limit_ratio(r, v)support to the ALB TimeSeries Merge (TSM) mechanism.
For a fixed ratio, Prometheus selects each input sample independently using a
deterministic hash of its complete label set. This selection is distributive
across shards: selecting on each shard and then unioning/deduplicating the
results is equivalent to selecting from the combined input vector. However,
the inner expression must itself have correct federated semantics. For example,
limit_ratio(0.1, sum by (service) (...))must globally merge the innersumbefore applying
limit_ratio.Scope
[-1, 1], including thecomplementary selection semantics of negative ratios.
by (...)andwithout (...)grouping forms, before or afterthe aggregation arguments.
sortandsort_descwrappers with the same rangequery behavior as Prometheus.
shapes that the TSM planner cannot evaluate globally.
Implementation guidance
limit_ratiocontaining theratio, inner query, grouping, and optional sort wrapper.
allow each Prometheus shard to apply
limit_ratio, then use normal TSMunion/deduplication.
inner expression, perform its global TSM merge, and apply
limit_ratioonce in the finalizer.
select
hash/maxUint64 < rfor non-negativer, andhash/maxUint64 >= 1+rfor negativer.labels have been handled; do not let routing-only labels change the
sample set.
conservatively. Do not silently evaluate different ratios per shard.
result warning.
Acceptance criteria
limit_ratio(r, v)returns the same label sets and values as a singleglobal Prometheus-compatible query layer for supported expressions.
modulo the documented boundary behavior.
-1,0, and1match Prometheus edge-case behavior.ALB pool member ordering.
byandwithoutgrouping work for instant and range queries.warning.
warning rather than returning silently inaccurate data.
Tests
wrappers, malformed queries, and unsupported scalar expressions.
native histograms.
sizes, and reordered pool members.
limit_ratio(0.5, sum by (service) (requests)).Prometheus references
limit_ratiooperator documentationdefines the ratio range, deterministic pseudo-random selection, negative
ratio complement, grouping behavior, and histogram support.
engine.go)contains
HashRatioSampler,AddRatioSampleWithOffset, and theLIMIT_RATIOaggregation path. These are the compatibility reference forlabel hashing, threshold comparisons, ratio clamping, and warnings.
labels.go)defines the
Labels.Hash()operation used byHashRatioSampler.documents the design rationale for deterministic hash sampling and negative
complementary ratios.
describes the experimental PromQL feature gate that includes
limit_ratio.Non-goals
operations cannot be planned by TSM.