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

Co-authored-by: Matthew Jacobson <matthew.jacobson@grafana.com>

---------

Co-authored-by: Matthew Jacobson <matthew.jacobson@grafana.com>

docs/sources/alerting/configure-notifications/template-notifications/examples.md

@@ -55,6 +55,11 @@ 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
@@ -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.

docs/sources/alerting/configure-notifications/template-notifications/reference.md

@@ -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.                                                                 |