Skip to content

Commit 981d8fe

Browse files
mergify[bot]mergify[bot]
authored
Merge branch 'main' into main
2 parents d9912ff + 3bf1361 commit 981d8fe

30 files changed

Lines changed: 2078 additions & 17 deletions

‎packages/@aws-cdk/aws-apigateway/README.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1305,13 +1305,19 @@ in your openApi file.
13051305
## Metrics
13061306

13071307
The API Gateway service sends metrics around the performance of Rest APIs to Amazon CloudWatch.
1308-
These metrics can be referred to using the metric APIs available on the `RestApi` construct.
1309-
The APIs with the `metric` prefix can be used to get reference to specific metrics for this API. For example,
1310-
the method below refers to the client side errors metric for this API.
1308+
These metrics can be referred to using the metric APIs available on the `RestApi`, `Stage` and `Method` constructs.
1309+
Note that detailed metrics must be enabled for a stage to use the `Method` metrics.
1310+
Read more about [API Gateway metrics](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-metrics-and-dimensions.html), including enabling detailed metrics.
1311+
The APIs with the `metric` prefix can be used to get reference to specific metrics for this API. For example:
13111312

13121313
```ts
13131314
const api = new apigateway.RestApi(this, 'my-api');
1314-
const clientErrorMetric = api.metricClientError();
1315+
const stage = api.deploymentStage;
1316+
const method = api.root.addMethod('GET');
1317+
1318+
const clientErrorApiMetric = api.metricClientError();
1319+
const serverErrorStageMetric = stage.metricServerError();
1320+
const latencyMethodMetric = method.metricLatency(stage);
13151321
```
13161322

13171323
## APIGateway v2

‎packages/@aws-cdk/aws-apigateway/lib/method.ts‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
1+
import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
12
import { ArnFormat, Lazy, Resource, Stack } from '@aws-cdk/core';
23
import { Construct } from 'constructs';
4+
import { ApiGatewayMetrics } from './apigateway-canned-metrics.generated';
35
import { CfnMethod, CfnMethodProps } from './apigateway.generated';
46
import { Authorizer, IAuthorizer } from './authorizer';
57
import { Integration, IntegrationConfig } from './integration';
@@ -9,6 +11,7 @@ import { IModel } from './model';
911
import { IRequestValidator, RequestValidatorOptions } from './requestvalidator';
1012
import { IResource } from './resource';
1113
import { IRestApi, RestApi, RestApiBase } from './restapi';
14+
import { IStage } from './stage';
1215
import { validateHttpMethod } from './util';
1316

1417
export interface MethodOptions {
@@ -364,6 +367,100 @@ export class Method extends Resource {
364367
// For backward compatibility
365368
return options.requestValidator?.requestValidatorId;
366369
}
370+
371+
/**
372+
* Returns the given named metric for this API method
373+
*/
374+
public metric(metricName: string, stage: IStage, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
375+
return new cloudwatch.Metric({
376+
namespace: 'AWS/ApiGateway',
377+
metricName,
378+
dimensionsMap: { ApiName: this.api.restApiName, Method: this.httpMethod, Resource: this.resource.path, Stage: stage.stageName },
379+
...props,
380+
}).attachTo(this);
381+
}
382+
383+
/**
384+
* Metric for the number of client-side errors captured in a given period.
385+
*
386+
* @default - sum over 5 minutes
387+
*/
388+
public metricClientError(stage: IStage, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
389+
return this.cannedMetric(ApiGatewayMetrics._4XxErrorSum, stage, props);
390+
}
391+
392+
/**
393+
* Metric for the number of server-side errors captured in a given period.
394+
*
395+
* @default - sum over 5 minutes
396+
*/
397+
public metricServerError(stage: IStage, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
398+
return this.cannedMetric(ApiGatewayMetrics._5XxErrorSum, stage, props);
399+
}
400+
401+
/**
402+
* Metric for the number of requests served from the API cache in a given period.
403+
*
404+
* @default - sum over 5 minutes
405+
*/
406+
public metricCacheHitCount(stage: IStage, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
407+
return this.cannedMetric(ApiGatewayMetrics.cacheHitCountSum, stage, props);
408+
}
409+
410+
/**
411+
* Metric for the number of requests served from the backend in a given period,
412+
* when API caching is enabled.
413+
*
414+
* @default - sum over 5 minutes
415+
*/
416+
public metricCacheMissCount(stage: IStage, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
417+
return this.cannedMetric(ApiGatewayMetrics.cacheMissCountSum, stage, props);
418+
}
419+
420+
/**
421+
* Metric for the total number API requests in a given period.
422+
*
423+
* @default - sample count over 5 minutes
424+
*/
425+
public metricCount(stage: IStage, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
426+
return this.cannedMetric(ApiGatewayMetrics.countSum, stage, {
427+
statistic: 'SampleCount',
428+
...props,
429+
});
430+
}
431+
432+
/**
433+
* Metric for the time between when API Gateway relays a request to the backend
434+
* and when it receives a response from the backend.
435+
*
436+
* @default - average over 5 minutes.
437+
*/
438+
public metricIntegrationLatency(stage: IStage, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
439+
return this.cannedMetric(ApiGatewayMetrics.integrationLatencyAverage, stage, props);
440+
}
441+
442+
/**
443+
* The time between when API Gateway receives a request from a client
444+
* and when it returns a response to the client.
445+
* The latency includes the integration latency and other API Gateway overhead.
446+
*
447+
* @default - average over 5 minutes.
448+
*/
449+
public metricLatency(stage: IStage, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
450+
return this.cannedMetric(ApiGatewayMetrics.latencyAverage, stage, props);
451+
}
452+
453+
private cannedMetric(fn: (dims: {
454+
ApiName: string;
455+
Method: string;
456+
Resource: string;
457+
Stage: string;
458+
}) => cloudwatch.MetricProps, stage: IStage, props?: cloudwatch.MetricOptions) {
459+
return new cloudwatch.Metric({
460+
...fn({ ApiName: this.api.restApiName, Method: this.httpMethod, Resource: this.resource.path, Stage: stage.stageName }),
461+
...props,
462+
}).attachTo(this);
463+
}
367464
}
368465

