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 completed backup counts without losing incomplete evidence

pulse-triage[bot]8bd7fa4f5d00
diff --git a/docs/RECOVERY.md b/docs/RECOVERY.md
index 56603ddf6f..6e9b56e24c 100644
--- a/docs/RECOVERY.md
+++ b/docs/RECOVERY.md
@@ -45,6 +45,41 @@ the same columns or filters, and a missing reading is not proof that no backup
exists. [Check missing evidence](#missing-or-inconsistent-evidence) before
changing the provider or Pulse's stored data.
+## Why Proxmox backup counts differ
+
+In **Proxmox → Backups → By date**, the inventory and completed-point totals
+answer different questions:
+
+- **Backup entries** includes running and failed entries, kept for inspection.
+ The **completed restore points** total in **Backup health** excludes both,
+ even when an incomplete entry has a size or a verification flag. The total
+ covers the loaded inventory, not just the rows matching your list filters.
+- **Completed restore points per day** also requires a known, non-future date
+ within the selected chart range. An undated completed point can count in
+ Backup health but not in a daily column. A blank chart is not proof that
+ no backups exist; check any inventory loading or access warning first.
+- **Completed restore volume per day** adds only positive reported sizes for
+ those dated completed points. A point with no reported size can count as a
+ point without contributing volume. These are recorded artifact sizes, not
+ PBS datastore usage or deduplicated physical space.
+- Guest **snapshots** can contribute to completed-point and chart totals.
+ They are not independent backups and do not fill Coverage's **Latest backup**.
+ If a completed backup's date is unavailable or in the future, the latest
+ backup age stays unknown rather than choosing an older dated backup.
+
+Selecting a chart day filters the list; it does not make every listed entry
+complete. Use **Clear date filter** and clear restrictive search or list filters
+to inspect undated and incomplete entries. This changes only the display, not
+collection, permissions or retention. Older versions may use different labels.
+
+**Completed is not Verified, a tested restore or guest thaw.** Compare the same
+provider, guest, location and time using existing records, not just a count.
+Do not run a new backup, verification or restore, delete entries, or clear
+History to make totals agree. For contradictory PBS verification or protection,
+use the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unprotected).
+An unresponsive guest or uncertain freeze/thaw needs the
+[backup safety precaution](VM_DISK_MONITORING.md#backup-safety), not a chart check.
+
## What the evidence means
Keep these observations separate:
diff --git a/frontend-modern/public/docs/RECOVERY.md b/frontend-modern/public/docs/RECOVERY.md
index 56603ddf6f..6e9b56e24c 100644
--- a/frontend-modern/public/docs/RECOVERY.md
+++ b/frontend-modern/public/docs/RECOVERY.md
@@ -45,6 +45,41 @@ the same columns or filters, and a missing reading is not proof that no backup
exists. [Check missing evidence](#missing-or-inconsistent-evidence) before
changing the provider or Pulse's stored data.
+## Why Proxmox backup counts differ
+
+In **Proxmox → Backups → By date**, the inventory and completed-point totals
+answer different questions:
+
+- **Backup entries** includes running and failed entries, kept for inspection.
+ The **completed restore points** total in **Backup health** excludes both,
+ even when an incomplete entry has a size or a verification flag. The total
+ covers the loaded inventory, not just the rows matching your list filters.
+- **Completed restore points per day** also requires a known, non-future date
+ within the selected chart range. An undated completed point can count in
+ Backup health but not in a daily column. A blank chart is not proof that
+ no backups exist; check any inventory loading or access warning first.
+- **Completed restore volume per day** adds only positive reported sizes for
+ those dated completed points. A point with no reported size can count as a
+ point without contributing volume. These are recorded artifact sizes, not
+ PBS datastore usage or deduplicated physical space.
+- Guest **snapshots** can contribute to completed-point and chart totals.
+ They are not independent backups and do not fill Coverage's **Latest backup**.
+ If a completed backup's date is unavailable or in the future, the latest
+ backup age stays unknown rather than choosing an older dated backup.
+
+Selecting a chart day filters the list; it does not make every listed entry
+complete. Use **Clear date filter** and clear restrictive search or list filters
+to inspect undated and incomplete entries. This changes only the display, not
+collection, permissions or retention. Older versions may use different labels.
+
+**Completed is not Verified, a tested restore or guest thaw.** Compare the same
+provider, guest, location and time using existing records, not just a count.
+Do not run a new backup, verification or restore, delete entries, or clear
+History to make totals agree. For contradictory PBS verification or protection,
+use the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unprotected).
+An unresponsive guest or uncertain freeze/thaw needs the
+[backup safety precaution](VM_DISK_MONITORING.md#backup-safety), not a chart check.
+
## What the evidence means
Keep these observations separate:
diff --git a/frontend-modern/src/features/docs/__tests__/completedBackupCountsDocs.test.ts b/frontend-modern/src/features/docs/__tests__/completedBackupCountsDocs.test.ts
new file mode 100644
index 0000000000..f878b7092e
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/completedBackupCountsDocs.test.ts
@@ -0,0 +1,119 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { buildBackupActivityTimeline } from '@/features/proxmox/proxmoxBackupActivityPresentation';
+import {
+ isCompletedRecoveryArtifact,
+ selectWorkloadRecoveryArtifacts,
+ type RecoverableArtifact,
+} from '@/features/proxmox/proxmoxBackupRecoveryModel';
+import { createGuideFixture } from './guideFixture';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');
+const read = (file: string) => readFileSync(path.join(root, file), 'utf8');
+const guide = createGuideFixture((name) => read(`docs/${name}.md`));
+const section = () => {
+ const article = guide('RECOVERY');
+ const heading = article.querySelector('#why-proxmox-backup-counts-differ');
+ expect(heading?.textContent).toBe('Why Proxmox backup counts differ');
+ const result = document.createElement('section');
+ for (let next = heading!.nextElementSibling; next && next.tagName !== 'H2'; next = next.nextElementSibling) {
+ result.appendChild(next.cloneNode(true));
+ }
+ return result;
+};
+const text = () => section().textContent!.replace(/\s+/g, ' ');
+const now = new Date('2026-10-24T12:00:00Z');
+const point = (id: string, overrides: Partial<RecoverableArtifact> = {}): RecoverableArtifact => ({
+ id,
+ nativeId: id,
+ sourceKind: 'pbs',
+ sourceLabel: 'PBS',
+ workload: { key: 'fixture', type: 'vm', typeLabel: 'VM', label: 'Fixture VM', vmid: '100' },
+ createdAt: '2026-10-24T10:00:00Z',
+ createdMs: Date.parse('2026-10-24T10:00:00Z'),
+ location: 'fixture / (root)',
+ detail: '',
+ protected: false,
+ ...overrides,
+});
+
+describe('completed backup count guidance', () => {
+ it('ships the current visible labels and separates inventory, chart and list scope', () => {
+ expect(read('frontend-modern/public/docs/RECOVERY.md')).toBe(read('docs/RECOVERY.md'));
+ const copy = text();
+ const tableSource = read('frontend-modern/src/features/proxmox/ProxmoxBackupsTable.tsx');
+ for (const label of ['Completed restore points per day', 'Completed restore volume per day']) {
+ expect(copy).toContain(label);
+ expect(tableSource).toContain(label);
+ }
+ expect(tableSource).toContain('aria-label="Clear date filter"');
+ expect(copy).toContain('covers the loaded inventory, not just the rows matching your list filters');
+ expect(copy).toContain('Selecting a chart day filters the list');
+ expect(copy).toContain('Clear date filter');
+ expect(copy).toContain('This changes only the display, not collection, permissions or retention');
+ expect(copy).toContain('Older versions may use different labels');
+ });
+
+ it('keeps incomplete entries out of completed totals even with size and verification evidence', () => {
+ const entries = [
+ point('completed', { size: 100, verified: false }),
+ point('undated', { sourceKind: 'archive', createdAt: '', createdMs: undefined }),
+ point('snapshot', { sourceKind: 'snapshot' }),
+ point('running', { running: true, protected: true, verified: true, size: 500 }),
+ point('failed', { failed: true, protected: true, verified: true, size: 500 }),
+ ];
+ const completed = entries.filter(isCompletedRecoveryArtifact);
+ expect(entries).toHaveLength(5);
+ expect(completed.map((entry) => entry.id)).toEqual(['completed', 'undated', 'snapshot']);
+ const classify = (entry: RecoverableArtifact) =>
+ isCompletedRecoveryArtifact(entry) ? entry.sourceKind : null;
+ const dated = buildBackupActivityTimeline(7, entries, (entry) => entry.createdMs, classify, { now });
+ const volume = buildBackupActivityTimeline(7, entries, (entry) => entry.createdMs, classify, {
+ now,
+ getValue: (entry) => entry.size ?? 0,
+ });
+ expect(dated.points.reduce((sum, day) => sum + day.total, 0)).toBe(2);
+ expect(volume.points.reduce((sum, day) => sum + day.total, 0)).toBe(100);
+ const copy = text();
+ expect(copy).toContain('excludes both, even when an incomplete entry has a size or a verification flag');
+ expect(copy).toContain('An undated completed point can count in Backup health but not in a daily column');
+ expect(copy).toContain('no reported size can count as a point without contributing volume');
+ expect(copy).toContain('not PBS datastore usage or deduplicated physical space');
+ });
+
+ it('does not substitute a snapshot or older backup when chronology is unknown', () => {
+ const known = point('known');
+ const snapshot = point('snapshot', { sourceKind: 'snapshot' });
+ const snapshotOnly = selectWorkloadRecoveryArtifacts([snapshot], now.getTime());
+ expect(snapshotOnly.latestBackup).toBeUndefined();
+ expect(snapshotOnly.latestSnapshot?.id).toBe('snapshot');
+ for (const createdAt of ['', '2026-10-25T10:00:00Z']) {
+ const unknown = point('unknown', { createdAt, createdMs: undefined });
+ const selected = selectWorkloadRecoveryArtifacts([known, snapshot, unknown], now.getTime());
+ expect(selected.latestBackup).toBeUndefined();
+ expect(selected.ageUnknown?.backup).toBe(true);
+ }
+ expect(text()).toContain('They are not independent backups');
+ expect(text()).toContain("do not fill Coverage's Latest backup");
+ expect(text()).toContain('age stays unknown rather than choosing an older dated backup');
+ });
+
+ it('keeps display checks passive and links to shipped safety and evidence sections', () => {
+ const copy = text();
+ expect(copy).toContain('A blank chart is not proof that no backups exist');
+ expect(copy).toContain('check any inventory loading or access warning first');
+ expect(copy).toContain('Completed is not Verified, a tested restore or guest thaw');
+ expect(copy).toContain('Do not run a new backup, verification or restore, delete entries, or clear History');
+ expect(section().querySelector('pre')).toBeNull();
+ for (const [name, anchor] of [
+ ['PBS', 'backups-are-visible-but-coverage-says-unprotected'],
+ ['VM_DISK_MONITORING', 'backup-safety'],
+ ]) {
+ expect(section().querySelector(`a[href="/docs/${name}#${anchor}"]`)).not.toBeNull();
+ expect(guide(name).querySelector(`[id="${anchor}"]`)).not.toBeNull();
+ expect(read(`frontend-modern/public/docs/${name}.md`)).toBe(read(`docs/${name}.md`));
+ }
+ });
+});