mirror of
https://github.com/grafana/grafana.git
synced 2025-08-02 22:24:31 +08:00
Docs:Cleanup alerting docs (#48826)
* Remove What's new reference. * Moved messaging templates to under contact points. fixed broken relrefs. * Fixed some more reflrefs * Fixed a few more broken relrefs and adjusted weight
This commit is contained in:
JitaC
@ -0,0 +1,139 @@
|
||||
+++
|
||||
title = "Message templating"
|
||||
description = "Message templating"
|
||||
keywords = ["grafana", "alerting", "guide", "contact point", "templating"]
|
||||
aliases = ["/docs/grafana/latest/alerting/message-templating/", "/docs/grafana/latest/alerting/unified-alerting/message-templating/"]
|
||||
weight = 400
|
||||
+++
|
||||
|
||||
# Message templating
|
||||
|
||||
Notifications sent via [contact points]({{< relref "../../contact-points/_index.md" >}}) are built using messaging templates. Grafana's default templates are based on the [Go templating system](https://golang.org/pkg/text/template) where some fields are evaluated as text, while others are evaluated as HTML (which can affect escaping). The default template, defined in [default_template.go](https://github.com/grafana/grafana/blob/main/pkg/services/ngalert/notifier/channels/default_template.go), is a useful reference for custom templates.
|
||||
|
||||
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]({{< relref "./template-data.md" >}}) topic lists variables that are available for templating. The default template is defined in [default_template.go](https://github.com/grafana/grafana/blob/main/pkg/services/ngalert/notifier/channels/default_template.go) which can serve as a useful reference or starting point for custom templates.
|
||||
|
||||
### Using templates
|
||||
|
||||
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.
|
||||
|
||||
<img src="/static/img/docs/alerting/unified/contact-points-template-fields-8-0.png" width="450px">
|
||||
|
||||
The following example shows the use of a custom template within one of the contact point fields.
|
||||
|
||||
<img src="/static/img/docs/alerting/unified/contact-points-use-template-8-0.png" width="400px">
|
||||
|
||||
### Create a message template
|
||||
|
||||
> **Note:** Before Grafana v8.2, the configuration of the embedded Alertmanager was shared across organisations. Users of Grafana 8.0 and 8.1 are advised to use the new Grafana 8 alerts only if they have one organisation. Otherwise, silences for the Grafana managed alerts will be visible by all organizations.
|
||||
|
||||
1. In the Grafana menu, click the **Alerting** (bell) icon to open the Alerting page listing existing alerts.
|
||||
1. In the Alerting page, click **Contact points** to open the page listing existing contact points.
|
||||
1. From Alertmanager drop-down, select an external Alertmanager to create and manage templates for the external data source. Otherwise, keep the default option of Grafana.
|
||||
{{< figure max-width="250px" src="/static/img/docs/alerting/unified/contact-points-select-am-8-0.gif" caption="Select Alertmanager" >}}
|
||||
1. Click **Add template**.
|
||||
1. In **Name**, add a descriptive name.
|
||||
1. In **Content**, add the content of the template.
|
||||
1. Click **Save template** button at the bottom of the page.
|
||||
<img src="/static/img/docs/alerting/unified/templates-create-8-0.png" width="600px">
|
||||
|
||||
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 ensure that they are the same.
|
||||
|
||||
### Edit a message template
|
||||
|
||||
1. In the Alerting page, click **Contact points** to open the page listing existing contact points.
|
||||
1. In the Template table, find the template you want to edit, then click the **Edit** (pen icon).
|
||||
1. Make your changes, then click **Save template**.
|
||||
|
||||
### Delete a message template
|
||||
|
||||
1. In the Alerting page, click **Contact points** to open the page listing existing contact points.
|
||||
1. In the Template table, find the template you want to delete, then click the **Delete** (trash icon).
|
||||
1. In the confirmation dialog, click **Yes, delete** to delete the template.
|
||||
|
||||
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. |
|
||||
|
||||
### Example of a custom template
|
||||
|
||||
Here's an example of how to use a custom template. You can also use the default template included in the setup.
|
||||
|
||||
Step 1: Configure a 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 }}
|
||||
```
|
||||
|
||||
Step 2: Configure a 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 }}
|
||||
```
|
||||
|
||||
Step 3: Add `mymessage` in the notification message field.
|
||||
|
||||
```
|
||||
Alert summary:
|
||||
{{ template "mymessage" . }}
|
||||
```
|
||||
|
||||
### 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 `<grafana-install-dir>/public/emails/ng_alert_notification.html`. You can edit this file to change the appearance of all alerting emails.
|
||||
@ -0,0 +1,62 @@
|
||||
+++
|
||||
title = "Template data"
|
||||
keywords = ["grafana", "alerting", "guide", "contact point", "templating"]
|
||||
aliases = ["/docs/grafana/latest/alerting/unified-alerting/message-templating/template-data/"]
|
||||
+++
|
||||
|
||||
# Template data
|
||||
|
||||
Template data is passed on to [message templates]({{< relref "./_index.md" >}}) as well as sent as payload to webhook pushes.
|
||||
|
||||
| Name | Type | Notes |
|
||||
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
|
||||
| Receiver | string | Name of the contact point that the notification is being sent to. |
|
||||
| Status | string | `firing` if at least one alert is firing, otherwise `resolved`. |
|
||||
| Alerts | Alert | List of alert objects that are included in this notification (see below). |
|
||||
| GroupLabels | KeyValue | Labels these alerts were grouped by. |
|
||||
| CommonLabels | KeyValue | Labels common to all the alerts included in this notification. |
|
||||
| CommonAnnotations | KeyValue | Annotations common to all the alerts included in this notification. |
|
||||
| ExternalURL | string | Back link to the Grafana that sent the notification. If using external Alertmanager, back link to this Alertmanager. |
|
||||
|
||||
The `Alerts` type exposes functions for filtering alerts:
|
||||
|
||||
- `Alerts.Firing` returns a list of firing alerts.
|
||||
- `Alerts.Resolved` returns a list of resolved alerts.
|
||||
|
||||
## Alert
|
||||
|
||||
| Name | Type | Notes |
|
||||
| ------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Status | string | `firing` or `resolved`. |
|
||||
| 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
|
||||
|
||||
`KeyValue` is a set of key/value string pairs that represent labels and annotations.
|
||||
|
||||
Here is an example containing two annotations:
|
||||
|
||||
```json
|
||||
{
|
||||
"summary": "alert summary",
|
||||
"description": "alert description"
|
||||
}
|
||||
```
|
||||
|
||||
In addition to direct access of data (labels and annotations) stored as KeyValue, there are also methods for sorting, removing and transforming.
|
||||
|
||||
| Name | Arguments | Returns | Notes |
|
||||
| ----------- | --------- | --------------------------------------- | ----------------------------------------------------------- |
|
||||
| SortedPairs | | Sorted list of key & 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 |
|
||||
@ -0,0 +1,139 @@
|
||||
+++
|
||||
title = "Template functions"
|
||||
keywords = ["grafana", "alerting", "guide", "contact point", "templating"]
|
||||
aliases = ["/docs/grafana/latest/alerting/unified-alerting/message-templating/template-functions/"]
|
||||
+++
|
||||
|
||||
# Template Functions
|
||||
|
||||
Template functions allow you to process labels and annotations to generate dynamic notifications.
|
||||
|
||||
| Name | Argument type | Return type | Description |
|
||||
| ----------------------------------------- | ------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [humanize](#humanize) | number or string | string | Converts a number to a more readable format, using metric prefixes. |
|
||||
| [humanize1024](#humanize1024) | number or string | string | Like humanize, but uses 1024 as the base rather than 1000. |
|
||||
| [humanizeDuration](#humanizeduration) | number or string | string | Converts a duration in seconds to a more readable format. |
|
||||
| [humanizePercentage](#humanizepercentage) | number or string | string | Converts a ratio value to a fraction of 100. |
|
||||
| [humanizeTimestamp](#humanizetimestamp) | number or string | string | Converts a Unix timestamp in seconds to a more readable format. |
|
||||
| [title](#title) | string | string | strings.Title, capitalises first character of each word. |
|
||||
| [toUpper](#toupper) | string | string | strings.ToUpper, converts all characters to upper case. |
|
||||
| [toLower](#tolower) | string | string | strings.ToLower, converts all characters to lower case. |
|
||||
| [match](#match) | pattern, text | boolean | regexp.MatchString Tests for a unanchored regexp match. |
|
||||
| [reReplaceAll](#rereplaceall) | pattern, replacement, text | string | Regexp.ReplaceAllString Regexp substitution, unanchored. |
|
||||
| [graphLink](#graphlink) | string - JSON Object with `"expr"` and `"datasource"` fields | string | Returns the path to graphical view in [Explore](https://grafana.com/docs/grafana/latest/explore/) for the given expression and data source. |
|
||||
| [tableLink](#tablelink) | string- JSON Object with `"expr"` and `"datasource"` fields | string | Returns the path to tabular view in [Explore](https://grafana.com/docs/grafana/latest/explore/) for the given expression and data source. |
|
||||
| [args](#args) | []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. |
|
||||
| [externalURL](#externalurl) | nothing | string | Returns a string representing the external URL. |
|
||||
| [pathPrefix](#pathprefix) | nothing | string | Returns the path of the external URL. |
|
||||
|
||||
## Examples
|
||||
|
||||
### humanize
|
||||
|
||||
**Template string** `{ humanize $value }`
|
||||
|
||||
**Input** `1234567.0`
|
||||
|
||||
**Expected** `1.235M`
|
||||
|
||||
### humanize1024
|
||||
|
||||
**TemplateString** `{ humanize1024 $value } `
|
||||
|
||||
**Input** `1048576.0`
|
||||
|
||||
**Expected** `1Mi`
|
||||
|
||||
### humanizeDuration
|
||||
|
||||
**TemplateString** `{ humanizeDuration $value }`
|
||||
|
||||
**Input** `899.99`
|
||||
|
||||
**Expected** `14m 59s`
|
||||
|
||||
### humanizePercentage
|
||||
|
||||
**TemplateString** `{ humanizePercentage $value }`
|
||||
|
||||
**Input** `0.1234567`
|
||||
|
||||
**Expected** `12.35%`
|
||||
|
||||
### humanizeTimestamp
|
||||
|
||||
**TemplateString** `{ $value | humanizeTimestamp }`
|
||||
|
||||
**Input** `1435065584.128`
|
||||
|
||||
**Expected** `2015-06-23 13:19:44.128 +0000 UTC`
|
||||
|
||||
### title
|
||||
|
||||
**TemplateString** `{ $value | title }`
|
||||
|
||||
**Input** `aa bb CC`
|
||||
|
||||
**Expected** `Aa Bb Cc`
|
||||
|
||||
### toUpper
|
||||
|
||||
**TemplateString** `{ $value | toUpper }`
|
||||
|
||||
**Input** `aa bb CC`
|
||||
|
||||
**Expected** `AA BB CC`
|
||||
|
||||
### toLower
|
||||
|
||||
**TemplateString** `{ $value | toLower }`
|
||||
|
||||
**Input** `aA bB CC`
|
||||
|
||||
**Expected** `aa bb cc`
|
||||
|
||||
### match
|
||||
|
||||
**TemplateString** `{ match "a+" $labels.instance }`
|
||||
|
||||
**Input** `aa`
|
||||
|
||||
**Expected** `true`
|
||||
|
||||
### reReplaceAll
|
||||
|
||||
**TemplateString** `{{ reReplaceAll "localhost:(.*)" "my.domain:$1" $labels.instance }}`
|
||||
|
||||
**Input** `localhost:3000`
|
||||
|
||||
**Expected** `my.domain:3000`
|
||||
|
||||
### graphLink
|
||||
|
||||
**TemplateString** `{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}`
|
||||
|
||||
**Expected** `/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}]`
|
||||
|
||||
### tableLink
|
||||
|
||||
**TemplateString** `{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}`
|
||||
|
||||
**Expected** `/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]`
|
||||
|
||||
### args
|
||||
|
||||
**TemplateString** `{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}`
|
||||
|
||||
**Expected** `1 2`
|
||||
|
||||
### externalURL
|
||||
|
||||
**TemplateString** `{ externalURL }`
|
||||
|
||||
**Expected** `http://localhost/path/prefix`
|
||||
|
||||
### pathPrefix
|
||||
|
||||
**TemplateString** `{ pathPrefix }`
|
||||
|
||||
**Expected** `/path/prefix`
|
||||
Reference in New Issue
Block a user