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

Аннотации и метки в правилах оповещений можно определять с помощью обычного текста. Однако вы также можете определять шаблоны, чтобы настраивать их значения с помощью динамических данных из запросов правил оповещений.

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

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

Переменные

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

Символы $ и . используются для ссылки на переменные и их свойства. Вы можете ссылаться на переменные напрямую в определениях правил оповещений с помощью символа $, за которым следует имя переменной. Аналогично вы можете обращаться к свойствам переменных через нотацию dot (.) в шаблонах правил оповещений.

Шаблоны основаны на системе шаблонизации Go. Дополнительные сведения см. в разделе Язык шаблонов.

Следующие переменные доступны при шаблонизации аннотаций и меток:

Expand table

Переменные	Описание
$labels	Содержит все метки из запроса, только метки запроса.
$values	Содержит метки и значения с плавающей точкой всех instant-запросов и выражений, индексированные по их Ref ID.
$value	Строка, содержащая метки и значения всех instant-запросов; выражений threshold, reduce и math; и classic conditions в правиле оповещения. При использовании одного источника данных возвращает значение запроса. Обычно рекомендуется использовать $values.

$labels

Переменная $labels содержит все метки из запроса. Она исключает пользовательские и зарезервированные метки, содержая только метки запроса.

Например, предположим, у вас есть запрос, возвращающий использование CPU для всех ваших серверов, и правило оповещения, которое срабатывает, когда использование CPU на любом из ваших серверов превысило 80% за последние 5 минут. Вы хотите добавить аннотацию summary к оповещению, которая сообщает, какой сервер испытывает высокую нагрузку CPU. С переменной $labels вы можете написать шаблон, выводящий читаемое предложение, например:

Результат этого шаблона будет таким:

Если вы используете classic condition, то $labels не будет содержать никаких меток из запроса. Classic conditions отбрасывают эти метки, чтобы обеспечить одномерное поведение (не более одного оповещения на правило оповещения). Если вы хотите использовать метки из запроса в вашем шаблоне, используйте пример здесь.

$values

Переменная $values — это таблица, содержащая метки и значения с плавающей точкой всех instant-запросов и выражений, индексированные по их Ref ID (например, A, B, C и т. д.). Она не содержит результаты range-запросов, так как они могут возвращать сотни или тысячи строк.

Каждый Ref ID, такой как $values.A, имеет следующие свойства

Expand table

Свойство	Тип	Описание
Value	Float	Значение, возвращённое instant-запросом или выражением.
Labels	Key/value pairs	Метки, связанные с instance-запросом или выражением.

Вот предыдущий пример, теперь выводящий значение instant-запроса с Ref ID A:

Если у оповещения есть метка instance=server1 и запрос возвращает 81.2345, шаблон выведет:

Если запрос в Ref ID A — это range-запрос, а не instant-запрос, то добавьте выражение reduce с Ref ID B и замените $values.A.Value на $values.B.Value:

В качестве альтернативы вы можете использовать функцию index() для получения значения запроса:

$value

Переменная $value — это строка, содержащая метки и значения всех instant-запросов; выражений threshold, reduce и math; и classic conditions в правиле оповещения.

Когда в правиле оповещения используется один источник данных, $value возвращает значение запроса напрямую.

Этот пример выводит переменную $value:

При использовании нескольких источников данных он отобразит что-то вроде этого:

Но с одним источником данных он отобразит только значение запроса:

Вместо этого мы рекомендуем использовать $values, которая содержит ту же информацию, что и $value, но структурирована в более удобном для использования табличном формате.

Функции

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

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

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

Числа

Expand table

Имя	Аргументы	Возвращает	Описание
humanize	number or string	string	Гуманизирует десятичные числа.
humanize1024	number or string	string	Как humanize, но использует 1024 в качестве основания вместо 1000.
humanizeDuration	number or string	string	Гуманизирует длительность в секундах.
humanizePercentage	number or string	string	Гуманизирует значение отношения в проценты.
humanizeTimestamp	number or string	string	Гуманизирует Unix-метку времени.
toTime	number or string	time	Преобразует Unix-метку времени в секундах во время.

