Menu
Amazon API Gateway
Developer Guide

Set up API Logging in API Gateway

To help debug issues related to request execution or client access to your API, you can enable Amazon CloudWatch Logs to trace API calls. Once enabled, API Gateway will log API calls in CloudWatch. There are two types of API logging: execution logging and access logging.

In execution logging, API Gateway manages the CloudWatch Logs. The process includes creating log groups and log streams, and reporting to the log streams any caller's requests and responses. The logged data includes errors or execution traces (such as request or response parameter values or payloads), data used by custom authorizers, whether API keys are required, whether usage plans are enabled, and so on.

When you deploy an API, API Gateway creates a log group and log streams under the log group. The log group is named following the API-Gateway-Execution-Logs_{rest-api-id}/{stage_name} format. Within each log group, the logs are further divided into log streams, which are ordered by Last Event Time as logged data is reported.

In access logging, you, as an API developer, want to log who has accessed your API and how the caller accessed the API. You can create your own log group or choose an existing one, which could be managed by API Gateway. You can specify the access details by selecting $context variables, expressed in a format of your choosing, and by choosing a log group as the destination. To preserve uniqueness of each log, access log format must include $context.requestId.

Choose a log format that is also adopted by your analytic backend, such as Common Log Format (CLF), JSON, XML, or CSV. You can then feed the access logs to it directly to have your metrics computed and rendered. To define the log format, set the log group ARN on the accessLogSettings/destinationArn property on the stage. You can obtain a log group ARN in the CloudWatch console, provided that the ARN column is selected for display. To define the access log format, set a chosen format on the accessLogSetting/format property on the stage.

Examples of some commonly used access log formats are shown in the API Gateway console and listed as follows.

  • CLF (Common Log Format):

    Copy
    $context.identity.sourceIp $context.identity.caller \ $context.identity.user [$context.requestTime] \ "$context.httpMethod $context.resourcePath $context.protocol" \ $context.status $context.responseLength $context.requestId

    The continuation characters (\) are meant as a visual aid and the log format cannot have any line breaks.

  • JSON:

    Copy
    { "requestId":"$context.requestId", \ "ip": "$context.identity.sourceIp", \ "caller":"$context.identity.caller", \ "user":"$context.identity.user", \ "requestTime":"$context.requestTime", \ "httpMethod":"$context.httpMethod", \ "resourcePath":"$context.resourcePath", \ "status":"$context.status", \ "protocol":"$context.protocol", \ "responseLength":"$context.responseLength" \ }

    The continuation characters (\) are meant as a visual aid and the log format cannot have any line breaks.

  • XML:

    Copy
    <request id="$context.requestId"> \ <ip>$context.identity.sourceIp</ip> \ <caller>$context.identity.caller</caller> \ <user>$context.identity.user</user> \ <requestTime>$context.requestTime</requestTime> \ <httpMethod>$context.httpMethod</httpMethod> \ <resourcePath>$context.resourcePath</resourcePath> \ <status>$context.status</status> \ <protocol>$context.protocol</protocol> \ <responseLength>$context.responseLength</responseLength> \ </request>

    The continuation characters (\) are meant as a visual aid and the log format cannot have any line breaks.

  • CSV (comma-separated values):

    Copy
    $context.identity.sourceIp,$context.identity.caller,\ $context.identity.user,$context.requestTime,$context.httpMethod,\ $context.resourcePath,$context.protocol,$context.status,\ $context.responseLength,$context.requestId

    The continuation characters (\) are meant as a visual aid and the log format cannot have any line breaks.

Permissions

To enable CloudWatch Logs, you must grant API Gateway proper permissions to read and write logs to CloudWatch for your account. The AmazonAPIGatewayPushToCloudWatchLogs managed policy (with an ARN of arn:aws:iam::aws:policy/service-role/AmazonAPIGatewayPushToCloudWatchLogs) has all the required permissions.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:PutLogEvents", "logs:GetLogEvents", "logs:FilterLogEvents" ], "Resource": "*" } ] }

To grant these permissions to your account, create an IAM role with apigateway.amazonaws.com as its trusted entity, attach the preceding policy to the IAM role, and set the IAM role ARN on the cloudWatchRoleArn property on your Account.

Set up API Logging Using the API Gateway Console

To set up API logging, you must have deployed the API to a stage. You must also have configured an appropriate CloudWatch Logs role ARN for your account.

  1. Sign in to the API Gateway console.

  2. Choose Settings from the primary navigation panel. Type an ARN of an IAM role with appropriate permissions in CloudWatch log role ARN. You need to do this once.

  3. Do one of the following:

    1. Choose an existing API and then choose a stage.

    2. Create an API and deploy it to a stage.

  4. Choose Logs in the Stage Editor.

  5. To enable execution logging, choose Enable CloudWatch Logs under CloudWatch Settings. Choose Error or Info from the drop-down menu. If desired, choose Enable Detailed CloudWatch Metrics.

  6. To enable access logging, choose Enable Access Logging under Custom Access Logging. Then type the ARN of a log group in CloudWatch Group. Type a log format in Log Format. You can choose CLF, JSON, XML, or CSV to use one of the provided examples as a guide.

  7. Choose Save Changes.

Note

You can enable execution logging and access logging independent of each other.

API Gateway is now ready to log requests to your API. You do not need to redeploy the API when you update the stage settings, logs, or stage variables.