construct for alarms based on anomaly detection

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

@@ -316,6 +316,41 @@ different between them. This affects both the notifications sent out over SNS,
 as well as the EventBridge events generated by this Alarm. If you are writing
 code to consume these notifications, be sure to handle both formats.
 
+### Anomaly Detection Alarms
+[Anomaly Detection Alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Create_Anomaly_Detection_Alarm.html) are alarms that utilize 
+[CloudWatch anomaly detection](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Anomaly_Detection.html). The `Anomaly Detection Alarm` provides you the ability to either provide a metric that has already defined an expression containing the `ANOMALY_DETECTION_BAND` metric math function:
+```ts
+declare const fn: lambda.Function;
+
+const mathExpr = new MathExpression({
+  expression: `ANOMALY_DETECTION_BAND('m1', 2)`,
+  usingMetrics: { ['m1']: fn.metricErrors() },
+});
+
+new cloudwatch.Alarm(this, 'Alarm', {
+  metric: mathExpr,
+  threshold: 2,
+  evaluationPeriods: 2,
+});
+```
+
+Alternatively, you can set the `generateAnomalyDetectionExpression` property to `true` and the `ANOMALY_DETECTION_BAND` will be automatically added:
+```ts
+declare const fn: lambda.Function;
+
+new cloudwatch.Alarm(this, 'Alarm', {
+  generateAnomalyDetectionExpression: true,
+  metric: fn.metricErrors(),
+  threshold: 2,
+  evaluationPeriods: 2,
+});
+```
+
+The most important properties to set while creating an `Anomaly Detection Alarm` are:
+- `generateAnomalyDetectionExpression`: a boolean flag that denotes whether to automatically generate the `ANOMALY_DETECTION_BAND` metric math function on top of the provide metric, defaults to `false`.
+- `threshold`:  the anomaly detection threshold, used to calculate the band around the metric. This is used only if the `generateAnomalyDetectionExpression` is set to `true`. The value should be a positive number. A higher number creates a thicker band of "normal" values that is more tolerant of metric changes. A lower number creates a thinner band that will go to `ALARM` state with smaller metric deviations.
+- `comparisonOperator`: the comparison operation to use, defaults to `metric > upper band threshold OR metric < lower band threshold`. Only the comparison operators related to the anomaly model band are allowed.
+
 ### Composite Alarms
 
 [Composite Alarms](https://aws.amazon.com/about-aws/whats-new/2020/03/amazon-cloudwatch-now-allows-you-to-combine-multiple-alarms/)

packages/aws-cdk-lib/aws-cloudwatch/lib/alarm-base.ts

@@ -1,5 +1,6 @@
+import { Construct } from 'constructs';
 import { IAlarmAction } from './alarm-action';
-import { IResource, Resource } from '../../core';
+import { ArnFormat, IResource, Resource, Stack } from '../../core';
 
 /**
  * Interface for Alarm Rule.
@@ -37,6 +38,39 @@ export interface IAlarm extends IAlarmRule, IResource {
  */
 export abstract class AlarmBase extends Resource implements IAlarm {
 
+  /**
+   * Import an existing CloudWatch alarm provided a Name.
+   *
+   * @param scope The parent creating construct (usually `this`)
+   * @param id The construct's name
+   * @param alarmName Alarm Name
+   */
+  public static fromAlarmName(scope: Construct, id: string, alarmName: string): IAlarm {
+    const stack = Stack.of(scope);
+
+    return this.fromAlarmArn(scope, id, stack.formatArn({
+      service: 'cloudwatch',
+      resource: 'alarm',
+      resourceName: alarmName,
+      arnFormat: ArnFormat.COLON_RESOURCE_NAME,
+    }));
+  }
+
+  /**
+   * Import an existing CloudWatch alarm provided an ARN
+   *
+   * @param scope The parent creating construct (usually `this`).
+   * @param id The construct's name
+   * @param alarmArn Alarm ARN (i.e. arn:aws:cloudwatch:<region>:<account-id>:alarm:Foo)
+   */
+  public static fromAlarmArn(scope: Construct, id: string, alarmArn: string): IAlarm {
+    class Import extends AlarmBase implements IAlarm {
+      public readonly alarmArn = alarmArn;
+      public readonly alarmName = Stack.of(scope).splitArn(alarmArn, ArnFormat.COLON_RESOURCE_NAME).resourceName!;
+    }
+    return new Import(scope, id);
+  }
+
   /**
    * @attribute
    */