feat(cloudwatch): standard set of graph colors

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:

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 };

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;
 

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;
 

packages/@aws-cdk/aws-cloudwatch/package.json

@@ -89,18 +89,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",

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();
+  },
+};