Alerting: add "about alert rules" section (#49413)

* Alerting: add "about alert rules" section

* chore: adds descriptions and keywords

* Docs: update image locations

* chore: fix typo

docs/sources/alerting/about-alert-rules/_index.md

@@ -0,0 +1,19 @@
++++
+title = "About alert rules"
+description = "Learn about Grafana alert rules"
+keywords = ["grafana", "alerting", "rules"]
+weight = 101
++++
+
+# About alert rules
+
+An alerting rule is a set of evaluation criteria that determines whether an alert instance will fire. The rule consists of one or more queries and expressions, a condition, the frequency of evaluation, and optionally, the duration over which the condition is met.
+
+While queries and expressions select the data set to evaluate, a condition sets the threshold that an alert must meet or exceed to create an alert.
+
+An interval specifies how frequently an alerting rule is evaluated. Duration, when configured, indicates how long a condition must be met. The alert rules can also define alerting behavior in the absence of data.
+
+- [Alert rule types]({{< relref "./alert-rule-types.md" >}})
+- [Alert instances]({{< relref "./alert-instances.md" >}})
+- [Organising alert rules]({{< relref "./organising-alerts.md" >}})
+- [Annotation and labels]({{< relref "../fundamentals/annotation-label/_index.md" >}})

docs/sources/alerting/about-alert-rules/alert-instances.md

@@ -0,0 +1,22 @@
++++
+title = "Alert instances"
+description = "Learn about Grafana alert instances"
+keywords = ["grafana", "alerting", "instances"]
+weight = 103
++++
+
+# Alert instances
+
+Grafana managed alerts support multi-dimensional alerting. Each alert rule can create multiple alert instances. This is exceptionally powerful if you are observing multiple series in a single expression.
+
+Consider the following PromQL expression:
+
+```promql
+sum by(cpu) (
+  rate(node_cpu_seconds_total{mode!="idle"}[1m])
+)
+```
+
+A rule using this expression will create as many alert instances as the amount of CPUs we are observing after the first evaluation, allowing a single rule to report the status of each CPU.
+
+{{< figure src="/static/img/docs/alerting/unified/multi-dimensional-alert.png" caption="A multi-dimensional Grafana managed alert rule" >}}

docs/sources/alerting/about-alert-rules/alert-rule-types.md

@@ -0,0 +1,30 @@
++++
+title = "Alert rule types"
+description = "Learn about the different alert rule types"
+keywords = ["grafana", "alerting", "rule types"]
+weight = 102
++++
+
+# Alert rule types
+
+Grafana supports several alert rule types, the following sections will explain their merits and demerits and help you choose the right alert type for your use case.
+
+## Grafana managed rules
+
+Grafana-managed rules are the most flexible alert rule type. They allow you to create alerts that can act on data from any of your existing data sources.
+
+In additional to supporting any datasource you can also add additional [expressions]({{< relref "../../panels/query-a-data-source/use-expressions-to-manipulate-data/_index.md" >}}) to transform your data and express alert conditions.
+
+## Mimir, Loki and Cortex rules
+
+To create Mimir, Loki or Cortex alerts you must have a compatible Prometheus data source. You can check if your data source is compatible by testing the data source and checking the details if the ruler API is supported.
+
+{{< figure src="/static/img/docs/alerting/unified/mimir-datasource-check.png" caption="Successfully connected to a Mimir Prometheus datasource" max-width="40%" >}}
+
+## Recording rules
+
+Recording rules are only available for compatible Prometheus data sources like Mimir, Loki and Cortex.
+
+A recording rule allows you to save an expression's result to a new set of time series. This is useful if you want to run alerts on aggregated data or if you have dashboards that query the same expression repeatedly.
+
+Read more about [recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/) in Prometheus.

docs/sources/alerting/about-alert-rules/organising-alerts.md

@@ -0,0 +1,22 @@
++++
+title = "Organising alert rules"
+description = "Learn how to organize alert rules"
+keywords = ["grafana", "alerting", "organization"]
+weight = 104
++++
+
+## Namespaces and groups
+
+Alerts can be organized using Folders for Grafana-managed rules and namespaces for Mimir or Loki rules and group names.
+
+### Namespaces
+
+When creating Grafana-managed rules, the folder can be used to perform access control and grant or deny access to all rules within a specific folder.
+
+### Groups
+
+All rules within a group are evaluated at the same **interval**.
+
+Alert rules and recording rules within a group will always be evaluated **sequentially**, meaning no rules will be evaluated at the same time and in order of appearance.
+
+> **Note** If you want rules to be evaluated concurrently and with different intervals, consider storing them in different groups.

docs/sources/alerting/silences/_index.md

@@ -10,13 +10,13 @@ aliases = ["/docs/grafana/latest/alerting/unified-alerting/silences/"]
 
 Use silences to stop notifications from one or more alerting rules. Silences do not prevent alert rules from being evaluated. Nor do they not stop alerting instances from being shown in the user interface. Silences only stop notifications from getting created. A silence lasts for only a specified window of time.
 
-Silences do not prevent alert rules from being evaluated. They also do not stop alert instances being shown in the user interface. Silences only prevent notifications from being created.
+Silences do not prevent alert rules from being evaluated. They also do not stop alert instances from being shown in the user interface. Silences only prevent notifications from being created.
 
 You can configure Grafana managed silences as well as silences for an [external Alertmanager data source]({{< relref "../../datasources/alertmanager.md" >}}). For more information, see [Alertmanager]({{< relref "../fundamentals/alertmanager.md" >}}).
 
 See also:
 
-- [About label matching for alert suppression]({{< relref "./label-matching-alert-suppression.md" >}})
+- [How label matching works]({{< relref "../fundamentals/annotation-label/labels-and-label-matchers.md" >}})
 - [Create a silence]({{< relref "./create-silence.md" >}})
 - [Create a URL to link to a silence form]({{< relref "./linking-to-silence-form.md" >}})
 - [Edit silences]({{< relref "./edit-silence.md" >}})

docs/sources/alerting/silences/create-silence.md

@@ -13,12 +13,12 @@ Silences stop notifications from getting created and last for only a specified w
 To add a silence:
 
 1. In the Grafana menu, click the **Alerting** (bell) icon to open the Alerting page listing existing alerts.
-2. In the Alerting page, click **Silences** to open the page listing existing contact points.
+2. On the Alerting page, click **Silences** to open the page listing existing contact points.
 3. From Alertmanager drop-down, select an external Alertmanager to create and manage silences for the external data source. Otherwise, keep the default option of Grafana.
 4. Click **New Silence** to open the Create silence page.
 5. In **Silence start and end**, select the start and end date to indicate when the silence should go into effect and expire.
 6. Optionally, in **Duration**, specify how long the silence is enforced. This automatically updates the end time in the **Silence start and end** field.
-7. In the **Name** and **Value** fields, enter one or more _Matching Labels_. Matchers determine which rules the silence will apply to. For more information, see [Label matching for alert suppression]({{< relref "./label-matching-alert-suppression.md" >}}).
+7. In the **Name** and **Value** fields, enter one or more _Matching Labels_. Matchers determine which rules the silence will apply to. For more information, see [how label matching works]({{< relref "../fundamentals/annotation-label/labels-and-label-matchers.md" >}}).
 8. In **Comment**, add details about the silence.
 9. In **Creator**, enter the name of the silence owner or keep the default owner.
 10. Click **Create**.

docs/sources/alerting/silences/label-matching-alert-suppression.md

@@ -1,21 +0,0 @@
-+++
-title = "Label matching and alert suppression"
-description = "Silences alert notifications"
-keywords = ["grafana", "alerting", "silence", "mute"]
-weight = 452
-aliases = ["/docs/grafana/latest/alerting/unified-alerting/silences/"]
-+++
-
-# About label matching for alert suppression
-
-Grafana suppresses notifications only for alerts with labels that match all the "Matching Labels" specified in the silence.
-
-- The **Label** field is the name of the label to match. It must exactly match the label name.
-- The **Operator** field is the operator to match against the label value. The available operators are:
-
-  - `=`: Select labels that are exactly equal to the provided string.
-  - `!=`: Select labels that are not equal to the provided string.
-  - `=~`: Select labels that regex-match the provided string.
-  - `!~`: Select labels that do not regex-match the provided string.
-
-- The **Value** field matches against the corresponding value for the specified **Label** name. How it matches depends on the **Operator** value.