APIs Detailed CloudWatch Metrics

Risk Level: Medium (should be achieved)

Rule ID: AG-002

Ensure that detailed CloudWatch metrics are enabled for all your Amazon API Gateway APIs in order to monitor API stage caching and latency, detect errors at a granular level, and set appropriate CloudWatch alarms.

This rule can help you with the following compliance standards:

MAS
NIST4

For further details on compliance standards supported by Conformity, see here.

This rule can help you work with the AWS Well-Architected Framework.

This rule resolution is part of the Conformity Security & Compliance tool for AWS.

Operational
excellence

Performance
efficiency

Sustainability

The main benefit of enabling detailed CloudWatch metrics for Amazon API Gateway APIs is getting more granular metric data which can help you to act fast and take immediate actions based on information delivered by these metrics through CloudWatch alarms. For example, if you developed a critical API and you need to be notified when there is a sudden spike in 4xx or 5xx errors, you can set up CloudWatch alarms that can monitor on a per minute basis (instead of 5-minute period), using the data gathered by the detailed metrics.

Audit

To determine if detailed CloudWatch metrics are enabled for Amazon API Gateway APIs, perform the following actions:

Using AWS Console

01 Sign in to the AWS Management Console.

02 Navigate to API Gateway console at https://console.aws.amazon.com/apigateway/.

03 In the main navigation panel, select APIs to access your API Gateway APIs.

04 Click on the name (link) of the API that you want to examine.

05 Choose Stages from the API menu to access the stages created for the selected API.

06 Click on the name of the API stage that you want to examine and choose the Logs/Tracing tab.

07 On the Logs/Tracing panel, in the CloudWatch Settings section, check the Enable Detailed CloudWatch Metrics setting status. If the Enable Detailed CloudWatch Metrics setting is disabled (i.e. the setting checkbox is not checked), the detailed Amazon CloudWatch metrics are not enabled for the selected API stage.

08 Repeat steps no. 6 and 7 for each API stage created for the selected API.

09 Repeat steps no. 4 – 8 for each Amazon API Gateway API available within the current region.

10 Change the AWS cloud region from the navigation bar and repeat the Audit process for other regions.

Using AWS CLI

01 Run get-rest-apis command (OSX/Linux/UNIX) using custom query filters to list the ID of each API Gateway API available in the selected AWS region:

aws apigateway get-rest-apis
  --region us-east-1
  --output table
  --query 'items[*].id'

02 The command output should return a table with the requested API ID(s):

----------------
|  GetRestApis |
+--------------+
|  abcabcabca  |
|  abcdabcdab  |
|  aabbccddee  |
+--------------+

03 Run get-stages command (OSX/Linux/UNIX) using the ID of the Amazon API Gateway API that you want to examine as the identifier parameter and custom query filters to get the names of the API stages created for the selected API:

aws apigateway get-stages
  --region us-east-1
  --rest-api-id abcabcabca
  --output table
  --query 'item[*].stageName'

04 The command output should return the requested API stage name(s):

----------------
|  GetStages   |
+--------------+
|  Production  |
|  Staging     |
|  Development |
+--------------+

05 Run get-stages command (OSX/Linux/UNIX) using the name of the API stage that you want to examine as the identifier parameter and custom query filters to determine whether the detailed CloudWatch metrics are enabled for the selected API stage:

aws apigateway get-stages
  --region us-east-1
  --rest-api-id abcabcabca
  --query 'item[?(stageName==`Production`)].methodSettings."*/*".metricsEnabled'

06 The command output should return the requested feature status:

[
  false
]

If the get-stages command output returns false or an empty array (i.e. []), the detailed Amazon CloudWatch metrics are not enabled for the selected API stage.

07 Repeat steps no. 5 and 6 for each API stage created for the selected API.

08 Repeat steps no. 4 – 7 for each Amazon API Gateway API available in the selected AWS region.

09 Change the AWS cloud region by updating the --region command parameter value and repeat the Audit process for other regions.

Remediation / Resolution

To enable detailed CloudWatch metrics for your Amazon API Gateway APIs, perform the following operations:

Using AWS CloudFormation

01 CloudFormation template (JSON):

{
   "AWSTemplateFormatVersion":"2010-09-09",
   "Description":"Enable Detailed CloudWatch Metrics",
   "Resources":{
      "RestAPI": {
         "Type": "AWS::ApiGateway::RestApi",
         "Properties": {
           "Name": "WebServiceAPI",
           "Description" : "A simple API Gateway REST API"
         }
      },
      "StageDeployment": {
           "Type": "AWS::ApiGateway::Deployment",
           "Properties": {
               "RestApiId": {
                  "Ref": "RestAPI"
               }
            }
      },
      "APIAccount": {
        "Type": "AWS::ApiGateway::Account",
        "Properties": {
            "CloudWatchRoleArn": "arn:aws:iam::123456789012:role/api-gateway-log-role"
         }
      },
      "APIStage": {
         "Type": "AWS::ApiGateway::Stage",
         "Properties": {
             "DeploymentId": {
                "Ref": "StageDeployment"
             },
             "RestApiId": {
                  "Ref": "RestAPI"
             },
             "StageName" : "Staging",
             "MethodSettings": [
                 {
                     "ResourcePath": "/*",
                     "HttpMethod": "*",
                     "MetricsEnabled": true
                 }
             ]
         }
      }
   }
}

02 CloudFormation template (YAML):

