apitech
/
grafana
mirror of https://github.com/grafana/grafana
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[release-12.0.2] docs(alerting): new notification template example: link to a dashboard with time range (#106292)

Browse Source 
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>
pull/106300/head
Pepe Cano 3 weeks ago committed by GitHub
parent 2a102f5b98
commit febbfb1902
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 145 additions and 12 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 141
      docs/sources/alerting/configure-notifications/template-notifications/examples.md
  2. 6
      docs/sources/alerting/configure-notifications/template-notifications/reference.md

141
docs/sources/alerting/configure-notifications/template-notifications/examples.md
Unescape View File

@ -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"
}
```

6
docs/sources/alerting/configure-notifications/template-notifications/reference.md
Unescape View File

@ -111,9 +111,9 @@ 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. |
| -------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |

Write Preview
Loading…
Cancel
Save