feat: allow users to customize alarm annotation properties (#184)

Allow users to override 1) color 2) label 3) visibility of the alarm annotation.

---

_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

@@ -1983,6 +1983,9 @@ const addAlarmProps: AddAlarmProps = { ... }
 | <code><a href="#cdk-monitoring-constructs.AddAlarmProps.property.evaluateLowSampleCountPercentile">evaluateLowSampleCountPercentile</a></code> | <code>boolean</code> | Used only for alarms based on percentiles. |
 | <code><a href="#cdk-monitoring-constructs.AddAlarmProps.property.evaluationPeriods">evaluationPeriods</a></code> | <code>number</code> | Number of periods to consider when checking the number of breaching datapoints. |
 | <code><a href="#cdk-monitoring-constructs.AddAlarmProps.property.fillAlarmRange">fillAlarmRange</a></code> | <code>boolean</code> | Indicates whether the alarming range of values should be highlighted in the widget. |
+| <code><a href="#cdk-monitoring-constructs.AddAlarmProps.property.overrideAnnotationColor">overrideAnnotationColor</a></code> | <code>string</code> | If specified, it modifies the final alarm annotation color. |
+| <code><a href="#cdk-monitoring-constructs.AddAlarmProps.property.overrideAnnotationLabel">overrideAnnotationLabel</a></code> | <code>string</code> | If specified, it modifies the final alarm annotation label. |
+| <code><a href="#cdk-monitoring-constructs.AddAlarmProps.property.overrideAnnotationVisibility">overrideAnnotationVisibility</a></code> | <code>boolean</code> | If specified, it modifies the final alarm annotation visibility. |
 | <code><a href="#cdk-monitoring-constructs.AddAlarmProps.property.period">period</a></code> | <code>aws-cdk-lib.Duration</code> | Period override for the metric to alarm on. |
 | <code><a href="#cdk-monitoring-constructs.AddAlarmProps.property.runbookLink">runbookLink</a></code> | <code>string</code> | An optional link included in the generated ticket description body. |
 
@@ -2240,6 +2243,45 @@ Indicates whether the alarming range of values should be highlighted in the widg
 
 ---
 
