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

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', () => {