Debugging Lambdas on AWS from your local computer 
Tags: rust, showdev, aws, productivity
Published: 2020-09-01 09:24:52

*I often need to debug complex Lambda setups that are tightly integrated into other services and are hard to simulate in my local dev environment. Even if I manage to grab the event JSON it is hard to send the response back in a timely manner. What I always wanted was to invoke Lambda handlers locally in response to AWS events in real time. This post describes one such solution I've been using successfully for the last few weeks.*

The core of my solution is an [AWS lambda function that acts as a proxy](https://github.com/rimutaka/lambda-debug-proxy). It sends both `Payload` and `Context` to a predefined SQS queue and then waits for a response that is deserialized and passed back onto the runtime.

In the meantime, you can read the message from the queue, deserialize  `Payload` and `Context`, process it locally and send back a response. If your local lambda fails you can re-read the message until either the proxy lambda times out or you send back a reply.

![flow diagram](https://raw.githubusercontent.com/rimutaka/lambda-debug-proxy/master/img/schematics.png)

The benefit of this approach *vs* using a local [mock environment](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-layer-simulated-docker/) is the full integration in your infra. It is not always possible to use mock input or try to copy the input by hand. The proxy function will give you near-real time request/response with real data.

### Components

- **Lambda Runtime** - a [modified Lambda runtime for Rust](https://github.com/rimutaka/aws-lambda-rust-runtime/tree/proxy-experiment) that adds a few required features
- **Lambda Handler Proxy** - a [handler](https://github.com/rimutaka/lambda-debug-proxy/blob/master/src/main.rs) that relays data to/from SQS queues
- **Request Queue** - an SQS queue for forwarding event details to the dev environment
- **Response Queue** - an SQS queue for forwarding response details from the dev environment
- **Lambda Handler Wrapper** - a [Lambda handler wrapper](https://github.com/rimutaka/lambda-debug-proxy/blob/master/examples/local.rs) running in dev environment and communicating with SQS queues
- **Lambda Handler** - the handler function that is supposed to run on AWS Lambda, but will be debugged in the local dev environment

![sequence diagram](https://raw.githubusercontent.com/rimutaka/lambda-debug-proxy/master/img/sequence.png)

If you are not familiar with [AWS SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html) you may not know that the messages [have to be explicitly deleted](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html) from the queue. The request messages are deleted by the handler wrapper when the handler returns a response. This allows re-running the handler if it fails before sending a response, which is a handy debugging feature. The response messages are deleted by the handler proxy as soon as they arrive.

It is possible for the response to arrive too late because either the Lambda Runtime or the caller timed out. For example, AWS APIGateway wait is limited to 30s. The Lambda function can be configured to wait for up to 15 minutes. I usually finish debugging regardless of the timeout and then re-run the request. 

### Client config

The lambda handler running on your local machine has to be wrapped into a local client that reads the queue, de-serializes the payload into your required format, calls your handler function and sends the response back. It is the exact reverse of what the  proxy function running at the AWS end does. See [local.rs example](https://github.com/rimutaka/lambda-debug-proxy/blob/master/examples/local.rs) for a sample Rust implementation. It should be easy to port the sample wrapper into the language of your Lambda handler.

Check out the source code on GitHub: https://github.com/rimutaka/lambda-debug-proxy.