4.9 KiB
Lifecycle, health, and logs
Public status and lifecycle
Start diagnosis with:
dsh-platform status
Restart only DSH, while keeping Gateway and Management available, with:
dsh-platform restart
For an Agent running inside the current DSH session, restart must remain asynchronous: report the returned task ID and let the browser enter the lifecycle holding page. Never run restart --wait or stop --wait from that session because DSH shutdown interrupts the tool transport. --wait is reserved for an external operator terminal, the standalone Management Console terminal, and external automation.
The standalone Management Console and CLI also expose explicit lifecycle operations:
dsh-platform start
dsh-platform stop
dsh-platform restart
An explicit stop lasts only for the current container lifetime. An unexpected DSH exit is recovered at most three times; check dshLifecycle and recoveryMode rather than repeatedly sending restart commands.
The container admits only the Bootstrap-supervised Web Profile. Do not launch a replacement with dsh web: when DSH is stopped that command delegates to the public start operation, and otherwise it reports the managed state without creating a second instance. An unregistered first SIGTERM is converted into a public asynchronous restart, but this compatibility behavior is not a reason to signal the process directly.
Do not send signals to DSH, kill its PID, invoke Bootstrap sockets, or restart the whole container unless the user specifically requested that broader action. During a registered lifecycle operation, browser navigation enters the localized holding page and returns to the original same-origin path only after the DSH HTTP upstream responds and the platform lifecycle has finished starting, restarting, recovering, or switching. This prevents a listening but not yet plugin-ready DSH instance from being shown early. API and WebSocket requests receive 503 until that combined readiness succeeds.
Do not diagnose these classified holding responses as Gateway outages. An explicit start, stop, restart, switch, or recovery does not emit gateway.upstream.failed or gateway.upstream.recovered; those records are reserved for an unclassified upstream outage and its recovery.
Plugin bundle requests are held while a registered lifecycle transition makes DSH temporarily unavailable. The same guard covers official DSH plugins, bundled System Plugins, and User Plugins. A failed bundle request or structured dynamic-import error may enter the holding page twice for the same running Deployment. A third structured failure opens Gateway's terminal plugin-failure page and links to the standalone Management Console; it never starts an unbounded reload loop. Detection uses the plugin request or module error URL, not visible page text. Do not advise repeated manual refreshes before checking lifecycle state, recovery-attempt fields, and browser recovery events in platform logs.
Docker health probes Gateway control-plane health at 127.0.0.1:3080/_dsh_gateway/health. It is independent of DSH readiness, so an intentional DSH stop does not make Docker report the container as unhealthy while the standalone Management Console remains available.
Logs
Inside the container, query structured platform logs with:
dsh-platform logs --limit 500
dsh-platform logs --source dsh-runtime --limit 500
dsh-platform logs --since <ISO-8601-time> --limit 500
The standalone Management Console and Platform Management plugin provide filtering, expansion of complete structured entries, refresh, live following, and JSONL export. From the Docker host, docker logs <container> includes platform and DSH output.
When reporting a failure, include the operation/task ID, source, timestamp, complete error, and the smallest relevant surrounding entries. Do not include credentials, terminal contents, or unrelated user data.
For a browser plugin-load failure, correlate browser.plugin-load.failed with browser.plugin-load.recovery.started, browser.plugin-load.recovery.completed, or browser.plugin-load.recovery.failed. A completed recovery confirms a transient lifecycle race. Attempt three and the terminal Gateway page identify a persistent failure; a failure without recovery eligibility also requires investigation of the named plugin bundle and DSH Runtime logs.
Logs rotate automatically according to the platform size and retention settings. Clearing the UI display is a local display cutoff and does not delete the persisted platform log files.
Management surfaces
The standalone DSH Management Console is served at /_dsh_platform/console/ and stays available when DSH is starting, restarting, recovering, or down. Platform Management inside DSH exposes the routine subset appropriate while DSH is available. Prefer the standalone console for recovery, Root terminal/file access, user-plugin recovery, and System Skill reinstallation.