Для разработчиков приложений

Какой запрос оптимизировать первым? Какой код получил ошибку? Кто держит запись при конфликте? Агент собирает ответы из trace и статистики прямо на сервере. Разработчик видит их в браузере и не заходит на сервер.

  • 1 мин файлы trace
  • 3 окна в сутки отчёт производительности
  • по плану группировка запросов
  • 15 мин поиск конфликтов
  • REST Local API для скриптов и CI

trace · process_traces · perf report

Отчёт производительности

Агент держит постоянную сессию trace. Каждую минуту он сжимает вывод в файл и считает итоги по каждому запросу. После конца окна агент сводит минуты в отчёт: самые медленные запросы и самые тяжёлые по fetches, чтениям и записям. У каждого запроса видно число выполнений.

  1. 1Сессия tracefbtracemgr работает постоянно; сторож перезапускает пропавшую сессию
  2. 2Файл минутысжатый вывод trace раз в минуту
  3. 3Итоги минутыпо каждому запросу: выполнения, время, fetches, reads, writes, marks
  4. 4Отчёт окнав течение 5 минут после конца окна; до 20 запросов в каждом рейтинге
  5. 5✓ HQ Monitorстраница Perf Report; ссылка из отчёта о здоровье
Три окна отчёта за сутки: утро 07:00–12:30, день 12:31–18:00, ночь 18:01–06:59; агент проверяет окна раз в 5 минут, поэтому отчёт появляется в течение 5 минут после конца окна
Окна по умолчанию. Утро, день и ночь. Окна и их число меняются в настройках агента. Минута без данных пропускается, отчёт всё равно строится.

Почему группировка по плану

Если программа подставляет значения прямо в текст SQL, каждое значение даёт новый текст. В одном реальном случае число разных текстов выросло с 204 до 83 825 в минуту. Тысячи «разных» запросов на деле один запрос с одним планом. Поэтому по умолчанию агент группирует запросы по ключу: первые 10 символов SQL без комментариев и план выполнения. Запрос без плана остаётся со своим полным текстом. Режим меняется в настройках агента, поле «Группировка минутной статистики»: по плану или по полному тексту SQL. По тексту файлы и отчёты становятся намного больше. Переключите режим в примере ниже и сравните рейтинги.

