fix(cloudwatch): automatic metric math label cannot be suppressed (#1…

…7639)

According to CloudWatch [docs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html):

> For the Label column of the expression, enter a name that describes what the expression is calculating.
If the result of an expression is an array of time series, each of those time series is displayed on the graph with a separate line, with different colors. Immediately under the graph is a legend for each line in the graph. For a single expression that produces multiple time series, the legend captions for those time series are in the format Expression-Label Metric-Label. For example, if the graph includes a metric with a label of Errors and an expression FILL(METRICS(), 0) that has a label of Filled With 0:, one line in the legend would be Filled With 0: Errors. **To have the legend show only the original metric labels, set Expression-Label to be empty.**

In the current implementation, if the label is left empty, the expression string is used, which makes the graph cumbersome. In multi widget dashboards where real estate is scarce, it becomes a real issue.

See my cats widget before the fix:


<img width="1432" alt="Screen Shot 2021-11-22 at 5 17 35 PM" src="https://user-images.githubusercontent.com/8578043/142959081-f3c28ea9-dd36-431f-b123-262eed0b2625.png">

My cats widget after the fix:

<img width="1250" alt="Screen Shot 2021-11-22 at 5 20 34 PM" src="https://user-images.githubusercontent.com/8578043/142959125-2ea5f7b3-9170-43bc-ba8b-233dc1af9700.png">



 


----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/@aws-cdk/aws-cloudwatch/README.md

@@ -104,7 +104,13 @@ graph showing the Average statistic with an aggregation period of 5 minutes:
 
 ```ts
 const cpuUtilization = new cloudwatch.MathExpression({
-  expression: "SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 300)"
+  expression: "SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 300)",
+
+  // Specifying '' as the label suppresses the default behavior
+  // of using the expression as metric label. This is especially appropriate
+  // when using expressions that return multiple time series (like SEARCH()
+  // or METRICS()), to show the labels of the retrieved metrics only.
+  label: '',
 });
 ```
 
@@ -157,6 +163,33 @@ useful when embedding them in graphs, see below).
 > happen to know the Metric you want to alarm on makes sense as a rate
 > (`Average`) you can always choose to change the statistic.
 
+### Labels
+
+Metric labels are displayed in the legend of graphs that include the metrics.
+
+You can use [dynamic labels](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html)
+to show summary information about the displayed time series
+in the legend. For example, if you use:
+
+```ts
+declare const fn: lambda.Function;
+
+const minuteErrorRate = fn.metricErrors({
+  statistic: 'sum',
+  period: Duration.hours(1),
+
+  // Show the maximum hourly error count in the legend
+  label: '[max: ${MAX}] Lambda failure rate',
+});
+```
+
+As the metric label, the maximum value in the visible range will
+be shown next to the time series name in the graph's legend.
+
+If the metric is a math expression producing more than one time series, the
+maximum will be individually calculated and shown for each time series produce
+by the math expression.
+
 ## Alarms
 
 Alarms can be created on metrics in one of two ways. Either create an `Alarm`
@@ -308,7 +341,7 @@ dashboard.addWidgets(new cloudwatch.GraphWidget({
   right: [errorCountMetric.with({
     statistic: "average",
     label: "Error rate",
-    color: cloudwatch.Color.GREEN
+    color: cloudwatch.Color.GREEN,
   })]
 }));
 ```

packages/@aws-cdk/aws-cloudwatch/lib/metric.ts

@@ -75,6 +75,18 @@ export interface CommonMetricOptions {
 
   /**
    * Label for this metric when added to a Graph in a Dashboard
+   *
+   * You can use [dynamic labels](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html)
+   * to show summary information about the entire displayed time series
+   * in the legend. For example, if you use:
+   *
+   * ```
+   * [max: ${MAX}] MyMetric
+   * ```
+   *
+   * As the metric label, the maximum value in the visible range will
+   * be shown next to the time series name in the graph's legend.
+   *
    * @default - No label
    */
   readonly label?: string;
@@ -127,7 +139,28 @@ export interface MetricOptions extends CommonMetricOptions {
  */
 export interface MathExpressionOptions {
   /**
-   * Label for this metric when added to a Graph in a Dashboard
+   * Label for this expression when added to a Graph in a Dashboard
+   *
+   * If this expression evaluates to more than one time series (for
+   * example, through the use of `METRICS()` or `SEARCH()` expressions),
+   * each time series will appear in the graph using a combination of the
+   * expression label and the individual metric label. Specify the empty
+   * string (`''`) to suppress the expression label and only keep the
+   * metric label.
+   *
+   * You can use [dynamic labels](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html)
+   * to show summary information about the displayed time series
+   * in the legend. For example, if you use:
+   *
+   * ```
+   * [max: ${MAX}] MyMetric
+   * ```
+   *
+   * As the metric label, the maximum value in the visible range will
+   * be shown next to the time series name in the graph's legend. If the
+   * math expression produces more than one time series, the maximum
+   * will be shown for each individual time series produce by this
+   * math expression.
    *
    * @default - Expression value is used as label
    */

packages/@aws-cdk/aws-cloudwatch/lib/private/rendering.ts

@@ -66,11 +66,17 @@ function metricGraphJson(metric: IMetric, yAxis?: string, id?: string) {
   if (yAxis !== 'left') { options.yAxis = yAxis; }
   if (id) { options.id = id; }
 
-  // If math expressions don't have a label (or an ID), they'll render with an unelegant
-  // autogenerated id ("metric_alias0"). Our ids may in the future also be autogenerated,
-  // so if an ME doesn't have a label, use its toString() as the label (renders the expression).
   if (options.visible !== false && options.expression && !options.label) {
-    options.label = metric.toString();
+    // Label may be '' or undefined.
+    //
+    // If undefined, we'll render the expression as the label, to suppress
+    // the default behavior of CW where it would render the metric
+    // id as label, which we (inelegantly) generate to be something like "metric_alias0".
+    //
+    // For array expressions (returning more than 1 TS) users may sometimes want to
+    // suppress the label completely. For those cases, we'll accept the empty string,
+    // and not render a label at all.
+    options.label = options.label === '' ? undefined : metric.toString();
   }
 
   const renderedOpts = dropUndefined(options);

packages/@aws-cdk/aws-cloudwatch/test/metric-math.test.ts

@@ -145,6 +145,27 @@ describe('Metric Math', () => {
       ]);
 
 
+    });
+
+    test('passing an empty string as the label of a MathExpressions does not emit a label', () => {
+      const graph = new GraphWidget({
+        left: [
+          new MathExpression({
+            expression: 'a + e',
+            label: '',
+            usingMetrics: {
+              a,
+            },
+          }),
+        ],
+      });
+
+      graphMetricsAre(graph, [
+        [{ expression: 'a + e' }],
+        ['Test', 'ACount', { visible: false, id: 'a' }],
+      ]);
+
+
     });
 
     test('can reuse identifiers in MathExpressions if metrics are the same', () => {