TimelessMetrics.PromQL (timeless_metrics v6.2.2)

Copy Markdown View Source

PromQL parser and evaluator for the Prometheus/VictoriaMetrics-compatible API.

A tokenizer + recursive-descent parser produces an AST; the evaluator fetches raw samples and evaluates Prometheus/VM semantics on an exact start + n*step grid — instant selectors take the most recent sample within the lookback window, range functions slide their [window] over raw samples, and counter functions (rate/increase/irate) are reset-adjusted with carry-in from before the window.

Supported

Effectively the full PromQL surface plus the common MetricsQL tier — every construct is verified against a live VictoriaMetrics instance by scripts/vm_diff.exs:

  • Selectors with all matcher types (duplicates AND together), offset, the @ modifier, subqueries [W:R], and step-relative [Ni] windows
  • Rollups: rate irate increase delta idelta deriv predict_linear changes resets and the *_over_time family (incl. quantile/stddev/ stdvar/present/last/first_over_time), window-less MetricsQL forms
  • Aggregations: sum avg min max count group stddev stdvar topk bottomk quantile count_values with by/without in either position
  • Binary operators with bool and full vector matching (on/ignoring/group_left/group_right), set ops, and the MetricsQL default/if/ifnot operators
  • histogram_quantile over classic le buckets
  • Transforms and math (abs ceil floor round clamp* sqrt exp ln log2 log10 sgn trig deg rad pi), label_replace label_join label_set label_del alias union sort sort_desc, absent absent_over_time, time timestamp scalar vector and the clock functions, keep_metric_names, range_*/running_*

Anything unsupported returns {:error, reason} — never a silent empty success — so API clients get a Prometheus-style error response.

Summary

Functions

execute(ast, store, start_ts, end_ts, step)

Evaluate a parsed AST over a time range against a store.

parse(query)

Parse a PromQL query string into an AST.

selector_info(ast)

Extract the first vector selector from an AST as %{metric: name | nil, metric_pattern: regex | nil, labels: map}.

Functions

execute(ast, store, start_ts, end_ts, step)

Evaluate a parsed AST over a time range against a store.

Evaluation follows Prometheus/VM semantics: every series is evaluated at the exact grid start, start+step, ..., end. Instant selectors take the most recent sample within the lookback window (default 300s, configure with config :timeless_metrics, promql_lookback_seconds: n); range functions evaluate over their [window] of raw samples ending at each grid point.

Returns {:ok, prometheus_matrix_response} or {:error, reason}.

parse(query)

Parse a PromQL query string into an AST.

Returns {:ok, ast} or {:error, reason}. Invalid or unsupported syntax is always an error — a query never silently degrades to a metric-name lookup.

selector_info(ast)

Extract the first vector selector from an AST as %{metric: name | nil, metric_pattern: regex | nil, labels: map}.

Used by the /api/v1/series endpoint, which only needs to know which series a match[] expression touches.