by
Group by operator. There are two variants of the :by operator.
Aggregation
Input Stack:| keys: List[String] | | aggregationFunc: AggregationFunction |
|
⇨ |
Output Stack: |
Groups the matching time series by a set of tag keys and applies an aggregation function to
each group. This allows you to aggregate data separately for different values of the specified
keys, rather than aggregating everything together.
Parameters
- aggregationFunc: An aggregation function (like
:sum, :max, :count) that will be applied to each group
- keys: A list of tag key names to group by (e.g.,
name, nf.app)
Examples
Group CPU metrics by name and apply sum aggregation to each group:
name,ssCpu,:re,
(,name,),:by
When matching against the sample data in the table below, the highlighted time series would be
included in the aggregate result:
| Name | nf.app | nf.node | Data |
| ssCpuUser |
alerttest |
i-0123 |
[1.0, 2.0, NaN] |
| ssCpuSystem |
alerttest |
i-0123 |
[3.0, 4.0, 5.0] |
| ssCpuUser |
nccp |
i-0abc |
[8.0, 7.0, 6.0] |
| ssCpuSystem |
nccp |
i-0abc |
[6.0, 7.0, 8.0] |
| numRequests |
nccp |
i-0abc |
[1.0, 2.0, 4.0] |
| ssCpuUser |
api |
i-0456 |
[1.0, 2.0, 2.0] |
The aggregation function will be applied independently for each group. In this example above
there are two matching values for the group by key name. This leads to a final result of:
| Name | Data |
| ssCpuSystem |
[9.0, 11.0, 13.0] |
| ssCpuUser |
[10.0, 11.0, 8.0] |
The name tag is included in the result set since it is used for the grouping.
Math
Input Stack:| keys: List[String] | | expr: TimeSeriesExpr |
|
⇨ |
Output Stack: |
Groups the time series from the input expression by a set of tag keys and applies an aggregation
to each group. The keys used for this grouping must be a subset of keys from the initial grouping
operation. This variant allows for hierarchical grouping where you first group by a broader set
of keys, then regroup by a subset.
Parameters
- expr: A time series expression that contains grouped data
- keys: A list of tag key names to group by (must be subset of original grouping keys)
Examples
First group by cluster and node, then regroup by cluster only (counting nodes per cluster):
| Before | After |
 |  |
name,sps,:eq,
:sum,
(,nf.cluster,nf.node,),:by
| name,sps,:eq,
:sum,
(,nf.cluster,nf.node,),:by,
:count,
(,nf.cluster,),:by
|
- :sum - Sum aggregation function (commonly used with grouping)
- :max - Maximum aggregation function
- :min - Minimum aggregation function
- :avg - Average aggregation function
- :count - Count aggregation function
- :eq - Equality filter (creates exact tag matches that preserve grouping)