diff --git a/docs/sources/alerting/configure-notifications/template-notifications/examples.md b/docs/sources/alerting/configure-notifications/template-notifications/examples.md index 7e916c5f60a..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,11 @@ 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 @@ -347,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 @@ -408,6 +413,75 @@ Execute the template by passing the dot (`.`): [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. diff --git a/docs/sources/alerting/configure-notifications/template-notifications/reference.md b/docs/sources/alerting/configure-notifications/template-notifications/reference.md index d9d5cc75fa4..02cd0f92770 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: