Template annotations and labels on Grafana Labs

Annotation and label template reference

Fri, 03 Apr 2026 19:43:06 +0000

Annotation and label template reference

Annotations and labels in alert rules can be defined using plain text. However, you can also define templates to customize their values with dynamic data from alert rule queries.

For example, you can template the summary annotation to include information from query values, providing relevant alert context for responders. Refer to Template annotations and labels for various use cases.

In templates, variables represent dynamic values from queries, while functions perform actions to transform or format this data.

Variables

Variables represent dynamic values from alert rule queries that can be displayed or accessed in your templates.

The $ and . symbols are used to reference variables and their properties. You can reference variables directly in your alert rule definitions using the $ symbol followed by the variable name. Similarly, you can access properties of variables using the dot (.) notation in alert rule templates.

{{ $values.A.Value }}

Templates are based on the Go templating system. Refer to Template language for additional information.

The following variables are available when templating annotations and labels:

Variables	Description
$labels	Contains all labels from the query, only query labels.
$values	Contains the labels and floating point values of all instant queries and expressions, indexed by their Ref IDs.
$value	A string containing the labels and values of all instant queries; threshold, reduce and math expressions, and classic conditions in the alert rule. When a single data source is used, it returns the value of the query. It is generally recommended to use $values.

$labels

The $labels variable contains all labels from the query. It excludes user-configured and reserved labels, containing only query labels.

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 {{ $labels.instance }} has exceeded 80% for the last 5 minutes

The outcome of this template would be:

CPU usage for server1 has exceeded 80% for the last 5 minutes

If you are using a classic condition then $labels will not contain any labels from the query. Classic conditions discard these labels in order to enforce uni-dimensional behavior (at most one alert per alert rule). If you want to use labels from the query in your template then use the example here.

$values

The $values variable is a table containing the labels and floating point values of all instant queries and expressions, indexed by their Ref IDs (e.g, A, B, C, etc.). It does not contain the results of range queries, as they can return hundreds or thousands of rows.

Each Ref IDs, such as $values.A, has the following properties

Property	Type	Description
`Value`	Float	The value returned by the instant query or expression.
`Labels`	Key/value pairs	The labels associated with the instance query or expression.

Here’s the previous example printing now the value of the instant query with Ref ID A:

