From 992fdd452e4053977945cb15a820afa82595461e Mon Sep 17 00:00:00 2001
From: Julien <jeluard@users.noreply.github.com>
Date: Wed, 22 May 2024 02:21:03 -0700
Subject: [PATCH] docs: added debugging section (#6743)

* docs: added debugging section

* chore: spell checks

* chore: added extra docs

* chore: address comments

* chore: added extra configuration

* chore: updated docs

* chore: added extra configuration

* chore: fix lint

* chore: fix typos

* chore: .gitignore

* chore: address comments

* chore: address comments
---
 .gitignore                    |  4 +-
 .vscode/README.md             |  2 +
 .vscode/launch.template.json  | 79 +++++++++++++++++++++++++++++++++++
 docs/pages/tools/debugging.md | 19 +++++++++
 docs/sidebars.ts              |  2 +-
 5 files changed, 104 insertions(+), 2 deletions(-)
 create mode 100644 .vscode/README.md
 create mode 100644 .vscode/launch.template.json

diff --git a/.gitignore b/.gitignore
index 775f46f6f235..a6d12b02445b 100644
--- a/.gitignore
+++ b/.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*
diff --git a/.vscode/README.md b/.vscode/README.md
new file mode 100644
index 000000000000..0e7781ad11b1
--- /dev/null
+++ b/.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.
diff --git a/.vscode/launch.template.json b/.vscode/launch.template.json
new file mode 100644
index 000000000000..7f8c7a70484c
--- /dev/null
+++ b/.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"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/docs/pages/tools/debugging.md b/docs/pages/tools/debugging.md
index e69de29bb2d1..ab884dd1b5e5 100644
--- a/docs/pages/tools/debugging.md
+++ b/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.
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
index 068325d946f1..c33dd65c3d0b 100644
--- a/docs/sidebars.ts
+++ b/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",