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.

Make safe troubleshooting paths reachable from the first screen

pulse-triage[bot]c46190050949
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 1ab6df91f3..5292d79942 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -1,5 +1,55 @@
# 🔧 Troubleshooting Guide
+## Choose the affected workflow
+
+Start with the symptom below, using observations you already have. A restart,
+reinstall or new diagnostic run is not a prerequisite for getting help.
+
+**If a guest is unresponsive, a backup is in freeze/thaw, or an earlier guest
+request's state is uncertain, read [Backup safety](VM_DISK_MONITORING.md#backup-safety)
+first.** Do not run Diagnostics, force guest-agent probes or repeat a backup to
+fill a report. A successful backup task or responsive console alone does not
+establish safe recovery.
+
+- **Cannot sign in:** use [local password recovery](TROUBLESHOOTING.md#i-forgot-my-password)
+ or [401 and login failures](TROUBLESHOOTING.md#cannot-login--401-unauthorized),
+ according to the existing authentication method. Do not delete configuration
+ or repeat first-time setup.
+- **Update failed or its result is uncertain:** start with
+ [Pulse server update checks](AUTO_UPDATE.md#update-failed). An update of a
+ monitored container is a different job; use
+ [Docker workload update checks](DOCKER.md#check-a-failed-or-pending-workload-update).
+ Preserve the current state and rollback evidence; do not repeat the attempt.
+- **Agent host is missing or reporting is rejected:** check the existing
+ [agent authentication and reporting evidence](UNIFIED_AGENT.md#agent-lookup-returns-http-401-or-403)
+ before replacing a token or reinstalling. Installer success is not an accepted
+ report.
+- **Guest readings are missing or disagree:** distinguish
+ [current, retained and unavailable disks](VM_DISK_MONITORING.md#current-retained-and-unavailable-disk-readings)
+ from [guest memory pressure](TROUBLESHOOTING.md#guest-memory-is-high-but-available-memory-is-plentiful).
+ Unknown is not zero, and a working Pulse Agent view does not prove API recovery.
+- **Proxmox data belongs to the wrong host, or healthy jobs look Pending:** use
+ [cross-installation identity checks](TROUBLESHOOTING.md#monitoring-is-mixed-between-proxmox-installations)
+ or [replication status checks](TROUBLESHOOTING.md#replication-jobs-are-pending-stale-or-missing).
+ Do not rename, remove or re-enrol resources to create evidence.
+- **TrueNAS readings are stale or absent:** use
+ [TrueNAS data checks](TRUENAS.md#stale-truenas-data), keeping the platform API
+ and Pulse Agent paths separate.
+- **Pulse itself uses more memory, CPU or disk writes:** use
+ [memory baseline and growth checks](TROUBLESHOOTING.md#memory-use-keeps-growing)
+ or [CPU and write-rate checks](TROUBLESHOOTING.md#excessive-cpu-writes-or-database-growth).
+ Guest usage and database size are different measurements.
+- **Notification Test works but alerts do not arrive:** follow
+ [ordinary delivery checks](TROUBLESHOOTING.md#test-succeeds-but-real-alerts-are-missing).
+ Do not trigger an alert or replay the queue just to complete a report.
+- **Private information was posted:** follow
+ [disclosure containment](TROUBLESHOOTING.md#if-you-already-posted-private-information).
+ Deleting the public copy does not revoke a credential.
+
+If none fits, use [Getting Help](TROUBLESHOOTING.md#-getting-help).
+Review evidence locally before sharing it; unknown or unavailable details are
+valid, and a full configuration, journal or network export is not required.
+
## ⚡ Quick Fixes
### I forgot my password
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index 1ab6df91f3..5292d79942 100644
--- a/frontend-modern/public/docs/TROUBLESHOOTING.md
+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md
@@ -1,5 +1,55 @@
# 🔧 Troubleshooting Guide
+## Choose the affected workflow
+
+Start with the symptom below, using observations you already have. A restart,
+reinstall or new diagnostic run is not a prerequisite for getting help.
+
+**If a guest is unresponsive, a backup is in freeze/thaw, or an earlier guest
+request's state is uncertain, read [Backup safety](VM_DISK_MONITORING.md#backup-safety)
+first.** Do not run Diagnostics, force guest-agent probes or repeat a backup to
+fill a report. A successful backup task or responsive console alone does not
+establish safe recovery.
+
+- **Cannot sign in:** use [local password recovery](TROUBLESHOOTING.md#i-forgot-my-password)
+ or [401 and login failures](TROUBLESHOOTING.md#cannot-login--401-unauthorized),
+ according to the existing authentication method. Do not delete configuration
+ or repeat first-time setup.
+- **Update failed or its result is uncertain:** start with
+ [Pulse server update checks](AUTO_UPDATE.md#update-failed). An update of a
+ monitored container is a different job; use
+ [Docker workload update checks](DOCKER.md#check-a-failed-or-pending-workload-update).
+ Preserve the current state and rollback evidence; do not repeat the attempt.
+- **Agent host is missing or reporting is rejected:** check the existing
+ [agent authentication and reporting evidence](UNIFIED_AGENT.md#agent-lookup-returns-http-401-or-403)
+ before replacing a token or reinstalling. Installer success is not an accepted
+ report.
+- **Guest readings are missing or disagree:** distinguish
+ [current, retained and unavailable disks](VM_DISK_MONITORING.md#current-retained-and-unavailable-disk-readings)
+ from [guest memory pressure](TROUBLESHOOTING.md#guest-memory-is-high-but-available-memory-is-plentiful).
+ Unknown is not zero, and a working Pulse Agent view does not prove API recovery.
+- **Proxmox data belongs to the wrong host, or healthy jobs look Pending:** use
+ [cross-installation identity checks](TROUBLESHOOTING.md#monitoring-is-mixed-between-proxmox-installations)
+ or [replication status checks](TROUBLESHOOTING.md#replication-jobs-are-pending-stale-or-missing).
+ Do not rename, remove or re-enrol resources to create evidence.
+- **TrueNAS readings are stale or absent:** use
+ [TrueNAS data checks](TRUENAS.md#stale-truenas-data), keeping the platform API
+ and Pulse Agent paths separate.
+- **Pulse itself uses more memory, CPU or disk writes:** use
+ [memory baseline and growth checks](TROUBLESHOOTING.md#memory-use-keeps-growing)
+ or [CPU and write-rate checks](TROUBLESHOOTING.md#excessive-cpu-writes-or-database-growth).
+ Guest usage and database size are different measurements.
+- **Notification Test works but alerts do not arrive:** follow
+ [ordinary delivery checks](TROUBLESHOOTING.md#test-succeeds-but-real-alerts-are-missing).
+ Do not trigger an alert or replay the queue just to complete a report.
+- **Private information was posted:** follow
+ [disclosure containment](TROUBLESHOOTING.md#if-you-already-posted-private-information).
+ Deleting the public copy does not revoke a credential.
+
+If none fits, use [Getting Help](TROUBLESHOOTING.md#-getting-help).
+Review evidence locally before sharing it; unknown or unavailable details are
+valid, and a full configuration, journal or network export is not required.
+
## ⚡ Quick Fixes
### I forgot my password
diff --git a/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts b/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts
new file mode 100644
index 0000000000..168ee8554e
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts
@@ -0,0 +1,111 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { renderDocMarkdown, stripLeadingTitle } from '../docMarkdown';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');
+const shippedDocs = path.join(repoRoot, 'frontend-modern/public/docs');
+const source = readFileSync(path.join(shippedDocs, 'TROUBLESHOOTING.md'), 'utf8');
+
+function renderGuide(name: string, markdown?: string): HTMLElement {
+ const article = document.createElement('article');
+ article.innerHTML = renderDocMarkdown(
+ stripLeadingTitle(markdown ?? readFileSync(path.join(shippedDocs, `${name}.md`), 'utf8')),
+ name,
+ );
+ return article;
+}
+
+function entry(): HTMLElement {
+ const article = renderGuide('TROUBLESHOOTING', source);
+ const heading = article.querySelector('h2');
+ expect(heading?.id).toBe('choose-the-affected-workflow');
+ const section = document.createElement('section');
+ for (let next = heading!.nextElementSibling; next; next = next.nextElementSibling) {
+ if (next.tagName === 'H2') break;
+ section.appendChild(next.cloneNode(true));
+ }
+ return section;
+}
+
+const prose = (element: HTMLElement): string =>
+ (element.textContent ?? '').replace(/\s+/g, ' ').trim();
+
+describe('troubleshooting workflow entry', () => {
+ it('puts guest incident safety before the symptom links and any collection recipe', () => {
+ const section = entry();
+ const link = section.querySelector('a');
+ expect(link?.getAttribute('href')).toBe('/docs/VM_DISK_MONITORING#backup-safety');
+ expect(section.querySelectorAll('li')).toHaveLength(9);
+ expect(section.querySelector('pre')).toBeNull();
+ const beforeList = [...section.children]
+ .slice(
+ 0,
+ [...section.children].findIndex((element) => element.tagName === 'UL'),
+ )
+ .map((element) => prose(element as HTMLElement))
+ .join(' ');
+ expect(beforeList).toContain("an earlier guest request's state is uncertain");
+ expect(beforeList).toContain(
+ 'Do not run Diagnostics, force guest-agent probes or repeat a backup',
+ );
+ expect(beforeList).toContain('responsive console alone does not establish safe recovery');
+ });
+
+ it('keeps server updates, workload updates and reporting acceptance distinct', () => {
+ const section = entry();
+ const rows = section.querySelectorAll('li');
+ expect(prose(rows[1] as HTMLElement)).toContain(
+ 'An update of a monitored container is a different job',
+ );
+ const updateLinks = [...rows[1].querySelectorAll('a')].map((link) => link.getAttribute('href'));
+ expect(updateLinks).toEqual([
+ '/docs/AUTO_UPDATE#update-failed',
+ '/docs/DOCKER#check-a-failed-or-pending-workload-update',
+ ]);
+ expect(prose(rows[1] as HTMLElement)).toContain(
+ 'Preserve the current state and rollback evidence',
+ );
+ expect(prose(rows[2] as HTMLElement)).toContain('Installer success is not an accepted report');
+ expect(prose(rows[3] as HTMLElement)).toContain(
+ 'a working Pulse Agent view does not prove API recovery',
+ );
+ expect(prose(rows[6] as HTMLElement)).toContain(
+ 'Guest usage and database size are different measurements',
+ );
+ });
+
+ it('routes every entry to an existing shipped heading in the production viewer', () => {
+ const links = [...entry().querySelectorAll('a[href]')];
+ expect(links).toHaveLength(16);
+ for (const link of links) {
+ const href = link.getAttribute('href')!;
+ const match = /^\/docs\/([^#]+)#(.+)$/.exec(href);
+ expect(match, href).not.toBeNull();
+ const target = renderGuide(match![1]).querySelector(`[id="${match![2]}"]`);
+ expect(target, href).not.toBeNull();
+ expect(target?.tagName, href).toMatch(/^H[1-6]$/);
+ expect(link.hasAttribute('data-doc-link'), href).toBe(true);
+ expect(link.hasAttribute('target'), href).toBe(false);
+ }
+ });
+
+ it('keeps the source and shipped entry identical and preserves existing anchors', () => {
+ const canonical = readFileSync(path.join(repoRoot, 'docs/TROUBLESHOOTING.md'), 'utf8');
+ expect(source).toBe(canonical);
+ const article = renderGuide('TROUBLESHOOTING');
+ for (const id of [
+ 'i-forgot-my-password',
+ 'memory-use-keeps-growing',
+ 'collect-diagnostics-safely',
+ 'recovery-mode',
+ '-getting-help',
+ ]) {
+ expect(article.querySelector(`[id="${id}"]`), id).not.toBeNull();
+ }
+ expect(prose(entry())).toContain('unknown or unavailable details are valid');
+ expect(prose(entry())).toContain('Deleting the public copy does not revoke a credential');
+ expect(prose(entry())).toContain('Do not trigger an alert or replay the queue');
+ });
+});