alerting docs: clarify silences/mute timings details

2026-01-12 11:31:18 -06:00
parent 0d1ec94548
commit 8fbf19c8b0
2 changed files with 52 additions and 1 deletions
@@ -79,6 +79,24 @@ The following table highlights the key differences between mute timings and sile
 | **Setup**  | Created and then added to notification policies             | Matches alerts using labels to determine whether to silence them |
 | **Period** | Uses time interval definitions that can repeat periodically | Has a fixed start and end time                                   |

+**When to use mute timings**
+
+Use mute timings for predictable, recurring time periods when you don't want to receive notifications:
+
+- Regular maintenance windows (for example, every Sunday from 2:00 AM to 4:00 AM)
+- Non-business hours (for example, nights and weekends)
+- Scheduled deployments or known change windows
+- Regular testing periods
+
+**When to use silences**
+
+Use silences for one-time or ad-hoc suppression of notifications:
+
+- Active incident response (suppress notifications while investigating)
+- Immediate suppression of a specific alert or group of alerts
+- One-time maintenance or deployment events
+- Temporarily suppress alerts for specific services or components
+
 [//]: <> ({{< docs/shared lookup="alerts/mute-timings-vs-silences.md" source="grafana" version="<GRAFANA_VERSION>" >}})

 ## Add silences
@@ -168,7 +186,22 @@ To remove a silence, complete the following steps.
 1. Click **Silences** to view the list of existing silences.
 1. Select the silence you want to end, then click **Unsilence**.

-> **Note:** You cannot remove a silence manually. Silences that have ended are retained and listed for five days.
+{{< admonition type="note" >}}
+Clicking **Unsilence** ends the silence immediately, which is the only way to end a silence before its configured end time. Silences cannot be permanently deleted manually.
+{{< /admonition >}}
+
+## Silence duration and retention
+
+**Duration limits**
+
+There is no maximum duration for a silence. You can create a silence for any length of time. However, administrators can configure the following limits:
+
+- `alertmanager_max_silences_count`: Maximum number of active and pending silences per tenant (default: 0, no limit)
+- `alertmanager_max_silence_size_bytes`: Maximum size of a silence in bytes (default: 0, no limit)
+
+**Expired silence retention**
+
+Expired silences are automatically deleted after 5 days. This retention period is not configurable. The cleanup process runs automatically every 15 minutes to remove expired silences that are older than the retention period.

 ## Rule-specific silences

@@ -15,3 +15,21 @@ The following table highlights the key differences between mute timings and sile
 | ---------- | ----------------------------------------------------------- | ---------------------------------------------------------------- |
 | **Setup**  | Created and then added to notification policies             | Matches alerts using labels to determine whether to silence them |
 | **Period** | Uses time interval definitions that can repeat periodically | Has a fixed start and end time                                   |
+
+**When to use mute timings**
+
+Use mute timings for predictable, recurring time periods when you don't want to receive notifications:
+
+- Regular maintenance windows (for example, every Sunday from 2:00 AM to 4:00 AM)
+- Non-business hours (for example, nights and weekends)
+- Scheduled deployments or known change windows
+- Regular testing periods
+
+**When to use silences**
+
+Use silences for one-time or ad-hoc suppression of notifications:
+
+- Active incident response (suppress notifications while investigating)
+- Immediate suppression of a specific alert or group of alerts
+- One-time maintenance or deployment events
+- Temporarily suppress alerts for specific services or components