feat(cloudwatch): trimmed mean stat in graph widgets (#15316)

Cloudwatch supports trimmed mean as a statistic in graph widgets.

Trimmed mean: https://en.wikipedia.org/wiki/Truncated_mean

Graph widgets can now take `tmNN.NN` to represent various
trimmed mean statistical ranges (similar to the existing percentile
ranges `pNN.NN`).

For instance, `tm90` represents the mean (or average) of all data
points after trimming out data points of the last 10 percentiles.

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

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

@@ -393,6 +393,9 @@ function renderIfExtendedStatistic(statistic?: string): string | undefined {
     // floating point rounding issues, return as-is but lowercase the p.
     return statistic.toLowerCase();
   }
+  if (parsed.type === 'trimmedMean') {
+    throw new Error('tmNN.NN stat is not supported in CloudWatch alarms');
+  }
   return undefined;
 }
 

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

@@ -36,6 +36,7 @@ export interface CommonMetricOptions {
    * - "Sum" | "sum"
    * - "SampleCount | "n"
    * - "pNN.NN"
+   * - "tmNN.NN"
    *
    * @default Average
    */

packages/@aws-cdk/aws-cloudwatch/lib/private/statistic.ts

@@ -9,10 +9,16 @@ export interface PercentileStatistic {
   type: 'percentile';
   percentile: number;
 }
+
+export interface TrimmedMeanStatistic {
+  type: 'trimmedMean';
+  trimmedMean: number;
+}
+
 /**
  * Parse a statistic, returning the type of metric that was used (simple or percentile)
  */
-export function parseStatistic(stat: string): SimpleStatistic | PercentileStatistic {
+export function parseStatistic(stat: string): SimpleStatistic | PercentileStatistic | TrimmedMeanStatistic {
   const lowerStat = stat.toLowerCase();
 
   // Simple statistics
@@ -35,17 +41,24 @@ export function parseStatistic(stat: string): SimpleStatistic | PercentileStatis
     };
   }
 
-  // Percentile statistics
-  const re = /^p([\d.]+)$/;
+  // Percentile or Trimmed Mean statistics
+  const re = /^(p|tm)([\d.]+)$/;
   const m = re.exec(lowerStat);
-  if (m) {
+  if (m && m[1] === 'p') {
     return {
       type: 'percentile',
-      percentile: parseFloat(m[1]),
+      percentile: parseFloat(m[2]),
+    };
+  }
+  if (m && m[1] === 'tm') {
+    return {
+      type: 'trimmedMean',
+      trimmedMean: parseFloat(m[2]),
     };
   }
 
-  throw new Error(`Not a valid statistic: '${stat}', must be one of Average | Minimum | Maximum | SampleCount | Sum | pNN.NN`);
+  const supportedStats = ['Average', 'Minimum', 'Maximum', 'SampleCount', 'Sum', 'pNN.NN', 'tmNN.NN'];
+  throw new Error(`Not a valid statistic: '${stat}', must be one of ${supportedStats.join(' | ')}`);
 }
 
 export function normalizeStatistic(stat: string): string {

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

@@ -161,6 +161,19 @@ export = {
     test.done();
   },
 
+  'trimmedMean not supported'(test: Test) {
+    const stack = new Stack();
+
+    test.throws(() => new Alarm(stack, 'Alarm', {
+      metric: testMetric,
+      statistic: 'TM99',
+      threshold: 1000,
+      evaluationPeriods: 3,
+    }), /tmNN.NN stat is not supported/);
+
+    test.done();
+  },
+
   'can set DatapointsToAlarm'(test: Test) {
     // GIVEN
     const stack = new Stack();

packages/@aws-cdk/aws-cloudwatch/test/test.graphs.ts

@@ -717,4 +717,27 @@ export = {
 
     test.done();
   },
+
+  'trimmedMean stat is rendered'(test: Test) {
+    // GIVEN
+    const stack = new Stack();
+    const widget = new GraphWidget({
+      statistic: 'tm90',
+    });
+
+    // THEN
+    test.deepEqual(stack.resolve(widget.toJson()), [{
+      type: 'metric',
+      width: 6,
+      height: 6,
+      properties: {
+        view: 'timeSeries',
+        region: { Ref: 'AWS::Region' },
+        yAxis: {},
+        stat: 'tm90',
+      },
+    }]);
+
+    test.done();
+  },
 };