Документация Grafana Документация GlaberGraph Визуализация данных Дашборды Переменные Add variables

Добавление переменных

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

Ввод общих параметров для любой переменной

Чтобы создать переменную, выполните следующие шаги:

1. Перейдите к дашборду, который хотите обновить.
2. Нажмите Edit.
3. Нажмите значок Add new element (синий знак «плюс») и выберите Variable.

Также можно нажать значок Add variable в верхней части дашборда (знак «плюс»).

4. Выберите тип переменной из списка.

   Тип переменной можно изменить, нажав Change type на боковой панели.

5. Введите Name переменной.

6. (Необязательно) В поле Label введите отображаемое имя для раскрывающегося списка переменной.

   Если не ввести отображаемое имя, меткой раскрывающегося списка будет имя переменной.

7. (Необязательно) В поле Description введите описание переменной. Описание отображается в виде всплывающей подсказки со значком информации рядом с именем переменной на дашборде.

   Описания поддерживают ссылки. Можно использовать ссылки в стиле Markdown ([link text](https://example.com)) или вставлять URL как есть (https://example.com). Только URL http и https отображаются как кликабельные ссылки — остальные протоколы отображаются как обычный текст.

8. Выберите параметр Display:

   • Above dashboard — раскрывающийся список переменной отображается над дашбордом со значением Name или Label переменной. Это значение по умолчанию.
   • Above dashboard, label hidden — раскрывающийся список переменной отображается над дашбордом, но без имени переменной.
   • Controls menu — переменная отображается в меню элементов управления дашборда, а не над дашбордом. Меню элементов управления дашборда отображается в виде кнопки на панели инструментов дашборда.
   • Hidden — раскрывающийся список переменной на дашборде не отображается.
9. Нажмите одну из следующих ссылок, чтобы выполнить шаги по добавлению выбранного типа переменной:
   • Query
   • Custom
   • Textbox
   • Constant
   • Data source
   • Interval
   • Switch

Рекомендации по работе с переменными

• Раскрывающиеся списки переменных отображаются в том порядке, в котором они перечислены в разделе Variables боковой панели, поэтому размещайте часто изменяемые переменные вверху, чтобы они отображались первыми.
• По умолчанию у переменных нет значения по умолчанию. Это означает, что всегда предварительно выбирается верхнее значение в раскрывающемся списке. Если вы хотите предварительно заполнить переменную пустым значением, можно использовать следующий обходной путь в настройках переменной:
  1. Установите флажок Include All Option.
  2. В поле Custom all value введите значение, например .+.

Добавление query-переменной

Query-переменные позволяют написать запрос к источнику данных, который может вернуть список имён метрик, значений тегов или ключей. Например, query-переменная может вернуть список имён серверов, идентификаторов датчиков или центров обработки данных. Значения переменной меняются, так как она динамически получает параметры с помощью запроса к источнику данных.

Query-переменные, как правило, поддерживаются только для строк. Если ваш запрос возвращает числа или любой другой тип данных, возможно, потребуется преобразовать их в строки, чтобы использовать в качестве переменных. Например, для источника данных Azure для этой цели можно использовать функцию tostring.

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

1. Введите общие параметры.

2. Нажмите Open variable editor.

3. Задайте следующие параметры для настройки запроса на вкладке Query:

   Expand table

   Параметр	Описание
   Target data source	Выберите источник данных в раскрывающемся списке. Также можно нажать Open advanced data source picker, чтобы увидеть больше параметров, включая добавление источника данных (только для администраторов). Дополнительные сведения об источниках данных см. в разделе Add a data source.
   Query type	Если применимо, выберите параметр в раскрывающемся списке и соответствующим образом заполните поля запроса. Дополнительные сведения см. в разделе Query type после этих шагов.
   Regex	(Необязательно) Введите регулярное выражение в поле, чтобы отфильтровать или захватить определённые части имён, возвращаемых запросом к источнику данных. Примеры см. в разделе Filter variables with a regular expression.
   Apply regex to	Выберите Variable value или Display text, чтобы указать, где применяется шаблон регулярного выражения. По умолчанию — Variable value.
   Sort	Выберите порядок сортировки значений, отображаемых в раскрывающемся списке. Параметр по умолчанию Disabled означает, что используется порядок параметров, возвращаемых запросом к источнику данных.

4. На вкладке Static options задайте следующие параметры:

   • Выберите параметр в раскрывающемся списке Static options sort, чтобы управлять тем, в каком месте списка значений переменной отображаются статические параметры.
   • В разделе value нажмите + Add new option или Paste from clipboard, чтобы добавить статические параметры.

5. Нажмите Preview в верхней части диалогового окна, чтобы протестировать переменную.

   Grafana отображает список текущих значений переменной.

6. В разделе Preview of values проверьте значения, чтобы убедиться, что они соответствуют ожидаемым.

7. Нажмите Apply, чтобы закрыть диалоговое окно редактора query-переменной.

8. В раскрывающемся списке Refresh выберите параметр, определяющий, когда переменная должна обновляться:

   • On dashboard load — запрашивает источник данных при каждой загрузке дашборда. Это замедляет загрузку дашборда, поскольку запрос переменной должен завершиться до инициализации дашборда.
   • On time range change — запрашивает источник данных при каждой загрузке дашборда и при изменении диапазона времени дашборда. Используйте этот параметр, если запрос параметров переменной содержит фильтр по диапазону времени или зависит от диапазона времени дашборда.

9. (Необязательно) При необходимости задайте параметры выбора:

   • Multi-value — позволяет выбирать несколько значений одновременно.
   • Include All value — добавляет параметр для включения всех переменных.
   • Allow custom values — позволяет пользователям добавлять пользовательские значения в список. Применяется только к пользовательским значениям CSV.

10. Нажмите Save в правом верхнем углу.

11. Введите необязательное описание изменений и нажмите Save.

12. Нажмите Exit edit.

Query type

Раздел запроса в редакторе зависит от вашего источника данных. Некоторые источники данных имеют собственные редакторы запросов.

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

Некоторые источники данных позволяют задавать пользовательские «отображаемые имена» для значений. Например, плагины PostgreSQL, MySQL и Microsoft SQL Server делают это, выполняя поиск полей с именами __text и __value в результате. Другие источники данных могут искать text и value или использовать иной подход. Всегда перепроверяйте документацию по источнику данных.

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

Добавление custom-переменной

Используйте custom-переменную для значения, которое не меняется, например числа или строки.

Например, если у вас есть имена серверов или регионов, которые никогда не меняются, возможно, вы захотите создать их как custom-переменные, а не как query-переменные. Поскольку они не меняются, их можно использовать в связанных переменных вместо других query-переменных. Это сократит количество запросов, которые Grafana должна отправлять при обновлении связанных переменных.

1. Введите общие параметры.

2. Нажмите Open variable editor.

3. Настройте один из следующих параметров:

   • CSV — введите плоский список значений переменной в виде списка, разделённого запятыми. Можно включать числа, строки или пары «ключ/значение», разделённые пробелом и двоеточием. Например, key1 : value1,key2 : value2.
   • JSON — предоставьте JSON-массив объектов, каждый из которых может иметь любое количество свойств, к которым можно обращаться. Дополнительные сведения см. в разделе Configure multi-property variables.

4. Нажмите Preview, чтобы протестировать переменную.

5. В разделе Preview of values Grafana отображает список текущих значений переменной. Если вы ввели JSON-массив, предварительный просмотр представляет собой таблицу со всеми свойствами значений. Проверьте их, чтобы убедиться, что они соответствуют ожидаемым.

6. Нажмите Apply, чтобы закрыть диалоговое окно редактора запроса.

7. (Необязательно) При необходимости задайте параметры выбора:

   • Multi-value — позволяет выбирать несколько значений одновременно.
   • Include All value — добавляет параметр для включения всех переменных.
   • Allow custom values — позволяет пользователям добавлять пользовательские значения в список. Применяется только к пользовательским значениям CSV.

8. Нажмите Save в правом верхнем углу.

9. Введите необязательное описание изменений и нажмите Save.

10. Нажмите Exit edit.

Добавление переменной текстового поля

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

Дополнительные сведения о кардинальности см. в статье What are cardinality spikes and why do they matter?

1. Введите общие параметры.

2. (Необязательно) В разделе Textbox options введите значение по умолчанию для переменной в поле Value.

   Если ничего не вводить в это поле, Grafana отобразит пустое текстовое поле для ввода текста пользователями.

3. Нажмите Save в правом верхнем углу.

4. Введите необязательное описание изменений и нажмите Save.

5. Нажмите Exit edit.

Добавление константной переменной

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

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

Константные переменные полезны, когда у вас есть сложные значения, которые нужно включать в запросы, но не хочется вводить заново в каждом запросе. Например, если у вас есть путь к серверу с именем i-0b6a61efe2ab843gg, его можно заменить переменной с именем $path_gg.

1. Введите общие параметры.

2. В разделе Constant options введите значение переменной в поле Value.

   Можно вводить буквы, цифры и символы. Можно даже использовать подстановочные знаки, если использовать формат raw.

3. Нажмите Save в правом верхнем углу.

4. Введите необязательное описание изменений и нажмите Save.

5. Нажмите Exit edit.

Добавление переменной источника данных

Data source-переменные позволяют быстро менять источник данных для всего дашборда. Они полезны, если у вас есть несколько экземпляров источника данных, возможно, в разных средах.

1. Введите общие параметры.

2. Настройте следующие Data source options:

   • Type — выберите целевой источник данных для переменной.
   • Name filter — (Необязательно) Введите регулярное выражение для фильтрации того, какие экземпляры источника данных выбирать в раскрывающемся списке значений переменной. Оставьте это поле пустым, чтобы отобразить все экземпляры.

3. (Необязательно) При необходимости задайте параметры выбора:

   • Multi-value — позволяет выбирать несколько значений одновременно.
   • Include All value — добавляет параметр для включения всех переменных.
   • Allow custom values — позволяет пользователям добавлять пользовательские значения в список. Применяется только к пользовательским значениям CSV.

4. Нажмите Save в правом верхнем углу.

5. Введите необязательное описание изменений и нажмите Save.

6. Нажмите Exit edit.

Добавление переменной-интервала

Используйте interval-переменную для представления промежутков времени, таких как 1m, 1h, 1d. Их можно рассматривать как команду «group by time» на уровне всего дашборда. Переменные-интервалы изменяют способ группировки данных в визуализации. Также можно использовать параметр Auto, чтобы возвращать заданное число точек данных на промежуток времени.

Переменную-интервал можно использовать как параметр группировки по времени (для InfluxDB), как интервал гистограммы по дате (для Elasticsearch) или как параметр функции summarize (для Graphite).

1. Введите общие параметры.

2. Настройте следующие Interval options:

   Expand table

   Параметр	Описание
   Values	Введите интервалы времени, которые должны отображаться в раскрывающемся списке переменной. Поддерживаются следующие единицы времени: s (секунды), m (минуты), h (часы), d (дни), w (недели), M (месяцы) и y (годы). Также можно принять или изменить значения по умолчанию: 1m,10m,30m,1h,6h,12h,1d,7d,14d,30d.
   Auto option	(Необязательно) Установите флажок, если хотите добавить в список параметр auto. Этот параметр позволяет указать, на сколько частей следует разделить текущий диапазон времени для вычисления текущего промежутка времени auto.
   Step count	Выберите, на сколько частей делится текущий диапазон времени для вычисления значения, аналогично параметру запроса Max data points. Например, если текущий видимый диапазон времени составляет 30 минут, интервал auto группирует данные в 30 одноминутных интервалов. Значение по умолчанию — 30 шагов. Отображается только при установленном флажке Auto option.
   Min interval	Минимальный порог, ниже которого интервалы шагов не делят время. Продолжая пример с 30 минутами: если минимальный интервал установлен в 2m, Grafana сгруппирует данные в 15 двухминутных интервалов. Отображается только при установленном флажке Auto option.

3. Нажмите Save в правом верхнем углу.

4. Введите необязательное описание изменений и нажмите Save.

5. Нажмите Exit edit.

Примеры переменных-интервалов

В следующем примере показана переменная-шаблон myinterval в функции Graphite:

Copy

summarize($myinterval, sum, false)

В следующем примере показан более сложный пример Graphite из панели Graphite Template Nested Requests:

Copy

groupByNode(summarize(movingAverage(apps.$app.$server.counters.requests.count, 5), '$interval', 'sum', false), 2, 'sum')

Добавление переменной-переключателя

Switch-переменные отображают переключатель с двумя настраиваемыми значениями, представляющими включённое и отключённое состояния. Этот тип переменной полезен, когда нужно:

• Переключаться между разными условиями запроса
• Включать или отключать определённые фильтры
• Переключаться между разными режимами визуализации
• Управлять логическими параметрами в источниках данных

1. Введите общие параметры.

2. Настройте следующие Switch options:

   Expand table

   Параметр	Описание
   Value pair type	Выберите один из следующих предопределённых параметров: True / False — использует логические значения true и false. 1 / 0 — использует числовые значения 1 и 0. Yes / No — использует строковые значения yes и no. Custom — позволяет определить пользовательские значения для включённого и отключённого состояний.
   Enabled value	Если вы выбрали Custom, настройте пользовательские значения. Введите значение, представляющее включённое состояние (например, «on»).
   Disabled value	Если вы выбрали Custom, введите значение, представляющее отключённое состояние (например, «off»).

3. Нажмите Save в правом верхнем углу.

4. Введите необязательное описание изменений и нажмите Save.

5. Нажмите Exit edit.

Примеры переменных-переключателей

В следующем примере показана переменная-переключатель $debug_mode, используемая в запросе Prometheus для условного включения меток отладки:

Copy

up{job="my-service"} and ($debug_mode == "true" or on() vector(0))

В следующем примере показана переменная-переключатель $show_errors, используемая для фильтрации записей журнала:

Copy

{job="application"} |= ($show_errors == "1" ? "ERROR" : "")

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

Copy

{{#if debug_mode}}Debug Mode: {{/if}}Application Metrics

Параметры выбора переменных

Selection Options — это функция, с помощью которой можно управлять выбором параметров переменных для query- и custom-переменных. Все параметры выбора необязательны и по умолчанию отключены.

Переменные с несколькими значениями

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

Переменные с несколькими значениями и источник данных Graphite

Graphite использует glob-выражения. В этом случае переменная с несколькими значениями была бы интерполирована как {host1,host2,host3}, если текущее значение переменной — host1, host2 и host3.

Переменные с несколькими значениями и источник данных Prometheus или InfluxDB

InfluxDB и Prometheus используют регулярные выражения, поэтому та же переменная была бы интерполирована как (host1|host2|host3). Каждое значение также было бы экранировано для регулярного выражения. В противном случае значение с управляющим символом регулярного выражения нарушило бы регулярное выражение.

Переменные с несколькими значениями и источник данных Elastic

Elasticsearch использует синтаксис запросов Lucene, поэтому та же переменная была бы отформатирована как ("host1" OR "host2" OR "host3"). В этом случае каждое значение должно быть экранировано, чтобы оно содержало только управляющие слова Lucene и кавычки.

Индексация переменных

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

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

text Copy

${query0.0}

Приведённый синтаксис ссылается на первую позицию (или позицию 0) в массиве.

В следующем примере есть массив из трёх значений — 1t, 2t и 3t, и вместо ссылки на эти значения запрос панели ссылается на второе значение в массиве, используя синтаксис ${query0.1}:

Устранение неполадок с переменными, имеющими несколько значений

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

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

• Отключить параметры Multi-value или Include All option.
• Использовать формат переменной raw.

Параметр Include All

Grafana добавляет в раскрывающийся список переменной параметр All. Если пользователь выбирает этот параметр, выбираются все параметры переменной.

Если вы включаете этот параметр, но также устанавливаете для переменной параметр Display в значение Hidden, переменная по умолчанию выбирает только первое значение—не All—если только вы явно не выберете All, пока переменная видима, а затем не сохраните дашборд. Чтобы задать All как значение по умолчанию для скрытой переменной, выполните следующие шаги:

1. Временно установите Display в значение Above dashboard.
2. На дашборде выберите параметр All в раскрывающемся списке переменной.
3. Сохраните дашборд, чтобы сохранить выбор.
4. Вернитесь в Dashboard options > Variables, выберите переменную и установите Display обратно в Hidden.
5. Снова сохраните дашборд.

Пользовательское значение all

Этот параметр виден только при выбранном параметре Include All option.

Введите регулярные выражения, glob-выражения или синтаксис Lucene в поле Custom all value, чтобы определить значение параметра All.

По умолчанию значение All включает все параметры в объединённом выражении. Оно может стать очень длинным и вызывать проблемы с производительностью. Иногда лучше указать пользовательское значение all, например подстановочное регулярное выражение.

Чтобы использовать в параметре Custom all value пользовательские регулярные выражения, glob-выражения или синтаксис Lucene, оно никогда не экранируется, поэтому нужно продумать, какое значение допустимо для вашего источника данных.