[release-12.0.2] docs(alerting): new notification template example: link to a dashboard with time range (#106292)
docs(alerting): new notification template example: link to a dashboard with time range (#106254)
* docs(alerting): new notification template example: link to a dashboard with time range
* remind configuring the `MyDashboardURL` annotation
* Update docs/sources/alerting/configure-notifications/template-notifications/examples.md
---------
(cherry picked from commit f36d5c5206)
Co-authored-by: Matthew Jacobson <matthew.jacobson@grafana.com>
This commit is contained in:
Pepe Cano
co-authored by
Matthew Jacobson
Matthew Jacobson
parent
2a102f5b98
commit
febbfb1902
@@ -55,6 +55,16 @@ refs:
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/fundamentals/notifications/group-alert-notifications/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/notifications/group-alert-notifications/
|
||||
link-alert-rules-to-panels:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/alerting-rules/link-alert-rules-to-panels/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/alerting-and-irm/alerting/alerting-rules/link-alert-rules-to-panels/
|
||||
custom-payload-webhook:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/#custom-payload
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/#custom-payload
|
||||
---
|
||||
|
||||
# Notification template examples
|
||||
@@ -342,16 +352,16 @@ Pass the dot (`.`) to execute the template:
|
||||
```template_output
|
||||
1 resolved alert(s)
|
||||
|
||||
- Dashboard: https://example.com/d/
|
||||
- Panel: https://example.com/d/
|
||||
- Dashboard: https://example.com/d/uiyahbsdaubsd?from=1740070380000&orgId=1&to=1740074106395
|
||||
- Panel: https://example.com/d/uiyahbsdaubsd?from=1740070380000&orgId=1&to=1740074106395&viewPanel=31
|
||||
- AlertGenerator: ?orgId=1
|
||||
- Silence: https://example.com/alerting/silence/new
|
||||
- RunbookURL: https://example.com/on-call/db_server_disk_space
|
||||
|
||||
1 firing alert(s)
|
||||
|
||||
- Dashboard: https://example.com/d/
|
||||
- Panel: https://example.com/d/
|
||||
- Dashboard: https://example.com/d/uiyahbsdaubsd?from=1740070380000&orgId=1&to=1740074106395
|
||||
- Panel: https://example.com/d/uiyahbsdaubsd?from=1740070380000&orgId=1&to=1740074106395&viewPanel=31
|
||||
- AlertGenerator: ?orgId=1
|
||||
- Silence: https://example.com/alerting/silence/new
|
||||
- RunbookURL: https://example.com/on-call/web_server_http_errors
|
||||
@@ -402,3 +412,126 @@ Execute the template by passing the dot (`.`):
|
||||
```template_output
|
||||
[FIRING:1, RESOLVED:1] api warning (sql_db)
|
||||
```
|
||||
|
||||
## Print a link to a dashboard with time range
|
||||
|
||||
You can include a link to a dashboard or panel in your alert notifications. This is useful when the alert rule is created from a dashboard panel or monitors a target visualized in an existing dashboard.
|
||||
|
||||
Including a dashboard link in the notification helps responders quickly navigate to the relevant context for investigation.
|
||||
|
||||
Use one of the following methods to include a dashboard link with the correct time range in the alert notification:
|
||||
|
||||
1. You can [link the alert rule to a panel](ref:link-alert-rules-to-panels). This includes the dashboard and panel URLs via `{{.Alert.DashboardURL}}` and `{{.Alert.PanelURL}}`.
|
||||
|
||||
```go
|
||||
{{ define "custom.link_to_dashboard" -}}
|
||||
{{ range .Alerts -}}
|
||||
Dashboard: {{.DashboardURL}}
|
||||
Panel: {{ .PanelURL }}
|
||||
{{ end -}}
|
||||
{{ end -}}
|
||||
```
|
||||
|
||||
Run the template using:
|
||||
|
||||
```go
|
||||
{{ template "custom.link_to_dashboard" . }}
|
||||
```
|
||||
|
||||
```template_output
|
||||
Dashboard: https://example.com/d/uiyahbsdaubsd?from=1740070380000&orgId=1&to=1740074106395
|
||||
Panel: https://example.com/d/uiyahbsdaubsd?from=1740070380000&orgId=1&to=1740074106395&viewPanel=31
|
||||
```
|
||||
|
||||
These URLs include a time range based on the alert’s timing:
|
||||
|
||||
- `from`: One hour before the alert started.
|
||||
- `to`: The current time if the alert is firing, or the alert’s end time if resolved.
|
||||
|
||||
1. Alternatively, you can use a custom annotation to set the dashboard URL and build the full URL using the `from` and `to` query parameters derived from `{{.Alert.StartsAt}}` and `{{.Alert.EndsAt}}`.
|
||||
|
||||
```go
|
||||
{{ define "custom.my_dashboard_url_annotation" -}}
|
||||
{{ range .Alerts -}}
|
||||
|
||||
{{/* StartsAt - 1h */}}
|
||||
{{- $from := (.StartsAt.Add -3600000000000).UnixMilli }}
|
||||
|
||||
{{- $to := "" }}
|
||||
{{- if eq .Status "resolved" }}
|
||||
{{- $to = (.EndsAt).UnixMilli }}
|
||||
{{- else -}}
|
||||
{{/* Use current time if alert is firing */}}
|
||||
{{- $to = (time.Now).UnixMilli }}
|
||||
{{- end -}}
|
||||
|
||||
Dashboard: {{.Annotations.MyDashboardURL}}?from={{$from}}&to={{$to}}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
To use this template, define a custom annotation named `MyDashboardURL` that contains the base dashboard URL without `from` and `to` parameters. For example: `http://localhost:3000/d/uiyahbsdaubsd`.
|
||||
|
||||
Run the template using:
|
||||
|
||||
```go
|
||||
{{ template "custom.my_dashboard_url_annotation" . }}
|
||||
```
|
||||
|
||||
```template_output
|
||||
Dashboard: http://localhost:3000/d/uiyahbsdaubsd?from=1740070380000&to=1740071880000
|
||||
```
|
||||
|
||||
## Custom JSON payload
|
||||
|
||||
The [custom payload option](ref:custom-payload-webhook) in the webhook contact point allows you to customize the payload of webhook notifications using a custom template.
|
||||
|
||||
The following example generates a custom JSON payload by executing other templates with `tmpl.Exec`, and using functions like `coll.Dict` and `data.ToJSON` to process and format JSON data.
|
||||
|
||||
{{< docs/shared lookup="alerts/example-custom-json-payload.md" source="grafana" version="<GRAFANA_VERSION>" >}}
|
||||
|
||||
```template_output
|
||||
{
|
||||
"alerts": [
|
||||
{
|
||||
"endsAt": "0001-01-01T00:00:00Z",
|
||||
"labels": {
|
||||
"alertname": "InstanceDown",
|
||||
"grafana_folder": "Test Folder",
|
||||
"instance": "instance1"
|
||||
},
|
||||
"startsAt": "2025-04-21T10:19:46.179Z",
|
||||
"status": "firing"
|
||||
},
|
||||
{
|
||||
"endsAt": "2025-04-22T10:19:46.179Z",
|
||||
"labels": {
|
||||
"alertname": "CpuUsage",
|
||||
"grafana_folder": "Test Folder",
|
||||
"instance": "instance1"
|
||||
},
|
||||
"startsAt": "2025-04-22T06:19:46.179Z",
|
||||
"status": "resolved"
|
||||
}
|
||||
],
|
||||
"allVariables": {},
|
||||
"commonAnnotations": {},
|
||||
"commonLabels": {
|
||||
"grafana_folder": "Test Folder",
|
||||
"instance": "instance1"
|
||||
},
|
||||
"externalURL": "http://localhost:3000/",
|
||||
"groupKey": "",
|
||||
"groupLabels": {
|
||||
"group_label": "group_label_value"
|
||||
},
|
||||
"message": "**Firing**\n\nValue: B=22, C=1\nLabels:\n - alertname = InstanceDown\n - grafana_folder = Test Folder\n - instance = instance1\nAnnotations:\n - summary = Instance instance1 has been down for more than 5 minutes\nSource: http://grafana.com/alerting/grafana/cdeqmlhvflz40f/view?orgId=1\nSilence: http://localhost:3000/alerting/silence/new?alertmanager=grafana\u0026matcher=alertname%3DInstanceDown\u0026matcher=grafana_folder%3DTest+Folder\u0026matcher=instance%3Dinstance1\u0026orgId=1\nDashboard: http://localhost:3000/d/dashboard_uid?from=1745227186179\u0026orgId=1\u0026to=1745317189058\nPanel: http://localhost:3000/d/dashboard_uid?from=1745227186179\u0026orgId=1\u0026to=1745317189058\u0026viewPanel=1\n\n\n**Resolved**\n\nValue: B=22, C=1\nLabels:\n - alertname = CpuUsage\n - grafana_folder = Test Folder\n - instance = instance1\nAnnotations:\n - summary = CPU usage above 90%\nSource: http://grafana.com/alerting/grafana/oZSMdGj7z/view?orgId=1\nSilence: http://localhost:3000/alerting/silence/new?alertmanager=grafana\u0026matcher=alertname%3DCpuUsage\u0026matcher=grafana_folder%3DTest+Folder\u0026matcher=instance%3Dinstance1\u0026orgId=1\nDashboard: http://localhost:3000/d/dashboard_uid?from=1745299186179\u0026orgId=1\u0026to=1745317186179\nPanel: http://localhost:3000/d/dashboard_uid?from=1745299186179\u0026orgId=1\u0026to=1745317186179\u0026viewPanel=1\n",
|
||||
"orgId": 1,
|
||||
"receiver": "TestReceiver",
|
||||
"state": "alerting",
|
||||
"status": "firing",
|
||||
"title": "[FIRING:1, RESOLVED:1] group_label_value (Test Folder instance1)",
|
||||
"truncatedAlerts": null,
|
||||
"version": "1"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -110,14 +110,14 @@ You can execute this template by passing the dot (`.`):
|
||||
|
||||
Grafana-managed alerts include these additional properties:
|
||||
|
||||
| Name | Type | Description |
|
||||
| -------------- | --------- | -------------------------------------------------------------------------------------------------- |
|
||||
| `DashboardURL` | string | A link to the Grafana Dashboard if the alert has a Dashboard UID annotation. |
|
||||
| `PanelURL` | string | A link to the panel if the alert has a Panel ID annotation. |
|
||||
| `SilenceURL` | string | A link to silence the alert. |
|
||||
| `Values` | [KV](#kv) | The values of expressions used to evaluate the alert condition. Only relevant values are included. |
|
||||
| `ValueString` | string | A string that contains the labels and value of each reduced expression in the alert. |
|
||||
| `OrgID` | integer | The ID of the organization that owns the alert. |
|
||||
| Name | Type | Description |
|
||||
| -------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `DashboardURL` | string | A link to the Grafana Dashboard if the alert has a Dashboard UID annotation, with time range from `1h` before alert start to end (or now if firing). |
|
||||
| `PanelURL` | string | A link to the panel if the alert has a Panel ID annotation, with time range from `1h` before alert start to end (or now if firing). |
|
||||
| `SilenceURL` | string | A link to silence the alert. |
|
||||
| `Values` | [KV](#kv) | The values of expressions used to evaluate the alert condition. Only relevant values are included. |
|
||||
| `ValueString` | string | A string that contains the labels and value of each reduced expression in the alert. |
|
||||
| `OrgID` | integer | The ID of the organization that owns the alert. |
|
||||
|
||||
This example iterates over the list of firing and resolved alerts (`.Alerts`) in the notification and prints the data for each alert:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user