docs: added debugging section

.gitignore

@@ -25,8 +25,10 @@ validators
 **/dist
 **/.nyc_output
 .tmp
-.vscode
 .npmrc
+.vscode/launch.json
+.vscode/settings.json
+.vscode/tasks.json
 
 # Tests artifacts
 packages/*/spec-tests*

.vscode/README.md

@@ -0,0 +1,2 @@
+Adapt to your needs `launch.template.json` and copy as `launch.json`.
+Follow `docs/pages/tools/debugging.md` for more details.

.vscode/launch.template.json

@@ -0,0 +1,59 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+      {
+        "type": "node",
+        "name": "Attach",
+        "port": 9229,
+        "request": "attach",
+        "skipFiles": ["<node_internals>/**"]
+      },
+      {
+        "type": "node",
+        "request": "launch",
+        "name": "Beacon",
+        "skipFiles": ["<node_internals>/**"],
+        "smartStep": true,
+        "program": "${workspaceFolder}/packages/cli/bin/lodestar.js",
+        "args": ["beacon"],
+        "console": "integratedTerminal"
+      },
+      {
+        "type": "node",
+        "request": "launch",
+        "name": "Dev",
+        "skipFiles": ["<node_internals>/**"],
+        "smartStep": true,
+        "program": "${workspaceFolder}/packages/cli/bin/lodestar.js",
+        "args": ["dev"],
+        "console": "integratedTerminal"
+      },
+      {
+        "name": "Test Current File",
+        "type": "node",
+        "request": "launch",
+        "program": "${workspaceFolder}/node_modules/.bin/vitest",
+        "args": ["--run", "${file}", "-t", "${input:testName}"],
+        "cwd": "${workspaceFolder}/${input:packageName}",
+        "console": "integratedTerminal",
+        "skipFiles": ["<node_internals>/**"]
+      }
+    ],
+    "inputs": [
+      {
+        "id": "packageName",
+        "type": "command",
+        "command": "extension.commandvariable.transform",
+        "args": {
+          "text": "${relativeFileDirname}",
+          "find": "^(packages/[^/]+).*",
+          "replace": "$1"
+        }
+      },
+      {
+        "id": "testName",
+        "type": "promptString",
+        "description": "Enter the test name to run, leave empty to run all"
+      }
+    ]
+  }

docs/pages/tools/debugging.md

@@ -0,0 +1,19 @@
+---
+title: Debugging
+---
+
+The simplest way to debug is to use the provided [launch.template.json](https://github.com/ChainSafe/lodestar/blob/unstable/.vscode/launch.template.json) `configurations`. Adapt and copy them as `.vscode/launch.json`, and they will be made available in the `Run and Debug` section. Note that users probably want to adapt the arguments of the beacon [configuration](https://github.com/ChainSafe/lodestar/blob/unstable/.vscode/launch.json#L11) to match their needs.
+VS Code supports debugging Workers out of the box when using those configurations.
+
+Remote `lodestar` processes can also be debugged by leveraging [node:inspector](https://nodejs.org/api/inspector.html). Adding `--inspect` to the node CLI (e.g. `NODE_OPTIONS=--inspect ./lodestar beacon`) allows to debug the main thread. To debug a specific `Worker`, follow those steps:
+
+- remove `--inspect` from `node` CLI
+- add following code to the `worker`
+
+```js
+import inspector from "node:inspector";
+inspector.open();
+inspector.waitForDebugger();
+```
+
+Use VS Code or Chrome devtools to debug those processes.

docs/sidebars.ts

@@ -94,7 +94,7 @@ const sidebars: SidebarsConfig = {
     {
       type: "category",
       label: "Tools",
-      items: ["tools/flamegraphs", "tools/heap-dumps", "tools/core-dumps"],
+      items: ["tools/debugging", "tools/flamegraphs", "tools/heap-dumps", "tools/core-dumps"],
     },
     {
       type: "category",