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.

Explain PMG collection controls in the published stable release

pulse-triage[bot]8812e7757c47
diff --git a/docs/MAIL_GATEWAY.md b/docs/MAIL_GATEWAY.md
index 78361e8611..fbfae785de 100644
--- a/docs/MAIL_GATEWAY.md
+++ b/docs/MAIL_GATEWAY.md
@@ -41,8 +41,9 @@ repeat discovery merely to diagnose missing statistics.
The connection form offers **Mail statistics & trends**, **Queue health
insights**, **Quarantine totals** and **Domain-level statistics**. Domain
-statistics are off by default for a new connection. In current development
-source, the saved switches control these subsequent ordinary poll requests:
+statistics are off by default for a new connection. **Published v6.6.0 and
+current source** respect these saved switches for subsequent ordinary poll
+requests:
| Saved option | Reads it controls |
| --- | --- |
@@ -98,9 +99,9 @@ badge or one populated panel does not prove that every dataset was read. Compare
the affected value and observation window with PMG's own existing view before
acting on an apparent empty queue or quarantine.
-Current development source records downstream read failures as incomplete
-collection while retaining the successful version connection. Missing readings
-do not become observed zero totals or resolve their metric alerts. Partial
+**Published v6.6.0** records downstream read failures as incomplete collection
+while retaining the successful version connection. Missing readings do not
+become observed zero totals or resolve their metric alerts. Partial
queue data can still raise the highest configured severity, but cannot clear
or downgrade an existing alert; quarantine recovery requires both categories.
These collector safeguards do not make every empty display a verified zero.
@@ -142,6 +143,21 @@ is wrong or the queue is empty. A separate transport or permission error still
needs its own assessment; a successful **Test Connection** does not resolve the
decoding failure.
+**Upgraded from v6.5.0 to v6.6.0?** In v6.5.0, a queue-read failure could be
+logged only at Debug level while the connection appeared healthy. In v6.6.0,
+the same failure counts as a failed ordinary poll, even after a successful
+version read or connection test. Newly visible `pmg_queue_status` errors do not
+establish that your network or credentials changed, or that queue readings were
+correct before the upgrade. Keep any other reported failure separate.
+
+If you deliberately turn off **Queue health insights** on v6.6.0, subsequent
+polls omit queue reads under the [saved collection scope](#collection-scope-and-older-releases).
+That can remove this error by removing the failed read, not by repairing it.
+Keep independent queue monitoring while fresh queue readings are unavailable.
+Pulse cannot evaluate new queue data with collection off; retained alerts do
+not establish current queue health. Do not repeatedly toggle collection to
+diagnose the failure.
+
Use PMG's own existing queue view for queue status while Pulse cannot read it.
Keep the affected dataset, original time and short redacted error for the report;
do not attach the full queue response, which can contain mail details. Do not
diff --git a/frontend-modern/public/docs/MAIL_GATEWAY.md b/frontend-modern/public/docs/MAIL_GATEWAY.md
index 78361e8611..fbfae785de 100644
--- a/frontend-modern/public/docs/MAIL_GATEWAY.md
+++ b/frontend-modern/public/docs/MAIL_GATEWAY.md
@@ -41,8 +41,9 @@ repeat discovery merely to diagnose missing statistics.
The connection form offers **Mail statistics & trends**, **Queue health
insights**, **Quarantine totals** and **Domain-level statistics**. Domain
-statistics are off by default for a new connection. In current development
-source, the saved switches control these subsequent ordinary poll requests:
+statistics are off by default for a new connection. **Published v6.6.0 and
+current source** respect these saved switches for subsequent ordinary poll
+requests:
| Saved option | Reads it controls |
| --- | --- |
@@ -98,9 +99,9 @@ badge or one populated panel does not prove that every dataset was read. Compare
the affected value and observation window with PMG's own existing view before
acting on an apparent empty queue or quarantine.
-Current development source records downstream read failures as incomplete
-collection while retaining the successful version connection. Missing readings
-do not become observed zero totals or resolve their metric alerts. Partial
+**Published v6.6.0** records downstream read failures as incomplete collection
+while retaining the successful version connection. Missing readings do not
+become observed zero totals or resolve their metric alerts. Partial
queue data can still raise the highest configured severity, but cannot clear
or downgrade an existing alert; quarantine recovery requires both categories.
These collector safeguards do not make every empty display a verified zero.
@@ -142,6 +143,21 @@ is wrong or the queue is empty. A separate transport or permission error still
needs its own assessment; a successful **Test Connection** does not resolve the
decoding failure.
+**Upgraded from v6.5.0 to v6.6.0?** In v6.5.0, a queue-read failure could be
+logged only at Debug level while the connection appeared healthy. In v6.6.0,
+the same failure counts as a failed ordinary poll, even after a successful
+version read or connection test. Newly visible `pmg_queue_status` errors do not
+establish that your network or credentials changed, or that queue readings were
+correct before the upgrade. Keep any other reported failure separate.
+
+If you deliberately turn off **Queue health insights** on v6.6.0, subsequent
+polls omit queue reads under the [saved collection scope](#collection-scope-and-older-releases).
+That can remove this error by removing the failed read, not by repairing it.
+Keep independent queue monitoring while fresh queue readings are unavailable.
+Pulse cannot evaluate new queue data with collection off; retained alerts do
+not establish current queue health. Do not repeatedly toggle collection to
+diagnose the failure.
+
Use PMG's own existing queue view for queue status while Pulse cannot read it.
Keep the affected dataset, original time and short redacted error for the report;
do not attach the full queue response, which can contain mail details. Do not
diff --git a/frontend-modern/src/features/docs/__tests__/pmgGuide.test.ts b/frontend-modern/src/features/docs/__tests__/pmgGuide.test.ts
new file mode 100644
index 0000000000..853627bacd
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/pmgGuide.test.ts
@@ -0,0 +1,52 @@
+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 root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');
+const source = readFileSync(path.join(root, 'docs/MAIL_GATEWAY.md'), 'utf8');
+const shipped = readFileSync(
+ path.join(root, 'frontend-modern/public/docs/MAIL_GATEWAY.md'),
+ 'utf8',
+);
+const guide = (): HTMLElement => {
+ const article = document.createElement('article');
+ article.innerHTML = renderDocMarkdown(stripLeadingTitle(shipped), 'MAIL_GATEWAY');
+ return article;
+};
+const prose = (element: Element): string => (element.textContent ?? '').replace(/\s+/g, ' ');
+
+describe('published PMG collection guidance', () => {
+ it('distinguishes shipped scope controls from the older release limitation', () => {
+ const article = guide();
+ const text = prose(article);
+ expect(shipped).toBe(source);
+ expect(text).toContain('Published v6.6.0 and current source respect these saved switches');
+ expect(text).toContain('Published v6.5.0 does not contain this scope correction');
+ expect(text).toContain('all four off does not mean no PMG requests');
+ expect(text).toContain('Published v6.6.0 records downstream read failures');
+ expect(article.querySelectorAll('table')[0].querySelectorAll('tbody tr')).toHaveLength(4);
+ });
+
+ it('explains the visible upgrade failure without inventing network or queue recovery', () => {
+ const article = guide();
+ const upgrade = [...article.querySelectorAll('p')].find((p) =>
+ p.textContent?.startsWith('Upgraded from v6.5.0 to v6.6.0?'),
+ )!;
+ expect(prose(upgrade)).toContain('same failure counts as a failed ordinary poll');
+ expect(prose(upgrade)).toContain('even after a successful version read or connection test');
+ expect(prose(upgrade)).toContain('do not establish that your network or credentials changed');
+ expect(prose(upgrade)).toContain('or that queue readings were correct before the upgrade');
+ const scope = upgrade.nextElementSibling!;
+ expect(prose(scope)).toContain('not by repairing it');
+ expect(prose(scope)).toContain('Keep independent queue monitoring');
+ expect(prose(scope)).toContain('retained alerts do not establish current queue health');
+ expect(prose(scope)).toContain('Do not repeatedly toggle collection');
+ const link = scope.querySelector('a[href="#collection-scope-and-older-releases"]');
+ expect(link?.textContent).toBe('saved collection scope');
+ expect(link?.hasAttribute('target')).toBe(false);
+ expect(article.querySelector('#collection-scope-and-older-releases')?.tagName).toBe('H3');
+ expect(scope.querySelector('pre')).toBeNull();
+ });
+});
diff --git a/scripts/tests/test_pmg_docs.py b/scripts/tests/test_pmg_docs.py
index 056779e263..1f30281260 100644
--- a/scripts/tests/test_pmg_docs.py
+++ b/scripts/tests/test_pmg_docs.py
@@ -123,7 +123,7 @@ class PMGDocsTest(unittest.TestCase):
self.assertIn(f"client.{method}(", body)
self.assertEqual(body.count(f"client.{method}("), poll.count(f"client.{method}("))
self.assertIn(description, self.guide)
- for phrase in ("saved switches control these subsequent ordinary poll requests",
+ for phrase in ("respect these saved switches for subsequent ordinary poll requests",
"Edits apply to the next poll", "not requests already in flight",
"does not dismiss an existing alert or establish recovery"):
self.assertIn(phrase, self.guide)
@@ -169,6 +169,28 @@ class PMGDocsTest(unittest.TestCase):
"assume development-source behaviour is present in an installed release"):
self.assertIn(phrase, self.guide)
+ def test_shipped_scope_is_not_described_as_development_only(self):
+ self.assertIn("Published v6.6.0 and current source", self.guide)
+ self.assertIn("Published v6.6.0 records downstream read failures", self.guide)
+ self.assertNotIn("In current development source", self.guide)
+ self.assertNotIn("Current development source records", self.guide)
+
+ def test_upgrade_guidance_does_not_turn_missing_queue_data_into_recovery(self):
+ section = self.guide.split("Upgraded from v6.5.0 to v6.6.0?", 1)[1]
+ section = section.split("Use PMG's own existing queue view", 1)[0]
+ for phrase in ("logged only at Debug level", "same failure counts as a failed ordinary poll",
+ "do not establish that your network or credentials changed",
+ "or that queue readings were correct before the upgrade",
+ "Keep any other reported failure separate",
+ "If you deliberately turn off Queue health insights on v6.6.0",
+ "not by repairing it", "Keep independent queue monitoring",
+ "Pulse cannot evaluate new queue data with collection off",
+ "retained alerts do not establish current queue health",
+ "Do not repeatedly toggle collection"):
+ self.assertIn(phrase, section)
+ self.assertIn("(#collection-scope-and-older-releases)", self.text)
+ self.assertNotRegex(section, r"```|\b(?:curl|wget)\b|upgrade to|fixed in|beta")
+
def test_incomplete_collection_does_not_promise_zero_or_recovery(self):
for phrase in ("records downstream read failures as incomplete collection",
"retaining the successful version connection",