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>
This commit is contained in:
Pepe Cano
co-authored by
Matthew Jacobson
Matthew Jacobson
parent
9a8555dead
commit
f36d5c5206
@@ -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.
|
||||
|
||||
@@ -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