diff --git a/packages/@aws-cdk/aws-cloudwatch/README.md b/packages/@aws-cdk/aws-cloudwatch/README.md index ff1f1997489f4..c1510e0e915c4 100644 --- a/packages/@aws-cdk/aws-cloudwatch/README.md +++ b/packages/@aws-cdk/aws-cloudwatch/README.md @@ -255,7 +255,7 @@ dashboard.addWidgets(new 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 dashboard.addWidgets(new GraphWidget({ @@ -266,6 +266,9 @@ dashboard.addWidgets(new GraphWidget({ { value: 1800, label: Duration.minutes(30).toHumanString(), color: Color.RED, }, { value: 3600, label: '1 hour', color: '#2ca02c', } ], + verticalAnnotations: [ + { value: '2022-10-19T00:00:00Z', label: 'Deployment', color: Color.RED, } + ] })); ``` diff --git a/packages/@aws-cdk/aws-cloudwatch/lib/graph.ts b/packages/@aws-cdk/aws-cloudwatch/lib/graph.ts index 709baba719109..423a531796695 100644 --- a/packages/@aws-cdk/aws-cloudwatch/lib/graph.ts +++ b/packages/@aws-cdk/aws-cloudwatch/lib/graph.ts @@ -171,6 +171,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 * @@ -281,6 +288,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 [{ @@ -295,7 +307,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, @@ -404,7 +416,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 { /** @@ -423,6 +474,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. */ diff --git a/packages/@aws-cdk/aws-cloudwatch/test/graphs.test.ts b/packages/@aws-cdk/aws-cloudwatch/test/graphs.test.ts index 0c1adfb58b1f8..51b165c47f965 100644 --- a/packages/@aws-cdk/aws-cloudwatch/test/graphs.test.ts +++ b/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 } from '../lib'; +import { Alarm, AlarmWidget, Color, GraphWidget, GraphWidgetView, LegendPosition, LogQueryWidget, Metric, Shading, SingleValueWidget, LogQueryVisualizationType, VerticalShading } from '../lib'; describe('Graphs', () => { test('add stacked property to graphs', () => { @@ -348,7 +348,7 @@ describe('Graphs', () => { }); - test('add annotations to graph', () => { + test('add horizontal annotations to graph', () => { // WHEN const stack = new Stack(); const widget = new GraphWidget({ @@ -388,8 +388,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', () => { diff --git a/packages/@aws-cdk/aws-cloudwatch/test/integ.alarm-and-dashboard.ts b/packages/@aws-cdk/aws-cloudwatch/test/integ.alarm-and-dashboard.ts index 1ca941d8519b4..f3da11d42579a 100644 --- a/packages/@aws-cdk/aws-cloudwatch/test/integ.alarm-and-dashboard.ts +++ b/packages/@aws-cdk/aws-cloudwatch/test/integ.alarm-and-dashboard.ts @@ -49,6 +49,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',