Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Оповещенияbreadcrumb arrow Настройка уведомленийbreadcrumb arrow Шаблонизация уведомленийbreadcrumb arrow Template reference

Справочник по шаблонам уведомлений

По умолчанию Grafana предоставляет предопределённые шаблоны для форматирования уведомительных сообщений.

Вы также можете настраивать свои уведомления с помощью пользовательских шаблонов, основанных на языке шаблонов Go.

Эта документация перечисляет данные, доступные для использования в шаблонах уведомлений.

Notification Data

В шаблонах уведомлений dot (.) инициализируется следующими данными:

Имя Тип Описание
Receiver string Имя точки контакта, отправляющей уведомление
Status string Статус — firing, если хотя бы одно оповещение срабатывает, иначе resolved.
Alerts []Alert Список всех сработавших и разрешившихся оповещений в этом уведомлении.
Alerts.Firing []Alert Список всех сработавших оповещений в этом уведомлении.
Alerts.Resolved []Alert Список всех разрешившихся оповещений в этом уведомлении.
GroupLabels KV Метки, группирующие эти оповещения в этом уведомлении на основе опции Group by.
CommonLabels KV Метки, общие для всех оповещений в этом уведомлении.
CommonAnnotations KV Аннотации, общие для всех оповещений в этом уведомлении.
ExternalURL string Ссылка на Grafana или на Alertmanager, отправивший это уведомление, если используется внешний Alertmanager.
GroupKey string Ключ, используемый для идентификации этой группы оповещений.
TruncatedAlerts integer Количество оповещений, если таковые были, усечённых в уведомлении. Поддерживается Webhook и OnCall.

Важно помнить, что одно уведомление может группировать несколько оповещений, чтобы сократить количество получаемых уведомлений. Alerts — это массив, включающий все оповещения в уведомлении.

Вот пример, выводящий все доступные данные уведомления из dot (.):

Go 
{{ define "custom_template" }}
  {{ .Receiver }}
  {{ .Status }}
  There are {{ len .Alerts }} alerts
  There are {{ len .Alerts.Firing }} firing alerts
  There are {{ len .Alerts.Resolved }} resolved alerts
  {{ .GroupLabels }}
  {{ .CommonLabels }}
  {{ .CommonAnnotations }}
  {{ .ExternalURL }}
{{ end }}

Вы можете выполнить этот шаблон, передав dot (.):

Go 
{{ template "custom_template" . }}

Alert

Alert содержит данные об отдельном оповещении:

Имя Тип Описание
Status string Firing или resolved.
Labels KV Метки, связанные с этим оповещением.
Включает все типы меток, но только метки запроса, использованные в условии оповещения.
Annotations KV Аннотации для этого оповещения.
StartsAt Time Время срабатывания оповещения
EndsAt Time Устанавливается только если известно время окончания оповещения. Иначе устанавливается в настраиваемый период тайм-аута с момента получения последнего оповещения.
GeneratorURL string Ссылка на Grafana или на источник оповещения, если используется внешний генератор оповещений.
Fingerprint string Уникальная строка, идентифицирующая оповещение.

Grafana-managed оповещения включают следующие дополнительные свойства:

Имя Тип Описание
DashboardURL string Ссылка на дашборд Grafana, если у оповещения есть аннотация Dashboard UID, с временным диапазоном от 1h до начала оповещения по конец (или сейчас, если срабатывает).
PanelURL string Ссылка на панель, если у оповещения есть аннотация Panel ID, с временным диапазоном от 1h до начала оповещения по конец (или сейчас, если срабатывает).
SilenceURL string Ссылка для отключения оповещения.
Values KV Значения выражений, использованных для вычисления условия оповещения. Включаются только релевантные значения.
ValueString string Строка, содержащая метки и значение каждого приведённого выражения в оповещении.
OrgID integer ID организации — владельца оповещения.

Этот пример итерируется по списку сработавших и разрешившихся оповещений (.Alerts) в уведомлении и выводит данные для каждого оповещения:

Go 
{{ define "custom_template" }}
{{ range .Alerts }}
  {{ .Status }}
  {{ .Labels }}
  {{ .Annotations }}
  {{ .StartsAt }}
  {{ .EndsAt }}
  {{ .GeneratorURL }}
  {{ .Fingerprint }}

  {{/* Only available for Grafana-managed alerts */}}
  {{ .DashboardURL }}
  {{ .PanelURL }}
  {{ .SilenceURL }}
  {{ .Values }}
  {{ .ValueString }}
{{ end }}
{{ end }}

Вы можете запустить этот шаблон, передав dot (.):

Go 
{{ template "custom_template" . }}

KV

KV — это набор пар ключ-значение, где каждый ключ и значение — строка.

Подобно доступу к свойствам переменных, вы можете использовать . для получения значения. Например:

