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 guest reading guidance separate from coverage and routing
pulse-triage[bot]7218babbb251
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex dd2e563462..8a4de47a36 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -282,10 +282,14 @@ restore, not by overwriting today's history. Follow#### Primary IP shows a Podman or Docker bridge addressOn a Proxmox VM or LXC, **Primary IP** is Pulse's selected address, not proof of-the guest's default route or reachability from your browser. In an agentless-LXC, the collected addresses can be sorted independently of their interfaces,-so a `podman0` or Docker bridge address can appear before the intended `eth0`-address. The Proxmox API and Pulse agent use different collection paths; an+the guest's default route or reachability from your browser. An agentless LXC+uses the Proxmox collection path. When interface associations are supplied,+Pulse prefers other guest interfaces to recognised local-container/overlay+interfaces such as `podman0`; this is a display hint, not a physical-NIC test.+Useful secondary addresses are retained, including a virtual-only guest's+addresses. An unknown interface association remains unknown; address order+does not establish the intended route. The Proxmox API and Pulse agent use+different collection paths; anagent's correct address does not establish that the API-only view is correct.For access, use the intended guest address from your existing Proxmox network@@ -381,8 +385,10 @@ logs. Repair an older generated unit through the current signed installer at aplanned maintenance window, preserving the deployment's settings and data.#### VMs show "-" for disk usage-- Read the disk value's explanation and observation time first; a dash is not- proof that the agent is missing.+- Start with [current, retained and unavailable disk readings](VM_DISK_MONITORING.md#current-retained-and-unavailable-disk-readings).+ A dash is not zero; a **Prior** number is not current free space. Clear numeric+ disk conditions to inspect missing readings, not to change collection or access.+ A filtered list or disk sort is not proof of complete monitoring.- Check the guest-local service, current VM Options and the configured APItoken's read permissions. Schedule any setup change or restart outside backups.- Do not run guest-agent probes during backup freeze/thaw. An OK backup taskdiff --git a/docs/VM_DISK_MONITORING.md b/docs/VM_DISK_MONITORING.mdindex 0310ad379f..8f2cd492c6 100644--- a/docs/VM_DISK_MONITORING.md+++ b/docs/VM_DISK_MONITORING.md@@ -311,8 +311,45 @@ custom monitoring role if the required read privileges are absent.## 🔧 Troubleshooting+### Current, retained and unavailable disk readings++In **Workloads**, read the disk cell's explanation or open the guest's details+and look under **Filesystems → Status**. Compact rows use **Prior** and **N/A**;+wider rows use **Last known** and **Unavailable**. Where an observation time is+shown, keep it with the reading; an unavailable time leaves freshness unknown.++| Reading | What it establishes |+| --- | --- |+| Current filesystem usage | Usage for the reported guest and filesystem, from its collection source. It does not establish that every filesystem is covered or that a backup can be restored. |+| **Prior**, **Last known**, or **Using last known disk stats** | Retained evidence, not current free space. A visible number or History sample does not make it fresh. |+| **N/A**, **Unavailable**, a dash, or a paused/deferred read | Usage is unknown, not zero and not proof that the disk is full. A cooldown ending does not establish a successful new read. |++**A numeric disk search or disk sort is not a monitoring-coverage check.** To+review missing readings, clear numeric disk conditions and restrictive table+filters, then use the existing name search or unfiltered inventory. Inspect the+same guest's explanation and filesystem rows, not just the first or last row+in a disk sort. A guest absent from a filtered result is not evidence of low+usage, deletion or healthy monitoring. Clearing a display filter neither changes+access nor stops API polling; keep intentionally restricted targets restricted.++An existing linked Pulse Agent can supply current filesystem readings while+Proxmox guest reads are deferred. Conversely, a stale agent can leave retained+values. Compare the collection source, same guest identity and filesystem; a+working Machines view does not prove that the QEMU-only path recovered. Use+[existing Machines readings](#use-existing-machines-readings-without-changing-the-guest)+only with those distinctions, without installing another agent.++Use normally collected observations and the guest's established filesystem+view for capacity decisions. Do not run Diagnostics, guest-agent probes,+a backup or a restart to turn an unknown reading into a number. Do not bypass a+guest-read pause or widen token access. None of these display states proves+thaw or successful workload writes; [Backup safety](#backup-safety) still applies.+### A missing reading is not an installation diagnosis+[Check the reading's context](#current-retained-and-unavailable-disk-readings)+before treating a dash or a retained number as a setup failure.+Pulse's **“agent not running”** disk explanation means Proxmox could not querythe guest agent. It can also cover a general guest-agent HTTP 500 response; itdoes not establish whether an agent is absent or stopped. An unknown explanationdiff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.mdindex dd2e563462..8a4de47a36 100644--- a/frontend-modern/public/docs/TROUBLESHOOTING.md+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md@@ -282,10 +282,14 @@ restore, not by overwriting today's history. Follow#### Primary IP shows a Podman or Docker bridge addressOn a Proxmox VM or LXC, **Primary IP** is Pulse's selected address, not proof of-the guest's default route or reachability from your browser. In an agentless-LXC, the collected addresses can be sorted independently of their interfaces,-so a `podman0` or Docker bridge address can appear before the intended `eth0`-address. The Proxmox API and Pulse agent use different collection paths; an+the guest's default route or reachability from your browser. An agentless LXC+uses the Proxmox collection path. When interface associations are supplied,+Pulse prefers other guest interfaces to recognised local-container/overlay+interfaces such as `podman0`; this is a display hint, not a physical-NIC test.+Useful secondary addresses are retained, including a virtual-only guest's+addresses. An unknown interface association remains unknown; address order+does not establish the intended route. The Proxmox API and Pulse agent use+different collection paths; anagent's correct address does not establish that the API-only view is correct.For access, use the intended guest address from your existing Proxmox network@@ -381,8 +385,10 @@ logs. Repair an older generated unit through the current signed installer at aplanned maintenance window, preserving the deployment's settings and data.#### VMs show "-" for disk usage-- Read the disk value's explanation and observation time first; a dash is not- proof that the agent is missing.+- Start with [current, retained and unavailable disk readings](VM_DISK_MONITORING.md#current-retained-and-unavailable-disk-readings).+ A dash is not zero; a **Prior** number is not current free space. Clear numeric+ disk conditions to inspect missing readings, not to change collection or access.+ A filtered list or disk sort is not proof of complete monitoring.- Check the guest-local service, current VM Options and the configured APItoken's read permissions. Schedule any setup change or restart outside backups.- Do not run guest-agent probes during backup freeze/thaw. An OK backup taskdiff --git a/frontend-modern/public/docs/VM_DISK_MONITORING.md b/frontend-modern/public/docs/VM_DISK_MONITORING.mdindex 0310ad379f..8f2cd492c6 100644--- a/frontend-modern/public/docs/VM_DISK_MONITORING.md+++ b/frontend-modern/public/docs/VM_DISK_MONITORING.md@@ -311,8 +311,45 @@ custom monitoring role if the required read privileges are absent.## 🔧 Troubleshooting+### Current, retained and unavailable disk readings++In **Workloads**, read the disk cell's explanation or open the guest's details+and look under **Filesystems → Status**. Compact rows use **Prior** and **N/A**;+wider rows use **Last known** and **Unavailable**. Where an observation time is+shown, keep it with the reading; an unavailable time leaves freshness unknown.++| Reading | What it establishes |+| --- | --- |+| Current filesystem usage | Usage for the reported guest and filesystem, from its collection source. It does not establish that every filesystem is covered or that a backup can be restored. |+| **Prior**, **Last known**, or **Using last known disk stats** | Retained evidence, not current free space. A visible number or History sample does not make it fresh. |+| **N/A**, **Unavailable**, a dash, or a paused/deferred read | Usage is unknown, not zero and not proof that the disk is full. A cooldown ending does not establish a successful new read. |++**A numeric disk search or disk sort is not a monitoring-coverage check.** To+review missing readings, clear numeric disk conditions and restrictive table+filters, then use the existing name search or unfiltered inventory. Inspect the+same guest's explanation and filesystem rows, not just the first or last row+in a disk sort. A guest absent from a filtered result is not evidence of low+usage, deletion or healthy monitoring. Clearing a display filter neither changes+access nor stops API polling; keep intentionally restricted targets restricted.++An existing linked Pulse Agent can supply current filesystem readings while+Proxmox guest reads are deferred. Conversely, a stale agent can leave retained+values. Compare the collection source, same guest identity and filesystem; a+working Machines view does not prove that the QEMU-only path recovered. Use+[existing Machines readings](#use-existing-machines-readings-without-changing-the-guest)+only with those distinctions, without installing another agent.++Use normally collected observations and the guest's established filesystem+view for capacity decisions. Do not run Diagnostics, guest-agent probes,+a backup or a restart to turn an unknown reading into a number. Do not bypass a+guest-read pause or widen token access. None of these display states proves+thaw or successful workload writes; [Backup safety](#backup-safety) still applies.+### A missing reading is not an installation diagnosis+[Check the reading's context](#current-retained-and-unavailable-disk-readings)+before treating a dash or a retained number as a setup failure.+Pulse's **“agent not running”** disk explanation means Proxmox could not querythe guest agent. It can also cover a general guest-agent HTTP 500 response; itdoes not establish whether an agent is absent or stopped. An unknown explanationdiff --git a/scripts/tests/test_guest_disk_reading_docs.py b/scripts/tests/test_guest_disk_reading_docs.pynew file mode 100644index 0000000000..7f0ce11691--- /dev/null+++ b/scripts/tests/test_guest_disk_reading_docs.py@@ -0,0 +1,74 @@+#!/usr/bin/env python3+"""Verify safe existing-view guidance, not polling, routing or native recovery."""++from pathlib import Path+import unittest+++ROOT = Path(__file__).resolve().parents[2]+HEADING = "### Current, retained and unavailable disk readings\n"+ANCHOR = "#current-retained-and-unavailable-disk-readings"+++class GuestDiskReadingDocsTest(unittest.TestCase):+ def section(self):+ guide = (ROOT / "docs/VM_DISK_MONITORING.md").read_text(encoding="utf-8")+ self.assertEqual(guide.count(HEADING), 1)+ return " ".join(guide.split(HEADING, 1)[1].split("\n### ", 1)[0].split())++ def test_explanations_use_existing_labels_without_claiming_freshness(self):+ text = self.section()+ row = (ROOT / "frontend-modern/src/components/Workloads/GuestRow.tsx").read_text()+ drawer = (ROOT / "frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx").read_text()+ presentation = (ROOT / "frontend-modern/src/utils/workloadGuestPresentation.ts").read_text()+ for label in ("Prior", "N/A", "Last known", "Unavailable"):+ with self.subTest(label=label):+ self.assertIn(label, text)+ self.assertIn(f"'{label}'", row)+ self.assertIn("Filesystems → Status", text)+ self.assertIn("label: 'Filesystems'", drawer)+ self.assertIn("makeDetailRow('Status'", drawer)+ self.assertIn("Using last known disk stats", text)+ self.assertIn("Using last known disk stats", presentation)+ for distinction in ("not current free space", "unknown, not zero",+ "not proof that the disk is full", "freshness unknown",+ "A cooldown ending does not establish a successful new read"):+ self.assertIn(distinction, text)++ def test_inventory_workflow_does_not_confuse_selection_with_coverage(self):+ text = self.section()+ for distinction in ("not a monitoring-coverage check", "clear numeric disk conditions",+ "existing name search or unfiltered inventory",+ "same guest's explanation and filesystem rows",+ "not evidence of low usage, deletion or healthy monitoring",+ "neither changes access nor stops API polling",+ "keep intentionally restricted targets restricted"):+ self.assertIn(distinction, text)++ def test_source_and_recovery_boundaries_remain_distinct(self):+ text = self.section()+ for distinction in ("existing linked Pulse Agent", "stale agent",+ "same guest identity and filesystem",+ "does not prove that the QEMU-only path recovered",+ "without installing another agent", "normally collected observations",+ "Do not run Diagnostics, guest-agent probes", "backup or a restart",+ "Do not bypass a guest-read pause or widen token access",+ "None of these display states proves thaw", "Backup safety"):+ self.assertIn(distinction, text)+ self.assertNotIn("```", text, "use existing observations, not an active command")++ def test_existing_entry_points_reach_the_guidance_and_mirrors_match(self):+ guide = (ROOT / "docs/VM_DISK_MONITORING.md").read_text()+ diagnosis = guide.split("### A missing reading is not an installation diagnosis\n", 1)[1]+ self.assertIn(f"[Check the reading's context]({ANCHOR})", diagnosis)+ trouble = (ROOT / "docs/TROUBLESHOOTING.md").read_text()+ dash_help = trouble.split('#### VMs show "-" for disk usage\n', 1)[1].split("\n#### ", 1)[0]+ self.assertIn(f"VM_DISK_MONITORING.md{ANCHOR}", dash_help)+ self.assertIn("A filtered list or disk sort is not proof of complete monitoring", dash_help)+ for name in ("VM_DISK_MONITORING.md", "TROUBLESHOOTING.md"):+ self.assertEqual((ROOT / "docs" / name).read_bytes(),+ (ROOT / "frontend-modern/public/docs" / name).read_bytes())+++if __name__ == "__main__":+ unittest.main()diff --git a/scripts/tests/test_guest_network_troubleshooting_docs.py b/scripts/tests/test_guest_network_troubleshooting_docs.pyindex 70358d057d..7e4a0e103e 100644--- a/scripts/tests/test_guest_network_troubleshooting_docs.py+++ b/scripts/tests/test_guest_network_troubleshooting_docs.py@@ -63,6 +63,24 @@ class GuestNetworkTroubleshootingDocsTest(unittest.TestCase):self.assertIn(boundary, text)self.assertNotIn("```", text, "use existing observations, not a copied command")+ def test_interface_preference_is_not_routing_or_blanket_virtual_exclusion(self):+ text = self.section()+ for distinction in (+ "When interface associations are supplied",+ "not a physical-NIC test",+ "Useful secondary addresses are retained",+ "virtual-only guest's addresses",+ "An unknown interface association remains unknown",+ "address order does not establish the intended route",+ ):+ with self.subTest(distinction=distinction):+ self.assertIn(distinction, text)+ self.assertNotIn("sorted independently of their interfaces", text)+ collector = (ROOT / "internal/monitoring/guest_network_addresses.go").read_text()+ self.assertIn("guestIPAddressesByInterface", collector)+ self.assertIn("IsSecondaryInterfaceName", collector)+ self.assertIn("!associated[address]", collector)+def test_shipped_help_is_byte_identical(self):self.assertEqual((ROOT / "docs/TROUBLESHOOTING.md").read_bytes(),