From 96c71045212c24b30907cf0874184722e9dae68d Mon Sep 17 00:00:00 2001 From: Anso Date: Mon, 25 May 2026 12:10:13 -0400 Subject: [PATCH] docs(dashboard): refresh Troubleshooting accordion for new metrics-stale chip and tightened refresh model (#1223) Three accordion edits keep the user-visible behaviour described on docs/features/dashboard.mdx in step with the audit's surface changes. - "Configuration Status still shows the old value after I changed a setting": replace the broad "most settings dispatch a live invalidation" language with the precise behaviour, which is that only a stack Auto-update toggle triggers an immediate refetch; every other settings edit waits for the 60-second poll. The change avoids promising responsiveness the card cannot deliver and points the operator at the hard-reload escape hatch. - New "The masthead shows a 'metrics stale' chip" entry: describe what the chip means, the threshold (three consecutive metrics-endpoint failures), that polling continues regardless, and that the chip describes data freshness rather than the polling cadence. Points the operator at the Docker daemon and Sencho container logs as first checks. - New "The dashboard feels sluggish on a large deployment" entry: document the Developer mode toggle as the supported diagnostic path for slow-dashboard reports. Lists the [Dashboard:debug] log shape so the operator knows what to look for, and reminds them to disable the toggle afterwards. --- docs/features/dashboard.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/features/dashboard.mdx b/docs/features/dashboard.mdx index 6e80eb1e..135515a6 100644 --- a/docs/features/dashboard.mdx +++ b/docs/features/dashboard.mdx @@ -220,7 +220,10 @@ When you switch the active node from the node switcher, the dashboard resets eve Pilot-agent nodes connect outbound to the primary over a reverse tunnel, so there is no synchronous request-response loop to measure. The Heartbeat card uses the tunnel's last heartbeat to set the dot color, and intentionally renders `n/a` in the latency column. If the dot is red, check the agent container's logs for the first `[Pilot]` line and confirm the agent can reach the primary URL it is dialing. See [Pilot agent](/features/pilot-agent). - The card refreshes every 60 seconds on its own schedule. Most settings changes also dispatch a live invalidation event that triggers an immediate refetch, but some flows (cloud backup provider switch, SSO provider change) only update on the next polling tick. If the row remains stale after a minute, hard-reload the dashboard tab to force a fresh fetch. + The card refreshes every 60 seconds on its own schedule. Toggling a stack's **Auto-update** setting also dispatches a live invalidation that the card picks up within a second. Other settings changes (cloud backup provider switch, SSO provider change, alert rule edit, agent toggle) update on the next 60-second tick. If the row stays stale after a minute, hard-reload the dashboard tab to force a fresh fetch. + + + The chip appears after three consecutive failures of the live metrics endpoints (`/api/stats` or `/api/system/stats`), which usually means the Docker socket is unreachable from this Sencho instance or the metrics service has stopped. The dashboard keeps polling on every cycle; the chip describes the freshness of the visible numbers, not the polling cadence. The chip clears on the first successful response once both endpoints are within the threshold. Check the Docker daemon status on the active node first, then the Sencho container logs for `[Dashboard]` lines if the chip persists. The card paginates at eight rows. Use the chevrons in the header to flip pages. The full alert history (with filters and search) lives in the bell menu in the top bar; the dashboard card is a tape view of the latest entries on the active node. **Clear All Notifications** deletes the whole feed in one call, fanned out across every node that contributed an entry. @@ -228,4 +231,7 @@ When you switch the active node from the node switcher, the dashboard resets eve Critical can fire on RAM, disk, or the combination of any exited container with an unread error alert, not only on CPU. Read the reasons line right under the meta line; it lists every signal pushing the state up. Common cases: RAM at or above 90% from an oversized service, disk at or above 90% from runaway log retention, or a crashed container that no one has acknowledged in the alerts panel. + + Toggle **Developer mode** under **Settings ยท System**. Both dashboard endpoints then emit a `[Dashboard:debug]` line in the Sencho container logs for every request, reporting elapsed milliseconds and the contextual fields (`nodeId`, row count, `days` window). Use the timings to identify whether the Configuration Status payload or the stack-restarts query is the bottleneck. Disable developer mode when you are done to keep the log volume manageable. +