feat(dynamo): add GSI throttling alarms (#376)

# Change Info
  GSI throttles can occur at times when the underlying table is not throttled. To notify GSI throttles, I added throttle alarms, adapting the pattern in `DynamoTableMonitoring`.

  # Testing Done
  Besides the package build, I deployed a variation of this change on an AWS stack.
 
  # Backwards Compatibility
  New `DynamoTableGlobalSecondaryIndexMonitoringProps` members are optional, so the change is backward-compatible.

---

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

Author: turanyuksel

API.md

@@ -1,18 +1,25 @@
-import { GraphWidget, IWidget } from "aws-cdk-lib/aws-cloudwatch";
+import {
+  GraphWidget,
+  HorizontalAnnotation,
+  IWidget,
+} from "aws-cdk-lib/aws-cloudwatch";
 
 import {
   DynamoTableGlobalSecondaryIndexMetricFactory,
   DynamoTableGlobalSecondaryIndexMetricFactoryProps,
 } from "./DynamoTableGlobalSecondaryIndexMetricFactory";
 import {
   BaseMonitoringProps,
+  CapacityType,
   CountAxisFromZero,
   DefaultGraphWidgetHeight,
   DefaultSummaryWidgetHeight,
+  DynamoAlarmFactory,
   MetricWithAlarmSupport,
   Monitoring,
   MonitoringScope,
   ThirdWidth,
+  ThrottledEventsThreshold,
 } from "../../common";
 import {
   MonitoringHeaderWidget,
@@ -22,7 +29,14 @@ import {
 export interface DynamoTableGlobalSecondaryIndexMonitoringProps
   extends DynamoTableGlobalSecondaryIndexMetricFactoryProps,
     BaseMonitoringProps {
-  // no alarms
+  readonly addReadThrottledEventsCountAlarm?: Record<
+    string,
+    ThrottledEventsThreshold
+  >;
+  readonly addWriteThrottledEventsCountAlarm?: Record<
+    string,
+    ThrottledEventsThreshold
+  >;
 }
 
 export class DynamoTableGlobalSecondaryIndexMonitoring extends Monitoring {
@@ -38,6 +52,9 @@ export class DynamoTableGlobalSecondaryIndexMonitoring extends Monitoring {
   protected readonly writeThrottleCountMetric: MetricWithAlarmSupport;
   protected readonly indexThrottleCountMetric: MetricWithAlarmSupport;
 
+  protected readonly gsiAlarmFactory: DynamoAlarmFactory;
+  protected readonly throttledEventsAnnotations: HorizontalAnnotation[];
+
   constructor(
     scope: MonitoringScope,
     props: DynamoTableGlobalSecondaryIndexMonitoringProps
@@ -74,6 +91,36 @@ export class DynamoTableGlobalSecondaryIndexMonitoring extends Monitoring {
       metricFactory.metricThrottledWriteRequestCount();
     this.indexThrottleCountMetric =
       metricFactory.metricThrottledIndexRequestCount();
+
+    const alarmFactory = scope.createAlarmFactory(
+      namingStrategy.resolveAlarmFriendlyName()
+    );
+    this.gsiAlarmFactory = new DynamoAlarmFactory(alarmFactory);
+    this.throttledEventsAnnotations = [];
+
+    for (const disambiguator in props.addReadThrottledEventsCountAlarm) {
+      const alarmProps = props.addReadThrottledEventsCountAlarm[disambiguator];
+      const createdAlarm = this.gsiAlarmFactory.addThrottledEventsAlarm(
+        this.readThrottleCountMetric,
+        CapacityType.READ,
+        alarmProps,
+        disambiguator
+      );
+      this.throttledEventsAnnotations.push(createdAlarm.annotation);
+      this.addAlarm(createdAlarm);
+    }
+    for (const disambiguator in props.addWriteThrottledEventsCountAlarm) {
+      const alarmProps = props.addWriteThrottledEventsCountAlarm[disambiguator];
+      const createdAlarm = this.gsiAlarmFactory.addThrottledEventsAlarm(
+        this.writeThrottleCountMetric,
+        CapacityType.WRITE,
+        alarmProps,
+        disambiguator
+      );
+      this.throttledEventsAnnotations.push(createdAlarm.annotation);
+      this.addAlarm(createdAlarm);
+    }
+    props.useCreatedAlarms?.consume(this.createdAlarms());
   }
 
   summaryWidgets(): IWidget[] {
@@ -137,6 +184,7 @@ export class DynamoTableGlobalSecondaryIndexMonitoring extends Monitoring {
         this.indexThrottleCountMetric,
       ],
       leftYAxis: CountAxisFromZero,
+      leftAnnotations: this.throttledEventsAnnotations,
     });
   }
 }

lib/monitoring/aws-dynamo/DynamoTableGlobalSecondaryIndexMonitoring.ts

@@ -2,7 +2,10 @@ import { Stack } from "aws-cdk-lib";
 import { Template } from "aws-cdk-lib/assertions";
 import { AttributeType, Table } from "aws-cdk-lib/aws-dynamodb";
 
-import { DynamoTableGlobalSecondaryIndexMonitoring } from "../../../lib";
+import {
+  AlarmWithAnnotation,
+  DynamoTableGlobalSecondaryIndexMonitoring,
+} from "../../../lib";
 import { addMonitoringDashboardsToStack } from "../../utils/SnapshotUtil";
 import { TestMonitoringScope } from "../TestMonitoringScope";
 
@@ -19,11 +22,59 @@ test("snapshot test: no alarms", () => {
     },
   });
 
+  let numAlarmsCreated = 0;
+
   const monitoring = new DynamoTableGlobalSecondaryIndexMonitoring(scope, {
     table,
     globalSecondaryIndexName: "non-existing-index",
+    useCreatedAlarms: {
+      consume(alarms: AlarmWithAnnotation[]) {
+        numAlarmsCreated = alarms.length;
+      },
+    },
+  });
+
+  addMonitoringDashboardsToStack(stack, monitoring);
+  expect(numAlarmsCreated).toStrictEqual(0);
+  expect(Template.fromStack(stack)).toMatchSnapshot();
+});
+
+test("snapshot test: all alarms", () => {
+  const stack = new Stack();
+
+  const scope = new TestMonitoringScope(stack, "Scope");
+
+  const table = new Table(stack, "Table", {
+    tableName: "DummyTable",
+    partitionKey: {
+      name: "id",
+      type: AttributeType.STRING,
+    },
+  });
+
+  let numAlarmsCreated = 0;
+
+  const monitoring = new DynamoTableGlobalSecondaryIndexMonitoring(scope, {
+    table,
+    globalSecondaryIndexName: "non-existing-index",
+    addReadThrottledEventsCountAlarm: {
+      Warning: {
+        maxThrottledEventsThreshold: 5,
+      },
+    },
+    addWriteThrottledEventsCountAlarm: {
+      Warning: {
+        maxThrottledEventsThreshold: 5,
+      },
+    },
+    useCreatedAlarms: {
+      consume(alarms: AlarmWithAnnotation[]) {
+        numAlarmsCreated = alarms.length;
+      },
+    },
   });
 
   addMonitoringDashboardsToStack(stack, monitoring);
+  expect(numAlarmsCreated).toStrictEqual(2);
   expect(Template.fromStack(stack)).toMatchSnapshot();
 });