Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
Jinja2 templating
Grafana OnCall can integrate with any monitoring system that can send alerts via webhooks with JSON payloads. By default, webhooks deliver raw JSON payloads. When Grafana OnCall receives an alert and parses its payload, a default pre-configured alert template is applied to modify the alert payload to be more human-readable. These alert templates are customizable for any integration. Templates are also used to notify different escalation chains based on the content of the alert payload.
Alert payload
Alerts received by Grafana OnCall contain metadata as keys and values in a JSON object. The following is an example of an alert which was 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"
}
}
In Grafana OnCall every alert and alert group have the following fields:
Title
,Message
andImage Url
for each notification method (Web, Slack, Ms Teams, SMS, Phone, Email, etc.)Grouping Id
- unique identifier for each non-resolved alert groupResolved by source
Acknowledged by source
Source link
The JSON payload is converted to OnCall fields. For example:
{{ payload.title }}
->Title
{{ payload.message }}
->Message
{{ payload.imageUrl }}
->Image Url
The result is that each field of the alert in OnCall is now mapped to the JSON payload keys. This also true for the alert behavior:
{{ payload.ruleId }}
-> Grouping Id{{ 1 if payload.state == 'OK' else 0 }}
-> Resolve Signal
Grafana OnCall provides pre-configured default Jinja templates for supported
integrations. If your monitoring system is
not in the Grafana OnCall integrations list, you can create a generic webhook
integration, send an alert, and configure
your templates.
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. For more advanced customization, use Jinja templates.
Routing template
Routing Template
- used to route alerts to different Escalation Chains based on alert content (conditional template, output should beTrue
)Note: For conditional templates, the output should be
True
to be applied, for example{{ True if payload.state == 'OK' else False }}
Appearance templates
How alerts are displayed in the UI, messengers, and notifications
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 Mobile app push notifications
Behavioral templates
Grouping Id
- applied to every incoming alert payload after theRouting Template
. It can be based on time, alert content, or both. If the resulting grouping id matches an existing non-resolved alert group grouping id, the alert will be grouped accordingly. Otherwise, a new alert group will be createdAutoresolution
- used to auto-resolve alert groups with statusResolved by source
(Conditional template, output should beTrue
)Auto acknowledge
- used to auto-acknowledge alert groups with statusAcknowledged by source
(Conditional template, output should beTrue
)Source link
- Used to customize the URL link to provide as the “source” of the alert.Note: For conditional templates, the output should be
True
to be applied, for example{{ True if payload.state == 'OK' else False }}
Pro Tip: As a best practice, add Playbooks, Useful links, or Checklists to the alert message.
How to edit templates
- Open the Integration page for the integration you want to edit 1`. Click the Edit button for the Templates Section. Now you can see previews of all templates for the Integration
- Select the template you want to edit and click the Edit button to the right to the template name. The template editor will open. The first column is the example alert payload, second column is the Template itself, and third column is used to view rendered result.
- Select one of the Recent Alert groups for the integration to see its
latest alert payload
. If you want to edit this payload, click the Edit button right to the Alert Group Name. - Alternatively, you can click Use custom payload and write your own payload to see how it will be rendered
- Press
Control + Enter
in the editor to see suggestions - Click Cheatsheet in the second column to get some inspiration.
- If you edit Messenger templates, click Save and open Alert Group in ChatOps to see how the alert will be rendered in the messenger, right in the messenger (Only works for an Alert Group that exists in the messenger)
- Click Save to save the template
Advanced Jinja templates
Grafana OnCall uses the Jinja templating language to format alert groups for the Web, Slack, phone calls, SMS messages, and more. As a result, you can decide what you want to see when an alert group is triggered, as well as how it should be presented.
Jinja2 offers simple but multi-faceted functionality by using loops, conditions, functions, and more.
NOTE: Every alert from a monitoring system comes in the key/value format.
Grafana OnCall has rules about which of the keys match to: __title
, message
, image
, grouping
, and auto-resolve__
.
Loops
Monitoring systems can send an array of values. In this example, you can use Jinja to iterate and format the alert using a Grafana example:
*Values:*
{% for evalMatch in payload.evalMatches -%}
`{{ evalMatch['metric'] }}: '{{ evalMatch['value'] -}}'`{{ " " }}
{%- endfor %}
Conditions
You can add instructions if an alert comes from a specified Grafana alert rule:
{% if payload.ruleId == '1' -%}
*Alert TODOs*
1. Get acess to the container
```
kubectl port-forward service/example 3000:80
```
2. Check for the exception.
3. Open the container and reload caches.
4. Click Custom Button `Send to Jira`
{%- endif -%}
Built-in Jinja functions
Jinja2 includes built-in functions that can also be used in Grafana OnCall. For example:
{{ payload | tojson_pretty }}
Built-in functions:
abs
capitalize
trim
- You can see the full list of Jinja built-in functions on github here
Functions added by Grafana OnCall
time
- current timetojson
- dumps a structure to JSONtojson_pretty
- same as tojson, but prettifiediso8601_to_time
- converts time from iso8601 (2015-02-17T18:30:20.000Z
) to datetimedatetimeformat
- converts time from datetime to the given format (%H:%M / %d-%m-%Y
by default)datetimeformat_as_timezone
- same asdatetimeformat
, with the inclusion of timezone conversion (UTC
by default)- Usage example:
{{ payload.alerts.startsAt | iso8601_to_time | datetimeformat_as_timezone('%Y-%m-%dT%H:%M:%S%z', 'America/Chicago') }}
- Usage example:
regex_replace
- performs a regex find and replaceregex_match
- performs a regex match, returnsTrue
orFalse
- Usage example:
{{ payload.ruleName | regex_match(".*") }}
- Usage example:
b64decode
- performs a base64 string decode- Usage example:
{{ payload.data | b64decode }}
- Usage example:
parse_json
- parses a given json string to an object- Usage example:
{{ (payload.data | b64decode | parse_json).name }}
- Usage example: