map(options, set[])

The map function allows you to execute the same composite function across multiple metrics or sources without having to repeat yourself for each metric or source. It takes a pattern of metrics or sources defined in the options map and applies that pattern to the given set. The result of the map function is N sets, one for each application of the pattern to the given set argument. This also allows the mapped metrics or sources to be dynamic and not have to be defined beforehand.

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

  • AWS.ELB.HTTPCode_Backend_2XX
  • AWS.ELB.HTTPCode_Backend_3XX
  • AWS.ELB.HTTPCode_Backend_4XX
  • AWS.ELB.HTTPCode_Backend_5XX
  • AWS.ELB.HTTPCode_ELB_4XX
  • AWS.ELB.HTTPCode_ELB_5XX

And that for each metric the following sources exist:

  • us-east-1b
  • us-east-1c
  • us-east-1e

The following function would calculate and return the sum of 5xx’s per cluster i.e. two series:

map({metric:"AWS.ELB.HTTPCode_*_5XX"}, sum(series("&", "us-east*")))

aws-5xx-error-codes

The map() function executes the sum() method twice, once for AWS.ELB.HTTPCode_Backend_5XX and again for AWS.ELB.HTTPCode_ELB_5XX. In the enclosed series() method the “&” character is a special token that is replaced with each metric name matched in the map function. The above function applied to the metrics/sources above is equivalent to:

[sum(series("AWS.ELB.HTTPCode_Backend_5XX", "us-east*")),
 sum(series("AWS.ELB.HTTPCode_ELB_5XX", "us-east*"))]

However, let’s say we want to get the over all sums of 5XX’s per source.

map({source:"us-east*"}, sum(series("WS.ELB.HTTPCode_*_5XX", "&")))

aws-5xx-error-codes-by-source

This way, the number of 5XX’s is returned on a per-source basis. This is equivalent to:

[sum(series("cluster.*.5XX", "us-east-1b")),
 sum(series("cluster.*.5XX", "us-east-1c")),
 sum(series("cluster.*.5XX", "us-east-1e"))]

Note: Using both metric and source in the same map() is not supported.