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.

Find safe diagnostics without requiring another live run

pulse-triage[bot]6860dde3ef5a
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d991ed6512..b5760c181f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -62,8 +62,9 @@ and installer tooling.
- Include only evidence relevant to the symptom: a screenshot or exact redacted
error may be enough for a visual problem; existing logs or observations may
explain a connection or data failure. Diagnostics are optional, not a condition
- of reporting. If a result is already displayed in **Settings → Diagnostics**,
- its download buttons reuse that result without running checks again.
+ of reporting. If a result is already displayed in **Settings → Support →
+ Diagnostics & Health**, its download buttons reuse that result without running
+ checks again.
- **Run Diagnostics** can make live API and guest-agent requests. Do not run it
during a backup, freeze/thaw or an unresponsive-host incident just to file a
report. Keep the original evidence instead; a successful one-off check does
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index a55df71ab4..7255d4c3d8 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -1329,7 +1329,13 @@ your own VPN or tunnel when away from home.
### Collect diagnostics safely
-**Run Diagnostics** in **Settings → Diagnostics** is not just a passive export.
+Open **Settings → Support → Diagnostics & Health** in your existing authorised
+Pulse session (`/settings/support/diagnostics` on your Pulse URL). Opening this
+panel does not run diagnostics. If no result is displayed, the download buttons
+are absent: use the original errors or observations rather than running checks
+just to obtain an attachment. Diagnostics are optional, not a condition of reporting.
+
+**Run Diagnostics** (shown as **Run** on phones) is not just a passive export.
It can make live Proxmox/PBS API and guest-agent requests; results may also come
from a short-lived cache. Do not run it during a backup, freeze/thaw or an
unresponsive-host incident merely to obtain a report. Keep the original errors
@@ -1353,7 +1359,8 @@ information, including details echoed in errors or notes. Do not paste a
Share only evidence relevant to the symptom; a screenshot or exact redacted
error may be enough. See [Getting Help](#-getting-help).
-The **Support Bundle** download in **System Logs** is a different export: it can
+The **Support Bundle** download in **Settings → Support → System Logs** is a
+different export: it can
contain a complete log file or server buffer plus configuration and environment
information. It is not the **GitHub (review first)** diagnostics export and is
not limited to the lines visible in the panel. Keep the archive private and
@@ -1729,9 +1736,10 @@ If you're still stuck:
versions, not just the version before an upgrade. For Docker, include the
running image tag or digest. If installation never started Pulse, give the
attempted release and public installer/helper source, or say "unknown".
-3. **Choose relevant, safe evidence**: if Pulse is running and collection is
- safe, use **Settings → Diagnostics → GitHub (review first)** for
- connection or data failures, following [safe diagnostics collection](#collect-diagnostics-safely).
+3. **Choose relevant, safe evidence**: use existing logs, errors or observations
+ first. If a result is already displayed in **Settings → Support → Diagnostics
+ & Health**, **GitHub (review first)** downloads it without running checks again;
+ follow [safe diagnostics collection](#collect-diagnostics-safely).
For a visual problem, a screenshot or the exact
error may be enough. If logs are needed, use the
[bounded Pulse log readers](#inspect-notification-logs), choosing the command
diff --git a/docs/TRUENAS.md b/docs/TRUENAS.md
index 0412b62e55..b880b3e51e 100644
--- a/docs/TRUENAS.md
+++ b/docs/TRUENAS.md
@@ -325,8 +325,8 @@ excerpt. Remove credentials, cookies, secret URLs, private hostnames,
addresses and personal information, including anything echoed in an error.
Do not upload configuration or credential files.
-In **Settings → Diagnostics**, an existing result's download buttons reuse it
-without running the checks again; nothing is uploaded. Use **GitHub (review first)**
+In **Settings → Support → Diagnostics & Health**, an existing result's download
+buttons reuse it without running the checks again; nothing is uploaded. Use **GitHub (review first)**
for an export intended for sharing, but sanitisation does not guarantee that
every error is safe to share. Open the downloaded file locally and review it
before sharing; keep **Full (private)** private. **Run Diagnostics** makes live
diff --git a/frontend-modern/public/docs/CONTRIBUTING.md b/frontend-modern/public/docs/CONTRIBUTING.md
index d991ed6512..b5760c181f 100644
--- a/frontend-modern/public/docs/CONTRIBUTING.md
+++ b/frontend-modern/public/docs/CONTRIBUTING.md
@@ -62,8 +62,9 @@ and installer tooling.
- Include only evidence relevant to the symptom: a screenshot or exact redacted
error may be enough for a visual problem; existing logs or observations may
explain a connection or data failure. Diagnostics are optional, not a condition
- of reporting. If a result is already displayed in **Settings → Diagnostics**,
- its download buttons reuse that result without running checks again.
+ of reporting. If a result is already displayed in **Settings → Support →
+ Diagnostics & Health**, its download buttons reuse that result without running
+ checks again.
- **Run Diagnostics** can make live API and guest-agent requests. Do not run it
during a backup, freeze/thaw or an unresponsive-host incident just to file a
report. Keep the original evidence instead; a successful one-off check does
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index a55df71ab4..7255d4c3d8 100644
--- a/frontend-modern/public/docs/TROUBLESHOOTING.md
+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md
@@ -1329,7 +1329,13 @@ your own VPN or tunnel when away from home.
### Collect diagnostics safely
-**Run Diagnostics** in **Settings → Diagnostics** is not just a passive export.
+Open **Settings → Support → Diagnostics & Health** in your existing authorised
+Pulse session (`/settings/support/diagnostics` on your Pulse URL). Opening this
+panel does not run diagnostics. If no result is displayed, the download buttons
+are absent: use the original errors or observations rather than running checks
+just to obtain an attachment. Diagnostics are optional, not a condition of reporting.
+
+**Run Diagnostics** (shown as **Run** on phones) is not just a passive export.
It can make live Proxmox/PBS API and guest-agent requests; results may also come
from a short-lived cache. Do not run it during a backup, freeze/thaw or an
unresponsive-host incident merely to obtain a report. Keep the original errors
@@ -1353,7 +1359,8 @@ information, including details echoed in errors or notes. Do not paste a
Share only evidence relevant to the symptom; a screenshot or exact redacted
error may be enough. See [Getting Help](#-getting-help).
-The **Support Bundle** download in **System Logs** is a different export: it can
+The **Support Bundle** download in **Settings → Support → System Logs** is a
+different export: it can
contain a complete log file or server buffer plus configuration and environment
information. It is not the **GitHub (review first)** diagnostics export and is
not limited to the lines visible in the panel. Keep the archive private and
@@ -1729,9 +1736,10 @@ If you're still stuck:
versions, not just the version before an upgrade. For Docker, include the
running image tag or digest. If installation never started Pulse, give the
attempted release and public installer/helper source, or say "unknown".
-3. **Choose relevant, safe evidence**: if Pulse is running and collection is
- safe, use **Settings → Diagnostics → GitHub (review first)** for
- connection or data failures, following [safe diagnostics collection](#collect-diagnostics-safely).
+3. **Choose relevant, safe evidence**: use existing logs, errors or observations
+ first. If a result is already displayed in **Settings → Support → Diagnostics
+ & Health**, **GitHub (review first)** downloads it without running checks again;
+ follow [safe diagnostics collection](#collect-diagnostics-safely).
For a visual problem, a screenshot or the exact
error may be enough. If logs are needed, use the
[bounded Pulse log readers](#inspect-notification-logs), choosing the command
diff --git a/frontend-modern/public/docs/TRUENAS.md b/frontend-modern/public/docs/TRUENAS.md
index 0412b62e55..b880b3e51e 100644
--- a/frontend-modern/public/docs/TRUENAS.md
+++ b/frontend-modern/public/docs/TRUENAS.md
@@ -325,8 +325,8 @@ excerpt. Remove credentials, cookies, secret URLs, private hostnames,
addresses and personal information, including anything echoed in an error.
Do not upload configuration or credential files.
-In **Settings → Diagnostics**, an existing result's download buttons reuse it
-without running the checks again; nothing is uploaded. Use **GitHub (review first)**
+In **Settings → Support → Diagnostics & Health**, an existing result's download
+buttons reuse it without running the checks again; nothing is uploaded. Use **GitHub (review first)**
for an export intended for sharing, but sanitisation does not guarantee that
every error is safe to share. Open the downloaded file locally and review it
before sharing; keep **Full (private)** private. **Run Diagnostics** makes live
diff --git a/frontend-modern/src/components/Settings/__tests__/useDiagnosticsPanelState.test.ts b/frontend-modern/src/components/Settings/__tests__/useDiagnosticsPanelState.test.ts
index 40fc1bd052..d1e4975771 100644
--- a/frontend-modern/src/components/Settings/__tests__/useDiagnosticsPanelState.test.ts
+++ b/frontend-modern/src/components/Settings/__tests__/useDiagnosticsPanelState.test.ts
@@ -211,12 +211,17 @@ describe('useDiagnosticsPanelState', () => {
expect(payload.infrastructureOnboarding).toBeUndefined();
});
- it('blocks export until diagnostics have been run', async () => {
+ it('opens with no result and makes no request just to prepare an export', async () => {
const { result } = renderHook(() => useDiagnosticsPanelState());
+ expect(result.diagnosticsData()).toBeNull();
+ expect(result.loading()).toBe(false);
+ expect(apiFetchJSONMock).not.toHaveBeenCalled();
+
await result.exportDiagnostics(true);
expect(showErrorMock).toHaveBeenCalledWith('Run diagnostics first');
expect(createObjectURLMock).not.toHaveBeenCalled();
+ expect(apiFetchJSONMock).not.toHaveBeenCalled();
});
});
diff --git a/frontend-modern/src/features/docs/__tests__/diagnosticsCollectionGuide.test.ts b/frontend-modern/src/features/docs/__tests__/diagnosticsCollectionGuide.test.ts
new file mode 100644
index 0000000000..5f04cf2e38
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/diagnosticsCollectionGuide.test.ts
@@ -0,0 +1,90 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { getSettingsNavItem } from '@/components/Settings/settingsNavCatalog';
+import { settingsTabPath } from '@/components/Settings/settingsNavigationModel';
+import { DIAGNOSTICS_PANEL_COPY } from '@/utils/diagnosticsPresentation';
+import { createGuideFixture } from './guideFixture';
+
+const read = (name: string) =>
+ readFileSync(resolve(process.cwd(), '../docs', `${name}.md`), 'utf8');
+const article = createGuideFixture(read);
+const text = (element: Element) => element.textContent!.replace(/\s+/g, ' ').trim();
+
+function collectionSection() {
+ const guide = article('TROUBLESHOOTING');
+ const heading = guide.querySelector('#collect-diagnostics-safely');
+ expect(heading?.tagName).toBe('H3');
+ const section = document.createElement('section');
+ for (
+ let next = heading!.nextElementSibling;
+ next && next.tagName !== 'H3';
+ next = next.nextElementSibling
+ ) {
+ section.append(next.cloneNode(true));
+ }
+ return section;
+}
+
+describe('safe diagnostic collection guidance', () => {
+ it('matches the existing Support panel and labels without turning its path into a GitHub link', () => {
+ const section = collectionSection();
+ const content = text(section);
+ expect(content).toContain(
+ `Settings → Support → ${getSettingsNavItem('support-diagnostics')?.label}`,
+ );
+ expect(section.querySelector('code')?.textContent).toBe(settingsTabPath('support-diagnostics'));
+ expect(section.querySelector('a[href^="/settings"]')).toBeNull();
+ expect(content).toContain(
+ `${DIAGNOSTICS_PANEL_COPY.runActionLabel} (shown as ${DIAGNOSTICS_PANEL_COPY.runShortLabel} on phones)`,
+ );
+ });
+
+ it('distinguishes safe panel opening, absent exports and a live check before any download advice', () => {
+ const paragraphs = [...collectionSection().querySelectorAll('p')].map(text);
+ expect(paragraphs[0]).toContain('Opening this panel does not run diagnostics');
+ expect(paragraphs[0]).toContain('the download buttons are absent');
+ expect(paragraphs[0]).toContain('use the original errors or observations');
+ expect(paragraphs[0]).toContain('Diagnostics are optional, not a condition of reporting');
+ expect(paragraphs[1]).toContain('live Proxmox/PBS API and guest-agent requests');
+ expect(paragraphs[1]).toContain(
+ 'Do not run it during a backup, freeze/thaw or an unresponsive-host incident',
+ );
+ expect(paragraphs[2]).toContain('reuse that result without running the checks again');
+ expect(paragraphs[2]).toContain('not an upload');
+ });
+
+ it('keeps both diagnostic downloads distinct from the full System Logs bundle', () => {
+ const section = collectionSection();
+ const content = text(section);
+ for (const label of [
+ DIAGNOSTICS_PANEL_COPY.exportFullLabel,
+ DIAGNOSTICS_PANEL_COPY.exportGithubLabel,
+ ]) {
+ expect(content).toContain(label);
+ }
+ expect(content).toContain('not a guarantee that every free-text error');
+ expect(content).toContain('Open the file locally and review it before sharing');
+ expect(content).toContain(`Settings → Support → ${getSettingsNavItem('support-logs')?.label}`);
+ expect(content).toContain('not limited to the lines visible in the panel');
+ const logsLink = section.querySelector('a[href="/docs/CONFIGURATION#log-levels"]');
+ expect(logsLink?.hasAttribute('data-doc-link')).toBe(true);
+ expect(article('CONFIGURATION').querySelector('#log-levels')).not.toBeNull();
+ });
+
+ it('ships the same current navigation and safety instructions at all three intake entry points', () => {
+ const contributing = readFileSync(resolve(process.cwd(), '../CONTRIBUTING.md'), 'utf8');
+ for (const [name, source] of [
+ ['TROUBLESHOOTING', read('TROUBLESHOOTING')],
+ ['TRUENAS', read('TRUENAS')],
+ ['CONTRIBUTING', contributing],
+ ]) {
+ expect(readFileSync(resolve(process.cwd(), `public/docs/${name}.md`), 'utf8')).toBe(source);
+ expect(source.replace(/\s+/g, ' ')).toContain('Settings → Support → Diagnostics & Health');
+ expect(source).not.toContain('Settings → Diagnostics');
+ }
+ const gettingHelp = read('TROUBLESHOOTING').split('## 🆘 Getting Help')[1].replace(/\s+/g, ' ');
+ expect(gettingHelp).toContain('use existing logs, errors or observations first');
+ expect(gettingHelp).toContain('If a result is already displayed');
+ });
+});