Rolling quantile

The rolling quantile advanced function bands each series with a quantile computed over a sliding window of past data, and flags values that fall outside the band. Because quantiles are stable metrics, this is a robust, assumption-free anomaly detector.

Concept diagram: a noisy series inside upper and lower rolling-quantile bands

Parameters

window

The rolling window in milliseconds — 1,800,000 ms for a 30-minute window.

bound

Width of the band adjustment in standard deviations: 1, 2, or 3.

band

Which band series to return: 4 = lower band, 5 = upper band, 6 = both.

How it works

To calculate the rolling quantile advanced function, we use the quantile_over_time function of the Prometheus engine.

To determine the upper and lower bounds, we adjust them using standard deviations. Instead of computing the standard deviation over the entire time range, we compute it over a specific window of past data.

When computing, we calculate the deviations over the original series and apply them to future events. This is because the standard deviations of the predicted bands are extremely close to zero. We chose this approach because quantiles are generally stable metrics.

Calculating the lower band
lower = avg_over_time(
  (quantile_over_time(0.16, $Query[5m:])
  -$Bound*stddev_over_time($Query[5m:]))[5m:])
none
Calculating the upper band
upper = avg_over_time(
  (quantile_over_time(0.84, $Query[5m:])
  +$Bound*stddev_over_time($Query[5m:]))[5m:])
none

In Dashboards

To use the kf_rolling_quantile operator in a dashboard, apply the following function:

kf_rolling_quantile( \
  ${promql}, \ (1)
  ${window}, \ (2)
  ${bound}, \ (3)
  ${band} \ (4)
)
none
1 ${promql}: PromQL query to evaluate
2 ${window}: Number of milliseconds in the window (1,800,000 ms for a 30-minute window)
3 ${bound}: Number of standard deviations (stdv): 1, 2, or 3
4 ${band}: 4 = lower band, 5 = upper band, 6 = both upper and lower bands

For the operator reference — syntax, parameters, and a validated example — see kf_rolling_quantile in the PromQL documentation.

Limitations

  • Because the operator uses quantiles to evaluate alert rules, the alert threshold gets triggered infrequently. That makes the rolling quantile less useful for alerts with a short window; a longer time window mitigates this.

  • The band is computed per input series; keep the series count low by aggregating first.

  • window is in milliseconds and must cover several data points at the query’s step, or the rolling quantile degenerates to the raw value.

Next steps

For an in-depth discussion of the rolling quantile functions, see these external resources: