public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Consolidate Templating labels and annotations docs into a single page (#59685)

Browse Source
This commit is contained in:
George Robinson
2022-12-02 09:40:48 +00:00
committed by GitHub
parent 2ac235eaff
commit 4073d044c1
3 changed files with 185 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/alerting/fundamentals/annotation-label/example-template-functions.md
-125
View File
@@ -1,125 +0,0 @@
---
aliases:
- /docs/grafana/latest/alerting/contact-points/message-templating/example-template-functions/
- /docs/grafana/latest/alerting/fundamentals/annotation-label/example-template-functions/
keywords:
- grafana
- alerting
- guide
- contact point
- templating
title: Examples of template functions
weight: 130
---
# Examples of template functions
## humanize
**Template string** `{ humanize $value }`
**Input** `1234567.0`
**Expected** `1.235M`
## humanize1024
**TemplateString** `{ humanize1024 $value } `
**Input** `1048576.0`
**Expected** `1Mi`
## humanizeDuration
**TemplateString** `{ humanizeDuration $value }`
**Input** `899.99`
**Expected** `14m 59s`
### humanizePercentage
**TemplateString** `{ humanizePercentage $value }`
**Input** `0.1234567`
**Expected** `12.35%`
## humanizeTimestamp
**TemplateString** `{ $value | humanizeTimestamp }`
**Input** `1435065584.128`
**Expected** `2015-06-23 13:19:44.128 +0000 UTC`
## title
**TemplateString** `{ $value | title }`
**Input** `aa bb CC`
**Expected** `Aa Bb Cc`
### toUpper
**TemplateString** `{ $value | toUpper }`
**Input** `aa bb CC`
**Expected** `AA BB CC`
### toLower
**TemplateString** `{ $value | toLower }`
**Input** `aA bB CC`
**Expected** `aa bb cc`
## match
**TemplateString** `{ match "a+" $labels.instance }`
**Input** `aa`
**Expected** `true`
## reReplaceAll
**TemplateString** `{{ reReplaceAll "localhost:(.*)" "my.domain:$1" $labels.instance }}`
**Input** `localhost:3000`
**Expected** `my.domain:3000`
### graphLink
**TemplateString** `{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}`
**Expected** `/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}]`
### tableLink
**TemplateString** `{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}`
**Expected** `/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]`
## args
**TemplateString** `{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}`
**Expected** `1 2`
## externalURL
**TemplateString** `{ externalURL }`
**Expected** `http://localhost/path/prefix`
## pathPrefix
**TemplateString** `{ pathPrefix }`
**Expected** `/path/prefix`
docs/sources/alerting/fundamentals/annotation-label/template-functions.md
-150
View File
@@ -1,150 +0,0 @@
---
aliases:
- /docs/grafana/latest/alerting/contact-points/message-templating/template-functions/
- /docs/grafana/latest/alerting/message-templating/template-functions/
- /docs/grafana/latest/alerting/unified-alerting/message-templating/template-functions/
- /docs/grafana/latest/alerting/fundamentals/annotation-label/template-functions/
- /docs/grafana/latest/alerting/unified-alerting/fundamentals/annotation-label/template-functions/
keywords:
- grafana
- alerting
- guide
- contact point
- templating
title: Template functions
weight: 125
---
# Template Functions
Template functions allow you to process alert evaluation results to generate dynamic notifications.
| Name | Argument type | Return type | Description |
| ----------------------------------------- | ------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [humanize](#humanize) | number or string | string | Converts a number to a more readable format, using metric prefixes. |
| [humanize1024](#humanize1024) | number or string | string | Like humanize, but uses 1024 as the base rather than 1000. |
| [humanizeDuration](#humanizeduration) | number or string | string | Converts a duration in seconds to a more readable format. |
| [humanizePercentage](#humanizepercentage) | number or string | string | Converts a ratio value to a fraction of 100. |
| [humanizeTimestamp](#humanizetimestamp) | number or string | string | Converts a Unix timestamp in seconds to a more readable format. |
| [title](#title) | string | string | strings.Title, capitalises first character of each word. |
| [toUpper](#toupper) | string | string | strings.ToUpper, converts all characters to upper case. |
| [toLower](#tolower) | string | string | strings.ToLower, converts all characters to lower case. |
| [match](#match) | pattern, text | boolean | regexp.MatchString Tests for a unanchored regexp match. |
| [reReplaceAll](#rereplaceall) | pattern, replacement, text | string | Regexp.ReplaceAllString Regexp substitution, unanchored. |
| [graphLink](#graphlink) | string - JSON Object with `"expr"` and `"datasource"` fields | string | Returns the path to graphical view in [Explore](https://grafana.com/docs/grafana/latest/explore/) for the given expression and data source. |
| [tableLink](#tablelink) | string- JSON Object with `"expr"` and `"datasource"` fields | string | Returns the path to tabular view in [Explore](https://grafana.com/docs/grafana/latest/explore/) for the given expression and data source. |
| [args](#args) | []interface{} | map[string]interface{} | Converts a list of objects to a map with keys, for example, arg0, arg1. Use this function to pass multiple arguments to templates. |
| [externalURL](#externalurl) | nothing | string | Returns a string representing the external URL. |
| [pathPrefix](#pathprefix) | nothing | string | Returns the path of the external URL. |
## Examples
### humanize
**Template string** `{ humanize $value }`
**Input** `1234567.0`
**Expected** `1.235M`
### humanize1024
**TemplateString** `{ humanize1024 $value } `
**Input** `1048576.0`
**Expected** `1Mi`
### humanizeDuration
**TemplateString** `{ humanizeDuration $value }`
**Input** `899.99`
**Expected** `14m 59s`
### humanizePercentage
**TemplateString** `{ humanizePercentage $value }`
**Input** `0.1234567`
**Expected** `12.35%`
### humanizeTimestamp
**TemplateString** `{ $value | humanizeTimestamp }`
**Input** `1435065584.128`
**Expected** `2015-06-23 13:19:44.128 +0000 UTC`
### title
**TemplateString** `{ $value | title }`
**Input** `aa bb CC`
**Expected** `Aa Bb Cc`
### toUpper
**TemplateString** `{ $value | toUpper }`
**Input** `aa bb CC`
**Expected** `AA BB CC`
### toLower
**TemplateString** `{ $value | toLower }`
**Input** `aA bB CC`
**Expected** `aa bb cc`
### match
**TemplateString** `{ match "a+" $labels.instance }`
**Input** `aa`
**Expected** `true`
### reReplaceAll
**TemplateString** `{{ reReplaceAll "localhost:(.*)" "my.domain:$1" $labels.instance }}`
**Input** `localhost:3000`
**Expected** `my.domain:3000`
### graphLink
**TemplateString** `{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}`
**Expected** `/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}]`
### tableLink
**TemplateString** `{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}`
**Expected** `/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]`
### args
**TemplateString** `{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}`
**Expected** `1 2`
### externalURL
**TemplateString** `{ externalURL }`
**Expected** `http://localhost/path/prefix`
### pathPrefix
**TemplateString** `{ pathPrefix }`
**Expected** `/path/prefix`
docs/sources/alerting/fundamentals/annotation-label/variables-label-annotation.md
+185 -35
View File
@@ -13,74 +13,106 @@ weight: 117
# Templating labels and annotations
In Grafana it is possible to template labels and annotations just like you would in Prometheus. Those who have used Prometheus before should be familiar with the `$labels` variable which holds the label key/value pairs of the alert instance and the `$value` variable which holds the evaluated value of the alert instance.
In Grafana it is possible to template labels and annotations just like in Prometheus. Those who have used Prometheus before should be familiar with `$labels` and `$value` as these variables contain the labels and value of the alert. You can use the same variables in Grafana to template labels and annotations, even if the alert does not use a Prometheus datasource.
In Grafana it is possible to use the same variables from Prometheus to template labels and annotations, even if your alert does not use a Prometheus datasource.
For example, let's suppose we want to create an alert in Grafana that tells us when one of our instances is down for more than 5 minutes. Like in Prometheus, we can add a summary annotation to show the instance which is down:
For example, suppose you want to create an alert rule in Grafana that fires when one of your instances is down for more than 5 minutes, and that each alert fired should have a summary annotation to tell you which instance is down:
```
Instance {{ $labels.instance }} has been down for more than 5 minutes
```
For alerts where we also want to know the value of the condition at the time the alert fired, we can use both the
`$labels` and the `$value` variable to add even more informative summaries:
## Labels with dots
If the label contains a dot (full stop or period) in its name then the following will not work:
```
{{ $labels.instance }} has a 95th percentile request latency above 1s: {{ $value }})
Instance {{ $labels.instance.name }} has been down for more than 5 minutes
```
One difference between Grafana and Prometheus is that Grafana uses `$value` to hold both the labels and the value
of the condition at the time the alert fired. For example:
This is because it is attempting to use a non-existing field `name` in `$labels.instance` rather than `instance.name` in `$labels`. Instead use the `index` function to print `instance.name`:
```
[ var='B' labels={instance=http_server} value=10 ]
Instance {{ index $labels "instance.name" }} has been down for more than 5 minutes
```
## Alert rules with two or more queries or expressions
## Use values in labels and annotations
In the case where an alert rule has two or more queries, or uses reduce and math expressions, it is possible to template the reduced result of each query and expression with the `$values` variable. This variable holds the labels and value of each reduced query, and the results of any math expressions. However, it does not hold the samples for each query.
Grafana supports `$value` when templating labels and annotations. However, while `$value` in Prometheus is a floating point number contains the value of the expression, `$value` in Grafana is a string containing the labels and values of all Threshold, Reduce and Maths expressions. It does not contain the value of queries as a single query can return anywhere from 1 to 10,000s of rows or metrics.
For example, suppose you have the following alert rule:
This `$value` variable is called the Value String. If you were to use it in the template of a summary annotation:
```
{{ $labels.instance }} has an average 95th percentile request latency above 1s: {{ $value }})
```
you will get the following summary:
```
http_server has an average 95th percentile request latency above 1s: [ var='B' labels={instance=http_server} value=10 ]
```
To get just the value of `B` you can instead use `$values`:
```
{{ $labels.instance }} has an average 95th percentile request latency above 1s: {{ $values.B }}
```
and then you will get this summary:
```
http_server has an average 95th percentile request latency above 1s: 11
```
## Alert rules with multiple queries, or expressions
If you have an alert rule with multiple queries and expressions, or a single query with a Reduce and Math expression, like in the following example:
{{< figure src="/static/img/docs/alerting/unified/grafana-alerting-histogram-quantile.png" class="docs-image--no-shadow" caption="An alert rule that uses histogram_quantile to compute 95th percentile" >}}
Should this rule create an alert instance `$values` will hold the result of the reduce expression `B` and the math expression `C`. It will not hold the results returned by query `A` because query `A` does not return a single value but rather a series of values over time.
Then the Value String will not just include the value of the alert condition, but the labels and values of all Threshold, Reduce and Maths expressions.
If we were to write a summary annotation such as:
**Example 1**: The Value String of an alert rule with a single query and Reduce expression `B`:
```
{{ $labels.instance }} has a 95th percentile request latency above 1s: {{ $value }})
[ var='B' labels={instance=http_server} value=11 ]
```
We would find that because the condition of the alert, the math expression `C` must be a boolean comparison, it must return either a `0` or a `1`. What we want instead is the 95th percentile from the reduce expression `B`:
**Example 2**: The Value String of an alert rule with a single query, Reduce expression `B` and a Math expression `C`:
```
{{ $labels.instance }} has a 95th percentile request latency above 1s: {{ $values.B }})
[ var='B' labels={instance=http_server} value=11, var='C' labels={instance=http_server} value=1 ]
```
We can also show the labels of `B`, however since this alert rule has just one query the labels of `B` are equivalent to `$labels`:
If you were to write a summary annotation such as:
```
{{ $values.B.Labels.instance }} has a 95th percentile request latency above 1s: {{ $values.B }})
{{ $labels.instance }} has an average 95th percentile request latency above 1s: {{ $values.C }})
```
### No data and execution errors or timeouts
You would find that because the condition of the alert `C` is a Math expression with a boolean comparison, it must return either a `0` or a `1`. What you want instead is the average of the 95th percentile, and you can get this from the reduce expression `B`:
```
{{ $labels.instance }} has an average 95th percentile request latency above 1s: {{ $values.B }})
```
## No data and execution errors or timeouts
Should query `A` return no data then the reduce expression `B` will also return no data. This means that
`{{ $values.B }}` will be nil. To ensure that labels and annotations can still be templated even when a query returns no data, we can use an if statement to check for `$values.B`:
`{{ $values.B }}` will be nil. To ensure that labels and annotations can still be templated even when a query returns no data, we can use an if statement to check for this condition:
```
{{ if $values.B }}{{ $labels.instance }} has a 95th percentile request latency above 1s: {{ $values.B }}){{ end }}
```
## Classic conditions
## Classic Conditions
If the rule uses a classic condition instead of a reduce and math expression, then `$values` contains the combination of the `refID` and position of the condition. For example, `{{ $values.A0 }}` and `{{ $values.A1 }}`.
If the rule uses Classic Conditions instead of Reduce and Math expressions, then `$values` contains the combination of the Ref ID and position of the condition. For example, `{{ $values.A0 }}` and `{{ $values.A1 }}`.
## Variables
## Reference
The following template variables are available when expanding labels and annotations.
### Variables
The following template variables are available when expanding labels and annotations:
| Name | Description |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -88,16 +120,134 @@ The following template variables are available when expanding labels and annotat
| $values | The values of all reduce and math expressions that were evaluated for this alert rule. For example, `{{ $values.A }}`, `{{ $values.A.Labels }}` and `{{ $values.A.Value }}` where `A` is the `refID` of the reduce or math expression. If the rule uses a classic condition instead of a reduce and math expression, then `$values` contains the combination of the `refID` and position of the condition. |
| $value | The value string of the alert instance. For example, `[ var='A' labels={instance=foo} value=10 ]`. |
### Labels with dots
### Functions
If a label contains a dot (full stop or period) in its name then the following will not work:
The following functions are also available when expanding labels and annotations:
```
Instance {{ $labels.instance.name }} has been down for more than 5 minutes
```
| Name | Argument type | Return type | Description |
| ----------------------------------------- | ------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [humanize](#humanize) | number or string | string | Converts a number to a more readable format, using metric prefixes. |
| [humanize1024](#humanize1024) | number or string | string | Like humanize, but uses 1024 as the base rather than 1000. |
| [humanizeDuration](#humanizeduration) | number or string | string | Converts a duration in seconds to a more readable format. |
| [humanizePercentage](#humanizepercentage) | number or string | string | Converts a ratio value to a fraction of 100. |
| [humanizeTimestamp](#humanizetimestamp) | number or string | string | Converts a Unix timestamp in seconds to a more readable format. |
| [title](#title) | string | string | strings.Title, capitalises first character of each word. |
| [toUpper](#toupper) | string | string | strings.ToUpper, converts all characters to upper case. |
| [toLower](#tolower) | string | string | strings.ToLower, converts all characters to lower case. |
| [match](#match) | pattern, text | boolean | regexp.MatchString Tests for a unanchored regexp match. |
| [reReplaceAll](#rereplaceall) | pattern, replacement, text | string | Regexp.ReplaceAllString Regexp substitution, unanchored. |
| [graphLink](#graphlink) | string - JSON Object with `"expr"` and `"datasource"` fields | string | Returns the path to graphical view in [Explore](https://grafana.com/docs/grafana/latest/explore/) for the given expression and data source. |
| [tableLink](#tablelink) | string- JSON Object with `"expr"` and `"datasource"` fields | string | Returns the path to tabular view in [Explore](https://grafana.com/docs/grafana/latest/explore/) for the given expression and data source. |
| [args](#args) | []interface{} | map[string]interface{} | Converts a list of objects to a map with keys, for example, arg0, arg1. Use this function to pass multiple arguments to templates. |
| [externalURL](#externalurl) | nothing | string | Returns a string representing the external URL. |
| [pathPrefix](#pathprefix) | nothing | string | Returns the path of the external URL. |
This is because we are printing a non-existing field `name` in `$labels.instance` rather than `instance.name` in `$labels`. Instead we can use the `index` function to print `instance.name`:
#### humanize
```
Instance {{ index $labels "instance.name" }} has been down for more than 5 minutes
```
**Template string** `{ humanize $value }`
**Input** `1234567.0`
**Expected** `1.235M`
#### humanize1024
**TemplateString** `{ humanize1024 $value } `
**Input** `1048576.0`
**Expected** `1Mi`
#### humanizeDuration
**TemplateString** `{ humanizeDuration $value }`
**Input** `899.99`
**Expected** `14m 59s`
#### humanizePercentage
**TemplateString** `{ humanizePercentage $value }`
**Input** `0.1234567`
**Expected** `12.35%`
#### humanizeTimestamp
**TemplateString** `{ $value | humanizeTimestamp }`
**Input** `1435065584.128`
**Expected** `2015-06-23 13:19:44.128 +0000 UTC`
#### title
**TemplateString** `{ $value | title }`
**Input** `aa bb CC`
**Expected** `Aa Bb Cc`
#### toUpper
**TemplateString** `{ $value | toUpper }`
**Input** `aa bb CC`
**Expected** `AA BB CC`
#### toLower
**TemplateString** `{ $value | toLower }`
**Input** `aA bB CC`
**Expected** `aa bb cc`
#### match
**TemplateString** `{ match "a+" $labels.instance }`
**Input** `aa`
**Expected** `true`
#### reReplaceAll
**TemplateString** `{{ reReplaceAll "localhost:(.*)" "my.domain:$1" $labels.instance }}`
**Input** `localhost:3000`
**Expected** `my.domain:3000`
#### graphLink
**TemplateString** `{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}`
**Expected** `/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}]`
#### tableLink
**TemplateString** `{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}`
**Expected** `/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]`
#### args
**TemplateString** `{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}`
**Expected** `1 2`
#### externalURL
**TemplateString** `{ externalURL }`
**Expected** `http://localhost/path/prefix`
#### pathPrefix
**TemplateString** `{ pathPrefix }`
**Expected** `/path/prefix`