feat(cloudwatch): parse all metrics statistics and support long format

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

@@ -166,6 +166,60 @@ below).
 > happen to know the Metric you want to alarm on makes sense as a rate
 > (`Average`) you can always choose to change the statistic.
 
+### Available Aggregation Statistics
+
+For your metrics aggregation, you can use the following statistics:
+
+| Statistic                |    Short format     |                 Long format                  | Factory name         |
+| ------------------------ | :-----------------: | :------------------------------------------: | -------------------- |
+| SampleCount (n)          |         ❌          |                      ❌                      | `Stats.SAMPLE_COUNT` |
+| Average (avg)            |         ❌          |                      ❌                      | `Stats.AVERAGE`      |
+| Sum                      |         ❌          |                      ❌                      | `Stats.SUM`          |
+| Minimum (min)            |         ❌          |                      ❌                      | `Stats.MINIMUM`      |
+| Maximum (max)            |         ❌          |                      ❌                      | `Stats.MAXIMUM`      |
+| Interquartile mean (IQM) |         ❌          |                      ❌                      | `Stats.IQM`          |
+| Percentile (p)           |        `p99`        |                      ❌                      | `Stats.p(99)`        |
+| Winsorized mean (WM)     | `wm99` = `WM(:99%)` | `WM(x:y) \| WM(x%:y%) \| WM(x%:) \| WM(:y%)` | `Stats.wm(10, 90)`   |
+| Trimmed count (TC)       | `tc99` = `TC(:99%)` | `TC(x:y) \| TC(x%:y%) \| TC(x%:) \| TC(:y%)` | `Stats.tc(10, 90)`   |
+| Trimmed sum (TS)         | `ts99` = `TS(:99%)` | `TS(x:y) \| TS(x%:y%) \| TS(x%:) \| TS(:y%)` | `Stats.ts(10, 90)`   |
+| Percentile rank (PR)     |         ❌          |        `PR(x:y) \| PR(x:) \| PR(:y)`         | `Stats.pr(10, 5000)` |
+
+The most common values are provided in the `cloudwatch.Stats` class. You can provide any string if your statistic is not in the class.
+
+Read more at [CloudWatch statistics definitions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Statistics-definitions.html).
+
+```ts
+new cloudwatch.Metric({
+  namespace: 'AWS/Route53',
+  metricName: 'DNSQueries',
+  dimensionsMap: {
+    HostedZoneId: hostedZone.hostedZoneId
+  },
+  statistic: cloudwatch.Stats.SAMPLE_COUNT,
+  period: cloudwatch.Duration.minutes(5)
+});
+
+new cloudwatch.Metric({
+  namespace: 'AWS/Route53',
+  metricName: 'DNSQueries',
+  dimensionsMap: {
+    HostedZoneId: hostedZone.hostedZoneId
+  },
+  statistic: cloudwatch.Stats.p(99),
+  period: cloudwatch.Duration.minutes(5)
+});
+
+new cloudwatch.Metric({
+  namespace: 'AWS/Route53',
+  metricName: 'DNSQueries',
+  dimensionsMap: {
+    HostedZoneId: hostedZone.hostedZoneId
+  },
+  statistic: 'TS(7.5%:90%)',
+  period: cloudwatch.Duration.minutes(5)
+});
+```
+
 ### Labels
 
 Metric labels are displayed in the legend of graphs that include the metrics.

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

@@ -9,7 +9,7 @@ import { IMetric, MetricExpressionConfig, MetricStatConfig } from './metric-type
 import { dispatchMetric, metricPeriod } from './private/metric-util';
 import { dropUndefined } from './private/object';
 import { MetricSet } from './private/rendering';
