Navigate your AWS Lambda Logs from Amazon API Gateway Response Headers

Sergei Khazov
Jul 13, 2018 · 4 min read
Photo by Paweł Czerwiński on Unsplash

When Front-End team works on integration of the new endpoint into the app, they might catch some unexpected behavior from endpoint. So the Back-End team needs spend some time on tracing down logs, finding the specific request that finished unsuccessfully and then start the investigation. Searching for broken request seems to be a big waist of time. And what if Front-End engineer can include in the bug report some unique request Id that helps Back-End engineer to simply navigate request’s execution logs, so engineer can start the investigation right away. This article explains how to implement this approach into your serverless app.

For Back-End App implementation I used AWS Lambda, Amazon API Gateway, and Serverless framework. Since API Gateway has access to data that was return from integration part (in our case it’s Lambda function), the main challenge for this implementation is to describe to the API Gateway where to pull from Lambda awsRequestId value (unique Lambda request id) so it can inject into response headers.

Lambda awsRequestId can be retrieved as a property from $context variable inside your Lambda handler as:

console.log('AWSrequestID', context.aswReestId);


AWS request ID associated with the request. This is the ID returned to the client that called the invoke method.

So when you can read Lambda awsRequestId you can send it to API Gateway response headers. There two ways how to set up custom headers in Amazon API Gateway:

  1. Using Lambda Proxy Integration
  2. Using API Gateway Response Data Mapping for Custom Lambda Integration

Lambda Proxy Integration

If you develop your application by using Proxy Integration you can simply define your custom header, lets say: x-amzn-LambdaRequestId, inside your Lambda response object as one of the property of headers:

Lambda Proxy Integration custom headers example

So now, when you’ll trigger your Lambda through API Gateway endpoint, you will see the additional costume header that you just set up.

Lambda awsRequestId presented in API Gateway Response Headers

Having this value you can simple navigate to Lambda’s AWS CloudWatch Logs and search Lambda logs by awsRequestId value: "fbfbe144-8074-11e8-a928-e9557e22f5ec" Please make sure that you place awsRequestId value in double quotes, so CloudWatch will take it as a whole string. The search result display logs flow related to the lambda’s specific request. So you can easily traced down your application on each step.

CloudWatch Filter Logs example

Custom Lambda Integration

If you develop you serverless application by using Lambda Integration you need to use API Gateway Response Data Mapping to define how Lambda will set custom header value for API Gateway.

Since you already know how to get awsRequestId inside Lambda function (see above), you can start from defining you serverless.yml template file. When you defining lambda function in template file, you need to adjust response section and include headers property with expected headers mapping from lambda.

As you can see from above example, there new header key x-amzn-LambdaRequestId, that gets awsRequestId from lambda through integration.response object. Integration Response object is the part of API Gateway Response Data Mapping variables. It provides the access for data returned from integration part (Lambda function in our case), so since lambda returns awsRequestId as part of body response, you can simply map it to custom header. Let’s take a look how to define the response from lambda, to support above template.

In above example, Lambda response includes header property awsLambdaRequestId that gives the access to API Gateway to read this value as integration.response.body.headers.awsLambdaRequestId When you need to support error response from lambda, you need to stringify the whole response object and read lambda’s awsRequestId through errorMessage property as integration.response.body.errorMessage.headers.awsLambdaRequestId It should set the custom header value as expected. After the application is deployed, you will get the same ability to search logs as you did in Proxy Integration implementation (see above)

Example filter logs in Lambda Custom Integration

Having this logging feature improvement on your endpoint can save you time on searching logs and it can improve bug reports information for your Back-End team. Good luck and happy codding!

Sergei Khazov

Written by

Cloud Engineer. Solution Architect. Full Stack Web-Developer. Excited about serverless approach.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade