DB Query

Материал из Документация Ключ-АСТРОМ
Версия от 18:10, 15 сентября 2026; Aleksandr.Zubarev (обсуждение | вклад)
(разн.) ← Предыдущая версия | Текущая версия (разн.) | Следующая версия → (разн.)

Расширение DB Query для Ключ-АСТРОМ

Расширение DB Query предназначено для мониторинга баз данных через выполнение пользовательских запросов и извлечения метрик. Оно поддерживает основные реляционные СУБД и MongoDB, позволяя превращать результаты запросов в метрики и измерения Ключ-АСТРОМ.

Возможности расширения

  • Подключение к базам данных PostgreSQL, Oracle, MySQL, MariaDB, SQL Server и MongoDB.
  • Выполнение произвольных запросов (SQL или MongoDB-команд) и преобразование результатов в метрики и размерности.
  • Настройка интервала выполнения запросов и расписания запуска по времени.
  • Ограничение времени выполнения запроса.
  • Проверка доступности подключения лёгким запросом (fastcheck).
  • Создание сущностей DB Query Host и DB Query Endpoint с топологическими связями.
  • Готовый обзорный дашборд.
  • Отображение ошибок подключения и выполнения в статусе расширения.

Поддерживаемые базы данных

  • PostgreSQL
  • Oracle
  • MySQL
  • MariaDB
  • SQL Server
  • MongoDB

Требования

  • АктивныйШлюз с включённым выполнением расширений (или ЕдиныйАгент с EEC).
  • Сетевой доступ к базе данных.
  • Учётные данные с правами на выполнение запросов.
  • Для MongoDB — зависимость pymongo (включена в расширение).

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

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

Поддерживаемые базы данных:

  • PostgreSQL
  • Oracle Database
  • MySQL
  • MariaDB
  • Microsoft SQL Server
  • MongoDB

Настройка подключения

Подключение можно настроить с помощью отдельных полей или строки JDBC connection string.

Если строка подключения указана внутри endpoint, она имеет приоритет над общей строкой подключения. Отсутствующие в строке имя пользователя и пароль берутся из общих полей DB user и DB password.

Пароль рекомендуется хранить в секретном поле DB password, а не включать в строку подключения.

Поддерживаются строки подключения PostgreSQL, Oracle, MySQL, MariaDB, SQL Server, MongoDB и MongoDB SRV.

Параметр Значение по умолчанию Описание
DB name — Тип базы данных: Postgres, Oracle, MySQL, MariaDB, SQLServer или MongoDB. Можно не заполнять, если тип определяется из строки подключения.
Host — IP-адрес или DNS-имя сервера. Можно не заполнять, если адрес указан в строке подключения.
DB port Стандартный порт СУБД Порт сервера базы данных.
DB user — Имя пользователя базы данных.
DB password — Пароль пользователя. Значение хранится как секрет.
JDBC connection string — Необязательная строка подключения. Максимальная длина — 2000 символов.
Query interval (minutes) 1 Интервал выполнения запросов без индивидуального расписания.
Query timeout (seconds) 600 Общий таймаут запроса. Допустимый диапазон — от 1 до 86400 секунд.
Max rows per query 10000 Максимальное количество строк или документов, получаемых одним запросом. Значение 0 отключает ограничение.
Max parallel queries 4 Количество одновременно выполняемых endpoint. Допустимый диапазон — от 1 до 20.

Настройка endpoint

Конфигурация должна содержать от 1 до 100 endpoint. Каждый endpoint описывает один запрос и правила преобразования его результата в метрики.

Параметр Обязательный Описание
Endpoint Name Да Уникальное имя запроса. Используется при формировании ключа метрики. Рекомендуется использовать латинские буквы в нижнем регистре, цифры и символ подчёркивания.
DBase name Условно Имя базы данных. Для Oracle указывается service name, PDB service или SID. Можно не заполнять, если имя базы содержится в строке подключения.
JDBC connection string Нет Строка подключения только для этого endpoint. Позволяет разным endpoint обращаться к разным серверам и базам данных.
Query Да SQL-запрос для реляционной базы данных или JSON-команда для MongoDB. Максимальная длина — 10000 символов.
Schedule (cron or HH:MM) Нет Индивидуальное расписание выполнения запроса по локальному времени АктивногоШлюза.
Query timeout (seconds) Нет Индивидуальный таймаут endpoint. Имеет приоритет над общим таймаутом.
Dimension columns Нет Имена или порядковые номера колонок, которые используются как измерения. Несколько значений разделяются запятыми.
Metric columns Нет Имена или порядковые номера числовых колонок, которые отправляются как метрики. Несколько значений разделяются запятыми.

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

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

Если поле Schedule (cron or HH:MM) не заполнено, запрос выполняется через интервал, заданный в Query interval (minutes).

Поддерживаются:

  • точное время в формате HH:MM, например 09:00;
  • несколько значений времени через запятую, например 09:00,18:30;
  • cron из пяти полей, например */15 * * * * или 0 9 * * 1-5;
  • макросы @hourly, @daily, @weekly, @monthly и @yearly;
  • несколько расписаний через точку с запятой.

Секунды в cron-выражениях не поддерживаются. Запрос выполняется в течение пяти минут после расчётного времени и не более одного раза для каждого слота расписания.

Преобразование результата в метрики

Поле Metric columns определяет числовые колонки, которые отправляются как метрики. Если оно не заполнено, числовые колонки определяются автоматически.

