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:

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

and is equivalent to the expanded composite function:

[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:

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:

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