Шаблонные переменные — одна из самых часто используемых функций в Grafana, предоставляющая пользователям выпадающий список, позволяющий превратить один дашборд в сотни: выберите другой кластер, регион или сервис, и каждая панель обновится.
На протяжении большей части истории Grafana переменные имели единственное место размещения — в верхней части дашборда. У каждого дашборда был один плоский список переменных, и этот список был общим для всех панелей на нем. Но по мере увеличения размера и количества дашбордов эти элементы управления становилось все труднее организовывать и поддерживать. Верхняя часть дашборда могла быть перегружена выпадающими списками, которые применялись только к определенным панелям, в то время как общие элементы управления копировались между дашбордами и требовали индивидуального обновления.
Чтобы решить эти проблемы, мы внедрили две новые функции в Grafana:
- Переменные, общие для нескольких дашбордов (публичная предварительная версия): это переменные, которые можно определить один раз и повторно использовать на разных дашбордах, что обеспечивает согласованность конфигураций и упрощает их поддержку.
(публичная предварительная версия): это переменные, которые можно определить один раз и повторно использовать на разных дашбордах, что обеспечивает согласованность конфигураций и упрощает их поддержку.
В этой статье мы более подробно рассмотрим каждый тип переменных, варианты их использования и то, как начать работу.
Переменные на уровне раздела: определение и управление переменными по строкам или вкладкам
Переменные на уровне раздела позволяют определять переменные и фильтры для конкретной строки или вкладки, чтобы они применялись только к панелям внутри этого раздела. Размещение элемента управления рядом с панелями, на которые он влияет, делает понятным, что изменит выбор, и позволяет избежать беспорядка в верхней части дашборда.
Допустим, вы хотите иметь два выпадающих списка $instance: один для панелей API-шлюза, а другой для панелей базы данных. Традиционно, при использовании одного плоского пространства имен, вы бы получили имена вроде $api_instance и $db_instance, либо вам пришлось бы разделить дашборд на два.
Теперь, благодаря переменным на уровне раздела, раздел API-шлюза и раздел базы данных могут иметь собственную переменную $instance с собственным запросом и выбранным значением. Оба раздела по-прежнему используют общий временной диапазон дашборда, и больше ничего на дашборде не меняется.
Вот как работают переменные на уровне раздела:
- Разрешение происходит от ближайшего к самому дальнему. Когда панель использует переменную, Grafana сначала проверяет раздел, в котором находится панель, на наличие соответствующей переменной, затем любые родительские разделы (строки и вкладки могут быть вложенными), а затем сам дашборд.
Разрешение происходит от ближайшего к самому дальнему. Когда панель использует переменную, Grafana сначала проверяет раздел, в котором находится панель, на наличие соответствующей переменной, затем любые родительские разделы (строки и вкладки могут быть вложенными), а затем сам дашборд.
- Фильтры тоже работают. Вы можете добавить элементы управления «Фильтр» и «Группировать по» на уровне раздела, чтобы раздел мог фильтровать данные по своим собственным меткам.
Фильтры тоже работают. Вы можете добавить элементы управления «Фильтр» и «Группировать по» на уровне раздела, чтобы раздел мог фильтровать данные по своим собственным меткам.
- Редактор запросов учитывает область видимости. Автозаполнение предлагает только те переменные, которые действительно видит редактируемая вами панель.
Редактор запросов учитывает область видимости. Автозаполнение предлагает только те переменные, которые действительно видит редактируемая вами панель.
- Реструктуризация безопасна. Если вы разгруппируете строку или вкладку, переменные этого раздела переместятся на уровень выше, а не исчезнут.
Реструктуризация безопасна. Если вы разгруппируете строку или вкладку, переменные этого раздела переместятся на уровень выше, а не исчезнут.
Чтобы добавить переменную на уровне раздела, отредактируйте дашборд, выберите строку или вкладку и откройте «Переменные» (Variables) на панели параметров.
Переменные, общие для нескольких дашбордов: определение и управление переменными на нескольких дашбордах
Переменные раздела решили проблему области видимости внутри одного дашборда. Более масштабным запросом всегда была область видимости между дашбордами.
Переменные, общие для нескольких дашбордов, позволяют определить общие элементы управления один раз и повторно использовать их на разных дашбордах, сокращая дублирование работы и поддерживая согласованность конфигураций.
Они бывают двух областей видимости:
- Глобальные переменные определяются на уровне организации и могут использоваться на любом дашборде.
Глобальные переменные определяются на уровне организации и могут использоваться на любом дашборде.
- Переменные папки определяются для папки и могут использоваться на дашбордах, находящихся в этой папке.
Переменные папки определяются для папки и могут использоваться на дашбордах, находящихся в этой папке.
Вот как переменные, общие для нескольких дашбордов, выглядят на практике: скажем, например, несколько командных дашбордов используют один и тот же выбор окружения со значениями dev, staging и prod. С помощью общей переменной вы определяете окружение один раз. Когда вы добавляете новое окружение или меняете запрос для него, каждый дашборд, использующий эту переменную, получает обновление без необходимости редактировать каждый дашборд по отдельности.
Переменные, общие для нескольких дашбордов, достигают этого путем разделения двух вещей: определение (тип переменной, запрос и параметры) является общим и управляется в одном месте, в то время как значение, которое выбирает пользователь (например, prod), выбирается на каждом дашборде по мере их использования.
Управление переменными, общими для нескольких дашбордов
Перейдите в Dashboards > Variables, чтобы создавать, редактировать, перемещать и удалять общие переменные. Редактор такой же, как тот, который вы уже используете для переменных дашборда, с теми же типами (Query, Custom, Data source, Text и т. д.). Единственное новое поле — «Папка» (Folder):
- Оставьте его в корне, чтобы создать глобальную переменную.
Оставьте его в корне, чтобы создать глобальную переменную.
- Выберите папку, чтобы создать переменную папки.
Выберите папку, чтобы создать переменную папки.
Чтобы изменить область видимости переменной, переместите ее между папками или в корень.
Выбор переменных для каждого дашборда
Дашборд не использует никакие общие переменные, пока вы их не выберете. В настройках дашборда выберите, какие глобальные переменные и переменные папки он должен использовать:
- Конкретные переменные: на дашборде отображаются только те, которые вы выбрали. Переменные, созданные позже в этой области видимости, не появятся, пока вы их не добавите.
Конкретные переменные: на дашборде отображаются только те, которые вы выбрали. Переменные, созданные позже в этой области видимости, не появятся, пока вы их не добавите.
- Все переменные в области видимости: отображаются все глобальные переменные или все переменные в папке дашборда. Новые появляются автоматически.
Все переменные в области видимости: отображаются все глобальные переменные или все переменные в папке дашборда. Новые появляются автоматически.
Приоритет: побеждает ближайшая область видимости
Поскольку переменная может поступать из четырех мест, существует одно простое правило: побеждает ближайшее определение.
Если дашборд определяет свой собственный регион, он переопределяет глобальный регион. Раздел может переопределить оба.
На дашборде общие переменные появляются рядом с собственными переменными дашборда и работают так же: вы можете выбирать значения, синхронизировать их с URL и использовать в запросах, заголовках и ссылках. В режиме редактирования они доступны только для чтения на дашборде. Чтобы изменить определение, перейдите в Dashboards > Variables.
Управление общими переменными как кодом
В рамках названия продукта общая переменная является ресурсом Variable с собственным API. Она не хранится внутри какого-либо дашборда, но привязана к дашбордам: она находится в группе API дашбордов (dashboard.grafana.app) рядом с Dashboard и ничего не делает, пока дашборд не подключит ее.
Поскольку это отдельный ресурс, он обслуживается той же платформой API в стиле Kubernetes, что и дашборды и папки v2. Вы можете создавать, просматривать и обновлять переменные, как и любой другой ресурс Grafana, не затрагивая при этом дашборд.
Переменная (Variable) имеет ту же структуру, что и переменная внутри дашборда, поэтому все, что вы уже знаете о JSON-структуре переменных дашборда, применимо и здесь:
Оставьте аннотацию grafana.app/folder пустой, чтобы сделать переменную глобальной.
Во время публичного предварительного просмотра ресурс Variable доступен в версии v2beta1. Он будет перенесен в v2, когда переменные для нескольких дашбордов станут общедоступными.
Подготовка с помощью Terraform
Поскольку Variable является стандартным ресурсом API, вы можете управлять им с помощью grafana_apps_generic_resource в Terraform-провайдере Grafana. Вот пример папки, переменной папки и дашборда, который использует эту переменную, — все в одной конфигурации Terraform:
Настройка подключения (opt-in) также естественным образом работает как код. Если не указывать аннотацию, дашборд не будет использовать переменные для нескольких дашбордов. Укажите имена, и он будет использовать именно их. На подготовленном дашборде ничего не появится, если это не указано в конфигурации.
Тот же API работает с kubectl, curl или любым другим инструментом, который взаимодействует с конечными точками /apis в Grafana.
Заключение
Эти обновления означают, что переменные Grafana теперь имеют единую согласованную модель: от отдельного раздела дашборда до всей вашей организации:
Область действия переменной
Где определяется
Где хранится
К чему применяется
Раздел
Строка или вкладка
Дашборд (схема v2)
Панели в этом разделе
Дашборд
Дашборд
Дашборд (схема v2)
Весь дашборд
Папка
Папка
Собственный ресурс Variable
Подключенные дашборды в папке
Глобальная
Стек
Собственный ресурс Variable
Подключенные дашборды в любом месте
В результате при создании дашбордов становится меньше беспорядка, а при их поддержке — меньше копирования и вставки.
Вот два быстрых способа начать работу:
- Предоставьте двум разделам дашборда собственные элементы управления. Отредактируйте дашборд, выберите строку или вкладку и откройте «Переменные» (Variables) на панели параметров. Добавьте переменную экземпляра в каждый раздел и посмотрите, как каждая из них влияет только на свои панели.
Предоставьте двум разделам дашборда собственные элементы управления. Отредактируйте дашборд, выберите строку или вкладку и откройте «Переменные» (Variables) на панели параметров. Добавьте переменную экземпляра в каждый раздел и посмотрите, как каждая из них влияет только на свои панели.
Чтобы узнать больше, ознакомьтесь с документацией по переменным уровня раздела и переменным для нескольких дашбордов. Мы будем рады узнать, как вы их используете. Пожалуйста, свяжитесь с нами в нашем Community Slack.
