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
Match probe help to the current observation-location editor
pulse-triage[bot]b27387d8fc48
diff --git a/docs/API.md b/docs/API.mdindex e57302d49a..8ecbce7731 100644--- a/docs/API.md+++ b/docs/API.md@@ -1663,7 +1663,12 @@ Target payload fields:- `linkedResourceId` - Optional resource id hint for attaching the probe facet to an existing resource.- `certificateMonitoringDisabled` - Explicit HTTPS-only opt-out; certificate validity monitoring is enabled by default.- `certificateExpiryWarningDays` - HTTPS certificate expiry warning window; defaults to 30 days.-- `probeAgentId` - Optional registered host-agent ID that runs the check instead of the Pulse server; requires the Pro `external_probe` entitlement. Send an explicit empty string on update to return the check to local execution.+- `observationLocationIds` - Observation locations for this one logical check: `pulse:local` for this Pulse server and `agent:<host-agent-id>` for a connected agent. Agent locations require the Pro `external_probe` entitlement. Include `pulse:local` only when a local observation is wanted; agent-only sets do not also run locally. Each location retains separate evidence rather than treating one path failure as a universal outage.+- `probeAgentId` - Compatibility field for single-location clients. A non-empty registered host-agent ID selects that agent; an explicit empty string selects local execution. When updating only this field, omit `observationLocationIds`. For multi-location updates, send the complete desired `observationLocationIds` set and clear `probeAgentId` to `""` so a legacy value cannot override a single-location edit.++External agents collect observations, but alert evaluation and notification+delivery still depend on the Pulse server. Missing reports are not proof of a+target outage. See [probe coverage and outage limits](CONFIGURATION.md#external-probes-pro).An explicit `linkedResourceId` is authoritative and fails closed when itcannot resolve. Without it, Pulse correlates only on one exact normalized IPdiff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.mdindex ef90f2a3b3..20cf7967ef 100644--- a/docs/CONFIGURATION.md+++ b/docs/CONFIGURATION.md@@ -579,20 +579,25 @@ alerts, and resource projections keep one canonical protocol value.External probes change **where a check runs**, not where alerts are sent.By default, checks run on the Pulse server. With the Pro `external_probe`-entitlement, assign a connected Pulse agent using **Run from** in the UI-(`probeAgentId` in the API). An agent on a cloud VM or at another site can-observe a service from outside its local network.+entitlement, select one or more connected agents under **Observation locations**+in the check editor. An agent on a cloud VM or at another site can observe a+service from outside its local network. Keep **This Pulse server** selected if+you also want a local observation; deselect it for agent-only checks. Pulse keeps+each location's evidence separate, so a failure on one path is not a universal+outage. The API uses `observationLocationIds`; see the+[target fields](API.md#availability-checks).The assigned agent receives signed configuration, runs the check and reports-results back to Pulse. Only the currently assigned agent's results are accepted;-an assigned check is not also run locally. **The agent does not send+results back to Pulse. Only agents assigned to that target may submit results;+the server runs a local check only when **This Pulse server** is selected.+**The agent does not sendnotifications directly.** The Pulse server must be running and able to reachthe notification destination to evaluate results and send alerts.| Situation | What the check can tell you || --- | --- || Pulse is running and receives probe results | Target observations are evaluated through the normal alert and notification policies. |-| Pulse is running but probe results stop arriving | The check becomes indeterminate: "no recent report from probe agent". This is missing evidence, not proof the target is down. |+| Pulse is running but probe results stop arriving | The affected location becomes indeterminate: "no recent report from probe agent". This is missing evidence, not proof the target is down. Other locations retain their own evidence. || Pulse is stopped or cannot reach its notification destination | An external agent cannot deliver Pulse alerts in its place. Use an independent external watchdog for this failure. |The missing-report window is the longer of **five minutes or three checkdiff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.mdindex dc9b567fae..6b8b322f15 100644--- a/docs/UNIFIED_AGENT.md+++ b/docs/UNIFIED_AGENT.md@@ -303,11 +303,15 @@ storage nodes to avoid duplicate or ambiguously correlated readings.## External Probes (Pro)With the Pro `external_probe` entitlement, availability checks configured in-Pulse can be assigned to run from a specific agent instead of the Pulse-server (Settings -> Monitoring -> Availability checks -> "Run from"). This is-how you observe a service from outside its local network: deploy the agent on-a machine elsewhere — a cloud VM, a Docker host at another location — and-assign checks to it. **The agent does not send notifications directly.** The+Pulse can run from one or more connected agents. In **Settings → Monitoring →+Availability checks**, select the agents under **Observation locations** in the+check editor. Keep **This Pulse server** selected for a local observation too,+or deselect it for agent-only checks. Each location keeps its own evidence; a+failure on one path is not a universal outage.++To observe a service from outside its local network, deploy the agent on a+machine elsewhere — a cloud VM, a Docker host at another location — and assign+checks to it. **The agent does not send notifications directly.** ThePulse server must be running and able to reach the notification destination;target failures are evaluated there through your normal alert routes.@@ -317,7 +321,7 @@ configured interval, and results are delivered with its regular reports.Results waiting for delivery use a bounded **in-memory** queue of up to 200observations across the agent's checks. Oldest pending observations are droppedwhen it fills, and an agent restart loses the queue; it is not a complete outage-record. If reports stop arriving, the check becomes indeterminate ("no recent+record. If reports stop arriving, the affected location becomes indeterminate ("no recentreport from probe agent"). This is missing evidence, not proof the target isdown. The missing-report window is thelonger of **five minutes or three check intervals**. During normal serverdiff --git a/frontend-modern/browser-tests/probe-guidance.cjs b/frontend-modern/browser-tests/probe-guidance.cjsindex a13e496443..6ee29e6ec1 100644--- a/frontend-modern/browser-tests/probe-guidance.cjs+++ b/frontend-modern/browser-tests/probe-guidance.cjs@@ -50,6 +50,7 @@ const { chromium, webkit } = require('playwright');const body = (await page.locator('article').innerText()).replace(/\s+/g, ' ');for (const text of ['The agent does not send notifications directly.','Pulse server must be running and able to reach the notification destination',+ 'Observation locations', 'This Pulse server', 'not a universal outage','not proof the target is down', 'five minutes or three check intervals','31 March 2027', 'Relay is no longer sold', 'not a permanent substitute']) {assert.ok(body.includes(text), text);@@ -96,6 +97,11 @@ const { chromium, webkit } = require('playwright');await page.getByRole('heading', { name: 'External Probes (Pro)', exact: true }).waitFor();await follow('configuration guide', '/docs/CONFIGURATION#external-probes-pro','External probes (Pro)', 'external-probes-pro');+ await follow('target fields', '/docs/API#availability-checks',+ 'Availability Checks', 'availability-checks');+ assert.ok((await page.locator('article').innerText()).includes('clear probeAgentId to ""'));+ await page.goBack();+ await page.getByRole('heading', { name: 'External probes (Pro)', exact: true }).waitFor();await follow('external watchdog', '/docs/TROUBLESHOOTING#no-alert-when-pulse-power-or-internet-goes-down','No alert when Pulse, power or internet goes down', 'no-alert-when-pulse-power-or-internet-goes-down');assert.deepEqual(errors, []);@@ -104,11 +110,11 @@ const { chromium, webkit } = require('playwright');serverDependencyVisible: true, semanticContainedCoverageTable: true,noDocumentOverflow: true, queueAndRetirementLimitsVisible: true,keyboardAgentGuide: true, keyboardConfigurationGuide: true,- keyboardWatchdogLinks: 2, keyboardRetirementLink: true, errors });+ keyboardWatchdogLinks: 2, keyboardRetirementLink: true, keyboardCanonicalApiFields: true, errors });await browser.close();browser = undefined;}- const files = ['public/docs/CONFIGURATION.md', 'public/docs/UNIFIED_AGENT.md',+ const files = ['public/docs/CONFIGURATION.md', 'public/docs/UNIFIED_AGENT.md', 'public/docs/API.md','browser-tests/probe-guidance.cjs', 'browser-tests/docs-fragment-navigation.tsx','src/features/docs/docMarkdown.ts', 'src/pages/Docs.tsx'].map((file) => ({ file,sha256: crypto.createHash('sha256').update(fs.readFileSync(path.join(root, file))).digest('hex') }));diff --git a/frontend-modern/public/docs/API.md b/frontend-modern/public/docs/API.mdindex e57302d49a..8ecbce7731 100644--- a/frontend-modern/public/docs/API.md+++ b/frontend-modern/public/docs/API.md@@ -1663,7 +1663,12 @@ Target payload fields:- `linkedResourceId` - Optional resource id hint for attaching the probe facet to an existing resource.- `certificateMonitoringDisabled` - Explicit HTTPS-only opt-out; certificate validity monitoring is enabled by default.- `certificateExpiryWarningDays` - HTTPS certificate expiry warning window; defaults to 30 days.-- `probeAgentId` - Optional registered host-agent ID that runs the check instead of the Pulse server; requires the Pro `external_probe` entitlement. Send an explicit empty string on update to return the check to local execution.+- `observationLocationIds` - Observation locations for this one logical check: `pulse:local` for this Pulse server and `agent:<host-agent-id>` for a connected agent. Agent locations require the Pro `external_probe` entitlement. Include `pulse:local` only when a local observation is wanted; agent-only sets do not also run locally. Each location retains separate evidence rather than treating one path failure as a universal outage.+- `probeAgentId` - Compatibility field for single-location clients. A non-empty registered host-agent ID selects that agent; an explicit empty string selects local execution. When updating only this field, omit `observationLocationIds`. For multi-location updates, send the complete desired `observationLocationIds` set and clear `probeAgentId` to `""` so a legacy value cannot override a single-location edit.++External agents collect observations, but alert evaluation and notification+delivery still depend on the Pulse server. Missing reports are not proof of a+target outage. See [probe coverage and outage limits](CONFIGURATION.md#external-probes-pro).An explicit `linkedResourceId` is authoritative and fails closed when itcannot resolve. Without it, Pulse correlates only on one exact normalized IPdiff --git a/frontend-modern/public/docs/CONFIGURATION.md b/frontend-modern/public/docs/CONFIGURATION.mdindex ef90f2a3b3..20cf7967ef 100644--- a/frontend-modern/public/docs/CONFIGURATION.md+++ b/frontend-modern/public/docs/CONFIGURATION.md@@ -579,20 +579,25 @@ alerts, and resource projections keep one canonical protocol value.External probes change **where a check runs**, not where alerts are sent.By default, checks run on the Pulse server. With the Pro `external_probe`-entitlement, assign a connected Pulse agent using **Run from** in the UI-(`probeAgentId` in the API). An agent on a cloud VM or at another site can-observe a service from outside its local network.+entitlement, select one or more connected agents under **Observation locations**+in the check editor. An agent on a cloud VM or at another site can observe a+service from outside its local network. Keep **This Pulse server** selected if+you also want a local observation; deselect it for agent-only checks. Pulse keeps+each location's evidence separate, so a failure on one path is not a universal+outage. The API uses `observationLocationIds`; see the+[target fields](API.md#availability-checks).The assigned agent receives signed configuration, runs the check and reports-results back to Pulse. Only the currently assigned agent's results are accepted;-an assigned check is not also run locally. **The agent does not send+results back to Pulse. Only agents assigned to that target may submit results;+the server runs a local check only when **This Pulse server** is selected.+**The agent does not sendnotifications directly.** The Pulse server must be running and able to reachthe notification destination to evaluate results and send alerts.| Situation | What the check can tell you || --- | --- || Pulse is running and receives probe results | Target observations are evaluated through the normal alert and notification policies. |-| Pulse is running but probe results stop arriving | The check becomes indeterminate: "no recent report from probe agent". This is missing evidence, not proof the target is down. |+| Pulse is running but probe results stop arriving | The affected location becomes indeterminate: "no recent report from probe agent". This is missing evidence, not proof the target is down. Other locations retain their own evidence. || Pulse is stopped or cannot reach its notification destination | An external agent cannot deliver Pulse alerts in its place. Use an independent external watchdog for this failure. |The missing-report window is the longer of **five minutes or three checkdiff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.mdindex dc9b567fae..6b8b322f15 100644--- a/frontend-modern/public/docs/UNIFIED_AGENT.md+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md@@ -303,11 +303,15 @@ storage nodes to avoid duplicate or ambiguously correlated readings.## External Probes (Pro)With the Pro `external_probe` entitlement, availability checks configured in-Pulse can be assigned to run from a specific agent instead of the Pulse-server (Settings -> Monitoring -> Availability checks -> "Run from"). This is-how you observe a service from outside its local network: deploy the agent on-a machine elsewhere — a cloud VM, a Docker host at another location — and-assign checks to it. **The agent does not send notifications directly.** The+Pulse can run from one or more connected agents. In **Settings → Monitoring →+Availability checks**, select the agents under **Observation locations** in the+check editor. Keep **This Pulse server** selected for a local observation too,+or deselect it for agent-only checks. Each location keeps its own evidence; a+failure on one path is not a universal outage.++To observe a service from outside its local network, deploy the agent on a+machine elsewhere — a cloud VM, a Docker host at another location — and assign+checks to it. **The agent does not send notifications directly.** ThePulse server must be running and able to reach the notification destination;target failures are evaluated there through your normal alert routes.@@ -317,7 +321,7 @@ configured interval, and results are delivered with its regular reports.Results waiting for delivery use a bounded **in-memory** queue of up to 200observations across the agent's checks. Oldest pending observations are droppedwhen it fills, and an agent restart loses the queue; it is not a complete outage-record. If reports stop arriving, the check becomes indeterminate ("no recent+record. If reports stop arriving, the affected location becomes indeterminate ("no recentreport from probe agent"). This is missing evidence, not proof the target isdown. The missing-report window is thelonger of **five minutes or three check intervals**. During normal serverdiff --git a/frontend-modern/src/utils/__tests__/docsLinks.test.ts b/frontend-modern/src/utils/__tests__/docsLinks.test.tsindex a2a9f683e3..9d063ad55f 100644--- a/frontend-modern/src/utils/__tests__/docsLinks.test.ts+++ b/frontend-modern/src/utils/__tests__/docsLinks.test.ts@@ -117,6 +117,31 @@ describe('docsLinks', () => {}});+ it('matches the existing observation-location editor and compatibility fields', () => {+ for (const guide of probeGuides()) {+ expect(guide).toContain('Observation locations');+ expect(guide).toContain('This Pulse server');+ expect(guide).toContain('not a universal outage');+ expect(guide).not.toContain('Run from');+ expect(guide).not.toContain('an assigned check is not also run locally');+ }+ const api = readFileSync(path.join(repoRoot, 'docs', 'API.md'), 'utf8');+ expect(api).toContain('`observationLocationIds` - Observation locations');+ expect(api).toContain('`pulse:local` for this Pulse server');+ expect(api).toContain('`agent:<host-agent-id>` for a connected agent');+ expect(api).toContain('omit `observationLocationIds`');+ expect(api).toContain('clear `probeAgentId` to `""`');+ const editor = readFileSync(path.join(frontendRoot, 'src', 'components', 'Settings',+ 'ConnectionEditor', 'CredentialSlots', 'AvailabilityTargetSlot.tsx'), 'utf8');+ expect(editor).toContain('Observation locations</legend>');+ expect(editor).toContain('observationLocationIds: [...form.observationLocationIds]');+ const handler = readFileSync(+ path.join(repoRoot, 'internal', 'api', 'availability_handlers.go'), 'utf8',+ );+ expect(handler).toContain('compatibility.ObservationLocationIDs == nil && compatibility.ProbeAgentID != nil');+ expect(handler).toContain('agentID != "" && len(*compatibility.ObservationLocationIDs) == 1');+ });+it('separates server removal from persistent-data erasure', () => {const installation = readFileSync(path.join(repoRoot, 'docs', 'INSTALL.md'), 'utf8');const removal = installation.split('## 🗑️ Uninstall')[1];