lambda-live-debugger
Advanced tools
Lambda Live Debugger (GitHub) is an indispensable tool for debugging AWS Lambda functions from your computer, even though they are deployed in the cloud. It supports Lambdas written in JavaScript or TypeScript.
This tool offers similar functionality to SST and Serverless Framework v4, with the addition of an Observability Mode.
It supports the following frameworks:
This project is in the early alpha stage. Your feedback is incredibly valuable. Please let me know if it works for you or if you encounter any issues. I've tested many scenarios, but people can configure their projects and TypeScript settings in numerous ways. The tool is flexible and can be adjusted to fit your setup in most cases without needing additional features. If you need help, please let me know. Any suggestions for improvements are welcome.
If the tool is working well for you, please fill out the general FEEDBACK FORM. This helps me understand how extensively the tool has been tested and whether there is a general interest in its further development.
If you've encountered a bug, need help, or would like to request additional features, please create an issue on GitHub Issue.
Contact me via:
Also, check out my blog: www.serverlesslife.com and follow me on X (Twitter).
Serverless is amazing and solves many issues with traditional systems. However, writing code for Lambda functions can be challenging. The cycle of writing, deploying, running, fixing, and redeploying is time-consuming and tedious. You could use tools to run Lambda locally or use unit/integration tests; those approaches often don't replicate the actual environment closely enough.
Lambda Live Debugger connects to your deployed Lambda, routes requests to your computer, and sends responses back to the deployed Lambda. This allows you to debug locally, but the system behaves as if the code is running in the cloud with the same permissions. In case of code changes, you do not have to redeploy. The code is reloaded automatically without deploying or even restarting the debugger.
The tool attaches Lambda Extensions (via a Layer), intercepts, and relays calls to AWS IoT. AWS IoT transfers messages between your Lambda and local machine. If the Lambda is written in TypeScript, it's transpiled to JavaScript. The code is executed via the Node Worker Thread.
AWS keys generated on the cloud for Lambda are transferred to the local environment, so the code has the same permissions as it would executed on the cloud. There could be a difference in packaging, mainly regarding static files, which are probably in different locations. You can use additional environment variables to adjust the code:
IS_LOCAL = true = Lambda is executed locallyLOCAL_PROJECT_DIR = directory of the projectLambda Live Debugger makes the following changes to your AWS infrastructure:
In case you do not want to debug all functions and add Layer to them, you can limit to the ones you need via the function parameter.
The tool generates temporary files in the .lldebugger folder, which can be deleted after debugging. The wizard can add .lldebugger to .gitignore for you.
Since you deploy code to a real AWS account, it's best to have a dedicated environment only for yourself. It could be your personal environment or an environment created for a feature. That is common practice when developing serverless systems. If that's not feasible due to organizational or technical reasons, use Observability Mode.
In Observability Mode, Lambda Live Debugger intercepts requests and sends them to your computer without waiting for a response. The Lambda continues as usual. The response from your machine is ignored. This mode can be used in the development, testing, or even, if you are an adventurous, production environment. It samples requests every 3 seconds by default (configurable with an interval setting) to avoid overloading the system.
Install globally:
npm install lambda-live-debugger -g
(On Linux and Mac: sudo npm install lambda-live-debugger -g)
or locally
npm install lambda-live-debugger
(If installed locally, you must prefix all commands with npx, if they are not part of scripts in package.json.)
With default profile, region, and other default settings:
lld
You probably need to tweak some settings. You can do it via CLI parameters or, better, run the wizard:
lld -w
The configuration is saved to lldebugger.config.ts.
-V, --version output the version number
-r, --remove [option] Remove Lambda Live Debugger infrastructure. Options: 'keep-layer' (default), 'remove-all'. The latest also removes the Lambda Layer
-w, --wizard Program interactively asks for each parameter and saves it to lldebugger.config.ts
-v, --verbose Verbose logging
-c, --context <context> AWS CDK context (default: [])
-s, --stage <stage> Serverless Framework stage
-f, --function <function name> Filter by function name. You can use * as a wildcard
-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
Example lldebugger.config.ts:
import { type LldConfigTs } from 'lambda-live-debugger';
export default {
framework: 'cdk',
context: ['environment=development'],
region: 'eu-central-1',
observable: false,
verbose: false,
//getLambdas: async (foundLambdas) => {
// you can customize the list of Lambdas here or create your own
// return foundLambdas;
//},
} satisfies LldConfigTs;
The setting are the same as for CLI parameters.
You might want to configure your development tool for debugging. The wizard automatically configures 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": {}
}
]
}
Now, you have to press F5 or press Run -> Start Debugging, and you can set breakpoints, step through lines of code, inspect variables... For more information on how to debug in VSCode, please refer to this link.
For other tools, please send documentation to include here. WebStorm instructions are especially needed.
Set the subfolder parameter if your framework is in a subfolder.
To remove Lambda Live Debugger from your AWS account
lld -r
This detaches the Layer from your Lambdas and removes the IoT permission policy. It will not remove the Layer as others might use it.
To also remove the Layer:
lld -r=all
Use the context parameter to pass context to your CDK code. This is a common way to pass variables to your code, most often the environment name.
Use the stage parameter to pass the stage/environment name.
Use the config-env parameter to pass the stage/environment name.
Only the basic setup is supported. Check the test case.
I am not a Terraform developer, so I only know the basics. Please provide a sample project so I can build better support.
Configuration file lldebugger.config.ts enables you to modify the list of Lambdas, change the code path, esBuild configuration, or provide your own list of Lambdas, thereby supporting support any framework. For this to work, install Lambda Live Debugger locally in the project.
getLambdas: async (foundLambdas, config) => {
//you can customize the list of Lambdas here or create your own
return foundLambdas;
};
Filter list of functions:
getLambdas: async (foundLambdas, config) => {
return foundLambdas?.filter((l) => l.functionName.includes('myfunction'));
};
Modify code path:
For example, when the framework has only a list of JavaScript files, but you transpiled them from TypeScript with your own solution.
getLambdas: async (foundLambdas, config) => {
if (foundLambdas) {
for (const lambda of foundLambdas) {
lambda.codePath = lambda.codePath
.replace('/dist/', '/src/')
.replace('.js', '.ts');
}
}
};
Modify esBuild configuration:
import { type EsBuildOptions, type LldConfigTs } from "lambda-live-debugger";
export default {
...
getLambdas: async (foundLambdas, config) => {
if (foundLambdas) {
for (const lambda of foundLambdas) {
lambda.esBuildOptions = {
target: "node14",
};
}
}
}
} satisfies LldConfigTs;
Provide your own list of Lambdas and support any framework:
export default {
//framework: <-- you do not need this line
...
getLambdas: async (foundLambdas, config) => {
return [
{
// function name as deployed on AWS
functionName: "mystack-myfunction",
codePath: "/src/myLambda.ts",
},
];
},
} satisfies LldConfigTs;
Modify existing framework support:
import { CdkFramework, type LldConfigBase, type LldConfigTs } from "lambda-live-debugger";
class MyCdkFramework extends CdkFramework {
override getCdkContext(cdkConfigPath: string, config: LldConfigBase) {
// your implementation
}
}
export default {
...
getLambdas: async (foundLambdas, config) => {
return new MyCdkFramework().getLambdas(config);
}
} satisfies LldConfigTs;s
Check the GitHub issues.
For the current list of missing features, please refer to the GitHub issues page. The most significant missing features at the moment are MFA authentication and additional Terraform configurations.
If you have a new feature idea, please create and issue.
Lambda Live Debugger is provided "as is", without warranty of any kind, express or implied. Use it at your own risk, and be mindful of potential impacts on performance, security, and costs when using it in your AWS environment.
FAQs
Debug Lambda functions locally like it is running in the cloud
The npm package lambda-live-debugger receives a total of 819 weekly downloads. As such, lambda-live-debugger popularity was classified as not popular.
We found that lambda-live-debugger demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Malicious PyPI checkers validate stolen emails against TikTok and Instagram APIs, enabling targeted account attacks and dark web credential sales.
Security News
The Node.js TSC opted not to endorse a feature bounty program, citing concerns about incentives, governance, and project neutrality.
Research
Security News
A look at the top trends in how threat actors are weaponizing open source packages to deliver malware and persist across the software supply chain.