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.

Make quiet-hours setup select a real notification window

pulse-triage[bot]ef2df62f1726
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index b259cfef8c..1aeeb84aae 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -508,8 +508,42 @@ This tolerance delays activation; it does not disable powered-off monitoring.
Use the existing guest offline-alert toggle when a guest should never produce
powered-off alerts.
+### Quiet hours and notification holds
+
+Open **Alerts → Schedule → Quiet hours** to enable a notification quiet period.
+Choose the start and end times, an IANA timezone such as `Europe/London`, and
+**Quiet days**. No selected days means no quiet period, even when enabled.
+Times are interpreted in the selected timezone, not your browser's timezone.
+
+Quiet hours hold **non-critical notifications**; they do not stop monitoring,
+clear the alert or confirm recovery. Critical notifications remain eligible
+unless you explicitly select their **Suppress categories** (Performance,
+Storage or Offline). Selecting a category also holds its critical
+notifications, including urgent failures; leave it unchecked when those must
+still reach you. Other routing, mute and delivery policies still apply.
+
+A window can cross midnight. Days refer to the **current local calendar day**:
+with only Monday selected, `22:00`–`06:00` covers Monday's early morning and
+late evening, not Tuesday's early morning. Select Tuesday too if that part of
+the night must be quiet. The configured end minute is included: an end of
+`06:00` remains quiet through `06:00:59`.
+
+Eligible queued notifications are held for re-evaluation when the quiet period
+ends. This is not a promise to send every held item at that instant: current
+alert state, destination settings, other policies and provider failures still
+matter. Use [Recent delivery activity](TROUBLESHOOTING.md#test-succeeds-but-real-alerts-are-missing)
+to distinguish a quiet-hours hold from a failed delivery; a settings Test skips
+the queue and does not validate this schedule. Do not create an outage to test
+it.
+
+The example below makes every day quiet from `22:00` through the `06:00` end
+minute in `Europe/London`, while leaving critical categories unsuppressed.
+Quiet hours are **off by default**. This is an illustrative excerpt, not a
+complete `alerts.json`: prefer the UI, and preserve existing rules and settings
+rather than replacing the file with this example.
+
<details>
-<summary><strong>Manual Configuration (JSON)</strong></summary>
+<summary><strong>Manual Configuration (JSON excerpt)</strong></summary>
```json
{
@@ -521,7 +555,22 @@ powered-off alerts.
"quietHours": {
"enabled": true,
"start": "22:00",
- "end": "06:00"
+ "end": "06:00",
+ "timezone": "Europe/London",
+ "days": {
+ "monday": true,
+ "tuesday": true,
+ "wednesday": true,
+ "thursday": true,
+ "friday": true,
+ "saturday": true,
+ "sunday": true
+ },
+ "suppress": {
+ "performance": false,
+ "storage": false,
+ "offline": false
+ }
}
}
}
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 74f3afa64a..df28fe2b71 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -604,8 +604,9 @@ alert was generated, routed or delivered to the intended recipient.
configured destinations and a successful test do not enable real delivery.
Turn delivery on there only when you intend to send alerts.
- Check the affected alert, the destination's **Enabled** state, minimum alert
- severity and tag filters. Review quiet hours and any mute, acknowledgement or
- maintenance policy before treating an absent attempt as a transport failure.
+ severity and tag filters. Review the [quiet-hours schedule](CONFIGURATION.md#quiet-hours-and-notification-holds)
+ and any mute, acknowledgement or maintenance policy before treating an absent
+ attempt as a transport failure.
- Use **Recent delivery activity** to correlate the original alert, destination
and absolute timestamp, including held-notification reasons. An empty window
is not proof of healthy delivery; an **unavailable** read is not an empty log.
diff --git a/frontend-modern/public/docs/CONFIGURATION.md b/frontend-modern/public/docs/CONFIGURATION.md
index b259cfef8c..1aeeb84aae 100644
--- a/frontend-modern/public/docs/CONFIGURATION.md
+++ b/frontend-modern/public/docs/CONFIGURATION.md
@@ -508,8 +508,42 @@ This tolerance delays activation; it does not disable powered-off monitoring.
Use the existing guest offline-alert toggle when a guest should never produce
powered-off alerts.
+### Quiet hours and notification holds
+
+Open **Alerts → Schedule → Quiet hours** to enable a notification quiet period.
+Choose the start and end times, an IANA timezone such as `Europe/London`, and
+**Quiet days**. No selected days means no quiet period, even when enabled.
+Times are interpreted in the selected timezone, not your browser's timezone.
+
+Quiet hours hold **non-critical notifications**; they do not stop monitoring,
+clear the alert or confirm recovery. Critical notifications remain eligible
+unless you explicitly select their **Suppress categories** (Performance,
+Storage or Offline). Selecting a category also holds its critical
+notifications, including urgent failures; leave it unchecked when those must
+still reach you. Other routing, mute and delivery policies still apply.
+
+A window can cross midnight. Days refer to the **current local calendar day**:
+with only Monday selected, `22:00`–`06:00` covers Monday's early morning and
+late evening, not Tuesday's early morning. Select Tuesday too if that part of
+the night must be quiet. The configured end minute is included: an end of
+`06:00` remains quiet through `06:00:59`.
+
+Eligible queued notifications are held for re-evaluation when the quiet period
+ends. This is not a promise to send every held item at that instant: current
+alert state, destination settings, other policies and provider failures still
+matter. Use [Recent delivery activity](TROUBLESHOOTING.md#test-succeeds-but-real-alerts-are-missing)
+to distinguish a quiet-hours hold from a failed delivery; a settings Test skips
+the queue and does not validate this schedule. Do not create an outage to test
+it.
+
+The example below makes every day quiet from `22:00` through the `06:00` end
+minute in `Europe/London`, while leaving critical categories unsuppressed.
+Quiet hours are **off by default**. This is an illustrative excerpt, not a
+complete `alerts.json`: prefer the UI, and preserve existing rules and settings
+rather than replacing the file with this example.
+
<details>
-<summary><strong>Manual Configuration (JSON)</strong></summary>
+<summary><strong>Manual Configuration (JSON excerpt)</strong></summary>
```json
{
@@ -521,7 +555,22 @@ powered-off alerts.
"quietHours": {
"enabled": true,
"start": "22:00",
- "end": "06:00"
+ "end": "06:00",
+ "timezone": "Europe/London",
+ "days": {
+ "monday": true,
+ "tuesday": true,
+ "wednesday": true,
+ "thursday": true,
+ "friday": true,
+ "saturday": true,
+ "sunday": true
+ },
+ "suppress": {
+ "performance": false,
+ "storage": false,
+ "offline": false
+ }
}
}
}
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index 74f3afa64a..df28fe2b71 100644
--- a/frontend-modern/public/docs/TROUBLESHOOTING.md
+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md
@@ -604,8 +604,9 @@ alert was generated, routed or delivered to the intended recipient.
configured destinations and a successful test do not enable real delivery.
Turn delivery on there only when you intend to send alerts.
- Check the affected alert, the destination's **Enabled** state, minimum alert
- severity and tag filters. Review quiet hours and any mute, acknowledgement or
- maintenance policy before treating an absent attempt as a transport failure.
+ severity and tag filters. Review the [quiet-hours schedule](CONFIGURATION.md#quiet-hours-and-notification-holds)
+ and any mute, acknowledgement or maintenance policy before treating an absent
+ attempt as a transport failure.
- Use **Recent delivery activity** to correlate the original alert, destination
and absolute timestamp, including held-notification reasons. An empty window
is not proof of healthy delivery; an **unavailable** read is not an empty log.
diff --git a/frontend-modern/src/utils/__tests__/quietHoursHelp.test.ts b/frontend-modern/src/utils/__tests__/quietHoursHelp.test.ts
new file mode 100644
index 0000000000..ee354c9578
--- /dev/null
+++ b/frontend-modern/src/utils/__tests__/quietHoursHelp.test.ts
@@ -0,0 +1,100 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+import { renderDocMarkdown } from '@/features/docs/docMarkdown';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const read = (name: string): string => readFileSync(path.join(root, name), 'utf8');
+const article = (name: string): HTMLElement => {
+ const element = document.createElement('article');
+ element.innerHTML = renderDocMarkdown(read(`docs/${name}.md`), name);
+ return element;
+};
+const quietHoursText = (): string => {
+ const guide = read('docs/CONFIGURATION.md');
+ const section = guide.split('### Quiet hours and notification holds')[1]?.split('<details>')[0];
+ expect(section, 'quiet-hours setup instructions must accompany the copied JSON').toBeDefined();
+ const element = document.createElement('article');
+ element.innerHTML = renderDocMarkdown(section!, 'CONFIGURATION');
+ return element.textContent!.replace(/\s+/g, ' ').trim();
+};
+
+describe('quiet-hours setup help', () => {
+ it('ships both exact guides and an expandable, complete JSON example', () => {
+ for (const name of ['CONFIGURATION', 'TROUBLESHOOTING']) {
+ expect(read(`frontend-modern/public/docs/${name}.md`)).toBe(read(`docs/${name}.md`));
+ }
+ const details = [...article('CONFIGURATION').querySelectorAll('details')].find((element) =>
+ element
+ .querySelector('summary')
+ ?.textContent?.includes('Manual Configuration (JSON excerpt)'),
+ );
+ expect(details).toBeDefined();
+ const example = JSON.parse(details!.querySelector('code')!.textContent!);
+ expect(example.schedule.quietHours).toEqual({
+ enabled: true,
+ start: '22:00',
+ end: '06:00',
+ timezone: 'Europe/London',
+ days: {
+ monday: true,
+ tuesday: true,
+ wednesday: true,
+ thursday: true,
+ friday: true,
+ saturday: true,
+ sunday: true,
+ },
+ suppress: { performance: false, storage: false, offline: false },
+ });
+ });
+
+ it('explains day, timezone and midnight boundaries rather than enabled alone', () => {
+ const text = quietHoursText();
+ expect(text).toContain('Alerts → Schedule → Quiet hours');
+ expect(text).toContain('No selected days means no quiet period, even when enabled');
+ expect(text).toContain("not your browser's timezone");
+ expect(text).toContain('current local calendar day');
+ expect(text).toContain("not Tuesday's early morning");
+ expect(text).toContain('Select Tuesday too');
+ expect(text).toContain('06:00:59');
+ });
+
+ it('keeps critical delivery, monitoring and current policy separate from held notifications', () => {
+ const text = quietHoursText();
+ expect(text).toContain('hold non-critical notifications');
+ expect(text).toContain('do not stop monitoring, clear the alert or confirm recovery');
+ expect(text).toContain('Critical notifications remain eligible unless');
+ expect(text).toContain('including urgent failures');
+ expect(text).toContain('not a promise to send every held item at that instant');
+ expect(text).toContain('a settings Test skips the queue and does not validate this schedule');
+ expect(text).toContain('Do not create an outage');
+ expect(text).toContain('off by default');
+ expect(text).toContain('not a complete alerts.json');
+ expect(text).toContain('preserve existing rules and settings');
+ });
+
+ it('connects troubleshooting and setup through real shipped section links', () => {
+ for (const [from, to, fragment, label] of [
+ [
+ 'TROUBLESHOOTING',
+ 'CONFIGURATION',
+ 'quiet-hours-and-notification-holds',
+ 'quiet-hours schedule',
+ ],
+ [
+ 'CONFIGURATION',
+ 'TROUBLESHOOTING',
+ 'test-succeeds-but-real-alerts-are-missing',
+ 'Recent delivery activity',
+ ],
+ ]) {
+ const link = article(from).querySelector(`a[href="/docs/${to}#${fragment}"]`);
+ expect(link?.textContent).toBe(label);
+ expect(link?.hasAttribute('data-doc-link')).toBe(true);
+ expect(article(to).querySelector(`[id="${fragment}"]`)).not.toBeNull();
+ }
+ });
+});
diff --git a/internal/alerts/configuration_guide_test.go b/internal/alerts/configuration_guide_test.go
new file mode 100644
index 0000000000..1a67bf2787
--- /dev/null
+++ b/internal/alerts/configuration_guide_test.go
@@ -0,0 +1,131 @@
+package alerts
+
+import (
+ "encoding/json"
+ "os"
+ "reflect"
+ "regexp"
+ "strings"
+ "testing"
+ "time"
+)
+
+// Exercise the actual copied JSON with the delivery owner's policy, without
+// opening stores, starting background workers or sending a notification.
+func documentedQuietHours(t *testing.T) *Manager {
+ t.Helper()
+ guide, err := os.ReadFile("../../docs/CONFIGURATION.md")
+ if err != nil {
+ t.Fatal(err)
+ }
+ _, section, ok := strings.Cut(string(guide), "## 🔔 Alerts (`alerts.json`)")
+ if !ok {
+ t.Fatal("missing alert configuration section")
+ }
+ section, _, _ = strings.Cut(section, "\n---\n")
+ block := regexp.MustCompile("(?s)```json\\s*\\n(.*?)\\n```").FindStringSubmatch(section)
+ if len(block) != 2 {
+ t.Fatal("missing alert configuration JSON example")
+ }
+ var config AlertConfig
+ if err := json.Unmarshal([]byte(block[1]), &config); err != nil {
+ t.Fatal(err)
+ }
+ loc := time.Local
+ if zone := config.Schedule.QuietHours.Timezone; zone != "" {
+ loc, err = time.LoadLocation(zone)
+ if err != nil {
+ t.Fatal(err)
+ }
+ }
+ return &Manager{config: config, quietHoursLoc: loc}
+}
+
+func TestDocumentedQuietHoursHoldWarningsOnEveryDay(t *testing.T) {
+ m := documentedQuietHours(t)
+ policy := m.QuietHoursNotificationPolicy()
+ alert := &Alert{ID: "guide", Type: "cpu", Level: AlertLevelWarning}
+ for day := 5; day <= 11; day++ { // Monday through Sunday, in summer time.
+ for _, hour := range []int{1, 22} {
+ now := time.Date(2026, time.October, day, hour, 30, 0, 0, m.quietHoursLoc)
+ if at := policy(alert, now); at == nil || !at.After(now) {
+ t.Errorf("documented %s %02d:30 schedule did not hold warning: %v", now.Weekday(), hour, at)
+ }
+ }
+ }
+}
+
+func TestDocumentedQuietHoursClockAndEndMinute(t *testing.T) {
+ m := documentedQuietHours(t)
+ policy := m.QuietHoursNotificationPolicy()
+ alert := &Alert{Type: "cpu", Level: AlertLevelWarning}
+ for _, tc := range []struct {
+ name string
+ now time.Time
+ held bool
+ }{
+ {"before start in BST", time.Date(2026, 10, 5, 20, 59, 59, 0, time.UTC), false},
+ {"start in BST", time.Date(2026, 10, 5, 21, 0, 0, 0, time.UTC), true},
+ {"last second of end minute", time.Date(2026, 10, 6, 5, 0, 59, 0, time.UTC), true},
+ {"after end minute", time.Date(2026, 10, 6, 5, 1, 0, 0, time.UTC), false},
+ {"daytime", time.Date(2026, 10, 6, 12, 0, 0, 0, time.UTC), false},
+ {"before start in GMT", time.Date(2026, 12, 7, 21, 59, 59, 0, time.UTC), false},
+ {"start in GMT", time.Date(2026, 12, 7, 22, 0, 0, 0, time.UTC), true},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ if at := policy(alert, tc.now); (at != nil) != tc.held {
+ t.Fatalf("held=%t, want %t; re-evaluation=%v", at != nil, tc.held, at)
+ }
+ })
+ }
+ now := time.Date(2026, 10, 5, 21, 30, 0, 0, time.UTC)
+ want := time.Date(2026, 10, 6, 5, 1, 0, 0, time.UTC)
+ if at := policy(alert, now); at == nil || !at.Equal(want) {
+ t.Fatalf("re-evaluation=%v, want %v", at, want)
+ }
+}
+
+func TestDocumentedQuietHoursKeepCriticalCategoriesEligible(t *testing.T) {
+ m := documentedQuietHours(t)
+ now := time.Date(2026, 10, 5, 22, 30, 0, 0, m.quietHoursLoc)
+ for _, kind := range []string{"cpu", "disk-health", "connectivity"} {
+ alert := &Alert{ID: "guide-" + kind, Type: kind, Level: AlertLevelCritical,
+ Acknowledged: true, Metadata: map[string]interface{}{"occurrence": "retained"}}
+ before := alert.Clone()
+ if at := m.QuietHoursNotificationPolicy()(alert, now); at != nil {
+ t.Errorf("example held critical %s until %v", kind, at)
+ }
+ m.config.Schedule.QuietHours.Suppress = QuietHoursSuppression{Performance: true, Storage: true, Offline: true}
+ if at := m.QuietHoursNotificationPolicy()(alert, now); at == nil {
+ t.Errorf("category opt-in did not hold critical %s", kind)
+ }
+ m.config.Schedule.QuietHours.Suppress = QuietHoursSuppression{}
+ if !reflect.DeepEqual(before, alert) {
+ t.Error("notification hold changed alert lifecycle or occurrence")
+ }
+ }
+}
+
+func TestDocumentedQuietHoursDaysAreLocalCalendarDays(t *testing.T) {
+ m := documentedQuietHours(t)
+ alert := &Alert{Type: "cpu", Level: AlertLevelWarning}
+ m.config.Schedule.QuietHours.Days = map[string]bool{"monday": true}
+ policy := m.QuietHoursNotificationPolicy()
+ for _, tc := range []struct {
+ day int
+ hour int
+ held bool
+ }{{5, 1, true}, {5, 22, true}, {6, 1, false}} {
+ now := time.Date(2026, 10, tc.day, tc.hour, 30, 0, 0, m.quietHoursLoc)
+ if at := policy(alert, now); (at != nil) != tc.held {
+ t.Errorf("%s %02d:30 held=%t, want %t", now.Weekday(), tc.hour, at != nil, tc.held)
+ }
+ }
+ // The original incomplete example omitted days entirely. Enabled alone
+ // must not be mistaken for an active notification hold.
+ m.config.Schedule.QuietHours.Days = nil
+ now := time.Date(2026, 10, 5, 22, 30, 0, 0, m.quietHoursLoc)
+ if at := m.QuietHoursNotificationPolicy()(alert, now); at != nil {
+ t.Errorf("no selected days invented a hold: %v", at)
+ }
+}