Used with timeChart() or bucket(), computes the aggregate for one or more fields over a sliding window of data. This function can only be used as the function argument with timeChart() or bucket(). If used elsewhere, an error is reported to the user.

ParameterTypeRequiredDefault ValueDescription
bucketsintegeroptional[a]   Defines the number of buckets in the sliding time window, for example, 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[b]array of aggregate functionsoptional[a] count(as=_count) Specifies which aggregate functions to perform on each window. If several aggregators are listed for the function parameter, then their outputs are combined using the rules described for stats().
spanlongoptional[a]   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 1 hour 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.

[a] Optional parameters use their default value unless explicitly set.

[b] The parameter name function can be omitted.

Hide omitted argument names for this function

Show omitted argument names for this function

window() Function Operation

The window() computes the running aggregate (for example, avg() or sum()) for the given incoming events. For each window, the window() takes the buckets parameter and uses this to calculate the rolling aggregate across that number of buckets in the input.

For example, this query calculates the rolling average over the preceding three buckets in the humio for allocBytes:

logscale
timeChart(span=15s,function=window(function=avg(allocBytes), buckets=3))
| formatTime(field=_bucket,format="%T",as=fmttime)

Tip

Use the Data tab in Time Chart to view the raw data being used for the chart.

_bucket_avgfmttime
171152002500018410.01408450704206:13:45
171152004000023895.21418826739306:14:00
171152005500024428.8389715832206:14:15
171152007000024178.22099447513806:14:30
171152008500024718.23933975240706:14:45
171152010000018554.2295081967206:15:00
171152011500025638.9877551020406:15:15
171152013000018482.97079276773406:15:30
171152014500025925.1389270976606:15:45
171152016000019303.47252747252806:16:00
171152017500025806.0408163265306:16:15
171152019000017668.75524475524406:16:30
171152020500024431.55129958960206:16:45
171152022000017237.95604395604506:17:00
171152023500023476.79566982408506:17:15
171152025000015585.5708274894806:17:30
171152026500022664.58935879945406:17:45
171152028000016099.0413223140506:18:00

A graphical representation, showing the span of each computed window is shown below.

By comparison this query computes the value over the preceding 5 buckets:

logscale
timeChart(span=15s,function=window(function=avg(allocBytes), buckets=3))
| formatTime(field=_bucket,format="%T",as=fmttime)

The computed average is different because a different series of values in different buckets is being used to compute the value:

_bucket_avgfmttime
171152002500017772.62295081967406:13:45
171152004000021970.35796387520506:14:00
171152005500022170.0445177246506:14:15
171152007000022505.8660049627806:14:30
171152008500023378.4730831973906:14:45
171152010000023568.35409836065406:15:00
171152011500023566.5202312138706:15:15
171152013000019816.21227197346506:15:30
171152014500024608.28781684382606:15:45
171152016000020315.03630363036406:16:00
171152017500024221.75020678246406:16:15
171152019000019854.06483790523606:16:30
171152020500023849.6993464052306:16:45
171152022000018996.48925619834706:17:00
171152023500022389.5090609555206:17:15
171152025000017751.33444259567506:17:30
171152026500021959.06840390879406:17:45
171152028000017377.42266335814606:18:00

This can be represented graphically like this:

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.

An 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.

logscale
| timeChart(function=[max(m1),window([stdDev(m1),avg(m1)], span=15min)])
| groupBy(_bucket, function={ limit := _avg+2*_stddev
| table([_max, limit]) })

window()Examples

Click + next to an example below to get the full details.

Make Data Compatible With Time Chart Widget - Example 1

Make data compatible with Time Chart Widget using the timeChart() function with window() and span parameter

Query
logscale
timeChart(host, function=window( function=avg(cpu_load), span=15min))
Introduction

In this example, the timeChart() function is used to create the required input format for the Time Chart Widget and the window() function is used to compute the running aggregate (avg()) for the cpu_load field over a sliding window of data in the time chart. The span width, for example 15 minutes, is defined by the span parameter. This defines the duration of the average calculation of the input data, the average value over 15 minutes. The number of buckets created will depend on the time interval of the query. A 2 hour time interval would create 8 buckets.

Note

The difference between window() and bucket() is that window() will create buckets with a consistent interval, whereas bucket() creates the buckets based on the query time.

Step-by-Step

  1. Starting with the source repository events.

  2. logscale
    timeChart(host, function=window( function=avg(cpu_load), span=15min))

    Groups by host, and calculates the average CPU load time per each 15 minutes over the last 24 hours for each host, displaying the results in a Time Chart Widget.

    The running average time of CPU load is grouped into spans of 30 minutes. Note that the time interval of the query must be larger than the window span to produce any result.

  3. Event Result set.

Summary and Results

Selecting the number of buckets or the timespan of each bucket enables you to show a consistent view either by time or by number of buckets independent of the time interval of the query. For example, the widget could show 10 buckets whether displaying 15 minutes or 15 days of data; alternatively the display could always show the data for each 15 minutes.

The query is used to make CPU load data compatible with the Time Chart Widget. This query is, for example, useful for CPU load monitoring to identify sustained high CPU usage over specific time periods.

For an example of dividing the input data by the number of buckets, see Make Data Compatible With Time Chart Widget - Example 2.

Make Data Compatible With Time Chart Widget - Example 2

Make data compatible with Time Chart Widget using the timeChart() function with window() and buckets parameter

Query
logscale
timeChart(host, function=window( function=[avg(cpu_load), max(cpu_load)], buckets=3))
Introduction

In this example, the window() function uses the number of buckets to calculate average and maximum CPU load. The timespan for each bucket will depend on the time interval of the query. The number of buckets are defined by the buckets parameter. The timeChart() function is used to create the required input format for the Time Chart Widget.

The query calculates both average AND maximum values across the requested timespan. In this example, the number of buckets is specified, so the events will be distributed across the specified number of buckets using a time span calculated from the time interval of the query. For example, a 15 minute time interval with 3 buckets would use a timespan of 5 minutes per bucket.

Note

The difference between window() and bucket() is that window() will create buckets with a consistent interval, whereas bucket() creates the buckets based on the query time.

Step-by-Step

  1. Starting with the source repository events.

  2. logscale
    timeChart(host, function=window( function=[avg(cpu_load), max(cpu_load)], buckets=3))

    Groups by host, and calculates both the average of CPU load time and the maximum CPU load time (using aggregates (avg() and max()) for the cpu_load field), displaying the results in 5 buckets showing a stacked graph for each host using a Time Chart Widget.

  3. Event Result set.

Summary and Results

Selecting the number of buckets or the timespan of each bucket enables you to show a consistent view either by time or by number of buckets independent of the time interval of the query. For example, the widget could show 10 buckets whether displaying 15 minutes or 15 days of data; alternatively the display could always show the data for each 15 minutes.

The query is used to make CPU load data compatible with the Time Chart Widget. This query is, for example, useful for CPU load monitoring to compare intervals, compare hourly performance etc.

For an example of dividing the input data by the timespan of each bucket, see Make Data Compatible With Time Chart Widget - Example 1.