Документация Grafana Документация GlaberGraph Источники данных PostgreSQL Переменные шаблонов

Переменные шаблонов PostgreSQL

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

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

Переменная запроса

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

Источник данных PostgreSQL включает выделенный редактор запросов переменных с полным редактором SQL (режим Code с автодополнением и подсветкой синтаксиса) и раскрывающимися списками Value Field / Text Field. После того как вы напишете и выполните запрос, редактор автоматически определяет возвращённые столбцы и заполняет раскрывающиеся списки полей, чтобы вы могли сопоставить, какой столбец предоставляет значение переменной, а какой — метку отображения.

Чтобы создать переменную запроса:

1. Перейдите к дашборду, который хотите обновить, и нажмите Edit.
2. Нажмите значок Add new element (синий знак плюс).
3. Нажмите Variable.
4. Выберите Query в качестве типа переменной.
5. Введите Name для вашей переменной (например, host).
6. Выберите опцию в раскрывающемся списке Display, чтобы управлять тем, где на дашборде отображается переменная.
7. Нажмите Open variable editor, чтобы открыть диалоговое окно Query Variable.
8. Выберите ваш источник данных PostgreSQL.
9. Напишите SQL-запрос в редакторе. Поддерживаются такие макросы, как $__timeFilter.
10. При необходимости задайте Value Field и Text Field, чтобы управлять тем, какие столбцы сопоставляются со значением переменной и меткой отображения.

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

SQL Copy

SELECT hostname FROM host

Запрос может возвращать несколько столбцов, и Grafana автоматически генерирует список, используя значения из этих столбцов. Например, следующий запрос возвращает значения из столбцов hostname и hostname2, которые включаются в раскрывающийся список переменной.

SQL Copy

SELECT host.hostname, other_host.hostname2 FROM host JOIN other_host ON host.city = other_host.city

Чтобы использовать в вашем запросе зависящие от диапазона времени макросы, такие как $__timeFilter(column), вы должны установить режим обновления переменной шаблона в On Time Range Change.

SQL Copy

SELECT event_name FROM event_log WHERE $__timeFilter(time_column)

Переменные «ключ/значение»

Вы можете создать переменную «ключ/значение», чтобы в раскрывающемся списке отображалась удобная для пользователя метка (например, hostname), тогда как запросы панелей используют другое значение (например, ID). Используйте Value field и Text field в редакторе переменных в нижней части раздела запроса, чтобы указать, какие столбцы запроса предоставляют значение и метку. Ваш запрос может использовать любые имена столбцов; вам не нужны __value или __text в SQL.

Пример: выполните запрос, возвращающий hostname и id, затем установите Text field в hostname, а Value field — в id.

SQL Copy

SELECT hostname, id FROM host

Обратите внимание, что значения в текстовом столбце должны быть уникальными. Если есть дубликаты, Grafana использует только первую совпадающую запись.

В качестве альтернативы вы можете использовать устаревший подход: возвращайте в запросе столбцы с именами __text и __value (например, SELECT hostname AS __text, id AS __value FROM host).

Вложенные переменные

Вы можете создавать вложенные переменные, где одна переменная зависит от значения другой. Например, если у вас есть переменная с именем region, вы можете настроить переменную hosts так, чтобы показывать только хосты из выбранного региона. Если region — многозначная переменная, используйте оператор IN вместо =, чтобы сопоставить несколько выбранных значений.

SQL Copy

SELECT hostname FROM host WHERE region IN($region)

Фильтрация результатов с помощью __searchFilter

Использование __searchFilter в поле запроса фильтрует результаты запроса на основе ввода пользователя в раскрывающемся списке выбора. Если ничего не введено, значение по умолчанию для __searchFilter — %.

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

Следующий пример включает поиск по hostname в реальном времени по мере ввода пользователем в раскрывающемся списке выбора:

SQL Copy

SELECT hostname FROM host WHERE hostname LIKE '$__searchFilter'

Для таблиц с большим количеством строк комбинируйте __searchFilter с LIMIT, чтобы раскрывающийся список оставался отзывчивым:

SQL Copy

SELECT DISTINCT hostname
FROM host
WHERE hostname LIKE '$__searchFilter'
ORDER BY hostname
LIMIT 100

Переменная с регулярным выражением

Вы можете использовать переменную типа Regex для фильтрации или преобразования значений из другой переменной. Например, если у вас есть переменная с именем server, возвращающая значения, такие как web-prod-01, web-staging-01 и db-prod-01, вы можете создать переменную с регулярным выражением, чтобы извлечь только среду:

