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.

Explain backup badge freshness for longer backup cycles

pulse-triage[bot]4511bb0a562d
diff --git a/docs/PBS.md b/docs/PBS.md
index bfe3bb3981..bfb61548c9 100644
--- a/docs/PBS.md
+++ b/docs/PBS.md
@@ -303,6 +303,39 @@ private keys. If help is needed, provide only the HTTP status, relevant redacted
error and which expected reading is missing. Do not clear History or recreate a
working connection to make missing data look resolved.
+### Backup age colours for a longer backup cycle
+
+The VM/LXC backup shield uses **hours**, separately from the backup-age alert
+thresholds in **days**. An amber age badge does not by itself mean that a
+backup failed or that a notification was sent.
+
+Open **Alerts → Thresholds → Proxmox**, then expand **Recovery**. In
+**Global Defaults**:
+
+| Control | What it changes |
+| --- | --- |
+| **Fresh Hours** | How long the latest completed backup keeps a green shield. The default is 24 hours. |
+| **Stale Hours** | The end of the next age band, after which the backup is classified as overdue. Keep it at least as large as Fresh Hours. |
+| **Warning Days** / **Critical Days** | Backup-age alert thresholds, not the shield's freshness window. Leave these unchanged unless you intend to change alert policy. |
+
+For a three-day cycle, **Fresh Hours = 72** keeps a completed backup fresh
+through 72 hours. **Stale Hours = 96**, for example, leaves a further day in
+the stale band. Choose any scheduling margin to match your existing backup
+policy; these are global display settings, not a change to the backup schedule.
+Review the alert-day values before saving, then check the same guest's badge.
+The completed backup's time does not change, and missing or unknown backup
+evidence is not made healthy by a longer freshness window.
+
+**v6.5.0 caution:** if **Critical Days** is Off while **Warning Days** is
+enabled, do not save threshold edits on that version: its editor can re-enable
+critical alerts at the warning age. Cancel rather than changing alert policy
+just to remove an amber badge.
+
+If the problem is missing backups or conflicting protection evidence rather
+than an expected longer cycle, use the [backup health checks](#backups-are-visible-but-coverage-says-unprotected)
+instead. Do not run another backup, change retention, disable alerts or clear
+History just to change a colour.
+
### Backups are visible but Coverage says Unprotected
The **Backup health** strip and the backup list answer different questions.
diff --git a/frontend-modern/public/docs/PBS.md b/frontend-modern/public/docs/PBS.md
index bfe3bb3981..bfb61548c9 100644
--- a/frontend-modern/public/docs/PBS.md
+++ b/frontend-modern/public/docs/PBS.md
@@ -303,6 +303,39 @@ private keys. If help is needed, provide only the HTTP status, relevant redacted
error and which expected reading is missing. Do not clear History or recreate a
working connection to make missing data look resolved.
+### Backup age colours for a longer backup cycle
+
+The VM/LXC backup shield uses **hours**, separately from the backup-age alert
+thresholds in **days**. An amber age badge does not by itself mean that a
+backup failed or that a notification was sent.
+
+Open **Alerts → Thresholds → Proxmox**, then expand **Recovery**. In
+**Global Defaults**:
+
+| Control | What it changes |
+| --- | --- |
+| **Fresh Hours** | How long the latest completed backup keeps a green shield. The default is 24 hours. |
+| **Stale Hours** | The end of the next age band, after which the backup is classified as overdue. Keep it at least as large as Fresh Hours. |
+| **Warning Days** / **Critical Days** | Backup-age alert thresholds, not the shield's freshness window. Leave these unchanged unless you intend to change alert policy. |
+
+For a three-day cycle, **Fresh Hours = 72** keeps a completed backup fresh
+through 72 hours. **Stale Hours = 96**, for example, leaves a further day in
+the stale band. Choose any scheduling margin to match your existing backup
+policy; these are global display settings, not a change to the backup schedule.
+Review the alert-day values before saving, then check the same guest's badge.
+The completed backup's time does not change, and missing or unknown backup
+evidence is not made healthy by a longer freshness window.
+
+**v6.5.0 caution:** if **Critical Days** is Off while **Warning Days** is
+enabled, do not save threshold edits on that version: its editor can re-enable
+critical alerts at the warning age. Cancel rather than changing alert policy
+just to remove an amber badge.
+
+If the problem is missing backups or conflicting protection evidence rather
+than an expected longer cycle, use the [backup health checks](#backups-are-visible-but-coverage-says-unprotected)
+instead. Do not run another backup, change retention, disable alerts or clear
+History just to change a colour.
+
### Backups are visible but Coverage says Unprotected
The **Backup health** strip and the backup list answer different questions.
diff --git a/frontend-modern/src/features/docs/__tests__/backupFreshnessDocs.test.ts b/frontend-modern/src/features/docs/__tests__/backupFreshnessDocs.test.ts
new file mode 100644
index 0000000000..a5ea5fbdf8
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/backupFreshnessDocs.test.ts
@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createRoot } from 'solid-js';
+import { describe, expect, it } from 'vitest';
+import { getBackupInfo } from '@/utils/format';
+import { ALERT_THRESHOLDS_SECTION_TITLE_BACKUPS } from '@/utils/alertThresholdsPresentation';
+import { useThresholdsRecoveryDefaultsState } from '@/features/alerts/thresholds/hooks/useThresholdsRecoveryDefaultsState';
+import type { ThresholdsTableProps } from '@/features/alerts/thresholds/types';
+import { createGuideFixture } from './guideFixture';
+
+const read = (name: string) => readFileSync(resolve(process.cwd(), '../docs', `${name}.md`), 'utf8');
+const article = createGuideFixture(read);
+const text = (node: Element) => node.textContent!.replace(/\s+/g, ' ').trim();
+const now = new Date('2026-10-12T08:00:00Z');
+const hour = 3_600_000;
+
+describe('backup-cycle help matches the existing controls', () => {
+ it('names the actual Recovery group and separates display hours from alert days', () => {
+ const guide = article('PBS');
+ const heading = guide.querySelector('#backup-age-colours-for-a-longer-backup-cycle');
+ expect(heading).not.toBeNull();
+ expect(text(guide)).toContain(`Alerts → Thresholds → Proxmox, then expand ${ALERT_THRESHOLDS_SECTION_TITLE_BACKUPS}`);
+ expect(text(guide)).toContain('Global Defaults');
+ const table = heading!.nextElementSibling!.nextElementSibling!.nextElementSibling!;
+ expect(table.tagName).toBe('TABLE');
+ expect([...table.querySelectorAll('tbody tr td:first-child')].map(text)).toEqual([
+ 'Fresh Hours', 'Stale Hours', 'Warning Days / Critical Days',
+ ]);
+ expect(text(table)).toContain('not the shield\'s freshness window');
+ expect(readFileSync(resolve(process.cwd(), 'public/docs/PBS.md'), 'utf8')).toBe(read('PBS'));
+ });
+
+ it('reproduces the one-day badge and validates the documented three-day boundary', () => {
+ const completed = now.getTime() - 25 * hour;
+ expect(getBackupInfo(completed, undefined, now).status).toBe('stale');
+ const thresholds = { freshHours: 72, staleHours: 96 };
+ expect(getBackupInfo(completed, thresholds, now).status).toBe('fresh');
+ for (const [hours, expected] of [[72, 'fresh'], [73, 'stale'], [96, 'stale'], [97, 'overdue']] as const) {
+ expect(getBackupInfo(now.getTime() - hours * hour, thresholds, now).status).toBe(expected);
+ }
+ expect(getBackupInfo(completed, thresholds, now).ageMs).toBe(25 * hour);
+ expect(text(article('PBS'))).toContain('Fresh Hours = 72');
+ expect(text(article('PBS'))).toContain('Stale Hours = 96');
+ });
+
+ it('does not turn missing, future or invalid evidence into a fresh backup', () => {
+ const thresholds = { freshHours: 72, staleHours: 96 };
+ expect(getBackupInfo(null, thresholds, now).status).toBe('never');
+ expect(getBackupInfo('invalid', thresholds, now).status).toBe('unknown');
+ expect(getBackupInfo(now.getTime() + hour, thresholds, now).status).toBe('unknown');
+ const guide = article('PBS');
+ expect(text(guide)).toContain('missing or unknown backup evidence is not made healthy');
+ expect(guide.querySelector('a[href="#backups-are-visible-but-coverage-says-unprotected"]')).not.toBeNull();
+ expect(text(guide)).toContain('Do not run another backup, change retention, disable alerts or clear History');
+ });
+
+ it('retains the stable-version caution while the repaired editor preserves Off', () => {
+ const config = { enabled: true, warningDays: 3, criticalDays: 0, freshHours: 72, staleHours: 96 };
+ const result = createRoot((dispose) => {
+ const state = useThresholdsRecoveryDefaultsState({
+ backupDefaults: () => config,
+ snapshotDefaults: () => ({ enabled: false, warningDays: 0, criticalDays: 0 }),
+ } as ThresholdsTableProps);
+ const sanitized = state.sanitizeBackupConfig(config);
+ dispose();
+ return sanitized;
+ });
+ expect(result).toMatchObject(config);
+ const guide = text(article('PBS'));
+ expect(guide).toContain('v6.5.0 caution:');
+ expect(guide).toContain('do not save threshold edits on that version');
+ expect(guide).toContain('Cancel rather than changing alert policy');
+ });
+});