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
Explain completed backup counts without losing incomplete evidence
pulse-triage[bot]8bd7fa4f5d00
diff --git a/docs/RECOVERY.md b/docs/RECOVERY.mdindex 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 backupexists. [Check missing evidence](#missing-or-inconsistent-evidence) beforechanging 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 meansKeep these observations separate:diff --git a/frontend-modern/public/docs/RECOVERY.md b/frontend-modern/public/docs/RECOVERY.mdindex 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 backupexists. [Check missing evidence](#missing-or-inconsistent-evidence) beforechanging 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 meansKeep these observations separate:diff --git a/frontend-modern/src/features/docs/__tests__/completedBackupCountsDocs.test.ts b/frontend-modern/src/features/docs/__tests__/completedBackupCountsDocs.test.tsnew file mode 100644index 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`));+ }+ });+});