Configure templates
Grafana OnCall integrates with your monitoring systems using webhooks with JSON payloads. By default, these webhooks deliver raw JSON payloads. Grafana OnCall applies a pre-configured alert template to modify these payloads into a more human-readable format. These templates are customizable, enabling you to format alerts and notify different escalation chains based on alert content.
Understand your alert payload
Alerts received by Grafana OnCall contain metadata as key-value pairs in a JSON object.
All alerts and alert groups in Grafana OnCall contain the following fields.
Title
Message
Image Url
Grouping Id
Resolved by source
Acknowledged by source
Source link
The following is an example of an alert initiated by Grafana Alerting and received by Grafana OnCall:
{
"dashboardId": 1,
"title": "[Alerting] Panel Title alert",
"message": "Notification Message",
"evalMatches": [
{
"value": 1,
"metric": "Count",
"tags": {}
}
],
"imageUrl": "https://grafana.com/static/assets/img/blog/mixed_styles.png",
"orgId": 1,
"panelId": 2,
"ruleId": 1,
"ruleName": "Panel Title alert",
"ruleUrl": "http://localhost:3000/d/hZ7BuVbWz/test-dashboard?fullscreen\u0026edit\u0026tab=alert\u0026panelId=2\u0026orgId=1",
"state": "alerting",
"tags": {
"tag name": "tag value"
}
}
Map payloads to OnCall fields
Each field of an alert in OnCall is mapped to the JSON payload keys.
Grafana OnCall converts the JSON payload to specific alert fields. For example:
{{ payload.title }}
->Title
{{ payload.message }}
->Message
{{ payload.imageUrl }}
->Image Url
Behavioral mappings include:
{{ payload.ruleId }}
->Grouping Id
{{ 1 if payload.state == 'OK' else 0 }}
->Resolve Signal
Types of templates
Alert templates allow you to format any alert fields recognized by Grafana OnCall. You can customize default alert templates for all the different notification methods.
Note
For conditional templates, the output should beTrue
to be applied, for example{{ True if payload.state == 'OK' else False }}
Routing template
Routing templates determine how alerts are routed to different escalation chains based on alert content.
These are conditional templates, output should be True
.
Appearance templates
Appearance templates customize how alerts are displayed across various platforms, including the web, Slack, MS Teams, SMS, phone calls, emails, and mobile app push notifications.
You can use appearance templates to define Title
, Message
, and Image URL
depending on the notification method.
Title
,Message
,Image URL
for WebTitle
,Message
,Image URL
for SlackTitle
,Message
,Image URL
for MS TeamsTitle
,Message
,Image URL
for TelegramTitle
for SMSTitle
for Phone CallTitle
,Message
for EmailTitle
,Message
for push notifications
Behavioral templates
Behavioral templates control alert behaviors such as grouping, auto-resolution, and acknowledgment.
Grouping Id
: Applied to every incoming alert payload after routing. Determines how alerts are grouped.Autoresolution
: Automatically resolves alert groups with a status ofResolved by source
(conditional template).Auto acknowledge
: Automatically acknowledges alert groups with a status ofAcknowledged by source
(conditional template).Source link
: Customizes the URL link provided as the alert’s source.
Tip
As a best practice, add Playbooks, useful links, or checklists to the alert message.
Integration templates
Integration templates are applied to alerts that originated from a specific integration to define alert rendering and behavior.
Grafana OnCall provides pre-configured default Jinja templates for supported integrations. For any monitoring system not available in the Grafana OnCall integrations list, configure a Webhook integration and configure your templates as needed.
Edit templates
- Open the Integration page for the desired integration.
- Navigate to the Templates section and click Edit to see previews of all templates for the integration.
- Select the template to edit and click Edit. The template editor will open with three columns: example alert payload, the template itself, and the rendered result.
- Choose a Recent Alert group to see its latest alert payload. Click Edit to modify this payload.
- Alternatively, click Use custom payload to write your own payload and see its rendering.
- Press
Control + Enter
in the editor to view suggestions. - Click Cheatsheet in the second column for inspiration.
- For messenger templates, click Save and open Alert Group in ChatOps to see how the alert renders in the messenger. Note: The alert group must exist in the messenger to preview the template.
- Click Save to save the template.