From 59bda131ec6a498a2f9e1baec915ff043b521f4a Mon Sep 17 00:00:00 2001 From: Alexander Weaver Date: Tue, 11 Jan 2022 14:16:04 -0600 Subject: [PATCH] Alerting: [Docs] Clarifications regarding what's supported in alerting message templates (#43544) * Clarify docs for alerting templates * Fix template cross-reference * Add a single missing delimiter * Update docs/sources/alerting/unified-alerting/message-templating/_index.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> * Update docs/sources/alerting/unified-alerting/message-templating/_index.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> * Update docs/sources/alerting/unified-alerting/message-templating/_index.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> * Update docs/sources/alerting/unified-alerting/message-templating/_index.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> * Address various points of docs feedback * Update docs/sources/alerting/unified-alerting/message-templating/_index.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> * Update docs/sources/alerting/unified-alerting/message-templating/_index.md Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> * Update docs/sources/alerting/unified-alerting/message-templating/_index.md Co-authored-by: Yuriy Tseretyan Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com> Co-authored-by: Yuriy Tseretyan --- .../message-templating/_index.md | 45 ++++++++++++++++--- 1 file changed, 40 insertions(+), 5 deletions(-) diff --git a/docs/sources/alerting/unified-alerting/message-templating/_index.md b/docs/sources/alerting/unified-alerting/message-templating/_index.md index 19fc8a0a319..909b1939a19 100644 --- a/docs/sources/alerting/unified-alerting/message-templating/_index.md +++ b/docs/sources/alerting/unified-alerting/message-templating/_index.md @@ -14,7 +14,7 @@ Since most of the contact point fields can be templated, you can create reusable ### Using templates -The following example shows the use of default templates to render an alert message in slack. The message title contains a count of firing or resolved alerts and the message body has a list of alerts with status. +The following example shows how to use default templates to render an alert message in Slack. The message title contains a count of alerts that are firing or were resolved. The message body lists the alerts and their status. @@ -52,12 +52,41 @@ The `define` tag in the Content section assigns the template name. This tag is o Use caution when deleting a template since Grafana does not prevent you from deleting templates that are in use. +### 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 any of the following built-in template options to embed custom templates. + +| Name | Notes | +| ----------------------- | ------------------------------------------------------------- | +| `default.title` | Displays high-level status information. | +| `default.message` | Provides a formatted summary of firing and resolved alerts. | +| `teams.default.message` | Similar to `default.messsage`, formatted for Microsoft Teams. | + ### Custom template examples +Here are a few examples of how to use custom templates. + Template to render a single alert: ``` -{{ define "alert" }} +{{ define "myalert" }} [{{.Status}}] {{ .Labels.alertname }} Labels: @@ -84,14 +113,20 @@ Template to render a single alert: Template to render entire notification message: ``` -{{ define "message" }} +{{ define "mymessage" }} {{ if gt (len .Alerts.Firing) 0 }} {{ len .Alerts.Firing }} firing: - {{ range .Alerts.Firing }} {{ template "alert" .}} {{ end }} + {{ range .Alerts.Firing }} {{ template "myalert" .}} {{ end }} {{ end }} {{ if gt (len .Alerts.Resolved) 0 }} {{ len .Alerts.Resolved }} resolved: - {{ range .Alerts.Resolved }} {{ template "alert" .}} {{ end }} + {{ range .Alerts.Resolved }} {{ template "myalert" .}} {{ end }} {{ end }} {{ end }} ``` + +### HTML in Message Templates + +HTML in alerting message templates is escaped. We do not support rendering of HTML in the resulting notification. + +Some notifiers support alternative methods of changing the look and feel of the resulting notification. For example, Grafana installs the base template for alerting emails to `/public/emails/ng_alert_notification.html`. You can edit this file to change the appearance of all alerting emails.