chore: use "canned metrics" obtained from CloudWatch Explorer (#11717)

CloudWatch Explorer is a new service who have been collecting a
set of metrics emitted by various services.

Integrate this model and use to generate convenience methods that are
aware of per-metric dimensions and suggested default statistics.

We switch over to these metrics to a get second source of
confirmation that we have the dimensions correct.

We can't do complete code generation off of this model yet. Adds a README document that explains
why.


----

*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-apigateway/lib/restapi.ts

@@ -5,6 +5,7 @@ import { CfnOutput, IResource as IResourceBase, Resource, Stack } from '@aws-cdk
 import { Construct } from 'constructs';
 import { ApiDefinition } from './api-definition';
 import { ApiKey, ApiKeyOptions, IApiKey } from './api-key';
+import { ApiGatewayMetrics } from './apigateway-canned-metrics.generated';
 import { CfnAccount, CfnRestApi } from './apigateway.generated';
 import { CorsOptions } from './cors';
 import { Deployment } from './deployment';
@@ -397,74 +398,77 @@ export abstract class RestApiBase extends Resource implements IRestApi {
       metricName,
       dimensions: { ApiName: this.restApiName },
       ...props,
-    });
+    }).attachTo(this);
   }
 
   /**
    * Metric for the number of client-side errors captured in a given period.
    *
-   * @default - sum over 5 minutes
+   * Default: sum over 5 minutes
    */
   public metricClientError(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
-    return this.metric('4XXError', { statistic: 'Sum', ...props });
+    return this.cannedMetric(ApiGatewayMetrics._4XxErrorSum, props);
   }
 
   /**
    * Metric for the number of server-side errors captured in a given period.
    *
-   * @default - sum over 5 minutes
+   * Default: sum over 5 minutes
    */
   public metricServerError(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
-    return this.metric('5XXError', { statistic: 'Sum', ...props });
+    return this.cannedMetric(ApiGatewayMetrics._5XxErrorSum, props);
   }
 
   /**
    * Metric for the number of requests served from the API cache in a given period.
    *
-   * @default - sum over 5 minutes
+   * Default: sum over 5 minutes
    */
   public metricCacheHitCount(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
-    return this.metric('CacheHitCount', { statistic: 'Sum', ...props });
+    return this.cannedMetric(ApiGatewayMetrics.cacheHitCountSum, props);
   }
 
   /**
    * Metric for the number of requests served from the backend in a given period,
    * when API caching is enabled.
    *
-   * @default - sum over 5 minutes
+   * Default: sum over 5 minutes
    */
   public metricCacheMissCount(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
-    return this.metric('CacheMissCount', { statistic: 'Sum', ...props });
+    return this.cannedMetric(ApiGatewayMetrics.cacheMissCountSum, props);
   }
 
   /**
    * Metric for the total number API requests in a given period.
    *
-   * @default - SampleCount over 5 minutes
+   * Default: samplecount over 5 minutes
    */
   public metricCount(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
-    return this.metric('Count', { statistic: 'SampleCount', ...props });
+    return this.cannedMetric(ApiGatewayMetrics.countSum, {
+      statistic: 'SampleCount',
+      ...props,
+    });
   }
 
   /**
    * Metric for the time between when API Gateway relays a request to the backend
    * and when it receives a response from the backend.
    *
-   * @default - no statistic
+   * Default: average over 5 minutes.
    */
   public metricIntegrationLatency(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
-    return this.metric('IntegrationLatency', props);
+    return this.cannedMetric(ApiGatewayMetrics.integrationLatencyAverage, props);
   }
 
   /**
    * The time between when API Gateway receives a request from a client
    * and when it returns a response to the client.
    * The latency includes the integration latency and other API Gateway overhead.
    *
-   * @default - no statistic
+   * Default: average over 5 minutes.
    */
   public metricLatency(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
-    return this.metric('Latency', props);
+    return this.cannedMetric(ApiGatewayMetrics.latencyAverage, props);
   }
 
   /**
@@ -544,6 +548,13 @@ export abstract class RestApiBase extends Resource implements IRestApi {
     }
     return undefined;
   }
+
+  private cannedMetric(fn: (dims: { ApiName: string }) => cloudwatch.MetricProps, props?: cloudwatch.MetricOptions) {
+    return new cloudwatch.Metric({
+      ...fn({ ApiName: this.restApiName }),
+      ...props,
+    }).attachTo(this);
+  }
 }
 
 /**

packages/@aws-cdk/aws-apigatewayv2/lib/http/api.ts

@@ -1,4 +1,4 @@
-import { Metric, MetricOptions } from '@aws-cdk/aws-cloudwatch';
+import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
 import { Duration, IResource, Resource } from '@aws-cdk/core';
 import { Construct } from 'constructs';
 import { CfnApi, CfnApiProps } from '../apigatewayv2.generated';
@@ -28,43 +28,43 @@ export interface IHttpApi extends IResource {
    *
    * @default - average over 5 minutes
    */
