From 5df6ead45a0ab9b4ee7b9138070fa50e4e26dcbb Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <aramiss@spotify.com>
Date: Mon, 20 Nov 2023 12:43:52 -0500
Subject: [PATCH] Add docs for how to debug.

Signed-off-by: Aramis Sennyey <aramiss@spotify.com>
---
 docs/local-dev/cli-build-system.md | 25 ++++++++++++++++---------
 docs/local-dev/debugging.md        | 29 +++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 9 deletions(-)

diff --git a/docs/local-dev/cli-build-system.md b/docs/local-dev/cli-build-system.md
index 7bb4918d47..6ee583efd8 100644
--- a/docs/local-dev/cli-build-system.md
+++ b/docs/local-dev/cli-build-system.md
@@ -592,19 +592,26 @@ A complete launch configuration for VS Code debugging may look like this:
 ```json
 {
   "type": "node",
-  "name": "vscode-jest-tests",
+  "name": "vscode-jest-tests.v2",
   "request": "launch",
+  "env": {
+    // Needed to disable watch by default mode.
+    "ENV": "CI"
+  },
+  "args": [
+    "repo",
+    "test",
+    "--runInBand",
+    "--watchAll=false",
+    "--testNamePattern",
+    "${jest.testNamePattern}",
+    "--runTestsByPath",
+    "${jest.testFile}"
+  ],
   "console": "integratedTerminal",
   "internalConsoleOptions": "neverOpen",
   "disableOptimisticBPs": true,
-  "program": "${workspaceFolder}/node_modules/.bin/jest",
-  "cwd": "${workspaceFolder}",
-  "args": [
-    "--config",
-    "node_modules/@backstage/cli/config/jest.js",
-    "--runInBand",
-    "--watchAll=false"
-  ]
+  "program": "${workspaceFolder}/node_modules/.bin/backstage-cli"
 }
 ```
 
diff --git a/docs/local-dev/debugging.md b/docs/local-dev/debugging.md
index d2a4d02db0..f0a3ffc528 100644
--- a/docs/local-dev/debugging.md
+++ b/docs/local-dev/debugging.md
@@ -47,3 +47,32 @@ The resulting log should now have more information available for debugging:
 [1] 2023-04-12T00:51:44.118Z search info Collating documents for tools succeeded type=plugin documentType=tools
 [1] 2023-04-12T00:51:44.119Z backstage debug task: search_index_tools will next occur around 2023-04-11T21:01:44.118-04:00 type=taskManager task=search_index_tools
 ```
+
+## Debugger
+
+### VSCode
+
+In your `launch.json`, add a new entry with the following,
+
+```jsonc
+{
+    // Can't get normal logs
+    "name": "Start Backend",
+    "request": "launch",
+    "env": {
+        "LOG_LEVEL": "DEBUG"
+    },
+    "args": [
+        "package",
+        "start"
+    ],
+    "cwd": "${workspaceFolder}/packages/backend",
+    "program": "${workspaceFolder}/node_modules/.bin/backstage-cli",
+    "skipFiles": [
+        "<node_internals>/**"
+    ],
+    "type": "node"
+},
+```
+
+You may notice that the normal logs mentioned above do not get logged, this is an issue with the logging library we're using, `winston`, and is not easily solved. See [this thread](https://github.com/winstonjs/winston/issues/1544) for more information.