lambda-live-debugger 0.0.90 → 0.0.92
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CNAME +1 -0
- package/README.md +134 -90
- package/_config.yml +1 -0
- package/architecture.drawio.png +0 -0
- package/dist/extension/extension.zip +0 -0
- package/package.json +1 -1
package/CNAME
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
www.lldebugger.com
|
package/README.md
CHANGED
|
@@ -2,111 +2,137 @@
|
|
|
2
2
|
|
|
3
3
|
|
|
4
4
|
|
|
5
|
-
Lambda Live Debugger is indispensable tool
|
|
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.
|
|
6
6
|
|
|
7
|
-
|
|
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.
|
|
8
|
+
|
|
9
|
+
It supports the following frameworks:
|
|
8
10
|
|
|
9
11
|
- AWS CDK v2
|
|
10
12
|
- Serverless Framework v3 (SLS)
|
|
11
13
|
- AWS Serverless Application Model (SAM)
|
|
12
14
|
- Terraform
|
|
13
|
-
-
|
|
14
|
-
- ... (
|
|
15
|
+
- Any other framework or setup by implementing a simple function in TypeScript
|
|
16
|
+
- ... (Need support for another framework? Let me know!)
|
|
15
17
|
|
|
16
|
-
## Early
|
|
18
|
+
## Early Alpha State
|
|
17
19
|
|
|
18
|
-
**
|
|
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.**
|
|
19
21
|
|
|
20
|
-
|
|
22
|
+
Contact me via:
|
|
21
23
|
|
|
22
|
-
- [
|
|
24
|
+
- [GitHub Issues](https://github.com/ServerlessLife/lambda-live-debugger/issues)
|
|
23
25
|
- [LinkedIn](http://www.linkedin.com/in/marko-serverlesslife)
|
|
24
26
|
|
|
25
|
-
## The
|
|
26
|
-
|
|
27
|
-
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.
|
|
27
|
+
## The Problem Statement
|
|
28
28
|
|
|
29
|
-
|
|
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.
|
|
30
30
|
|
|
31
|
-
## How
|
|
31
|
+
## How It Works
|
|
32
32
|
|
|
33
|
-
|
|
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.
|
|
34
34
|
|
|
35
|
-
|
|
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.
|
|
36
36
|
|
|
37
37
|
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
### Infrastructure Changes
|
|
40
40
|
|
|
41
|
-
|
|
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:
|
|
44
42
|
|
|
45
|
-
|
|
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
|
|
46
46
|
|
|
47
|
-
|
|
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.
|
|
48
48
|
|
|
49
|
-
|
|
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.
|
|
50
50
|
|
|
51
|
-
|
|
51
|
+
## Development Process
|
|
52
52
|
|
|
53
|
-
|
|
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.
|
|
54
54
|
|
|
55
55
|
## Observability Mode
|
|
56
56
|
|
|
57
|
-
In Observability Mode Lambda Live Debugger
|
|
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.
|
|
58
58
|
|
|
59
|
-
##
|
|
59
|
+
## Getting Started
|
|
60
60
|
|
|
61
61
|
### Installation
|
|
62
62
|
|
|
63
|
-
Install
|
|
64
|
-
`npm install lambda-live-debugger`
|
|
65
|
-
or globaly
|
|
66
|
-
`npm install lambda-live-debugger -g` (Linux, Mac: `sudo npm install lambda-live-debugger -g`)
|
|
63
|
+
Install locally:
|
|
67
64
|
|
|
68
|
-
|
|
65
|
+
```
|
|
66
|
+
npm install lambda-live-debugger
|
|
67
|
+
```
|
|
69
68
|
|
|
70
|
-
|
|
69
|
+
or globally
|
|
71
70
|
|
|
72
|
-
|
|
71
|
+
```
|
|
72
|
+
npm install lambda-live-debugger -g
|
|
73
|
+
```
|
|
73
74
|
|
|
74
|
-
|
|
75
|
+
(On Linux and Mac: `sudo npm install lambda-live-debugger -g`)
|
|
75
76
|
|
|
76
|
-
|
|
77
|
+
Running the Tool
|
|
77
78
|
|
|
78
|
-
|
|
79
|
+
With default profile, region, and other default settings:
|
|
79
80
|
|
|
80
81
|
```
|
|
81
|
-
|
|
82
|
-
-r, --remove [option] Remove Lambda Live Debugger infrastructure. Options: 'keep-layer' (default),
|
|
83
|
-
'remove-all'
|
|
84
|
-
-w, --wizard Program interactivly ask for each parameter
|
|
85
|
-
-v, --verbose Verbose logs
|
|
86
|
-
-c, --context <context> AWS CDK context (default: [])
|
|
87
|
-
-s, --stage <stage> Serverless Framework stage
|
|
88
|
-
-f, --function <function name> Filter by function name
|
|
89
|
-
-m, --subfolder <subfolder> Monorepo subfolder
|
|
90
|
-
-o, --observable Observable mode
|
|
91
|
-
-i --interval <interval> Observable mode interval (default: "3000")
|
|
92
|
-
--config-env <evironment> SAM environment
|
|
93
|
-
--profile <profile> AWS profile to use
|
|
94
|
-
--region <region> AWS region to use
|
|
95
|
-
--role <role> AWS role to use
|
|
96
|
-
--framework <framework> Framework to use (cdk, sls, sam, terraform)
|
|
97
|
-
--gitignore Add .lldebugger to .gitignore
|
|
98
|
-
-h, --help display help for command
|
|
82
|
+
lld
|
|
99
83
|
```
|
|
100
84
|
|
|
101
|
-
|
|
85
|
+
or if installed locally:
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
npx lld
|
|
89
|
+
```
|
|
102
90
|
|
|
103
|
-
|
|
91
|
+
But you probably need to tweak some settings. You can do it via CLI parameters or, better run a wizard:
|
|
104
92
|
|
|
105
93
|
```
|
|
94
|
+
lld -w
|
|
95
|
+
```
|
|
96
|
+
|
|
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
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
-V, --version output the version number
|
|
109
|
+
-r, --remove [option] Remove Lambda Live Debugger infrastructure. Options: 'keep-layer' (default),
|
|
110
|
+
'remove-all'
|
|
111
|
+
-w, --wizard Program interactively asks for each parameter
|
|
112
|
+
-v, --verbose Verbose logs
|
|
113
|
+
-c, --context <context> AWS CDK context (default: [])
|
|
114
|
+
-s, --stage <stage> Serverless Framework stage
|
|
115
|
+
-f, --function <function name> Filter by function name
|
|
116
|
+
-m, --subfolder <subfolder> Monorepo subfolder
|
|
117
|
+
-o, --observable Observable mode
|
|
118
|
+
-i --interval <interval> Observable mode interval (default: "3000")
|
|
119
|
+
--config-env <evironment> SAM environment
|
|
120
|
+
--profile <profile> AWS profile to use
|
|
121
|
+
--region <region> AWS region to use
|
|
122
|
+
--role <role> AWS role to use
|
|
123
|
+
--framework <framework> Framework to use (cdk, sls, sam, terraform)
|
|
124
|
+
--gitignore Add .lldebugger to .gitignore
|
|
125
|
+
-h, --help display help for command
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Debugging
|
|
129
|
+
|
|
130
|
+
You might want to configure your development tool for debugging. The wizard automatically configures for VsCode in `.vscode/launch.json`. Here is an example:
|
|
131
|
+
|
|
132
|
+
```json
|
|
106
133
|
{
|
|
107
134
|
"version": "0.2.0",
|
|
108
135
|
"configurations": [
|
|
109
|
-
|
|
110
136
|
{
|
|
111
137
|
"name": "Lambda Live Debugger",
|
|
112
138
|
"type": "node",
|
|
@@ -114,22 +140,20 @@ You might want to configure you development tool for debugging. The wizard avuto
|
|
|
114
140
|
"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/lld",
|
|
115
141
|
"runtimeArgs": [],
|
|
116
142
|
"console": "integratedTerminal",
|
|
117
|
-
"skipFiles": [
|
|
118
|
-
"<node_internals>/**"
|
|
119
|
-
],
|
|
143
|
+
"skipFiles": ["<node_internals>/**"],
|
|
120
144
|
"env": {}
|
|
121
|
-
}
|
|
145
|
+
}
|
|
122
146
|
]
|
|
123
147
|
}
|
|
124
148
|
```
|
|
125
149
|
|
|
126
|
-
|
|
150
|
+
For other tools, please send documentation to include here. WebStorm instructions are especially needed.
|
|
127
151
|
|
|
128
|
-
|
|
152
|
+
## Monorepo Setup
|
|
129
153
|
|
|
130
|
-
If your framework is
|
|
154
|
+
If your framework is in a subfolder, set the `subfolder` parameter.
|
|
131
155
|
|
|
132
|
-
## Custom
|
|
156
|
+
## Custom Configuration
|
|
133
157
|
|
|
134
158
|
getLambdas: async (foundLambdas) => {
|
|
135
159
|
//you can customize the list of lambdas here or create your own
|
|
@@ -138,56 +162,76 @@ getLambdas: async (foundLambdas) => {
|
|
|
138
162
|
|
|
139
163
|
## Removing
|
|
140
164
|
|
|
141
|
-
|
|
142
|
-
|
|
165
|
+
To remove Lambda Live Debugger from your AWS account
|
|
166
|
+
|
|
167
|
+
```
|
|
168
|
+
lld -r
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
or if installed locally:
|
|
172
|
+
|
|
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:
|
|
143
186
|
|
|
144
|
-
|
|
187
|
+
```
|
|
188
|
+
npx lld -r=all
|
|
189
|
+
```
|
|
145
190
|
|
|
146
|
-
|
|
147
|
-
`lld -r=all` (`npx lld -r=all` if installed locally)
|
|
191
|
+
## Framework-Specific Notes
|
|
148
192
|
|
|
149
|
-
|
|
193
|
+
### AWS CDK v2
|
|
150
194
|
|
|
151
|
-
`context`
|
|
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.
|
|
152
196
|
|
|
153
|
-
|
|
197
|
+
### Serverless Framework v3 (SLS)
|
|
154
198
|
|
|
155
|
-
`stage`
|
|
199
|
+
Use the `stage` parameter to pass the stage/environment name.
|
|
156
200
|
|
|
157
|
-
|
|
201
|
+
### AWS Serverless Application Model (SAM)
|
|
158
202
|
|
|
159
|
-
`config-env`
|
|
203
|
+
Use the `config-env` parameter to pass the stage/environment name.
|
|
160
204
|
|
|
161
|
-
|
|
205
|
+
### Terraform
|
|
162
206
|
|
|
163
|
-
Only the
|
|
207
|
+
Only the basic setup is supported. Check the [test case](https://github.com/ServerlessLife/lambda-live-debugger/tree/main/test/terraform-basic).
|
|
164
208
|
|
|
165
|
-
I am not a Terraform developer, so I only know
|
|
209
|
+
I am not a Terraform developer, so I only know the basics. Please provide a sample project so I can build better support.
|
|
166
210
|
|
|
167
211
|
## Know issues
|
|
168
212
|
|
|
169
|
-
|
|
213
|
+
...
|
|
170
214
|
|
|
171
|
-
|
|
215
|
+
## Missing Features
|
|
172
216
|
|
|
173
|
-
The
|
|
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.
|
|
174
218
|
|
|
175
|
-
## Reporting an
|
|
219
|
+
## Reporting an Issue
|
|
176
220
|
|
|
177
|
-
- Make sure the bug
|
|
178
|
-
-
|
|
179
|
-
-
|
|
180
|
-
-
|
|
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.
|
|
181
225
|
|
|
182
226
|
## Authors:
|
|
183
227
|
|
|
184
228
|
- [Marko (ServerlessLife)](https://github.com/ServerlessLife)
|
|
185
|
-
-
|
|
229
|
+
- ⭐ Your name here for big code contributions
|
|
186
230
|
|
|
187
231
|
## Contributors (alphabetical)
|
|
188
232
|
|
|
189
|
-
-
|
|
233
|
+
- ⭐ Your name here for smaller code/documentation contributions or sample projects as part of bug reports
|
|
190
234
|
|
|
191
235
|
## Declarment
|
|
192
236
|
|
|
193
|
-
Use
|
|
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.
|
package/_config.yml
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
theme: jekyll-theme-primer
|
package/architecture.drawio.png
CHANGED
|
Binary file
|
|
Binary file
|