From b53f68ea5e7c545fad84b1188b061f8ec633377b Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Wed, 14 May 2025 10:00:30 +0200 Subject: [PATCH] docs(alerting): Correct gotcha when using dynamic labels (#105347) --- .../alerting/alerting-rules/templates/_index.md | 12 +++++++++++- .../alerting/alerting-rules/templates/examples.md | 12 +++++++++++- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/sources/alerting/alerting-rules/templates/_index.md b/docs/sources/alerting/alerting-rules/templates/_index.md index d068b4a3390..5c81428b337 100644 --- a/docs/sources/alerting/alerting-rules/templates/_index.md +++ b/docs/sources/alerting/alerting-rules/templates/_index.md @@ -18,6 +18,11 @@ labels: title: Template annotations and labels weight: 500 refs: + shared-stale-alert-instances: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/fundamentals/alert-rule-evaluation/state-and-health/#stale-alert-instances-missingseries + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/alert-rule-evaluation/state-and-health/#stale-alert-instances-missingseries reference-labels: - pattern: /docs/grafana/ destination: /docs/grafana//alerting/alerting-rules/templates/reference/#labels @@ -190,7 +195,12 @@ low In this example, the value of the `severity` label is determined by the query value, and the possible options are `critical`, `high`, `medium`, or `low`. You can then use the `severity` label to change their notifications—for instance, sending `critical` alerts immediately or routing `low` alerts to a specific team for further review. -{{< docs/shared lookup="alerts/note-dynamic-labels.md" source="grafana" version="" >}} +> **Note:** An alert instance is uniquely identified by its set of labels. +> +> - Avoid displaying query values in labels, as this can create numerous alert instances—one for each distinct label set. Instead, use annotations for query values. +> - If a templated label's value changes, it maps to a different alert instance, and the previous instance is considered [stale (MissingSeries)](ref:shared-stale-alert-instances) when its label value is no longer present. + +[//]: <> ({{< docs/shared lookup="alerts/note-dynamic-labels.md" source="grafana" version="" >}}) ### How to template a label diff --git a/docs/sources/alerting/alerting-rules/templates/examples.md b/docs/sources/alerting/alerting-rules/templates/examples.md index e9ee1a8015b..093390423b7 100644 --- a/docs/sources/alerting/alerting-rules/templates/examples.md +++ b/docs/sources/alerting/alerting-rules/templates/examples.md @@ -16,6 +16,11 @@ title: Labels and annotations template examples menuTitle: Examples weight: 102 refs: + shared-stale-alert-instances: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/fundamentals/alert-rule-evaluation/state-and-health/#stale-alert-instances-missingseries + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/alert-rule-evaluation/state-and-health/#stale-alert-instances-missingseries labels: - pattern: /docs/grafana/ destination: /docs/grafana//alerting/fundamentals/alert-rules/annotation-label/#labels @@ -209,7 +214,12 @@ In this example, the `severity` label is determined by the query value: You can then use the `severity` label to control how alerts are handled. For instance, you could send `critical` alerts immediately, while routing `low` severity alerts to a team for further investigation. -{{< docs/shared lookup="alerts/note-dynamic-labels.md" source="grafana" version="" >}} +> **Note:** An alert instance is uniquely identified by its set of labels. +> +> - Avoid displaying query values in labels, as this can create numerous alert instances—one for each distinct label set. Instead, use annotations for query values. +> - If a templated label's value changes, it maps to a different alert instance, and the previous instance is considered [stale (MissingSeries)](ref:shared-stale-alert-instances) when its label value is no longer present. + +[//]: <> ({{< docs/shared lookup="alerts/note-dynamic-labels.md" source="grafana" version="" >}}) ### Based on query label