+##### `overrideAnnotationColor`<sup>Optional</sup> <a name="overrideAnnotationColor" id="cdk-monitoring-constructs.AddAlarmProps.property.overrideAnnotationColor"></a>
+
+```typescript
+public readonly overrideAnnotationColor: string;
+```
+
+- *Type:* string
+- *Default:* no override (default color)
+
+If specified, it modifies the final alarm annotation color.
+
+---
+
+##### `overrideAnnotationLabel`<sup>Optional</sup> <a name="overrideAnnotationLabel" id="cdk-monitoring-constructs.AddAlarmProps.property.overrideAnnotationLabel"></a>
+
+```typescript
+public readonly overrideAnnotationLabel: string;
+```
+
+- *Type:* string
+- *Default:* no override (default label)
+
+If specified, it modifies the final alarm annotation label.
+
+---
+
+##### `overrideAnnotationVisibility`<sup>Optional</sup> <a name="overrideAnnotationVisibility" id="cdk-monitoring-constructs.AddAlarmProps.property.overrideAnnotationVisibility"></a>
+
+```typescript
+public readonly overrideAnnotationVisibility: boolean;
+```
+
+- *Type:* boolean
+- *Default:* no override (default visibility)
+
+If specified, it modifies the final alarm annotation visibility.
+
+---
+
 ##### `period`<sup>Optional</sup> <a name="period" id="cdk-monitoring-constructs.AddAlarmProps.property.period"></a>
 
 ```typescript
@@ -2613,6 +2655,9 @@ const alarmAnnotationStrategyProps: AlarmAnnotationStrategyProps = { ... }
 | <code><a href="#cdk-monitoring-constructs.AlarmAnnotationStrategyProps.property.fillAlarmRange">fillAlarmRange</a></code> | <code>boolean</code> | *No description.* |
 | <code><a href="#cdk-monitoring-constructs.AlarmAnnotationStrategyProps.property.metric">metric</a></code> | <code>aws-cdk-lib.aws_cloudwatch.Metric \| aws-cdk-lib.aws_cloudwatch.MathExpression</code> | *No description.* |
 | <code><a href="#cdk-monitoring-constructs.AlarmAnnotationStrategyProps.property.threshold">threshold</a></code> | <code>number</code> | *No description.* |
+| <code><a href="#cdk-monitoring-constructs.AlarmAnnotationStrategyProps.property.overrideAnnotationColor">overrideAnnotationColor</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#cdk-monitoring-constructs.AlarmAnnotationStrategyProps.property.overrideAnnotationLabel">overrideAnnotationLabel</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#cdk-monitoring-constructs.AlarmAnnotationStrategyProps.property.overrideAnnotationVisibility">overrideAnnotationVisibility</a></code> | <code>boolean</code> | *No description.* |
 
 ---
 
@@ -2736,6 +2781,36 @@ public readonly threshold: number;
 
 ---
 
+##### `overrideAnnotationColor`<sup>Optional</sup> <a name="overrideAnnotationColor" id="cdk-monitoring-constructs.AlarmAnnotationStrategyProps.property.overrideAnnotationColor"></a>
+
+```typescript
+public readonly overrideAnnotationColor: string;
+```
+
+- *Type:* string
+
+---
+
+##### `overrideAnnotationLabel`<sup>Optional</sup> <a name="overrideAnnotationLabel" id="cdk-monitoring-constructs.AlarmAnnotationStrategyProps.property.overrideAnnotationLabel"></a>
+
+```typescript
+public readonly overrideAnnotationLabel: string;
+```
+
+- *Type:* string
+
+---
+
+##### `overrideAnnotationVisibility`<sup>Optional</sup> <a name="overrideAnnotationVisibility" id="cdk-monitoring-constructs.AlarmAnnotationStrategyProps.property.overrideAnnotationVisibility"></a>
+
+```typescript
+public readonly overrideAnnotationVisibility: boolean;
+```
+
+- *Type:* boolean
+
+---
+
 ### AlarmFactoryDefaults <a name="AlarmFactoryDefaults" id="cdk-monitoring-constructs.AlarmFactoryDefaults"></a>
 
 #### Initializer <a name="Initializer" id="cdk-monitoring-constructs.AlarmFactoryDefaults.Initializer"></a>

lib/common/alarm/AlarmFactory.ts

@@ -198,6 +198,27 @@ export interface AddAlarmProps {
    * @default false
    */
   readonly fillAlarmRange?: boolean;
+
+  /**
+   * If specified, it modifies the final alarm annotation color.
+   *
+   * @default no override (default color)
+   */
+  readonly overrideAnnotationColor?: string;
+
+  /**
+   * If specified, it modifies the final alarm annotation label.
+   *
+   * @default no override (default label)
+   */
+  readonly overrideAnnotationLabel?: string;
+
+  /**
+   * If specified, it modifies the final alarm annotation visibility.
+   *
+   * @default no override (default visibility)
+   */
+  readonly overrideAnnotationVisibility?: boolean;
 }
 
 /**
@@ -507,6 +528,9 @@ export class AlarmFactory {
       datapointsToAlarm,
       dedupeString,
       fillAlarmRange: props.fillAlarmRange ?? false,
+      overrideAnnotationColor: props.overrideAnnotationColor,
+      overrideAnnotationLabel: props.overrideAnnotationLabel,
+      overrideAnnotationVisibility: props.overrideAnnotationVisibility,
       comparisonOperator: props.comparisonOperator,
       threshold: props.threshold,
       disambiguator: props.disambiguator,

lib/common/alarm/IAlarmAnnotationStrategy.ts

@@ -16,6 +16,9 @@ export interface AlarmAnnotationStrategyProps extends AlarmMetadata {
   readonly datapointsToAlarm: number;
   readonly evaluationPeriods: number;
   readonly fillAlarmRange: boolean;
+  readonly overrideAnnotationColor?: string;
+  readonly overrideAnnotationLabel?: string;
+  readonly overrideAnnotationVisibility?: boolean;
 }
 
 /**
@@ -36,11 +39,21 @@ export abstract class FillingAlarmAnnotationStrategy
   implements IAlarmAnnotationStrategy
 {
   createAnnotation(props: AlarmAnnotationStrategyProps): HorizontalAnnotation {
-    const annotation = this.createAnnotationToFill(props);
-    if (props.fillAlarmRange) {
-      return { ...annotation, fill: this.getAlarmingRangeShade(props) };
-    }
-    return annotation;
+    return {
+      ...this.createAnnotationToFill(props),
+      ...(props.fillAlarmRange && {
+        fill: this.getAlarmingRangeShade(props),
+      }),
+      ...(props.overrideAnnotationColor !== undefined && {
+        color: props.overrideAnnotationColor,
+      }),
+      ...(props.overrideAnnotationLabel !== undefined && {
+        label: props.overrideAnnotationLabel,
+      }),
+      ...(props.overrideAnnotationVisibility !== undefined && {
+        visible: props.overrideAnnotationVisibility,
+      }),
+    };
   }
 
   protected abstract createAnnotationToFill(

test/common/alarm/AlarmFactory.test.ts

@@ -229,6 +229,29 @@ test("addAlarm: fill is propagated to alarm annotation", () => {
   expect(alarmBelow.annotation.fill).toStrictEqual(Shading.BELOW);
 });
 
+test("addAlarm: annotation overrides are applied", () => {
+  const stack = new Stack();
+  const factory = new AlarmFactory(stack, {
+    globalMetricDefaults,
+    globalAlarmDefaults,
+    localAlarmNamePrefix: "prefix",
+  });
+  const alarm = factory.addAlarm(metric, {
+    ...props,
+    alarmNameSuffix: "none",
+    comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
+    overrideAnnotationLabel: "NewLabel",
+    overrideAnnotationVisibility: false,
+    overrideAnnotationColor: "NewColor",
+  });
+  expect(alarm.annotation).toStrictEqual({
+    color: "NewColor",
+    label: "NewLabel",
+    value: 10,
+    visible: false,
+  });
+});
+
 test("addCompositeAlarm: snapshot for operator", () => {
   const stack = new Stack();
   const factory = new AlarmFactory(stack, {