[v11.3.x] Alerting docs: add Time type documentation for notification templates (#95776)
Alerting docs: add `Time` type documentation for notification templates (#95688)
* Improve `tz` and `date` docs
* Add documentation for `Time` type
(cherry picked from commit 9d937725ad)
Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com>
This commit is contained in:
grafana-delivery-bot[bot]
co-authored by
Pepe Cano
Pepe Cano
parent
693ed6dddd
commit
28f9eb3221
@@ -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. |
|
||||
| `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). |
|
||||
|
||||
| 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:
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user