AWSTemplateFormatVersion: '2010-09-09'
Description: Enable Detailed CloudWatch Metrics
Resources:
  RestAPI:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: WebServiceAPI
      Description: A simple API Gateway REST API
  StageDeployment:
    Type: AWS::ApiGateway::Deployment
    Properties:
      RestApiId: !Ref 'RestAPI'
  APIAccount:
    Type: AWS::ApiGateway::Account
    Properties:
      CloudWatchRoleArn: arn:aws:iam::123456789012:role/api-gateway-log-role
  APIStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      DeploymentId: !Ref 'StageDeployment'
      RestApiId: !Ref 'RestAPI'
      StageName: Staging
      MethodSettings:
        - ResourcePath: /*
          HttpMethod: '*'
          MetricsEnabled: true

Using Terraform (AWS Provider)

01 Terraform configuration file (.tf):

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 3.27"
    }
  }

  required_version = ">= 0.14.9"
}

provider "aws" {
  profile = "default"
  region  = "us-east-1"
}

resource "aws_api_gateway_account" "api-account" {
  cloudwatch_role_arn = "arn:aws:iam::123456789012:role/api-gateway-log-role"
}

resource "aws_api_gateway_rest_api" "rest-api" {
  name = "web-service-api"
  description = "A simple API Gateway REST API"
}

resource "aws_api_gateway_deployment" "rest-api-deployment" {
  rest_api_id = aws_api_gateway_rest_api.rest-api.id
}

resource "aws_api_gateway_stage" "api-stage" {
  deployment_id = aws_api_gateway_deployment.rest-api-deployment.id
  rest_api_id   = aws_api_gateway_rest_api.rest-api.id
  stage_name    = "Production"
}

resource "aws_api_gateway_method_settings" "api-gateway-method" {
  rest_api_id = aws_api_gateway_rest_api.rest-api.id
  stage_name  = aws_api_gateway_stage.api-stage.stage_name
  method_path = "*/*"

  settings {

    # Enable Detailed CloudWatch Metrics
    metrics_enabled = true
    logging_level   = "INFO"

  }

}

Using AWS Console

01 Sign in to the AWS Management Console.

02 Navigate to API Gateway console at https://console.aws.amazon.com/apigateway/.

03 In the main navigation panel, select APIs to access your API Gateway APIs.

04 Click on the name of the API that you want to reconfigure.

05 Choose Stages from the API menu to access the stages created for the selected API.

06 Click on the name of the API stage that you want to access and choose the Logs/Tracing tab.

07 On the Logs/Tracing panel, in the CloudWatch Settings section, select the Enable Detailed CloudWatch Metrics setting checkbox to enable detailed Amazon CloudWatch metrics for the selected API stage. Choose Save Changes to apply the changes. Once enabled, each API method will begin to generate the following metrics: API calls, Latency, Integration Latency, 4xx and 5xx errors.

08 Repeat steps no. 6 and 7 to enable detailed CloudWatch metrics for each API stage created for the selected API.

09 Repeat steps no. 4 – 8 to reconfigure each Amazon API Gateway API available within the current AWS region.

10 Change the AWS cloud region from the navigation bar and repeat the Remediation process for other regions.

Using AWS CLI

01 Run update-stage command (OSX/Linux/UNIX) using the name of the API stage that you want to reconfigure as the identifier parameter, to enable detailed Amazon CloudWatch metrics for the selected API stage. Once enabled, each API method will begin to generate the following metrics: API calls, Latency, Integration Latency, 4xx and 5xx errors. The following command request example detailed metrics for an API stage named "Production", created for an API identified by the ID "abcabcabca":

aws apigateway update-stage
  --region us-east-1
  --rest-api-id abcabcabca
  --stage-name 'Production'
  --patch-operations op=replace,path=/*/*/metrics/enabled,value=true

02 The command output should return the metadata available for the reconfigured API stage:

{
    "stageName": "Production",
    "cacheClusterSize": "0.5",
    "cacheClusterEnabled": false,
    "cacheClusterStatus": "NOT_AVAILABLE",
    "deploymentId": "abc123",
    "createdDate": "2022-01-11T10:56:31+00:00",
    "lastUpdatedDate": "2022-01-11T12:34:58+00:00",
    "methodSettings": {
        "*/*": {
            "cacheTtlInSeconds": 300,
            "loggingLevel": "INFO",
            "dataTraceEnabled": true,
            "metricsEnabled": true,
            "unauthorizedCacheControlHeaderStrategy": "SUCCEED_WITH_RESPONSE_HEADER",
            "throttlingRateLimit": 10000.0,
            "cacheDataEncrypted": false,
            "cachingEnabled": false,
            "throttlingBurstLimit": 5000,
            "requireAuthorizationForCacheControl": true
        }
    }
}

03 Repeat steps no. 1 and 2 to enable detailed CloudWatch metrics for each API stage created for the selected API.

04 Repeat steps no. 1 – 3 to reconfigure each Amazon API Gateway API available in the selected AWS region.

05 Change the AWS cloud region by updating the --region command parameter value and perform the Remediation process for other regions.

References

AWS Command Line Interface (CLI) Documentation
apigateway
get-rest-apis
get-stages
update-stage

CloudFormation Documentation
Amazon API Gateway resource type reference

Terraform Documentation
AWS Provider

Publication date Nov 2, 2017

Audit

Using AWS Console

Using AWS CLI

Remediation / Resolution

Using AWS CloudFormation

Using Terraform (AWS Provider)

Using AWS Console

Using AWS CLI

References

Related APIGateway rules