Запросы и преобразование данных

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

О запросах

Панели Grafana взаимодействуют с источниками данных с помощью запросов, которые извлекают данные для визуализации. Запрос — это вопрос, написанный на языке запросов, используемом источником данных.

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

Редакторы запросов

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

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

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

• Для источников данных, входящих в состав Grafana, см. Встроенные основные источники данных, где приведены ссылки на документацию каждого основного источника данных.
• Для источников данных, установленных как плагины, см. документацию соответствующего плагина.
  • Плагины источников данных в каталоге плагинов Grafana содержат ссылки на документацию или включают её в свои описания в каталоге. Подробнее о каталоге плагинов см. в разделе Plugin management.
  • Ссылки на документацию плагинов источников данных Grafana Enterprise см. в указателе плагинов Enterprise.

Синтаксис запросов

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

Пример PostgreSQL:

Пример PromQL:

Специальные источники данных

Grafana также включает три специальных источника данных: Grafana, Mixed и Dashboard. Подробнее см. в разделе Data sources

Сохранённые запросы

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

Сохранённые запросы поддерживаются в:

• Дашбордах
• Explore
• Аннотациях

Узнайте больше о сохранённых запросах:

• Диалоговое окно Saved queries
• Роли, разрешения и RBAC
• Как сохранить запрос
• Переменные в сохранённых запросах
• Управление сохранёнными запросами как кодом
• Известные ограничения

Диалоговое окно Saved queries

Диалоговое окно Saved queries даёт доступ ко всем сохранённым запросам вашей организации:

Чтобы открыть сохранённые запросы:

• Нажмите Replace в области редактора запросов.
• Нажмите синий значок «плюс» в боковой панели редактора запросов и выберите Add saved query.

Нажатие Add saved query добавляет дополнительный запрос, а нажатие Replace обновляет настроенный запрос.

В диалоговом окне Saved queries вы можете:

• Искать запросы по имени источника данных, содержимому запроса, заголовку или описанию.
• Сортировать запросы по алфавиту или по дате создания.
• Фильтровать по имени источника данных, имени автора и тегам. Фильтр по тегам использует оператор OR, а остальные — оператор AND. Используйте переключатель Remember filters, чтобы сохранять выбранные фильтры между сессиями в локальном хранилище.
• Добавлять запросы в избранное, чтобы они отображались в представлении фильтра Starred queries.
• Дублировать или удалять сохранённый запрос.
• Изменять заголовок, описание или теги запроса.

Все те же параметры поиска, фильтрации и сортировки доступны в представлении фильтра Starred queries.

Роли, разрешения и RBAC

Сохранённые запросы поддерживают управление доступом на основе ролей. По умолчанию для сохранённых запросов предусмотрены две роли RBAC:

• Writer: создание, обновление и удаление всех сохранённых запросов.
• Reader: повторное использование сохранённых запросов.

Если вы использовали сохранённые запросы до появления поддержки RBAC в Grafana v12.4, роли пользователей Grafana сопоставляются следующим образом:

• Admin > Writer
• Editor > Writer
• Viewer > Reader

Сохранение запроса

Чтобы сохранить созданный запрос:

1. В редакторе запросов нажмите Save:

2. В диалоговом окне Saved queries введите заголовок запроса, который упростит его поиск в дальнейшем.

3. (Необязательно) Введите описание и соответствующие теги.

4. Нажмите Save.

Переменные в сохранённых запросах

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

Вы можете сопоставить исходные переменные либо с:

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

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

Управление сохранёнными запросами как кодом

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

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

• При сохранении запроса проверка не выполняется, поэтому можно сохранить некорректный запрос. Перед сохранением убедитесь, что запрос работает правильно.
• Можно сохранить не более 1000 запросов.

Навигация по редактору запросов

Редактор запросов панели содержит следующие элементы. Наведите курсор на номер, чтобы отобразить сведения об элементе редактора запросов.

Grafana организует запросы, выражения и преобразования в виде строк, каждая из которых имеет собственную карточку и область редактора. Запросы и выражения по умолчанию обозначаются буквой (A, B, C и так далее).

Вы также можете изменить порядок элементов, перетаскивая карточки в списке.

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

Для конвейеров с большим количеством запросов, выражений или преобразований вы можете развернуть боковую панель на всю высоту, чтобы увидеть всё сразу:

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

Добавление запроса

Запрос возвращает данные, которые Grafana визуализирует на панелях дашборда. При создании панели Grafana автоматически выбирает источник данных по умолчанию.

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

1. Наведите курсор на любую часть панели, к которой добавляете запрос, и нажмите Configure visualization.

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

2. В области редактора нажмите раскрывающееся меню Data source и выберите источник данных.

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

3. Нажмите Query options, чтобы настроить максимальное количество точек данных, которое вам нужно.

   Подробнее о параметрах запроса см. в разделе Параметры запроса.