Поле Dimension columns определяет колонки, которые добавляются как измерения. Если оно не заполнено, измерениями становятся все колонки, не выбранные как метрики.

При одной метрической колонке ключ формируется следующим образом: 

ru.ruscomtech.dbquery.<endpoint>

При нескольких метрических колонках к ключу добавляется имя колонки: 

ru.ruscomtech.dbquery.<endpoint>.<column>

Во все метрики автоматически добавляются измерения с адресом сервера, портом, типом базы данных, именем базы и именем endpoint.

Для MongoDB поле Query принимает JSON-команду. Поддерживаются операции find, find_one, count_documents, estimated_document_count и aggregate.

Проверка конфигурации

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

Для реляционных СУБД выполняется короткий запрос SELECT 1. Для Oracle используется SELECT 1 FROM dual, для MongoDB — команда ping.

Ошибки конфигурации, подключения, аутентификации и выполнения запросов отображаются в статусе расширения.

Метрики

  • ru.ruscomtech.dbquery.host.status — состояние настроенного хоста DB Query.
  • ru.ruscomtech.dbquery.query.duration — продолжительность выполнения запроса в миллисекундах.
  • ru.ruscomtech.dbquery.query.timeout — признак превышения таймаута: 1, если запрос завершён по таймауту, иначе 0.

История версий

Версия 0.3.1

  • Добавлена поддержка строки подключения JDBC connection string на уровне расширения и отдельного endpoint. Поддерживаются PostgreSQL, Oracle, MySQL, MariaDB, SQL Server и MongoDB.
  • Поля подключения можно не заполнять, если необходимые параметры указаны в строке подключения.
  • Расписание запуска поддерживает cron из пяти полей, макросы @hourly, @daily, @weekly, @monthly, @yearly и прежний формат HH:MM.
  • Таймаут запроса теперь задаётся в секундах. Его можно переопределить для отдельного endpoint.
  • Добавлены ограничения Max rows per query и Max parallel queries.
  • Добавлено параллельное выполнение endpoint.
  • Добавлены метрики ru.ruscomtech.dbquery.query.duration и ru.ruscomtech.dbquery.query.timeout.

Версия 0.2.30

  • Лимит поля Query увеличен до 10000 символов.
  • Добавлено поле Query timeout (minutes) для ограничения времени выполнения одного запроса. По умолчанию 10 минут; применяется для Postgres, Oracle, MySQL, MariaDB, SQLServer и MongoDB.
  • Добавлено поле Execution times для запуска конкретного endpoint по расписанию. Формат: HH:MM по локальному времени хоста/АктивногоШлюза; несколько значений через запятую, например 09:00,18:30.
  • Запуск по Execution times выполняется в окне от указанного времени до +5 минут. Если поле пустое, endpoint выполняется по старому правилу через Query interval (minutes).
  • fastcheck() проверяет подключение к БД лёгким запросом: MongoDB — ping, Oracle — SELECT 1 FROM dual, MySQL/MariaDB/SQLServer — SELECT 1, Postgres — SELECT 1.
  • Ошибки выполнения query больше не отображаются как OK: последняя ошибка endpoint сохраняется и возвращается в runtime status.
  • Ошибки подключения, авторизации и конфигурации мапятся в соответствующие StatusValue; ошибка Oracle DPY-6005: cannot connect to database классифицируется как DEVICE_CONNECTION_ERROR.
  • Исправлена ошибка UnboundLocalError после неуспешного подключения к MongoDB или другой БД.
  • Русифицированы описания полей.
  • Добавлена служебная метрика ru.ruscomtech.dbquery.host.status для отображения DB Query Host на overview dashboard.
  • Плитка DB Query Host теперь содержит Data Explorer query и показывает хосты по device.address.
  • Метрика ru.ruscomtech.dbquery.host.status отправляется в каждом цикле query() для валидной конфигурации, даже если endpoint пропущен по расписанию или интервалу.

Версия 0.2.11

  • Добавлена поддержка MongoDB.
  • Добавлена зависимость pymongo.
  • Для MongoDB поле query принимает JSON:
    • raw MongoDB command для выполнения через db.command(...);
    • wrapper с collection и operation.
  • Поддержанные операции MongoDB: find, find_one, count_documents, estimated_document_count, aggregate.
  • Поля dimension_columns и metric_columns работают для MongoDB по возвращаемым полям документов, так же как для SQL-колонок.

Версия 0.2.10

  • Добавлены topology entities для DB Query Host и DB Query Endpoint.
  • Добавлен overview dashboard.

Версия 0.2.1

  • Добавлена поддержка Oracle.
  • Добавлена функция ожидания после каждого выполнения.

Примеры конфигурации

Пример MongoDB count

{
  "name": "mongo_orders_open",
  "db_name": "mydb",
  "query": "{\"collection\":\"orders\",\"operation\":\"count_documents\",\"filter\":{\"status\":\"open\"}}",
  "metric_columns": "count"
}

Пример MongoDB aggregate

{
  "name": "mongo_orders_by_status",
  "db_name": "mydb",
  "query": "{\"collection\":\"orders\",\"operation\":\"aggregate\",\"pipeline\":[{\"$group\":{\"_id\":\"$status\",\"total\":{\"$sum\":1}}}]}",
  "dimension_columns": "_id",
  "metric_columns": "total"
}
Источник — https://doc.ruscomtech.ru/index.php?title=DB_Query&oldid=6674