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,79 @@
+{
+  "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}",
+        "--pool",
+        "threads",
+        "--poolOptions.threads.singleThread"
+      ],
+      "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",