Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

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.md
index 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.md
index 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.ts
index 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');