Запросы за минуту

    Рейтинг по fetches

      Таблица отчётаЧто показывает
      Top SQL by durationСамые медленные выполнения: время и число записей.
      Top SQL by fetches, reads, writesСуммы за окно: выполнения, время, fetches, reads, writes, marks; доля от всего окна; среднее и максимум на одно выполнение.
      Processes и AddressesНагрузка по программам и по адресам клиентов: соединения, время, число разных планов и запросов.
      Строка запросаПолный SQL, PLAN, параметры и статистика по таблицам: natural, index, update, insert, delete, backout, purge, expunge.
      Десять рейтингов во вкладкахДлительность, частота, общее время, fetches, reads, writes, планы, теги, процедуры и триггеры. У каждой метрики виден разброс значений.
      Образец запускаКогда выполнялся, какой клиент и с какого адреса, в какой базе. Если запуск закончился ошибкой, это видно; у запроса есть счётчик неудачных запусков.
      Запуски по часамСколько раз и как долго запрос выполнялся в каждый час окна.
      DatabasesИтоги по базам сервера и главные базы каждого запроса.

      Сравнение, история и отчёт по запросу

      Отчёт окна отвечает на вопрос «что было тяжёлым сегодня». Три новые функции отвечают на вопросы «что изменилось» и «что было в этот час».

      • Сравнение двух оконДва отчёта рядом: какие запросы стали медленнее, какие появились и какие ушли.
      • История запроса за 30 днейКак менялись время и число запусков одного запроса от окна к окну.
      • Фильтр по базеОтчёт только по одной базе. На страницу отчёта ведёт ссылка со страницы базы.
      • К трассам минутыОт запроса в отчёте — к трассам той минуты, когда он выполнялся.
      • Отчёт по запросуКнопка Build report… строит отчёт за любой диапазон до 24 часов. Фильтры: база, минимальная длительность, программа. Агент строит один такой отчёт за раз и хранит 20 последних.
      • Поиск и выгрузкаПоле поиска по тексту запроса. Исходный файл отчёта можно скачать.
      • Неполный отчёт отмеченЕсли часть файлов trace ещё не пришла, отчёт помечен как неполный. Отчёт хранит только верх каждого рейтинга, поэтому страница пишет «нет в рейтинге», а не «не выполнялся».
      • Процедуры и триггерыЭти рейтинги заполняются, когда в настройках trace включена запись завершения процедур и триггеров. По умолчанию она выключена.
      • Из отчёта о здоровьеКнопка Perf report открывает нужное окно. Строки запроса отмечены, первая из них уже раскрыта.
      • Запрос и таблицаВкладка Queries статистики gstat связывает запросы с таблицами и индексами, которые они читают.
      • Минута на графике базыКлик по минуте показывает тяжёлые запросы из trace и все соединения этой минуты.
      • Копировать SQLС параметрами или без, сразу в свой инструмент. В demo-режиме кнопки скрыты.

      trace · Errors

      Ошибки SQL с данными клиента

      Пользователь говорит «программа выдала ошибку». Страница Errors показывает каждую ошибку Firebird из trace: время, соединение, базу, текст и клиента. По имени программы, адресу и функции Firebird ошибку легко найти в своём коде.

      Блок ошибки в trace

      2026-10-17T12:00:05.0000 (4521:0x7f..) ERROR AT JStatement::execute /db/shop.fdb (ATT_370201, SHOP_APP:NONE, UTF8, TCPv4:10.0.0.5/50123) C:\Shop\shop.exe:7712 335544665 : violation of PRIMARY or UNIQUE KEY constraint "UK_ITEM"

      Строка на странице Errors

      tstmpattIDdb · errTxt 12:00370201/db/shop.fdb ×3 335544665 : violation of PRIMARY or UNIQUE KEY constraint "UK_ITEM" C:\Shop\shop.exe:7712 · 10.0.0.5/50123 · JStatement::execute

      • Одинаковые ошибки — одна строкаОдна строка на минуту, базу и вид ошибки, с числом ×N. Подсказка показывает первое и последнее время и число соединений.
      • ФильтрыInclude и Exclude по тексту, базе, программе, адресу и функции. Клик по программе или адресу оставляет только её ошибки.
      • Export CSVВсе строки с фильтрами, в UTF-8 с BOM: Excel сразу открывает файл по колонкам.
      • Если программы нетМногие драйверы JDBC и .NET не передают имя программы. Тогда строка клиента короче.

      trace_monitor_conflicts · find_deadlocks

      Конфликты и deadlock

      Ошибка «update conflicts with concurrent update» сама по себе мало говорит. Нужно знать, что делала вторая транзакция. Для этого агент держит вторую сессию trace, настроенную на изменения данных и ошибки. Раз в 15 минут он ищет конфликты и собирает отчёт.

      Транзакция 1001 изменила запись; транзакция 1002 пытается изменить ту же запись и получает ошибку; отчёт находит запросы транзакции 1001 по её номеру

      Как читать отчёт

      Слева список минут с конфликтами. Каждая группа — одна транзакция, из-за которой были конфликты: номер транзакции и время ошибки.

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

      Адрес страницы хранит дату и минуту. Ссылку можно отправить коллеге.

      Страница Conflicts. Минуты слева, группа транзакции справа: процесс и коды ошибки.
      ПараметрПо умолчаниюЧто значит
      Поиск конфликтовкаждые 15 минутПоследняя минута пропускается: её ещё пишет trace.
      Глубина поиска3 часаСколько истории до конфликта просматривать в поиске запросов второй транзакции.
      Хранение сырого trace6 часовСырые файлы конфликтной сессии на сервере не копятся. Отчёты хранятся и уходят в HQ Monitor.

      gstat · индексы · метаданные

      Как меняется база

      Раз в сутки агент снимает полную статистику gstat. HQ Monitor разбирает файл: размер таблиц и индексов, версии записей, BLOB, глубина индексов. Вкладка «Анализ и рекомендации» говорит, что не так и что делать.

      Анализ и рекомендации. Проблема, число случаев, объекты-ссылки, рекомендация и действие.
      Тренды. Сравнение последних снимков: что выросло и когда объект вырастет на 25%.
      ВкладкаЧто даёт разработчику
      TablesРазмер данных, индексов и BLOB, число записей, версии записей и максимум версий одной записи.
      IndexesГлубина, страницы, уникальные значения, дубликаты. Глубина 4 — жёлтая строка, 5 и больше — красная.
      Queries и LinksКакие запросы читают таблицу или индекс. Данные из отчётов производительности, близких по времени к снимку.
      TrendsСравнение 5, 10, 20 или 30 снимков; порог изменения 10%, 2% или 0,5%. Прогноз «+25%» по трём снимкам и больше.
      ВыгрузкаJSON с измерениями и Excel с полным анализом.
      • Статистика индексовПо умолчанию выключена, включается в настройках агента. Затем раз в 6 часов агент считает неактивные индексы и индексы с плохой селективностью. Индекс, не построенный после restore, — serious в отчёте о здоровье.
      • Прогноз ростаЧип «+25%» в таблице баз показывает самую быстрорастущую таблицу или индекс и открывает прогноз.
      • Выгрузка схемыАгент выгружает метаданные базы через isql -x и хранит архивы по датам.
      • Отслеживание метаданныхПо умолчанию выключено, включается в настройках агента. Раз в 6 часов агент сравнивает новую выгрузку схемы с предыдущей и записывает, когда схема изменилась.

      LWM · MON$ · клиенты

      Соединения: долгие транзакции и версии клиентов

      Одна забытая транзакция тормозит всю базу: версии записей копятся, сборка мусора стоит.

      Агент каждую минуту пишет счётчики транзакций и данные соединений. На графике базы растёт Next − OAT, если транзакция долго открыта. Таблица соединений этой минуты, отсортированная по Act.Tran, показывает программу, адрес и процесс, который держит транзакцию. Подробнее о счётчиках — на странице о состоянии сервера.

      Раз в сутки агент читает, какие клиентские библиотеки подключаются к базе и сколько у каждой соединений. Строка «Not detected. Old version?» обычно значит старую клиентскую библиотеку.

      Версии клиентов. Строка версии от клиента и число соединений. Соединения самого агента видны отдельной строкой.
      • Метрики MON$Раз в час: память по программам, 5 соединений с наибольшей памятью и 5 с наибольшей нагрузкой.
      • Старые клиенты без ложных тревогНаходка «старые клиенты» считает только библиотеки fbclient. Драйверы, которые работают без fbclient, в неё не попадают.
      • Долгие транзакции в отчётеОтчёт о здоровье отмечает долгие транзакции и рост Next − OAT. Находка называет пользователя, программу и адрес и даёт готовую команду отключения.

      Local API · Prometheus · HQbird MCP

      Свои скрипты, CI и AI-ассистент

      Всё, что видно в HQ Monitor, доступно из своих инструментов. Local API агента слушает только loopback, каждый запрос несёт Bearer-токен. Тяжёлые задания запускаются асинхронно: ответ даёт номер операции, статус читается по нему. Каждый запрос, который меняет сервер, и каждый отказ 401 или 403 агент пишет в журнал аудита. Запросы на чтение в журнал не попадают.

      # порт Local API = 10000 + порт Firebird: в примере Firebird на 3055, поэтому 13055
      # состояние сервера: тот же снимок, что в отчёте о здоровье
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/status
      # последний отчёт производительности и последний отчёт о конфликтах
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/perf-report/latest
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/deadlocks/latest
      # запустить бэкап перед миграцией в CI и ждать результата
      curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"job_id":"nightly","reason":"before migration"}' \
           http://127.0.0.1:13055/v1/jobs/vbackup/run
      curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/runs/<run_id>
      ПутьЧто даёт
      /v1/statusСнимок состояния сервера целиком или по разделу, например бэкапы.
      /v1/databasesСписок активных баз.
      /v1/artifacts/…Данные агента: LWM (Light-weight Monitoring) за минуту, gstat, статистика индексов, метрики, последняя выгрузка схемы, отчёты trace.
      /v1/jobs/{job}/runЗапуск задания: бэкап, restore, sweep, проверка базы, пересчёт индексов, SQL-скрипт. Повтор с тем же ключом не запускает задание дважды.

      Метрики для Prometheus идут не через Local API. У них свой адрес: по умолчанию 127.0.0.1, порт 25000 + порт Firebird. У них свой Bearer-токен. Экспорт по умолчанию выключен и включается в настройках агента. Метрики: LWM, CPU и память, диски, лимиты ОС, temp-файлы.

      AI-ассистент в IDE

      HQbird MCP подключает Firebird и данные агента к Claude Code, Cursor, Codex и другим MCP-клиентам. Ассистент видит отчёты агента и работает с базой под контролем человека: опасные действия подтверждает человек.

      Запрос

      План и индекс

      План запроса и совет по индексу, с перепроверкой плана после создания индекса. Проверка компиляции запроса до выполнения.

      Схема

      Сравнение двух баз

      Разница схем и данных, например разработки и тестового стенда.

      Миграция

      План, подтверждение, откат

      Миграция с планом, одним подтверждением и планом отката.

      Подробнее: HQbird MCP

      ← Вернуться к обзору HQbird 2027 · Состояние сервера подробно →