Over-time aggregations

Over-time functions aggregate the samples of each individual series across a range window. They complement the aggregation operators, which combine values across series at one instant — fleet summaries typically use both.

absent_over_time

Returns a single series with value 1 when the selector matched no samples anywhere in the range window, and nothing otherwise. The windowed form of absent, and the standard silence detector for alerting.

Syntax

absent_over_time(<metric>{<matchers>}[<range>])
none

Parameters

Parameter Required Description

<range>

Required

The silence window, such as [10m].
absent_over_time does not support the subquery form. It requires a raw metric selector, not a computed expression.

Example

Check for samples of a metric that does not exist on this cluster — the result is 1, the signal an alert would fire on.

absent_over_time(nonexistent_demo_metric{app_kubernetes_io_instance="kfuse"}[10m])
Expected output
app_kubernetes_io_instance Value

kfuse

1

When samples exist the result is empty — dashboards show no data and alert rules stay quiet.

avg_over_time

Averages the samples of each series within the range window — the standard smoothing wrapper for noisy gauges.

Syntax

avg_over_time(<metric>[<range>])
avg_over_time(<expr>[<range>:<step>])
none

The second form is a subquery: <expr> is any instant-vector PromQL expression evaluated at every <step> interval over the trailing <range> window. Use it when there is no raw metric to pass directly — for example, to smooth a rate() result.

Parameters

Parameter Required Description

<range>

Required

The trailing window to aggregate over.

<step>

Subquery only

The evaluation interval within the subquery window. Defaults to the global evaluation interval when omitted (written as [<range>:]).

Example

Apply avg_over_time to the query-service goroutine gauge over the last ten minutes, then average across pods for a single row.

avg by (app_kubernetes_io_name) (avg_over_time(go_goroutines{app_kubernetes_io_name="query-service"}[10m]))
Expected output
app_kubernetes_io_name Value

query-service

313.15

Over-time functions aggregate one series across time; the aggregation operators (sum, avg, …​) aggregate across series at one instant. Combine both for fleet summaries.

count_over_time

Counts the samples of each series within the range window — effectively a scrape-health measure.

Syntax

count_over_time(<metric>[<range>])
count_over_time(<expr>[<range>:<step>])
none

The second form is a subquery: <expr> is any instant-vector PromQL expression evaluated at every <step> interval over the trailing <range> window.

Parameters

Parameter Required Description

<range>

Required

The trailing window to aggregate over.

<step>

Subquery only

The evaluation interval within the subquery window. Defaults to the global evaluation interval when omitted (written as [<range>:]).

Example

Apply count_over_time to the query-service goroutine gauge over the last ten minutes, then average across pods for a single row.

avg by (app_kubernetes_io_name) (count_over_time(go_goroutines{app_kubernetes_io_name="query-service"}[10m]))
Expected output
app_kubernetes_io_name Value

query-service

19.89

Over-time functions aggregate one series across time; the aggregation operators (sum, avg, …​) aggregate across series at one instant. Combine both for fleet summaries.

last_over_time

Returns the newest sample of each series within the range window — the right reader for sparsely reported gauges.

Syntax

last_over_time(<metric>[<range>])
last_over_time(<expr>[<range>:<step>])
none

The second form is a subquery: <expr> is any instant-vector PromQL expression evaluated at every <step> interval over the trailing <range> window.

Parameters

Parameter Required Description

<range>

Required

The trailing window to aggregate over.

<step>

Subquery only

The evaluation interval within the subquery window. Defaults to the global evaluation interval when omitted (written as [<range>:]).

Example

Apply last_over_time to the query-service goroutine gauge over the last ten minutes, then average across pods for a single row.

avg by (app_kubernetes_io_name) (last_over_time(go_goroutines{app_kubernetes_io_name="query-service"}[10m]))
Expected output
app_kubernetes_io_name Value

query-service

313.16

Over-time functions aggregate one series across time; the aggregation operators (sum, avg, …​) aggregate across series at one instant. Combine both for fleet summaries.

max_over_time

Returns the largest sample of each series within the range window — peaks that a downsampled chart would hide.

Syntax

max_over_time(<metric>[<range>])
max_over_time(<expr>[<range>:<step>])
none

The second form is a subquery: <expr> is any instant-vector PromQL expression evaluated at every <step> interval over the trailing <range> window.

Parameters

Parameter Required Description

<range>

Required

The trailing window to aggregate over.

<step>

Subquery only

The evaluation interval within the subquery window. Defaults to the global evaluation interval when omitted (written as [<range>:]).

Example

Apply max_over_time to the query-service goroutine gauge over the last ten minutes, then average across pods for a single row.

avg by (app_kubernetes_io_name) (max_over_time(go_goroutines{app_kubernetes_io_name="query-service"}[10m]))
Expected output
app_kubernetes_io_name Value

query-service

316.70

Over-time functions aggregate one series across time; the aggregation operators (sum, avg, …​) aggregate across series at one instant. Combine both for fleet summaries.

min_over_time

Returns the smallest sample of each series within the range window.

Syntax

min_over_time(<metric>[<range>])
min_over_time(<expr>[<range>:<step>])
none

The second form is a subquery: <expr> is any instant-vector PromQL expression evaluated at every <step> interval over the trailing <range> window.

Parameters

Parameter Required Description

<range>

Required

The trailing window to aggregate over.

<step>

Subquery only

