Notification template reference
By default, Grafana provides predefined templates to format notification messages.
You can also customize your notifications with custom templates, which are based on the Go template language.
This documentation lists the data available for use in notification templates.
Notification Data
In notification templates, dot (.
) is initialized with the following data:
It’s important to remember that a single notification can group multiple alerts to reduce the number of alerts you receive. Alerts
is an array that includes all the alerts in the notification.
Here’s an example that prints all available notification data from dot (.
):
{{ define "custom_template" }}
{{ .Receiver }}
{{ .Status }}
There are {{ len .Alerts }} alerts
There are {{ len .Alerts.Firing }} firing alerts
There are {{ len .Alerts.Resolved }} resolved alerts
{{ .GroupLabels }}
{{ .CommonLabels }}
{{ .CommonAnnotations }}
{{ .ExternalURL }}
{{ end }}
You can execute this template by passing the dot (.
):
{{ template "custom_template" . }}
Alert
Alert
contains data for an individual alert:
Grafana-managed alerts include these additional properties:
This example iterates over the list of firing and resolved alerts (.Alerts
) in the notification and prints the data for each alert:
{{ define "custom_template" }}
{{ range .Alerts }}
{{ .Status }}
{{ .Labels }}
{{ .Annotations }}
{{ .StartsAt }}
{{ .EndsAt }}
{{ .GeneratorURL }}
{{ .Fingerprint }}
{{/* Only available for Grafana-managed alerts */}}
{{ .DashboardURL }}
{{ .PanelURL }}
{{ .SilenceURL }}
{{ .Values }}
{{ .ValueString }}
{{ end }}
{{ end }}
You can run this template by passing the dot (.
):
{{ template "custom_template" . }}
KV
KV
is a set of key value pairs, where each key and value is a string.
Similarly to accessing variable properties, you can use .
to retrieve the value of a value. For example:
{{ define "custom_template" }}
{{ .CommonLabels.grafana_folder }}
{{ end }}
If a KV happens to contain numbers or bools then these are string representations of the numeric or boolean value.
Additionally, KV provides methods to sort the pairs, remove keys, and iterate over just the keys or values:
Here’s an example of using these methods:
{{ define "custom_template" }}
{{ .CommonLabels.SortedPairs }}
{{ .CommonLabels.Names }}
{{ .CommonLabels.Values }}
{{ .CommonLabels.Remove (stringSlice "grafana_folder") }}
{{ end }}
Time
Some template functions and properties return a Time
object, which refers to the type Time
in Go’s time package.
When accessing a Time
object, you can use various Time
functions in your templates as follows.
{{ define "custom_template" }}
{{ range .Alerts }}
{{ .StartsAt }}
{{ .StartsAt.Add 6000000000000 }}
{{ .StartsAt.Add -6000000000000 }}
{{ .StartsAt.AddDate 1 0 0 }}
{{ .StartsAt.Year }}/{{ .StartsAt.Month }}/{{ .StartsAt.Day }}
{{ .StartsAt.Hour }}:{{ .StartsAt.Minute }}:{{ .StartsAt.Second }}
{{ .StartsAt.YearDay }}-{{ .StartsAt.Weekday }}
{{ .StartsAt.Unix }} {{ .StartsAt.UnixMilli }}
{{ end}}
{{ end }}
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 notifications:
Here’s an example using some functions to format text:
{{ define "custom_template" }}
{{ title "hello, world!" }}
{{ toUpper "Hello, world!" }}
{{ toLower "Hello, world!" }}
{{ trimSpace "Hello, world!" }}
{{ match "a.*" "abc" }}
{{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }}
{{ join "-" (stringSlice "a" "b" "c") }}
{{ safeHtml "<b>Text</b>"}}
{{ stringSlice "a" "b" "c" }}
{{ end }}
date
and tz
can format times. For example, to print the time an alert fired in the format 15:04:05 MST
:
{{ define "custom_template" }}
{{ range .Alerts }}
{{ .StartsAt | date "15:04:05 MST" }}
{{ end}}
{{ end }}
You can then use tz
to change the timezone from UTC to local time, such as Europe/Paris
.
{{ define "custom_template" }}
{{ range .Alerts }}
{{ .StartsAt | tz "Europe/Paris" }}
{{ .StartsAt | tz "Europe/Paris" | date "15:04:05 MST" }}
{{ end}}
{{ end }}
2024-10-30 21:01:45.227 +0100 CET
21:01:45 CET
Differences with annotation and label templates
In the alert rule, you can also template annotations and labels to include additional information. For example, you might add a summary
annotation that displays the query value triggering the alert.
Annotation and label templates add relevant information to individual alert instances, while notification templates inform about a group of alert instances.
Since both types of templates operate in distinct contexts, the functions and variables available in annotation and label templates differ from those used in notification templates.