4. Чтобы создать запрос, выполните одно из следующих действий:

   • Напишите или постройте запрос на языке запросов вашего источника данных.
   • Нажмите Replace, чтобы повторно использовать сохранённый запрос.

   Note

   Сохранённые запросы доступны только в Grafana Enterprise и Grafana Cloud.

5. (Необязательно) Чтобы сохранить запрос для повторного использования, нажмите Save в области редактора.

6. (Необязательно) В боковой панели нажмите синий значок «плюс» рядом с Queries & Expressions и выберите Add query или Add saved query, чтобы добавить дополнительные запросы по мере необходимости.

7. Нажмите Run queries в области редактора.

Grafana отправляет запрос к источнику данных и визуализирует данные.

Управление запросами

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

Expand table

Icon	Description
	Заменяет настроенный запрос сохранённым запросом. Подробнее см. в разделе Сохранённые запросы (только Enterprise и Cloud).
	Сохранить запрос. Сохраняет запрос для повторного использования. Доступ к сохранённым запросам открывается нажатием Replace. Подробнее см. в разделе Сохранённые запросы (только Enterprise и Cloud).
	Создать записанные запросы, чтобы видеть тенденции во времени, делая снимок точки данных через заданный интервал (только Enterprise и Cloud).
	Скрывает запрос. Grafana не отправляет скрытые запросы источнику данных.
	Удаляет запрос. Удаление запроса происходит безвозвратно, но иногда удалённые запросы можно восстановить, вернувшись к ранее сохранённым версиям панели.
	Копирует запрос. Дублирование запросов полезно при работе с несколькими похожими сложными запросами, когда вы хотите поэкспериментировать с разными вариантами или внести небольшие изменения. Чтобы воспользоваться этой возможностью, откройте меню More query actions.
	Переключает справку редактора запросов. Если источник данных это поддерживает, нажмите этот значок, чтобы отобразить сведения об использовании редактора запросов или получить быстрый доступ к типовым запросам. Чтобы воспользоваться этой возможностью, откройте меню More query actions.

Параметры запроса

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

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

Max data points

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

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

Так как значение по умолчанию зависит от ширины панели в пикселях, один и тот же дашборд может по-разному отображать данные в зависимости от размера панели на экране. Когда вы открываете панель, нажав View в меню панели или нажав v, панель разворачивается на всё окно. Это не меняет сеточный макет дашборда, но даёт панели больше пикселей для отрисовки. С большим количеством пикселей Grafana может запросить больше точек данных, что повышает разрешение и уменьшает шаг между точками. В результате один и тот же запрос может вернуть более детальный ряд в режиме просмотра, чем в сетке дашборда.

Чтобы получить согласованное визуальное представление в обоих режимах, задайте для Max data points фиксированное значение. Например, если задать значение 100, Grafana запросит не более 100 точек независимо от ширины панели в пикселях. Это означает, что разрешение запроса остаётся более согласованным как в сетке дашборда, так и в режиме просмотра.

При потоковых данных Grafana использует значение max data points для скользящего буфера. Потоковая передача — это непрерывный поток данных, а буферизация разбивает поток на части. Например, Loki передаёт данные потоком в режиме live tailing.

Min interval

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

Interval

Задаёт интервал времени, который можно использовать при агрегировании или группировке точек данных по времени.

Grafana автоматически вычисляет подходящий интервал, который можно использовать как переменную в шаблонных запросах. Переменная измеряется в секундах ($__interval) или миллисекундах ($__interval_ms).

Интервалы обычно используются в функциях агрегирования, таких как sum или average. Например, это запрос Prometheus, использующий переменную интервала: rate(http_requests_total[$__interval]).

Этот автоматический интервал вычисляется на основе ширины графика. Когда пользователь уменьшает масштаб визуализации, интервал увеличивается, что приводит к более грубому агрегированию. Аналогично, если пользователь увеличивает масштаб, интервал уменьшается, что приводит к более точному агрегированию.

Подробнее см. в разделе Глобальные переменные.

Relative time

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

Expand table

Пример	Поле относительного времени
Последние 5 минут	now-5m
Текущие сутки	now/d
Последние 5 дней	now-5d/d
Текущая неделя	now/w
Последние 2 года	now-2y/y

Time shift

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

Expand table

Пример	Поле смещения времени
Прошлая неделя целиком	1w/w
Две недели назад целиком	2w/w
Прошлый месяц целиком	1M/M
Текущий год целиком	1d/y
Прошлый год целиком	1y/y

Cache timeout

Этот параметр виден, только если он доступен в источнике данных. Он переопределяет время ожидания кэша по умолчанию, если в вашем хранилище временных рядов есть кэш запросов. Укажите это значение числом в секундах.