The evaluation interval within the subquery window. Defaults to the global evaluation interval when omitted (written as [<range>:]).

Example

Apply min_over_time to the query-service goroutine gauge over the last ten minutes, then average across pods for a single row.

avg by (app_kubernetes_io_name) (min_over_time(go_goroutines{app_kubernetes_io_name="query-service"}[10m]))
Expected output
app_kubernetes_io_name Value

query-service

310.97

Over-time functions aggregate one series across time; the aggregation operators (sum, avg, …​) aggregate across series at one instant. Combine both for fleet summaries.

present_over_time

Returns 1 for each series that has at least one sample within the range window — existence without caring about values.

Syntax

present_over_time(<metric>[<range>])
none

Parameters

Parameter Required Description

<range>

Required

The trailing window to aggregate over.
present_over_time does not support the subquery form. It requires a raw metric selector, not a computed expression.

Example

Apply present_over_time to the query-service goroutine gauge over the last ten minutes, then average across pods for a single row.

avg by (app_kubernetes_io_name) (present_over_time(go_goroutines{app_kubernetes_io_name="query-service"}[10m]))
Expected output
app_kubernetes_io_name Value

query-service

1

Over-time functions aggregate one series across time; the aggregation operators (sum, avg, …​) aggregate across series at one instant. Combine both for fleet summaries.

quantile_over_time

Computes the given quantile (0 to 1) of each series' samples within the range window.

Syntax

quantile_over_time(<q>, <metric>[<range>])
quantile_over_time(<q>, <expr>[<range>:<step>])
none

The second form is a subquery: <expr> is any instant-vector PromQL expression evaluated at every <step> interval over the trailing <range> window.

Parameters

Parameter Required Description

<q>

Required

The quantile, between 0 and 1.

<range>

Required

The trailing window to aggregate over.

<step>

Subquery only

The evaluation interval within the subquery window. Defaults to the global evaluation interval when omitted (written as [<range>:]).

Example

Apply quantile_over_time to the query-service goroutine gauge over the last ten minutes, then average across pods for a single row.

avg by (app_kubernetes_io_name) (quantile_over_time(0.95, go_goroutines{app_kubernetes_io_name="query-service"}[10m]))
Expected output
app_kubernetes_io_name Value

query-service

313.15

Over-time functions aggregate one series across time; the aggregation operators (sum, avg, …​) aggregate across series at one instant. Combine both for fleet summaries.

stddev_over_time

Computes the population standard deviation of each series' samples within the range window — how erratic the value is over time.

Syntax

stddev_over_time(<metric>[<range>])
stddev_over_time(<expr>[<range>:<step>])
none

The second form is a subquery: <expr> is any instant-vector PromQL expression evaluated at every <step> interval over the trailing <range> window.

Parameters

Parameter Required Description

<range>

Required

The trailing window to aggregate over.

<step>

Subquery only

The evaluation interval within the subquery window. Defaults to the global evaluation interval when omitted (written as [<range>:]).

Example

Apply stddev_over_time to the query-service goroutine gauge over the last ten minutes, then average across pods for a single row.

avg by (app_kubernetes_io_name) (stddev_over_time(go_goroutines{app_kubernetes_io_name="query-service"}[10m]))
Expected output
app_kubernetes_io_name Value

query-service

0

Over-time functions aggregate one series across time; the aggregation operators (sum, avg, …​) aggregate across series at one instant. Combine both for fleet summaries.

stdvar_over_time

Computes the population variance of each series' samples within the range window — the square of stddev_over_time.

Syntax

stdvar_over_time(<metric>[<range>])
stdvar_over_time(<expr>[<range>:<step>])
none

The second form is a subquery: <expr> is any instant-vector PromQL expression evaluated at every <step> interval over the trailing <range> window.

Parameters

Parameter Required Description

<range>

Required

The trailing window to aggregate over.

<step>

Subquery only

The evaluation interval within the subquery window. Defaults to the global evaluation interval when omitted (written as [<range>:]).

Example

Apply stdvar_over_time to the query-service goroutine gauge over the last ten minutes, then average across pods for a single row.

avg by (app_kubernetes_io_name) (stdvar_over_time(go_goroutines{app_kubernetes_io_name="query-service"}[10m]))
Expected output
app_kubernetes_io_name Value

query-service

0

Over-time functions aggregate one series across time; the aggregation operators (sum, avg, …​) aggregate across series at one instant. Combine both for fleet summaries.

sum_over_time

Adds up all samples of each series within the range window. Meaningful for quantities where samples accumulate; for counters, use increase instead.

Syntax

sum_over_time(<metric>[<range>])
sum_over_time(<expr>[<range>:<step>])
none

The second form is a subquery: <expr> is any instant-vector PromQL expression evaluated at every <step> interval over the trailing <range> window.

Parameters

Parameter Required Description

<range>

Required

The trailing window to aggregate over.

<step>

Subquery only

The evaluation interval within the subquery window. Defaults to the global evaluation interval when omitted (written as [<range>:]).

Example

Apply sum_over_time to the query-service goroutine gauge over the last ten minutes, then average across pods for a single row.

avg by (app_kubernetes_io_name) (sum_over_time(go_goroutines{app_kubernetes_io_name="query-service"}[10m]))
Expected output
app_kubernetes_io_name Value

query-service

6,259.19

Over-time functions aggregate one series across time; the aggregation operators (sum, avg, …​) aggregate across series at one instant. Combine both for fleet summaries.