Range aggregation operators :: Kloudfuse Docs
Range aggregation operators
Range aggregations turn a log stream into a metric by applying a function over a sliding time window — the range in square brackets, such as [5m]. Use them to chart log volume, throughput, and error counts, or as the basis for alerts.
absent_over_time
Returns a single series with value 1 when the selector matches no log lines in the range window, and returns nothing when lines exist. This inversion is what alerting needs for silence detection: a service that has stopped logging entirely produces no series for a normal alert rule to fire on.
Syntax
absent_over_time({<selector>} [<pipeline>] [<range>])
Parameters
| Parameter | Required | Description |
|---|---|---|
<selector> |
Required | Stream selector, optionally followed by a filter/parser pipeline. |
<range> |
Required | The silence window, such as [5m] or [15m]. |
Example
Check whether a service has logged anything in the last five minutes. Because no payments-service source exists on this cluster, the query returns 1 — the signal an alert rule would fire on.
absent_over_time({source="payments-service"}[5m])
| source | Value |
|---|---|
| payments-service | 1 |
Expected output
| When log lines exist, the result is empty — dashboards show no data, and alert rules do not fire. The returned series carries the equality matchers from the selector as labels, so the alert knows which service went silent. |
bytes_over_time
Sums the size in bytes of the log lines of each stream within the range window. Use it to see which sources, namespaces, or clusters generate log volume — the first question when managing ingest cost.
Syntax
bytes_over_time({<selector>} [<pipeline>] [<range>])
Parameters
| Parameter | Required | Description |
|---|---|---|
<selector> |
Required | Stream selector, optionally followed by a filter/parser pipeline. |
<range> |
Required | The window to sum over, such as [5m] or [1h]. |
Example
Measure how many bytes of Kafka broker logs were produced in the last five minutes.
sum(bytes_over_time({source="kafka"}[5m]))
| Value |
|---|
| 1,046,779 |
Expected output
| The value counts the raw line content, not labels or storage overhead. |
bytes_rate
Computes the per-second byte throughput of each stream in the range window — bytes_over_time divided by the window length. Use it to compare logging bandwidth across sources or to alert on sudden surges in log volume.
Syntax
bytes_rate({<selector>} [<pipeline>] [<range>])
Parameters
| Parameter | Required | Description |
|---|---|---|
<selector> |
Required | Stream selector, optionally followed by a filter/parser pipeline. |
<range> |
Required | The window to compute the rate over, such as [1m] or [5m]. |
Example
Measure the Kafka brokers' current logging bandwidth in bytes per second, averaged over five minutes.
sum(bytes_rate({source="kafka"}[5m]))
| Value |
|---|
| 3,564.21 |
Expected output
Pair with topk to rank the noisiest sources: topk(5, sum by (source) (bytes_rate({source=~".+"}[5m]))). |
count_over_time
Counts the log lines of each stream within the range window. This is the fundamental log-to-metric operator: wrap it in sum by (…) to chart log volume by any label, or compare error counts across services and levels.
Syntax
count_over_time({<selector>} [<pipeline>] [<range>])
Parameters
| Parameter | Required | Description |
|---|---|---|
<selector> |
Required | Stream selector, optionally followed by a filter/parser pipeline. |
<range> |
Required | The window to count over, such as [1m], [5m], or [1h]. |
Example
Count Grafana log lines by level over the last five minutes. The sum by (level) aggregation collapses the per-stream counts into one series per level.
sum by (level) (count_over_time({source="grafana"}[5m]))
| level | Value |
|---|---|
| debug | 7,900 |
| error | 63,685 |
| info | 75,079 |
| warn | 11 |
Expected output
In a range query (as charted on a dashboard), the window slides: each evaluation step counts the lines in the trailing <range> interval. |
rate
Computes the per-second rate of log lines in the range window — count_over_time divided by the window length. Rates are comparable across window sizes, which makes rate the usual choice for dashboards and alert thresholds.
Syntax
rate({<selector>} [<pipeline>] [<range>])
Parameters
Example
Measure Grafana’s logging rate per level in lines per second, averaged over the last five minutes.
sum by (level) (rate({source="grafana"}[5m]))
| level | Value |
|---|---|
| debug | 26.4 |
| error | 215.65 |
| info | 255.40 |
| warn | 0.03667 |
Expected output
| Add a line filter to rate specific events: `rate({source="nginx"} |