{{ $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:

81.2345 CPU usage for instance1 over the last 5 minutes.

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 {{ $labels.instance }} over the last 5 minutes.

Alternatively, you can use the index() function to retrieve the query value:

{{ index $values "B" }} CPU usage for {{ index $labels "instance" }} over the last 5 minutes.

Note
Variable names that start with a number (for example, 1B) are not valid identifiers in Go templates.

To access a value or label whose key starts with a number, use the index function:
{{ index $values "1B" }} CPU usage for {{ index $labels "1instance" }} over the last 5 minutes.
Using {{ $values.1B.Value }} is invalid and causes the template code to render as plain text.

$value

The $value variable is a string containing the labels and values of all instant queries; threshold, reduce and math expressions, and classic conditions in the alert rule.

When a single data source is used in the alert rule, $value will return the query value directly.

This example prints the $value variable:

{{ $value }}: CPU usage has exceeded 80% for the last 5 minutes.

When using multiple data sources, it would display something like this:

[ var='A' labels={instance=instance1} value=81.234, , [ var='B' labels={instance=instance2} value=1 ] ]: CPU usage has exceeded 80% for the last 5 minutes.

But with a single data source, it would display just the value of the query:

81.234: CPU usage has exceeded 80% for the last 5 minutes.

Instead, we recommend using $values, which contains the same information as $value but is structured in an easier-to-use table format.

Functions

Functions can perform actions in templates such as transforming or formatting data.

Note that the functions provided by Go’s template language, 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:

Numbers

Name	Arguments	Returns	Description
humanize	number or string	string	Humanizes decimal numbers.
humanize1024	number or string	string	Like `humanize`, but but uses 1024 as the base rather than 1000.
humanizeDuration	number or string	string	Humanizes a duration in seconds.
humanizePercentage	number or string	string	Humanizes a ratio value to a percentage.
humanizeTimestamp	number or string	string	Humanizes a Unix timestamp.
toTime	number or string	time	Converts a Unix timestamp in seconds to time.

Strings

Name	Arguments	Returns	Description
title	string	string	Capitalizes the first character of each word.
toUpper	string	string	Returns all text in uppercase.
toLower	string	string	Returns all text in lowercase.
stripPort	string	string	Returns only host.
match	pattern, text	boolean	Matches the text against a regular expression pattern.
reReplaceAll	pattern, replacement, text	string	Replaces text matching the regular expression.
graphLink	expr	string	Returns the path to the graphical view in `Explore` for the given expression and data source.
tableLink	expr	string	Returns the path to the tabular view in `Explore` for the given expression and data source.
parseDuration	string	float	Parses a duration string such as “1h” into the number of seconds it represents.
stripDomain	string	string	Returns the result of removing the domain part of a FQDN.

Others

Name	Arguments	Returns	Description
args	[]interface{}	map[string]interface{}	Translates a list of objects to a map with keys arg0, arg1 etc.
safeHtml	string	string	Marks string as HTML not requiring auto-escaping.
externalURL	none	string	Returns the external URL of the Grafana server as configured in the ini file(s).
pathPrefix	none	string	Returns the path of the Grafana server as configured in the ini file(s).

For further context on these functions, note that templating in Grafana is based on the Prometheus template implementation, enabling the use of these functions and Prometheus-like templates for formatting alert messages within Grafana.

humanize

The humanize function humanizes decimal numbers:

{{ humanize 1000.0 }}

1k

humanize1024

The humanize1024 works similar to humanize but but uses 1024 as the base rather than 1000:

{{ humanize1024 1024.0 }}

1ki

humanizeDuration

The humanizeDuration function humanizes a duration in seconds:

{{ humanizeDuration 60.0 }}

1m 0s

humanizePercentage

The humanizePercentage function humanizes a ratio value between 0 and 1 to a percentage:

{{ humanizePercentage 0.2 }}

20%

humanizeTimestamp

The humanizeTimestamp function humanizes a Unix timestamp:

{{ humanizeTimestamp 1577836800.0 }}

2020-01-01 00:00:00 +0000 UTC

toTime

The toTime function converts a Unix timestamp in seconds to time.:

{{ toTime 1727802106 }}

2024-10-01 17:01:46 +0000 UTC

title

The title function capitalizes the first character of each word:

{{ title "hello, world!" }}

Hello, World!

toUpper

The toUpper function returns all text in uppercase:

{{ toUpper "Hello, world!" }}

HELLO, WORLD!

toLower

The toLower function returns all text in lowercase:

{{ toLower "Hello, world!" }}

hello, world!

stripPort

The stripPort splits string into host and port, then returns only host:

{{ stripPort "example.com:8080" }}

example.com

match

The match function matches the text against a regular expression pattern:

{{ match "a.*" "abc" }}

true

reReplaceAll

The reReplaceAll function replaces text matching the regular expression:

{{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }}

example.com:8080

graphLink

The graphLink function returns the path to the graphical view in Explore for the given expression and data source:

{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}

/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}]

parseDuration

The parseDuration function parses a duration string such as “1h” into the number of seconds it represents.

{{ parseDuration "1h" }}

stripDomain

The stripDomain removes the domain part of a FQDN, leaving port untouched:

{{ stripDomain "example.com:8080" }}

example:8080

tableLink

The tableLink function returns the path to the tabular view in Explore for the given expression and data source:

{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}

/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]

args

The args function translates a list of objects to a map with keys arg0, arg1 etc. This is intended to allow multiple arguments to be passed to templates:

{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}

1 2

safeHtml

The safeHtml function marks string as HTML not requiring auto-escaping:

{{ safeHtml "<b>Text</b>"}}

<b>Text</b>

externalURL

The externalURL function returns the external URL of the Grafana server as configured in the ini file(s):

{{ externalURL }}

https://example.com/grafana

pathPrefix

The pathPrefix function returns the path of the Grafana server as configured in the ini file(s):

{{ pathPrefix }}

/grafana

Differences with notification templates

Both notification templates and alert rule templates use the Go templating system. However, the functions and variables available in notification templates differ from those used in annotations and labels templates, which are described in this documentation.

Annotation and label templates operate in the context of an individual alert instance, while notification templates apply to a notification that includes a group of alert(s).

For example, notification templates provide the .Alerts variable, which includes the list of all firing and resolved alerts in the notification. This variable is not available in alert rule templates, which operate within the context of a single alert instance.

