feat(cloudwatch): add id and visible properties for CloudWatch Metric

packages/@aws-cdk-testing/framework-integ/test/aws-cloudwatch/test/integ.dashboard-with-metric-id-and-visible.js.snapshot/DashboardWithMetricIdAndVisibleIntegrationTest.template.json

@@ -0,0 +1,55 @@
+{
+ "Resources": {
+  "DashCCD7F836": {
+   "Type": "AWS::CloudWatch::Dashboard",
+   "Properties": {
+    "DashboardBody": {
+     "Fn::Join": [
+      "",
+      [
+       "{\"widgets\":[{\"type\":\"metric\",\"width\":6,\"height\":6,\"x\":0,\"y\":0,\"properties\":{\"view\":\"timeSeries\",\"title\":\"Metrics with id and visible properties\",\"region\":\"",
+       {
+        "Ref": "AWS::Region"
+       },
+       "\",\"metrics\":[[\"CDK/Test\",\"Metric1\",{\"label\":\"Visible metric with custom ID\",\"id\":\"custom_metric_id\",\"visible\":true}],[\"CDK/Test\",\"Metric2\",{\"label\":\"Hidden metric for calculations\",\"id\":\"hidden_metric_id\",\"visible\":false}],[\"CDK/Test\",\"Metric3\",{\"label\":\"Metric with only ID\",\"id\":\"id_only_metric\"}],[\"CDK/Test\",\"Metric4\",{\"label\":\"Metric with only visible\",\"visible\":true}],[\"CDK/Test\",\"Metric5\",{\"label\":\"Right side hidden metric\",\"id\":\"right_hidden_id\",\"visible\":false,\"yAxis\":\"right\"}]],\"yAxis\":{}}}]}"
+      ]
+     ]
+    }
+   }
+  }
+ },
+ "Parameters": {
+  "BootstrapVersion": {
+   "Type": "AWS::SSM::Parameter::Value<String>",
+   "Default": "/cdk-bootstrap/hnb659fds/version",
+   "Description": "Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]"
+  }
+ },
+ "Rules": {
+  "CheckBootstrapVersion": {
+   "Assertions": [
+    {
+     "Assert": {
+      "Fn::Not": [
+       {
+        "Fn::Contains": [
+         [
+          "1",
+          "2",
+          "3",
+          "4",
+          "5"
+         ],
+         {
+          "Ref": "BootstrapVersion"
+         }
+        ]
+       }
+      ]
+     },
+     "AssertDescription": "CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI."
+    }
+   ]
+  }
+ }
+}

packages/@aws-cdk-testing/framework-integ/test/aws-cloudwatch/test/integ.dashboard-with-metric-id-and-visible.ts

@@ -0,0 +1,62 @@
+import { App, Stack, StackProps } from 'aws-cdk-lib';
+import { IntegTest } from '@aws-cdk/integ-tests-alpha';
+import { Dashboard, Metric, GraphWidget } from 'aws-cdk-lib/aws-cloudwatch';
+
+class DashboardWithMetricIdAndVisibleIntegrationTest extends Stack {
+  constructor(scope: App, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const dashboard = new Dashboard(this, 'Dash');
+
+    const widget = new GraphWidget({
+      title: 'Metrics with id and visible properties',
+      left: [
+        new Metric({
+          namespace: 'CDK/Test',
+          metricName: 'Metric1',
+          label: 'Visible metric with custom ID',
+          id: 'custom_metric_id',
+          visible: true,
+        }),
+
+        new Metric({
+          namespace: 'CDK/Test',
+          metricName: 'Metric2',
+          label: 'Hidden metric for calculations',
+          id: 'hidden_metric_id',
+          visible: false,
+        }),
+
+        new Metric({
+          namespace: 'CDK/Test',
+          metricName: 'Metric3',
+          label: 'Metric with only ID',
+          id: 'id_only_metric',
+        }),
+
+        new Metric({
+          namespace: 'CDK/Test',
+          metricName: 'Metric4',
+          label: 'Metric with only visible',
+          visible: true,
+        }),
+      ],
+      right: [
+        new Metric({
+          namespace: 'CDK/Test',
+          metricName: 'Metric5',
+          label: 'Right side hidden metric',
+          id: 'right_hidden_id',
+          visible: false,
+        }),
+      ],
+    });
+
+    dashboard.addWidgets(widget);
+  }
+}
+
+const app = new App();
+new IntegTest(app, 'cdk-integ-dashboard-with-metric-id-and-visible', {
+  testCases: [new DashboardWithMetricIdAndVisibleIntegrationTest(app, 'DashboardWithMetricIdAndVisibleIntegrationTest')],
+});

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

@@ -53,6 +53,39 @@ const metric = new cloudwatch.Metric({
 });
 ```
 
+### Metric ID
+
+Metrics can be assigned a unique identifier using the `id` property. This is
+useful when referencing metrics in math expressions:
+
+```ts
+const metric = new cloudwatch.Metric({
+  namespace: 'AWS/Lambda',
+  metricName: 'Invocations',
+  dimensionsMap: {
+    FunctionName: 'MyFunction'
+  },
+  id: 'invocations'
+});
+```
+
+The `id` must start with a lowercase letter and can only contain letters, numbers, and underscores.
+
+### Metric Visible
+Metrics can be hidden from dashboard graphs using the `visible` property:
+
+```ts
+declare const fn: lambda.Function;
+
+const metric = fn.metricErrors({
+  visible: false
+});
+```
+
+By default, all metrics are visible (`visible: true`). Setting `visible: false`
+hides the metric from dashboard visualizations while still allowing it to be
+used in math expressions given that it has an `id` set to it.
+
 ### Metric Math
 
 Math expressions are supported by instantiating the `MathExpression` class.