You're getting weird errors for API Gateway and need to see what's going on

You're getting a weird error back from API Gateway and you're not sure where it's coming from. You don't see any evidence in your Lambda or backend logs of the request even getting there. You would like to turn on logging for API Gateway but the settings screen says something about an ARN and that sounds like a deep dive into the bowels of IAM Policies.

It's easier than you think

Don't worry! AWS has setup some IAM templates that make the process of enabling logs pretty easy. After reading this article you'll have logging turned on for API Gateway and be able to customize it by stage and region. This article assumes you already have an API Gateway configured. If you don't you can use Amazon's sample PetStore to practice with.

Set up the IAM Role

The first step in the process is to setup the IAM Role. IAM is kind of scary the first few times you use it, but don't worry! We'll be going off an AWS role template. I recommend making one role per API Gateway region you are using because both API Gateway and CloudWatch follow regions.

0. Navigate to Services -> IAM.
1. Click Roles.
2. Click Create a New Role Button.
3. Choose a name, I recommend the format: apigateway-logs-<region>.
4. Choose Next Step.
5. Under Select Role Type choose "Amazon API Gateway".
6. Check "AmazonAPIGatewayPushToCloudWatchLogs", click Next Step.
7. Click Create Role.
8. Click your new role in the roles listing.
9. Make a note of the Role from the Role ARN field. It's a long string of the form arn:aws:iam::<account id>:role/<role name>. This is the value you're going to paste into the API Gateway configuration. Your new role should look like this:

Configure the IAM Role in API Gateway

The next step is to configure the IAM Role in API Gateway. Rather than configuring on a per-api basis you're going to configure this role on a per API Gateway & Region basis. So all APIs in the region share the same logging role.

0. Navigate to Services -> API Gateway
1. Choose the region you want
2. Click Settings
3. Paste the ARN for the role you created in the CloudWatch log role ARN field.
4. Click Save.

Configure logging in each API

Now you have the API Gateway region configured to log your APIs. The last step is to enable and configure logging on a per-api basis. Make sure you have published your api to at least one stage first before executing the following steps:

0. Navigate to the Stages screen for the stage you want to configure.
1. Under CloudWatch Settings check Enable CloudWatch Logs.
2. Choose the "INFO" Log Level so you can see everything.
3. Check Log full requests/responses data for your practice run. This will dump the entire initial request and response into the log.
4. Check Enble CloudWatch Metrics if you want to see graphs in CloudWatch.

View your logs

It's time to view your logs! Execute one of your APIs again after configuring the logs so you have something to view.

0. Navigate to Services -> CloudWatch
1. Choose the region that matches your API Gateway region.
2. Select Logs on the Left menu
3. The logs for your API Gateway will be named based on the id of your api. The form is "API-Gateway-Execution-Logs_<api id>/<api stage>
   Select your logs and you will see a giant list of log streams with cryptic identifiers. Look in the Last Event Time column for a date/time stamp and find your recent execution.

Keep in mind

• Each region has its own setting for log roles, so if you get a warning about the ARN not being set be sure to check the API Gateway settings for the region you are in.
• You won't get any logs if your URL accidentally uses a resource that's not configured. For example if you just append "/foo" to a URL you have working you will get a 403 "Missing authentication token" response and won't even see a new log entry at all. It's too bad it doesn't get logged as a simple error because this would save me a lot of headaches.
• Be sure to set up expiration for your API Logs so they don't become a runaway train in your storage system. Since the log stream name varies by stage you can configure your prod stage differently than your dev stage.

Tell me what you're troubleshooting

I hope this article helps you with troubleshooting your API Gateway problems. I'd love to hear what kinds of troubleshooting has been challenging for you. Please comment below, tweet @kennbrodhagen, or email me kennbrodhagen@gmail.com and let me know what trouble you're shooting!

References

• Image by Skitter Photo used under Creative Commons

Interested in more?

Sign up for my mailing list. You'll get each new article and other announcements delivered to your inbox. I promise not to spam you. Unsubscribe any time you like.