Additionally, you cannot reuse templates for labels and annotations as you can with notification templates. Instead, you need to write each template inline within the label or annotation fields and manually copy them wherever you want to reuse the templates.

Labels and annotations template examples

Fri, 03 Apr 2026 19:43:06 +0000

Labels and annotations template examples

Templating allows you to add dynamic data from queries to alert labels and annotations. Dynamic data enhances alert context, making it easier for responders to quickly assess and address the issue.

This page provides common examples for templating labels and annotations. For more information on templating, refer to:

Annotation example

Annotations add extra details to alert instances and are often used to provide helpful information for identifying the issue and guiding the response.

A common use case for annotations is to display the specific query value or threshold that triggered the alert.

For example, you can display the query value from the $values variable to inform about the CPU value that triggered the alert.

CPU usage has exceeded 80% ({{ $values.A.value }}) for the last 5 minutes.

Alternatively, you can use the index() function to retrieve the query value as follows.

CPU usage has exceeded 80% ({{ index $values "A" }}) for the last 5 minutes.

CPU usage has exceeded 80% (81.2345) for the last 5 minutes.

Include labels for extra details

To provide additional context, you can include labels from the query using the $labels variable.

For instance, the previous case could also include the affected instance.

CPU usage for {{ $labels.instance }} has exceeded 80% ({{ $values.A.Value }}) for the last 5 minutes.

CPU usage for Instance 1 has exceeded 80% (81.2345) for the last 5 minutes.

You can incorporate any labels returned by the query into the template. For instance, the following template includes information about the environment and region where the alert occurred.

Alert triggered in {{ $labels.environment }} on {{ $labels.region }} region.

Alert triggered in production on AMER region.

Print a range query

To print the value of an instant query you can print its Ref ID using the index function or the $values variable:

{{ $values.A.Value }}

For range queries, reduce them from a time series to an instant vector using a reduce expression. You can then print the result by referencing its Ref ID. For example, if the reduce expression averages A with the Ref ID B, you would then print $values.B:

{{ $values.B.Value }}

Humanize the value of a query

To print the humanized value of an instant query, use the humanize function:

{{ humanize $values.A.Value }}

Alternatively:

{{ humanize (index $values "A").Value }}

554.9

To print the value of an instant query as a percentage, use the humanizePercentage function:

{{ humanizePercentage $values.A.Value }}

10%

For additional functions to display or format data, refer to:

Label example

Labels determine how alerts are routed and managed, ensuring that notifications reach the right teams at the right time. If the labels returned by your queries don’t fully capture the necessary context, you can create a new label and sets its value based on query data.

Based on query value

Here’s an example of creating a severity label based on a query value:

{{- if (gt $values.A.Value 90.0) -}}critical
{{- else if (gt $values.A.Value 80.0) -}}high
{{- else if (gt $values.A.Value 60.0) -}}medium
{{- else -}}low
{{- end -}}

In this example, the severity label is determined by the query value:

critical for values above 90,
high for values above 80,
medium for values above 60,
and low for anything below.

You can then use the severity label to control how alerts are handled. For instance, you could send critical alerts immediately, while routing low severity alerts to a team for further investigation.

Note: An alert instance is uniquely identified by its set of labels.

Avoid displaying query values in labels, as this can create numerous alert instances—one for each distinct label set. Instead, use annotations for query values.

If a templated label’s value changes, it maps to a different alert instance, and the previous instance is considered stale. Learn all the details in this example using dynamic labels.

Based on query label

You can use labels to differentiate alerts coming from various environments (e.g., production, staging, dev). For example, you may want to add a label that sets the environment based on the instance’s label. Here’s how you can template it:

{{- if eq $labels.instance "prod-server-1" -}}
production
{{- else if eq $labels.instance "staging-server-1" -}}
staging
{{- else -}}
development
{{- end -}}

This would print:

For instance prod-server-1, the label would be production.
For staging-server-1, the label would be staging.
All other instances would be labeled development.

To make this template more flexible, you can use a regular expression that matches the instance name with the instance name prefix using the match() function:

{{- if match "^prod-server-.*" $labels.instance -}}
production
{{- else if match "^staging-server-.*" $labels.instance -}}
staging
{{- else -}}
development
{{- end -}}

Legacy Alerting templates

