Debugging AWS lambda locally in developers machine

This post explains how to debug a lambda on a developers machine using sam (serverless application model).

This will invoke the local AWS lambda function on a docker and quits after the invocation completes.

Prepare the dependencies:

1. Template file

As in any sam application, we need a template file which specifies the serverless application. This has to be in the root of the application. If it is on another path, it can be specified using --template parameter.

2. Docker

Keep docker running so that the lambda can be deployed in a container.

3. Prepare incoming data

Most lambda wakes up on an event occurrence and that event will be passed as parameter to the lambda. In addition, there will be request data. Since we are running the lambda in local, we need to provide these data. For that, create a json file and keep some sample data in it.

For example, I would create a localTesting folder and keep a lambda-params.json in it. The data to be passed can be configured as below:

//localTesting/lambda-params.json

{
  "body": "{\"url\": \"/test-page\"}"
}

This will be passed as the --event param.

4. Prepare env variables

In addition to incoming data, there will be some env variables which the lambda will look for during the execution. We need to provide that too. For that we can create another file called local-env.json in the localTesting folder and keep the required info like below:

{
  "Publish": {
    "ENVIRONMENT_NAME": "staging",
    "S3_BUCKET_NAME": "staging-s3",
    "AWS_SDK_LOAD_CONFIG": 1
  }
}

Configurations specific to another entry point can be configured as comma separated list in this file.

This file can be specified in the --env-vars parameter.

5. CLI installations

Time to install sam cli. For mac, the installation commands using home brew are the following:

brew tap aws/tap
brew install aws-sam-cli

more help on installation https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install-mac.html

6. Grab the entry point name

Almost there. We can grab the name of the entrypoint which we are going to trigger. It will be in the template file as the name of the lambda description. For my case, it is Publish.

7. Find CodeUri path

Go to the template file and find the CodeUri in your lambda specification. We need this folder with the lambda logic to be generated before running the lambda.

8. Build

If you are using node, go to package.json and find the command which to build the code, which would possibly result in the codeUri path in the previous step to be generated.

Run it

Now that we have all the necessary dependencies tackled, we just have to run it

sam local invoke --env-vars localTesting/local-env.json --event localTesting/lambda-params.json "Publish"

This expects the template to be on the root. If it's on another path, specify that too using --template parameter.

For example,

sam local invoke --template src/template.yml --env-vars localTesting/local-env.json --event localTesting/lambda-params.json "Publish"

This will print out the lambda response on the terminal. You can add logs to debug or even build newer features easily now.

Note: remember to rebuild after every change. If you keep build in watch mode, you don't even have to build again.

Bonus tip:

If you wan't to test only the application logic of a lambda, you could invoke the built lambda function with necessary params without sam.