You can use templates to customize alert and notification messages, including dynamic data from alert rule queries.
In Grafana Alerting, you can template alert messages in two ways.
1.**Template annotations and labels**: In the alert rule definition, you can template annotations and labels to include extra information from query data to the alert, adding meaningful details based on the query results.
1.**Template notifications**: You can template notifications to control the content and appearance of your notifications.
## How templating works
In this diagram, you can see the differences between both types of templates.
Refer to [Templates Introduction](ref:intro-to-templates) for a more detailed explanation of this diagram.
Both types of templates are written in the Go templating system. However, it's important to understand that variables and functions used in notification templates are different from those used in annotation and label templates.
1.**Template annotations and labels**: These templates add extra information to individual alert instances. Template variables like [`$labels`](ref:reference-labels) and [`$values`](ref:reference-values) represent alert query data of the individual alert instance.
1.**Template notifications**: Notification templates format the notification content for a group of alerts. Variables like [`.Alerts`](ref:notification-data-reference) include all firing and resolved alerts in the notification.
## Template annotations
[Annotations](ref:annotations) add additional information to alert instances and are often used to help identify the alert and guide responders on how to address the issue.
Annotations are key-value pairs defined in the alert rule. They can contain plain text or template code that is evaluated when the alert fires.
Grafana includes several optional annotations, such as `description`, `summary`, and `runbook_url`, which can be edited in the alert rule. You can also create your custom annotations. For example, you might create a new annotation named `location` to report the location of the system that triggered the alert.
For instance, you can template the previous example to display the specific instance and CPU value that triggered the alert.
```
CPU usage for {{ $labels.instance }} has exceeded 80% ({{ $values.A.Value }}) for the last 5 minutes.
```
Alternatively, you can use the `index` function to print query values.
```
CPU usage for {{ index $labels "instance" }} has exceeded 80% ({{ index $values "A" }}) for the last 5 minutes.
```
The result of the annotation would be as follows.
```
CPU usage for Instance 1 has exceeded 80% (81.2345) for the last 5 minutes.
```
### How to template an annotation
Complete the following steps to template an annotation.
1. Navigate to **Alerts & IRM** -> **Alert rules** -> create or edit an alert rule.
1. Scroll down to the **Configure notification message** section.
1. Copy in your template in the corresponding annotation field (`summary`, `description`, `runbook_url`, `custom`).
### Preview annotation templates
You can template annotations when creating or editing an alert rule.
{{<figuresrc="/media/docs/alerting/alert-rule-using-annotation-template.png"max-width="1200px"alt="An alert rule templating the annotation summary">}}
Two common methods are used to test and preview annotation templates:
1. Trigger the alert and [view the alert instance state in the Grafana UI](ref:view-alert-state), where all annotations of the alert instance are displayed.
1. Use a notification template that displays all annotations, then [preview the notification template](ref:preview-notifications) using the alert instance.
## Template labels
The set of [labels](ref:labels) for an alert instance is used to uniquely identify that alert among all other alert instances.
Labels determine how alerts are routed and managed for notifications, making their design key to the effectiveness of your alerting system.
Labels can be returned from an alert rule query, such as the `pod` label in a Kubernetes Prometheus query. You can also define additional labels in the alert rule to provide extra information for processing alerts.
Like annotations, labels are key-value pairs that can contain plain text or template code evaluated when the alert fires.
Template labels when the labels returned by your queries are insufficient. For instance:
- A new label based on a query value can group a subset of alerts differently, changing how notifications are sent.
- A new label based on a query value can be used in a notification policy to alter the notification contact point.
Here’s an example of templating a `severity` label based on the query value.
In this example, the value of the `severity` label is determined by the query value, and the possible options are `critical`, `high`, `medium`, or `low`. You can then use the `severity` label to change their notifications—for instance, sending `critical` alerts immediately or routing `low` alerts to a specific team for further review.
> **Note:** An alert instance is uniquely identified by its set of labels.
>
> - Avoid displaying query values in labels, as this can create numerous alert instances—one for each distinct label set. Instead, use annotations for query values.
> - If a templated label's value changes, it maps to a different alert instance, and the previous instance is considered **stale**. Learn all the details in this [example using dynamic labels](ref:shared-dynamic-label-example).
Grafana Cloud users can use built-in AI tool to generate templates in the appropriate [alerting template language](/docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/template-notifications/language/) for you.
To use AI to create your template, follow these steps:
1. Go to **Alerting -> Contact points**.
1. Click the Notification Templates tab then, click the **+ Add notification template group** button.
1. Name your template.
1. In the Template group section, click the **Generate with AI** button.
1. Supply the AI tool with a prompt or select from one of the example prompts and edit that if necessary.
For a practical example of templating, refer to our [Getting Started with Templating tutorial](https://grafana.com/tutorials/alerting-get-started-pt4/).
