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 guest reading guidance separate from coverage and routing

pulse-triage[bot]7218babbb251
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 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 address
On 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; an
agent'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 a
planned 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 API
token's read permissions. Schedule any setup change or restart outside backups.
- Do not run guest-agent probes during backup freeze/thaw. An OK backup task
diff --git a/docs/VM_DISK_MONITORING.md b/docs/VM_DISK_MONITORING.md
index 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 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
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index 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 address
On 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; an
agent'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 a
planned 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 API
token's read permissions. Schedule any setup change or restart outside backups.
- Do not run guest-agent probes during backup freeze/thaw. An OK backup task
diff --git a/frontend-modern/public/docs/VM_DISK_MONITORING.md b/frontend-modern/public/docs/VM_DISK_MONITORING.md
index 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 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
diff --git a/scripts/tests/test_guest_disk_reading_docs.py b/scripts/tests/test_guest_disk_reading_docs.py
new file mode 100644
index 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.py
index 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(),