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

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

Установка

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

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

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

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

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

Важно

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

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

Плагин поддерживает транспортные протоколы 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>

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

Имя Описание Тип
authKind Тип аутентификации "Anonymous", "ServiceAccountKey", "AccessToken", "UserPassword", "MetaData"
endpoint Эндпоинт string
dbLocation Путь к базе string
user Имя пользователя string
serviceAccAuthAccessKey Ключ доступа для сервисного аккаунта string (защищенное поле)
accessToken Access токен string (защищенное поле)
password Пароль string (защищенное поле)
certificate Если на вашем кластере YDB используются самоподписанные сертификаты TLS, то для соединения с YDB необходимо указать сертификат сертификационного центра, через который они были выпущены string (защищенное поле)

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

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

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

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

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

Time-series

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

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

  • поле с типом данных 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 запроса, возвращающего ровно один набор результатов.

Table

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

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

Logs

Макросы

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

В запросе могут содержаться два вида макросов - уровня 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"))
Макрос Описание Пример вывода
$__timeFilter(columnName) Заменяется условием, которое фильтрует данные в указанной колонке или результате выражения на основании временного диапазона, заданного на панели в микросекундах foo >= CAST(1636717526371000 AS Timestamp) AND foo <= CAST(1668253526371000 AS Timestamp)' )
$__fromTimestamp Заменяется временем начала диапазона, заданного на панели в формате Timestamp CAST(1636717526371000 AS Timestamp)
$__toTimestamp Заменяется временем окончания диапазона, заданного на панели в формате Timestamp CAST(1636717526371000 AS Timestamp)
$__varFallback(condition, $templateVar) Заменяется первым параметром в том случае, если второй параметр не определен. $__varFallback('foo', $bar) foo если переменная bar не определена, или значение переменной $bar

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

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

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

Предыдущая
Следующая