Selector modifiers :: Kloudfuse Docs

Selector modifiers

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())

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())
Value
1.003

Expected output
@ 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>

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)
Value
0.9839

Expected output
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>]

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]))
app_kubernetes_io_name Value
query-service 329.59

Expected output
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>]

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])
Value
385,840

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