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 memory setup advice safe during backups

pulse-triage[bot]c776990b817b
diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
index 783fff56fd..1511069f29 100644
--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md
+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
@@ -223,6 +223,11 @@ the caveat in the bar tooltip and drawer instead of a label on every row. A
retained or freshness-unknown reading keeps its own freshness label with the
caveat in its explanation, an unavailable reading is never qualified, and the
drawer states the note as visible text in `About this reading`.
+Agent setup advice first states that setup, restarts and live guest-agent probes
+must be deferred during backups or a guest incident. This precaution stays with
+VM/container fallback guidance regardless of freshness or a reported backup lock;
+a fallback value or an ended lock does not establish that changing agents is safe.
+It changes no numbers, source selection, collection, thresholds or guest actions.
`GuestRow.test.tsx`, `GuestDrawerOverview.memory-cache.test.tsx`,
`MetricMiniSparkline.test.tsx` and `memoryObservation.test.ts` pin these
diff --git a/frontend-modern/browser-verification/e927107049b090ab.json b/frontend-modern/browser-verification/e927107049b090ab.json
new file mode 100644
index 0000000000..6d43f7dabb
--- /dev/null
+++ b/frontend-modern/browser-verification/e927107049b090ab.json
@@ -0,0 +1,38 @@
+{
+ "version": 1,
+ "base_sha": "123652e29bf2598fca65ddbc2d543789919beb53",
+ "verified_at": "2026-10-12T09:33:16Z",
+ "result": "passed",
+ "changed_paths": [
+ "frontend-modern/src/utils/memoryObservation.ts"
+ ],
+ "content_sha256": {
+ "frontend-modern/src/utils/memoryObservation.ts": "ea36675771aed0b5ba55f7f6ad69a58ccbf5153d75592e55a7ac8720a8993a59"
+ },
+ "routes": [
+ "/tmp/memory-setup-safety/index.html",
+ "/tmp/memory-setup-safety/index.html?lxc"
+ ],
+ "viewports": [
+ {
+ "width": 1440,
+ "height": 1000
+ },
+ {
+ "width": 390,
+ "height": 844
+ }
+ ],
+ "states": [
+ "Production useWorkloads canonical snapshot mapper, GuestRow, GuestDrawer and CSS with synthetic VM/LXC snapshots; no native guest operation",
+ "Current cache-inclusive memory retains the 94% reading and original source/time; setup precaution precedes conditional advice",
+ "Backup-active, last-known and freshness-unknown readings retain the precaution; advancing Last seen cannot renew memory",
+ "Unavailable is N/A with no setup note; measured zero remains current; a cache-aware agent removes the unneeded note",
+ "VM guidance keeps QEMU Linux-only; container guidance suggests Pulse only; no pressure or guaranteed recovery claim"
+ ],
+ "interactions": [
+ "Chromium 141.0.7390.37 desktop light: keyboard row disclosure/control activation and real memory-bar pointer tooltip",
+ "WebKit 26.0 phone dark: touch row expansion and snapshot controls; visible stacked About this reading note",
+ "40 grouped checks, 12 captures inspected, no overflow/page or console errors/API writes/external requests; browser and server closed"
+ ]
+}
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.memory-cache.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.memory-cache.test.tsx
index 52a972103e..4df7a74672 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.memory-cache.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.memory-cache.test.tsx
@@ -79,6 +79,9 @@ describe('guest drawer cache-inclusive memory note', () => {
expect(note).toHaveTextContent('a high percentage alone does not mean it is short of memory');
expect(note).toHaveTextContent('Pulse agent in the VM');
expect(note).toHaveTextContent('QEMU guest agent on a Linux VM');
+ expect(note).toHaveTextContent(
+ 'Defer agent setup, restarts and live guest-agent probes during backups or a guest incident.',
+ );
});
it('follows the guest when a better source replaces the cache-inclusive one', () => {
@@ -112,6 +115,23 @@ describe('guest drawer cache-inclusive memory note', () => {
const note = screen.getByText('About this reading').closest('tr')!;
expect(note).toHaveTextContent('Pulse agent in the container');
expect(note).not.toHaveTextContent('QEMU');
+ expect(note).toHaveTextContent('during backups or a guest incident');
+ });
+
+ it('does not remove the setup precaution when a backup ends or the reading becomes retained', () => {
+ const [value, setValue] = createSignal(
+ guest('status-mem', { backupInProgress: true, diskStatusReason: 'prev-vm-locked' }),
+ );
+ render(() => <GuestDrawerOverview {...overviewProps(value())} />);
+ const note = () => screen.getByText('About this reading').closest('tr')!;
+ expect(note()).toHaveTextContent('during backups or a guest incident');
+ setValue(guest('status-mem'));
+ expect(note()).toHaveTextContent('during backups or a guest incident');
+ const retained = guest('status-mem');
+ retained.memory.observation!.state = 'last-known';
+ setValue(retained);
+ expect(note()).toHaveTextContent('during backups or a guest incident');
+ expect(screen.getByText('Memory reading').closest('tr')).toHaveTextContent('Last known');
});
it.each(['guest-agent-meminfo', 'agent'])(
diff --git a/frontend-modern/src/utils/__tests__/memoryObservation.test.ts b/frontend-modern/src/utils/__tests__/memoryObservation.test.ts
index 76d8579670..f5ba44db2c 100644
--- a/frontend-modern/src/utils/__tests__/memoryObservation.test.ts
+++ b/frontend-modern/src/utils/__tests__/memoryObservation.test.ts
@@ -117,6 +117,30 @@ describe('cache-inclusive Proxmox memory sources', () => {
},
);
+ it.each(['status-mem', 'status-freemem', 'cluster-resources', 'derived-total-minus-used'])(
+ 'keeps %s setup advice behind the backup and guest-incident precaution',
+ (source) => {
+ const precaution =
+ 'Defer agent setup, restarts and live guest-agent probes during backups or a guest incident.';
+ for (const type of ['qemu', 'lxc']) {
+ for (const state of ['current', 'last-known', 'future-state']) {
+ const input = reading(source, state, { type });
+ const original = structuredClone(input);
+ const presentation = getWorkloadMemoryObservationPresentation(input, {
+ includeCurrent: false,
+ })!;
+ expect(presentation.cacheNote).toContain(precaution);
+ expect(presentation.cacheNote!.indexOf(precaution)).toBeLessThan(
+ presentation.cacheNote!.indexOf('Installing a Pulse agent'),
+ );
+ expect(presentation.message).toContain(precaution);
+ expect(presentation.cacheNote).not.toMatch(/\bwill\b|qm agent|systemctl|curl/);
+ expect(input).toEqual(original);
+ }
+ }
+ },
+ );
+
it.each([
'guest-agent-meminfo',
'guest-agent-meminfo-derived',
diff --git a/frontend-modern/src/utils/memoryObservation.ts b/frontend-modern/src/utils/memoryObservation.ts
index 879b648b87..8592b557e7 100644
--- a/frontend-modern/src/utils/memoryObservation.ts
+++ b/frontend-modern/src/utils/memoryObservation.ts
@@ -41,16 +41,21 @@ export type MemoryGuestKind = 'vm' | 'container';
const getCacheNote = (kind: MemoryGuestKind | undefined): string => {
const noun = kind === 'vm' ? 'VM' : kind === 'container' ? 'container' : 'guest';
const caveat = `Proxmox's reading may include cached memory the ${noun} can reuse, so a high percentage alone does not mean it is short of memory.`;
+ // A fallback memory value does not establish that it is safe to change the
+ // guest's agents. Keep the precaution with the advice, even without a known
+ // backup lock: Pulse cannot infer the absence of a guest incident.
+ const setupPrecaution =
+ 'Defer agent setup, restarts and live guest-agent probes during backups or a guest incident.';
// A Pulse agent inside the guest can supply its own figure on any OS (a
// container's must report the container's own limit). The QEMU guest agent
// path reads Linux /proc/meminfo only and needs installing in the guest and
// enabling in Proxmox. Neither is guaranteed to replace every fallback
// source, so the advice says "can". Kept short: the drawer column is narrow.
if (kind === 'vm') {
- return `${caveat} Installing a Pulse agent in the VM, or setting up the QEMU guest agent on a Linux VM, can let Pulse show its own figure.`;
+ return `${caveat} ${setupPrecaution} Installing a Pulse agent in the VM, or setting up the QEMU guest agent on a Linux VM, can let Pulse show its own figure.`;
}
if (kind === 'container') {
- return `${caveat} Installing a Pulse agent in the container can let Pulse show its own figure.`;
+ return `${caveat} ${setupPrecaution} Installing a Pulse agent in the container can let Pulse show its own figure.`;
}
return caveat;
};