Configure alert templates

Alert templates in Grafana IRM control how alert information is formatted, processed, and displayed to users. Using Jinja2 templates, you can customize how alerts appear in different notification channels and control alert behavior such as grouping and auto-resolution.

About alert templates

Grafana IRM integrates with your monitoring systems through webhooks that deliver JSON payloads. These raw payloads often contain complex data structures that aren’t immediately useful to humans. Alert templates transform these payloads into more readable formats and control how the system processes alerts.

Alert templates help you:

Format alerts for better readability across different notification channels
Customize alert appearance based on severity or source
Control alert grouping behavior
Set up auto-resolution and auto-acknowledgment criteria
Provide context and actionable information for responders

Understanding alert payloads

Before creating templates, it’s important to understand the structure of your alert payloads. All alerts in Grafana IRM contain the following standard fields:

Title - The alert name or summary
Message - Detailed information about the alert
Image Url - URL to a visual representation (graph, screenshot)
Grouping Id - Identifier used for grouping related alerts
Resolved by source - Flag indicating if the source system marked the alert as resolved
Acknowledged by source - Flag indicating if the source system acknowledged the alert
Source link - URL to the source system

Example alert payload

Here’s an example of an alert payload from Grafana Alerting:

{
  "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"
  }
}

Mapping payloads to OnCall fields

OnCall maps JSON payload keys to specific alert fields using templates. For example:

{{ payload.title }} → Title
{{ payload.message }} → Message
{{ payload.imageUrl }} → Image Url

Behavioral mappings control how alerts are processed:

{{ payload.ruleId }} → Grouping Id
{{ 1 if payload.state == 'OK' else 0 }} → Resolve Signal

Types of alert templates

Grafana IRM supports several types of templates for different purposes:

Routing templates

Routing templates determine which escalation chain handles an alert. These templates evaluate incoming alerts based on their content.

Example (route database alerts to the Database team):

{{ "database" in payload.title | lower }}

Note: Routing templates must evaluate to True for the route to be selected.

Appearance templates

Appearance templates control how alerts appear in different notification channels:

Web UI templates: Control alert display in the Grafana IRM web interface
Slack templates: Format alerts for Slack notifications
MS Teams templates: Format alerts for Microsoft Teams
Telegram templates: Format alerts for Telegram
SMS templates: Format alerts for SMS messages (title only)
Phone call templates: Format alerts for phone calls (title only)
Email templates: Format alerts for email notifications
Mobile app templates: Format alerts for the mobile app

For each notification channel, you can customize:

Title - The alert headline
Message - The detailed description
Image URL - A visual representation (where supported)

Behavioral templates

Behavioral templates control how alerts function within Grafana IRM:

Grouping Id: Determines how alerts are grouped together
Autoresolution: Controls when alerts are automatically resolved
Auto acknowledge: Controls when alerts are automatically acknowledged
Source link: Customizes the URL link to the alert source

Edit templates

To customize alert templates:

Navigate to the Integrations page and select the integration.
Scroll to the Templates section and click Edit.
Select the template type you want to modify.
The template editor provides three columns:
- Left: Example alert payload
- Middle: Template editor
- Right: Rendered result
To work with real data, select a Recent Alert group from the dropdown.
To test with custom data, click Use custom payload.
Press Control + Enter in the editor for template suggestions.
Click Cheatsheet for template examples and syntax guidance.
For chatting app templates, click Save and open Alert Group in ChatOps to preview the final result.
Click Save when finished.

Template best practices

Add context to alerts: Include links to dashboards, documentation, or runbooks.
Format for readability: Use clear headings and structured formatting.
Include actionable information: Add specific steps or commands that responders can use.
Use conditional formatting: Highlight different severity levels with appropriate formatting.
Test with real data: Always verify templates with actual alert payloads.
Keep it concise: Focus on essential information, especially for SMS and phone calls.

Example: Enhanced alert message template

{% set severity = payload.labels.severity | default('unknown') %}

**{{ payload.alertname }}**
{% if severity == 'critical' %}🔴 CRITICAL{% elif severity == 'warning' %}🟠 WARNING{% else %}ℹ️ INFO{% endif %}

**Details:**
- Service: {{ payload.labels.service | default('N/A') }}
- Instance: {{ payload.labels.instance | default('N/A') }}
- Value: {{ payload.value | default('N/A') }} {{ payload.unit | default('') }}

**Runbook:** {{ payload.annotations.runbook_url | default('No runbook available') }}

**Dashboard:** {{ payload.generatorURL | default('N/A') }}