369466
export enum AuthorizationType {

‎packages/@aws-cdk/aws-apigateway/lib/restapi.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,12 @@ export interface IRestApi extends IResourceBase {
2828
*/
2929
readonly restApiId: string;
3030

31+
/**
32+
* The name of this API Gateway RestApi.
33+
* @attribute
34+
*/
35+
readonly restApiName: string;
36+
3137
/**
3238
* The resource ID of the root resource.
3339
* @attribute
@@ -673,6 +679,13 @@ export interface RestApiAttributes {
673679
*/
674680
readonly restApiId: string;
675681

682+
/**
683+
* The name of the API Gateway RestApi.
684+
*
685+
* @default - ID of the RestApi construct.
686+
*/
687+
readonly restApiName?: string;
688+
676689
/**
677690
* The resource ID of the root resource.
678691
*/
@@ -713,6 +726,7 @@ export class RestApi extends RestApiBase {
713726
public static fromRestApiAttributes(scope: Construct, id: string, attrs: RestApiAttributes): IRestApi {
714727
class Import extends RestApiBase {
715728
public readonly restApiId = attrs.restApiId;
729+
public readonly restApiName = attrs.restApiName ?? id;
716730
public readonly restApiRootResourceId = attrs.rootResourceId;
717731
public readonly root: IResource = new RootResource(this, {}, this.restApiRootResourceId);
718732
}

‎packages/@aws-cdk/aws-apigateway/lib/stage.ts‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1+
import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
12
import { ArnFormat, Duration, IResource, Resource, Stack, Token } from '@aws-cdk/core';
23
import { Construct } from 'constructs';
34
import { AccessLogFormat, IAccessLogDestination } from './access-log';
5+
import { ApiGatewayMetrics } from './apigateway-canned-metrics.generated';
46
import { CfnStage } from './apigateway.generated';
57
import { Deployment } from './deployment';
68
import { IRestApi, RestApiBase } from './restapi';
@@ -348,4 +350,93 @@ export class Stage extends Resource implements IStage {
348350
};
349351
}
350352
}
353+
354+
/**
355+
* Returns the given named metric for this stage
356+
*/
357+
public metric(metricName: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric {
358+
return new cloudwatch.Metric({
359+
namespace: 'AWS/ApiGateway',
360+
metricName,
361+
dimensionsMap: { ApiName: this.restApi.restApiName, Stage: this.stageName },
362+
...props,
363+
}).attachTo(this);
364+
}
365+
366+
/**
367+
* Metric for the number of client-side errors captured in a given period.
368+
*
369+
* @default - sum over 5 minutes
370+
*/
371+
public metricClientError(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
372+
return this.cannedMetric(ApiGatewayMetrics._4XxErrorSum, props);
373+
}
374+
375+
/**
376+
* Metric for the number of server-side errors captured in a given period.
377+
*
378+
* @default - sum over 5 minutes
379+
*/
380+
public metricServerError(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
381+
return this.cannedMetric(ApiGatewayMetrics._5XxErrorSum, props);
382+
}
383+
384+
/**
385+
* Metric for the number of requests served from the API cache in a given period.
386+
*
387+
* @default - sum over 5 minutes
388+
*/
389+
public metricCacheHitCount(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
390+
return this.cannedMetric(ApiGatewayMetrics.cacheHitCountSum, props);
391+
}
392+
393+
/**
394+
* Metric for the number of requests served from the backend in a given period,
395+
* when API caching is enabled.
396+
*
397+
* @default - sum over 5 minutes
398+
*/
399+
public metricCacheMissCount(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
400+
return this.cannedMetric(ApiGatewayMetrics.cacheMissCountSum, props);
401+
}
402+
403+
/**
404+
* Metric for the total number API requests in a given period.
405+
*
406+
* @default - sample count over 5 minutes
407+
*/
408+
public metricCount(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
409+
return this.cannedMetric(ApiGatewayMetrics.countSum, {
410+
statistic: 'SampleCount',
411+
...props,
412+
});
413+
}
414+
415+
/**
416+
* Metric for the time between when API Gateway relays a request to the backend
417+
* and when it receives a response from the backend.
418+
*
419+
* @default - average over 5 minutes.
420+
*/
421+
public metricIntegrationLatency(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
422+
return this.cannedMetric(ApiGatewayMetrics.integrationLatencyAverage, props);
423+
}
424+
425+
/**
426+
* The time between when API Gateway receives a request from a client
427+
* and when it returns a response to the client.
428+
* The latency includes the integration latency and other API Gateway overhead.
429+
*
430+
* @default - average over 5 minutes.
431+
*/
432+
public metricLatency(props?: cloudwatch.MetricOptions): cloudwatch.Metric {
433+
return this.cannedMetric(ApiGatewayMetrics.latencyAverage, props);
434+
}
435+
436+
private cannedMetric(fn: (dims: { ApiName: string; Stage: string }) => cloudwatch.MetricProps, props?: cloudwatch.MetricOptions) {
437+
return new cloudwatch.Metric({
438+
...fn({ ApiName: this.restApi.restApiName, Stage: this.stageName }),
439+
...props,
440+
}).attachTo(this);
441+
}
351442
}

‎packages/@aws-cdk/aws-apigateway/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@
8080
},
8181
"license": "Apache-2.0",
8282
"devDependencies": {
83+
"@aws-cdk/integ-tests": "0.0.0",
8384
"@aws-cdk/assertions": "0.0.0",
8485
"@aws-cdk/cdk-build-tools": "0.0.0",
8586
"@aws-cdk/integ-runner": "0.0.0",

‎packages/@aws-cdk/aws-apigateway/test/integ.restapi-metrics.ts‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
2+
import * as cdk from '@aws-cdk/core';
3+
import * as integ from '@aws-cdk/integ-tests';
4+
import * as apigw from '../lib';
5+
6+
const app = new cdk.App();
7+
const stack = new cdk.Stack(app, 'restapi-metrics');
8+
const restApi = new apigw.RestApi(stack, 'Api');
9+
const stage = restApi.deploymentStage;
10+
const method = restApi.root.addMethod('GET');
11+
12+
new cloudwatch.Alarm(stack, 'RestApiAlarm', {
13+
metric: restApi.metricClientError(),
14+
evaluationPeriods: 1,
15+
threshold: 1,
16+
});
17+
18+
new cloudwatch.Alarm(stack, 'MethodAlarm', {
19+
metric: method.metricServerError(stage),
20+
evaluationPeriods: 1,
21+
threshold: 1,
22+
});
23+
24+
new cloudwatch.Alarm(stack, 'StageAlarm', {
25+
metric: stage.metricCount(),
26+
evaluationPeriods: 1,
27+
threshold: 1,
28+
});
29+
30+
new integ.IntegTest(app, 'MetricsTest', {
31+
testCases: [stack],
32+
});
33+
34+
app.synth();

0 commit comments

Comments
 (0)