Go 
{{ define "custom_template" }}
  {{ .CommonLabels.grafana_folder }}
{{ end }}

Если KV содержит числа или булевы значения, то это строковые представления числового или булева значения.

Кроме того, KV предоставляет методы для сортировки пар, удаления ключей и итерации только по ключам или значениям:

Имя метода Описание Аргументы Возвращает
SortedPairs Возвращает отсортированный список пар ключ/значение. Pairs
Remove Возвращает копию KV с удалёнными ключами []string KV
Names Возвращает имена меток []string
Values Возвращает список значений []string

Вот пример использования этих методов:

Go 
{{ define "custom_template" }}
  {{ .CommonLabels.SortedPairs }}
  {{ .CommonLabels.Names }}
  {{ .CommonLabels.Values }}
  {{ .CommonLabels.Remove (stringSlice "grafana_folder") }}
{{ end }}

Time

Некоторые функции шаблонов и свойства возвращают объект Time, который относится к типу Time в пакете time языка Go.

При доступе к объекту Time вы можете использовать различные функции Time в ваших шаблонах следующим образом.

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 }}

Функции

Функции могут выполнять в шаблонах такие действия, как преобразование или форматирование данных.

Обратите внимание, что доступны функции, предоставляемые языком шаблонов Go, такие как index, and, printf и len, а также многие другие.

Кроме того, для шаблонизации уведомлений также доступны следующие функции:

Имя Аргументы Возвращает Описание
title string string Делает первую букву каждого слова заглавной.
toUpper string string Возвращает весь текст в верхнем регистре.
toLower string string Возвращает весь текст в нижнем регистре.
trimSpace string string Удаляет ведущие и завершающие пробельные символы.
match pattern, text boolean Сопоставляет текст с шаблоном регулярного выражения.
reReplaceAll pattern, replacement, text string Заменяет текст, соответствующий регулярному выражению.
join sep string, s []string string Объединяет элементы s в одну строку. Строка-разделитель sep помещается между элементами в результирующей строке.
safeHtml string string Помечает строку как HTML, не требующий автоэкранирования.
stringSlice …string string Возвращает переданные строки как срез строк. auto-escaping.
date string, Time string Форматирует время в указанном формате. Опции формата см. в документации по формату времени Go.
tz string, Time Time Возвращает время в указанном часовом поясе, таком как Europe/Paris. Доступные варианты часовых поясов см. в списке часовых поясов базы данных tz.

Вот пример использования некоторых функций для форматирования текста:

Go 
{{ define "custom_template" }}
  {{ title "hello, world!" }}
  {{ toUpper "Hello, world!" }}
  {{ toLower "Hello, world!" }}
  {{ trimSpace "Hello, world!" }}
  {{ match "a.*" "abc" }}
  {{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }}
  {{ join "-" (stringSlice "a" "b" "c") }}
  {{ safeHtml "<b>Text</b>"}}
  {{ stringSlice "a" "b" "c" }}
{{ end }}

date и tz могут форматировать время. Например, чтобы вывести время срабатывания оповещения в формате 15:04:05 MST:

Go 
{{ define "custom_template" }}
  {{ range .Alerts }}
    {{ .StartsAt | date "15:04:05 MST" }}
  {{ end}}
{{ end }}

Затем вы можете использовать tz, чтобы изменить часовой пояс с UTC на местное время, такое как Europe/Paris.

Go 
{{ define "custom_template" }}
  {{ range .Alerts }}
    {{ .StartsAt | tz "Europe/Paris" }}
    {{ .StartsAt | tz "Europe/Paris" | date "15:04:05 MST" }}
  {{ end}}
{{ end }}
template-output 
2024-10-30 21:01:45.227 +0100 CET
21:01:45 CET

Namespaced Functions

Note

Namespaced Functions пока не является общедоступной функцией в Grafana Cloud.

Помимо функций верхнего уровня, также доступны следующие namespaced functions:

Функции коллекций

Имя Аргументы Возвращает Описание
coll.Dict key string, value any, … map Создаёт карту со строковыми ключами из пар ключ/значение. Все ключи преобразуются в строки. Если передано нечётное число аргументов, у последнего ключа значение будет пустой строкой.
coll.Slice …any []any Создаёт срез (массив/список) из предоставленных аргументов. Полезно для создания списков, по которым можно итерироваться с помощью range.
coll.Append value any, list []any []any Создаёт новый список, добавляя значение в конец существующего списка. Не изменяет исходный список.

Пример использования функций коллекций:

Go 
{{ define "collection.example" }}
{{- /* Create a dictionary of alert metadata */ -}}
{{- $metadata := coll.Dict
    "severity" "critical"
    "team" "infrastructure"
    "environment" "production"
-}}

