Skip to content

Commit 284f464

Browse files
ServerlessLifeServerlessLife
committed
fix: Improve documentation
1 parent 8d3b425 commit 284f464

File tree

2 files changed

+126
-82
lines changed

2 files changed

+126
-82
lines changed

‎README.md

Lines changed: 126 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -2,80 +2,107 @@
22

33
![Logo](logo.png)
44

5-
Lambda Live Debugger is an indispensable tool that allows you to debug AWS Lambda from your computer, although it is deployed on the cloud. It supports Lambdas written in JavaScript or TypeScript.
5+
Lambda Live Debugger 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.
66

7-
This is essentially the same as offered by [SST](https://sst.dev/) and [Serverless Framework v4](https://www.serverless.com/blog/serverless-framework-v4-general-availability), except it supports an additional Obserability mode.
7+
This tool offers similar functionality to [SST](https://sst.dev/) and [Serverless Framework v4](https://www.serverless.com/blog/serverless-framework-v4-general-availability), with the addition of an Observability mode.
88

99
It supports the following frameworks:
1010

11-
- AWS CDK v2,
12-
- Serverless Framework v3 (SLS),
13-
- AWS Serverless Application Model (SAM),
14-
- Terraform,
15-
- by implementing a simple function and option to support any framework or setup you might have,
16-
- ... (if you need any other framework, let me know?)
11+
- AWS CDK v2
12+
- Serverless Framework v3 (SLS)
13+
- AWS Serverless Application Model (SAM)
14+
- Terraform
15+
- Any other framework or setup by implementing a simple function in TypeScript
16+
- ... (Need support for another framework? Let me know!)
1717

18-
## Early alpha state
18+
## Early Alpha State
1919

20-
**Currently, the project is in the early alpha state. Please let me know if everything works for you. A simple message would help a lot, so I know I am on the right track. I tested many scenarios, but there are numerous ways how people can configure projects and TypeScript configuration. The tool is flexible enough, so the settings can be tweaked to adjust your setup without implementing additional features. Any advice on how to improve the project is also very welcome.**
20+
**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 there are numerous ways people configure their projects and TypeScript settings. The tool is flexible and can be adjusted to fit your setup in most cases without needing additional features. If you got stuck, please let me know. Any suggestions for improvements are welcome.**
2121

22-
You can contact me by:
22+
Contact me via:
2323

24-
- [Open GitHub issue](https://github.com/ServerlessLife/lambda-live-debugger/issues)
24+
- [GitHub Issues](https://github.com/ServerlessLife/lambda-live-debugger/issues)
2525
- [LinkedIn](http://www.linkedin.com/in/marko-serverlesslife)
2626

27-
## The problem statement
27+
## The Problem Statement
2828

29-
The serverless is amazing and resolves many issues that regular systems face. But writing code can be a struggle. You write code, deploy, run, fix, deploy again. That process is time-consuming and tiresome. You can also use one of the tools for running code locally or use unit/integration tests for that, but that has many other issues, and it does not mimic an actual environment close enough.
29+
Serverless is amazing and solve many issues with traditional systems. But writing code for Lambda functions can be challenging. The cycle of writing, deploying, running, fixing, and redeploying is time-consuming and tedious. While local testing tools and unit/integration tests exist, they often don't replicate the actual environment closely enough.
3030

31-
## How does it work
31+
## How It Works
3232

33-
It connects to your deployed Lambda, sends the request to your computer, and sends the response back to Lambda. This way, you can debug on your machine, but the system behaves as if the code is running in the cloud with the same permissions.
33+
Lambda Live Debugger connects to your deployed Lambda, routes requests to your computer, and sends responses back to the Lambda. This allows you to debug locally, but the system behaves as if the code is running in the cloud with the same permissions.
3434

35-
Lambda Live Debugger attaches Lambda Extensions (via Layer) to the Lambda to intercept calls and send them to AWS IoT. AWS IoT is used to transfer messages to and from your machine. Lambda Live Debugger runs locally, connects to the AWS IoT, and executes the code locally. If Lambda is written in TypeScript, it is transpiled to JavaScript. Calls are executed via Node Worker Threads.
35+
The tool attaches Lambda Extensions (via a Layer) to intercept calls and relay them to AWS IoT, which 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 Node Worker Threads.
3636

3737
![Architecture](./architecture.drawio.png)
3838

39-
Lambda Live Debugger makes the following changes to your AWS infrastructure:
39+
### Infrastructure Changes
4040

41-
- Lambda excentions as a Layer
42-
- Attach Layer to each Lambda that you are debugging
43-
- Add policy to Lambda Role to use AWS IoT
41+
Lambda Live Debugger makes the following changes to your AWS infrastructure:
4442

45-
In case you do not want to add Layer to all functions, you can limit to the ones you need via configuration parameters.
43+
- Adds Lambda Layer
44+
- Attaches the Layer to each Lambda you're debugging
45+
- Adds a policy to the Lambda Role for AWS IoT access
4646

47-
While compiling, it creates many temporary files in the folder `.lldebugger`; you can freely delete the folder once you are done debugging or add `.lldebugger` to `.gitignore`. The wizard adds that for you if you want.
47+
In case you do not want to debug all functions and add Layer to them, you can limit to the ones you need via `function` parameter.
4848

49-
## Your developing process with Lambda Live Debugger
49+
The tool generates temporary files in the `.lldebugger` folder, which can be deleted after debugging. The wizard can add `.lldebugger` to `.gitignore` for you.
5050

51-
Since you will be deploying code into an actual AWS account while developing, you must use that environment only for yourself or create a temporary environment for you or for a feature you are working on.
51+
## Development Process
5252

53-
Unfortunately, having a separate AWS environment is not always possible because of organizational issues (it is 2024, and companies still do not understand how to work with serverless) or technical issues (it is hard to duplicate databases or other parts of the system). For that purpose, there is an Observability Mode.
53+
Since you deploy code to a real AWS account, it's best to have a dedicated environment only for yourself. It could be your personla environemnt or environment created for a special feature. That is [common practice when developing serverless systems](https://theburningmonk.com/2019/09/why-you-should-use-temporary-stacks-when-you-do-serverless/). If that's not feasible due to organizational or technical reasons, use Observability Mode.
5454

5555
## Observability Mode
5656

57-
In Observability Mode, Lambda Live Debugger via Lambda Extension just intercepts the request received by Lambda and forwards it to the local environment, but it does not wait for the response. After that, Lambda continues regular execution and ignores the response from the local environment. The system is not impacted, and regular users and other developers can continue to use it. You can run Observability Mode on the development or testing environment. If you are an adventurer, you can even run it in production. In observability 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 will not be overloaded if there are a lot of requests coming in.
57+
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 development, testing, or even, if you are an adventures, production environments. It samples requests every 3 seconds by default (configurable with `interval` setting) to avoid overloading the system.
5858

59-
## How to start
59+
## Getting Started
6060

6161
### Installation
6262

6363
Install locally:
64-
`npm install lambda-live-debugger`
64+
65+
```
66+
npm install lambda-live-debugger
67+
```
68+
6569
or globally
66-
`npm install lambda-live-debugger -g` (Linux, Mac: `sudo npm install lambda-live-debugger -g`)
6770

68-
### How to run
71+
```
72+
npm install lambda-live-debugger -g
73+
```
74+
75+
(On Linux and Mac: `sudo npm install lambda-live-debugger -g`)
76+
77+
Running the Tool
6978

70-
If you use the default profile, default region, and other default settings then just run:
79+
With default profile, region, and other default settings:
7180

72-
`lld` or `npx lld` (if installed locally)
81+
```
82+
lld
83+
```
84+
85+
or if installed locally:
86+
87+
```
88+
npx lld
89+
```
7390

74-
But you probably need to tweak some settings. You can do it via CLI parameters or, better run a wizard. The configuration is saved to `lldebugger.config.ts`
91+
But you probably need to tweak some settings. You can do it via CLI parameters or, better run a wizard:
7592

76-
`npx lld -w` or `lld -w` (if installed globally)
93+
```
94+
lld -w
95+
```
7796

78-
### CLI parameters
97+
or if installed locally:
98+
99+
```
100+
npx lld -w
101+
```
102+
103+
The configuration is saved to `lldebugger.config.ts`
104+
105+
### CLI Parameters
79106

80107
```
81108
-V, --version output the version number
@@ -102,34 +129,31 @@ But you probably need to tweak some settings. You can do it via CLI parameters o
102129

103130
You might want to configure your development tool for debugging. The wizard automatically configures for VsCode in `.vscode/launch.json`. Here is an example:
104131

105-
```
132+
```json
106133
{
107-
"version": "0.2.0",
108-
"configurations": [
109-
110-
{
111-
"name": "Lambda Live Debugger",
112-
"type": "node",
113-
"request": "launch",
114-
"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/lld",
115-
"runtimeArgs": [],
116-
"console": "integratedTerminal",
117-
"skipFiles": [
118-
"<node_internals>/**"
119-
],
120-
"env": {}
121-
},
122-
]
134+
"version": "0.2.0",
135+
"configurations": [
136+
{
137+
"name": "Lambda Live Debugger",
138+
"type": "node",
139+
"request": "launch",
140+
"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/lld",
141+
"runtimeArgs": [],
142+
"console": "integratedTerminal",
143+
"skipFiles": ["<node_internals>/**"],
144+
"env": {}
145+
}
146+
]
123147
}
124148
```
125149

126-
If you are using another tool, please send me documentation so I can include it here. Especially the instruction for WebStorm is needed.
150+
For other tools, please send documentation to include here. WebStorm instructions are especially needed.
127151

128-
### Monorepo
152+
## Monorepo Setup
129153

130-
If your framework is one of the subfolders, set the `subfolder˙ setting.
154+
If your framework is in a subfolder, set the `subfolder` parameter.
131155

132-
## Custom configuraiton
156+
## Custom Configuration
133157

134158
getLambdas: async (foundLambdas) => {
135159
//you can customize the list of lambdas here or create your own
@@ -138,56 +162,76 @@ getLambdas: async (foundLambdas) => {
138162

139163
## Removing
140164

141-
You can remove Lambda Live Debugger from your AWS account by running:
142-
`lld -r` (`npx lld -r` if installed locally)
165+
To remove Lambda Live Debugger from your AWS account
166+
167+
```
168+
lld -r
169+
```
170+
171+
or if installed locally:
143172

144-
This will detach the Layer from your Lambda and remove the additional IoT permission policy.
173+
```
174+
npx lld -r
175+
```
176+
177+
This detaches the Layer from your Lambdas and removes the IoT permission policy. It will not remove the Layer as others might use it.
178+
179+
To also remove the Layer:
180+
181+
```
182+
lld -r=all
183+
```
184+
185+
or if installed locally:
186+
187+
```
188+
npx lld -r=all
189+
```
145190

146-
It will not remove the Layer as others might use it. You can do everything, including Layer, with:
147-
`lld -r=all` (`npx lld -r=all` if installed locally)
191+
## Framework-Specific Notes
148192

149-
## AWS CDK v2
193+
### AWS CDK v2
150194

151-
`context` is an additional setting for CDK. This is a common way to pass various variables to your code, most often the environment name.
195+
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.
152196

153-
## Serverless Framework v3 (SLS)
197+
### Serverless Framework v3 (SLS)
154198

155-
`stage` is an additional setting for SLS to pass the stage/environment name to SLS.
199+
Use the `stage` parameter to pass the stage/environment name.
156200

157-
## AWS Serverless Application Model (SAM)
201+
### AWS Serverless Application Model (SAM)
158202

159-
`config-env` is an additional setting for SAM to pass the stage/environment name to SLS.
203+
Use the `config-env` parameter to pass the stage/environment name.
160204

161-
## Terraform
205+
### Terraform
162206

163-
Only the most basic setup for Terraform is supported. Check the test case [in](https://github.com/ServerlessLife/lambda-live-debugger/tree/main/test/terraform-basic).
207+
Only the basic setup is supported. Check the [test case](https://github.com/ServerlessLife/lambda-live-debugger/tree/main/test/terraform-basic).
164208

165-
I am not a Terraform developer, so I only know the basics. Please provide a project sample so I can build better support.
209+
I am not a Terraform developer, so I only know the basics. Please provide a sample project so I can build better support.
166210

167211
## Know issues
168212

169-
## Missing features
213+
...
170214

171-
Please check the open [issues](https://github.com/ServerlessLife/lambda-live-debugger/issues).
215+
## Missing Features
172216

173-
The most important missing feature is MFA authentication and the most possible configuration for Terraform.
217+
Check the [open issues](https://github.com/ServerlessLife/lambda-live-debugger/issues). The biggest missing feature right now is MFA authentication and more Terraform configurations.
174218

175-
## Reporting an issue
219+
## Reporting an Issue
176220

177-
- Make sure the bug is not already reported. Add +1 comment so I know there are multiple users struggling with the same issue. If possible, add some additional info.
178-
- Make a descriptive title with the prefix "bug:", "help:", "feature:", "discussion:" to indicate if you find a bug, need help, propose a feature... Please also add the matching label and, if needed, set priority via label.
179-
- Turn on verbose logging and provide the whole log.
180-
- Carefully describe your setup, or even better, provide a sample project.
221+
- Make sure the bug isn't already reported. Add a "+1" comment so I know there are multiple users struggling with the same issue. If possible, add some additional info.
222+
- Use descriptive titles with prefixes like "bug:", "help:", "feature:", or "discussion:". Please also add the matching label and, if needed, set priority via label.
223+
- Enable verbose logging and provide the full log.
224+
- Describe your setup in detail, or better yet, provide a sample project.
181225

182226
## Authors:
183227

184228
- [Marko (ServerlessLife)](https://github.com/ServerlessLife)
185-
- ⭐ place for you for large code contribution
229+
- ⭐ Your name here for big code contributions
186230

187231
## Contributors (alphabetical)
188232

189-
- ⭐ place for you for smaller code/documentation contributions or a sample project as a part of a bug report
233+
- ⭐ Your name here for smaller code/documentation contributions or sample projects as part of bug reports
190234

191235
## Declarment
192236

193-
Use this tool at your responsibility...
237+
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.

‎architecture.drawio.png

1.15 KB
Loading

0 commit comments

Comments
 (0)