-import { parseStatistic } from './private/statistic';
+import { normalizeStatistic, parseStatistic } from './private/statistic';
 
 /**
  * Properties for Alarms
@@ -413,7 +413,7 @@ function renderIfSimpleStatistic(statistic?: string): string | undefined {
 
   const parsed = parseStatistic(statistic);
   if (parsed.type === 'simple') {
-    return parsed.statistic;
+    return normalizeStatistic(parsed);
   }
   return undefined;
 }
@@ -422,14 +422,9 @@ function renderIfExtendedStatistic(statistic?: string): string | undefined {
   if (statistic === undefined) { return undefined; }
 
   const parsed = parseStatistic(statistic);
-  if (parsed.type === 'percentile') {
-    // Already percentile. Avoid parsing because we might get into
-    // floating point rounding issues, return as-is but lowercase the p.
-    return statistic.toLowerCase();
-  } else if (parsed.type === 'generic') {
-    return statistic;
+  if (parsed.type === 'single' || parsed.type === 'pair') {
+    return normalizeStatistic(parsed);
   }
-
   return undefined;
 }
 

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

@@ -2,11 +2,12 @@ import * as iam from '@aws-cdk/aws-iam';
 import * as cdk from '@aws-cdk/core';
 import { Construct, IConstruct } from 'constructs';
 import { Alarm, ComparisonOperator, TreatMissingData } from './alarm';
-import { Dimension, IMetric, MetricAlarmConfig, MetricConfig, MetricGraphConfig, Unit } from './metric-types';
+import { Dimension, IMetric, MetricAlarmConfig, MetricConfig, MetricGraphConfig, Statistic, Unit } from './metric-types';
 import { dispatchMetric, metricKey } from './private/metric-util';
-import { normalizeStatistic, parseStatistic } from './private/statistic';
+import { normalizeStatistic, pairStatisticToString, parseStatistic, singleStatisticToString } from './private/statistic';
+import { Stats } from './stats';
 
-export type DimensionHash = {[dim: string]: any};
+export type DimensionHash = { [dim: string]: any };
 
 export type DimensionsMap = { [dim: string]: string };
 
@@ -24,6 +25,8 @@ export interface CommonMetricOptions {
   /**
    * What function to use for aggregating.
    *
+   * Use the `aws_cloudwatch.Stats` helper class to construct valid input strings.
+   *
    * Can be one of the following:
    *
    * - "Minimum" | "min"
@@ -38,8 +41,6 @@ export interface CommonMetricOptions {
    * - "tcNN.NN" | "tc(NN.NN%:NN.NN%)"
    * - "tsNN.NN" | "ts(NN.NN%:NN.NN%)"
    *
-   * Use the factory functions on the `Stats` object to construct valid input strings.
-   *
    * @default Average
    */
   readonly statistic?: string;
@@ -197,13 +198,13 @@ export interface MathExpressionOptions {
   readonly searchAccount?: string;
 
   /**
-    * Region to evaluate search expressions within.
-    *
-    * Specifying a searchRegion has no effect to the region used
-    * for metrics within the expression (passed via usingMetrics).
-    *
-    * @default - Deployment region.
-    */
+   * Region to evaluate search expressions within.
+   *
+   * Specifying a searchRegion has no effect to the region used
+   * for metrics within the expression (passed via usingMetrics).
+   *
+   * @default - Deployment region.
+   */
   readonly searchRegion?: string;
 }
 
@@ -291,17 +292,30 @@ export class Metric implements IMetric {
     if (periodSec !== 1 && periodSec !== 5 && periodSec !== 10 && periodSec !== 30 && periodSec % 60 !== 0) {
       throw new Error(`'period' must be 1, 5, 10, 30, or a multiple of 60 seconds, received ${periodSec}`);
     }
+
+    this.warnings = undefined;
     this.dimensions = this.validateDimensions(props.dimensionsMap ?? props.dimensions);
     this.namespace = props.namespace;
     this.metricName = props.metricName;
-    // Try parsing, this will throw if it's not a valid stat
-    this.statistic = normalizeStatistic(props.statistic || 'Average');
+
+    const parsedStat = parseStatistic(props.statistic || Stats.AVERAGE);
+    if (parsedStat.type === 'generic') {
+      // Unrecognized statistic, do not throw, just warn
+      // There may be a new statistic that this lib does not support yet
+      const label = props.label ? `, label "${props.label}"`: '';
+      this.warnings = [
+        `Unrecognized statistic "${props.statistic}" for metric with namespace "${props.namespace}"${label} and metric name "${props.metricName}".` +
+          ' Preferably use the `aws_cloudwatch.Stats` helper class to specify a statistic.' +
+          ' You can ignore this warning if your statistic is valid but not yet supported by the `aws_cloudwatch.Stats` helper class.',
+      ];
+    }
+    this.statistic = normalizeStatistic(parsedStat);
+
     this.label = props.label;
     this.color = props.color;
     this.unit = props.unit;
     this.account = props.account;
     this.region = props.region;
-    this.warnings = undefined;
   }
 
   /**
@@ -389,14 +403,22 @@ export class Metric implements IMetric {
       throw new Error('Using a math expression is not supported here. Pass a \'Metric\' object instead');
     }
 
-    const stat = parseStatistic(metricConfig.metricStat.statistic);
+    const parsed = parseStatistic(metricConfig.metricStat.statistic);
+
+    let extendedStatistic: string | undefined = undefined;
+    if (parsed.type === 'single') {
+      extendedStatistic = singleStatisticToString(parsed);
+    } else if (parsed.type === 'pair') {
+      extendedStatistic = pairStatisticToString(parsed);
+    }
+
     return {
       dimensions: metricConfig.metricStat.dimensions,
       namespace: metricConfig.metricStat.namespace,
       metricName: metricConfig.metricStat.metricName,
       period: metricConfig.metricStat.period.toSeconds(),
-      statistic: stat.type === 'simple' ? stat.statistic : undefined,
-      extendedStatistic: stat.type === 'percentile' ? 'p' + stat.percentile : undefined,
+      statistic: parsed.type === 'simple' ? parsed.statistic as Statistic : undefined,
+      extendedStatistic,
       unit: this.unit,
     };
   }