Using messaging templates
This documentation topic is designed for Grafana workspaces that support Grafana version 8.x.
For Grafana workspaces that support Grafana version 10.x, see Working in Grafana version 10.
For Grafana workspaces that support Grafana version 9.x, see Working in Grafana version 9.
Notifications sent via Working with contact points are built using messaging
templates. Grafana’s default templates are based on the Go templating system
Since most of the contact point fields can be templated, you can create reusable custom templates and use them in multiple contact points. The Template data topic lists variables that are available for templating.
Using templates
Templates are used to create a message. For example, with a Slack alert message, you can set the title and body in the contact point. The following example shows how to use default templates to create a title that contains a count of alerts firing and resolved, and a body that lists the alerts and their statuses.
-
Title:
{{ len .Alerts.Firing }} firing, {{ len .Alerts.Resolved }} resolved
-
Text Body:
{{ range .Alerts }}{{ .Status }}: {{ .Labels.alertname }} {{end }}
You can create your own custom templates, as in the following example.
-
Title:
{{ template "slack.default.title" .}}
-
Text Body:
{{ template "mymessage" .}}
The following is a sample template.
{{ define "myalert" }} [{{.Status}}] {{ .Labels.alertname }} Labels: {{ range .Labels.SortedPairs }} {{ .Name }}: {{ .Value }} {{ end }} {{ if gt (len .Annotations) 0 }} Annotations: {{ range .Annotations.SortedPairs }} {{ .Name }}: {{ .Value }} {{ end }} {{ end }} {{ if gt (len .SilenceURL ) 0 }} Silence alert: {{ .SilenceURL }} {{ end }} {{ if gt (len .DashboardURL ) 0 }} Go to dashboard: {{ .DashboardURL }} {{ end }} {{ end }}
The following procedures show how to create, edit, and delete custom message templates.
To create a message template
-
From your Grafana console, in the Grafana menu, choose the Alerting (bell) icon to open the Alerting page.
-
Choose Contact points.
-
From the Alertmanager dropdown, select the Alertmanager instance you want to create a message template for. The default is the Grafana Alertmanager.
-
Choose Add template.
-
Add a descriptive Name.
-
Add the Content for the template, for example:
{{ define "mymessage" }} {{ range .Alerts }} [{{ .Status }}] {{ range .Labels }} {{ .Name }}={{.Value }}{{end}} {{ end }} {{ end }}
The
define
tag in the Content section assigns the template name. This tag is optional, and when omitted, the template name is derived from the Name field. When both are specified, it is a best practice to keep them the same. -
Choose Save template.
Note
HTML in alerting message templates is rendered as text, with control characters escaped. Rendering of HTML in the resulting notification is not supported by Grafana.
To edit a message template
-
In the Alerting page, choose Contact points to open the list of contact points.
-
In the Template table, find the template you want to edit, then choose the Edit icon (pen).
-
Make your changes, then choose Save template.
To delete a message template
-
In the Alerting page, choose Contact points to open the list of contact points.
-
In the Template table, find the template you want to remove, then choose the Delete icon (trash can).
-
Choose Yes, delete to delete the template.
Nested templates
You can embed templates within other templates.
For example, you can define a template fragment using the define
keyword:
{{ define "mytemplate" }} {{ len .Alerts.Firing }} firing. {{ len .Alerts.Resolved }} resolved. {{ end }}
You can then embed custom templates within this fragment using the
template
keyword. For example:
Alert summary: {{ template "mytemplate" . }}
You can use the following built-in template options to embed custom templates.
Name | Notes |
---|---|
|
Displays high-level status information. |
|
Provides a formatted summary of firing and resolved alerts. |
Custom template examples
Here are examples of how to use custom templates.
Template to render a single alert:
{{ define "myalert" }} [{{.Status}}] {{ .Labels.alertname }} Labels: {{ range .Labels.SortedPairs }} {{ .Name }}: {{ .Value }} {{ end }} {{ if gt (len .Annotations) 0 }} Annotations: {{ range .Annotations.SortedPairs }} {{ .Name }}: {{ .Value }} {{ end }} {{ end }} {{ if gt (len .SilenceURL ) 0 }} Silence alert: {{ .SilenceURL }} {{ end }} {{ if gt (len .DashboardURL ) 0 }} Go to dashboard: {{ .DashboardURL }} {{ end }} {{ end }}
Template to render entire notification message:
{{ define "mymessage" }} {{ if gt (len .Alerts.Firing) 0 }} {{ len .Alerts.Firing }} firing: {{ range .Alerts.Firing }} {{ template "myalert" .}} {{ end }} {{ end }} {{ if gt (len .Alerts.Resolved) 0 }} {{ len .Alerts.Resolved }} resolved: {{ range .Alerts.Resolved }} {{ template "myalert" .}} {{ end }} {{ end }} {{ end }}
Template data
The following data is passed to message templates.
Name | Type | Notes |
---|---|---|
|
string |
Name of the contact point that the notification is being sent to. |
|
string |
firing if at least one alert is firing, otherwise resolved. |
|
Alert |
List of alert objects that are included in this notification (see below). |
|
KeyValue |
Labels these alerts were grouped by. |
|
KeyValue |
Labels common to all the alerts included in this notification. |
|
KeyValue |
Annotations common to all the alerts included in this notification. |
|
string |
Back link to the Grafana that sent the notification. If using external Alertmanager, back link to this Alertmanager. |
The Alerts
type exposes two functions for filtering the alerts
returned.
-
Alerts.Firing
– Returns a list of firing alerts. -
Alerts.Resolved
– Returns a list of resolved alerts.
Alert (type)
The alert type contains the following data.
Name | Type | Notes |
---|---|---|
Status |
string |
|
Labels |
KeyValue |
A set of labels attached to the alert. |
Annotations |
KeyValue |
A set of annotations attached to the alert. |
StartsAt |
time.Time |
Time the alert started firing. |
EndsAt |
time.Time |
Only set if the end time of an alert is known. Otherwise set to a configurable timeout period from the time since the last alert was received. |
GeneratorURL |
string |
A back link to Grafana or external Alertmanager. |
SilenceURL |
string |
Link to grafana silence for with labels for this alert pre-filled. Only for Grafana managed alerts. |
DashboardURL |
string |
Link to grafana dashboard, if alert rule belongs to one. Only for Grafana managed alerts. |
PanelURL |
string |
Link to grafana dashboard panel, if alert rule belongs to one. Only for Grafana managed alerts. |
Fingerprint |
string |
Fingerprint that can be used to identify the alert. |
ValueString |
string |
A string that contains the labels and value of each reduced expression in the alert. |
KeyValue type
The KeyValue
type is a set of key/value string pairs that represent
labels and annotations.
In addition to direct access of the data stored as a KeyValue
, there
are also methods for sorting, removing and transforming the data.
Name | Arguments | Returns | Notes |
---|---|---|---|
SortedPairs |
Sorted list of key and value string pairs |
||
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 |
Template functions
Using template functions you can process labels and annotations to generate dynamic notifications. The following functions are available.
Name | Argument type | Return type | Description |
---|---|---|---|
|
number or string |
string |
Converts a number to a more readable format, using metric prefixes. |
|
number or string |
string |
Like humanize, but uses 1024 as the base rather than 1000. |
|
number or string |
string |
Converts a duration in seconds to a more readable format. |
|
number or string |
string |
Converts a ratio value to a fraction of 100. |
|
number or string |
string |
Converts a Unix timestamp in seconds to a more readable format. |
|
string |
string |
strings.Title, capitalizes first character of each word. |
|
string |
string |
strings.ToUpper, converts all characters to upper case. |
|
string |
string |
strings.ToLower, converts all characters to lower case. |
|
pattern, text |
boolean |
regexp.MatchString Tests for an unanchored regexp match. |
|
pattern, replacement, text |
string |
Regexp.ReplaceAllString Regexp substitution, unanchored. |
|
string - JSON Object with |
string |
Returns the path to graphical view in Explore for the given expression and data source. |
|
string - JSON Object with |
string |
Returns the path to tabular view in Explore for the given expression and data source. |
|
[]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. |
|
nothing |
string |
Returns a string representing the external URL. |
|
nothing |
string |
Returns the path of the external URL. |
The following table shows examples of using each function.
Function | TemplateString | Input | Expected |
---|---|---|---|
humanize |
{ humanize $value } |
1234567.0 |
1.235M |
humanize1024 |
{ humanize1024 $value } |
1048576.0 |
1Mi |
humanizeDuration |
{ humanizeDuration $value } |
899.99 |
14m 59s |
humanizePercentage |
{ humanizePercentage $value } |
0.1234567 |
12.35% |
humanizeTimestamp |
{ humanizeTimestamp $value } |
1435065584.128 |
2015-06-23 13:19:44.128 +0000 UTC |
title |
{ $value | title } |
aa bB CC |
Aa Bb Cc |
toUpper |
{ $value | toUpper } |
aa bB CC |
AA BB CC |
toLower |
{ $value | toLower } |
aa bB CC |
aa bb cc |
match |
{ match "a+" $labels.instance } |
aa |
true |
reReplaceAll |
{{ reReplaceAll "localhost:(.*)" "my.domain:$1" $labels.instance }} |
localhost:3000 |
my.domain:3000 |
graphLink |
{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }} |
/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}] |
|
tableLink |
{{ tableLink "{\"expr\":\"up\", \"datasource\":\"gdev-prometheus\"}" }} |
/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}] |
|
args |
{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}} |
1 2 |
|
externalURL |
{ externalURL } |
http://localhost/path/prefix |
|
pathPrefix |
{ pathPrefix } |
/path/prefix |