1. Создайте новую переменную с Type: Query.
2. Задайте запрос так, чтобы он возвращал сырые значения.
3. В поле Regex введите шаблон для извлечения или фильтрации. Например, /^web-(.+)-\d+$/ извлекает prod и staging из имён веб-серверов.

Вы также можете использовать регулярное выражение для фильтрации вариантов переменной. Например, установка поля Regex в /prod/ для переменной, возвращающей все имена серверов, ограничивает раскрывающийся список только продакшен-серверами.

Переменные с несколькими свойствами

Источник данных PostgreSQL поддерживает переменные с несколькими свойствами. Используйте их, когда одно и то же логическое понятие имеет разные идентификаторы в разных контекстах (например, среда называется dev в одной системе и development в другой). Вместо того чтобы поддерживать несколько переменных синхронно, вы можете сопоставить все эти значения с одной переменной и ссылаться на нужное свойство в каждой панели или запросе.

Вы можете создать переменную с несколькими свойствами с Type: Custom или Type: Query:

• Type: Custom — в Custom options > JSON вставьте свой собственный массив JSON с сопоставлением. Каждый объект в массиве может иметь любое количество свойств; используйте text и value для метки и значения, отображаемых в раскрывающемся списке, и добавляйте дополнительные свойства по мере необходимости. О формате JSON и примерах см. Пользовательские переменные с несколькими свойствами в разделе «Добавление переменных и управление ими».

• Type: Query — напишите SQL-запрос, возвращающий несколько столбцов. В редакторе переменных установите Value field и Text field в столбцы, которые предоставляют значение и метку для раскрывающегося списка. Добавьте по одному столбцу на каждое свойство, на которое хотите ссылаться; имя каждого столбца становится именем свойства. На панелях и в запросах ссылайтесь на свойство с помощью ${varName.columnName}.

Пример (Type: Query): переменная с именем env, которая перечисляет среды с разными идентификаторами для каждого облака. В редакторе переменных установите Text field в name, а Value field — в id.

SQL Copy

SELECT
  name,
  id,
  aws_identifier AS env_aws,
  azure_identifier AS env_azure
FROM environments

В запросе панели вы можете использовать $env.env_aws для запроса, связанного с AWS, и $env.env_azure для запроса, связанного с Azure. Подробнее о концепции см. Настройка переменных с несколькими свойствами в разделе Добавление переменных и управление ими.

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

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

При использовании многозначной переменной используйте оператор сравнения IN вместо =, чтобы сопоставить несколько значений.

Grafana поддерживает два синтаксиса для использования переменных в запросах:

• Синтаксис $<varname>

Пример с переменной шаблона с именем hostname:

SQL Copy

SELECT
  atimestamp AS time,
  aint AS value
FROM table
WHERE $__timeFilter(atimestamp) AND hostname IN($hostname)
ORDER BY atimestamp ASC

• Синтаксис [[varname]]

Пример с переменной шаблона с именем hostname:

SQL Copy

SELECT
  atimestamp AS time,
  aint AS value
FROM table
WHERE $__timeFilter(atimestamp) AND hostname IN([[hostname]])
ORDER BY atimestamp ASC

Многозначная переменная с предложением IN

Когда для переменной включено Multi-value, Grafana автоматически добавляет кавычки вокруг каждого выбранного значения. Например, если пользователь выбирает web01 и web02, $hostname разворачивается в 'web01','web02'. Используйте оператор IN для сопоставления:

SQL Copy

SELECT
  $__timeGroupAlias("created_at", '5m'),
  count(*) AS requests
FROM access_log
WHERE $__timeFilter("created_at")
  AND hostname IN($hostname)
GROUP BY time
ORDER BY time

Если выбрано только одно значение, предложение IN всё равно работает корректно — IN('web01') эквивалентно = 'web01'.

Многозначная переменная с числовыми столбцами

Для числовых столбцов (таких как ID) отключите заключение в кавычки с помощью опции формата csv, чтобы значения не оборачивались в кавычки:

SQL Copy

SELECT name FROM host WHERE id IN(${host_id:csv})

Если для host_id выбраны значения 1, 2 и 3, это разворачивается в IN(1,2,3) вместо IN('1','2','3').

Отключение заключения в кавычки для многозначных переменных

По умолчанию Grafana форматирует многозначные переменные как строку с кавычками, разделённую запятыми. Например, если выбраны server01 и server02, результат — 'server01','server02'. Чтобы отключить заключение в кавычки, используйте опцию форматирования csv:

text Copy

${servers:csv}

Это выводит значения как список без кавычек, разделённый запятыми.

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