Lambda Live Debugger

Lambda Live Debugger is indispensable tool that allows you to debug AWS Lambda from your computer althouw it is deplyoed on the cloud. It support Lambdas writen in JavaScript and TypeScript.

It support the folowing frameworks:

• AWS CDK v2
• Serverless Framework v3 (SLS)
• AWS Serverless Application Model (SAM)
• Terraform
• an option to implement any framwrowk/seupt implementaiton via custom extension
• ... (do you need any other framwwork suppor?)

Early alpha state

Currently the project is in early alpha state. Please let me know if everyting works for you. Just a simple message would help a lot, so I know I am on the right track. I tested many secanrious, but there are numerus ways how peope can configure project and TypeScript configuration. Project is flexible enoug so setting can be twicked to adjust your setup, without code changes. Any other advice how to improve the project is also very welcome.

Ways to contact me:

• Open GitHub issue
• LinkedIn

The problem statement

The Serverless is amazing and resolve mayn issues that regular stemns face. But developing can be a strugle. You write code, deploy run, fix deploy again. That process is extremly time consuming and tiresome. You can also use one of the tools for running code localy or use unit/interation tests for that, but that has many other issues and it does not mimic an actualy enviroment enoug.

Tools like SST and Serverless Framework V4 has the exact same functionality (without Observability mode). But other tools do not have it.

How does it work

It connect to your deployed Lambda, send the request to your computer and the response back to Lambda. This way you can debug on your machine, but system begavous as code is running in the cloud with the same permissions.

Lambda Live Debugger attach Lambda Extensions (via Layer) to the Lambda to interecept calls and send them to AWS IoT. AWS IoT is used for transfering messages to your machine and back. Lambda Live Debugger running localy attach to the AWS IoT and excute the call localy. If Lambda is writem in TypeScript it transpile it to JavaScript. Calls are executed via Node Worker Threads.

Lambda Live Debugger makes the follwoing changes to your AWS infrastructureo:

• Lambda excentions as a Layer
• Attach Layer to each Lambda that you are debugging
• Add policy to Lambda Role to use AWS IoT

In case you do not want to add Layer to all functions you can limit to one the onest you need via configuration parameters.

While compiling it creates a lot of temporary files in folder .lldebugger, you can freely delete the folder once you are done dubbging, or simpler add .lldebugger to .gitignore. The wizard add that for you if you want.

Your developing process with Lambda Live Debugger

Since you will be deplying code into actual AWS accound while developing it is mandatory that you use that enviroment only for yourself or better create a temporary enviroment for you or your featrue you are working om.

Unfortunately haveing a seperate AWS enviromonment is not always possible, becaouse of organization issues (it is 2024 and companies still do not uderstand how to work with serverless) or techincal (hard to dupklicate database or other parts of the system). For that perpuse there is an Observability Mode.

Observability Mode

In Observability Mode Lambda Live Debugger via Lambda Extension just intercept the request received by Lambda and forward it to local enviroment, but it does not wait for the response. After that Lambda continue regular execution and ignores response from loca environement. The enviroment is not impacted and regular users can continue use it aswell as other develoers. You can run Observability Mode on development and testing eviroment. If you are adventures you can even run it in production. In observablitiy mode you do not get all Lambda requests. You only get one every 3 seconds. You can configure that interval via interval setting. This way the system is not overloaded if there are a lot of requests comming in.

How to start

Installation

Install localy: npm install lambda-live-debugger or globaly npm install lambda-live-debugger -g (Linux, Mac: sudo npm install lambda-live-debugger -g)

How to run

If you use default profile, default region and other default setting than just run:

npx lld or lld (if installed globaly)

But you probably need to tweak some setting. You can do it via CLI parameters or better run a wizard. The configuration is saved to lldebugger.config.ts

npx lld -w or lld -w (if installed globaly)

CLI parameters

  -V, --version                   output the version number
  -r, --remove [option]           Remove Lambda Live Debugger infrastructure. Options: 'keep-layer' (default),
                                  'remove-all'
  -w, --wizard                    Program interactivly ask for each parameter
  -v, --verbose                   Verbose logs
  -c, --context <context>         AWS CDK context (default: [])
  -s, --stage <stage>             Serverless Framework stage
  -f, --function <function name>  Filter by function name
  -m, --subfolder <subfolder>     Monorepo subfolder
  -o, --observable                Observable mode
  -i --interval <interval>        Observable mode interval (default: "3000")
  --config-env <evironment>       SAM environment
  --profile <profile>             AWS profile to use
  --region <region>               AWS region to use
  --role <role>                   AWS role to use
  --framework <framework>         Framework to use (cdk, sls, sam, terraform)
  --gitignore                     Add .lldebugger to .gitignore
  -h, --help                      display help for command

Debugging

You might want to configure you development tool for debugging. The wizard avutomaticaly copnfiguration for VsCode in .vscode/launch.json. Here is an example:

{
  "version": "0.2.0",
  "configurations": [

    {
      "name": "Lambda Live Debugger",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/lld",
      "runtimeArgs": [],
      "console": "integratedTerminal",
      "skipFiles": [
        "<node_internals>/**"
      ],
      "env": {}
    },
  ]
}

If you are using another tool, please send me documantation so I can include it here. Especialy the instructions for WebStorm is needed.

Monorepo

If your framework is one of the subfolders, set the `subfolder˙ setting.

Custom configuraiton

getLambdas: async (foundLambdas) => { //you can customize the list of lambdas here or create your own //return foundLambdas; },

Removing

You can remove Lambda Live Debugger from your AWS account by running: lld -r (npx lld -r if installed locally)

This will deatach Layer from your Lambda and remove the addtional IoT permission policy.

It will not remove the Layer as other might use it. You can everythign incliudng layer with: lld -r=all (npx lld -r=all if installed locally)

AWS CDK v2

context is an additional setting for CDK. This a common way to pass varius variables to your code, most often the enviroment name.

Serverless Framework v3 (SLS)

stage is an additional setting for SLS to pass the stage/enviroment name to SLS.

AWS Serverless Application Model (SAM)

config-env is an additional setting for SAM to pass the stage/enviroment name to SLS.

Terraform

Only the most bacis setup for Terraform is supported. Check the test case in.

I am not a Terraform developer, so I only know basis. Please provide a project sample so I can build a better support.

Know issues

Missing features

Please check the open issues.

The most importan missing feature is MFA authentication and more possible configuration for Terraform.

Reporting an issue

• Make sure the bug is not already reported. Add +1 comment so I know there are multiple users strugling with the same issue. If possible add some additiona info.
• Make a descriptive title with prefix "bug:", "help:", "feature:", "discussion:" to indicate if you find a bug, need help, propose feature... Please also add the matching label and if needed set priorit via label.
• Turn on verbose logging and provide whole log.
• Cerfully descript your setup, or even better provide a sample project.

Authors:

• Marko (ServerlessLife)
• ⭐⭐⭐ place for you for large code contibution ⭐⭐⭐

Contributors (alphabetical)

• ⭐⭐⭐ place for you for smaller code/docuemntaiton contibution or sample project as a part of bug report ⭐⭐⭐

Declarment

Use this tool at your reposiblity ...