feat(cloudwatch): add gauge widget (#22213)

Description:
GraphWidget doesn't have the option to create gauge graphs, and adding gauge to `GraphWidgetView` doesn't solve this problem because gauge graphs require left Y axis settings with min and max value and in `GraphView` this is optional

Solution:
I created a custom `GaugeWidget` to solve this issue

Closes #22136
----

### All Submissions:

* [x] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [x] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [x] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*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

@@ -399,6 +399,24 @@ dashboard.addWidgets(new cloudwatch.GraphWidget({
 }));
 ```
 
+### Gauge widget
+
+Gauge graph requires the max and min value of the left Y axis, if no value is informed the limits will be from 0 to 100.
+
+```ts
+declare const dashboard: cloudwatch.Dashboard;
+declare const errorAlarm: cloudwatch.Alarm;
+declare const gaugeMetric: cloudwatch.Metric;
+
+dashboard.addWidgets(new cloudwatch.GaugeWidget({
+  metrics: [gaugeMetric],
+  leftYAxis: {
+    min: 0,
+    max: 1000,
+  }
+}));
+```
+
 ### Alarm widget
 
 An alarm widget shows the graph and the alarm line of a single alarm:

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

@@ -139,6 +139,135 @@ export enum GraphWidgetView {
   PIE = 'pie',
 }
 
+/**
+ * Properties for a GaugeWidget
+ */
+export interface GaugeWidgetProps extends MetricWidgetProps {
+  /**
+   * Metrics to display on left Y axis
+   *
+   * @default - No metrics
+   */
+  readonly metrics?: IMetric[];
+
+  /**
+   * Annotations for the left Y axis
+   *
+   * @default - No annotations
+   */
+  readonly annotations?: HorizontalAnnotation[];
+
+  /**
+   * Left Y axis
+   *
+   * @default - None
+   */
+  readonly leftYAxis?: YAxisProps;
+
+  /**
+   * Position of the legend
+   *
+   * @default - bottom
+   */
+  readonly legendPosition?: LegendPosition;
+
+  /**
+   * Whether the graph should show live data
+   *
+   * @default false
+   */
+  readonly liveData?: boolean;
+
+  /**
+   * Whether to show the value from the entire time range. Only applicable for Bar and Pie charts.
+   *
+   * If false, values will be from the most recent period of your chosen time range;
+   * if true, shows the value from the entire time range.
+   *
+   * @default false
+   */
+  readonly setPeriodToTimeRange?: boolean;
+
+  /**
+   * The default period for all metrics in this widget.
+   * The period is the length of time represented by one data point on the graph.
+   * This default can be overridden within each metric definition.
+   *
+   * @default cdk.Duration.seconds(300)
+   */
+  readonly period?: cdk.Duration;
+
+  /**
+   * The default statistic to be displayed for each metric.
+   * This default can be overridden within the definition of each individual metric
+   *
+   * @default - The statistic for each metric is used
+   */
+  readonly statistic?: string;
+}
+
+/**
+ * A dashboard gauge widget that displays metrics
+ */
+export class GaugeWidget extends ConcreteWidget {
+
+  private readonly props: GaugeWidgetProps;
+
+  private readonly metrics: IMetric[];
+
+  constructor(props: GaugeWidgetProps) {
+    super(props.width || 6, props.height || 6);
+    this.props = props;
+    this.metrics = props.metrics ?? [];
+    this.copyMetricWarnings(...this.metrics);
+  }
+
+  /**
+   * Add another metric to the left Y axis of the GaugeWidget
+   *
+   * @param metric the metric to add
+   */
+  public addMetric(metric: IMetric) {
+    this.metrics.push(metric);
+    this.copyMetricWarnings(metric);
+  }
+
+  public toJson(): any[] {
+    const horizontalAnnotations = [
+      ...(this.props.annotations || []).map(mapAnnotation('annotations')),
+    ];
+
+    const metrics = allMetricsGraphJson(this.metrics, []);
+    const leftYAxis = {
+      ...this.props.leftYAxis,
+      min: this.props.leftYAxis?.min ?? 0,
+      max: this.props.leftYAxis?.max ?? 100,
+    };
+    return [{
+      type: 'metric',
+      width: this.width,
+      height: this.height,
+      x: this.x,
+      y: this.y,
+      properties: {
+        view: 'gauge',
+        title: this.props.title,
+        region: this.props.region || cdk.Aws.REGION,
+        metrics: metrics.length > 0 ? metrics : undefined,
+        annotations: horizontalAnnotations.length > 0 ? { horizontal: horizontalAnnotations } : undefined,
+        yAxis: {
+          left: leftYAxis ?? undefined,
+        },
+        legend: this.props.legendPosition !== undefined ? { position: this.props.legendPosition } : undefined,
+        liveData: this.props.liveData,
+        setPeriodToTimeRange: this.props.setPeriodToTimeRange,
+        period: this.props.period?.toSeconds(),
+        stat: this.props.statistic,
+      },
+    }];
+  }
+}
+
 /**
  * Properties for a GraphWidget
  */

packages/@aws-cdk/aws-cloudwatch/test/gauge-alarm.integ.snapshot/GaugeAlarmIntegrationTestDefaultTestDeployAssertF43E2A2D.assets.json

@@ -0,0 +1,19 @@
+{
+  "version": "21.0.0",
+  "files": {
+    "21fbb51d7b23f6a6c262b46a9caee79d744a3ac019fd45422d988b96d44b2a22": {
+      "source": {
+        "path": "GaugeAlarmIntegrationTestDefaultTestDeployAssertF43E2A2D.template.json",
+        "packaging": "file"
+      },
+      "destinations": {
+        "current_account-current_region": {
+          "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
+          "objectKey": "21fbb51d7b23f6a6c262b46a9caee79d744a3ac019fd45422d988b96d44b2a22.json",
+          "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
+        }
+      }
+    }
+  },
+  "dockerImages": {}
+}

packages/@aws-cdk/aws-cloudwatch/test/gauge-alarm.integ.snapshot/GaugeAlarmIntegrationTestDefaultTestDeployAssertF43E2A2D.template.json

@@ -0,0 +1,36 @@
+{
+ "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/aws-cloudwatch/test/gauge-alarm.integ.snapshot/cdk.out

@@ -0,0 +1 @@
+{"version":"21.0.0"}

packages/@aws-cdk/aws-cloudwatch/test/gauge-alarm.integ.snapshot/gauge-alarm.assets.json

@@ -0,0 +1,19 @@
+{
+  "version": "21.0.0",
+  "files": {
+    "8f02ef0ee3c900b85f9315a4a4807bd1e86f92b80d77cadc667b2b21b5b34e0b": {
+      "source": {
+        "path": "gauge-alarm.template.json",
+        "packaging": "file"
+      },
+      "destinations": {
+        "current_account-current_region": {
+          "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
+          "objectKey": "8f02ef0ee3c900b85f9315a4a4807bd1e86f92b80d77cadc667b2b21b5b34e0b.json",
+          "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
+        }
+      }
+    }
+  },
+  "dockerImages": {}
+}

packages/@aws-cdk/aws-cloudwatch/test/gauge-alarm.integ.snapshot/gauge-alarm.template.json

@@ -0,0 +1,66 @@
+{
+ "Resources": {
+  "queue": {
+   "Type": "AWS::SQS::Queue"
+  },
+  "DashCCD7F836": {
+   "Type": "AWS::CloudWatch::Dashboard",
+   "Properties": {
+    "DashboardBody": {
+     "Fn::Join": [
+      "",
+      [
+       "{\"widgets\":[{\"type\":\"metric\",\"width\":24,\"height\":6,\"x\":0,\"y\":0,\"properties\":{\"view\":\"gauge\",\"region\":\"",
+       {
+        "Ref": "AWS::Region"
+       },
+       "\",\"metrics\":[[\"AWS/SQS\",\"ApproximateNumberOfMessagesVisible\",\"QueueName\",\"",
+       {
+        "Fn::GetAtt": [
+         "queue",
+         "QueueName"
+        ]
+       },
+       "\"]],\"yAxis\":{\"left\":{\"max\":500,\"min\":0}}}}]}"
+      ]
+     ]
+    },
+    "DashboardName": "MyCustomGaugeAlarm"
+   }
+  }
+ },
+ "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/aws-cloudwatch/test/gauge-alarm.integ.snapshot/integ.json

@@ -0,0 +1,12 @@
+{
+  "version": "21.0.0",
+  "testCases": {
+    "GaugeAlarmIntegrationTest/DefaultTest": {
+      "stacks": [
+        "gauge-alarm"
+      ],
+      "assertionStack": "GaugeAlarmIntegrationTest/DefaultTest/DeployAssert",
+      "assertionStackName": "GaugeAlarmIntegrationTestDefaultTestDeployAssertF43E2A2D"
+    }
+  }
+}