Строки

Expand table

Имя	Аргументы	Возвращает	Описание
title	string	string	Делает первую букву каждого слова заглавной.
toUpper	string	string	Возвращает весь текст в верхнем регистре.
toLower	string	string	Возвращает весь текст в нижнем регистре.
stripPort	string	string	Возвращает только хост.
match	pattern, text	boolean	Сопоставляет текст с шаблоном регулярного выражения.
reReplaceAll	pattern, replacement, text	string	Заменяет текст, соответствующий регулярному выражению.
graphLink	expr	string	Возвращает путь к графическому представлению в Explore для заданного выражения и источника данных.
tableLink	expr	string	Возвращает путь к табличному представлению в Explore для заданного выражения и источника данных.
parseDuration	string	float	Разбирает строку длительности, например “1h”, в количество секунд, которое она представляет.
stripDomain	string	string	Возвращает результат удаления части домена из FQDN.

Прочее

Expand table

Имя	Аргументы	Возвращает	Описание
args	[]interface{}	map[string]interface{}	Преобразует список объектов в карту с ключами arg0, arg1 и т. д.
safeHtml	string	string	Помечает строку как HTML, не требующий автоэкранирования.
externalURL	none	string	Возвращает внешний URL сервера Grafana, как настроено в ini-файле(ах).
pathPrefix	none	string	Возвращает путь сервера Grafana, как настроено в ini-файле(ах).

Для дополнительного контекста об этих функциях: шаблонизация в Grafana основана на реализации шаблонов Prometheus, что позволяет использовать эти функции и шаблоны, похожие на Prometheus, для форматирования сообщений оповещений в Grafana.

humanize

Функция humanize гуманизирует десятичные числа:

humanize1024

Функция humanize1024 работает подобно humanize, но использует 1024 в качестве основания вместо 1000:

humanizeDuration

Функция humanizeDuration гуманизирует длительность в секундах:

humanizePercentage

Функция humanizePercentage гуманизирует значение отношения от 0 до 1 в проценты:

humanizeTimestamp

Функция humanizeTimestamp гуманизирует Unix-метку времени:

toTime

Функция toTime преобразует Unix-метку времени в секундах во время:

title

Функция title делает первую букву каждого слова заглавной:

toUpper

Функция toUpper возвращает весь текст в верхнем регистре:

toLower

Функция toLower возвращает весь текст в нижнем регистре:

stripPort

Функция stripPort разделяет строку на хост и порт, затем возвращает только хост:

match

Функция match сопоставляет текст с шаблоном регулярного выражения:

reReplaceAll

Функция reReplaceAll заменяет текст, соответствующий регулярному выражению:

graphLink

Функция graphLink возвращает путь к графическому представлению в Explore для заданного выражения и источника данных:

parseDuration

Функция parseDuration разбирает строку длительности, например “1h”, в количество секунд, которое она представляет.

stripDomain

Функция stripDomain удаляет часть домена из FQDN, оставляя порт нетронутым:

tableLink

Функция tableLink возвращает путь к табличному представлению в Explore для заданного выражения и источника данных:

args

Функция args преобразует список объектов в карту с ключами arg0, arg1 и т. д. Это предназначено для передачи нескольких аргументов в шаблоны:

safeHtml

Функция safeHtml помечает строку как HTML, не требующий автоэкранирования:

externalURL

Функция externalURL возвращает внешний URL сервера Grafana, как настроено в ini-файле(ах):

pathPrefix

Функция pathPrefix возвращает путь сервера Grafana, как настроено в ini-файле(ах):

Отличия от шаблонов уведомлений

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

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

Например, шаблоны уведомлений предоставляют переменную .Alerts, которая включает список всех сработавших и разрешившихся оповещений в уведомлении. Эта переменная недоступна в шаблонах правил оповещений, которые работают в контексте одного экземпляра оповещения.

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