window(set[], options={})

Given an arbitrary number of series, moves a windowing function across each series to return a set of equal length. The size of the window and the function to compute across each window are configurable. A common use of this function is to smooth a noisy set of series by averaging local variance over a wider period of samples.

Windows are always calculated with points previous to, and including, the current point in time and operate with a fixed number of data points. This is also commonly referred to as the Simple Moving Average when computing the mean of the data points across the window.

The options map accepts the following keys:

  • size - The size of the window specified in the number of inclusive, previous points over which to compute the window function. At each point in the set of the input series, the window will be computed using the current point plus the size - 1 previous points. If there are not size - 1 previous points the current point will be dropped from the returned set. This means that for an input series of N points, the returned series will have N - (size - 1) points, the first size - 1 points having been dropped from the result. The default size of a window if not specified is 1 – ie, no windowing. The maximum value is size:"64".
  • function - The function parameter defines the function that is computed over each moving window of points. The values are: mean, sum, min, max, and median. The default function, if not specified, is mean.

Example:

The following expression plots the median values of the metric api.auth.time.p99 over a window of 5 points.

window(max(s("api.auth.time.p99", {"host": "prod.web*"})), {size: "5", function:"median"})

The resulting chart demonstrates how the window function will smooth out any noise. The chart includes the bare metric api.auth.time.p99 for comparison, which displays many spikes not seen in the composite metric.

window-composite-example

Note: Composite metrics that you set up for alerting and that use window() or moving_average() functions use a start time of the query 15 minutes in the past, effectively allowing a maximum window size of 15 minutes for the query.