feat(cloudwatch): allow overriding of metric graph rendering (#4571)

* feat(cloudwatch): allow overriding of metric graph rendering

This allows to create custom graphs easier by creating sub-class of
metric and overriding the `toGraphConfig` method. Before attributes have
been only selectively copied to the widget configuration.

```
class HiddenMetric extends Metric {
  public toGraphConfig(): any {
    const ret = super.toGraphConfig();
    ret.renderingProperties.visible = false;
  }
}
```

Before `visible` would not have been taken over since it was not part of
options.

Docs: https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/CloudWatch-Dashboard-Body-Structure.html#CloudWatch-Dashboard-Properties-Rendering-Object-Format

* feat(cloudwatch): allow overriding of metric graph rendering - backwards compatible

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

@@ -320,13 +320,7 @@ function metricJson(metric: IMetric, yAxis: string): any[] {
   }
 
   // Options
-  ret.push({
-    yAxis,
-    label: config.label,
-    color: config.color,
-    period: config.period,
-    stat: config.statistic,
-  });
+  ret.push({ yAxis, ...config.renderingProperties });
 
   return ret;
 }

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

@@ -132,28 +132,68 @@ export interface MetricGraphConfig {
    */
   readonly metricName: string;
 
+  /**
+   * Rendering properties override yAxis parameter of the widget object
+   */
+  readonly renderingProperties: MetricRenderingProperties;
+
   /**
    * How many seconds to aggregate over
+   *
+   * @deprecated Use `period` in `renderingProperties`
    */
   readonly period: number;
 
   /**
    * Label for the metric
+   *
+   * @deprecated Use `label` in `renderingProperties`
    */
   readonly label?: string;
 
   /**
    * Color for the graph line
+   *
+   * @deprecated Use `color` in `renderingProperties`
    */
   readonly color?: string;
 
   /**
    * Aggregation function to use (can be either simple or a percentile)
+   *
+   * @deprecated Use `stat` in `renderingProperties`
    */
   readonly statistic?: string;
 
   /**
    * The unit of the alarm
+   *
+   * @deprecated not used in dashboard widgets
    */
   readonly unit?: Unit;
-}
+}
+
+/**
+ * Custom rendering properties that override the default rendering properties specified in the yAxis parameter of the widget object.
+ */
+export interface MetricRenderingProperties {
+  /**
+   * How many seconds to aggregate over
+   */
+  readonly period: number;
+
+  /**
+   * Label for the metric
+   */
+  readonly label?: string;
+
+  /**
+   * Color for the graph line
+   */
+  readonly color?: string;
+
+  /**
+   * Aggregation function to use (can be either simple or a percentile)
+   */
+  readonly stat?: string;
+}

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

@@ -195,6 +195,13 @@ export class Metric implements IMetric {
       dimensions: this.dimensionsAsList(),
       namespace: this.namespace,
       metricName: this.metricName,
+      renderingProperties: {
+        period: this.period.toSeconds(),
+        stat: this.statistic,
+        color: this.color,
+        label: this.label,
+      },
+      // deprecated properties for backwards compatibility
       period: this.period.toSeconds(),
       statistic: this.statistic,
       unit: this.unit,

packages/@aws-cdk/aws-cloudwatch/package.json

@@ -82,6 +82,7 @@
     "exclude": [
       "duration-prop-type:@aws-cdk/aws-cloudwatch.MetricAlarmConfig.period",
       "duration-prop-type:@aws-cdk/aws-cloudwatch.MetricGraphConfig.period",
+      "duration-prop-type:@aws-cdk/aws-cloudwatch.MetricRenderingProperties.period",
       "docs-public-apis:@aws-cdk/aws-cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD",
       "docs-public-apis:@aws-cdk/aws-cloudwatch.Unit.NONE",
       "docs-public-apis:@aws-cdk/aws-cloudwatch.Unit.COUNT_PER_SECOND",
@@ -118,8 +119,12 @@
       "props-default-doc:@aws-cdk/aws-cloudwatch.MetricGraphConfig.color",
       "props-default-doc:@aws-cdk/aws-cloudwatch.MetricGraphConfig.dimensions",
       "props-default-doc:@aws-cdk/aws-cloudwatch.MetricGraphConfig.label",
+      "props-default-doc:@aws-cdk/aws-cloudwatch.MetricGraphConfig.period",
       "props-default-doc:@aws-cdk/aws-cloudwatch.MetricGraphConfig.statistic",
       "props-default-doc:@aws-cdk/aws-cloudwatch.MetricGraphConfig.unit",
+      "props-default-doc:@aws-cdk/aws-cloudwatch.MetricRenderingProperties.color",
+      "props-default-doc:@aws-cdk/aws-cloudwatch.MetricRenderingProperties.label",
+      "props-default-doc:@aws-cdk/aws-cloudwatch.MetricRenderingProperties.stat",
       "props-default-doc:@aws-cdk/aws-cloudwatch.MetricWidgetProps.title",
       "docs-public-apis:@aws-cdk/aws-cloudwatch.Unit.GIGABITS_PER_SECOND",
       "docs-public-apis:@aws-cdk/aws-cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD",

packages/@aws-cdk/aws-cloudwatch/test/test.graphs.ts

@@ -317,4 +317,30 @@ export = {
 
     test.done();
   },
+
+  'allows overriding custom values of dashboard widgets'(test: Test) {
+    class HiddenMetric extends Metric {
+      public toGraphConfig(): any {
+        const ret = super.toGraphConfig();
+        // @ts-ignore
+        ret.renderingProperties.visible = false;
+        return ret;
+      }
+    }
+
+    const stack = new Stack();
+    const widget = new GraphWidget({
+      left: [
+        new HiddenMetric({ namespace: 'CDK', metricName: 'Test' })
+      ]
+    });
+
+    // test.ok(widget.toJson()[0].properties.metrics[0].visible === false);
+    test.deepEqual(
+      stack.resolve(widget.toJson())[0].properties.metrics[0],
+      ["CDK", "Test", { yAxis: 'left', period: 300, stat: 'Average', visible: false }]
+    );
+
+    test.done();
+  },
 };