From 11eb2f394f6d73a116dd236f30934fa7e2f98ab5 Mon Sep 17 00:00:00 2001 From: Chris Brown Date: Thu, 28 May 2026 13:02:15 +0100 Subject: [PATCH] docs: add workspace debug mode documentation Add a new procedure page documenting how to use debug mode for diagnosing workspace startup failures. Covers the dashboard UI actions ("Open in Debug mode" and "Restart in Debug mode"), log inspection, and clarifies that manual annotation patching is overwritten by the dashboard. Related: eclipse-che/che-dashboard (Restart in Debug mode feature) Signed-off-by: Chris Brown Co-Authored-By: Claude Opus 4.6 --- modules/end-user-guide/nav.adoc | 1 + .../pages/debugging-a-workspace.adoc | 75 +++++++++++++++++++ .../pages/troubleshooting-che.adoc | 1 + 3 files changed, 77 insertions(+) create mode 100644 modules/end-user-guide/pages/debugging-a-workspace.adoc diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index 18c9c36cf4..9e7d86517c 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -61,6 +61,7 @@ *** xref:viewing-workspace-logs-in-cli.adoc[] *** xref:viewing-workspace-logs-in-the-openshift-console.adoc[] *** xref:viewing-language-servers-and-debug-adapters-logs-in-visual-studio-code.adoc[] +** xref:debugging-a-workspace.adoc[] ** xref:troubleshooting-slow-workspaces.adoc[] ** xref:troubleshooting-network-problems.adoc[] ** xref:troubleshooting-webview-loading-error.adoc[] diff --git a/modules/end-user-guide/pages/debugging-a-workspace.adoc b/modules/end-user-guide/pages/debugging-a-workspace.adoc new file mode 100644 index 0000000000..74c0639dbb --- /dev/null +++ b/modules/end-user-guide/pages/debugging-a-workspace.adoc @@ -0,0 +1,75 @@ +:_content-type: PROCEDURE +:description: Debugging a failing {prod-short} workspace by starting it in debug mode +:keywords: user-guide, debug, workspace, troubleshooting +:navtitle: Debugging a workspace +:page-aliases: + +[id="debugging-a-workspace"] += Debugging a {prod-short} workspace + +When a workspace fails to start, {prod-short} normally scales down the workspace deployment and moves it to a `Failed` state. This makes it difficult to diagnose issues such as failing `postStart` commands or misconfigured containers. + +Debug mode keeps the workspace containers running after a failure so that you can inspect logs and exec into containers to diagnose the root cause. + +When debug mode is enabled: + +* If a `postStart` lifecycle command fails, the container sleeps instead of terminating, giving you time to connect and inspect the failure. +* Logs from `postStart` commands are written to `/tmp/poststart-stdout.txt` and `/tmp/poststart-stderr.txt` inside the workspace container. +* The workspace deployment remains available for the duration of the configured `progressTimeout` (default: 5 minutes) before scaling down. + +.Prerequisites + +* A running {prod-short} instance. +* Access to the {prod-short} dashboard. + +.Procedure + +To start a stopped workspace in debug mode: + +. In the {prod-short} dashboard, go to the *Workspaces* page. +. Click the kebab menu (*⋮*) for the workspace you want to debug. +. Select *Open in Debug mode*. ++ +The workspace starts with the `controller.devfile.io/debug-start` annotation set to `true`, and the *Logs* tab opens. + +To restart a running workspace in debug mode: + +. In the {prod-short} dashboard, go to the *Workspaces* page. +. Click the kebab menu (*⋮*) for the running workspace. +. Select *Restart in Debug mode*. ++ +The workspace restarts with debug mode enabled, and the *Logs* tab opens. + +To inspect a failing workspace: + +. Wait for the workspace to report a failure in the *Logs* tab. +. Use `{orch-cli}` to exec into the workspace container: ++ +[subs="+attributes,+quotes"] +---- +$ {orch-cli} exec --namespace='____' \ + deploy/workspace____ -- /bin/bash +---- + +. Review the `postStart` command logs: ++ +---- +$ cat /tmp/poststart-stderr.txt +$ cat /tmp/poststart-stdout.txt +---- + +.Verification + +* In the *Logs* tab, verify that the workspace status conditions include the message `DevWorkspace is starting in debug mode`. +* If a `postStart` command fails, verify that the container remains running and that `/tmp/poststart-stderr.txt` contains the failure details. + +[IMPORTANT] +==== +The `controller.devfile.io/debug-start` annotation is managed by the {prod-short} dashboard. Manually patching this annotation on a DevWorkspace resource using `{orch-cli}` will not persist, because the dashboard reconciles the annotation on every start or restart operation. + +Always use the dashboard actions described above to enable debug mode. +==== + +.Additional resources +* xref:viewing-che-workspaces-logs.adoc[] +* xref:viewing-workspace-logs-in-cli.adoc[] diff --git a/modules/end-user-guide/pages/troubleshooting-che.adoc b/modules/end-user-guide/pages/troubleshooting-che.adoc index 0aaa05eb0b..35d8e3d4c5 100644 --- a/modules/end-user-guide/pages/troubleshooting-che.adoc +++ b/modules/end-user-guide/pages/troubleshooting-che.adoc @@ -12,6 +12,7 @@ This section provides troubleshooting procedures for the most frequent issues a .Additional resources * xref:viewing-che-workspaces-logs.adoc[] +* xref:debugging-a-workspace.adoc[] * xref:troubleshooting-slow-workspaces.adoc[] * xref:troubleshooting-network-problems.adoc[] * xref:troubleshooting-webview-loading-error.adoc[] \ No newline at end of file