From 646b8409240df543cc912db7ff3295c98b9c4769 Mon Sep 17 00:00:00 2001 From: "grafana-delivery-bot[bot]" <132647405+grafana-delivery-bot[bot]@users.noreply.github.com> Date: Wed, 28 Jun 2023 04:11:04 -0500 Subject: [PATCH] [v10.0.x] Docs: adds evaluation doc (#70797) Docs: adds evaluation doc (#70757) * Docs: adds evaluation doc * Adds note on classic condition * fixes link * fixes link * fixes link * fixes data source * link fix * fixes rbac link * adds aliases (cherry picked from commit 5159317ee7e5c059a6896809527c93abe9d48b0d) Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> --- .../index.md | 2 +- .../manage-contact-points/_index.md | 1 + .../configure-integrations.md | 2 + .../manage-contact-points/webhook-notifier.md | 1 + .../queries-conditions/_index.md | 8 ++- .../alert-rules/rule-evaluation/_index.md | 64 +++++++++++++++++++ .../alerting/fundamentals/alertmanager.md | 1 + .../notification-policies/notifications.md | 1 + .../declare-incident-from-alert.md | 2 + .../alerting/set-up/meta-monitoring/_index.md | 1 + .../set-up/migrating-alerts/_index.md | 1 + .../legacy-alerting-deprecation.md | 2 + .../legacy-alerting/_index.md | 1 + .../set-up/performance-limitations/index.md | 1 + 14 files changed, 85 insertions(+), 3 deletions(-) rename docs/sources/alerting/fundamentals/{ => alert-rules}/queries-conditions/_index.md (95%) create mode 100644 docs/sources/alerting/fundamentals/alert-rules/rule-evaluation/_index.md diff --git a/docs/sources/administration/roles-and-permissions/access-control/rbac-fixed-basic-role-definitions/index.md b/docs/sources/administration/roles-and-permissions/access-control/rbac-fixed-basic-role-definitions/index.md index 4ab8bd0c97b..d67539879ac 100644 --- a/docs/sources/administration/roles-and-permissions/access-control/rbac-fixed-basic-role-definitions/index.md +++ b/docs/sources/administration/roles-and-permissions/access-control/rbac-fixed-basic-role-definitions/index.md @@ -97,7 +97,7 @@ The following tables list permissions associated with basic and fixed roles. ### Alerting roles -If alerting is [enabled]({{< relref "../../../../alerting/migrating-alerts/opt-out/" >}}), you can use predefined roles to manage user access to alert rules, alert instances, and alert notification settings and create custom roles to limit user access to alert rules in a folder. +If alerting is [enabled]({{< relref "../../../../alerting/set-up/migrating-alerts/opt-out/" >}}), you can use predefined roles to manage user access to alert rules, alert instances, and alert notification settings and create custom roles to limit user access to alert rules in a folder. Access to Grafana alert rules is an intersection of many permissions: diff --git a/docs/sources/alerting/alerting-rules/manage-contact-points/_index.md b/docs/sources/alerting/alerting-rules/manage-contact-points/_index.md index 631045ae504..adf5669f456 100644 --- a/docs/sources/alerting/alerting-rules/manage-contact-points/_index.md +++ b/docs/sources/alerting/alerting-rules/manage-contact-points/_index.md @@ -5,6 +5,7 @@ aliases: - ../../contact-points/edit-contact-point/ - ../../contact-points/test-contact-point/ - ../create-contact-point/ + - alerting/manage-notifications/manage-contact-points/ description: How to manage your contact points keywords: - grafana diff --git a/docs/sources/alerting/alerting-rules/manage-contact-points/configure-integrations.md b/docs/sources/alerting/alerting-rules/manage-contact-points/configure-integrations.md index 8c28bfda42e..b89757d6ebf 100644 --- a/docs/sources/alerting/alerting-rules/manage-contact-points/configure-integrations.md +++ b/docs/sources/alerting/alerting-rules/manage-contact-points/configure-integrations.md @@ -1,4 +1,6 @@ --- +aliases: + - alerting/manage-notifications/manage-contact-points/configure-integrations/ description: Configure integrations keywords: - Grafana diff --git a/docs/sources/alerting/alerting-rules/manage-contact-points/webhook-notifier.md b/docs/sources/alerting/alerting-rules/manage-contact-points/webhook-notifier.md index ba16d6689dc..9ce3cd43eac 100644 --- a/docs/sources/alerting/alerting-rules/manage-contact-points/webhook-notifier.md +++ b/docs/sources/alerting/alerting-rules/manage-contact-points/webhook-notifier.md @@ -2,6 +2,7 @@ aliases: - ../contact-points/notifiers/webhook-notifier/ - ../fundamentals/contact-points/webhook-notifier/ + - alerting/manage-notifications/manage-contact-points/webhook-notifier/ description: Configure the webhook notifier for notifications keywords: - grafana diff --git a/docs/sources/alerting/fundamentals/queries-conditions/_index.md b/docs/sources/alerting/fundamentals/alert-rules/queries-conditions/_index.md similarity index 95% rename from docs/sources/alerting/fundamentals/queries-conditions/_index.md rename to docs/sources/alerting/fundamentals/alert-rules/queries-conditions/_index.md index 6e3af579927..4a1aef158b4 100644 --- a/docs/sources/alerting/fundamentals/queries-conditions/_index.md +++ b/docs/sources/alerting/fundamentals/alert-rules/queries-conditions/_index.md @@ -13,7 +13,7 @@ keywords: In Grafana, queries play a vital role in fetching and transforming data from supported data sources, which include databases like MySQL and PostgreSQL, time series databases like Prometheus, InfluxDB and Graphite, and services like Elasticsearch, AWS CloudWatch, Azure Monitor and Google Cloud Monitoring. -For more information on supported data sources, see [Data sources]({{< relref "../data-source-alerting.md" >}}). +For more information on supported data sources, see [Data sources]({{< relref "../../data-source-alerting.md" >}}). The process of executing a query involves defining the data source, specifying the desired data to retrieve, and applying relevant filters or transformations. Query languages or syntaxes specific to the chosen data source are utilized for constructing these queries. @@ -21,7 +21,7 @@ In Alerting, you define a query to get the data you want to measure and a condit An alert rule consists of one or more queries and expressions that select the data you want to measure. -For more information on queries and expressions, see [Query and transform data]({{< relref "../../../panels-visualizations/query-transform-data" >}}). +For more information on queries and expressions, see [Query and transform data]({{< relref "../../../../panels-visualizations/query-transform-data" >}}). ## Data source queries @@ -55,6 +55,10 @@ In Alerting, you can only use expressions for Grafana-managed alert rules. For e You can also use classic condition, which creates an alert rule that triggers a single alert when its condition is met. As a result, Grafana sends only a single alert even when alert conditions are met for multiple series. +**Note:** + +Classic conditions exist mainly for compatibility reasons and should be avoided if possible. + **Reduce** Aggregates time series values in the selected time range into a single value. diff --git a/docs/sources/alerting/fundamentals/alert-rules/rule-evaluation/_index.md b/docs/sources/alerting/fundamentals/alert-rules/rule-evaluation/_index.md new file mode 100644 index 00000000000..472eb935cf7 --- /dev/null +++ b/docs/sources/alerting/fundamentals/alert-rules/rule-evaluation/_index.md @@ -0,0 +1,64 @@ +--- +title: Alert rule evaluation +description: Introduction to alert rule evaluation +weight: 106 +keywords: + - grafana + - alerting + - evaluation +--- + +# Alert rule evaluation + +Use alert rule evaluation to determine how frequently an alert rule should be evaluated and how quickly it should change its state. + +To do this, you need to make sure that your alert rule is in the right evaluation group and set a pending period time that works best for your use case. + +## Evaluation group + +Every alert rule is part of an evaluation group. Each evaluation group contains an evaluation interval that determines how frequently the alert rule is checked. Alert rules within the same group are evaluated one after the other, while alert rules in different groups can be evaluated simultaneously. + +This feature is especially useful for Prometheus/Mimir rules when you want to ensure that recording rules are evaluated before any alert rules. + +**Note:** + +Evaluation groups and alerts grouping in notification policies are two separate things. Grouping in notification policies allows multiple alerts sharing the same labels to be sent in the same time message. + +## Pending period + +By setting a pending period, you can avoid unnecessary alerts for temporary problems. + +In the pending period, you select the period in which an alert rule can be in breach of the condition until it fires. + +**Example** + +Imagine you have an alert rule evaluation interval set at every 30 seconds and the pending period to 90 seconds. + +Evaluation will occur as follows: + +[00:30] First evaluation - condition not met. + +[01:00] Second evaluation - condition breached. +Pending counter starts. **Alert stars pending.** + +[01:30] Third evaluation - condition breached. Pending counter = 30s. **Pending state.** + +[02:00] Fourth evaluation - condition breached. Pending counter = 60s **Pending state.** + +[02:30] Fifth evaluation - condition breached. Pending counter = 90s. **Alert starts firing** + +If the alert rule has a condition that needs to be in breach for a certain amount of time before it takes action, then its state changes as follows: + +- When the condition is first breached, the rule goes into a "pending" state. + +- The rule stays in the "pending" state until the condition has been broken for the required amount of time - pending period. + +- Once the required time has passed, the rule goes into a "firing" state. + +- If the condition is no longer broken during the pending period, the rule goes back to its normal state. + +**Note:** + +If you want to skip the pending state, you can simply set the pending period to 0. This effectively skips the pending period and your alert rule will start firing as soon as the condition is breached. + +When an alert rule fires, alert instances are produced, which are then sent to the Alertmanager. diff --git a/docs/sources/alerting/fundamentals/alertmanager.md b/docs/sources/alerting/fundamentals/alertmanager.md index 2e9af1735b4..51a751753b5 100644 --- a/docs/sources/alerting/fundamentals/alertmanager.md +++ b/docs/sources/alerting/fundamentals/alertmanager.md @@ -3,6 +3,7 @@ aliases: - ../fundamentals/alertmanager/ - ../metrics/ - ../unified-alerting/fundamentals/alertmanager/ + - alerting/manage-notifications/alertmanager/ description: Intro to the different Alertmanagers title: Alertmanager weight: 103 diff --git a/docs/sources/alerting/fundamentals/notification-policies/notifications.md b/docs/sources/alerting/fundamentals/notification-policies/notifications.md index ec3e9adbd61..3c8ad3d13d2 100644 --- a/docs/sources/alerting/fundamentals/notification-policies/notifications.md +++ b/docs/sources/alerting/fundamentals/notification-policies/notifications.md @@ -1,6 +1,7 @@ --- aliases: - ../notifications/ + - alerting/manage-notifications/create-notification-policy/ description: Notification policies keywords: - grafana diff --git a/docs/sources/alerting/manage-notifications/declare-incident-from-alert.md b/docs/sources/alerting/manage-notifications/declare-incident-from-alert.md index 8d82ee80522..de4272ae75c 100644 --- a/docs/sources/alerting/manage-notifications/declare-incident-from-alert.md +++ b/docs/sources/alerting/manage-notifications/declare-incident-from-alert.md @@ -1,4 +1,6 @@ --- +aliases: + - alerting/alerting-rules/declare-incident-from-alert/ description: Declare an incident from a firing alert keywords: - grafana diff --git a/docs/sources/alerting/set-up/meta-monitoring/_index.md b/docs/sources/alerting/set-up/meta-monitoring/_index.md index ca51ff466b4..467266dc320 100644 --- a/docs/sources/alerting/set-up/meta-monitoring/_index.md +++ b/docs/sources/alerting/set-up/meta-monitoring/_index.md @@ -1,6 +1,7 @@ --- aliases: - meta-monitoring/ + - alerting/meta-monitoring/ description: Meta monitoring keywords: - grafana diff --git a/docs/sources/alerting/set-up/migrating-alerts/_index.md b/docs/sources/alerting/set-up/migrating-alerts/_index.md index 8556e933abe..abfeefd5537 100644 --- a/docs/sources/alerting/set-up/migrating-alerts/_index.md +++ b/docs/sources/alerting/set-up/migrating-alerts/_index.md @@ -3,6 +3,7 @@ aliases: - difference-old-new/ - unified-alerting/ - unified-alerting/difference-old-new/ + - alerting/migrating-alerts/ description: Upgrade Grafana alerts title: Upgrade Alerting weight: 150 diff --git a/docs/sources/alerting/set-up/migrating-alerts/legacy-alerting-deprecation.md b/docs/sources/alerting/set-up/migrating-alerts/legacy-alerting-deprecation.md index c27f3964a08..db115a6a027 100644 --- a/docs/sources/alerting/set-up/migrating-alerts/legacy-alerting-deprecation.md +++ b/docs/sources/alerting/set-up/migrating-alerts/legacy-alerting-deprecation.md @@ -1,5 +1,7 @@ --- title: Legacy alerting deprecation +aliases: + - alerting/legacy-alerting-deprecation/ description: Legacy alerting deprecation notice weight: 109 keywords: diff --git a/docs/sources/alerting/set-up/migrating-alerts/legacy-alerting/_index.md b/docs/sources/alerting/set-up/migrating-alerts/legacy-alerting/_index.md index 59f9d2400f8..6a47699d0b1 100644 --- a/docs/sources/alerting/set-up/migrating-alerts/legacy-alerting/_index.md +++ b/docs/sources/alerting/set-up/migrating-alerts/legacy-alerting/_index.md @@ -3,6 +3,7 @@ aliases: - /docs/grafana-cloud/alerts/ - /docs/grafana-cloud/how-do-i/alerts/ - /docs/grafana-cloud/legacy-alerting/ + - alerting/migrating-alerts/legacy-alerting/ description: Legacy alerting title: Legacy alerting weight: 110 diff --git a/docs/sources/alerting/set-up/performance-limitations/index.md b/docs/sources/alerting/set-up/performance-limitations/index.md index d73cdce545c..2675380e3f6 100644 --- a/docs/sources/alerting/set-up/performance-limitations/index.md +++ b/docs/sources/alerting/set-up/performance-limitations/index.md @@ -1,6 +1,7 @@ --- aliases: - alerting-limitations/ + - alerting/performance-limitations/ description: Performance considerations and limitations keywords: - grafana