Understanding Aggregations

A metric arrives as many raw data points: every host, container, or process reports its own value every few seconds. Before a widget can draw a line or show a number, Middleware has to combine those points. It does this in up to three steps:

1. Time aggregation combines the points of each series inside a time bucket.
2. Space aggregation combines the series of different hosts or groups at each timestamp.
3. Reducer (single-value widgets only) collapses the whole time range into one value.

This page walks through each step with one example, so you can predict exactly what a widget will show.

Reading a query#

The legend label of every series spells out the steps applied to it. Take this label:

avg(system.memory.utilization,value(avg))

Other parts can appear in the label, depending on the query:

When you set an Alias Name, the legend shows the alias instead of this label.

The example#

The rest of this page uses the same data: 3 servers, monitored for 1 hour, each reporting system.memory.utilization every 5 minutes, with a 30-minute roll-up.

Each server reports 12 data points:

Step 1: Time aggregation#

Time aggregation works on one series at a time. It splits the series into time buckets and combines the points in each bucket into one value. Here, value(avg) averages the 6 points in each 30-minute bucket:

The bucket size comes from Roll Up … over N seconds. If you leave it on auto, Middleware picks it from the selected time range; see Roll-Up in the Dashboard builder guide. The interval for the time range is also the minimum, so a smaller value you enter is raised to it.

For longer time ranges, Middleware reads metrics that are pre-aggregated into 5-minute or 30-minute summaries instead of every raw point. For Average, each summary contributes its own average, so the result is an average of averages. As the callout at the end of this page explains, that matches the raw average only when every summary holds the same number of points.

Step 2: Space aggregation#

Space aggregation works on one timestamp at a time. It combines the values of all series that fall in the same group. With avg and no group by, the 3 servers are averaged into one series:

• First timestamp (0–30 min): (61.3% + 70.5% + 80.0%) ÷ 3 = 70.6%
• Second timestamp (30–60 min): (73.2% + 76.5% + 88.5%) ÷ 3 = 79.4%

If you add a group by such as host.name, each server stays its own series, so step 2 has nothing to combine and you get one line per server.

The other space aggregations work the same way, per timestamp: sum by adds the series, min by and max by keep the lowest or highest, and count by counts how many series reported a value. last keeps the value of one series without a defined order between series, so use it only when each group holds one series.

Timeseries result#

A Timeseries widget plots the output of step 2 directly: one line with two points, 70.6% at the first timestamp and 79.4% at the second.

Reducers#

Widgets such as List Value show one number per group instead of a line over time. To get that number, Middleware adds a third step: the reducer, set with Reduce values in timeframe to in the query builder. It collapses all the timestamps of a series into a single value.

List Value calculation#

Using the same example, steps 1 and 2 run exactly as above and produce 70.6% and 79.4%. The reducer then combines them. With the default avg:

(70.6% + 79.4%) ÷ 2 = 75% for the whole hour

Reducer options#

With a group by#

Add a group by and the reducer runs once per group. With host.name as the group by and the default avg, a List Value widget shows one row per server:

Where reducers apply#

• Shown on: List Value, Query Value, Pie Chart, Top List Chart, Tree Chart, Scatter Plot, and Hexagon Chart.
• Not shown on: Timeseries, Bar Chart, Heatmap Chart, and Split Graph, because they plot every timestamp.
• Defaults: new queries use avg. Widgets saved before the reducer existed show last, which is how their values were already calculated.

For the full list of rules, see Reduce values in timeframe to.