mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Rework template docs and add examples (#43178)
This commit is contained in:
David Parrott
GitHub
@@ -7,54 +7,32 @@ weight = 401
|
||||
|
||||
# Annotations and labels for alerting rules
|
||||
|
||||
Annotations and labels help customize alert messages so that you can quickly identify the service or application that needs attention.
|
||||
Annotations and labels are key value pairs associated with alerts originating from the alerting rule, datasource response, and as a result of alerting rule evaluation. They can be used in alert notifications directly or in [templates]({{< relref "../message-templating/" >}}) and [template functions]({{< relref "../message-templating/template-functions" >}}) to create notification contact dynamically.
|
||||
|
||||
## Annotations
|
||||
|
||||
Annotations are key-value pairs that provide additional meta-information about an alert. For example: a description, a summary, and runbook URL. These are displayed in rule and alert details in the UI and can be used in contact type message templates. Annotations can also be templated, for example `Instance {{ $labels.instance }} down` will have the evaluated `instance` label value added for every alert this rule produces.
|
||||
Annotations are key-value pairs that provide additional meta-information about an alert. For example: a description, a summary, and runbook URL. These are displayed in rule and alert details in the UI and can be used in contact point message templates.
|
||||
|
||||
## Labels
|
||||
|
||||
Labels are key-value pairs that categorize or identify an alert. Labels are used to match alerts in silences or match and groups alerts in notification policies. Labels are also shown in rule or alert details in the UI and can be used in contact type message templates. For example, you can add a `severity` label, then configure a separate notification policy for each severity. You can also add, for example, a `team` label and configure notification policies specific to the team or silence all alerts for a particular team. Labels can also be templated like annotations, for example, `{{ $labels.namespace }}/{{ $labels.job }}` will produce a new rule label that will have the evaluated `namespace` and `job` label value added for every alert this rule produces. The rule labels take precedence over the labels produced by the query/condition.
|
||||
Labels are key-value pairs that contain information about, and are used to uniquely identify an alert. The label set for an alert is generated and added to throughout the alerting evaluation and notification process.
|
||||
|
||||
### How are labels used?
|
||||
|
||||
- The complete set of labels for an alert is what uniquely identifies an alert within Grafana Alerts.
|
||||
- The Alertmanager uses labels to match alerts for [silences]({{< relref "../silences/" >}}) and [alert groups]({{< relref "../alert-groups/" >}}) in [notification policies]({{< relref "../notification-policies/" >}}).
|
||||
- The alerting UI displays labels for every alert instance generated by the evaluation of that rule.
|
||||
- Contact points can access labels to dynamically generate notifications that contain information specific to the alert that is resulting in a notification.
|
||||
- Labels can be added to an [alerting rule]({{< relref "../alerting-rules/" >}}). These manually configured labels are able to use template functions and reference other labels. Labels added to an alerting rule here take precedence in the event of a collision between labels.
|
||||
|
||||
{{< figure src="/static/img/docs/alerting/unified/rule-edit-details-8-0.png" max-width="550px" caption="Alert details" >}}
|
||||
|
||||
#### Template variables
|
||||
#### Variables available to alerting rule labels and annotations
|
||||
|
||||
The following template variables are available when expanding annotations and labels.
|
||||
|
||||
| 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. |
|
||||
| $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 expression. This is unavailable when the rule uses a [classic condition]({{< relref "./create-grafana-managed-rule/#single-and-multi-dimensional-rule" >}}) |
|
||||
| $value | The value string of the alert instance. For example, `[ var='A' labels={instance=foo} value=10 ]`. |
|
||||
|
||||
#### Template functions
|
||||
|
||||
The following template functions are available when expanding annotations and labels.
|
||||
|
||||
| Name | Argument | Return | Description |
|
||||
| ------------------ | ------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| humanize | number or string | string | Converts a number to a more readable format, using metric prefixes. |
|
||||
| humanize1024 | number or string | string | Like humanize, but uses 1024 as the base rather than 1000. |
|
||||
| humanizeDuration | number or string | string | Converts a duration in seconds to a more readable format. |
|
||||
| humanizePercentage | number or string | string | Converts a ratio value to a fraction of 100. |
|
||||
| humanizeTimestamp | number or string | string | Converts a Unix timestamp in seconds to a more readable format. |
|
||||
| title | string | string | strings.Title, capitalises first character of each word. |
|
||||
| toUpper | string | string | strings.ToUpper, converts all characters to upper case. |
|
||||
| toLower | string | string | strings.ToLower, converts all characters to lower case. |
|
||||
| match | pattern, text | boolean | regexp.MatchString Tests for a unanchored regexp match. |
|
||||
| reReplaceAll | pattern, replacement, text | string | Regexp.ReplaceAllString Regexp substitution, unanchored. |
|
||||
| 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 | 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 | []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 | nothing | string | Returns a string representing the external URL. |
|
||||
| pathPrefix | nothing | string | Returns the path of the external URL. |
|
||||
| tmpl | string, []interface{} | nothing | Not supported |
|
||||
| safeHtml | string | string | Not supported |
|
||||
| query | query string | []sample | Not supported |
|
||||
| first | []sample | sample | Not supported |
|
||||
| label | label, sample | string | Not supported |
|
||||
| strvalue | []sample | string | Not supported |
|
||||
| value | sample | float64 | Not supported |
|
||||
| sortByLabel | label, []samples | []sample | Not supported |
|
||||
| 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 "./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 expression. This is unavailable when the rule uses a classic condition |
|
||||
| $value | The value string of the alert instance. For example, `[ var='A' labels={instance=foo} value=10 ]`. |
|
||||
|
||||
@@ -59,17 +59,3 @@ In addition to direct access of data (labels and annotations) stored as KeyValue
|
||||
| Remove | []string | KeyValue | Returns a copy of the Key/Value map without the given keys. |
|
||||
| Names | | []string | List of label names |
|
||||
| Values | | []string | List of label values |
|
||||
|
||||
## Functions
|
||||
|
||||
Some functions to transform values are also available, along with [default functions provided by Go templating](https://golang.org/pkg/text/template/#hdr-Functions).
|
||||
|
||||
| Name | Arguments | Returns |
|
||||
| ------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| title | string | Capitalizes first character of each word. |
|
||||
| toUpper | string | Converts all characters to upper case. |
|
||||
| match | pattern, string | Match a string using RegExp. |
|
||||
| reReplaceAll | pattern, replacement, string | RegExp substitution, unanchored. |
|
||||
| join | string, []string | Concatenates the elements of the second argument to create a single string. First argument is the separator. |
|
||||
| safeHtml | string | Marks string as HTML, not requiring auto-escaping. |
|
||||
| stringSlice | ...string | Returns passed strings as slice of strings. |
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
+++
|
||||
title = "Template functions"
|
||||
keywords = ["grafana", "alerting", "guide", "contact point", "templating"]
|
||||
+++
|
||||
|
||||
# Template Functions
|
||||
|
||||
Template functions allow you to process labels and annotations 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`
|
||||
Reference in New Issue
Block a user