window( ) Query Function

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.

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]) })

Parameters

Name Type Required Default Description
function [Aggregate] No count(as=_count) Specifies which aggregate functions to perform on each window.
span string No 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 modifier 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.
buckets number No 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 is the unnamed parameter.

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)