-  metric(metricName: string, props?: MetricOptions): Metric;
+  metric(metricName: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric;
 
   /**
    * Metric for the number of client-side errors captured in a given period.
    *
    * @default - sum over 5 minutes
    */
-  metricClientError(props?: MetricOptions): Metric;
+  metricClientError(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
 
   /**
    * Metric for the number of server-side errors captured in a given period.
    *
    * @default - sum over 5 minutes
    */
-  metricServerError(props?: MetricOptions): Metric;
+  metricServerError(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
 
   /**
    * Metric for the amount of data processed in bytes.
    *
    * @default - sum over 5 minutes
    */
-  metricDataProcessed(props?: MetricOptions): Metric;
+  metricDataProcessed(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
 
   /**
    * Metric for the total number API requests in a given period.
    *
    * @default - SampleCount over 5 minutes
    */
-  metricCount(props?: MetricOptions): Metric;
+  metricCount(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
 
   /**
    * Metric for the time between when API Gateway relays a request to the backend
    * and when it receives a response from the backend.
    *
    * @default - no statistic
    */
-  metricIntegrationLatency(props?: MetricOptions): Metric;
+  metricIntegrationLatency(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
 
   /**
    * The time between when API Gateway receives a request from a client
@@ -73,7 +73,7 @@ export interface IHttpApi extends IResource {
    *
    * @default - no statistic
    */
-  metricLatency(props?: MetricOptions): Metric;
+  metricLatency(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
 
   /**
    * Add a new VpcLink
@@ -186,36 +186,36 @@ abstract class HttpApiBase extends Resource implements IHttpApi { // note that t
   public abstract readonly httpApiId: string;
   private vpcLinks: Record<string, VpcLink> = {};
 
-  public metric(metricName: string, props?: MetricOptions): Metric {
-    return new Metric({
+  public metric(metricName: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
+    return new cloudwatch.Metric({
       namespace: 'AWS/ApiGateway',
       metricName,
       dimensions: { ApiId: this.httpApiId },
       ...props,
     }).attachTo(this);
   }
 
-  public metricClientError(props?: MetricOptions): Metric {
+  public metricClientError(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
     return this.metric('4XXError', { statistic: 'Sum', ...props });
   }
 
-  public metricServerError(props?: MetricOptions): Metric {
+  public metricServerError(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
     return this.metric('5XXError', { statistic: 'Sum', ...props });
   }
 
-  public metricDataProcessed(props?: MetricOptions): Metric {
+  public metricDataProcessed(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
     return this.metric('DataProcessed', { statistic: 'Sum', ...props });
   }
 
-  public metricCount(props?: MetricOptions): Metric {
+  public metricCount(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
     return this.metric('Count', { statistic: 'SampleCount', ...props });
   }
 
-  public metricIntegrationLatency(props?: MetricOptions): Metric {
+  public metricIntegrationLatency(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
     return this.metric('IntegrationLatency', props);
   }
 
-  public metricLatency(props?: MetricOptions): Metric {
+  public metricLatency(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
     return this.metric('Latency', props);
   }
 

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

@@ -1,5 +1,6 @@
 import * as iam from '@aws-cdk/aws-iam';
 import * as cdk from '@aws-cdk/core';
+import * as constructs from 'constructs';
 import { Alarm, ComparisonOperator, TreatMissingData } from './alarm';
 import { Dimension, IMetric, MetricAlarmConfig, MetricConfig, MetricGraphConfig, Unit } from './metric-types';
 import { dispatchMetric, metricKey } from './private/metric-util';
@@ -272,7 +273,7 @@ export class Metric implements IMetric {
    * If the scope we attach to is in an environment-agnostic stack,
    * nothing is done and the same Metric object is returned.
    */
-  public attachTo(scope: cdk.Construct): Metric {
+  public attachTo(scope: constructs.IConstruct): Metric {
     const stack = cdk.Stack.of(scope);
 
     return this.with({

packages/@aws-cdk/aws-codebuild/lib/project.ts

@@ -12,6 +12,7 @@ import { Construct } from 'constructs';
 import { IArtifacts } from './artifacts';
 import { BuildSpec } from './build-spec';
 import { Cache } from './cache';
+import { CodeBuildMetrics } from './codebuild-canned-metrics.generated';
 import { CfnProject } from './codebuild.generated';
 import { CodePipelineArtifacts } from './codepipeline-artifacts';
 import { IFileSystemLocation } from './file-location';
@@ -340,11 +341,8 @@ abstract class ProjectBase extends Resource implements IProject {
    *
    * @default sum over 5 minutes
    */
-  public metricBuilds(props?: cloudwatch.MetricOptions) {
-    return this.metric('Builds', {
-      statistic: 'sum',
-      ...props,
-    });
+  public metricBuilds(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
+    return this.cannedMetric(CodeBuildMetrics.buildsSum, props);
   }
 
   /**
@@ -356,11 +354,8 @@ abstract class ProjectBase extends Resource implements IProject {
    *
    * @default average over 5 minutes
    */
-  public metricDuration(props?: cloudwatch.MetricOptions) {
-    return this.metric('Duration', {
-      statistic: 'avg',
-      ...props,
-    });
+  public metricDuration(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
+    return this.cannedMetric(CodeBuildMetrics.durationAverage, props);
   }
 
   /**
@@ -372,11 +367,8 @@ abstract class ProjectBase extends Resource implements IProject {
    *
    * @default sum over 5 minutes
    */
-  public metricSucceededBuilds(props?: cloudwatch.MetricOptions) {
-    return this.metric('SucceededBuilds', {
-      statistic: 'sum',
-      ...props,
-    });
+  public metricSucceededBuilds(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
+    return this.cannedMetric(CodeBuildMetrics.succeededBuildsSum, props);
   }
 
   /**
@@ -389,11 +381,17 @@ abstract class ProjectBase extends Resource implements IProject {
    *
    * @default sum over 5 minutes
    */
-  public metricFailedBuilds(props?: cloudwatch.MetricOptions) {
-    return this.metric('FailedBuilds', {
-      statistic: 'sum',
+  public metricFailedBuilds(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
+    return this.cannedMetric(CodeBuildMetrics.failedBuildsSum, props);
+  }
+
+  private cannedMetric(
+    fn: (dims: { ProjectName: string }) => cloudwatch.MetricProps,
+    props?: cloudwatch.MetricOptions): cloudwatch.Metric {
+    return new cloudwatch.Metric({
+      ...fn({ ProjectName: this.projectName }),
       ...props,
-    });
+    }).attachTo(this);
   }
 }