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
Make quiet-hours setup select a real notification window
pulse-triage[bot]ef2df62f1726
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.mdindex 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 producepowered-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.mdindex 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, destinationand absolute timestamp, including held-notification reasons. An empty windowis 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.mdindex 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 producepowered-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.mdindex 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, destinationand absolute timestamp, including held-notification reasons. An empty windowis 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.tsnew file mode 100644index 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.gonew file mode 100644index 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)+ }+}