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

Alerting docs: add `Time` type documentation for notification templates (#95688)

Browse Source 
* Improve `tz` and `date` docs

* Add documentation for `Time` type
pull/94851/head^2
Pepe Cano 1 year ago committed by GitHub
parent c490b29d34
commit 9d937725ad
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 58 additions and 32 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. 90
      docs/sources/alerting/configure-notifications/template-notifications/reference.md

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

@ -85,15 +85,15 @@ Here's an example that prints all available notification data from dot (`.`):
`Alert` contains data for an individual alert:
| Name | Type | Description |
| -------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `Status` | string | Firing or resolved. |
| `Labels` | [KV](#kv) | The labels for this alert. |
| `Annotations` | [KV](#kv) | The annotations for this alert. |
| `StartsAt` | time | The time the alert fired |
| `EndsAt` | time | Only set if the end time of an alert is known. Otherwise set to a configurable timeout period from the time since the last alert was received. |
| `GeneratorURL` | string | A link to Grafana, or the source of the alert if using an external alert generator. |
| `Fingerprint` | string | A unique string that identifies the alert. |
| Name | Type | Description |
| -------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `Status` | string | Firing or resolved. |
| `Labels` | [KV](#kv) | The labels for this alert. |
| `Annotations` | [KV](#kv) | The annotations for this alert. |
| `StartsAt` | [Time](#time) | The time the alert fired |
| `EndsAt` | [Time](#time) | Only set if the end time of an alert is known. Otherwise set to a configurable timeout period from the time since the last alert was received. |
| `GeneratorURL` | string | A link to Grafana, or the source of the alert if using an external alert generator. |
| `Fingerprint` | string | A unique string that identifies the alert. |
Grafana-managed alerts include these additional properties:
@ -162,6 +162,27 @@ Here's an example of using these methods:
{{ end }}
```
## Time
Some template functions and properties return a `Time` object, which refers to the [type `Time`](https://pkg.go.dev/time#Time) in Go's time package.
When accessing a `Time` object, you can use various [`Time` functions](https://pkg.go.dev/time#Time) in your templates as follows.
```go
{{ define "custom_template" }}
{{ range .Alerts }}
{{ .StartsAt }}
{{ .StartsAt.Add 6000000000000 }}
{{ .StartsAt.Add -6000000000000 }}
{{ .StartsAt.AddDate 1 0 0 }}
{{ .StartsAt.Year }}/{{ .StartsAt.Month }}/{{ .StartsAt.Day }}
{{ .StartsAt.Hour }}:{{ .StartsAt.Minute }}:{{ .StartsAt.Second }}
{{ .StartsAt.YearDay }}-{{ .StartsAt.Weekday }}
{{ .StartsAt.Unix }} {{ .StartsAt.UnixMilli }}
{{ end}}
{{ end }}
```
## Functions
Functions can perform actions in templates such as transforming or formatting data.
@ -170,21 +191,21 @@ Note that the [functions provided by Go's template language](ref:template-langua
In addition, the following functions are also available for templating notifications:
### Strings
| Name | Arguments | Returns | Description |
| -------------- | -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | string | string | Capitalizes the first character of each word. |
| `toUpper` | string | string | Returns all text in uppercase. |
| `toLower` | string | string | Returns all text in lowercase. |
| `trimSpace` | string | string | Removes leading and trailing white spaces. |
| `match` | pattern, text | boolean | Matches the text against a regular expression pattern. |
| `reReplaceAll` | pattern, replacement, text | string | Replaces text matching the regular expression. |
| `join` | sep string, s []string | string | Concatenates the elements of s to create a single string. The separator string sep is placed between elements in the resulting string. |
| `safeHtml` | string | string | Marks string as HTML not requiring auto-escaping. |
| `stringSlice` | ...string | string | Returns the passed strings as a slice of strings. auto-escaping. |
Here's an example of using these functions:
| Name | Arguments | Returns | Description |
| -------------- | -------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | string | string | Capitalizes the first character of each word. |
| `toUpper` | string | string | Returns all text in uppercase. |
| `toLower` | string | string | Returns all text in lowercase. |
| `trimSpace` | string | string | Removes leading and trailing white spaces. |
| `match` | pattern, text | boolean | Matches the text against a regular expression pattern. |
| `reReplaceAll` | pattern, replacement, text | string | Replaces text matching the regular expression. |
| `join` | sep string, s []string | string | Concatenates the elements of s to create a single string. The separator string sep is placed between elements in the resulting string. |
| `safeHtml` | string | string | Marks string as HTML not requiring auto-escaping. |
| `stringSlice` | ...string | string | Returns the passed strings as a slice of strings. auto-escaping. |
| `date` | string, [Time](#time) | string | Format a time in the specified format. For format options, refer to [Go's time format documentation](https://pkg.go.dev/time#pkg-constants). |
| `tz` | string, [Time](#time) | [Time](#time) | Returns the time in the specified timezone, such as `Europe/Paris`. For available timezone options, refer to the [list of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). |
Here's an example using some functions to format text:
```go
{{ define "custom_template" }}
@ -200,26 +221,31 @@ Here's an example of using these functions:
{{ end }}
```
### Time
You can format a time in a number of different formats using the `date` function.
For example, to print the time that an alert fired in the format `15:04:05 MST`:
`date` and `tz` can format times. For example, to print the time an alert fired in the format `15:04:05 MST`:
```go
{{ define "custom_template" }}
{{ with (index .Alerts 0) }}
{{ range .Alerts }}
{{ .StartsAt | date "15:04:05 MST" }}
{{ end}}
{{ end }}
```
You can also use the `tz` function to change the timezone from UTC to a local time. For example:
You can then use `tz` to change the timezone from UTC to local time, such as `Europe/Paris`.
```go
{{ .StartsAt | tz "Europe/Paris" | date "15:04:05 MST" }}
{{ define "custom_template" }}
{{ range .Alerts }}
{{ .StartsAt | tz "Europe/Paris" }}
{{ .StartsAt | tz "Europe/Paris" | date "15:04:05 MST" }}
{{ end}}
{{ end }}
```
You can find a reference for Go's time format [here](https://pkg.go.dev/time#pkg-constants).
```template-output
2024-10-30 21:01:45.227 +0100 CET
21:01:45 CET
```
## Differences with annotation and label templates

Write Preview
Loading…
Cancel
Save