feat(route53): Support Route53 Health Checks (#411)

WHAT?

Introduce `interface IMetricAdjuster` which allows to adjust a metric
before `AlarmFactory` creates an alarm from it.

Additionally created three implementations of `IMetricAdjuster`:

- `DefaultMetricAdjuster`: Contains the metric adjustment logic which
   used to be inlined in the `AlarmFactory.addAlarm()` method.
- `CompositeMetricAdjuster`: Allows to apply a collection of
  `IMetricAdjuster` instances, one after the other.
- `Route53HealthCheckMetricAdjuster`: Validates a metric's configuration
  and transforms it so that it can be used to create CloudWatch alarms
  compatible with Route53 Health Checks.

WHY?

Route53 Health Checks have strict requirements about which CloudWatch
alarms can be used. By default, alarms created by `MonitoringFacade`
use metrics with the `label` property set which results in alarms that
are incompatible with Route53 Health Checks. This commit introdues an
opt-in `Route53HealthCheckMetricAdjuster` class that allows users to
mark alarms to be suitable for Route53 Health Checks.

HOW?

`npx yarn build` succeeds all the way to `package:js`.

---

_By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license_

Author: marcogrcr

API.md

@@ -254,6 +254,58 @@ monitorCustom({
 
 Search metrics do not support setting an alarm, which is a CloudWatch limitation.
 
+### Route53 Health Checks
+
+Route53 has [strict requirements](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/health-checks-types.html) as to which alarms are allowed to be referenced in Health Checks.
+You adjust the metric for an alarm sot hat it can be used in a Route53 Health Checks as follows:
+
+```ts
+monitoring
+  .monitorSomething(something, {
+    addSomeAlarm: {
+      Warning: {
+        // ...other props
+        metricAdjuster: Route53HealthCheckMetricAdjuster.INSTANCE,
+      }
+    }
+  });
+```
+
+This will ensure the alarm can be used on a Route53 Health Check or otherwise throw an `Error` indicating why the alarm can't be used.
+In order to easily find your Route53 Health Check alarms later on, you can apply a custom tag to them as follows:
+
+```ts
+import { CfnHealthCheck } from "aws-cdk-lib/aws-route53";
+
+monitoring
+  .monitorSomething(something, {
+    addSomeAlarm: {
+      Warning: {
+        // ...other props
+        customTags: ["route53-health-check"],
+        metricAdjuster: Route53HealthCheckMetricAdjuster.INSTANCE,
+      }
+    }
+  });
+
+const alarms = monitoring.createdAlarmsWithTag("route53-health-check");
+
+const healthChecks = alarms.map(({ alarm }) => {
+  const id = getHealthCheckConstructId(alarm);
+
+  return new CfnHealthCheck(scope, id, {
+    healthCheckConfig: {
+      // ...other props
+      type: "CLOUDWATCH_METRIC",
+      alarmIdentifier: {
+        name: alarm.alarmName,
+        region: alarm.stack.region,
+      },
+    },
+  });
+});
+```
+
 ### Custom monitoring segments
 
 If you want even more flexibility, you can create your own segment.

README.md

@@ -20,12 +20,16 @@ import {
 } from "./IAlarmAnnotationStrategy";
 import { IAlarmDedupeStringProcessor } from "./IAlarmDedupeStringProcessor";
 import { IAlarmNamingStrategy } from "./IAlarmNamingStrategy";
+import {
+  CompositeMetricAdjuster,
+  DefaultMetricAdjuster,
+  IMetricAdjuster,
+} from "./metric-adjuster";
 import {
   MetricFactoryDefaults,
   MetricStatistic,
   MetricWithAlarmSupport,
 } from "../metric";
-import { removeBracketsWithDynamicLabels } from "../strings";
 
 const DefaultDatapointsToAlarm = 3;
 
@@ -235,6 +239,13 @@ export interface AddAlarmProps {
    * @default - no override (default visibility)
    */
   readonly overrideAnnotationVisibility?: boolean;
+
+  /**
+   * If specified, adjusts the metric before creating an alarm from it.
+   *
+   * @default - no adjuster
+   */
+  readonly metricAdjuster?: IMetricAdjuster;
 }
 
 /**
@@ -486,19 +497,19 @@ export class AlarmFactory {
     metric: MetricWithAlarmSupport,
     props: AddAlarmProps
   ): AlarmWithAnnotation {
-    // prepare the metric
-
-    let adjustedMetric = metric;
-    if (props.period) {
-      // Adjust metric period for the alarm
-      adjustedMetric = adjustedMetric.with({ period: props.period });
-    }
-    if (adjustedMetric.label) {
-      // Annotations do not support dynamic labels, so we have to remove them from metric name
-      adjustedMetric = adjustedMetric.with({
-        label: removeBracketsWithDynamicLabels(adjustedMetric.label),
-      });
-    }
+    // adjust the metric
+
+    const metricAdjuster = props.metricAdjuster
+      ? CompositeMetricAdjuster.of(
+          props.metricAdjuster,
+          DefaultMetricAdjuster.INSTANCE
+        )
+      : DefaultMetricAdjuster.INSTANCE;
+    const adjustedMetric = metricAdjuster.adjustMetric(
+      metric,
+      this.alarmScope,
+      props
+    );
 
     // prepare primary alarm properties
 

lib/common/alarm/AlarmFactory.ts

@@ -5,6 +5,7 @@ import {
 } from "aws-cdk-lib/aws-cloudwatch";
 
 import { IAlarmActionStrategy } from "./action";
+import { IMetricAdjuster } from "./metric-adjuster";
 
 /**
  * Common customization that can be attached to each alarm.
@@ -136,4 +137,11 @@ export interface CustomAlarmThreshold {
    * @default - false
    */
   readonly fillAlarmRange?: boolean;
+
+  /**
+   * If specified, adjusts the metric before creating an alarm from it.
+   *
+   * @default - no adjuster
+   */
+  readonly metricAdjuster?: IMetricAdjuster;
 }

lib/common/alarm/CustomAlarmThreshold.ts

@@ -1,4 +1,5 @@
 export * from "./action";
+export * from "./metric-adjuster";
 export * from "./AlarmFactory";
 export * from "./AlarmNamingStrategy";
 export * from "./CustomAlarmThreshold";

lib/common/alarm/index.ts

@@ -0,0 +1,29 @@
+import { Construct } from "constructs";
+import { IMetricAdjuster } from "./IMetricAdjuster";
+import { MetricWithAlarmSupport } from "../../metric";
+import { AddAlarmProps } from "../AlarmFactory";
+
+/**
+ * Allows to apply a collection of {@link IMetricAdjuster} to a metric.
+ */
+export class CompositeMetricAdjuster implements IMetricAdjuster {
+  constructor(private readonly adjusters: IMetricAdjuster[]) {}
+
+  static of(...adjusters: IMetricAdjuster[]) {
+    return new CompositeMetricAdjuster(adjusters);
+  }
+
+  /** @inheritdoc */
+  adjustMetric(
+    metric: MetricWithAlarmSupport,
+    alarmScope: Construct,
+    props: AddAlarmProps
+  ): MetricWithAlarmSupport {
+    let adjustedMetric = metric;
+    for (const adjuster of this.adjusters) {
+      adjustedMetric = adjuster.adjustMetric(adjustedMetric, alarmScope, props);
+    }
+
+    return adjustedMetric;
+  }
+}

lib/common/alarm/metric-adjuster/CompositeMetricAdjuster.ts

@@ -0,0 +1,35 @@
+import { Construct } from "constructs";
+import { IMetricAdjuster } from "./IMetricAdjuster";
+import { MetricWithAlarmSupport } from "../../metric";
+import { removeBracketsWithDynamicLabels } from "../../strings";
+import { AddAlarmProps } from "../AlarmFactory";
+
+/**
+ * Applies the default metric adjustments.
+ * These adjustments are always applied last, regardless the value configured in {@link AddAlarmProps.metricAdjuster}.
+ */
+export class DefaultMetricAdjuster implements IMetricAdjuster {
+  static readonly INSTANCE = new DefaultMetricAdjuster();
+
+  /** @inheritdoc */
+  adjustMetric(
+    metric: MetricWithAlarmSupport,
+    _: Construct,
+    props: AddAlarmProps
+  ): MetricWithAlarmSupport {
+    let adjustedMetric = metric;
+    if (props.period) {
+      // Adjust metric period for the alarm
+      adjustedMetric = adjustedMetric.with({ period: props.period });
+    }
+
+    if (adjustedMetric.label) {
+      // Annotations do not support dynamic labels, so we have to remove them from metric name
+      adjustedMetric = adjustedMetric.with({
+        label: removeBracketsWithDynamicLabels(adjustedMetric.label),
+      });
+    }
+
+    return adjustedMetric;
+  }
+}

lib/common/alarm/metric-adjuster/DefaultMetricAdjuster.ts

@@ -0,0 +1,21 @@
+import { Construct } from "constructs";
+import { MetricWithAlarmSupport } from "../../metric";
+import { AddAlarmProps } from "../AlarmFactory";
+
+/**
+ * Adjusts a metric before creating adding an alarm to it.
+ */
+export interface IMetricAdjuster {
+  /**
+   * Adjusts a metric.
+   * @param metric The metric to adjust.
+   * @param alarmScope The alarm scope.
+   * @param props The props specified for adding the alarm.
+   * @returns The adjusted metric.
+   */
+  adjustMetric(
+    metric: MetricWithAlarmSupport,
+    alarmScope: Construct,
+    props: AddAlarmProps
+  ): MetricWithAlarmSupport;
+}

lib/common/alarm/metric-adjuster/IMetricAdjuster.ts

@@ -0,0 +1,87 @@
+import { Stack } from "aws-cdk-lib";
+import { Metric } from "aws-cdk-lib/aws-cloudwatch";
+import { Construct } from "constructs";
+import { IMetricAdjuster } from "./IMetricAdjuster";
+import { MetricStatistic, MetricWithAlarmSupport } from "../../metric";
+import { AddAlarmProps } from "../AlarmFactory";
+
+/**
+ * The supported statistics by Route53 Health Checks.
+ * @see https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/health-checks-types.html
+ */
+const SUPPORTED_STATS = new Set<string>([
+  MetricStatistic.AVERAGE,
+  MetricStatistic.MIN,
+  MetricStatistic.MAX,
+  MetricStatistic.SUM,
+  MetricStatistic.N,
+]);
+
+/**
+ * Adjusts a metric so that alarms created from it can be used in Route53 Health Checks.
+ * The metric will be validated to ensure it satisfies Route53 Health Check alarm requirements, otherwise it will throw an {@link Error}.
+ * @see https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/health-checks-types.html
+ */
+export class Route53HealthCheckMetricAdjuster implements IMetricAdjuster {
+  static readonly INSTANCE = new Route53HealthCheckMetricAdjuster();
+
+  /** @inheritdoc */
+  adjustMetric(
+    metric: MetricWithAlarmSupport,
+    alarmScope: Construct,
+    props: AddAlarmProps
+  ): MetricWithAlarmSupport {
+    // Route53 health checks do not support composite alarms
+    if (props.minMetricSamplesToAlarm) {
+      throw new Error(
+        "Alarms with 'minMetricSamplesToAlarm' are not supported."
+      );
+    }
+
+    // Route53 health checks do to support metric math
+    if (!(metric instanceof Metric)) {
+      throw new Error("The specified metric must be a Metric instance.");
+    }
+
+    const { account, period, statistic } = metric;
+
+    if (account && account !== Stack.of(alarmScope).account) {
+      throw new Error("Cross-account metrics are not supported.");
+    }
+
+    // Route53 health checks do not support high-resolution metrics
+    if (period && period.toSeconds() < 60) {
+      throw new Error("High resolution metrics are not supported.");
+    }
+
+    // Route53 health checks only support a subset of statistics
+    if (!SUPPORTED_STATS.has(statistic)) {
+      throw new Error(
+        `Metrics with statistic '${statistic}' are not supported.`
+      );
+    }
+
+    // Can't use `metric.with()` to remove the label, only change it
+    // See: https://github.com/aws/aws-cdk/blob/v2.65.0/packages/%40aws-cdk/aws-cloudwatch/lib/metric.ts#L314-L342
+    return new Metric({
+      ...metric,
+      // all fields except dimensions have the same names
+      dimensionsMap: metric.dimensions,
+      /*
+       * `AWS::CloudWatch::Alarm` CFN resource types have two variants:
+       * - Based on a single metric: Uses `MetricName` property.
+       * - Based on metric math: Uses `Metrics` property.
+       *
+       * If the `label` of a `Metric` instance is defined, when an
+       * alarm is created from it, even if it doesn't use metric math,
+       * it will use the `Metrics` property. Since Route53 does not
+       * support metric math it assumes any alarm created using the
+       * `Metrics` property must use metric math, thus it must be removed.
+       *
+       * See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudwatch-alarm.html
+       * See: https://github.com/aws/aws-cdk/blob/v2.65.0/packages/@aws-cdk/aws-cloudwatch/lib/alarm.ts#L262-L298
+       */
+      label: undefined,
+    });
+  }
+}

lib/common/alarm/metric-adjuster/Route53HealthCheckMetricAdjuster.ts

@@ -0,0 +1,4 @@
+export * from "./CompositeMetricAdjuster";
+export * from "./DefaultMetricAdjuster";
+export * from "./IMetricAdjuster";
+export * from "./Route53HealthCheckMetricAdjuster";