feat(apigatewayv2): http api - metric methods for api and stage

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

@@ -23,6 +23,7 @@
   - [Cross Origin Resource Sharing (CORS)](#cross-origin-resource-sharing-cors)
   - [Publishing HTTP APIs](#publishing-http-apis)
   - [Custom Domain](#custom-domain)
+  - [Metrics](#metrics)
 
 ## Introduction
 
@@ -198,3 +199,22 @@ with 3 API mapping resources across different APIs and Stages.
 | api | $default  |   `https://${domainName}/foo`  |
 | api | beta  |   `https://${domainName}/bar`  |
 | apiDemo | $default  |   `https://${domainName}/demo`  |
+
+## Metrics
+
+The API Gateway v2 service sends metrics around the performance of HTTP APIs to Amazon CloudWatch. These metrics can be referred to using the metric APIs available on the HttpApi construct. The APIs with the metric prefix can be used to get reference to specific metrics for this API. For example, the method below refers to the client side errors metric for this API.
+
+```
+const api = new apigw.HttpApi(stack, 'my-api');
+const clientErrorMetric = api.metricClientError();
+
+```
+Please note that this will return a metric for all the stages defined in the api. It is also possible to collect metrics only from a specic `stage` using the metric methods from the `stage`.
+
+```
+const api = new apigw.HttpApi(stack, 'my-api');
+const stage = new HttpStage(stack, 'Stage', {
+   httpApi: api,
+});
+const clientErrorMetric = stage.metricClientError();
+```

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

@@ -1,3 +1,4 @@
+import { Metric, MetricOptions } from '@aws-cdk/aws-cloudwatch';
 import { Duration, IResource, Resource } from '@aws-cdk/core';
 import { Construct } from 'constructs';
 import { CfnApi, CfnApiProps } from '../apigatewayv2.generated';
@@ -16,10 +17,67 @@ export interface IHttpApi extends IResource {
    */
   readonly httpApiId: string;
 
+  /**
+   * A human friendly name for this HTTP API. Note that this is different from `httpApiId`.
+   */
+  readonly httpApiName?: string;
+
   /**
    * The default stage
    */
   readonly defaultStage?: HttpStage;
+
+  /**
+   * Return the given named metric for this HTTP Api Gateway
+   *
+   * @default Average over 5 minutes
+   */
+  metric(metricName: string, props?: MetricOptions): Metric;
+
+  /**
+   * Metric for the number of client-side errors captured in a given period.
+   *
+   * @default - sum over 5 minutes
+   */
+  metricClientError(props?: MetricOptions): Metric;
+
+  /**
+   * Metric for the number of server-side errors captured in a given period.
+   *
+   * @default - sum over 5 minutes
+   */
+  metricServerError(props?: MetricOptions): Metric;
+
+  /**
+   * Metric for the amount of data processed in bytes.
+   *
+   * @default - sum over 5 minutes
+   */
+  metricDataProcessed(props?: MetricOptions): Metric;
+
+  /**
+   * Metric for the total number API requests in a given period.
+   *
+   * @default - SampleCount over 5 minutes
+   */
+  metricCount(props?: MetricOptions): 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;
+
+  /**
+   * 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
+   */
+  metricLatency(props?: MetricOptions): Metric;
 }
 
 /**
@@ -116,22 +174,11 @@ export interface AddRoutesOptions extends BatchHttpRouteOptions {
   readonly methods?: HttpMethod[];
 }
 
-/**
- * Create a new API Gateway HTTP API endpoint.
- * @resource AWS::ApiGatewayV2::Api
- */
-export class HttpApi extends Resource implements IHttpApi {
-  /**
-   * Import an existing HTTP API into this CDK app.
-   */
-  public static fromApiId(scope: Construct, id: string, httpApiId: string): IHttpApi {
-    class Import extends Resource implements IHttpApi {
-      public readonly httpApiId = httpApiId;
-    }
-    return new Import(scope, id);
-  }
+class HttpApiBase extends Resource implements IHttpApi { // note that this is not exported
 
   public readonly httpApiId: string;
+  public readonly httpApiName?: string;
+
   /**
    * default stage of the api resource
    */
@@ -140,7 +187,7 @@ export class HttpApi extends Resource implements IHttpApi {
   constructor(scope: Construct, id: string, props?: HttpApiProps) {
     super(scope, id);
 
-    const apiName = props?.apiName ?? id;
+    this.httpApiName = props?.apiName ?? id;
 
     let corsConfiguration: CfnApi.CorsProperty | undefined;
     if (props?.corsPreflight) {
@@ -167,7 +214,7 @@ export class HttpApi extends Resource implements IHttpApi {
     }
 
     const apiProps: CfnApiProps = {
-      name: apiName,
+      name: this.httpApiName,
       protocolType: 'HTTP',
       corsConfiguration,
     };
@@ -202,6 +249,55 @@ export class HttpApi extends Resource implements IHttpApi {
     }
   }
 
+  public metric(metricName: string, props?: MetricOptions): Metric {
+    return new Metric({
+      namespace: 'AWS/ApiGateway',
+      metricName,
+      dimensions: { ApiId: this.httpApiId },
+      ...props,
+    }).attachTo(this);
+  }
+
+  public metricClientError(props?: MetricOptions): Metric {
+    return this.metric('4XXError', { statistic: 'Sum', ...props });
+  }
+
+  public metricServerError(props?: MetricOptions): Metric {
+    return this.metric('5XXError', { statistic: 'Sum', ...props });
+  }
+
+  public metricDataProcessed(props?: MetricOptions): Metric {
+    return this.metric('DataProcessed', { statistic: 'Sum', ...props });
+  }
+
+  public metricCount(props?: MetricOptions): Metric {
+    return this.metric('Count', { statistic: 'SampleCount', ...props });
+  }
+
+  public metricIntegrationLatency(props?: MetricOptions): Metric {
+    return this.metric('IntegrationLatency', props);
+  }
+
+  public metricLatency(props?: MetricOptions): Metric {
+    return this.metric('Latency', props);
+  }
+}
+
+/**
+ * Create a new API Gateway HTTP API endpoint.
+ * @resource AWS::ApiGatewayV2::Api
+ */
+export class HttpApi extends HttpApiBase {
+  /**
+   * Import an existing HTTP API into this CDK app.
+   */
+  public static fromApiId(scope: Construct, id: string, httpApiId: string): IHttpApi {
+    class Import extends HttpApiBase {
+      public readonly httpApiId = httpApiId;
+    }
+    return new Import(scope, id);
+  }
+
   /**
    * Get the URL to the default stage of this API.
    * Returns `undefined` if `createDefaultStage` is unset.

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

@@ -1,10 +1,12 @@
+import { Metric, MetricOptions } from '@aws-cdk/aws-cloudwatch';
 import { Resource, Stack } from '@aws-cdk/core';
 import { Construct } from 'constructs';
 import { CfnStage } from '../apigatewayv2.generated';
 import { CommonStageOptions, IDomainName, IStage } from '../common';
 import { IHttpApi } from './api';
 import { HttpApiMapping } from './api-mapping';
 
+
 const DEFAULT_STAGE_NAME = '$default';
 
 /**
@@ -117,4 +119,73 @@ export class HttpStage extends Resource implements IStage {
     const urlPath = this.stageName === DEFAULT_STAGE_NAME ? '' : this.stageName;
     return `https://${this.httpApi.httpApiId}.execute-api.${s.region}.${s.urlSuffix}/${urlPath}`;
   }
+
+  /**
+   * Return the given named metric for this HTTP Api Gateway Stage
+   *
+   * @default Average over 5 minutes
+   */
+  public metric(metricName: string, props?: MetricOptions): Metric {
+    var api = this.httpApi;
+    return api.metric(metricName, props).with({
+      dimensions: { ApiId: this.httpApi.httpApiId, Stage: this.stageName },
+    }).attachTo(this);
+  }
+
+  /**
+   * Metric for the number of client-side errors captured in a given period.
+   *
+   * @default - sum over 5 minutes
+   */
+  public metricClientError(props?: MetricOptions): Metric {
+    return this.metric('4XXError', { statistic: 'Sum', ...props });
+  }
+
+  /**
+   * Metric for the number of server-side errors captured in a given period.
+   *
+   * @default - sum over 5 minutes
+   */
+  public metricServerError(props?: MetricOptions): Metric {
+    return this.metric('5XXError', { statistic: 'Sum', ...props });
+  }
+
+  /**
+   * Metric for the amount of data processed in bytes.
+   *
+   * @default - sum over 5 minutes
+   */
+  public metricDataProcessed(props?: MetricOptions): Metric {
+    return this.metric('DataProcessed', { statistic: 'Sum', ...props });
+  }
+
+  /**
+   * Metric for the total number API requests in a given period.
+   *
+   * @default - SampleCount over 5 minutes
+   */
+  public metricCount(props?: MetricOptions): Metric {
+    return this.metric('Count', { 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
+   */
+  public metricIntegrationLatency(props?: MetricOptions): Metric {
+    return this.metric('IntegrationLatency', 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
+   */
+  public metricLatency(props?: MetricOptions): Metric {
+    return this.metric('Latency', props);
+  }
 }

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

@@ -82,13 +82,15 @@
     "@aws-cdk/aws-certificatemanager": "0.0.0",
     "@aws-cdk/aws-iam": "0.0.0",
     "@aws-cdk/aws-lambda": "0.0.0",
+    "@aws-cdk/aws-cloudwatch": "0.0.0",
     "@aws-cdk/core": "0.0.0",
     "constructs": "^3.0.4"
   },
   "peerDependencies": {
     "@aws-cdk/aws-iam": "0.0.0",
     "@aws-cdk/aws-lambda": "0.0.0",
     "@aws-cdk/aws-certificatemanager": "0.0.0",
+    "@aws-cdk/aws-cloudwatch": "0.0.0",
     "@aws-cdk/core": "0.0.0",
     "constructs": "^3.0.4"
   },

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

@@ -1,5 +1,6 @@
 import '@aws-cdk/assert/jest';
 import { ABSENT } from '@aws-cdk/assert';
+import { Metric } from '@aws-cdk/aws-cloudwatch';
 import { Code, Function, Runtime } from '@aws-cdk/aws-lambda';
 import { Duration, Stack } from '@aws-cdk/core';
 import { HttpApi, HttpMethod, LambdaProxyIntegration } from '../../lib';
@@ -155,5 +156,50 @@ describe('HttpApi', () => {
         },
       })).toThrowError(/allowCredentials is not supported/);
     });
+
+    test('get metric', () => {
+      // GIVEN
+      const stack = new Stack();
+      const api = new HttpApi(stack, 'test-api', {
+        createDefaultStage: false,
+      });
+      const metricName = '4xxError';
+      const statistic = 'Sum';
+      const apiId = api.httpApiId;
+
+      // WHEN
+      const countMetric = api.metric(metricName, { statistic });
+
+      // THEN
+      expect(countMetric.namespace).toEqual('AWS/ApiGateway');
+      expect(countMetric.metricName).toEqual(metricName);
+      expect(countMetric.dimensions).toEqual({ ApiId: apiId });
+      expect(countMetric.statistic).toEqual(statistic);
+    });
+
+    test('Exercise metrics', () => {
+      // GIVEN
+      const stack = new Stack();
+      const api = new HttpApi(stack, 'test-api', {
+        createDefaultStage: false,
+      });
+      const color = '#00ff00';
+      const apiId = api.httpApiId;
+
+      // WHEN
+      const metrics = new Array<Metric>();
+      metrics.push(api.metricClientError({ color }));
+      metrics.push(api.metricServerError({ color }));
+      metrics.push(api.metricDataProcessed({ color }));
+      metrics.push(api.metricLatency({ color }));
+      metrics.push(api.metricIntegrationLatency({ color }));
+      metrics.push(api.metricCount({ color }));
+      // THEN
+      for (const metric of metrics) {
+        expect(metric.namespace).toEqual('AWS/ApiGateway');
+        expect(metric.dimensions).toEqual({ ApiId: apiId });
+        expect(metric.color).toEqual(color);
+      }
+    });
   });
 });