DB Query

Материал из Документация Ключ-АСТРОМ
Версия от 23:24, 22 октября 2026; Azubarev (обсуждение | вклад) ([wiki-cd:ruscomtech-extensions:b0985a6744c086353b26ac217dfa652296b8c814])
(разн.) ← Предыдущая версия | Текущая версия (разн.) | Следующая версия → (разн.)

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

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

Текущая версия — 0.3.9. Идентификатор расширения: ru.ruscomtech.dbquery.

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

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

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

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

Требования

  • Ключ-АСТРОМ 1.290.0+.
  • АктивныйШлюз с включённым контроллером выполнения расширений (EEC). Поддерживается только удалённое выполнение; запуск на ЕдиномАгенте не предусмотрен.
  • Среда Python не ниже 3.10 в составе EEC. Драйверы поставляются в пакете; устанавливать зависимости в системный Python не требуется.
  • Сетевой доступ к базе данных.
  • Учётные данные с правами на выполнение запросов.
  • Для MongoDB — зависимость pymongo (включена в расширение).

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

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

Загрузите подписанный ZIP-пакет в раздел Расширения, активируйте версию 0.3.9, создайте конфигурацию удалённого мониторинга и выберите группу АктивныхШлюзов. Затем заполните общие параметры подключения и добавьте запросы в список endpoint.

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

Подключение можно настроить с помощью отдельных полей или строки 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–1000000; 0 отключает ограничение.
  • Max parallel queries — количество одновременно выполняемых endpoint: по умолчанию 4, диапазон 1–20.

Настройка endpoint

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

  • Endpoint Name — обязательное уникальное имя запроса, участвующее в ключе метрики. Рекомендуются латинские буквы в нижнем регистре, цифры и подчёркивание.
  • DBase name — имя базы данных; для Oracle — service name, PDB service или SID. Можно не заполнять, если оно содержится в строке подключения.
  • JDBC connection string — необязательная строка подключения только этого endpoint; имеет приоритет над общей.
  • Query — обязательный SQL-запрос либо JSON-команда MongoDB; максимум 10000 символов.
  • Schedule (cron or HH:MM) — необязательное индивидуальное расписание по локальному времени АктивногоШлюза.
  • Query timeout (seconds) — необязательный таймаут endpoint; имеет приоритет над общим.
  • Flatten JSON/JSONB fields (flatten_json) — разворачивать вложенные объекты и массивы результата реляционного запроса в отдельные колонки; по умолчанию выключено.
  • 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.

Вложенные JSON/JSONB-значения

Включите Flatten JSON/JSONB fields (flatten_json) у endpoint, если драйвер реляционной СУБД возвращает в колонках объекты или массивы. Вложенные ключи разделяются точками, а индексы массивов начинаются с 0.

Например, колонка payload содержит объект: 

{"stats":{"count":42},"region":"eu","items":[{"value":7}]}

После разворачивания доступны колонки payload.stats.count, payload.region и payload.items.0.value. Укажите payload.stats.count,payload.items.0.value в Metric columns и payload.region в Dimension columns. Использование имён надёжнее номеров при изменении структуры JSON.

Функция работает с объектами и массивами, возвращёнными драйвером. Строка, содержащая JSON-текст, автоматически не разбирается: при необходимости преобразуйте её в поддерживаемый драйвером JSON-тип на стороне запроса. Документы MongoDB разворачиваются отдельно при обработке результата и не требуют включения этого флажка.

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

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

Для реляционных СУБД выполняется короткий запрос 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.

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

Следующие фрагменты описывают отдельные endpoint; общие параметры подключения и учётные данные задаются в конфигурации мониторинга.

MongoDB: количество открытых заказов

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

MongoDB: количество заказов по статусам

{
  "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"
}

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

Версия 0.3.9

Версия расширения для Ключ-АСТРОМ 1.290.0+, с удалённым выполнением на АктивномШлюзе и Python 3.10+ в составе EEC.

  • Добавлен параметр flatten_json для разворачивания вложенных JSON/JSONB-объектов и массивов результата реляционного запроса.
  • Вложенные поля доступны для выбора метрик и измерений по составным именам с разделителем . и индексами массивов от 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.
  • Добавлена функция ожидания после каждого выполнения.
Источник — https://doc.ruscomtech.ru/index.php?title=DB_Query&oldid=7235