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 unknown restore-point sizes without implying empty backups

pulse-triage[bot]f93ef2486523
diff --git a/docs/RECOVERY.md b/docs/RECOVERY.md
index 03c54f5067..df294431e8 100644
--- a/docs/RECOVERY.md
+++ b/docs/RECOVERY.md
@@ -68,7 +68,8 @@ answer different questions:
counts normally in **Count**. Amber marks days with unknown sizes, not zero
volume. When a day mixes known and unknown sizes, its known volume is a lower
bound, not a complete total. These are recorded artifact sizes, not
- PBS datastore usage or deduplicated physical space.
+ PBS datastore usage or deduplicated physical space. For a row marked
+ **Unknown size**, use the [individual size checks](#restore-point-sizes-and-unknown-values).
- Guest **snapshots** can contribute to completed-point and chart totals.
They are not independent backups and do not fill Coverage's **Last backup**.
If a completed backup's date is unavailable or in the future, the latest
@@ -97,6 +98,30 @@ use the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unpro
An unresponsive guest or uncertain freeze/thaw needs the
[backup safety precaution](VM_DISK_MONITORING.md#backup-safety), not a chart check.
+## Restore-point sizes and unknown values
+
+In **Proxmox → Backups → By date**, **Unknown size** means no usable byte
+count was reported, not that the restore point is empty, corrupt or failed.
+Missing sizes and zero placeholders both remain unknown. The point stays in
+the inventory; its completion, verification and protection are separate evidence.
+A positive size is the reported artifact size, not the guest's disk capacity,
+PBS datastore usage or deduplicated physical space.
+
+On a wide screen, use the **Size** column. Sorting it keeps measured sizes
+ahead of unknowns in **both directions**; reversing the sort reverses only
+the measured order. On a phone, expand the restore-point row and read **Size**
+under **Restore point**. A hidden column is not a missing reading. In
+**Coverage**, expand the workload to see each point's size; narrow layouts
+show it alongside the point's identity. One known size does not fill the gaps
+for other points. For daily totals, see [why counts and volume differ](#why-proxmox-backup-counts-differ).
+
+Compare the same workload, repository and time in existing provider records
+before drawing a conclusion. Do not run another backup, verification or
+restore, delete a point or clear History just to obtain a size. Older versions
+may show a dash or zero instead; neither establishes an empty backup. If a
+guest is unresponsive or thaw is uncertain, stop this display comparison and
+follow [Backup safety](VM_DISK_MONITORING.md#backup-safety).
+
## 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 03c54f5067..df294431e8 100644
--- a/frontend-modern/public/docs/RECOVERY.md
+++ b/frontend-modern/public/docs/RECOVERY.md
@@ -68,7 +68,8 @@ answer different questions:
counts normally in **Count**. Amber marks days with unknown sizes, not zero
volume. When a day mixes known and unknown sizes, its known volume is a lower
bound, not a complete total. These are recorded artifact sizes, not
- PBS datastore usage or deduplicated physical space.
+ PBS datastore usage or deduplicated physical space. For a row marked
+ **Unknown size**, use the [individual size checks](#restore-point-sizes-and-unknown-values).
- Guest **snapshots** can contribute to completed-point and chart totals.
They are not independent backups and do not fill Coverage's **Last backup**.
If a completed backup's date is unavailable or in the future, the latest
@@ -97,6 +98,30 @@ use the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unpro
An unresponsive guest or uncertain freeze/thaw needs the
[backup safety precaution](VM_DISK_MONITORING.md#backup-safety), not a chart check.
+## Restore-point sizes and unknown values
+
+In **Proxmox → Backups → By date**, **Unknown size** means no usable byte
+count was reported, not that the restore point is empty, corrupt or failed.
+Missing sizes and zero placeholders both remain unknown. The point stays in
+the inventory; its completion, verification and protection are separate evidence.
+A positive size is the reported artifact size, not the guest's disk capacity,
+PBS datastore usage or deduplicated physical space.
+
+On a wide screen, use the **Size** column. Sorting it keeps measured sizes
+ahead of unknowns in **both directions**; reversing the sort reverses only
+the measured order. On a phone, expand the restore-point row and read **Size**
+under **Restore point**. A hidden column is not a missing reading. In
+**Coverage**, expand the workload to see each point's size; narrow layouts
+show it alongside the point's identity. One known size does not fill the gaps
+for other points. For daily totals, see [why counts and volume differ](#why-proxmox-backup-counts-differ).
+
+Compare the same workload, repository and time in existing provider records
+before drawing a conclusion. Do not run another backup, verification or
+restore, delete a point or clear History just to obtain a size. Older versions
+may show a dash or zero instead; neither establishes an empty backup. If a
+guest is unresponsive or thaw is uncertain, stop this display comparison and
+follow [Backup safety](VM_DISK_MONITORING.md#backup-safety).
+
## What the evidence means
Keep these observations separate:
diff --git a/frontend-modern/src/features/docs/__tests__/backupSizeGuide.test.ts b/frontend-modern/src/features/docs/__tests__/backupSizeGuide.test.ts
new file mode 100644
index 0000000000..a85522785e
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/backupSizeGuide.test.ts
@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { buildProxmoxBackupRecoveryModel } from '@/features/proxmox/proxmoxBackupRecoveryModel';
+import {
+ BACKUP_IDENTITY_NOW,
+ identityGuest,
+ identityPBS,
+} from '@/features/proxmox/__fixtures__/backupIdentity';
+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 = '#restore-point-sizes-and-unknown-values';
+const section = () => {
+ const heading = guide('RECOVERY').querySelector(fragment);
+ expect(heading?.textContent).toBe('Restore-point sizes and unknown values');
+ 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, ' ');
+
+describe('restore-point size guidance', () => {
+ it('ships a reachable explanation with the same wide and narrow inspection labels', () => {
+ expect(read('frontend-modern/public/docs/RECOVERY.md')).toBe(read('docs/RECOVERY.md'));
+ expect(guide('RECOVERY').querySelector(`a[href="${fragment}"]`)?.textContent).toBe(
+ 'individual size checks',
+ );
+ const consumer = read('frontend-modern/src/features/proxmox/ProxmoxRecoverableTable.tsx');
+ for (const label of ['Unknown size', 'Restore point', 'Size']) {
+ expect(text()).toContain(label);
+ expect(consumer).toContain(`'${label}'`);
+ }
+ expect(text()).toContain('On a phone, expand the restore-point row');
+ expect(text()).toContain('A hidden column is not a missing reading');
+ expect(text()).toContain('Sorting it keeps measured sizes ahead of unknowns in both directions');
+ expect(text()).toContain("narrow layouts show it alongside the point's identity");
+ });
+
+ it.each([undefined, 0, 1])("explains the current model's size evidence for %s", (size) => {
+ const model = buildProxmoxBackupRecoveryModel({
+ workloads: [identityGuest('fixture', 'east', 'pve-1')],
+ pbsBackups: [identityPBS({ size })],
+ archives: [],
+ snapshots: [],
+ tasks: [],
+ nowMs: BACKUP_IDENTITY_NOW,
+ });
+ expect(model.recoverableArtifacts[0].size).toBe(size ? size : undefined);
+ expect(model.coverageSummary.recoverableArtifacts).toBe(1);
+ expect(text()).toContain('Missing sizes and zero placeholders both remain unknown');
+ expect(text()).toContain('not that the restore point is empty, corrupt or failed');
+ expect(text()).toContain('its completion, verification and protection are separate evidence');
+ expect(text()).toContain("not the guest's disk capacity");
+ });
+
+ it('uses existing records and keeps size inspection separate from guest recovery', () => {
+ const copy = text();
+ expect(copy).toContain('Compare the same workload, repository and time');
+ expect(copy).toContain('Do not run another backup, verification or restore');
+ expect(copy).toContain('delete a point or clear History just to obtain a size');
+ expect(copy).toContain('Older versions may show a dash or zero instead');
+ expect(copy).toContain('stop this display comparison');
+ expect(section().querySelector('pre')).toBeNull();
+ for (const [name, anchor] of [
+ ['RECOVERY', 'why-proxmox-backup-counts-differ'],
+ ['VM_DISK_MONITORING', 'backup-safety'],
+ ]) {
+ const href = name === 'RECOVERY' ? `#${anchor}` : `/docs/${name}#${anchor}`;
+ expect(section().querySelector(`a[href="${href}"]`)).not.toBeNull();
+ expect(guide(name).querySelector(`#${anchor}`)).not.toBeNull();
+ }
+ });
+});