Computes aggregate functions over a sliding window of data. This function
can only be used as the function argument in a
timeChart() or bucket()
operation i.e., some aggregate that has multiple "time buckets" from which
to draw the running aggregate operation. If used elsewhere, an error is
reported to the user.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
buckets | number | false | Defines the number of buckets in the sliding time window i.e., the number of buckets in the surrounding timeChart() or bucket() to use for the running window aggregate. Exactly one of span and buckets should be defined. | |
function | [Aggregate] | false | count(as=_count) | Specifies which aggregate functions to perform on each window. [a] |
span | string | false | Defines the width of the sliding time window. This value is rounded to the nearest multiple of time buckets of the surrounding timeChart() or bucket(). The time span is defined as a relative-time-syntax like 1hour or 3 weeks. If the query's time interval is less than the span of the window, no window result is computed. Exactly one of span and buckets should be defined. | |
When an embedded aggregate function computes its result, the "window result" is put into the time bucket after the last bucket contributing to the "window result". Here is an example. Notice how the first three buckets in the result column have no values.
| time bucket | B0 | B1 | B2 | B3 | B4 | B5 | B6 |
|---|---|---|---|---|---|---|---|
| data | 1 | 3 | 5 | 2 | 1 | 3 | 5 |
window(function=avg(), buckets=3)
| 3 | 3.33 | 2.66 | 2 |
At B3, the average of 1, 3, and 5, which is 3, is emitted. In bucketed and time charted data, the timestamp (_bucket field) of the emitted events is always the beginning of said bucket, so the average of bucket B0, B1, and B2 is timestamped at the beginning of B4.
If the number of buckets required by the sliding window to compute its
aggregate result is higher than the number of buckets provided by the
surrounding timeChart() or
bucket() function, then the
window() function will yield an empty result.
Any aggregate function can be used to compute sliding window data.
Another example use case would be to find outliers, comparing a running average +/- running standard deviations to the concrete min/max values. This can be obtained by computing like this, which graphs the max value vs the limit value computed as average plus two standard deviations over the previous 15 minutes.
| timeChart(function=[max(m1),window([stdDev(m1),avg(m1)], span=15min)])
| groupBy(_bucket, function={ limit := _avg+2*_stddev
| table([_max, limit]) })window() Examples
Chart 30 minutes running average of cpu load. The time interval of the query must be larger than the window span to produce any result.
timeChart(host, function=window( function=avg(cpu_load), span=30min ))Chart 30 minutes running average and maximum of cpu load. This example specifies three buckets of the outer timechart (each of 10 minutes).
timeChart(host, function=window( function=[avg(cpu_load), max(cpu_load)], buckets=3 ), span=10m)