Шаблонные переменные Loki

Вместо того чтобы жёстко задавать в запросах метрик такие сведения, как имена сервера, приложения и сенсора, вы можете использовать переменные. Grafana перечисляет эти переменные в раскрывающихся списках в верхней части дашборда, помогая вам изменять данные, отображаемые на дашборде. Grafana называет такие переменные шаблонными переменными (template variables).

Введение в шаблонизацию и шаблонные переменные см. в документации Шаблонизация и Добавление переменных и управление ими.

Использование переменных-запросов

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

Форма имеет следующие параметры:

Query type	Пример метки	Пример селектора потока	Возвращаемый список
Label names	Не требуется	Не требуется	Имена меток.
Label values	`label`		Значения метки `label`.
Label values	`label`	`log stream selector`	Значения метки `label` в указанном `log stream selector`.

Пример переменной-запроса

Чтобы создать переменную, которая перечисляет значения метки app:

Добавьте новую переменную типа Query и выберите источник данных Loki.
Установите Query type в Label values, а Label — в app.
При желании введите Stream selector, например {namespace="$namespace"}, чтобы возвращать только значения, которые появляются в пределах выбора другой переменной. Это создаёт связанную переменную, которая обновляется при изменении родительской переменной.

Ссылайтесь на переменную в запросе по её имени с префиксом $. Для переменной с одним значением используйте точное совпадение:

{app="$app"}

Когда у переменной включены Multi-value или Include All, Grafana объединяет выбранные значения в регулярное выражение, например payments|checkout. Используйте оператор сопоставления с регулярным выражением =~, чтобы запрос соответствовал любому из выбранных значений:

{app=~"$app"}

Форматирование значений переменных

По умолчанию источник данных Loki форматирует значения переменных на основе настроек переменной:

Переменная с одним значением вставляется как есть, без экранирования.
Переменная с Multi-value или Include All экранирует каждое значение для использования в регулярном выражении и объединяет их с помощью |, например payments|checkout.

Это поведение по умолчанию подходит для оператора сопоставления с регулярным выражением =~, но может дать неожиданные результаты, когда пользовательское или статическое значение содержит символы, которые Grafana экранирует, или когда вы вставляете значение в контекст, не являющийся регулярным выражением. Чтобы управлять форматированием, используйте параметр формата в синтаксисе переменной:

Синтаксис	Результат
`${app:raw}`	Вставляет значение без экранирования. Используйте это для пользовательских или статических значений, которые должны передаваться без изменений.
`${app:pipe}`	Объединяет несколько значений с помощью `\|` без экранирования для регулярного выражения.
`${app:regex}`	Экранирует значения для регулярного выражения и объединяет их с помощью `\|`.

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

{app="${app:raw}"}

Полный список параметров формата см. в разделе Расширенные параметры формата переменных.

Использование ad hoc-фильтров

Loki поддерживает ad hoc-фильтры. Используйте их, чтобы задать любое количество фильтров «ключ/значение», которые Grafana автоматически применяет ко всем вашим запросам Loki, без редактирования каждого запроса.

Например, если вы добавите ad hoc-фильтр для level = error, Grafana добавит сопоставитель в селектор потока каждого запроса Loki на дашборде, так что запрос вида {app="payments"} выполнится как {app="payments", level="error"}.

Дополнительную информацию см. в разделе Добавление ad hoc-фильтров.

Использование переменной `$__auto` для запросов метрик Loki

Рассмотрите использование переменной $__auto в ваших запросах метрик Loki, которая автоматически подставляется значением шага для запросов range и значением выбранного временного диапазона (вычисленным из времени начала и окончания) для instant-запросов.

Используйте её как диапазон в range-агрегации:

sum(rate({app="payments"} |= `error` [$__auto]))

Note
Предпочитайте $__auto вместо $__range для диапазона в запросе метрик. Переменная $__range разрешается в весь выбранный временной диапазон, поэтому использование её как range-вектора, например [$__range], заставляет каждую точку данных агрегироваться по всему окну. Это может привести к сканированию гораздо большего объёма данных и к заглядыванию дальше назад, чем вы намеревались.

Дополнительную информацию о переменных см. в разделе Глобальные встроенные переменные.

Известные ограничения

Учитывайте следующие ограничения при использовании шаблонных переменных с источником данных Loki:

Для запросов переменных меток доступны только индексируемые метки. Переменная Query типа Label values возвращает значения индексируемых меток потока. Значения, которые существуют только как разобранные поля или structured metadata, недоступны, потому что запрос переменной не выполняет конвейер журналов для их извлечения.
Длинные временные диапазоны могут возвращать неполные значения. Запросы переменных меток и значений меток выполняются по выбранному временному диапазону дашборда. На длинном диапазоне с большим объёмом журналов запрос может превысить тайм-аут или достичь лимитов, настроенных в Loki, и вернуть неполный список значений. Сузьте временной диапазон или добавьте селектор потока в запрос переменной, чтобы он сканировал меньше данных.

Извлечение и индексирование меток в Loki

Метки играют ключевую роль в том, как Loki агрегирует журналы и запрашивает их. Метки — это пары key-value, которые добавляют контекстную информацию к записям журнала, и Loki использует их для эффективной организации, фильтрации и поиска данных журналов.

Извлечение меток

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

2023-07-25 12:34:56 INFO: Request from IP A.B.C.D to endpoint /api/data

Вы можете определить регулярное выражение, которое извлекает уровень журнала (INFO), IP-адрес (A.B.C.D) и конечную точку (/api/data) как метки. Затем вы можете использовать эти метки для фильтрации и агрегации записей журнала.

Индексирование меток

Loki индексирует извлечённые метки. Индекс сопоставляет метки их записям журнала, поэтому Loki может извлекать журналы по метке без сканирования всего набора данных. Например, если метка job представляет сервисы в вашем приложении, Loki индексирует журналы каждого job отдельно, так что вы можете быстро запросить один job.

Комбинируйте индексируемые метки Loki с шаблонными переменными Grafana, чтобы строить динамические запросы. Используйте шаблонные переменные для выбора и фильтрации журналов по меткам, таким как имена job, идентификаторы экземпляров или уровни серьёзности, чтобы интерактивно исследовать и визуализировать данные ваших журналов.