Selector modifiers

Selector modifiers control the time dimension of a selector: a range vector reads a window of raw samples, offset and @ shift or pin the evaluation time, and subqueries evaluate a derived expression over a range.

At modifier (@)

Fixes the evaluation time of a selector to an absolute Unix timestamp, regardless of the query’s own evaluation time. @ start() and @ end() pin to the boundaries of the query range — useful for showing a constant baseline across every step of a range query.

Syntax

<metric>{<matchers>} @ <unix-seconds>    (also @ start(), @ end())
none

Parameters

Parameter Required Description

<unix-seconds>

Required

Absolute timestamp in Unix seconds, or the functions start() / end() for the query-range boundaries.

Example

Chart the ratio of the current Kloudfuse goroutine total to its value at the start of the query range — a drift indicator that always compares against the same baseline sample.

sum(go_goroutines{app_kubernetes_io_instance="kfuse"})
/
sum(go_goroutines{app_kubernetes_io_instance="kfuse"} @ start())
Expected output
Value

1.003

@ and offset can be combined; order does not matter.

Offset modifier (offset)

Shifts the evaluation time of a single selector into the past. offset is the tool for same-query time comparison: this hour’s value next to yesterday’s, this week against last week.

Syntax

<metric>{<matchers>} offset <duration>
none

Parameters

Parameter Required Description

<duration>

Required

How far back to shift, such as 1h, 1d, or 1w. Must immediately follow the selector.

Example

Compare the current total goroutine count of Kloudfuse services against one hour ago — a value near 1.0 means no change.

sum(go_goroutines{app_kubernetes_io_instance="kfuse"})
/
sum(go_goroutines{app_kubernetes_io_instance="kfuse"} offset 1h)
Expected output
Value

0.9839

offset binds to its selector, not to the whole expression — each selector that should look back needs its own offset.

Range vector ([5m])

Appending a duration in square brackets to a selector returns a range vector: the raw samples of each series over that trailing window. Range vectors feed functions such as rate, increase, and the *_over_time family — they cannot be graphed directly.

Syntax

<metric>{<matchers>}[<duration>]
none

Parameters

Parameter Required Description

<duration>

Required

The window size: 30s, 5m, 1h, 1d. Use a window of at least 2–4× the metric’s scrape interval so every step sees multiple samples.

Example

Average the query-service goroutine count over the samples of the last ten minutes.

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

329.59

A range vector must be consumed by a function; go_goroutines[5m] alone is not a chartable expression.

Subquery ([1h:5m])

A subquery evaluates any instant expression repeatedly over a range, producing a range vector from computed values instead of raw samples. This lets range functions consume derived series — the max of a rate, the average of a sum — without creating a recording rule first.

Syntax

<expression>[<range>:<resolution>]
none

Parameters

Parameter Required Description

<range>

Required

The window to evaluate over.

<resolution>

Optional

Step between inner evaluations; defaults to the global evaluation interval.

Example

Find the highest total Kloudfuse goroutine count seen in the last hour, sampled every five minutes.

max_over_time(sum(go_goroutines{app_kubernetes_io_instance="kfuse"})[1h:5m])
Expected output
Value

385,840

Subqueries re-evaluate the inner expression at every resolution step — heavier than reading raw samples, so prefer a plain range vector when one suffices.