Аннотации Loki

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

Прежде чем начать

Прежде чем создавать аннотации Loki, убедитесь, что у вас есть:

Настроенный источник данных Loki.
Запрос журналов LogQL, возвращающий события, которые вы хотите аннотировать.

Как работают аннотации Loki

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

В качестве источника для аннотаций можно использовать только запросы журналов. Метрические запросы не поддерживаются.

Создание запроса аннотаций

Чтобы добавить аннотацию Loki на дашборд:

Откройте дашборд, на который хотите добавить аннотации.
Нажмите Edit, затем нажмите Settings в верхней панели навигации.
Выберите вкладку Annotations.
Нажмите Add annotation query.
Введите Name для аннотации, например Deploy events.
Выберите ваш источник данных Loki.
Введите запрос журналов LogQL и настройте необязательные поля, описанные в следующей таблице.
Нажмите Save dashboard.

Редактор запросов аннотаций предоставляет следующие поля:

Поле	Описание
Query	Запрос журналов LogQL, который выбирает строки журнала для аннотирования.
Title	Необязательно. Буквенное имя или шаблон для заголовка аннотации. Ссылайтесь на метки через `{{label}}`, например `{{level}}`.
Tags	Необязательно. Список ключей меток через запятую, которые нужно использовать как теги аннотации, например `app,level`. Если пусто, Grafana использует метки потока журнала как теги.
Text	Необязательно. Буквенная строка или шаблон для текста аннотации. Ссылайтесь на метки через `{{label}}`. Если пусто, Grafana использует содержимое строки журнала как текст.

Шаблонные поля раскрываются по меткам каждой возвращённой строки журнала, включая разобранные поля. Чтобы сослаться на значение, которое не является индексированной меткой, добавьте в запрос парсер, например logfmt или json, чтобы поле стало доступным.

Пример

Чтобы аннотировать события развёртывания, настройте запрос аннотаций со следующими значениями:

Поле	Значение
Query	`{app="deploy-bot"} \|= "deployed"`
Title	`{{app}} deployed`
Tags	`app,env`
Text	`{{message}}`

Каждая совпадающая строка журнала становится аннотацией с заголовком, содержащим развёртывающее приложение, с тегами меток app и env и описанием из разобранного поля message. Поскольку шаблон Text ссылается на разобранное поле, запросу нужен парсер, например:

{app="deploy-bot"} |= `deployed` | logfmt

Устранение неполадок с аннотациями

Если аннотации не отображаются как ожидается, попробуйте следующие решения.

Аннотации не отображаются

Убедитесь, что запрос журналов возвращает результаты в Explore за тот же диапазон времени. Аннотации берутся из возвращённых строк журнала, поэтому запрос, не возвращающий журналов, не даёт аннотаций.
Убедитесь, что запрос является запросом журналов, а не метрическим запросом.
Расширьте диапазон времени дашборда, чтобы он включал ожидаемые события журнала.

Появляется слишком много аннотаций

Добавьте в запрос LogQL фильтры меток или фильтр строк, чтобы сузить возвращаемые строки журнала.
Уменьшите максимальное количество строк, возвращаемых запросом.