Skip to content

support promql limit_ratio in ALB TSM #1069

Description

@jranson

Support semantically correct limit_ratio in ALB TSM fanout

Parent: #1068

Summary

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

Non-goals

  • Building a general distributed evaluator for arbitrary scalar expressions.
  • Claiming correctness for an inner PromQL expression whose own cross-shard
    operations cannot be planned by TSM.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions