feat(aws-cloudwatch): add verticalAnnotations property to GraphWidget

packages/@aws-cdk/aws-cloudwatch/README.md

@@ -372,7 +372,7 @@ dashboard.addWidgets(new cloudwatch.GraphWidget({
 
 Using the methods `addLeftMetric()` and `addRightMetric()` you can add metrics to a graph widget later on.
 
-Graph widgets can also display annotations attached to the left or the right y-axis.
+Graph widgets can also display annotations attached to the left or right y-axes or the x-axis.
 
 ```ts
 declare const dashboard: cloudwatch.Dashboard;
@@ -384,6 +384,9 @@ dashboard.addWidgets(new cloudwatch.GraphWidget({
     { value: 1800, label: Duration.minutes(30).toHumanString(), color: cloudwatch.Color.RED, },
     { value: 3600, label: '1 hour', color: '#2ca02c', }
   ],
+  verticalAnnotations: [
+    { value: '2022-10-19T00:00:00Z', label: 'Deployment', color: Color.RED, }
+  ]
 }));
 ```
 

packages/@aws-cdk/aws-cloudwatch/lib/graph.ts

@@ -300,6 +300,13 @@ export interface GraphWidgetProps extends MetricWidgetProps {
    */
   readonly rightAnnotations?: HorizontalAnnotation[];
 
+  /**
+   * Annotations for the vertical axis
+   *
+   * @default - No annotations
+   */
+  readonly verticalAnnotations?: VerticalAnnotation[];
+
   /**
    * Whether the graph should be shown as stacked lines
    *
@@ -413,6 +420,11 @@ export class GraphWidget extends ConcreteWidget {
       ...(this.props.leftAnnotations || []).map(mapAnnotation('left')),
       ...(this.props.rightAnnotations || []).map(mapAnnotation('right')),
     ];
+    const verticalAnnotations = this.props.verticalAnnotations || [];
+    const annotations = horizontalAnnotations.length > 0 || verticalAnnotations.length > 0 ? ({
+      horizontal: horizontalAnnotations.length > 0 ? horizontalAnnotations : undefined,
+      vertical: verticalAnnotations.length > 0 ? verticalAnnotations : undefined,
+    }) : undefined;
 
     const metrics = allMetricsGraphJson(this.leftMetrics, this.rightMetrics);
     return [{
@@ -427,7 +439,7 @@ export class GraphWidget extends ConcreteWidget {
         region: this.props.region || cdk.Aws.REGION,
         stacked: this.props.stacked,
         metrics: metrics.length > 0 ? metrics : undefined,
-        annotations: horizontalAnnotations.length > 0 ? { horizontal: horizontalAnnotations } : undefined,
+        annotations,
         yAxis: {
           left: this.props.leftYAxis ?? undefined,
           right: this.props.rightYAxis ?? undefined,
@@ -641,7 +653,46 @@ export interface HorizontalAnnotation {
 }
 
 /**
- * Fill shading options that will be used with an annotation
+ * Vertical annotation to be added to a graph
+ */
+export interface VerticalAnnotation {
+  /**
+   * The date and time in the graph where the vertical annotation line is to appear
+   */
+  readonly value: string;
+
+  /**
+   * Label for the annotation
+   *
+   * @default - No label
+   */
+  readonly label?: string;
+
+  /**
+   * The hex color code, prefixed with '#' (e.g. '#00ff00'), to be used for the annotation.
+   * The `Color` class has a set of standard colors that can be used here.
+   *
+   * @default - Automatic color
+   */
+  readonly color?: string;
+
+  /**
+   * Add shading before or after the annotation
+   *
+   * @default No shading
+   */
+  readonly fill?: VerticalShading;
+
+  /**
+   * Whether the annotation is visible
+   *
+   * @default true
+   */
+  readonly visible?: boolean;
+}
+
+/**
+ * Fill shading options that will be used with a horizontal annotation
  */
 export enum Shading {
   /**
@@ -660,6 +711,26 @@ export enum Shading {
   BELOW = 'below'
 }
 
+/**
+ * Fill shading options that will be used with a vertical annotation
+ */
+export enum VerticalShading {
+  /**
+   * Don't add shading
+   */
+  NONE = 'none',
+
+  /**
+   * Add shading before the annotation
+   */
+  BEFORE = 'before',
+
+  /**
+   * Add shading after the annotation
+   */
+  AFTER = 'after'
+}
+
 /**
  * A set of standard colours that can be used in annotations in a GraphWidget.
  */

packages/@aws-cdk/aws-cloudwatch/test/alarm-and-dashboard.integ.snapshot/aws-cdk-cloudwatch-alarms.template.json

@@ -63,7 +63,7 @@
          "QueueName"
         ]
        },
-       "\"]],\"annotations\":{\"horizontal\":[{\"label\":\"ApproximateNumberOfMessagesVisible >= 100 for 2 datapoints within 15 minutes\",\"value\":100,\"yAxis\":\"left\"}]},\"yAxis\":{}}},{\"type\":\"metric\",\"width\":6,\"height\":3,\"x\":0,\"y\":17,\"properties\":{\"view\":\"singleValue\",\"title\":\"Current messages in queue\",\"region\":\"",
+       "\"]],\"annotations\":{\"horizontal\":[{\"label\":\"ApproximateNumberOfMessagesVisible >= 100 for 2 datapoints within 15 minutes\",\"value\":100,\"yAxis\":\"left\"}],\"vertical\":[{\"value\":\"2022-10-19T00:00:00Z\",\"label\":\"Deployment\",\"color\":\"#d62728\"}]},\"yAxis\":{}}},{\"type\":\"metric\",\"width\":6,\"height\":3,\"x\":0,\"y\":17,\"properties\":{\"view\":\"singleValue\",\"title\":\"Current messages in queue\",\"region\":\"",
        {
         "Ref": "AWS::Region"
        },

packages/@aws-cdk/aws-cloudwatch/test/graphs.test.ts

@@ -1,5 +1,5 @@
 import { Duration, Stack } from '@aws-cdk/core';
-import { Alarm, AlarmWidget, Color, GraphWidget, GraphWidgetView, LegendPosition, LogQueryWidget, Metric, Shading, SingleValueWidget, LogQueryVisualizationType, CustomWidget, GaugeWidget } from '../lib';
+import { Alarm, AlarmWidget, Color, CustomWidget, GaugeWidget, GraphWidget, GraphWidgetView, LegendPosition, LogQueryVisualizationType, LogQueryWidget, Metric, Shading, SingleValueWidget, VerticalShading } from '../lib';
 
 describe('Graphs', () => {
   test('add stacked property to graphs', () => {
@@ -413,7 +413,7 @@ describe('Graphs', () => {
     }]);
   });
 
-  test('add annotations to graph', () => {
+  test('add horizontal annotations to graph', () => {
     // WHEN
     const stack = new Stack();
     const widget = new GraphWidget({
@@ -453,8 +453,49 @@ describe('Graphs', () => {
         yAxis: {},
       },
     }]);
+  });
 
+  test('add vertical annotations to graph', () => {
+    const date = '2021-07-29T02:31:09.890Z';
 
+    // WHEN
+    const stack = new Stack();
+    const widget = new GraphWidget({
+      title: 'My fancy graph',
+      left: [
+        new Metric({ namespace: 'CDK', metricName: 'Test' }),
+      ],
+      verticalAnnotations: [{
+        value: date,
+        color: '667788',
+        fill: VerticalShading.AFTER,
+        label: 'this is the annotation',
+      }],
+    });
+
+    // THEN
+    expect(stack.resolve(widget.toJson())).toEqual([{
+      type: 'metric',
+      width: 6,
+      height: 6,
+      properties: {
+        view: 'timeSeries',
+        title: 'My fancy graph',
+        region: { Ref: 'AWS::Region' },
+        metrics: [
+          ['CDK', 'Test'],
+        ],
+        annotations: {
+          vertical: [{
+            value: date,
+            color: '667788',
+            fill: 'after',
+            label: 'this is the annotation',
+          }],
+        },
+        yAxis: {},
+      },
+    }]);
   });
 
   test('convert alarm to annotation', () => {

packages/@aws-cdk/aws-cloudwatch/test/integ.alarm-and-dashboard.ts

@@ -53,6 +53,13 @@ dashboard.addWidgets(new cloudwatch.GraphWidget({
   title: 'More messages in queue with alarm annotation',
   left: [numberOfMessagesVisibleMetric],
   leftAnnotations: [alarm.toAnnotation()],
+  verticalAnnotations: [
+    {
+      value: '2022-10-19T00:00:00Z',
+      label: 'Deployment',
+      color: cloudwatch.Color.RED,
+    },
+  ],
 }));
 dashboard.addWidgets(new cloudwatch.SingleValueWidget({
   title: 'Current messages in queue',