For users working with Grafana’s legacy alerting system, templates can still be utilized to extract useful information from alert conditions. However, it’s important to note that you cannot use $labels to print labels from the query if you are using classic conditions, and must use $values instead. The reason for this is classic conditions discard these labels to enforce uni-dimensional behavior (at most one alert per alert rule). If classic conditions didn’t discard these labels, then queries that returned many time series would cause alerts to flap between firing and resolved constantly as the labels would change every time the alert rule was evaluated.

Instead, the $values variable contains the reduced values of all time series for all conditions that are firing. For example, if you have an alert rule with a query A that returns two time series, and a classic condition B with two conditions, then $values would contain B0, B1, B2 and B3. If the classic condition B had just one condition, then $values would contain just B0 and B1.

Print all labels from a classic condition

To print all labels of all firing time series use the following template (make sure to replace B in the regular expression with the Ref ID of the classic condition if it’s different):

{{ range $k, $v := $values -}}
{{ if (match "B[0-9]+" $k) -}}
{{ $k }}: {{ $v.Labels }}{{ end }}
{{ end }}

For example, a classic condition for two time series exceeding a single condition would print:

B0: instance=server1
B1: instance=server2

If the classic condition has two or more conditions, and a time series exceeds multiple conditions at the same time, then its labels will be duplicated for each condition that is exceeded:

B0: instance=server1
B1: instance=server2
B2: instance=server1
B3: instance=server2

If you need to print unique labels you should consider changing your alert rules from uni-dimensional to multi-dimensional instead. You can do this by replacing your classic condition with reduce and math expressions.

Print all values from a classic condition

To print all values from a classic condition take the previous example and replace $v.Labels with $v.Value:

{{ range $k, $v := $values -}}
{{ if (match "B[0-9]+" $k) -}}
{{ $k }}: {{ $v.Value }}{{ end }}
{{ end }}

For example, a classic condition for two time series exceeding a single condition would print:

B0: 81.2345
B1: 84.5678

If the classic condition has two or more conditions, and a time series exceeds multiple conditions at the same time, then $values will contain the values of all conditions:

B0: 81.2345
B1: 92.3456
B2: 84.5678
B3: 95.6789

Alerting template language

Fri, 03 Apr 2026 19:43:06 +0000

Alerting template language

Notification templates and alert rule templates, such as annotations and labels, both use the Go template language, text/template.

Both types of templates can use the same keywords, functions, and comparison operators of the Go template language, such as range, if, and, index, eq, and more.

However, it’s important to note that because notifications and alert rules operate in distinct contexts, some additional variables and functions are only available for either notification or alert rule templates. Refer to:

This documentation provides an overview of the functions and operators of the Go template language that are available for both notification and alert rule templates.

Print

To print the value of something, use {{ and }}. You can print the value of a variable, a field of a variable, the result of a function, or the value of dot.

{{ $values }}
{{ $values.A.Value }}
{{ humanize 1000.0 }}
{{ .Alerts }}

Dot

In text/template, there is a special cursor called dot, written as .. You can think of this cursor as a variable whose value changes depending on where in the template it is used.

At the start of notification templates, dot (.) refers to Notification Data.

{{ .Alerts }}

In annotation and label templates, dot (.) is initialized with all alert data. It’s recommended to use the $labels and $values variables instead to directly access the alert labels and query values.

Note
Dot (.) might refer to something else when used in a range, a with, or when writing templates used in other templates.

If

You can use if statements in templates. For example, you can print Variable empty when a variable is empty:

{{ if $element }}
Element value: {{$element}}
{{ else }}
Element is empty
{{ end }}

With

with is similar to if statements, but unlike if, it updates dot(.) to refer to the value of the expression in with:

{{ with $array }}
There are {{ len . }} item(s)
{{ else }}
There are no alerts
{{ end }}

Range

range iterates over an array or map, and dot (.) is set to the current element of the array:

{{ range $array }}
{{ .itemPropertyName }}
{{ end }}

Optionally, you can handle empty objects using else:

{{ range $array }}
  {{ .itemPropertyName }}
{{ else }}
  Empty array
{{ end }}

You can also get the index of each item within a range by defining index and value variables at the start of the range:

{{ $num_items := len $array }}
{{ range $index, $item := $array }}
This is item {{ $index }} out of {{ $num_items }}
{{ end }}

