Logging API calls to Kinesis Data Firehose

To help debug issues related to client access to your API, you can log API calls to Amazon Kinesis Data Firehose. For more information about Kinesis Data Firehose, see What Is Amazon Kinesis Data Firehose?.

For access logging, you can only enable CloudWatch or Kinesis Data Firehose—you can't enable both. However, you can enable CloudWatch for execution logging and Kinesis Data Firehose for access logging.

Kinesis Data Firehose log formats for API Gateway

Kinesis Data Firehose logging uses the same format as CloudWatch logging.

Permissions for Kinesis Data Firehose logging

When Kinesis Data Firehose access logging is enabled on a stage, API Gateway creates a service-linked role in your account if the role doesn't exist already. The role is named AWSServiceRoleForAPIGateway and has the APIGatewayServiceRolePolicy managed policy attached to it. For more information about service-linked roles, see Using Service-Linked Roles.

Note

The name of your Kinesis Data Firehose delivery stream must be amazon-apigateway-{your-delivery-stream-name}.

Set up Kinesis Data Firehose access logging by using the API Gateway console

To set up API logging, you must have deployed the API to a stage. You must also have created a Kinesis Data Firehose delivery stream.

Old REST API console

Note

We've redesigned the API Gateway console. The old console experience will no longer be available starting December 2023.

1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

2. 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.

3. Choose Logs/Tracing in the Stage Editor.

4. To enable access logging to a Kinesis Data Firehose delivery stream:

   1. Choose Enable Access Logging under Custom Access Logging.

   2. Enter the ARN of a Kinesis Data Firehose delivery stream in Access Log Destination ARN. The ARN format is arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-delivery-stream-name}.

      Note

      The name of your delivery stream must be amazon-apigateway-{your-delivery-stream-name}.

   3. Enter a log format in Log Format. You can choose CLF, JSON, XML, or CSV to use one of the provided examples as a guide.

5. Choose Save Changes.

New REST API console

1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

2. 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.

3. In the main navigation pane, choose Stages.

4. In the Logs and tracing section, choose Edit.

5. To enable access logging to a Kinesis Data Firehose delivery stream:

   1. Turn on Custom access logging.

   2. For Access log destination ARN, enter the ARN of a Kinesis Data Firehose delivery stream. The ARN format is arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-delivery-stream-name}.

      Note

      The name of your delivery stream must be amazon-apigateway-{your-delivery-stream-name}.

   3. For Log format, enter a log format. You can choose CLF, JSON, XML, or CSV. To learn more about example log formats, see CloudWatch log formats for API Gateway.

6. Choose Save changes.

API Gateway is now ready to log requests to your API to Kinesis Data Firehose. You don't need to redeploy the API when you update the stage settings, logs, or stage variables.