API Logging Deep Dive

Why log?

When we work in the cloud, we have to expect the unexpected. Experts rightly warn that we must understand that "everything fails all the time" in the cloud (AWS CTO Werner Vogels). It’s said that "success is an exception" for services deployed on the cloud, and our implementation should survive all eventualities.

Things go wrong, and the applications fail more often than we imagine. When that happens, the first problem is identifying what went wrong. Unfortunately, when our data flows through a hundred services deployed across the globe, it’s challenging to locate the path it followed or guess if it missed something.

AWS provides CloudWatch to watch all that’s happening in the cloud. Besides other features, CloudWatch can collect all logs of all services running in our account and it helps us analyze those logs. We can configure all AWS services to dump their logs into CloudWatch. We can also configure special alarms in CloudWatch so that it notifies us when our attention is required.

CloudWatch is versatile so, naturally, it costs money. Excessive logging is costly. At the same time, we can’t afford to be miserly about it. It’s important that we send the right amount of details to CloudWatch. This amount isn’t easy to identify. There’s no general answer to this. Some applications can go well with minimal logs, while others require extreme details. The final decision depends upon the requirement and judgment of the architect.

However, to make such a decision, it’s important to understand the different configurations for API logging. Let’s look at that in detail.

API logging

REST API allows us to configure logs in the following different ways:

• Error and info logs

• Requests and responses

• Access logs

Additionally, we can enable detailed CloudWatch metrics to see a graphical view of the API statistics.

Error and info logs

The API gateway processes the incoming request through the four steps of integration. Request mapping, request integration, response integration, and response mapping. Each step has specific processing that potentially generates logs. We can tap these logs into CloudWatch.

API Gateway creates a new log group in CloudWatch for every API. We can configure the logging level to be INFO or ERROR. Some systems require audit logs with details about every request. For such applications, we can set it to INFO. Otherwise, we can set the log level to ERROR so that the BAU logs don’t clutter our system.

Request and response

We can make the API logs more verbose by adding the complete request or response payload to the intermediate processing logs.

Access logs

We can configure the API to log specific details about each individual invocation. It’s called the access log. It consists of the contextual information mainly pulled from `$context`. We have the freedom to choose just what we need. These logs go to the log group we explicitly configure for the access logs.