feat(cloudwatch): support for metric math

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

@@ -4,6 +4,7 @@ import { CfnAlarm } from './cloudwatch.generated';
 import { HorizontalAnnotation } from './graph';
 import { CreateAlarmOptions } from './metric';
 import { IMetric } from './metric-types';
+import { MetricSet } from './metric-util';
 import { parseStatistic } from './util.statistic';
 
 export interface IAlarm extends IResource {
@@ -121,8 +122,6 @@ export class Alarm extends Resource implements IAlarm {
 
     const comparisonOperator = props.comparisonOperator || ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD;
 
-    const config = props.metric.toAlarmConfig();
-
     const alarm = new CfnAlarm(this, 'Resource', {
       // Meta
       alarmDescription: props.alarmDescription,
@@ -143,7 +142,7 @@ export class Alarm extends Resource implements IAlarm {
       okActions: Lazy.listValue({ produce: () => this.okActionArns }),
 
       // Metric
-      ...dropUndef(config),
+      ...renderAlarmMetric(props.metric),
       ...dropUndef({
         // Alarm overrides
         period: props.period && props.period.toSeconds(),
@@ -228,6 +227,56 @@ export class Alarm extends Resource implements IAlarm {
   }
 }
 
+function renderAlarmMetric(metric: IMetric) {
+  const config = metric.toMetricConfig();
+
+  if (config.metricStat) {
+    const st = config.metricStat;
+    return dropUndef({
+      dimensions: st.dimensions,
+      namespace: st.namespace,
+      metricName: st.metricName,
+      period: st.period,
+      statistic: renderIfSimpleStatistic(st.statistic),
+      extendedStatistic: renderIfExtendedStatistic(st.statistic),
+    });
+  } else if (config.mathExpression) {
+    // Expand the math expression metric into a set
+    const mset = new MetricSet<boolean>();
+    mset.addPrimary(true, metric);
+
+    let mid = 0;
+    function uniqueMetricId() {
+      return `mid${++mid}`;
+    }
+
+    return {
+      metrics: mset.entries.map(entry => {
+        const conf = entry.metric.toMetricConfig();
+
+        return dropUndef({
+          expression: conf.mathExpression?.expression,
+          metricStat: conf.metricStat ? {
+            metric: {
+              metricName: conf.metricStat.metricName,
+              namespace: conf.metricStat.namespace,
+              dimensions: conf.metricStat.dimensions,
+            },
+            period: conf.metricStat.period,
+            stat: conf.metricStat.statistic,
+            // unit: not used, on purpose. Does not do what we need it to do.
+          } : undefined,
+          id: entry.id || uniqueMetricId(),
+          label: conf.renderingProperties?.label,
+          returnData: entry.tag ? undefined : false, // Tag stores "primary" attribute, default is "true"
+        } as CfnAlarm.MetricDataQueryProperty);
+      })
+    };
+  } else {
+    throw new Error(`Metric object must have either 'metricStat' or 'mathExpression'`);
+  }
+}
+
 /**
  * Return a human readable string for this period
  *

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

@@ -1,6 +1,7 @@
 import * as cdk from '@aws-cdk/core';
 import { IAlarm } from "./alarm";
 import { IMetric } from "./metric-types";
+import { allMetricsGraphJson } from './metric-util';
 import { ConcreteWidget } from "./widget";
 
 /**
@@ -169,8 +170,7 @@ export class GraphWidget extends ConcreteWidget {
   public toJson(): any[] {
     const horizontalAnnoations =  (this.props.leftAnnotations || []).map(mapAnnotation('left')).concat(
       (this.props.rightAnnotations || []).map(mapAnnotation('right')));
-    const metrics = (this.props.left || []).map(m => metricJson(m, 'left')).concat(
-      (this.props.right || []).map(m => metricJson(m, 'right')));
+    const metrics = allMetricsGraphJson(this.props.left || [], this.props.right || []);
     return [{
       type: 'metric',
       width: this.width,
@@ -232,7 +232,7 @@ export class SingleValueWidget extends ConcreteWidget {
         view: 'singleValue',
         title: this.props.title,
         region: this.props.region || cdk.Aws.REGION,
-        metrics: this.props.metrics.map(m => metricJson(m, 'left')),
+        metrics: allMetricsGraphJson(this.props.metrics, []),
         setPeriodToTimeRange: this.props.setPeriodToTimeRange
       }
     }];
@@ -298,29 +298,4 @@ function mapAnnotation(yAxis: string): ((x: HorizontalAnnotation) => any) {
   return (a: HorizontalAnnotation) => {
     return { ...a, yAxis };
   };
-}
-
-/**
- * Return the JSON structure which represents this metric in a graph
- *
- * This will be called by GraphWidget, no need for clients to call this.
- */
-function metricJson(metric: IMetric, yAxis: string): any[] {
-  const config = metric.toGraphConfig();
-
-  // Namespace and metric Name
-  const ret: any[] = [
-    config.namespace,
-    config.metricName,
-  ];
-
-  // Dimensions
-  for (const dim of (config.dimensions || [])) {
-    ret.push(dim.name, dim.value);
-  }
-
-  // Options
-  ret.push({ yAxis, ...config.renderingProperties });
-
-  return ret;
-}
+}

packages/@aws-cdk/aws-cloudwatch/lib/metric-types.ts

@@ -1,21 +1,30 @@
-
 /**
  * Interface for metrics
  */
 export interface IMetric {
+  /**
+   * Inspect the details of the metric object
+   */
+  toMetricConfig(): MetricConfig;
+
   /**
    * Turn this metric object into an alarm configuration
+   *
+   * @deprecated Use `toMetricsConfig()` instead.
    */
   toAlarmConfig(): MetricAlarmConfig;
 
   /**
    * Turn this metric object into a graph configuration
+   *
+   * @deprecated Use `toMetricsConfig()` instead.
    */
   toGraphConfig(): MetricGraphConfig;
 }
 
 /**
  * Metric dimension
+ *
  */
 export interface Dimension {
   /**
@@ -33,48 +42,131 @@ export interface Dimension {
  * Statistic to use over the aggregation period
  */
 export enum Statistic {
-  SAMPLE_COUNT = 'SampleCount',
-  AVERAGE = 'Average',
-  SUM = 'Sum',
-  MINIMUM = 'Minimum',
-  MAXIMUM = 'Maximum',
+  SAMPLE_COUNT = "SampleCount",
+  AVERAGE = "Average",
+  SUM = "Sum",
+  MINIMUM = "Minimum",
+  MAXIMUM = "Maximum"
 }
 
 /**
  * Unit for metric
  */
 export enum Unit {
-  SECONDS = 'Seconds',
-  MICROSECONDS = 'Microseconds',
-  MILLISECONDS = 'Milliseconds',
-  BYTES = 'Bytes',
-  KILOBYTES = 'Kilobytes',
-  MEGABYTES = 'Megabytes',
-  GIGABYTES = 'Gigabytes',
-  TERABYTES = 'Terabytes',
-  BITS = 'Bits',
-  KILOBITS = 'Kilobits',
-  MEGABITS = 'Megabits',
-  GIGABITS = 'Gigabits',
-  TERABITS = 'Terabits',
-  PERCENT = 'Percent',
-  COUNT = 'Count',
-  BYTES_PER_SECOND = 'Bytes/Second',
-  KILOBYTES_PER_SECOND = 'Kilobytes/Second',
-  MEGABYTES_PER_SECOND = 'Megabytes/Second',
-  GIGABYTES_PER_SECOND = 'Gigabytes/Second',
-  TERABYTES_PER_SECOND = 'Terabytes/Second',
-  BITS_PER_SECOND = 'Bits/Second',
-  KILOBITS_PER_SECOND = 'Kilobits/Second',
-  MEGABITS_PER_SECOND = 'Megabits/Second',
-  GIGABITS_PER_SECOND = 'Gigabits/Second',
-  TERABITS_PER_SECOND = 'Terabits/Second',
-  COUNT_PER_SECOND = 'Count/Second',
-  NONE = 'None'
+  SECONDS = "Seconds",
+  MICROSECONDS = "Microseconds",
+  MILLISECONDS = "Milliseconds",
+  BYTES = "Bytes",
+  KILOBYTES = "Kilobytes",
+  MEGABYTES = "Megabytes",
+  GIGABYTES = "Gigabytes",
+  TERABYTES = "Terabytes",
+  BITS = "Bits",
+  KILOBITS = "Kilobits",
+  MEGABITS = "Megabits",
+  GIGABITS = "Gigabits",
+  TERABITS = "Terabits",
+  PERCENT = "Percent",
+  COUNT = "Count",
+  BYTES_PER_SECOND = "Bytes/Second",
+  KILOBYTES_PER_SECOND = "Kilobytes/Second",
+  MEGABYTES_PER_SECOND = "Megabytes/Second",
+  GIGABYTES_PER_SECOND = "Gigabytes/Second",
+  TERABYTES_PER_SECOND = "Terabytes/Second",
+  BITS_PER_SECOND = "Bits/Second",
+  KILOBITS_PER_SECOND = "Kilobits/Second",
+  MEGABITS_PER_SECOND = "Megabits/Second",
+  GIGABITS_PER_SECOND = "Gigabits/Second",
+  TERABITS_PER_SECOND = "Terabits/Second",
+  COUNT_PER_SECOND = "Count/Second",
+  NONE = "None"
+}
+
+/**
+ * Properties of a rendered metric
+ */
+export interface MetricConfig {
+  /**
+   * In case the metric represents a query, the details of the query
+   */
+  readonly metricStat?: MetricStatConfig;
+
+  /**
+   * In case the metric is a math expression, the details of the math expression
+   */
+  readonly mathExpression?: MetricExpressionConfig;
+
+  /**
+   * Additional properties which will be rendered if the metric is used in a dashboard
+   *
+   * Examples are 'label' and 'color', but any key in here will be
+   * added to dashboard graphs.
+   */
+  readonly renderingProperties?: Record<string, any>;
+}
+
+/**
+ * Properties for a concrete metric
+ *
+ * NOTE: `unit` is no longer on this object since it is only used for `Alarms`, and doesn't mean what one
+ * would expect it to mean there anyway. It is most likely to be misused.
+ */
+export interface MetricStatConfig {
+  /**
+   * The dimensions to apply to the alarm
+   */
+  readonly dimensions?: Dimension[];
+
+  /**
+   * Namespace of the metric
+   */
+  readonly namespace: string;
+
+  /**
+   * Name of the metric
+   */
+  readonly metricName: string;
+
+  /**
+   * How many seconds to aggregate over
+   */
+  readonly period: number;
+
+  /**
+   * Aggregation function to use (can be either simple or a percentile)
+   */
+  readonly statistic: string;
+
+  /**
+   * Region of the metric
+   */
+  readonly region?: string;
+
+  /**
+   * Account of the metric
+   */
+  readonly account?: string;
+}
+
+/**
+ * Properties for a concrete metric
+ */
+export interface MetricExpressionConfig {
+  /**
+   * Math expression for the metric.
+   */
+  readonly expression: string;
+
+  /**
+   * Metrics used in the math expression
+   */
+  readonly expressionMetrics: Record<string, IMetric>;
 }
 
 /**
  * Properties used to construct the Metric identifying part of an Alarm
+ *
+ * @deprecated Replaced by MetricConfig
  */
 export interface MetricAlarmConfig {
   /**
@@ -115,6 +207,8 @@ export interface MetricAlarmConfig {
 
 /**
  * Properties used to construct the Metric identifying part of a Graph
+ *  *
+ * @deprecated Replaced by MetricConfig
  */
 export interface MetricGraphConfig {
   /**
@@ -175,6 +269,8 @@ export interface MetricGraphConfig {
 
 /**
  * Custom rendering properties that override the default rendering properties specified in the yAxis parameter of the widget object.
+ *
+ * @deprecated Replaced by `MetricConfig`.
  */
 export interface MetricRenderingProperties {
   /**