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.

Diagnose missing readings without resetting connections

pulse-triage[bot]cf95b692a463
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 5861ba8c95..91fbbbd901 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -153,13 +153,38 @@ Yes. Pulse supports **OIDC** and **SAML** SSO providers, with multi-provider sup
## ⚠️ Troubleshooting
### No data showing?
-- Check Proxmox API is reachable (port 8006).
-- Verify credentials in **Settings → Infrastructure**.
-- Check logs: `journalctl -u pulse -f` or `docker logs -f pulse`.
+
+First distinguish what is missing; Pulse monitors more than Proxmox.
+
+| Missing item | Check existing evidence first |
+| --- | --- |
+| Whole page or resource | Open its platform page, not just Machines. Follow the [current navigation guide](TROUBLESHOOTING.md#old-bookmarks-dont-work) for moved pages and bookmarks. |
+| Current readings | Check the affected connection in **Settings → Infrastructure**: is it enabled, and does its last activity advance during ordinary polling? For an agent, compare **Last seen** with the particular missing reading. |
+| History only | Check the selected resource and time range. A current value does not prove that samples were stored for that chart; use [History troubleshooting](METRICS_HISTORY.md#troubleshooting). |
+
+A green connection badge, recent **Last seen** or successful **Test Connection**
+does not prove that every reading is fresh. Missing or unavailable is not zero.
+Use the relevant checks for [stale TrueNAS data](TRUENAS.md#stale-truenas-data),
+[empty PBS History](PBS.md#pbs-is-connected-but-history-stays-empty) or
+[missing VM disk usage](VM_DISK_MONITORING.md#troubleshooting). Check Proxmox
+[effective permissions](TROUBLESHOOTING.md#check-permissions-proxmox) only when
+the affected operation reports an access error, not on a missing chart alone.
+
+Keep the original time and displayed error. Do not replace credentials, delete
+connections or re-enrol agents just to populate a chart. During a backup,
+freeze/thaw or an unresponsive-host incident, defer setup, live tests and
+**Run Diagnostics**; follow [safe evidence collection](TROUBLESHOOTING.md#collect-diagnostics-safely).
+If logs are needed, use a bounded excerpt from the original incident and review
+it locally before sharing, as described in [Getting Help](TROUBLESHOOTING.md#-getting-help).
### Connection refused?
-- Check if Pulse is running: `systemctl status pulse` or `docker ps`.
-- Verify the port (default 7655) is open on your firewall.
+
+Distinguish your browser's connection to Pulse from Pulse's connection to a
+monitored platform. If the browser cannot reach Pulse, check the actual service,
+listening port and proxy using the [connection guide](TROUBLESHOOTING.md#connection-refused).
+If Pulse opens but a platform request is refused, preserve that request's
+redacted error and use its platform guide above; changing Pulse's listening
+port does not repair the platform connection.
### CORS errors?
Pulse defaults to same-origin only. If you access the API from a different domain, set **Settings → System → Network → Allowed Origins** or use `ALLOWED_ORIGINS` (single origin, or `*` if you explicitly want all origins).
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 2c0e5540e4..c2e9c76bb6 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -126,9 +126,28 @@ Do not post full service environments, `docker inspect` output or resolved
only the relevant port numbers and a redacted error if help is needed.
### "Connection Refused"
-- Check if Pulse is running.
-- Verify the port is open on your firewall.
-- **PBS**: Remember PBS uses port **8007** and requires **HTTPS**.
+
+Identify which connection failed before changing ports or credentials:
+
+- **Your browser cannot open Pulse:** check that the intended Pulse service or
+ container is running, then its actual listening port, container port mapping
+ and reverse proxy target. Pulse's default port is **7655**, but an existing
+ deployment can use a different one. Use the [port-change checks](#port-change-didnt-take-effect)
+ and [reverse proxy guide](REVERSE_PROXY.md) for that path; do not broadly open
+ firewall access or expose Pulse directly to bypass a proxy.
+- **Pulse opens, but a monitored platform request is refused:** check the
+ affected connection's saved hostname, scheme and port in **Settings →
+ Infrastructure**, and the network path **from the Pulse server**. Browser
+ access to the platform is a different path. Proxmox VE normally uses HTTPS
+ on **8006**; PBS uses HTTPS on **8007**. Other platforms use their saved
+ endpoint, not an assumed Proxmox port. Changing Pulse's listening port does
+ not repair this connection.
+
+A connection refusal is not an authentication response (**401/403**) or a
+certificate-validation error. Keep the original time and redacted error;
+do not replace credentials or disable TLS verification on a refusal alone.
+For a page that opens but has missing readings, use the
+[missing-data checks](FAQ.md#no-data-showing) instead of resetting the connection.
---
diff --git a/frontend-modern/public/docs/FAQ.md b/frontend-modern/public/docs/FAQ.md
index 5861ba8c95..91fbbbd901 100644
--- a/frontend-modern/public/docs/FAQ.md
+++ b/frontend-modern/public/docs/FAQ.md
@@ -153,13 +153,38 @@ Yes. Pulse supports **OIDC** and **SAML** SSO providers, with multi-provider sup
## ⚠️ Troubleshooting
### No data showing?
-- Check Proxmox API is reachable (port 8006).
-- Verify credentials in **Settings → Infrastructure**.
-- Check logs: `journalctl -u pulse -f` or `docker logs -f pulse`.
+
+First distinguish what is missing; Pulse monitors more than Proxmox.
+
+| Missing item | Check existing evidence first |
+| --- | --- |
+| Whole page or resource | Open its platform page, not just Machines. Follow the [current navigation guide](TROUBLESHOOTING.md#old-bookmarks-dont-work) for moved pages and bookmarks. |
+| Current readings | Check the affected connection in **Settings → Infrastructure**: is it enabled, and does its last activity advance during ordinary polling? For an agent, compare **Last seen** with the particular missing reading. |
+| History only | Check the selected resource and time range. A current value does not prove that samples were stored for that chart; use [History troubleshooting](METRICS_HISTORY.md#troubleshooting). |
+
+A green connection badge, recent **Last seen** or successful **Test Connection**
+does not prove that every reading is fresh. Missing or unavailable is not zero.
+Use the relevant checks for [stale TrueNAS data](TRUENAS.md#stale-truenas-data),
+[empty PBS History](PBS.md#pbs-is-connected-but-history-stays-empty) or
+[missing VM disk usage](VM_DISK_MONITORING.md#troubleshooting). Check Proxmox
+[effective permissions](TROUBLESHOOTING.md#check-permissions-proxmox) only when
+the affected operation reports an access error, not on a missing chart alone.
+
+Keep the original time and displayed error. Do not replace credentials, delete
+connections or re-enrol agents just to populate a chart. During a backup,
+freeze/thaw or an unresponsive-host incident, defer setup, live tests and
+**Run Diagnostics**; follow [safe evidence collection](TROUBLESHOOTING.md#collect-diagnostics-safely).
+If logs are needed, use a bounded excerpt from the original incident and review
+it locally before sharing, as described in [Getting Help](TROUBLESHOOTING.md#-getting-help).
### Connection refused?
-- Check if Pulse is running: `systemctl status pulse` or `docker ps`.
-- Verify the port (default 7655) is open on your firewall.
+
+Distinguish your browser's connection to Pulse from Pulse's connection to a
+monitored platform. If the browser cannot reach Pulse, check the actual service,
+listening port and proxy using the [connection guide](TROUBLESHOOTING.md#connection-refused).
+If Pulse opens but a platform request is refused, preserve that request's
+redacted error and use its platform guide above; changing Pulse's listening
+port does not repair the platform connection.
### CORS errors?
Pulse defaults to same-origin only. If you access the API from a different domain, set **Settings → System → Network → Allowed Origins** or use `ALLOWED_ORIGINS` (single origin, or `*` if you explicitly want all origins).
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index 2c0e5540e4..c2e9c76bb6 100644
--- a/frontend-modern/public/docs/TROUBLESHOOTING.md
+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md
@@ -126,9 +126,28 @@ Do not post full service environments, `docker inspect` output or resolved
only the relevant port numbers and a redacted error if help is needed.
### "Connection Refused"
-- Check if Pulse is running.
-- Verify the port is open on your firewall.
-- **PBS**: Remember PBS uses port **8007** and requires **HTTPS**.
+
+Identify which connection failed before changing ports or credentials:
+
+- **Your browser cannot open Pulse:** check that the intended Pulse service or
+ container is running, then its actual listening port, container port mapping
+ and reverse proxy target. Pulse's default port is **7655**, but an existing
+ deployment can use a different one. Use the [port-change checks](#port-change-didnt-take-effect)
+ and [reverse proxy guide](REVERSE_PROXY.md) for that path; do not broadly open
+ firewall access or expose Pulse directly to bypass a proxy.
+- **Pulse opens, but a monitored platform request is refused:** check the
+ affected connection's saved hostname, scheme and port in **Settings →
+ Infrastructure**, and the network path **from the Pulse server**. Browser
+ access to the platform is a different path. Proxmox VE normally uses HTTPS
+ on **8006**; PBS uses HTTPS on **8007**. Other platforms use their saved
+ endpoint, not an assumed Proxmox port. Changing Pulse's listening port does
+ not repair this connection.
+
+A connection refusal is not an authentication response (**401/403**) or a
+certificate-validation error. Keep the original time and redacted error;
+do not replace credentials or disable TLS verification on a refusal alone.
+For a page that opens but has missing readings, use the
+[missing-data checks](FAQ.md#no-data-showing) instead of resetting the connection.
---
diff --git a/frontend-modern/src/features/docs/__tests__/missingDataFAQ.test.ts b/frontend-modern/src/features/docs/__tests__/missingDataFAQ.test.ts
new file mode 100644
index 0000000000..0f351d28e5
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/missingDataFAQ.test.ts
@@ -0,0 +1,110 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { renderDocMarkdown } from '../docMarkdown';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');
+
+function renderGuide(name: string): HTMLElement {
+ const input = process.env[`PULSE_${name}_GUIDE_TEST_INPUT`];
+ const source = readFileSync(
+ input ?? path.join(repoRoot, 'frontend-modern/public/docs', `${name}.md`),
+ 'utf8',
+ );
+ const article = document.createElement('article');
+ article.innerHTML = renderDocMarkdown(source, name);
+ return article;
+}
+
+function section(id: string): HTMLElement {
+ const heading = renderGuide('FAQ').querySelector(`#${id}`);
+ expect(heading).not.toBeNull();
+ const result = document.createElement('section');
+ for (let next = heading!.nextElementSibling; next; next = next.nextElementSibling) {
+ if (/^H[1-6]$/.test(next.tagName)) break;
+ result.appendChild(next.cloneNode(true));
+ }
+ return result;
+}
+
+const prose = (element: HTMLElement): string =>
+ (element.textContent ?? '').replace(/\s+/g, ' ').trim();
+
+describe('shipped missing-data FAQ', () => {
+ it('separates missing navigation, current readings and stored History', () => {
+ const rows = section('no-data-showing').querySelectorAll('tbody tr');
+ expect(rows).toHaveLength(3);
+ expect(prose(rows[0] as HTMLElement)).toContain('Whole page or resource');
+ expect(prose(rows[0] as HTMLElement)).toContain('platform page, not just Machines');
+ expect(prose(rows[1] as HTMLElement)).toContain('during ordinary polling');
+ expect(prose(rows[1] as HTMLElement)).toContain('particular missing reading');
+ expect(prose(rows[2] as HTMLElement)).toContain('selected resource and time range');
+ expect(prose(rows[2] as HTMLElement)).toContain('samples were stored for that chart');
+ });
+
+ it('does not mistake connection liveness or a successful test for fresh metrics', () => {
+ const text = prose(section('no-data-showing'));
+ expect(text).toContain('Last seen or successful Test Connection');
+ expect(text).toContain('does not prove that every reading is fresh');
+ expect(text).toContain('Missing or unavailable is not zero');
+ expect(text).toContain('access error, not on a missing chart alone');
+ });
+
+ it('routes each symptom to a real heading in a shipped guide', () => {
+ const sections = [section('no-data-showing'), section('connection-refused')];
+ const links = sections.flatMap((element) => [...element.querySelectorAll('a[href]')]);
+ expect(links).toHaveLength(9);
+ for (const link of links) {
+ const href = link.getAttribute('href')!;
+ const match = /^\/docs\/([^#]+)(#.+)$/.exec(href);
+ expect(match, href).not.toBeNull();
+ expect(renderGuide(match![1]).querySelector(match![2]), href).not.toBeNull();
+ expect(link.hasAttribute('data-doc-link'), href).toBe(true);
+ expect(link.hasAttribute('target'), href).toBe(false);
+ }
+ });
+
+ it('preserves identity and backup safety while keeping collection bounded and private', () => {
+ const element = section('no-data-showing');
+ const text = prose(element);
+ expect(text).toContain('Do not replace credentials, delete connections or re-enrol agents');
+ expect(text).toContain('backup, freeze/thaw or an unresponsive-host incident');
+ expect(text).toContain('defer setup, live tests and Run Diagnostics');
+ expect(text).toContain('bounded excerpt from the original incident');
+ expect(text).toContain('review it locally before sharing');
+ expect(element.querySelector('pre')).toBeNull();
+ expect(text).not.toMatch(/journalctl|docker logs|port 8006/);
+ });
+
+ it('keeps a refused platform request separate from a refused Pulse browser connection', () => {
+ const element = section('connection-refused');
+ const text = prose(element);
+ expect(text).toContain("browser's connection to Pulse from Pulse's connection");
+ expect(text).toContain('actual service, listening port and proxy');
+ expect(text).toContain(
+ "changing Pulse's listening port does not repair the platform connection",
+ );
+ expect(element.querySelector('pre')).toBeNull();
+ });
+
+ it('makes the connection guide diagnose the affected path without weakening access or TLS', () => {
+ const heading = renderGuide('TROUBLESHOOTING').querySelector('#connection-refused');
+ expect(heading).not.toBeNull();
+ const element = document.createElement('section');
+ for (let next = heading!.nextElementSibling; next; next = next.nextElementSibling) {
+ if (/^H[1-6]$/.test(next.tagName)) break;
+ element.appendChild(next.cloneNode(true));
+ }
+ const text = prose(element);
+ expect(text).toContain('Your browser cannot open Pulse');
+ expect(text).toContain('Pulse opens, but a monitored platform request is refused');
+ expect(text).toContain('network path from the Pulse server');
+ expect(text).toContain('not an assumed Proxmox port');
+ expect(text).toContain('not broadly open firewall access or expose Pulse directly');
+ expect(text).toContain('not an authentication response (401/403)');
+ expect(text).toContain('do not replace credentials or disable TLS verification');
+ expect(element.querySelector('a[href="/docs/FAQ#no-data-showing"]')).not.toBeNull();
+ expect(element.querySelector('pre')).toBeNull();
+ });
+});