Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Keep missing guest disk guidance out of unsafe setup assumptions
pulse-triage[bot]0db135d7ccbc
diff --git a/docs/VM_DISK_MONITORING.md b/docs/VM_DISK_MONITORING.mdindex 14ba35ea07..f331ccba0c 100644--- a/docs/VM_DISK_MONITORING.md+++ b/docs/VM_DISK_MONITORING.md@@ -146,6 +146,29 @@ custom monitoring role if the required read privileges are absent.## 🔧 Troubleshooting+### A missing reading is not an installation diagnosis++Pulse's **“agent not running”** disk explanation means Proxmox could not query+the guest agent. It can also cover a general guest-agent HTTP 500 response; it+does not establish whether an agent is absent or stopped. An unknown explanation+establishes neither. **Do not install, enable or restart an agent solely to clear+a disk dash.**++Read [Backup safety](#backup-safety) before changing anything. During a backup,+freeze/thaw or an unresponsive-guest incident, defer setup and live probes and+use the guest/platform's established recovery procedure. A running VM, an absent+lock or an OK backup does not prove thaw. Keep the monitoring-outage precaution+until independent checks confirm thaw, fresh successful writes to **every+filesystem covered by the backup** and workload liveness. Restore only services+and timers that were previously active.++When the guest is responsive and outside those conditions, review its existing+agent configuration and guest-local service through your normal console. Use+[Setup](#-setup) only if it actually needs configuration and the guest OS has a+supported QEMU Guest Agent. The Linux package name is not a Windows or Android+installation instruction. If no supported agent is available, use the guest's+own filesystem tools; missing Pulse usage is unknown, not zero.+| Observation | Useful next check || --- | --- || **Disk shows “-”** | Read its explanation and observation time. Check the owning host, current VM options, guest-local service and configured API token access. |diff --git a/frontend-modern/public/docs/VM_DISK_MONITORING.md b/frontend-modern/public/docs/VM_DISK_MONITORING.mdindex 14ba35ea07..f331ccba0c 100644--- a/frontend-modern/public/docs/VM_DISK_MONITORING.md+++ b/frontend-modern/public/docs/VM_DISK_MONITORING.md@@ -146,6 +146,29 @@ custom monitoring role if the required read privileges are absent.## 🔧 Troubleshooting+### A missing reading is not an installation diagnosis++Pulse's **“agent not running”** disk explanation means Proxmox could not query+the guest agent. It can also cover a general guest-agent HTTP 500 response; it+does not establish whether an agent is absent or stopped. An unknown explanation+establishes neither. **Do not install, enable or restart an agent solely to clear+a disk dash.**++Read [Backup safety](#backup-safety) before changing anything. During a backup,+freeze/thaw or an unresponsive-guest incident, defer setup and live probes and+use the guest/platform's established recovery procedure. A running VM, an absent+lock or an OK backup does not prove thaw. Keep the monitoring-outage precaution+until independent checks confirm thaw, fresh successful writes to **every+filesystem covered by the backup** and workload liveness. Restore only services+and timers that were previously active.++When the guest is responsive and outside those conditions, review its existing+agent configuration and guest-local service through your normal console. Use+[Setup](#-setup) only if it actually needs configuration and the guest OS has a+supported QEMU Guest Agent. The Linux package name is not a Windows or Android+installation instruction. If no supported agent is available, use the guest's+own filesystem tools; missing Pulse usage is unknown, not zero.+| Observation | Useful next check || --- | --- || **Disk shows “-”** | Read its explanation and observation time. Check the owning host, current VM options, guest-local service and configured API token access. |diff --git a/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts b/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.tsindex fa22a89310..4f31933bb1 100644--- a/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts+++ b/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts@@ -19,6 +19,42 @@ function render(markdown: string, name: string): HTMLElement {}describe('manual backup safety help', () => {+ it('makes missing-reading guidance observational, OS-specific and safe before setup', () => {+ const rendered = render(guide, 'VM_DISK_MONITORING');+ const troubleshooting = rendered.querySelector(+ '#a-missing-reading-is-not-an-installation-diagnosis',+ );+ expect(troubleshooting?.textContent).toBe('A missing reading is not an installation diagnosis');+ const explanation = guide+ .split('### A missing reading is not an installation diagnosis')[1]+ .split('| Observation |')[0];+ const text = render(explanation, 'VM_DISK_MONITORING').textContent?.replace(/\s+/g, ' ');+ expect(text).toContain('does not establish whether an agent is absent or stopped');+ expect(text).toContain(+ 'Do not install, enable or restart an agent solely to clear a disk dash',+ );+ expect(text).toContain('defer setup and live probes');+ expect(text).toContain('every filesystem covered by the backup');+ expect(text).toContain('workload liveness');+ expect(text).toContain('Restore only services and timers that were previously active');+ expect(text).toContain('not a Windows or Android installation instruction');+ expect(text).toContain('missing Pulse usage is unknown, not zero');+ expect(render(explanation, 'VM_DISK_MONITORING').querySelector('pre')).toBeNull();+ for (const fragment of ['backup-safety', '-setup']) {+ const link = render(explanation, 'VM_DISK_MONITORING').querySelector(+ `a[href="#${fragment}"]`,+ );+ expect(link).not.toBeNull();+ expect(rendered.querySelector(`#${fragment}`)).not.toBeNull();+ }+ // This broad status comes from the current collector, not a reproduced+ // native failure or a new diagnosis of the guest's service state.+ const classifier = read('internal/monitoring/guest_disk_stability.go');+ expect(classifier).toMatch(+ /case strings.Contains\(errStr, "500"\):\s+return "agent-not-running"/,+ );+ });+it('ships the complete precaution and makes it reachable from troubleshooting', () => {expect(read('frontend-modern/public/docs/VM_DISK_MONITORING.md')).toBe(guide);const troubleshooting = read('docs/TROUBLESHOOTING.md');