Enable detailed metrics for RestAPI construct?

[paul-uz]

detailedMetricsEnabled is available for the HttpApi in API Gateway v2, but seemingly isnt for the API Gateway RestApi. What gives?

[github-actions[bot]]

Hello! Reopening this discussion to make it searchable.

[paul-uz]

It is there, just maybe not labelled "super" well. It's enabled via metricsEnabled, whereas in HttpApi it's detailedMetricsEnabled

[DYNOSuprovo]

In AWS CDK for API Gateway v1 (RestApi), the property is named metricsEnabled instead of detailedMetricsEnabled.

It is configured through deployOptions (or directly on a Stage construct), either across the entire stage or scoped to individual method paths.

---

1. Enable Detailed Metrics Across the Entire Stage

To enable detailed CloudWatch metrics for all resources and methods in your RestApi:

import * as apigateway from 'aws-cdk-lib/aws-apigateway';

const api = new apigateway.RestApi(this, 'MyRestApi', {
  deployOptions: {
    stageName: 'prod',
    metricsEnabled: true, // <--- Enables detailed CloudWatch metrics for all methods
    loggingLevel: apigateway.MethodLoggingLevel.INFO,
    dataTraceEnabled: false,
  },
});

---

2. Enable Detailed Metrics for Specific Methods Only

If you only want detailed metrics on specific high-traffic or critical routes (to optimize CloudWatch custom metrics costs):

const api = new apigateway.RestApi(this, 'MyRestApi', {
  deployOptions: {
    stageName: 'prod',
    methodOptions: {
      // Wildcard for all methods under a specific resource
      '/items/*': {
        metricsEnabled: true,
      },
      // Or an exact path and HTTP verb
      '/orders/GET': {
        metricsEnabled: true,
      },
    },
  },
});

---

3. How It Maps to CloudFormation

Under the hood, CDK compiles this into the AWS::ApiGateway::Stage resource's MethodSettings block:

Type: AWS::ApiGateway::Stage
Properties:
  StageName: prod
  MethodSettings:
    - ResourcePath: '/*'
      HttpMethod: '*'
      MetricsEnabled: true

What You Get:

Once enabled, API Gateway publishes detailed per-method metrics to Amazon CloudWatch under the namespace AWS/ApiGateway with dimensions:

• ApiName
• Stage
• Method
• Resource

These include Latency, IntegrationLatency, Count, 4XXError, and 5XXError at 1-minute intervals.