Documentation Grafana documentation Alerting Configure notifications Template notifications Template language

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 context, some additional variables and functions are only available for either notification or alert rule templates. Refer to:

• Annotation and label template reference
• Notification template reference

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.

Copy

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

Copy

{{ .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.

If

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

Go Copy

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

Go Copy

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

Go Copy

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

Optionally, you can handle empty objects using else:

Go Copy

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

Go Copy

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

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

Comparison operators

Boolean comparison operators are also available in text/template:

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:

Go Copy

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

This template outputs:

Copy

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:

Go Copy

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

Go Copy

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

Go Copy

{{ template "print_alerts" .Alerts }}

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

Go Copy

{{ template "print_labels" .SortedLabels }}

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

Go Copy

{{ template "print_alerts" .Alerts }}

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

Go Copy

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

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

Go Copy

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

Comments

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

Go Copy

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

To avoid adding line breaks, use:

Go Copy

{{- /* 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:

Go Copy

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

Go Copy

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

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

Copy

    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:

Go Copy

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

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

Copy

alertname = "Test"
grafana_folder = "Test alerts"