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
Diagnose missing readings without resetting connections
pulse-triage[bot]cf95b692a463
diff --git a/docs/FAQ.md b/docs/FAQ.mdindex 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.mdindex 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 resolvedonly 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.mdindex 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.mdindex 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 resolvedonly 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.tsnew file mode 100644index 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();+ });+});