How to aggregate points from multiple time series with or without interpolation.

You can combine points from multiple time series using an aggregation function such as `sum()`, `avg()`, `min()`, `count()`, `percentile()` etc. An aggregation function returns a series of points whose values are calculated from corresponding points in two or more input time series. Wavefront supports aggregation with interpolation or without interpolation:

• Standard aggregation functions (e.g. `sum()`, `avg()`, or `max()`) first interpolate the points of the underlying set of series, and then apply the aggregation function to the interpolated series. These functions aggregate multiple series down, usually to a single series.
• Raw aggregation functions (e.g. `rawsum()`, `rawavg()`) do not interpolate the underlying series before aggregation.
• Moving window functions (e.g. `msum()`, `mavg()` and `mmax()` aggregate series horizontally across a chart by time. They take each individual series and aggregate its own prior behavior across the timeWindow. For example, you can get the maximum value for each series in the specified time window.

In the following video, Wavefrount co-founder Clement Pang explains how interpolation works:

## Aggregating Data Points That Line Up

The easiest way to see the results of an aggregation function is when all of the input series report their data points at exactly the same time. This causes the points at any given timestamp to all line up. The aggregation function operates on the values in each lineup of points, and returns each result in a point at the corresponding timestamp.

For example, consider the two time series in the following chart. The reporting interval for these series is 1 minute, and the points in these series “line up” at each 1-minute mark on the x-axis. We use a point plot to reveal the correspondences between reported points. Now we use the `sum()` function to aggregate these two time series. Each blue point produced by `sum()` is the result of adding the data values reported by the input series at the same minute. ## Aggregating When Data Points Do Not Line Up

In many cases, the set of time series you specify to an aggregation function will have data points that do not “line up” at corresponding moments in time. For example:

• All input series might report data points regularly, but some might report at a longer or shorter interval than the others.
• One input series might report at irregular times that don’t match the reporting times of any other input series.
• One otherwise regular input series might have gaps due to reporting interruptions (e.g., intermittent server or network downtime) which are not experienced by the other input series.

Wavefront provides two kinds of aggregation functions for handling this situation:

• Standard aggregation functions fill in the gaps in each input series by interpolating values, and therefore operate on interpolated values as well as actual reported data points.
• Raw aggregation functions do not interpolate the underlying series before aggregation, but rather operate only on actual reported data points.

### Standard Aggregation Functions (Interpolation)

Standard aggregation functions fill in the gaps in each input series by interpolating values.

For example, let’s start with a pair of series with reporting intervals that do not line up. In the following chart, `series 1` reports once a minute, and `series 2` reports once every 2.5 minutes. Both series have data points aligned at 4:25 and again at 4:30. Between these times, we see unaligned data points – 4 points from `series 1`, and one point (at 4:27:30) from `series 2`. Now we use the `sum()` function (a standard aggregation function) to aggregate these two time series. In the following chart, we see that `sum()` produces a result for every moment in time that a data point is reported by at least one input series. Whenever both series report a data point at the same time (for example, 4:25), `sum()` returns a data point whose value is the sum of both reported points (169.05 + 162 = 331.05). The result at 4:26 is more interesting. At this moment in time, `sum()` returns the value 328.430, although there is only a single input data value (164) at that time, reported by `series 1`. `sum()` produces the return value by adding 164 to an interpolated value from `series 2`. Interpolation inserts an implicit point into `series 2` at 4:26, and assigns an estimated value to that point based on the values of the actual, reported points on either side (at 4:25 and 4:27:30). `sum()` uses the estimated value (in this case, 164.43) to calculate the value returned at 4:26.

Requirements for Interpolation

Wavefront interpolates a value into an input time series only under the following circumstances:

• When at least one other input time series reports a real data value at the same moment in time. In our example, no values are interpolated at, say, 4:26:30, because neither input series reports a point at that time.

• When the time series has an actual reported value on either side of it. Sometimes this cannot occur, for example, when a new data point has not been reported yet at the right edge of a live-view chart. In this case, Wavefront inserts implicit points wherever needed, and assigns the last known reported value in the time series to those implicit points. (The last known reported value must be reported within the last 15% of the query time in the chart window.)

### Raw Aggregation Functions (No Interpolation)

You can use raw aggregation functions instead of standard aggregation functions if you want the results to be based on actual reported values, without any interpolated values. For example, you might use raw aggregation results as a way of detecting when one or more input time series fail to report a value.

Let’s see how the raw aggregation function `rawsum()` treats the two sample time series from the previous section. The following chart shows that `rawsum()`, like `sum()`, produces a result for every moment in time that a data point is reported by at least one input series.

Unlike `sum()`, `rawsum()` produces its results by adding up just the actual values at each reporting moment. At 4:26, for example, `rawsum()` returns 164.00, which is the only value reported at this time. No values from `series 2` are present at that time, and none are interpolated. Whenever both series report a data point at the same time (for example, 4:25), `rawsum()` returns a data point whose value is the sum of both reported points (169.05 + 162 = 331.05).

## Filtering the Aggregation Input

You use an expression to describe the set of time series to be aggregated. When using a ts() expression, you can include filters to narrow the set. For example, if multiple sources are reporting the metric `~sample.cpu.loadavg.1m`:

• `sum(ts(~sample.cpu.loadavg.1m))` shows the sum of the values reported for the metric from all sources.
• `sum(ts(~sample.cpu.loadavg.1m, source=app-1*))` shows the sum of the values reported for the metric, but only from sources that match `app-1*`.
• `sum(ts(~sample.cpu.loadavg.1m, source=app-1*, env=prod))` further filters the input series to those with the point tag `env=prod`.

## Grouping the Aggregation Results

Each aggregation function accepts a ‘group by’ parameter that allows you to subdivide the input time series into groups, and request separate aggregates for each group. The chart displays a separate line corresponding to each group. For example, you can use a ‘group by’ parameter with `sum()` or `rawsum()` produce a separate subtotal for each group of time series that are reported from a common source. The chart for such a query displays one line corresponding to each source. When used without a ‘group by’ parameter, an aggregation function returns a single series of results.

'Group By' ParameterDescriptionExample
metrics Group the series with the same metric name. `sum(ts(cpu.loadavg.1m), metrics)`
sources Group the series that are reported from the same source. `sum(ts(cpu.loadavg.1m), sources)`
sourceTags Group the series that are reported from sources with the same source tag names. A source tag is used only if it is explicitly specified in the ts() expression. `sum(ts(cpu.loadavg.1m, tag=prod or tag=db),sourceTags)`
pointTags Group the series by all available point tag keys. `sum(ts(cpu.loadavg.1m), pointTags)`
<pointTagKey> Group the series with common values for a particular point tag key. Specify the point tag key by name, such as `region`. `sum(ts(cpu.loadavg.1m), region)`

### A Closer Look at the `sourceTags` Parameter

The `sourceTags` parameter behaves a little differently from the other grouping parameters. `sourceTags` produces a subgroup that corresponds to each source tag that is explicitly specified in the ts() expression. No other source tags are taken into account.

For example, suppose you added 3 source tags (`prod`, `db`, and `highPriority`) to the metric `cpu.loadavg.1m`, and now you want to use the `sourceTags` parameter with `sum()` to return subtotals based on the source tags.

• The following query returns only 2 subtotals - one for the group with the source tag `prod` and one for the group with the source tag `db`:

``````  sum(ts(cpu.loadavg.1m, tag=prod or tag=db),sourceTags)
``````
• The following query returns 3 subtotals, one for each source tag:

``````  sum(ts(cpu.loadavg.1m, tag=prod or tag=db or tag=highPriority),sourceTags)
``````

In contrast, a ‘group by’ parameter like `pointTags` produces a separate aggregate corresponding to every point tag that is associated with the specified time series, even if the ts() expression does not explicitly specify any point tags as filters.

## Aggregation Example

The chart below represents 3 unique series reporting latency data. The sections with dashed lines represent gaps where no data is reported. The series report data like this:

• Two of the reporting series have gaps of missing data between 9:15a and 9:21a.
• All three reporting series have gaps of missing data between 9:27a and 9:30a
• One reporting series has a gap of missing data between 9:36a and 9:42a.

The following chart shows what happens when we apply `sum()` (orange line) and `rawsum()` (blue line) to the three time series. The lines are different because interpolation occurs with the standard aggregation function (`sum()`), but not with the raw aggregation function (`rawsum()`).

Example: Standard Aggregation Function

When there is at least 1 true data value reported at a given interval, standard aggregation functions interpolate data values before executing the aggregation.

The data values in the charts above are typically reported once a minute. In the chart that shows the 3 time series, we see that:

• Between 9:15a and 9:21a, the orange series reports once a minute, on the minute, while the other two series do not. Because the orange series reports at least 1 true data value during this time, Wavefront interpolates the values for the blue and green series before calculating the `sum()` value.
• Between 9:36a and 9:42a the green and orange series report data values every minute, but the blue series does not not. Wavefront does interpolation before aggregation.

Example: Raw Aggregation Function

Raw aggregation functions on the other hand calculate aggregates based on actual reported values (no interpolation).

• Between 9:15a and 9:21a, the `rawsum()` values are approximately 1/3 of the `sum()` values (1 of 3 series reported values)
• Between 9:36a and 9:42a, the `rawsum()` values are approximately 2/3 of the `sum()` value (2 of 3 series reported values).

Note that the gap between 9:27a and 9:30a is exactly the same regardless of which aggregation function type we use. None of the series included in the aggregation reported a data value during this time. As a result, the standard aggregation function does not apply interpolated values during this gap, and the result of aggregation looks the same for `sum()` and `rawsum()`.

The behavior differences between standard and raw apply to all aggregation functions (sum, avg, min, max, count, variance, percentile).