Documentation forAppOptics

Function: group_by(tags, set[])

The group_by function allows you to group a single composite function by a set of one or more tag names. It takes as its first argument a comma-separated list of one or more tag names to group the remaining composite function by, specified by the second parameter. It is as if the enclosed composite function is executed once per unique set of tag values for the grouped tag names.

The best way to explain group_by is with a set of examples. First off, assume the following metrics exist:

  • AWS.ELB.HTTPCode_Backend_2XX
  • AWS.ELB.RequestCount

And that for each metric the following tags exist:

  • region = us-east-1, az = b
  • region = us-east-1, az = c
  • region = us-west-1, az = b
  • region = eu-west-1, az = e

The following composite function aggregates 2XX values by US regions:

Copy
group_by("region", sum(series("AWS.ELB.HTTPCode_Backend_2XX", {"region" : "us*"})))

and is equivalent to the expanded composite function:

Copy
[sum(series("AWS.ELB.HTTPCode_Backend_2XX", {"region" : "us-east-1"})),
 sum(series("AWS.ELB.HTTPCode_Backend_2XX", {"region" : "us-west-1"}))]

The group_by function will group all series() calls enclosed within the group_by, so that if you want to apply the same grouping across multiple metric streams you can. For example, the following composite calculates the percentage of 2XX requests within each region and AZ:

Copy
group_by("region,az", divide([sum(series("AWS.ELB.HTTPCode_Backend_2XX", "*")),
                              sum(series("AWS.ELB.RequestCount", "*"))]))

If a given series should not be grouped, you can disable grouping for that series with the series boolean option "group". If you disable grouping it will instead load all streams for each grouped set. For example, this composite is similar to the last one, but shows the 2XX's per region/AZ as a percentage to the total request count globally:

Copy
group_by("region,az", divide([sum(series("AWS.ELB.HTTPCode_Backend_2XX", "*")),
                              sum(series("AWS.ELB.RequestCount", "*", {group: "false"}))]))

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.