Additionally, you can use {{break}} to stop the remaining iterations or {{continue}} to stop the current iteration and continue with the next one.

Functions

The global functions available in text/template are:

Function	Description
`and`	Returns the boolean AND of its arguments by returning the first empty argument or the last argument.
`call`	Returns the result of calling the first argument, which must be a function, with the remaining arguments as parameters.
`html`	Returns the escaped HTML equivalent of the textual representation of its arguments.
`index`	Returns the result of indexing its first argument by the following arguments, e.g., `{{ index $labels "instance" }}` returns the `instance` key in the `$labels` map variable.
`slice`	Returns the result of slicing its first argument by the remaining arguments.
`js`	Returns the escaped JavaScript equivalent of the textual representation of its arguments.
`len`	Returns the integer length of its argument, e.g., `{{ len $array }}`
`not`	Returns the boolean negation of its single argument.
`or`	Returns the boolean OR of its arguments by returning the first non-empty argument or the last argument.
`print`	An alias for fmt.Sprint
`printf`	An alias for fmt.Sprintf
`println`	An alias for fmt.Sprintln
`urlquery`	Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query

For more details, refer to the official documentation on functions in text/template.

Comparison operators

Boolean comparison operators are also available in text/template:

Function	Description
`eq`	Returns the boolean truth of arg1 == arg2
`ne`	Returns the boolean truth of arg1 != arg2
`lt`	Returns the boolean truth of arg1 < arg2
`le`	Returns the boolean truth of arg1 <= arg2
`gt`	Returns the boolean truth of arg1 > arg2
`ge`	Returns the boolean truth of arg1 >= arg2

Variables

Variables in text/template must be created within the template. For example, you can create a variable with the current value of dot (.) and assign a string or another object to the variable like this:

{{ $variable := . }}
{{ $variable := "This is a test" }}
{{ $variable }}

This template outputs:

This is a test

Templates

You can create reusable templates that can be executed from other templates or within the same template.

Define templates using define and the name of the template in double quotes:

{{ define "print_labels" }}
{{ end }}

You should not define templates with the same name as other templates, including default templates such as __subject, __text_values_list, __text_alert_list, default.title and default.message. Where a template has been created with the same name as a default template, or a template in another notification template, Grafana might use either template. Grafana does not prevent, or show an error message, when there are two or more templates with the same name.

Execute templates

You can execute defined templates using template, the name of the template in double quotes, and the cursor that should be passed to the template:

{{ template "print_labels" . }}

Within a template dot refers to the value that is passed to the template.

For example, if a template is passed a list of firing alerts then dot refers to that list of firing alerts:

{{ template "print_alerts" .Alerts }}

If the template is passed the sorted labels for an alert then dot refers to the list of sorted labels:

{{ template "print_labels" .SortedLabels }}

This is useful when writing reusable templates. For example, to print all alerts you might write the following:

{{ template "print_alerts" .Alerts }}

Then to print just the firing alerts you could write this:

{{ template "print_alerts" .Alerts.Firing }}

This works because both .Alerts and .Alerts.Firing is a list of alerts.

{{ define "print_alerts" }}
{{ range . }}
{{ template "print_labels" .SortedLabels }}
{{ end }}
{{ end }}

Note
You cannot create independent, reusable templates for labels and annotations as you can with notification templates. In alert rule templates, you need to write each template inline within the label or annotation field.

Comments

You can add comments with {{/* and */}}:

{{/* This is a comment */}}

To avoid adding line breaks, use:

{{- /* This is a comment with no leading or trailing line breaks */ -}}

Indentation

You can use indentation, both tabs and spaces, and line breaks, to make templates more readable:

{{ range .Alerts }}
  {{ range .Labels.SortedPairs }}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

However, indentation in the template is also present in the text.

Remove spaces and line breaks

In text/template use {{- and -}} to remove leading and trailing spaces and line breaks.

For example, when using indentation and line breaks to make a template more readable:

{{ range .Alerts }}
  {{ range .Labels.SortedPairs }}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

The indentation and line breaks are also present in the text:

    alertname = "Test"

    grafana_folder = "Test alerts"

You can remove the indentation and line breaks from the text changing }} to -}} at the start of each range:

{{ range .Alerts -}}
  {{ range .Labels.SortedPairs -}}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

The indentation and line breaks in the template are now absent from the text:

alertname = "Test"
grafana_folder = "Test alerts"