|
| 1 | +:_content-type: PROCEDURE |
| 2 | +:description: Debugging a failing {prod-short} workspace by starting it in debug mode |
| 3 | +:keywords: user-guide, debug, workspace, troubleshooting |
| 4 | +:navtitle: Debugging a workspace |
| 5 | +:page-aliases: |
| 6 | + |
| 7 | +[id="debugging-a-workspace"] |
| 8 | += Debugging a {prod-short} workspace |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +When debug mode is enabled: |
| 15 | + |
| 16 | +* If a `postStart` lifecycle command fails, the container sleeps instead of terminating, giving you time to connect and inspect the failure. |
| 17 | +* Logs from `postStart` commands are written to `/tmp/poststart-stdout.txt` and `/tmp/poststart-stderr.txt` inside the workspace container. |
| 18 | +* The workspace deployment remains available for the duration of the configured `progressTimeout` (default: 5 minutes) before scaling down. |
| 19 | + |
| 20 | +.Prerequisites |
| 21 | + |
| 22 | +* A running {prod-short} instance. |
| 23 | +* Access to the {prod-short} dashboard. |
| 24 | + |
| 25 | +.Procedure |
| 26 | + |
| 27 | +To start a stopped workspace in debug mode: |
| 28 | + |
| 29 | +. In the {prod-short} dashboard, go to the *Workspaces* page. |
| 30 | +. Click the kebab menu (*⋮*) for the workspace you want to debug. |
| 31 | +. Select *Open in Debug mode*. |
| 32 | ++ |
| 33 | +The workspace starts with the `controller.devfile.io/debug-start` annotation set to `true`, and the *Logs* tab opens. |
| 34 | + |
| 35 | +To restart a running workspace in debug mode: |
| 36 | + |
| 37 | +. In the {prod-short} dashboard, go to the *Workspaces* page. |
| 38 | +. Click the kebab menu (*⋮*) for the running workspace. |
| 39 | +. Select *Restart in Debug mode*. |
| 40 | ++ |
| 41 | +The workspace restarts with debug mode enabled, and the *Logs* tab opens. |
| 42 | + |
| 43 | +To inspect a failing workspace: |
| 44 | + |
| 45 | +. Wait for the workspace to report a failure in the *Logs* tab. |
| 46 | +. Use `{orch-cli}` to exec into the workspace container: |
| 47 | ++ |
| 48 | +[subs="+attributes,+quotes"] |
| 49 | +---- |
| 50 | +$ {orch-cli} exec --namespace='__<workspace_namespace>__' \ |
| 51 | + deploy/workspace__<workspace_id>__ -- /bin/bash |
| 52 | +---- |
| 53 | + |
| 54 | +. Review the `postStart` command logs: |
| 55 | ++ |
| 56 | +---- |
| 57 | +$ cat /tmp/poststart-stderr.txt |
| 58 | +$ cat /tmp/poststart-stdout.txt |
| 59 | +---- |
| 60 | + |
| 61 | +[IMPORTANT] |
| 62 | +==== |
| 63 | +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. |
| 64 | +
|
| 65 | +Always use the dashboard actions described above to enable debug mode. |
| 66 | +==== |
| 67 | + |
| 68 | +.Additional resources |
| 69 | +* xref:viewing-che-workspaces-logs.adoc[] |
| 70 | +* xref:viewing-workspace-logs-in-cli.adoc[] |
0 commit comments