From a1b1de584cfd7384ca1f07c6083274b6af0c4fef Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Fri, 9 May 2025 21:03:38 +0200 Subject: [PATCH] docs(alerting): fix broken links due to using shared md files (#105195) * docs(alerting): fix broken links due to using shared md files * fix prettier errors * fix aliased links --- .../create-data-source-managed-rule.md | 50 ++++++++++++-- .../create-grafana-managed-rule.md | 40 ++++++++++- .../configure-notifications/create-silence.md | 68 ++++++++++++++++++- .../configure-notifications/mute-timings.md | 13 +++- .../fundamentals/alert-rules/_index.md | 10 ++- .../notifications/notification-policies.md | 53 ++++++++++++++- 6 files changed, 219 insertions(+), 15 deletions(-) diff --git a/docs/sources/alerting/alerting-rules/create-data-source-managed-rule.md b/docs/sources/alerting/alerting-rules/create-data-source-managed-rule.md index 44fed1d97cb..9c0836726a3 100644 --- a/docs/sources/alerting/alerting-rules/create-data-source-managed-rule.md +++ b/docs/sources/alerting/alerting-rules/create-data-source-managed-rule.md @@ -22,9 +22,9 @@ weight: 200 refs: shared-configure-prometheus-data-source-alerting: - pattern: /docs/grafana/ - destination: /docs/grafana//datasources/prometheus/configure-prometheus-data-source/#alerting + destination: /docs/grafana//datasources/prometheus/configure/ - pattern: /docs/grafana-cloud/ - destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/prometheus/configure-prometheus-data-source/#alerting + destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/prometheus/configure/ configure-grafana-managed-rules: - pattern: /docs/grafana/ destination: /docs/grafana//alerting/alerting-rules/create-grafana-managed-rule/ @@ -85,7 +85,11 @@ The rules are stored within the data source. In a distributed architecture, they We recommend using [Grafana-managed alert rules](ref:configure-grafana-managed-rules) whenever possible and opting for data source-managed alert rules when scaling your alerting setup is necessary. -{{< docs/shared lookup="alerts/note-prometheus-ds-rules.md" source="grafana" version="" >}} +> Rules from a Prometheus data source appear in the **Data source-managed** section of the **Alert rules** page when [Manage alerts via Alerting UI](ref:shared-configure-prometheus-data-source-alerting) is enabled. +> +> However, Grafana can only create and edit data source-managed rules for Mimir and Loki, not for a Prometheus instance. + +[//]: <> ({{< docs/shared lookup="alerts/note-prometheus-ds-rules.md" source="grafana" version="" >}}) To create or edit data source-managed alert rules, follow these instructions. @@ -107,7 +111,13 @@ Alert rules for Mimir or Loki instances can be edited or deleted by users with * If you do not want to manage alert rules for a particular data source, go to its settings and clear the **Manage alerts via Alerting UI** checkbox. -{{< docs/shared lookup="alerts/configure-provisioning-before-begin.md" source="grafana" version="" >}} +### Provisioning + +Note that if you delete an alert resource created in the UI, you can no longer retrieve it. + +To backup and manage alert rules, you can [provision alerting resources](ref:shared-provision-alerting-resources) using options such as configuration files, Terraform, or the Alerting API. + +[//]: <> ({{< docs/shared lookup="alerts/configure-provisioning-before-begin.md" source="grafana" version="" >}}) {{< docs/shared lookup="alerts/configure-alert-rule-name.md" source="grafana" version="" >}} @@ -154,4 +164,34 @@ All alert rules and instances, irrespective of their labels, match the default n Add custom labels by selecting existing key-value pairs from the drop down, or add new labels by entering the new key or value. -{{< docs/shared lookup="alerts/configure-notification-message.md" source="grafana" version="" >}} +## Configure notification message + +Use [annotations](ref:shared-annotations) to add information to alert messages that can help respond to the alert. + +Annotations are included by default in notification messages, and can use text or [templates](ref:shared-alert-rule-template) to display dynamic data from queries. + +Grafana provides several optional annotations. + +1. Optional: Add a summary. + + Short summary of what happened and why. + +1. Optional: Add a description. + + Description of what the alert rule does. + +1. Optional: Add a Runbook URL. + + Webpage where you keep your runbook for the alert + +1. Optional: Add a custom annotation. + + Add any additional information that could help address the alert. + +1. Optional: **Link dashboard and panel**. + + [Link the alert rule to a panel](ref:shared-link-alert-rules-to-panels) to facilitate alert investigation. + +1. Click **Save rule**. + +[//]: <> ({{< docs/shared lookup="alerts/configure-notification-message.md" source="grafana" version="" >}}) diff --git a/docs/sources/alerting/alerting-rules/create-grafana-managed-rule.md b/docs/sources/alerting/alerting-rules/create-grafana-managed-rule.md index a05cf160c9f..ac42779b142 100644 --- a/docs/sources/alerting/alerting-rules/create-grafana-managed-rule.md +++ b/docs/sources/alerting/alerting-rules/create-grafana-managed-rule.md @@ -145,7 +145,13 @@ Verify that the data sources you plan to query in the alert rule are [compatible Only users with **Edit** permissions for the folder storing the rules can edit or delete Grafana-managed alert rules. Only admins can restore deleted Grafana-managed alert rules. -{{< docs/shared lookup="alerts/configure-provisioning-before-begin.md" source="grafana" version="" >}} +### Provisioning + +Note that if you delete an alert resource created in the UI, you can no longer retrieve it. + +To backup and manage alert rules, you can [provision alerting resources](ref:shared-provision-alerting-resources) using options such as configuration files, Terraform, or the Alerting API. + +[//]: <> ({{< docs/shared lookup="alerts/configure-provisioning-before-begin.md" source="grafana" version="" >}}) ### Default vs Advanced options @@ -287,7 +293,37 @@ Complete the following steps to set up notifications. 1. Click **See details** to view alert routing details and an email preview. -{{< docs/shared lookup="alerts/configure-notification-message.md" source="grafana" version="" >}} +## Configure notification message + +Use [annotations](ref:shared-annotations) to add information to alert messages that can help respond to the alert. + +Annotations are included by default in notification messages, and can use text or [templates](ref:shared-alert-rule-template) to display dynamic data from queries. + +Grafana provides several optional annotations. + +1. Optional: Add a summary. + + Short summary of what happened and why. + +1. Optional: Add a description. + + Description of what the alert rule does. + +1. Optional: Add a Runbook URL. + + Webpage where you keep your runbook for the alert + +1. Optional: Add a custom annotation. + + Add any additional information that could help address the alert. + +1. Optional: **Link dashboard and panel**. + + [Link the alert rule to a panel](ref:shared-link-alert-rules-to-panels) to facilitate alert investigation. + +1. Click **Save rule**. + +[//]: <> ({{< docs/shared lookup="alerts/configure-notification-message.md" source="grafana" version="" >}}) ## Permanently delete or restore deleted alert rules diff --git a/docs/sources/alerting/configure-notifications/create-silence.md b/docs/sources/alerting/configure-notifications/create-silence.md index 5cf6f4a9c04..ba08f790d4d 100644 --- a/docs/sources/alerting/configure-notifications/create-silence.md +++ b/docs/sources/alerting/configure-notifications/create-silence.md @@ -67,7 +67,18 @@ Silences stop notifications from being created for a specified time window but d Silences are assigned to a [specific Alertmanager](ref:alertmanager-architecture) and only suppress notifications for alerts managed by that Alertmanager. {{< /admonition >}} -{{< docs/shared lookup="alerts/mute-timings-vs-silences.md" source="grafana" version="" >}} +## Mute timings vs silences + +[Mute timings](ref:shared-mute-timings) and [silences](ref:shared-silences) are distinct methods to suppress notifications. They do not prevent alert rules from being evaluated or stop alert instances from appearing in the user interface; they only prevent notifications from being created. + +The following table highlights the key differences between mute timings and silences. + +| | Mute timing | Silence | +| ---------- | ----------------------------------------------------------- | ---------------------------------------------------------------- | +| **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 | + +[//]: <> ({{< docs/shared lookup="alerts/mute-timings-vs-silences.md" source="grafana" version="" >}}) ## Add silences @@ -81,9 +92,60 @@ To add a silence, complete the following steps. 1. Optionally, in **Duration**, specify how long the silence is enforced. This automatically updates the end time in the **Silence start and end** field. 1. In the **Label** and **Value** fields, enter one or more _Matching Labels_ to determine which alerts the silence applies to. - {{< docs/shared lookup="alerts/how_label_matching_works.md" source="grafana" version="" >}} + {{< collapse title="How label matching works" >}} - Any matching alerts (in the firing state only) display under **Affected alert instances**. +Use [labels](ref:shared-alert-labels) and label matchers to link alert rules to [notification policies](ref:shared-notification-policies) and [silences](ref:shared-silences). This allows for a flexible way to manage your alert instances, specify which policy should handle them, and which alerts to silence. + +A label matchers consists of 3 distinct parts, the **label**, the **value** and the **operator**. + +- The **Label** field is the name of the label to match. It must exactly match the label name. + +- The **Value** field matches against the corresponding value for the specified **Label** name. How it matches depends on the **Operator** value. + +- The **Operator** field is the operator to match against the label value. The available operators are: + + | Operator | Description | + | -------- | -------------------------------------------------- | + | `=` | Select labels that are exactly equal to the value. | + | `!=` | Select labels that are not equal to the value. | + | `=~` | Select labels that regex-match the value. | + | `!~` | Select labels that do not regex-match the value. | + +{{% admonition type="note" %}} +If you are using multiple label matchers, they are combined using the AND logical operator. This means that all matchers must match in order to link a rule to a policy. +{{% /admonition %}} + +**Label matching example** + +If you define the following set of labels for your alert: + +`{ foo=bar, baz=qux, id=12 }` + +then: + +- A label matcher defined as `foo=bar` matches this alert rule. +- A label matcher defined as `foo!=bar` does _not_ match this alert rule. +- A label matcher defined as `id=~[0-9]+` matches this alert rule. +- A label matcher defined as `baz!~[0-9]+` matches this alert rule. +- Two label matchers defined as `foo=bar` and `id=~[0-9]+` match this alert rule. + +**Exclude labels** + +You can also write label matchers to exclude labels. + +Here is an example that shows how to exclude the label `Team`. You can choose between any of the values below to exclude labels. + +| Label | Operator | Value | +| ------ | -------- | ----- | +| `team` | `=` | `""` | +| `team` | `!~` | `.+` | +| `team` | `=~` | `^$` | + + {{< /collapse >}} + +[//]: <> ({{< docs/shared lookup="alerts/how_label_matching_works.md" source="grafana" version="" >}}) + +Any matching alerts (in the firing state only) display under **Affected alert instances**. 1. In **Comment**, add details about the silence. 1. Click **Submit**. diff --git a/docs/sources/alerting/configure-notifications/mute-timings.md b/docs/sources/alerting/configure-notifications/mute-timings.md index 79be30654e0..e0394f4b70b 100644 --- a/docs/sources/alerting/configure-notifications/mute-timings.md +++ b/docs/sources/alerting/configure-notifications/mute-timings.md @@ -47,7 +47,18 @@ Use mute timings to temporarily pause notifications for a specific recurring per Mute timings are assigned to a [specific Alertmanager](ref:alertmanager-architecture) and only suppress notifications for alerts managed by that Alertmanager. {{< /admonition >}} -{{< docs/shared lookup="alerts/mute-timings-vs-silences.md" source="grafana" version="" >}} +## Mute timings vs silences + +[Mute timings](ref:shared-mute-timings) and [silences](ref:shared-silences) are distinct methods to suppress notifications. They do not prevent alert rules from being evaluated or stop alert instances from appearing in the user interface; they only prevent notifications from being created. + +The following table highlights the key differences between mute timings and silences. + +| | Mute timing | Silence | +| ---------- | ----------------------------------------------------------- | ---------------------------------------------------------------- | +| **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 | + +[//]: <> ({{< docs/shared lookup="alerts/mute-timings-vs-silences.md" source="grafana" version="" >}}) ## Add mute timings diff --git a/docs/sources/alerting/fundamentals/alert-rules/_index.md b/docs/sources/alerting/fundamentals/alert-rules/_index.md index 439c56b130c..59d15cb930a 100644 --- a/docs/sources/alerting/fundamentals/alert-rules/_index.md +++ b/docs/sources/alerting/fundamentals/alert-rules/_index.md @@ -20,9 +20,9 @@ weight: 100 refs: shared-configure-prometheus-data-source-alerting: - pattern: /docs/grafana/ - destination: /docs/grafana//datasources/prometheus/configure-prometheus-data-source/#alerting + destination: /docs/grafana//datasources/prometheus/configure/ - pattern: /docs/grafana-cloud/ - destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/prometheus/configure-prometheus-data-source/#alerting + destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/prometheus/configure/ queries-and-conditions: - pattern: /docs/grafana/ destination: /docs/grafana//alerting/fundamentals/alert-rules/queries-conditions/#data-source-queries @@ -102,7 +102,11 @@ Data source-managed alert rules can only be created using Grafana Mimir or Grafa 1. Alert rules are evaluated by the Alert Rule Evaluation Engine within the data source. 1. Firing and resolved alert instances are forwarded to [handle their notifications](ref:notifications). -{{< docs/shared lookup="alerts/note-prometheus-ds-rules.md" source="grafana" version="" >}} +> Rules from a Prometheus data source appear in the **Data source-managed** section of the **Alert rules** page when [Manage alerts via Alerting UI](ref:shared-configure-prometheus-data-source-alerting) is enabled. +> +> However, Grafana can only create and edit data source-managed rules for Mimir and Loki, not for a Prometheus instance. + +[//]: <> ({{< docs/shared lookup="alerts/note-prometheus-ds-rules.md" source="grafana" version="" >}}) ## Comparison between alert rule types diff --git a/docs/sources/alerting/fundamentals/notifications/notification-policies.md b/docs/sources/alerting/fundamentals/notifications/notification-policies.md index ae8d53f1520..2182796cdcc 100644 --- a/docs/sources/alerting/fundamentals/notifications/notification-policies.md +++ b/docs/sources/alerting/fundamentals/notifications/notification-policies.md @@ -71,7 +71,58 @@ Notification policies are _not_ a list, but rather are structured according to a Each policy consists of a set of label matchers (0 or more) that specify which alerts they are or aren't interested in handling. A matching policy refers to a notification policy with label matchers that match the alert instance’s labels. -{{< docs/shared lookup="alerts/how_label_matching_works.md" source="grafana" version="" >}} +{{< collapse title="How label matching works" >}} + +Use [labels](ref:shared-alert-labels) and label matchers to link alert rules to [notification policies](ref:shared-notification-policies) and [silences](ref:shared-silences). This allows for a flexible way to manage your alert instances, specify which policy should handle them, and which alerts to silence. + +A label matchers consists of 3 distinct parts, the **label**, the **value** and the **operator**. + +- The **Label** field is the name of the label to match. It must exactly match the label name. + +- The **Value** field matches against the corresponding value for the specified **Label** name. How it matches depends on the **Operator** value. + +- The **Operator** field is the operator to match against the label value. The available operators are: + + | Operator | Description | + | -------- | -------------------------------------------------- | + | `=` | Select labels that are exactly equal to the value. | + | `!=` | Select labels that are not equal to the value. | + | `=~` | Select labels that regex-match the value. | + | `!~` | Select labels that do not regex-match the value. | + +{{% admonition type="note" %}} +If you are using multiple label matchers, they are combined using the AND logical operator. This means that all matchers must match in order to link a rule to a policy. +{{% /admonition %}} + +**Label matching example** + +If you define the following set of labels for your alert: + +`{ foo=bar, baz=qux, id=12 }` + +then: + +- A label matcher defined as `foo=bar` matches this alert rule. +- A label matcher defined as `foo!=bar` does _not_ match this alert rule. +- A label matcher defined as `id=~[0-9]+` matches this alert rule. +- A label matcher defined as `baz!~[0-9]+` matches this alert rule. +- Two label matchers defined as `foo=bar` and `id=~[0-9]+` match this alert rule. + +**Exclude labels** + +You can also write label matchers to exclude labels. + +Here is an example that shows how to exclude the label `Team`. You can choose between any of the values below to exclude labels. + +| Label | Operator | Value | +| ------ | -------- | ----- | +| `team` | `=` | `""` | +| `team` | `!~` | `.+` | +| `team` | `=~` | `^$` | + +{{< /collapse >}} + +[//]: <> ({{< docs/shared lookup="alerts/how_label_matching_works.md" source="grafana" version="" >}}) {{< figure src="/media/docs/alerting/notification-routing.png" max-width="750px" caption="Matching alert instances with notification policies" alt="Example of a notification policy tree" >}}