From b8c43bcf3d74204f8d2519744ec08cd24a459249 Mon Sep 17 00:00:00 2001 From: "grafana-delivery-bot[bot]" <132647405+grafana-delivery-bot[bot]@users.noreply.github.com> Date: Wed, 23 Oct 2024 09:07:06 +0200 Subject: [PATCH] [v11.3.x] Alerting docs: Update `Labels and Annotations` to detail use cases (#95221) Alerting docs: Update `Labels and Annotations` to detail use cases (#95213) * Alerting docs: Update `Labels and Annotations` to detail use cases * Update docs/sources/alerting/fundamentals/alert-rules/annotation-label.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> --------- Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> (cherry picked from commit 8072286daf6a0ea227d9cfbd19f921c945495184) Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> --- .../alert-rules/annotation-label.md | 36 +++++++++++++------ 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/docs/sources/alerting/fundamentals/alert-rules/annotation-label.md b/docs/sources/alerting/fundamentals/alert-rules/annotation-label.md index 270b45d563c..50a8e74a82d 100644 --- a/docs/sources/alerting/fundamentals/alert-rules/annotation-label.md +++ b/docs/sources/alerting/fundamentals/alert-rules/annotation-label.md @@ -28,9 +28,9 @@ refs: destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals#alert-instances create-alerts-from-panel: - pattern: /docs/grafana/ - destination: /docs/grafana//alerting/alerting-rules/create-grafana-managed-rule#create-alerts-from-panels + destination: /docs/grafana//alerting/alerting-rules/create-alerts-panels/ - pattern: /docs/grafana-cloud/ - destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/create-grafana-managed-rule#create-alerts-from-panels + destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/create-alerts-panels/ templates: - pattern: /docs/grafana/ destination: /docs/grafana//alerting/fundamentals/notifications/templates/ @@ -57,8 +57,8 @@ refs: Labels and annotations add additional information about an alert using key/value pairs: -- [Labels](#labels) are used to differentiate an alert from all other alerts. -- [Annotations](#annotations) are used to provide extra detail on an existing alert. +- [Labels](#labels) are used to differentiate an alert from all other alerts and decide how to manage them. +- [Annotations](#annotations) provide extra details for alert responders to help them understand and address potential issues. ## Labels @@ -83,9 +83,9 @@ An alert's label set can contain three types of labels: **User-configured labels** -Labels that you manually configure in the alert rule to identify the generated alert instances or group them. +Labels that you manually configure in the alert rule to identify the generated alert instances and manage the alerts. Common custom labels, depending on the use case, are: `severity`, `priority`, `team`, and `service`. -You can also use a [template](ref:templates) to customize the label value and generate dynamic values when the rule is evaluated. +Additionally, you can use a [template](ref:templates) to customize the label value and generate dynamic values from query data. **Data source query labels** @@ -100,7 +100,7 @@ Reserved labels are automatically added by Grafana: - `alert_name`: the name of the alert rule. - `grafana_folder`: the title of the folder containing the alert. -Labels prefixed with `grafana_` are reserved by Grafana for special use. To stop Grafana Alerting from adding a reserved label, you can disable it via the `disabled_labels` option in [unified_alerting.reserved_labels](/docs/grafana//setup-grafana/configure-grafana#unified_alertingreserved_labels) configuration. +Labels prefixed with `grafana_` are reserved by Grafana for special use. You can disable reserved labels via the [`unified_alerting.reserved_labels`](/docs/grafana//setup-grafana/configure-grafana#unified_alertingreserved_labels) option. {{}} @@ -132,13 +132,29 @@ If multiple label keys are sanitized to the same value, the duplicates have a sh ## Annotations -The purpose of annotations is to add additional information to alert instances, such as extra details for notification messages. +Annotations add additional information to alert instances, helping responders identify and address potential issues. -Grafana provides several optional annotations that you can edit for use in notification messages and within Grafana. +Annotations are displayed in Grafana and are included by default in notifications. Grafana provides several optional annotations that you can edit: - `summary`: A short summary of what the alert has detected and why. - `description`: A detailed description of what happened and what the alert does. - `runbook_url`: The runbook page to guide operators managing a potential incident. - `dashboardUId` and `panelId`: Link the alert to a dashboard and panel. These are automatically set when [creating an alert from panels](ref:create-alerts-from-panel). -Like labels, annotations can use a [template](ref:templates) to customize the label value and generate dynamic values when the rule is evaluated. +For example, you can edit the annotation `summary` to explain why the alert was triggered: + +``` +CPU usage has exceeded 80% for the last 5 minutes. +``` + +And edit the `description` annotation to provide more context and how to respond: + +``` +The web server's CPU has exceeded 80% for more than 5 minutes. + +This indicates that the system is under heavy load and may result in an outage. + +Consider scaling the server's resources and investigating bottlenecks. +``` + +Like labels, annotations can use a [template](ref:templates) to include dynamic data from queries.