mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
alerting>intro>templates (#86850)
* alerting>intro>templates * restored alias url * numbering * diagram * Update docs/sources/alerting/fundamentals/notifications/message-templating.md Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * formatting * figure fix * Brenda edits * Brenda edit 2 * new diagram * new diagram2 --------- Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com>
This commit is contained in:
parent
28e86c3edb
commit
42778de2b4
@ -4,7 +4,7 @@ aliases:
|
||||
- ../../alert-rules/message-templating/ # /docs/grafana/<GRAFANA_VERSION>/alerting/alert-rules/message-templating/
|
||||
- ../../unified-alerting/message-templating/ # /docs/grafana/<GRAFANA_VERSION>/alerting/unified-alerting/message-templating/
|
||||
canonical: https://grafana.com/docs/grafana/latest/alerting/fundamentals/notifications/message-templating/
|
||||
description: Learn about notification templating
|
||||
description: Learn about templates
|
||||
keywords:
|
||||
- grafana
|
||||
- alerting
|
||||
@ -16,57 +16,36 @@ labels:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
title: Notification templates
|
||||
title: Templates
|
||||
weight: 114
|
||||
---
|
||||
|
||||
# Notification templates
|
||||
## Templates
|
||||
|
||||
Notifications sent via contact points are built using notification 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).
|
||||
Use templating to customize, format, and reuse alert notification messages. Create more flexible and informative alert notification messages by incorporating dynamic content, such as metric values, labels, and other contextual information.
|
||||
|
||||
The default template [default_template.go](https://github.com/grafana/alerting/blob/main/templates/default_template.go) is a useful reference for custom templates.
|
||||
In Grafana, there are two ways to template your alert notification messages:
|
||||
|
||||
Since most of the contact point fields can be templated, you can create reusable custom templates and use them in multiple contact points.
|
||||
1. Labels and annotations
|
||||
|
||||
### Using templates
|
||||
- Template labels and annotations in alert rules.
|
||||
- Labels and annotations contain information about an alert.
|
||||
- Labels are used to differentiate an alert from all other alerts, while annotations are used to add additional information to an existing alert.
|
||||
|
||||
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.
|
||||
2. Notification templates
|
||||
|
||||
{{< figure src="/static/img/docs/alerting/unified/contact-points-template-fields-8-0.png" class="docs-image--no-shadow" max-width= "550px" caption="Default template" >}}
|
||||
- Template notifications in contact points.
|
||||
- Add notification templates to contact points for reuse and consistent messaging in your notifications.
|
||||
- Use notification templates to change the title, message, and format of the message in your notifications.
|
||||
|
||||
The following example shows the use of a custom template within one of the contact point fields.
|
||||
This diagram illustrates the entire process of templating, from the creation of labels and annotations in alert rules or notification templates in contact points, to what they look like when exported and applied in your alert notification messages.
|
||||
|
||||
{{< figure src="/static/img/docs/alerting/unified/contact-points-use-template-8-0.png" class="docs-image--no-shadow" max-width= "550px" caption="Default template" >}}
|
||||
{{< figure src="/media/docs/alerting/grafana-templating-diagram-2.jpg" max-width="1200px" caption="How Templating works" >}}
|
||||
|
||||
### Nested templates
|
||||
In this diagram:
|
||||
|
||||
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.message`, formatted for Microsoft Teams. |
|
||||
|
||||
### HTML in notification templates
|
||||
|
||||
HTML in alerting notification 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.
|
||||
- **Monitored Application**: A web server, database, or any other service generating metrics. For example, it could be an NGINX server providing metrics about request rates, response times, and so on.
|
||||
- **Prometheus**: Prometheus collects metrics from the monitored application. For example, it might scrape metrics from the NGINX server, including labels like instance (the server hostname) and job (the service name).
|
||||
- **Grafana**: Grafana queries Prometheus to retrieve metrics data. For example, you might create an alert rule to monitor NGINX request rates over time, and template labels or annotations based on the instance label.
|
||||
- **Alertmanager**: Part of the Prometheus ecosystem, Alertmanager handles alert notifications. For example, if the request rate exceeds a certain threshold on a particular NGINX server, Alertmanager can send an alert notification to, for example, Slack or email, including the server name and the exceeded threshold (the instance label will be interpolated, and the actual server name will appear in the alert notification).
|
||||
- **Alert notification**: When an alert rule condition is met, Alertmanager sends a notification to various channels such as Slack, Grafana OnCall, etc. These notifications can include information from the labels associated with the alerting rule. For example, if an alert triggers due to high CPU usage on a specific server, the notification message can include details like server name (instance label), disk usage percentage, and the threshold that was exceeded.
|
||||
|
Loading…
Reference in New Issue
Block a user