Плагин-источник данных Grafana для интеграции с YDB

YDB data source plugin позволяет использовать Grafana для запросов и визуализации данных из YDB.

Установка

Для работы плагина понадобится Grafana версии не ниже 9.2.

Следуйте документации Grafana, чтобы установить плагин под названием ydb-grafana-datasource-plugin.

Конфигурация

YDB пользователь для источника данных

Настройте аккаунт пользователя YDB с правами только на чтение (подробнее об уровнях доступа) и доступом до баз данных и таблиц, к которым потребуется делать запросы.

Протокол передачи данных

Плагин поддерживает транспортные протоколы gRPC и gRPCS.

Настройка через UI

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

Настройка через файл конфигурации

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

Аутентификация

Плагин поддерживает следующие типы аутентификации в YDB: Anonymous, Access Token, Metadata, Service Account Key и Static Credentials.

Пример настройки источника данных YDB с использованием аутентификации в через логин/пароль:

apiVersion: 1
datasources:
  - name: YDB
    type: ydbtech-ydb-datasource
    jsonData:
      authKind: '<password>'
      endpoint: 'grpcs://<hostname>:2135'
      dbLocation: '<location_to_db>'
      user: '<username>'
    secureJsonData:
      password: '<userpassword>'
      certificate: |
        <full content of *.pem file>

Поддерживаемые поля для создания соединения:

Написание запросов

Для запроса данных из баз YDB используется YQL.

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

Временные ряды

Визуализировать данные как временные ряды возможно при условии наличия в результатах запроса одного поля с типами Date, Datetime или Timestamp (на текущий момент поддержана работа со временем только во временной зоне UTC) и как минимум одного поля с типом Int64, Int32, Int16, Int8, Uint64, Uint32, Uint16, Uint8, Double или Float. Визуализацию в виде временных рядов можно выбрать с помощью настроек. Все остальные колонки интерпретируются как значения.

Многострочные временные ряды

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

• поле с типом данных Date, Datetime или Timestamp (на текущий момент поддержана работа со временем только во временной зоне UTC)
• метрика - поле с типом Int64, Int32, Int16, Int8, Uint64, Uint32, Uint16, Uint8, Double или Float
• либо метрика, либо поле с типом String или Utf8 - значение для разбиения метрик по отдельным рядам.

Например:

SELECT
    `timestamp`,
    `responseStatus`
    AVG(`requestTime`) AS `avgReqTime`
FROM `/database/endpoint/my-logs`
GROUP BY `responseStatus`, `timestamp`
ORDER BY `timestamp`

Таблицы

Табличное представление доступно для любого валидного YDB запроса, возвращающего ровно один набор результатов.

Визуализация логов

Для визуализации данных в виде логов запрос должен возвращать поле с типом данных Date, Datetime или Timestamp и прое с типом String. Выбрать тип визуализации можно с помощью настроек. По умолчанию только первое встреченное текстовое поле трактуется как строка лога, но это поведение может быть изменено с помощью конструктора запросов.

Макросы

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

В запросе могут содержаться два вида макросов - уровня Grafana и уровня YQL. Перед отправкой запроса в YDB, плагин проанализирует текст запроса и заменит макросы уровня Grafana на конкретные значения. После этого макросы уровня YQL будут обработаны на сервере YDB.

Пример запроса с макросом, который позволяет использовать временной фильтр Grafana.

SELECT `timeCol`
FROM `/database/endpoint/my-logs`
WHERE $__timeFilter(`timeCol`)

SELECT `timeCol`
FROM `/database/endpoint/my-logs`
WHERE $__timeFilter(`timeCol` + Interval("PT24H"))

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

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

Дополнительная информация

• Добавить Аннотации.
• Настроить и использовать Шаблоны и переменные.
• Добавить Трансформации.
• Настроить Уведомления.