diff --git a/packages/@aws-cdk/aws-cloudwatch/README.md b/packages/@aws-cdk/aws-cloudwatch/README.md index 1d409cf098257..2583f97e5d48e 100644 --- a/packages/@aws-cdk/aws-cloudwatch/README.md +++ b/packages/@aws-cdk/aws-cloudwatch/README.md @@ -206,11 +206,25 @@ dashboard.addWidgets(new GraphWidget({ right: [errorCountMetric.with({ statistic: "average", label: "Error rate", - color: "00FF00" + color: Color.GREEN })] })); ``` +Graph widgets can also display annotations attached to the left or the right y-axis. + +```ts +dashboard.addWidgets(new GraphWidget({ + // ... + // ... + + leftAnnotations: [ + { value: 1800, label: Duration.minutes(30).toHumanString(), color: Color.RED, }, + { value: 3600, label: '1 hour', color: '#2ca02c', } + ], +})); +``` + ### Alarm widget An alarm widget shows the graph and the alarm line of a single alarm: diff --git a/packages/@aws-cdk/aws-cloudwatch/lib/graph.ts b/packages/@aws-cdk/aws-cloudwatch/lib/graph.ts index d506a0369d723..456a26bb7be3d 100644 --- a/packages/@aws-cdk/aws-cloudwatch/lib/graph.ts +++ b/packages/@aws-cdk/aws-cloudwatch/lib/graph.ts @@ -251,14 +251,15 @@ export interface HorizontalAnnotation { /** * Label for the annotation * - * @default No label + * @default - No label */ readonly label?: string; /** - * Hex color code to be used for the annotation + * 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 + * @default - Automatic color */ readonly color?: string; @@ -294,6 +295,35 @@ export enum Shading { BELOW = 'below' } +/** + * A set of standard colours that can be used in annotations in a GraphWidget. + */ +export class Color { + /** blue - hex #1f77b4 */ + public static readonly BLUE = '#1f77b4'; + + /** brown - hex #8c564b */ + public static readonly BROWN = '#8c564b'; + + /** green - hex #2ca02c */ + public static readonly GREEN = '#2ca02c'; + + /** grey - hex #7f7f7f */ + public static readonly GREY = '#7f7f7f'; + + /** orange - hex #ff7f0e */ + public static readonly ORANGE = '#ff7f0e'; + + /** pink - hex #e377c2 */ + public static readonly PINK = '#e377c2'; + + /** purple - hex #9467bd */ + public static readonly PURPLE = '#9467bd'; + + /** red - hex #d62728 */ + public static readonly RED = '#d62728'; +} + function mapAnnotation(yAxis: string): ((x: HorizontalAnnotation) => any) { return (a: HorizontalAnnotation) => { return { ...a, yAxis }; diff --git a/packages/@aws-cdk/aws-cloudwatch/lib/metric-types.ts b/packages/@aws-cdk/aws-cloudwatch/lib/metric-types.ts index 424d7160045f4..5b54438975cd9 100644 --- a/packages/@aws-cdk/aws-cloudwatch/lib/metric-types.ts +++ b/packages/@aws-cdk/aws-cloudwatch/lib/metric-types.ts @@ -312,7 +312,8 @@ export interface MetricRenderingProperties { readonly label?: string; /** - * Color for the graph line + * The hex color code, prefixed with '#' (e.g. '#00ff00'), to use when this metric is rendered on a graph. + * The `Color` class has a set of standard colors that can be used here. */ readonly color?: string; diff --git a/packages/@aws-cdk/aws-cloudwatch/lib/metric.ts b/packages/@aws-cdk/aws-cloudwatch/lib/metric.ts index 6c08c4b227f2f..ab12e2df4ee07 100644 --- a/packages/@aws-cdk/aws-cloudwatch/lib/metric.ts +++ b/packages/@aws-cdk/aws-cloudwatch/lib/metric.ts @@ -53,31 +53,34 @@ export interface CommonMetricOptions { * * CloudWatch does not honor this property for graphs. * - * @default All metric datums in the given metric stream + * @default - All metric datums in the given metric stream */ readonly unit?: Unit; /** * Label for this metric when added to a Graph in a Dashboard + * @default - No label */ readonly label?: string; /** - * Color for this metric when added to a Graph in a Dashboard + * The hex color code, prefixed with '#' (e.g. '#00ff00'), to use when this metric is rendered on a graph. + * The `Color` class has a set of standard colors that can be used here. + * @default - Automatic color */ readonly color?: string; /** * Account which this metric comes from. * - * @default Deployment account. + * @default - Deployment account. */ readonly account?: string; /** * Region which this metric comes from. * - * @default Deployment region. + * @default - Deployment region. */ readonly region?: string; } @@ -178,33 +181,28 @@ export class Metric implements IMetric { }); } + /** Dimensions of this metric */ public readonly dimensions?: DimensionHash; + /** Namespace of this metric */ public readonly namespace: string; + /** Name of this metric */ public readonly metricName: string; + /** Period of this metric */ public readonly period: cdk.Duration; + /** Statistic of this metric */ public readonly statistic: string; + /** Label for this metric when added to a Graph in a Dashboard */ public readonly label?: string; + /** The hex color code used when this metric is rendered on a graph. */ public readonly color?: string; - /** - * Unit of the metric. - * - * @default None - */ + /** Unit of the metric. */ public readonly unit?: Unit; - /** - * Account which this metric comes from. - * - * @default Deployment account. - */ + /** Account which this metric comes from */ public readonly account?: string; - /** - * Region which this metric comes from. - * - * @default Deployment region. - */ + /** Region which this metric comes from. */ public readonly region?: string; constructor(props: MetricProps) { @@ -227,7 +225,7 @@ export class Metric implements IMetric { } /** - * Return a copy of Metric with properties changed. + * Return a copy of Metric `with` properties changed. * * All properties except namespace and metricName can be changed. * @@ -427,7 +425,8 @@ export class MathExpression implements IMetric { public readonly label?: string; /** - * Color for this metric when added to a Graph. + * The hex color code, prefixed with '#' (e.g. '#00ff00'), to use when this metric is rendered on a graph. + * The `Color` class has a set of standard colors that can be used here. */ public readonly color?: string; diff --git a/packages/@aws-cdk/aws-cloudwatch/package.json b/packages/@aws-cdk/aws-cloudwatch/package.json index a9a062604d12c..5a61ee84b5288 100644 --- a/packages/@aws-cdk/aws-cloudwatch/package.json +++ b/packages/@aws-cdk/aws-cloudwatch/package.json @@ -91,18 +91,7 @@ "docs-public-apis:@aws-cdk/aws-cloudwatch.Unit.COUNT_PER_SECOND", "docs-public-apis:@aws-cdk/aws-cloudwatch.Unit.TERABITS_PER_SECOND", "docs-public-apis:@aws-cdk/aws-cloudwatch.Alarm.fromAlarmArn", - "docs-public-apis:@aws-cdk/aws-cloudwatch.Metric.metricName", - "docs-public-apis:@aws-cdk/aws-cloudwatch.Metric.namespace", - "docs-public-apis:@aws-cdk/aws-cloudwatch.Metric.period", - "docs-public-apis:@aws-cdk/aws-cloudwatch.Metric.statistic", - "docs-public-apis:@aws-cdk/aws-cloudwatch.Metric.color", - "docs-public-apis:@aws-cdk/aws-cloudwatch.Metric.dimensions", - "docs-public-apis:@aws-cdk/aws-cloudwatch.Metric.label", - "docs-public-apis:@aws-cdk/aws-cloudwatch.Metric.unit", "props-default-doc:@aws-cdk/aws-cloudwatch.AlarmWidgetProps.leftYAxis", - "props-default-doc:@aws-cdk/aws-cloudwatch.CommonMetricOptions.color", - "props-default-doc:@aws-cdk/aws-cloudwatch.CommonMetricOptions.label", - "props-default-doc:@aws-cdk/aws-cloudwatch.CommonMetricOptions.unit", "docs-public-apis:@aws-cdk/aws-cloudwatch.DashboardProps", "props-default-doc:@aws-cdk/aws-cloudwatch.GraphWidgetProps.left", "props-default-doc:@aws-cdk/aws-cloudwatch.GraphWidgetProps.leftAnnotations", diff --git a/packages/@aws-cdk/aws-cloudwatch/test/test.graphs.ts b/packages/@aws-cdk/aws-cloudwatch/test/test.graphs.ts index 24ceb4ae0801a..ccbc6da6e647a 100644 --- a/packages/@aws-cdk/aws-cloudwatch/test/test.graphs.ts +++ b/packages/@aws-cdk/aws-cloudwatch/test/test.graphs.ts @@ -1,6 +1,6 @@ import { Stack } from '@aws-cdk/core'; import { Test } from 'nodeunit'; -import { Alarm, AlarmWidget, GraphWidget, Metric, Shading, SingleValueWidget } from '../lib'; +import { Alarm, AlarmWidget, Color, GraphWidget, Metric, Shading, SingleValueWidget } from '../lib'; export = { 'add stacked property to graphs'(test: Test) { @@ -343,4 +343,24 @@ export = { test.done(); }, -}; + + 'GraphColor is correctly converted into the correct hexcode'(test: Test) { + // GIVEN + const stack = new Stack(); + const metric = new Metric({ namespace: 'CDK', metricName: 'Test' }); + + // WHEN + const widget = new GraphWidget({ + left: [metric.with({ + color: Color.BLUE, + })], + leftAnnotations: [ + { color: Color.RED, value: 100, }, + ] + }); + + test.deepEqual(stack.resolve(widget.toJson())[0].properties.metrics[0], [ 'CDK', 'Test', { color: '#1f77b4' } ]); + test.deepEqual(stack.resolve(widget.toJson())[0].properties.annotations.horizontal[0], { yAxis: 'left', value: 100, color: '#d62728' }); + test.done(); + }, +}; \ No newline at end of file