From cb70f995a4f934b3cdae4439600fea414fc58151 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Wed, 16 Oct 2024 10:06:14 +0200 Subject: [PATCH] Use `.` notation instead of `index` in examples --- .../alerting-rules/templates/_index.md | 10 ++++++++-- .../alerting-rules/templates/examples.md | 6 ------ .../alerting-rules/templates/reference.md | 19 ++++++++++++------- .../alerting/fundamentals/templates.md | 2 +- 4 files changed, 21 insertions(+), 16 deletions(-) diff --git a/docs/sources/alerting/alerting-rules/templates/_index.md b/docs/sources/alerting/alerting-rules/templates/_index.md index 3874e0183f3..3dd2bb6f0f7 100644 --- a/docs/sources/alerting/alerting-rules/templates/_index.md +++ b/docs/sources/alerting/alerting-rules/templates/_index.md @@ -119,11 +119,17 @@ However, if you want to display dynamic query values in annotations, you need to For instance, you can template the previous example to display the specific instance and CPU value that triggered the alert: +``` +CPU usage for {{ $labels.instance }} has exceeded 80% ({{ $values.A.Value }}) for the last 5 minutes. +``` + +Alternatively, you can use the `index` function to print query values: + ``` CPU usage for {{ index $labels "instance" }} has exceeded 80% ({{ index $values "A" }}) for the last 5 minutes. ``` -The result of this annotation would now be: +The result of the annotation would now be: ``` CPU usage for Instance 1 has exceeded 80% (81.2345) for the last 5 minutes. @@ -180,7 +186,7 @@ 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. {{% admonition type="note" %}} -You should avoid displaying query values in labels, as this may create numerous unique alert instances when only one instance is necessary. Instead, use annotations to inform about query values. +You should avoid displaying query values in labels, as this may create numerous unique alert instances—one for each distinct label value. Instead, use annotations to inform about query values. {{% /admonition %}} ### 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 1be51d78ce9..2992f040b0b 100644 --- a/docs/sources/alerting/alerting-rules/templates/examples.md +++ b/docs/sources/alerting/alerting-rules/templates/examples.md @@ -121,12 +121,6 @@ To provide additional context, you can include labels from the query. For instan CPU usage for {{ $labels.instance }} has exceeded 80% ({{ $values.A.Value }}) for the last 5 minutes. ``` -Alternatively, you can use the `index()` function: - -``` -CPU usage for {{ index $labels "instance" }} has exceeded 80% ({{ index $values "A" }}) for the last 5 minutes. -``` - ```template_output CPU usage for Instance 1 has exceeded 80% (81.2345) for the last 5 minutes. ``` diff --git a/docs/sources/alerting/alerting-rules/templates/reference.md b/docs/sources/alerting/alerting-rules/templates/reference.md index 80efc7b5d2a..f33a8632cb3 100644 --- a/docs/sources/alerting/alerting-rules/templates/reference.md +++ b/docs/sources/alerting/alerting-rules/templates/reference.md @@ -21,12 +21,17 @@ refs: destination: /docs/grafana//alerting/configure-notifications/template-notifications/reference/ - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/template-notifications/reference/ - template-language: + language: - pattern: /docs/grafana/ destination: /docs/grafana//alerting/alerting-rules/templates/language/ - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/templates/language/ - template-language-functions: + language-functions: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/alerting-rules/templates/language/#functions + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/templates/language/#functions + language-index: - pattern: /docs/grafana/ destination: /docs/grafana//alerting/alerting-rules/templates/language/#functions - pattern: /docs/grafana-cloud/ @@ -61,7 +66,7 @@ The `$` and `.` symbols are used to reference variables and their properties. Yo {{ $values.A.Value }} ``` -Templates are based on the **Go templating system**. Refer to [Template language](ref:template-language) for additional information. +Templates are based on the **Go templating system**. Refer to [Template language](ref:language) for additional information. The following variables are available when templating annotations and labels: @@ -80,7 +85,7 @@ The `$labels` variable contains all labels from the query. For example, suppose you have a query that returns CPU usage for all of your servers, and you have an alert rule that fires when any of your servers have exceeded 80% CPU usage for the last 5 minutes. You want to add a summary annotation to the alert that tells you which server is experiencing high CPU usage. With the `$labels` variable you can write a template that prints a human-readable sentence such as: ``` -CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes +CPU usage for {{ $labels.instance }} has exceeded 80% for the last 5 minutes ``` The outcome of this template would be: @@ -105,7 +110,7 @@ Each Ref IDs, such as `$values.A`, has the following properties Here's the previous example printing now the value of the instant query with Ref ID `A`: ``` -{{ $values.A.Value }} CPU usage for {{ index $labels "instance" }} over the last 5 minutes. +{{ $values.A.Value }} CPU usage for {{ $labels.instance }} over the last 5 minutes. ``` If the alert has the label `instance=server1` and the query returns `81.2345`, the template would print: @@ -117,7 +122,7 @@ If the alert has the label `instance=server1` and the query returns `81.2345`, t If the query in Ref ID `A` is a range query rather than an instant query then add a reduce expression with Ref ID `B` and replace `$values.A.Value` with `$values.B.Value`: ``` -{{ $values.B.Value }} CPU usage for {{ index $labels "instance" }} over the last 5 minutes. +{{ $values.B.Value }} CPU usage for {{ $labels.instance }} over the last 5 minutes. ``` Alternatively, you can use the `index()` function to retrieve the query value: @@ -148,7 +153,7 @@ Instead, we recommend using [$values](#values), which contains the same informat Functions can perform actions in templates such as transforming or formatting data. -Note that the [functions provided by Go's template language](ref:template-language-functions), such as `index`, `and`, `printf`, and `len`, are available, along with many others. +Note that the [functions provided by Go's template language](ref:language-functions), such as `index`, `and`, `printf`, and `len`, are available, along with many others. In addition, the following functions are also available for templating annotations and labels: diff --git a/docs/sources/alerting/fundamentals/templates.md b/docs/sources/alerting/fundamentals/templates.md index feced1a3e25..5eda3f5cdb0 100644 --- a/docs/sources/alerting/fundamentals/templates.md +++ b/docs/sources/alerting/fundamentals/templates.md @@ -98,7 +98,7 @@ Annotations can contain plain text, but you should template annotations if you n Here’s an example of templating an annotation, which explains where and why the alert was triggered. In this case, the alert triggers when CPU usage exceeds a threshold, and the `summary` annotation provides the relevant details. ``` -CPU usage for {{ index $labels "instance" }} has exceeded 80% ({{ index $values "A" }}) for the last 5 minutes. +CPU usage for {{ $labels.instance }} has exceeded 80% ({{ $values.A.Value }}) for the last 5 minutes. ``` The outcome of this template would be: