AlertsGrafana 8 AlertsCreate and manage rulesAnnotations and labels for alerting rules

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

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.

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.

Alert details

Template variables

The following template variables are available when expanding annotations and labels.

NameDescription
$labelsThe labels from the query or condition. For example, {{ $labels.instance }} and {{ $labels.job }}. This is unavailable when the rule uses a classic condition.
$valuesThe 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
$valueThe 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.

NameArgumentReturnDescription
humanizenumber or stringstringConverts a number to a more readable format, using metric prefixes.
humanize1024number or stringstringLike humanize, but uses 1024 as the base rather than 1000.
humanizeDurationnumber or stringstringConverts a duration in seconds to a more readable format.
humanizePercentagenumber or stringstringConverts a ratio value to a fraction of 100.
humanizeTimestampnumber or stringstringConverts a Unix timestamp in seconds to a more readable format.
titlestringstringstrings.Title, capitalises first character of each word.
toUpperstringstringstrings.ToUpper, converts all characters to upper case.
toLowerstringstringstrings.ToLower, converts all characters to lower case.
matchpattern, textbooleanregexp.MatchString Tests for a unanchored regexp match.
reReplaceAllpattern, replacement, textstringRegexp.ReplaceAllString Regexp substitution, unanchored.
graphLinkexprstringNot supported
tableLinkexprstringNot supported
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.
externalURLnothingstringReturns a string representing the external URL.
pathPrefixnothingstringReturns the path of the external URL.
tmplstring, []interface{}nothingNot supported
safeHtmlstringstringNot supported
queryquery string[]sampleNot supported
first[]samplesampleNot supported
labellabel, samplestringNot supported
strvalue[]samplestringNot supported
valuesamplefloat64Not supported
sortByLabellabel, []samples[]sampleNot supported