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 PBS datastore counts without implying backup recovery
pulse-triage[bot]e5ab29be5d33
diff --git a/docs/PBS.md b/docs/PBS.mdindex 91b177875d..79a26c8dbc 100644--- a/docs/PBS.md+++ b/docs/PBS.md@@ -199,6 +199,10 @@ If you have multiple PBS servers, add each one separately in Settings. Pulse wil- Show backups from all servers under **Proxmox → Backups** (`/proxmox/backups`)- Deduplicate if the same backup appears via both PVE passthrough and direct PBS+For the **Backups** number beside each datastore, see+[backup server counts](#what-the-backup-server-count-means). It is not a+verified-recovery total.+---## Troubleshooting@@ -518,6 +522,40 @@ Pulse Agent's stored History request. Restarting that guest is not a diagnosisof an empty PBS chart. See [VM Disk Monitoring](VM_DISK_MONITORING.md) if theseparate symptom is missing filesystem information in a PVE VM row.+### What the backup server count means++In **Proxmox → Backups**, each **Backup server** datastore row has a+**Backups** count. It counts the loaded direct PBS inventory entries for that+exact configured connection and datastore, across its namespaces. It is not a+count of guests, completed or verified restore points, or physical files.+An in-progress or unverified entry can count too.++| Backups cell | What it establishes |+| --- | --- |+| A number, including **0** | The number of matching entries in the loaded inventory. **0** does not prove that the datastore is empty or that every expected backup was collected. |+| **Loading** | The PBS inventory has not loaded yet; this is not a zero count. |+| **Unavailable** | The PBS inventory read failed; this is not a zero count. Server reachability and datastore capacity can still be shown independently. |+| **—** | This server row has no reported datastore to count, not an empty backup repository. |++The table can hide **Backups** on a narrow screen. A hidden column is not+missing inventory. These counts are separate from the filtered **By date**+list and its completed-point charts; see+[why backup counts differ](RECOVERY.md#why-proxmox-backup-counts-differ).++Compare existing records for the same connection, datastore and namespace.+Shared hostnames, display labels or guest IDs do not establish the same reader;+an entry without reader or datastore identity cannot fill a named row's count.+Keep private names consistent when redacting a discrepancy. Do not share full+inventories or credentials, rename connections, widen permissions, clear History+or run another backup to make counts agree. Use the+[loading guidance](#slow-backup-loading) for an existing read error, not repeated+retries. Older versions may attribute counts differently; preserve the existing+native records rather than changing the setup to match Pulse.++A count is not protection, verification, restore readiness or guest thaw. If a+guest is unresponsive or freeze/thaw is uncertain, stop the display comparison+and follow [Backup safety](VM_DISK_MONITORING.md#backup-safety).+### Slow Backup LoadingA slow backup list does not establish an encrypted-datastore or PVE-proxydiff --git a/frontend-modern/public/docs/PBS.md b/frontend-modern/public/docs/PBS.mdindex 91b177875d..79a26c8dbc 100644--- a/frontend-modern/public/docs/PBS.md+++ b/frontend-modern/public/docs/PBS.md@@ -199,6 +199,10 @@ If you have multiple PBS servers, add each one separately in Settings. Pulse wil- Show backups from all servers under **Proxmox → Backups** (`/proxmox/backups`)- Deduplicate if the same backup appears via both PVE passthrough and direct PBS+For the **Backups** number beside each datastore, see+[backup server counts](#what-the-backup-server-count-means). It is not a+verified-recovery total.+---## Troubleshooting@@ -518,6 +522,40 @@ Pulse Agent's stored History request. Restarting that guest is not a diagnosisof an empty PBS chart. See [VM Disk Monitoring](VM_DISK_MONITORING.md) if theseparate symptom is missing filesystem information in a PVE VM row.+### What the backup server count means++In **Proxmox → Backups**, each **Backup server** datastore row has a+**Backups** count. It counts the loaded direct PBS inventory entries for that+exact configured connection and datastore, across its namespaces. It is not a+count of guests, completed or verified restore points, or physical files.+An in-progress or unverified entry can count too.++| Backups cell | What it establishes |+| --- | --- |+| A number, including **0** | The number of matching entries in the loaded inventory. **0** does not prove that the datastore is empty or that every expected backup was collected. |+| **Loading** | The PBS inventory has not loaded yet; this is not a zero count. |+| **Unavailable** | The PBS inventory read failed; this is not a zero count. Server reachability and datastore capacity can still be shown independently. |+| **—** | This server row has no reported datastore to count, not an empty backup repository. |++The table can hide **Backups** on a narrow screen. A hidden column is not+missing inventory. These counts are separate from the filtered **By date**+list and its completed-point charts; see+[why backup counts differ](RECOVERY.md#why-proxmox-backup-counts-differ).++Compare existing records for the same connection, datastore and namespace.+Shared hostnames, display labels or guest IDs do not establish the same reader;+an entry without reader or datastore identity cannot fill a named row's count.+Keep private names consistent when redacting a discrepancy. Do not share full+inventories or credentials, rename connections, widen permissions, clear History+or run another backup to make counts agree. Use the+[loading guidance](#slow-backup-loading) for an existing read error, not repeated+retries. Older versions may attribute counts differently; preserve the existing+native records rather than changing the setup to match Pulse.++A count is not protection, verification, restore readiness or guest thaw. If a+guest is unresponsive or freeze/thaw is uncertain, stop the display comparison+and follow [Backup safety](VM_DISK_MONITORING.md#backup-safety).+### Slow Backup LoadingA slow backup list does not establish an encrypted-datastore or PVE-proxydiff --git a/frontend-modern/src/features/docs/__tests__/pbsServerCountsGuide.test.ts b/frontend-modern/src/features/docs/__tests__/pbsServerCountsGuide.test.tsnew file mode 100644index 0000000000..b010e1f964--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/pbsServerCountsGuide.test.ts@@ -0,0 +1,126 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, it } from 'vitest';+import type { Resource } from '@/types/resource';+import { buildBackupServerRows } from '@/features/proxmox/ProxmoxBackupServersTable';+import { parsePBSBackupInventory } from '@/features/proxmox/proxmoxBackupInventory';+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(`frontend-modern/public/docs/${name}.md`));+const fragment = '#what-the-backup-server-count-means';+const section = () => {+ const heading = guide('PBS').querySelector(fragment);+ expect(heading?.textContent).toBe('What the backup server count means');+ const result = document.createElement('section');+ for (let next = heading!.nextElementSibling; next; next = next.nextElementSibling) {+ if (/^H[1-3]$/.test(next.tagName)) break;+ result.appendChild(next.cloneNode(true));+ }+ return result;+};+const text = () => section().textContent!.replace(/\s+/g, ' ');+const server = (name: string, datastore = 'tank'): Resource => ({+ id: `service-${name}`,+ name,+ displayName: 'Shared display name',+ type: 'pbs',+ status: 'online',+ lastSeen: 1_793_300_000_000,+ platformId: 'proxmox-pbs',+ platformType: 'proxmox-pbs',+ sourceType: 'api',+ pbs: {+ instanceId: `pbs-${name}`,+ hostname: 'shared.example.test',+ datastores: [{ name: datastore, total: 1000, used: 400 }],+ },+});+const entry = (instance: string | undefined, datastore = 'tank', namespace = '') => ({+ id: JSON.stringify([instance, datastore, namespace]),+ instance,+ datastore,+ namespace,+ backupType: 'vm',+ vmid: '100',+ backupTime: '2026-10-30T01:00:00Z',+ files: ['index.json.blob'],+});+const rows = (servers: Resource[], entries: ReturnType<typeof entry>[]) =>+ buildBackupServerRows(servers, parsePBSBackupInventory({ data: { backups: entries } }).backups);++describe('PBS server count guidance', () => {+ it('ships a discoverable section, matching mirror and usable related links', () => {+ expect(read('frontend-modern/public/docs/PBS.md')).toBe(read('docs/PBS.md'));+ expect(guide('PBS').querySelector(`a[href="/docs/PBS${fragment}"]`)?.textContent).toBe(+ 'backup server counts',+ );+ for (const [name, hash] of [+ ['RECOVERY', '#why-proxmox-backup-counts-differ'],+ ['PBS', '#slow-backup-loading'],+ ['VM_DISK_MONITORING', '#backup-safety'],+ ]) {+ expect(section().querySelector(`a[href="/docs/${name}${hash}"]`)).not.toBeNull();+ expect(guide(name).querySelector(hash)).not.toBeNull();+ }+ });++ it('explains the real count across namespaces without filtering in-progress or unverified entries', () => {+ const entries = [entry('main'), entry('main', 'tank', 'child')];+ Object.assign(entries[1], { inProgress: true, verified: false });+ expect(rows([server('main')], entries)[0].backupCount).toBe(2);+ expect(text()).toContain('across its namespaces');+ expect(text()).toContain('An in-progress or unverified entry can count too');+ expect(text()).toContain('not a count of guests, completed or verified restore points');+ expect(text()).toContain('separate from the filtered By date list');+ });++ it('keeps a genuine matching zero separate from another reader, datastore or missing identity', () => {+ const result = rows(+ [server('main'), server('pbs-main')],+ [entry('pbs-main'), entry('main', 'other'), entry(undefined)],+ );+ expect(result.map((row) => [row.serverName, row.backupCount])).toEqual([+ ['main', 0],+ ['pbs-main', 1],+ ]);+ expect(text()).toContain('exact configured connection and datastore');+ expect(text()).toContain('0 does not prove that the datastore is empty');+ expect(text()).toContain('or that every expected backup was collected');+ expect(text()).toContain(+ 'an entry without reader or datastore identity cannot fill a named row',+ );+ expect(text()).toContain('Shared hostnames, display labels or guest IDs');+ });++ it('distinguishes inventory failure, loading, absent datastore and a hidden column from zero', () => {+ const meanings = [...section().querySelectorAll('tbody tr')].map((row) =>+ row.textContent!.replace(/\s+/g, ' ').trim(),+ );+ expect(meanings).toHaveLength(4);+ expect(meanings[1]).toContain('Loading The PBS inventory has not loaded yet');+ expect(meanings[2]).toContain('Unavailable The PBS inventory read failed');+ expect(meanings[2]).toContain(+ 'reachability and datastore capacity can still be shown independently',+ );+ expect(meanings[3]).toContain('— This server row has no reported datastore to count');+ expect(text()).toContain('A hidden column is not missing inventory');+ });++ it('keeps comparison passive and private, with a separate guest-safety exit', () => {+ for (const boundary of [+ 'Compare existing records',+ 'Do not share full inventories or credentials, rename connections, widen permissions',+ 'clear History or run another backup',+ 'not repeated retries',+ 'Older versions may attribute counts differently',+ 'A count is not protection, verification, restore readiness or guest thaw',+ 'stop the display comparison',+ ]) {+ expect(text()).toContain(boundary);+ }+ expect(section().querySelector('pre')).toBeNull();+ });+});