feat(billing): add total cost anomaly alarm (#262)

Fixes #204 

---

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

Author: voho

API.md

@@ -72,7 +72,7 @@ You can browse the documentation at https://constructs.dev/packages/cdk-monitori
 | AWS API Gateway (REST API) (`.monitorApiGateway()`) | TPS, latency, errors | Latency, error count/rate, low/high TPS | To see metrics, you have to enable Advanced Monitoring |
 | AWS API Gateway V2 (HTTP API) (`.monitorApiGatewayV2HttpApi()`) | TPS, latency, errors | Latency, error count/rate, low/high TPS | To see route level metrics, you have to enable Advanced Monitoring |
 | AWS AppSync (GraphQL API) (`.monitorAppSyncApi()`) | TPS, latency, errors | Latency, error count/rate, low/high TPS | |
-| AWS Billing (`.monitorBilling()`) | AWS account cost | | [Requires enabling](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/gs_monitor_estimated_charges_with_cloudwatch.html#gs_turning_on_billing_metrics) the **Receive Billing Alerts** option in AWS Console / Billing Preferences |
+| AWS Billing (`.monitorBilling()`) | AWS account cost | Total cost (anomaly) | [Requires enabling](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/gs_monitor_estimated_charges_with_cloudwatch.html#gs_turning_on_billing_metrics) the **Receive Billing Alerts** option in AWS Console / Billing Preferences |
 | AWS Certificate Manager (`.monitorCertificate()`) | Certificate expiration | Days until expiration | |
 | AWS CloudFront (`.monitorCloudFrontDistribution()`) | TPS, traffic, latency, errors | Error rate, low/high TPS | |
 | AWS CloudWatch Logs (`.monitorLog()`) | Patterns present in the log group | | |

README.md

@@ -1,7 +1,11 @@
 import { Duration } from "aws-cdk-lib";
 import { IMetric, Metric } from "aws-cdk-lib/aws-cloudwatch";
 
-import { MetricStatistic, XaxrMathExpression } from "../../common";
+import {
+  MetricStatistic,
+  MetricWithAlarmSupport,
+  XaxrMathExpression,
+} from "../../common";
 
 export const BillingRegion = "us-east-1";
 export const BillingCurrency = "USD";
@@ -33,7 +37,7 @@ export class BillingMetricFactory {
     });
   }
 
-  metricTotalCostInUsd(): IMetric {
+  metricTotalCostInUsd(): MetricWithAlarmSupport {
     // not using metric factory because we customize everything
 
     return new Metric({

lib/monitoring/aws-billing/BillingMetricFactory.ts

@@ -1,4 +1,3 @@
-import { Stack } from "aws-cdk-lib";
 import {
   GraphWidget,
   GraphWidgetView,
@@ -8,11 +7,15 @@ import {
 } from "aws-cdk-lib/aws-cloudwatch";
 
 import {
+  AlarmFactory,
+  AnomalyDetectingAlarmFactory,
+  AnomalyDetectionThreshold,
   BaseMonitoringProps,
   CurrencyAxisUsdFromZero,
   DefaultGraphWidgetHeight,
   DefaultSummaryWidgetHeight,
   FullWidth,
+  MetricWithAlarmSupport,
   Monitoring,
   MonitoringScope,
   QuarterWidth,
@@ -28,28 +31,53 @@ import {
   BillingRegion,
 } from "./BillingMetricFactory";
 
-export interface BillingMonitoringOptions extends BaseMonitoringProps {}
+export interface BillingMonitoringOptions extends BaseMonitoringProps {
+  readonly addTotalCostAnomalyAlarm?: Record<string, AnomalyDetectionThreshold>;
+}
+
 export interface BillingMonitoringProps extends BillingMonitoringOptions {}
 
 export class BillingMonitoring extends Monitoring {
   readonly title: string;
 
+  readonly alarmFactory: AlarmFactory;
+  readonly anomalyDetectingAlarmFactory: AnomalyDetectingAlarmFactory;
+
   readonly costByServiceMetric: IMetric;
-  readonly totalCostMetric: IMetric;
+  readonly totalCostMetric: MetricWithAlarmSupport;
 
   constructor(scope: MonitoringScope, props: BillingMonitoringProps) {
     super(scope);
 
-    const fallbackConstructName = Stack.of(scope).account;
     const namingStrategy = new MonitoringNamingStrategy({
       ...props,
-      fallbackConstructName,
+      fallbackConstructName: "Billing",
     });
     this.title = namingStrategy.resolveHumanReadableName();
+    this.alarmFactory = scope.createAlarmFactory(
+      namingStrategy.resolveAlarmFriendlyName()
+    );
+    this.anomalyDetectingAlarmFactory = new AnomalyDetectingAlarmFactory(
+      this.alarmFactory
+    );
     const metricFactory = new BillingMetricFactory();
     this.costByServiceMetric =
       metricFactory.metricSearchTopCostByServiceInUsd();
     this.totalCostMetric = metricFactory.metricTotalCostInUsd();
+
+    for (const disambiguator in props.addTotalCostAnomalyAlarm) {
+      const alarmProps = props.addTotalCostAnomalyAlarm[disambiguator];
+      const createdAlarm =
+        this.anomalyDetectingAlarmFactory.addAlarmWhenOutOfBand(
+          this.totalCostMetric,
+          "Cost-Anomaly",
+          disambiguator,
+          alarmProps
+        );
+      this.addAlarm(createdAlarm);
+    }
+
+    props.useCreatedAlarms?.consume(this.createdAlarms());
   }
 
   summaryWidgets(): IWidget[] {

lib/monitoring/aws-billing/BillingMonitoring.ts

@@ -1,7 +1,7 @@
 import { Stack } from "aws-cdk-lib";
 import { Template } from "aws-cdk-lib/assertions";
 
-import { BillingMonitoring } from "../../../lib";
+import { AlarmWithAnnotation, BillingMonitoring } from "../../../lib";
 import { addMonitoringDashboardsToStack } from "../../utils/SnapshotUtil";
 import { TestMonitoringScope } from "../TestMonitoringScope";
 
@@ -17,3 +17,31 @@ test("snapshot test", () => {
   addMonitoringDashboardsToStack(stack, monitoring);
   expect(Template.fromStack(stack)).toMatchSnapshot();
 });
+
+test("snapshot test: all alarms", () => {
+  const stack = new Stack();
+
+  const scope = new TestMonitoringScope(stack, "Scope");
+
+  let numAlarmsCreated = 0;
+
+  const monitoring = new BillingMonitoring(scope, {
+    humanReadableName: "Billing",
+    addTotalCostAnomalyAlarm: {
+      Warning: {
+        alarmWhenBelowTheBand: false,
+        alarmWhenAboveTheBand: true,
+        standardDeviationForAlarm: 5,
+      },
+    },
+    useCreatedAlarms: {
+      consume(alarms: AlarmWithAnnotation[]) {
+        numAlarmsCreated = alarms.length;
+      },
+    },
+  });
+
+  addMonitoringDashboardsToStack(stack, monitoring);
+  expect(numAlarmsCreated).toStrictEqual(1);
+  expect(Template.fromStack(stack)).toMatchSnapshot();
+});