{{- /* Create a slice of affected services */ -}}
{{- $services := coll.Slice "database" "cache" "api" -}}

{{- /* Append a new service to the list */ -}}
{{- $services = coll.Append "web" $services -}}

{{- /* Use the collections in a template */ -}}
Affected Services: {{ range $services }}{{ . }},{{ end }}

Alert Metadata:
{{- range $k, $v := $metadata }}
  {{ $k }}: {{ $v }}
{{- end }}
{{ end }}

Вывод:

Affected Services: database,cache,api,web,

Alert Metadata:
  environment: production
  severity: critical
  team: infrastructure

Функции данных

Имя Аргументы Возвращает Описание
data.JSON jsonString string any Разбирает строку JSON в объект, которым можно манипулировать в шаблоне. Работает как с объектами JSON, так и с массивами.
data.ToJSON obj any string Сериализует любой объект (карты, массивы и т. д.) в строку JSON. Полезно для создания полезных нагрузок webhook.
data.ToJSONPretty indent string, obj any string Создаёт строковое представление объекта в виде JSON с отступами. Первый аргумент задаёт строку отступа (например, пробелы).

Пример использования функций данных:

Go 
{{ define "data.example" }}
{{- /* First, let's create some alert data as a JSON string */ -}}
{{ $jsonString := `{
  "service": {
    "name": "payment-api",
    "environment": "production",
    "thresholds": {
      "error_rate": 5,
      "latency_ms": 100
    }
  }
}` }}

{{- /* Parse the JSON string into an object we can work with */ -}}
{{ $config := $jsonString | data.JSON }}

{{- /* Create a new alert payload */ -}}
{{ $payload := coll.Dict
    "service" $config.service.name
    "environment" $config.service.environment
    "status" .Status
    "errorThreshold" $config.service.thresholds.error_rate
}}

{{- /* Output the payload in different JSON formats */ -}}
Compact JSON: {{ $payload | data.ToJSON }}

Pretty JSON with 2-space indent:
{{ $payload | data.ToJSONPretty "  " }}
{{ end }}

Вывод:

Compact JSON: {"environment":"production","errorThreshold":5,"service":"payment-api","status":"resolved"}

Pretty JSON with 2-space indent:
{
  "environment": "production",
  "errorThreshold": 5,
  "service": "payment-api",
  "status": "resolved"
}

Функции шаблонов

Имя Аргументы Возвращает Описание
tmpl.Exec name string, [context any] string Выполняет именованный шаблон и возвращает результат как строку. Похоже на действие template, но позволяет выполнять постобработку результата.
tmpl.Inline template string, context any string Рендерит строку как шаблон.
Go 
{{ define "template.example" -}}
{{ coll.Dict
    "info" (tmpl.Exec `info` . | data.JSON)
    "severity" (tmpl.Inline `{{ print "critical" | toUpper }}` . )
    | data.ToJSONPretty " "}}
{{- end }}

{{- /* Define a sub-template */ -}}
{{ define "info" -}}
{{coll.Dict
    "team" "infrastructure"
    "environment" "production" | data.ToJSON }}
{{- end }}

Вывод:

JSON 
{
  "info": {
    "environment": "production",
    "team": "infrastructure"
  },
  "severity": "CRITICAL"
}

Функции времени

Имя Аргументы Возвращает Описание
time.Now Time Возвращает текущее местное время как объект time.Time. Может быть отформатировано с помощью функций форматирования времени Go.

Пример использования функций времени:

Go 
{{ define "time.example" }}
{{- /* Get current time in different formats */ -}}
Current Time (UTC): {{ (time.Now).UTC.Format "2006-01-02 15:04:05 MST" }}
Current Time (Local): {{ (time.Now).Format "Monday, January 2, 2006 at 15:04:05" }}

{{- /* Compare alert time with current time */ -}}
{{ $timeAgo := (time.Now).Sub .StartsAt }}
Alert fired: {{ $timeAgo }} ago
{{ end }}

Вывод:

Current Time (UTC): 2025-03-08 18:14:27 UTC
Current Time (Local): Saturday, March 8, 2025 at 14:14:27
Alert fired: 25h49m32.78574723s ago

Отличия от шаблонов аннотаций и меток

В правиле оповещения вы также можете шаблонизировать аннотации и метки, чтобы включать дополнительную информацию. Например, вы можете добавить аннотацию summary, отображающую значение запроса, вызывающее срабатывание оповещения.

Шаблоны аннотаций и меток добавляют релевантную информацию к отдельным экземплярам оповещений, тогда как шаблоны уведомлений информируют о группе экземпляров оповещений.

Поскольку оба типа шаблонов работают в разных контекстах, функции и переменные, доступные в шаблонах аннотаций и меток, отличаются от используемых в шаблонах уведомлений.