diff --git a/docs/sources/alerting/configure-notifications/template-notifications/examples.md b/docs/sources/alerting/configure-notifications/template-notifications/examples.md index d9ce3f780a0..c94de3628a8 100644 --- a/docs/sources/alerting/configure-notifications/template-notifications/examples.md +++ b/docs/sources/alerting/configure-notifications/template-notifications/examples.md @@ -55,6 +55,16 @@ refs: destination: /docs/grafana//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//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//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="" >}} + +```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" +} +``` diff --git a/docs/sources/alerting/configure-notifications/template-notifications/reference.md b/docs/sources/alerting/configure-notifications/template-notifications/reference.md index 665e15857c9..6d9784a524c 100644 --- a/docs/sources/alerting/configure-notifications/template-notifications/reference.md +++ b/docs/sources/alerting/configure-notifications/template-notifications/reference.md @@ -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: