HQbird для разработчиков
Для разработчиков приложений
Какой запрос оптимизировать первым? Какой код получил ошибку? Кто держит запись при конфликте? Агент собирает ответы из trace и статистики прямо на сервере. Разработчик видит их в браузере и не заходит на сервер.
- 1 мин файлы trace
- 3 окна в сутки отчёт производительности
- по плану группировка запросов
- 15 мин поиск конфликтов
- REST Local API для скриптов и CI
trace · process_traces · perf report
Отчёт производительности
Агент держит постоянную сессию trace. Каждую минуту он сжимает вывод в файл и считает итоги по каждому запросу. После конца окна агент сводит минуты в отчёт: самые медленные запросы и самые тяжёлые по fetches, чтениям и записям. У каждого запроса видно число выполнений.
- 1Сессия tracefbtracemgr работает постоянно; сторож перезапускает пропавшую сессию
- 2Файл минутысжатый вывод trace раз в минуту
- 3Итоги минутыпо каждому запросу: выполнения, время, fetches, reads, writes, marks
- 4Отчёт окнав течение 5 минут после конца окна; до 20 запросов в каждом рейтинге
- 5✓ HQ Monitorстраница Perf Report; ссылка из отчёта о здоровье
Почему группировка по плану
Если программа подставляет значения прямо в текст 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
Строка на странице Errors
- Одинаковые ошибки — одна строкаОдна строка на минуту, базу и вид ошибки, с числом ×N. Подсказка показывает первое и последнее время и число соединений.
- ФильтрыInclude и Exclude по тексту, базе, программе, адресу и функции. Клик по программе или адресу оставляет только её ошибки.
- Export CSVВсе строки с фильтрами, в UTF-8 с BOM: Excel сразу открывает файл по колонкам.
- Если программы нетМногие драйверы JDBC и .NET не передают имя программы. Тогда строка клиента короче.
trace_monitor_conflicts · find_deadlocks
Конфликты и deadlock
Ошибка «update conflicts with concurrent update» сама по себе мало говорит. Нужно знать, что делала вторая транзакция. Для этого агент держит вторую сессию trace, настроенную на изменения данных и ошибки. Раз в 15 минут он ищет конфликты и собирает отчёт.
Как читать отчёт
Слева список минут с конфликтами. Каждая группа — одна транзакция, из-за которой были конфликты: номер транзакции и время ошибки.
В левой колонке ошибки: соединение, программа, коды Firebird и запрос, который не прошёл. В правой колонке успешные запросы конкурирующей транзакции: время, соединение, номер транзакции, программа. У каждого запроса есть SQL, параметры, статистика и таблицы.
Адрес страницы хранит дату и минуту. Ссылку можно отправить коллеге.
| Параметр | По умолчанию | Что значит |
|---|---|---|
| Поиск конфликтов | каждые 15 минут | Последняя минута пропускается: её ещё пишет trace. |
| Глубина поиска | 3 часа | Сколько истории до конфликта просматривать в поиске запросов второй транзакции. |
| Хранение сырого trace | 6 часов | Сырые файлы конфликтной сессии на сервере не копятся. Отчёты хранятся и уходят в HQ Monitor. |
gstat · индексы · метаданные
Как меняется база
Раз в сутки агент снимает полную статистику gstat. HQ Monitor разбирает файл: размер таблиц и индексов, версии записей, BLOB, глубина индексов. Вкладка «Анализ и рекомендации» говорит, что не так и что делать.
| Вкладка | Что даёт разработчику |
|---|---|
| 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 2027 · Состояние сервера подробно →