From 7db4119b485d3310f715b9e4fca750c979cefa25 Mon Sep 17 00:00:00 2001 From: JitaC <70489351+achatterjee-grafana@users.noreply.github.com> Date: Wed, 25 May 2022 18:53:05 -0400 Subject: [PATCH] Check in changes. --- docs/sources/alerting/_index.md | 5 ++- docs/sources/alerting/fundamentals/_index.md | 1 + .../fundamentals/alert-rules/_index.md | 19 +++++++++ .../alert-rules/alert-instances.md | 22 ++++++++++ .../alert-rules/alert-rule-types.md | 30 ++++++++++++++ .../alert-rules/organising-alerts.md | 22 ++++++++++ .../alerting/migrating-alerts/opt-out.md | 40 +++++++++++++++++++ 7 files changed, 137 insertions(+), 2 deletions(-) create mode 100644 docs/sources/alerting/fundamentals/alert-rules/_index.md create mode 100644 docs/sources/alerting/fundamentals/alert-rules/alert-instances.md create mode 100644 docs/sources/alerting/fundamentals/alert-rules/alert-rule-types.md create mode 100644 docs/sources/alerting/fundamentals/alert-rules/organising-alerts.md create mode 100644 docs/sources/alerting/migrating-alerts/opt-out.md diff --git a/docs/sources/alerting/_index.md b/docs/sources/alerting/_index.md index 72206e75b36..12e9bfd4bc5 100644 --- a/docs/sources/alerting/_index.md +++ b/docs/sources/alerting/_index.md @@ -23,8 +23,9 @@ For new installations or existing installs without alerting configured, Grafana Before you begin, we recommend that you familiarize yourself with some of the [fundamental concepts]({{< relref "./fundamentals/_index.md" >}}) of Grafana alerting. Refer to [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to learn more about controlling access to alerts using role-based permissions. -- [Enable Grafana alerting in OSS]({{< relref "./opt-in.md" >}}) -- [Migrating legacy alerts]({{< relref "./migrating-legacy-alerts.md" >}}) +- [About alert rules]({{< relref "./fundamentals/alert-rules/_index.md" >}}) +- [Migrating legacy alerts]({{< relref "./migrating-alerts/_index.md" >}}) +- [Disable Grafana alerting in OSS]({{< relref "./migrating-alerts/opt-out.md" >}}) - [Create Grafana managed alerting rules]({{< relref "alerting-rules/create-grafana-managed-rule.md" >}}) - [Create Grafana Mimir or Loki managed alerting rules]({{< relref "alerting-rules/create-mimir-loki-managed-rule.md" >}}) - [View existing alerting rules and manage their current state]({{< relref "alerting-rules/rule-list.md" >}}) diff --git a/docs/sources/alerting/fundamentals/_index.md b/docs/sources/alerting/fundamentals/_index.md index 8826764c5ca..a21778eb7a5 100644 --- a/docs/sources/alerting/fundamentals/_index.md +++ b/docs/sources/alerting/fundamentals/_index.md @@ -8,6 +8,7 @@ weight = 110 This section includes the following fundamental concepts of Grafana alerting: +- [Alert rules]({{< relref "./alert-rules/_index.md" >}}) - [Annotations and labels for alerting rules]({{< relref "./annotation-label/_index.md" >}}) - [Alertmanager]({{< relref "./alertmanager.md" >}}) - [State and health of alerting rules]({{< relref "./state-and-health.md" >}}) diff --git a/docs/sources/alerting/fundamentals/alert-rules/_index.md b/docs/sources/alerting/fundamentals/alert-rules/_index.md new file mode 100644 index 00000000000..8ca7ad6c983 --- /dev/null +++ b/docs/sources/alerting/fundamentals/alert-rules/_index.md @@ -0,0 +1,19 @@ ++++ +title = "Alert rules" +description = "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 "../annotation-label/_index.md" >}}) diff --git a/docs/sources/alerting/fundamentals/alert-rules/alert-instances.md b/docs/sources/alerting/fundamentals/alert-rules/alert-instances.md new file mode 100644 index 00000000000..485c0170b0f --- /dev/null +++ b/docs/sources/alerting/fundamentals/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" >}} diff --git a/docs/sources/alerting/fundamentals/alert-rules/alert-rule-types.md b/docs/sources/alerting/fundamentals/alert-rules/alert-rule-types.md new file mode 100644 index 00000000000..18b9553f0f8 --- /dev/null +++ b/docs/sources/alerting/fundamentals/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. diff --git a/docs/sources/alerting/fundamentals/alert-rules/organising-alerts.md b/docs/sources/alerting/fundamentals/alert-rules/organising-alerts.md new file mode 100644 index 00000000000..6a6a0cc50fe --- /dev/null +++ b/docs/sources/alerting/fundamentals/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. diff --git a/docs/sources/alerting/migrating-alerts/opt-out.md b/docs/sources/alerting/migrating-alerts/opt-out.md new file mode 100644 index 00000000000..b7756b6b1ff --- /dev/null +++ b/docs/sources/alerting/migrating-alerts/opt-out.md @@ -0,0 +1,40 @@ ++++ +aliases = ["/docs/grafana/latest/alerting/opt-in/", "/docs/grafana/latest/alerting/unified-alerting/opt-in/"] +description = "Disable Grafana alerts" +title = "Opt-out of Grafana alerting" +weight = 113 ++++ + +# Opt-out to Grafana alerting in OSS + +This topic discusses how to disable Grafana alerting and migrate to legacy dashboard alerting. It also provides guidance on how to enable Grafana alerting once you are ready to migrate to Grafana alerting. + +> **Note:** This topic is only relevant for OSS and Enterprise customers. Contact customer support to enable or disable Grafana alerting for your Grafana Cloud stack. + +## Before you begin + +We recommend that you backup Grafana's database. If you are using PostgreSQL as the backend database, then the minimum required version is 9.5. + +## Opt-out of Grafana alerts + +To opt-out of Grafana alerts and roll back to legacy dashboard alerting: + +1. In your custom configuration file ($WORKING_DIR/conf/custom.ini), go to the [Grafana alerting]({{< relref "../../administration/configuration.md#unified_alerting" >}}) section. +1. Set the `enabled` property to `false`. +1. For [legacy dashboard alerting]({{< relref "../../administration/configuration.md#alerting" >}}), set the `enabled` flag to `true`. +1. Restart Grafana for the configuration changes to take effect. + +> **Note:** Rolling back from Grafana to legacy alerting can result in data loss. This is applicable to the fresh installation as well as upgraded setups. + +## Opt-in to Grafana alerting + +When you are ready to make the switch, the following procedure will help you migrate to Grafana alerting. + +To opt-in to Grafana alerts: + +1. In your custom configuration file ($WORKING_DIR/conf/custom.ini), go to the [unified alerts]({{< relref "../../administration/configuration.md#unified_alerting" >}}) section. +1. Set the `enabled` property to `true`. +1. Next, for [legacy dashboard alerting]({{< relref "../../administration/configuration.md#alerting" >}}), set the `enabled` flag to `false`. +1. Restart Grafana for the configuration changes to take effect. + +> **Note:** The `ngalert` toggle previously used to enable or disable Grafana alerting is no longer available.