HQbird для розробників
Для розробників застосунків
Який запит оптимізувати першим? Який код спричинив помилку? Хто утримує запис у конфлікті? Агент збирає відповіді з трасування та статистики на самому сервері. Розробник бачить їх у браузері й не входить на сервер.
- 1 хв файли трасування
- 3 вікна на день звіт про продуктивність
- за планом групування запитів
- 15 хв пошук конфліктів
- REST Local API для скриптів і CI
trace · process_traces · perf report
Звіт про продуктивність
Агент постійно тримає відкриту сесію трасування. Щохвилини він стискає вивід у файл і обчислює підсумки для кожного запиту. Коли вікно завершується, агент об'єднує хвилини у звіт: найповільніші запити та найважчі за кількістю вибірок, читань і записів. Для кожного запиту показано кількість його виконань.
- 1Сесія трасуванняfbtracemgr працює постійно; watchdog перезапускає втрачену сесію
- 2Хвилинний файлстиснений вивід трасування раз на хвилину
- 3Хвилинні підсумкидля кожного запиту: виконання, час, вибірки, читання, записи, позначки
- 4Звіт за вікнопротягом 5 хвилин після завершення вікна; до 20 запитів у кожному рейтингу
- 5✓ HQ MonitorСторінка Perf Report; посилання зі звіту про стан
Чому групувати за планом
Якщо програма вставляє значення безпосередньо в текст SQL, кожне значення дає новий текст. В одному реальному випадку кількість різних текстів зросла з 204 до 83 825 за хвилину. Тисячі «різних» запитів насправді є одним запитом з одним планом. Тому за замовчуванням агент групує запити за ключем: перші 10 символів SQL без коментарів плюс план виконання. Запит без плану зберігає свій повний текст. Ви змінюєте режим у налаштуваннях агента, поле «Perf group by»: за планом або за повним текстом SQL. За текстом файли та звіти стають значно більшими. Перемкніть режим у прикладі нижче й порівняйте рейтинги.
Запити за одну хвилину
Рейтинг за вибірками
| Таблиця звіту | Що вона показує |
|---|---|
| Top SQL by duration | Найповільніші виконання: час і кількість записів. |
| Top SQL by fetches, reads, writes | Підсумки за вікно: виконання, час, вибірки, читання, записи, позначки; частка від усього вікна; середнє та максимум на виконання. |
| Processes and Addresses | Навантаження за програмою та за адресою клієнта: з'єднання, час, кількість різних планів і запитів. |
| Query row | Повний SQL, PLAN, параметри та статистика за таблицями: natural, index, update, insert, delete, backout, purge, expunge. |
| Ten rankings in tabs | Тривалість, частота, загальний час, вибірки, читання, записи, плани, теги, процедури та тригери. Для кожної метрики ви бачите розкид значень. |
| Sample execution | Коли виконувався, який клієнт і з якої адреси, у якій базі даних. Якщо виконання завершилося помилкою, ви її бачите; кожен запит має лічильник невдалих виконань. |
| Executions by hour | Скільки разів і як довго виконувався запит у кожній годині вікна. |
| Databases | Підсумки за базами даних сервера та основними базами даних кожного запиту. |
Порівняння, історія та звіт на запит
Звіт за вікно відповідає на питання «що було важким сьогодні». Три нові функції відповідають на питання «що змінилося» та «що сталося в цю годину».
- Порівняння двох віконДва звіти поруч: які запити стали повільнішими, які з'явилися, а які зникли.
- Історія запиту за 30 днівЯк змінювалися час і кількість виконань одного запиту від вікна до вікна.
- Фільтр за базою данихЗвіт лише для однієї бази даних. Посилання на сторінці бази даних веде на сторінку звіту.
- До трасувань хвилиниВід запиту у звіті до трасувань хвилини, коли він виконувався.
- Звіт на запитКнопка Build report… будує звіт для будь-якого діапазону до 24 годин. Фільтри: база даних, мінімальна тривалість, програма. Агент будує один такий звіт за раз і зберігає останні 20.
- Пошук і завантаженняПоле пошуку за текстом запиту. Ви можете завантажити вихідний файл звіту.
- Неповний звіт позначеноЯкщо деякі файли трасування ще не надійшли, звіт позначено як неповний. Звіт зберігає лише верхівку кожного рейтингу, тому сторінка каже «не в рейтингу», а не «не виконувався».
- Процедури та тригериЦі рейтинги заповнюються, коли налаштування трасування вмикають журналювання завершення процедур і тригерів. За замовчуванням це журналювання вимкнене.
- Зі звіту про станКнопка Perf report відкриває потрібне вікно. Рядки запитів позначено, а перший уже розгорнуто.
- Запит і таблицяВкладка Queries статистики gstat пов'язує запити з таблицями та індексами, які вони читають.
- Хвилина на графіку бази данихКлік на хвилині показує важкі запити з trace та всі з'єднання цієї хвилини.
- Копіювати SQLЗ параметрами або без них — одразу у ваш власний інструмент. У демо-режимі кнопки приховані.
trace · Errors
Помилки SQL з даними клієнта
Користувач каже: «програма видала помилку». Сторінка Errors показує кожну помилку Firebird з trace: час, з'єднання, базу даних, текст і клієнта. За назвою програми, адресою та функцією Firebird ви легко знайдете помилку у своєму коді.
Блок помилки в trace
Рядок на сторінці Errors
- Однакові помилки — один рядокОдин рядок на хвилину, базу даних і тип помилки, з лічильником ×N. Підказка показує перший і останній час та кількість з'єднань.
- ФільтриInclude та Exclude за текстом, базою даних, програмою, адресою та функцією. Клік на програмі або адресі залишає лише її помилки.
- Експорт CSVУсі рядки із застосованими фільтрами, у UTF-8 з BOM: Excel одразу відкриває файл по стовпцях.
- Якщо програми немаєБагато драйверів JDBC та .NET не надсилають назву програми. Тоді рядок клієнта коротший.
trace_monitor_conflicts · find_deadlocks
Конфлікти та взаємоблокування
Помилка «update conflicts with concurrent update» сама по собі мало що говорить. Потрібно знати, що робила інша транзакція. Для цього агент тримає другу сесію trace, налаштовану на зміни даних і помилки. Кожні 15 хвилин він шукає конфлікти та будує звіт.
Як читати звіт
Ліворуч — список хвилин з конфліктами. Кожна група — це одна транзакція, що спричинила конфлікти: номер транзакції та час помилки.
Лівий стовпець показує помилки: з'єднання, програму, коди Firebird і запит, що завершився невдачею. Правий стовпець показує успішні запити конкуруючої транзакції: час, з'єднання, номер транзакції, програму. Кожен запит має свій SQL, параметри, статистику та таблиці.
Адреса сторінки зберігає дату та хвилину. Ви можете надіслати посилання колезі.
| Параметр | За замовчуванням | Значення |
|---|---|---|
| Пошук конфліктів | кожні 15 хвилин | Остання хвилина пропускається: trace ще її записує. |
| Глибина пошуку | 3 години | Скільки історії до конфлікту переглядати під час пошуку запитів іншої транзакції. |
| Зберігання сирого trace | 6 годин | Сирі файли сесії конфліктів не накопичуються на сервері. Звіти зберігаються та надсилаються до HQ Monitor. |
gstat · indexes · metadata
Як змінюється база даних
Раз на день агент знімає повну статистику gstat. HQ Monitor розбирає файл: розмір таблиць та індексів, версії записів, BLOB, глибина індексів. Вкладка «Analysis and recommendations» розповідає, що не так і що робити.
| Вкладка | Що вона дає розробнику |
|---|---|
| Таблиці | Розмір даних, індексів і BLOB, кількість записів, версії записів і максимальна кількість версій одного запису. |
| Індекси | Глибина, сторінки, унікальні значення, дублікати. Глибина 4 — жовтий рядок, 5 і більше — червоний. |
| Запити та зв'язки | Які запити читають таблицю або індекс. Дані зі звітів про продуктивність, близькі за часом до знімка. |
| Тренди | Порівняння 5, 10, 20 або 30 знімків; поріг зміни 10%, 2% або 0,5%. Прогноз «+25%» за трьома або більше знімками. |
| Експорт | JSON із вимірюваннями та Excel із повним аналізом. |
- Статистика індексівВимкнено за замовчуванням; ви вмикаєте її в налаштуваннях агента. Далі кожні 6 годин агент підраховує неактивні індекси та індекси з поганою селективністю. Індекс, не побудований після відновлення, — це серйозна проблема у звіті про стан.
- Прогноз зростанняПозначка «+25%» у таблиці баз даних показує таблицю або індекс, що найшвидше зростає, і відкриває прогноз.
- Експорт схемиАгент експортує метадані бази даних за допомогою
isql -xі зберігає архіви за датою. - Відстеження метаданихВимкнено за замовчуванням; ви вмикаєте його в налаштуваннях агента. Кожні 6 годин агент порівнює новий експорт схеми з попереднім і фіксує, коли схема змінилася.
LWM · MON$ · клієнти
З'єднання: довгі транзакції та версії клієнтів
Одна забута транзакція сповільнює всю базу даних: версії записів накопичуються, а збирання сміття зупиняється.
Щохвилини агент записує лічильники транзакцій і дані про з'єднання. На графіку бази даних Next − OAT зростає, якщо транзакція залишається відкритою довго. Таблиця з'єднань для цієї хвилини, відсортована за Act.Tran, показує програму, адресу та процес, що утримує транзакцію. Докладніше про лічильники — на сторінці стану сервера.
Раз на день агент зчитує, які клієнтські бібліотеки підключаються до бази даних і скільки з'єднань має кожна з них. Рядок «Не виявлено. Стара версія?» зазвичай означає стару клієнтську бібліотеку.
- Метрики 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, статистика індексів, метрики, останній експорт схеми, звіти трасування. |
/v1/jobs/{job}/run | Запустити завдання: резервне копіювання, відновлення, sweep, перевірка бази даних, перерахунок статистики індексів, SQL-скрипт. Повтор із тим самим ключем не запускає завдання двічі. |
Метрики Prometheus не проходять через Local API. Вони мають власну адресу: за замовчуванням 127.0.0.1, порт 25000 + порт Firebird. Вони мають власний Bearer-токен. Експорт вимкнено за замовчуванням; ви вмикаєте його в налаштуваннях агента. Метрики: LWM, CPU і пам'ять, диски, ліміти ОС, тимчасові файли.
AI-асистент в IDE
HQbird MCP з'єднує Firebird і дані агента з Claude Code, Cursor, Codex та іншими MCP-клієнтами. Асистент бачить звіти агента та працює з базою даних під контролем людини: людина підтверджує небезпечні дії.
План та індекс
План запиту та поради щодо індексів, із повторною перевіркою плану після створення індексу. Перевірка компіляції запиту перед його виконанням.
Порівняти дві бази даних
Відмінності схеми та даних, наприклад між розробкою та тестовим стендом.
План, підтвердження, відкат
Міграція з планом, одним підтвердженням і планом відкату.