From 8fbf19c8b06e142cf52d9cf85694b23a72fe8ab2 Mon Sep 17 00:00:00 2001
From: "Johnny K." <johnny.kartheiser@grafana.com>
Date: Mon, 12 Jan 2026 11:31:18 -0600
Subject: [PATCH] alerting docs: clarify silences/mute timings details

---
 .../configure-notifications/create-silence.md | 35 ++++++++++++++++++-
 .../shared/alerts/mute-timings-vs-silences.md | 18 ++++++++++
 2 files changed, 52 insertions(+), 1 deletion(-)

diff --git a/docs/sources/alerting/configure-notifications/create-silence.md b/docs/sources/alerting/configure-notifications/create-silence.md
index faf41d9a892..9626b9c12ee 100644
--- a/docs/sources/alerting/configure-notifications/create-silence.md
+++ b/docs/sources/alerting/configure-notifications/create-silence.md
@@ -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
 
diff --git a/docs/sources/shared/alerts/mute-timings-vs-silences.md b/docs/sources/shared/alerts/mute-timings-vs-silences.md
index 163cb2dcca5..0a7e1d8835a 100644
--- a/docs/sources/shared/alerts/mute-timings-vs-silences.md
+++ b/docs/sources/shared/alerts/mute-timings-vs-silences.md
@@ -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