mirror of
https://github.com/grafana/grafana.git
synced 2025-08-01 11:32:36 +08:00
c1c48dd610
* Use relative aliases for all non-current Grafana aliases
Prevents non-latest documentation "stealing" the page away from latest
and through permanent redirects for latest pages that no longer exist.
The redirected pages are indexed by search engines but our robots.txt
forbids them crawling the non-latest page.
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Remove aliases from shared pages
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Rewrite all current latest aliases to be next
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Fix typo in latest alias
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Remove all current page aliases
find docs/sources -type f -name '*.md' -exec sed -z -i 's#\n *- /docs/grafana/next/[^\n]*\n#\n#' {} \;
find docs/sources -type f -name '*.md' -exec sed -Ez -i 's#\n((aliases:\n *-)|aliases:\n)#\n\2#' {} \;
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Prettier
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
252 lines
13 KiB
Markdown
252 lines
13 KiB
Markdown
---
|
|
description: Learn about templating of labels and annotations
|
|
keywords:
|
|
- grafana
|
|
- alerting
|
|
- guide
|
|
- fundamentals
|
|
title: Templating labels and annotations
|
|
weight: 117
|
|
---
|
|
|
|
# Templating labels and annotations
|
|
|
|
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.
|
|
|
|
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
|
|
```
|
|
|
|
## Labels with dots
|
|
|
|
If the label contains a dot (full stop or period) in its name then the following will not work:
|
|
|
|
```
|
|
Instance {{ $labels.instance.name }} has been down for more than 5 minutes
|
|
```
|
|
|
|
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`:
|
|
|
|
```
|
|
Instance {{ index $labels "instance.name" }} has been down for more than 5 minutes
|
|
```
|
|
|
|
## Use values in labels and annotations
|
|
|
|
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.
|
|
|
|
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" >}}
|
|
|
|
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.
|
|
|
|
**Example 1**: The Value String of an alert rule with a single query and Reduce expression `B`:
|
|
|
|
```
|
|
[ var='B' labels={instance=http_server} value=11 ]
|
|
```
|
|
|
|
**Example 2**: The Value String of an alert rule with a single query, Reduce expression `B` and a Math expression `C`:
|
|
|
|
```
|
|
[ var='B' labels={instance=http_server} value=11, var='C' labels={instance=http_server} value=1 ]
|
|
```
|
|
|
|
If you were to write a summary annotation such as:
|
|
|
|
```
|
|
{{ $labels.instance }} has an average 95th percentile request latency above 1s: {{ $values.C }})
|
|
```
|
|
|
|
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 this condition:
|
|
|
|
```
|
|
{{ if $values.B }}{{ $labels.instance }} has a 95th percentile request latency above 1s: {{ $values.B }}){{ end }}
|
|
```
|
|
|
|
## Classic Conditions
|
|
|
|
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 }}`.
|
|
|
|
## Reference
|
|
|
|
### Variables
|
|
|
|
The following template variables are available when expanding labels and annotations:
|
|
|
|
| Name | Description |
|
|
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| $labels | The labels from the query or condition. For example, `{{ $labels.instance }}` and `{{ $labels.job }}`. This is unavailable when the rule uses a [classic condition]({{< relref "../../alerting-rules/create-grafana-managed-rule/#single-and-multi-dimensional-rule" >}}). |
|
|
| $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 ]`. |
|
|
|
|
### Functions
|
|
|
|
The following functions are also available when expanding labels and annotations:
|
|
|
|
| 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. |
|
|
|
|
#### 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`
|