feat(cloudwatch): Support 'datapointsToAlarm' on Alarms (#1631)

Adds support for settingt the `dataPointsToAlarm` property of the
CloudWatch `Alarm`s (also via the `Metric`s).

Fixes #1626

Author: RomainMuller

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

@@ -1,73 +1,20 @@
 import { Construct, Token } from '@aws-cdk/cdk';
 import { CfnAlarm } from './cloudwatch.generated';
 import { HorizontalAnnotation } from './graph';
-import { Dimension, Metric, Statistic, Unit } from './metric';
+import { Dimension, Metric, MetricAarmProps, Statistic, Unit } from './metric';
 import { parseStatistic } from './util.statistic';
 
 /**
  * Properties for Alarms
  */
-export interface AlarmProps {
+export interface AlarmProps extends MetricAarmProps {
   /**
    * The metric to add the alarm on
    *
    * Metric objects can be obtained from most resources, or you can construct
    * custom Metric objects by instantiating one.
    */
   metric: Metric;
-
-  /**
-   * Name of the alarm
-   *
-   * @default Automatically generated name
-   */
-  alarmName?: string;
-
-  /**
-   * Description for the alarm
-   *
-   * @default No description
-   */
-  alarmDescription?: string;
-
-  /**
-   * Comparison to use to check if metric is breaching
-   *
-   * @default GreaterThanOrEqualToThreshold
-   */
-  comparisonOperator?: ComparisonOperator;
-
-  /**
-   * The value against which the specified statistic is compared.
-   */
-  threshold: number;
-
-  /**
-   * The number of periods over which data is compared to the specified threshold.
-   */
-  evaluationPeriods: number;
-
-  /**
-   * Specifies whether to evaluate the data and potentially change the alarm
-   * state if there are too few data points to be statistically significant.
-   *
-   * Used only for alarms that are based on percentiles.
-   */
-  evaluateLowSampleCountPercentile?: string;
-
-  /**
-   * Sets how this alarm is to handle missing data points.
-   *
-   * @default TreatMissingData.Missing
-   */
-  treatMissingData?: TreatMissingData;
-
-  /**
-   * Whether the actions for this alarm are enabled
-   *
-   * @default true
-   */
-  actionsEnabled?: boolean;
 }
 
 /**
@@ -153,6 +100,7 @@ export class Alarm extends Construct {
       // Evaluation
       comparisonOperator,
       threshold: props.threshold,
+      datapointsToAlarm: props.datapointsToAlarm,
       evaluateLowSampleCountPercentile: props.evaluateLowSampleCountPercentile,
       evaluationPeriods: props.evaluationPeriods,
       treatMissingData: props.treatMissingData,

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

@@ -148,7 +148,7 @@ export class Metric {
    * Combines both properties that may adjust the metric (aggregation) as well
    * as alarm properties.
    */
-  public newAlarm(scope: cdk.Construct, id: string, props: NewAlarmProps): Alarm {
+  public newAlarm(scope: cdk.Construct, id: string, props: MetricAarmProps): Alarm {
     return new Alarm(scope, id, {
       metric: this.with({
         statistic: props.statistic,
@@ -157,6 +157,7 @@ export class Metric {
       alarmName: props.alarmName,
       alarmDescription: props.alarmDescription,
       comparisonOperator: props.comparisonOperator,
+      datapointsToAlarm: props.datapointsToAlarm,
       threshold: props.threshold,
       evaluationPeriods: props.evaluationPeriods,
       evaluateLowSampleCountPercentile: props.evaluateLowSampleCountPercentile,
@@ -293,9 +294,9 @@ export interface MetricCustomization {
 }
 
 /**
- * Properties to make an alarm from a metric
+ * Properties needed to make an alarm from a metric
  */
-export interface NewAlarmProps {
+export interface MetricAarmProps {
   /**
    * The period over which the specified statistic is applied.
    *
@@ -372,6 +373,17 @@ export interface NewAlarmProps {
    * @default true
    */
   actionsEnabled?: boolean;
+
+  /**
+   * The number of datapoints that must be breaching to trigger the alarm. This is used only if you are setting an "M
+   * out of N" alarm. In that case, this value is the M. For more information, see Evaluating an Alarm in the Amazon
+   * CloudWatch User Guide.
+   *
+   * @default ``evaluationPeriods``
+   *
+   * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarm-evaluation
+   */
+  datapointsToAlarm?: number;
 }
 
 function ifUndefined<T>(x: T | undefined, def: T | undefined): T | undefined {

packages/@aws-cdk/aws-cloudwatch/test/integ.alarm-and-dashboard.expected.json

@@ -8,10 +8,8 @@
       "Properties": {
         "ComparisonOperator": "GreaterThanOrEqualToThreshold",
         "EvaluationPeriods": 3,
-        "MetricName": "ApproximateNumberOfMessagesVisible",
-        "Namespace": "AWS/SQS",
-        "Period": 300,
         "Threshold": 100,
+        "DatapointsToAlarm": 2,
         "Dimensions": [
           {
             "Name": "QueueName",
@@ -23,6 +21,9 @@
             }
           }
         ],
+        "MetricName": "ApproximateNumberOfMessagesVisible",
+        "Namespace": "AWS/SQS",
+        "Period": 300,
         "Statistic": "Average"
       }
     },

packages/@aws-cdk/aws-cloudwatch/test/integ.alarm-and-dashboard.ts

@@ -21,7 +21,8 @@ const metric = new cloudwatch.Metric({
 
 const alarm = metric.newAlarm(stack, 'Alarm', {
   threshold: 100,
-  evaluationPeriods: 3
+  evaluationPeriods: 3,
+  datapointsToAlarm: 2,
 });
 
 const dashboard = new cloudwatch.Dashboard(stack, 'Dash');

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

@@ -17,13 +17,40 @@ export = {
     new Alarm(stack, 'Alarm', {
       metric: testMetric,
       threshold: 1000,
-      evaluationPeriods: 2
+      evaluationPeriods: 3,
     });
 
     // THEN
     expect(stack).to(haveResource('AWS::CloudWatch::Alarm', {
       ComparisonOperator: "GreaterThanOrEqualToThreshold",
-      EvaluationPeriods: 2,
+      EvaluationPeriods: 3,
+      MetricName: "Metric",
+      Namespace: "CDK/Test",
+      Period: 300,
+      Statistic: 'Average',
+      Threshold: 1000,
+    }));
+
+    test.done();
+  },
+
+  'can set DatapointsToAlarm'(test: Test) {
+    // GIVEN
+    const stack = new Stack();
+
+    // WHEN
+    new Alarm(stack, 'Alarm', {
+      metric: testMetric,
+      threshold: 1000,
+      evaluationPeriods: 3,
+      datapointsToAlarm: 2,
+    });
+
+    // THEN
+    expect(stack).to(haveResource('AWS::CloudWatch::Alarm', {
+      ComparisonOperator: "GreaterThanOrEqualToThreshold",
+      EvaluationPeriods: 3,
+      DatapointsToAlarm: 2,
       MetricName: "Metric",
       Namespace: "CDK/Test",
       Period: 300,