feat(custom): add support for vertical annotations (#507)

Leveraging aws/aws-cdk#26819

---

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

Author: Eugene Cheung

API.md

@@ -4,6 +4,7 @@ import {
   HorizontalAnnotation,
   IMetric,
   LegendPosition,
+  VerticalAnnotation,
   YAxisProps,
 } from "aws-cdk-lib/aws-cloudwatch";
 
@@ -14,6 +15,7 @@ export interface SingleAxisGraphWidgetProps {
   readonly leftMetrics: IMetric[];
   readonly leftAxis: YAxisProps;
   readonly leftAnnotations?: HorizontalAnnotation[];
+  readonly verticalAnnotations?: VerticalAnnotation[];
 }
 
 /**
@@ -44,6 +46,7 @@ export class SingleAxisGraphWidget extends GraphWidget {
       left: props.leftMetrics,
       leftYAxis: props.leftAxis,
       leftAnnotations: props.leftAnnotations,
+      verticalAnnotations: props.verticalAnnotations,
       legendPosition,
     };
   }
@@ -59,6 +62,7 @@ export interface DoubleAxisGraphWidgetProps {
   readonly rightMetrics: IMetric[];
   readonly rightAxis: YAxisProps;
   readonly rightAnnotations?: HorizontalAnnotation[];
+  readonly verticalAnnotations?: VerticalAnnotation[];
 }
 
 /**
@@ -95,6 +99,7 @@ export class DoubleAxisGraphWidget extends GraphWidget {
       right: props.rightMetrics,
       rightYAxis: props.rightAxis,
       rightAnnotations: props.rightAnnotations,
+      verticalAnnotations: props.verticalAnnotations,
     };
   }
 }

lib/dashboard/widget/StrictGraphWidget.ts

@@ -9,6 +9,7 @@ import {
   LegendPosition,
   Row,
   TextWidget,
+  VerticalAnnotation,
   YAxisProps,
 } from "aws-cdk-lib/aws-cloudwatch";
 
@@ -188,15 +189,19 @@ export interface CustomMetricGroup {
    */
   readonly metrics: CustomMetric[];
   /**
-   * optional custom horizontal annotations which will be displayed over the metrics on the left axis
-   * (if there are any alarms, any existing annotations will be merged together)
+   * Optional custom horizontal annotations which will be displayed over the metrics on the left axis
+   * (if there are any alarms, any existing annotations will be merged together).
    */
   readonly horizontalAnnotations?: HorizontalAnnotation[];
   /**
-   * optional custom horizontal annotations which will be displayed over the metrics on the right axis
-   * (if there are any alarms, any existing annotations will be merged together)
+   * Optional custom horizontal annotations which will be displayed over the metrics on the right axis
+   * (if there are any alarms, any existing annotations will be merged together).
    */
   readonly horizontalRightAnnotations?: HorizontalAnnotation[];
+  /**
+   * Optional custom vertical annotations which will be displayed over the metrics.
+   */
+  readonly verticalAnnotations?: VerticalAnnotation[];
 }
 
 export interface CustomMonitoringProps extends BaseMonitoringProps {
@@ -225,6 +230,7 @@ export interface CustomMetricGroupWithAnnotations {
   readonly metricGroup: CustomMetricGroup;
   readonly annotations: HorizontalAnnotation[];
   readonly rightAnnotations: HorizontalAnnotation[];
+  readonly verticalAnnotations: VerticalAnnotation[];
   readonly titleAddons: string[];
   readonly height?: number;
 }
@@ -270,6 +276,7 @@ export class CustomMonitoring extends Monitoring {
         metricGroup,
         annotations: [],
         rightAnnotations: [],
+        verticalAnnotations: [],
         titleAddons: [],
       };
 
@@ -283,6 +290,11 @@ export class CustomMonitoring extends Monitoring {
           ...metricGroup.horizontalRightAnnotations
         );
       }
+      if (metricGroup.verticalAnnotations) {
+        metricGroupWithAnnotation.verticalAnnotations.push(
+          ...metricGroup.verticalAnnotations
+        );
+      }
 
       metricGroup.metrics.forEach((metric) => {
         if (this.hasAlarm(metric) && this.hasAnomalyDetection(metric)) {
@@ -412,6 +424,7 @@ export class CustomMonitoring extends Monitoring {
         rightAnnotations: annotatedGroup.rightAnnotations,
         leftYAxis: annotatedGroup.metricGroup.graphWidgetAxis,
         rightYAxis: annotatedGroup.metricGroup.graphWidgetRightAxis,
+        verticalAnnotations: annotatedGroup.verticalAnnotations,
         legendPosition: annotatedGroup.metricGroup.graphWidgetLegend,
         setPeriodToTimeRange:
           annotatedGroup.metricGroup.graphWidgetSetPeriodToTimeRange,

lib/monitoring/custom/CustomMonitoring.ts

@@ -1,6 +1,8 @@
 import {
   HorizontalAnnotation,
   Metric,
+  VerticalAnnotation,
+  VerticalShading,
   YAxisProps,
 } from "aws-cdk-lib/aws-cloudwatch";
 import { DoubleAxisGraphWidget, SingleAxisGraphWidget } from "../../../lib";
@@ -11,6 +13,12 @@ const DummyAxis1: YAxisProps = { min: 0, max: 1 };
 const DummyAxis2: YAxisProps = { min: 100, max: 200 };
 const DummyAnnotation1: HorizontalAnnotation = { value: 42 };
 const DummyAnnotation2: HorizontalAnnotation = { value: 66 };
+const DummyVerticalAnnotation: VerticalAnnotation = {
+  date: "2021-07-29T02:31:09.890Z",
+  color: "123456",
+  fill: VerticalShading.BEFORE,
+  label: "Custom vertical annotation",
+};
 
 test("single axis - single metric: snapshot test", () => {
   const widget = new SingleAxisGraphWidget({
@@ -33,6 +41,7 @@ test("single axis - two metrics: snapshot test", () => {
     leftMetrics: [DummyMetric1, DummyMetric2],
     leftAnnotations: [DummyAnnotation1],
     leftAxis: DummyAxis1,
+    verticalAnnotations: [DummyVerticalAnnotation],
   });
 
   expect(removeRegionToken(widget.toJson())).toMatchSnapshot();
@@ -49,6 +58,7 @@ test("double axis - two metrics: snapshot test", () => {
     rightMetrics: [DummyMetric1],
     rightAxis: DummyAxis2,
     rightAnnotations: [DummyAnnotation2],
+    verticalAnnotations: [DummyVerticalAnnotation],
   });
 
   expect(removeRegionToken(widget.toJson())).toMatchSnapshot();

test/dashboard/widget/StrictGraphWidget.test.ts

@@ -6,6 +6,7 @@ import {
   MathExpression,
   Metric,
   Shading,
+  VerticalShading,
 } from "aws-cdk-lib/aws-cloudwatch";
 
 import {
@@ -153,6 +154,14 @@ test("snapshot test", () => {
         horizontalRightAnnotations: [
           { label: "DummyAnnotation3", value: 20, fill: Shading.BELOW },
         ],
+        verticalAnnotations: [
+          {
+            date: "2021-07-29T02:31:09.890Z",
+            color: "667788",
+            fill: VerticalShading.AFTER,
+            label: "this is a vertical annotation",
+          },
+        ],
         graphWidgetLegend: LegendPosition.RIGHT,
       },
       {