¶ DBTrace
DBTrace — утилита для запуска пользовательской трассировки Firebird через fbtracemgr.exe, сохранения исходного trace-лога и формирования отчетов по событиям, ошибкам и времени выполнения SQL-запросов.
Программа рассчитана на обычный рабочий сценарий: выбрать установленный Firebird, добавить одну или несколько баз, настроить состав событий, запустить трассировку, воспроизвести проблему, остановить трассировку и сформировать отчеты.
Билд программы находится в папке:
\\\Secure FTP\Share42\Agbis\_NonVersion\
¶ Для чего нужна программа
DBTrace позволяет работать с Firebird Trace без ручного запуска fbtracemgr из командной строки.
С помощью программы можно:
- трассировать одну или несколько баз в одной пользовательской trace-сессии;
- выбирать нужные виды событий;
- использовать готовые профили трассировки;
- ограничивать события по времени, соединению, регулярным выражениям SQL и кодам GDS;
- записывать планы и показатели производительности запросов;
- получать исходный trace-лог, сводку, отчет об ошибках и отчет по медленным SQL;
- видеть фактическое время выполнения завершенных SQL-запросов.
¶ Первый запуск
При запуске DBTrace автоматически ищет установленные экземпляры Firebird и показывает их в верхней части формы.
Программа работает с локальным сервером 127.0.0.1. Для подключения к службе Firebird используются:
- пользователь —
SYSDBA; - пароль —
masterkey; - служба —
service_mgr.
Пароль и сгенерированное имя trace-сессии в DBTrace.ini не сохраняются.
Выберите Firebird, который обслуживает нужную базу. Порт и путь к fbtracemgr.exe будут подставлены автоматически. Если автоматический поиск не дал нужного результата, порт можно указать вручную.
¶ Добавление базы
- Откройте вкладку
Базы. - Нажмите
Добавить. - Выберите добавленную базу в списке слева.
- Нажмите
Выбратьи укажите файл базы, напримерE:\Agbis\DB\ARM.FDB. - Убедитесь, что установлен флажок
Включить базу.
Параметры справа относятся только к выбранной базе. Для каждой базы сохраняется собственный набор настроек.
¶ Основные настройки трассировки базы
¶ Что трассировать
SQL— начало и завершение SQL-запросов;Транзакции— начало, подтверждение и откат транзакций;Соединения— подключения и отключения;Процедуры— выполнение хранимых процедур;Триггеры— выполнение триггеров.
¶ Что показывать
Ошибки— ошибки Firebird;Предупреждения— предупреждения Firebird.
¶ Медленные SQL от, мс
Это порог на уровне Firebird Trace (time_threshold). Он определяет, какие события Firebird запишет в исходный trace-лог.
Например, значение 1000 означает, что Firebird будет отбирать события с порогом 1000 мс. Значение 0 отключает ограничение и создает наиболее подробный лог.
Порог на вкладке
Базыи порог на вкладкеОтчетывыполняют разные задачи. Первый ограничивает сбор исходного лога, второй фильтрует уже собранные данные при формированииslow_sql.txt.
¶ Вкладка «Дополнительно»
Вкладка содержит готовые профили и точные параметры Firebird Trace для выбранной базы.
¶ Профили трассировки
Пользовательский— текущий набор параметров без автоматического изменения;Медленные SQL— SQL, ошибки и предупреждения, порог 1000 мс;SQL с планами— все SQL с обычным и подробным планами, порог 0 мс;Ошибки и предупреждения— только диагностические сообщения;Соединения— подключения и транзакции;Процедуры и триггеры— процедуры, функции и триггеры;Полная диагностика— все поддерживаемые события, планы, контекст и sweep, порог 0 мс.
Профиль меняет параметры выбранной базы, но не меняет путь к базе, флажок Включить базу и ограничения длины SQL/аргументов. После выбора профиля параметры можно скорректировать вручную.
¶ Дополнительные события
- подготовка SQL (
log_statement_prepare); - освобождение SQL (
log_statement_free); - PSQL-функции;
- контекст соединения;
- sweep;
- обычный план (
print_plan); - подробный план (
explain_plan).
¶ Ограничения и фильтры
ID соединения— трассировать только указанное подключение;0означает все подключения;Максимальная длина SQL— от 300 до 32768 символов, по умолчанию 4096;Максимальная длина аргумента— от 0 до 8192 символов, по умолчанию 256;Максимальное число аргументов— от 0 до 1000, по умолчанию 30;- фильтр включения SQL — регулярное выражение Firebird
include_filter; - фильтр исключения SQL — регулярное выражение Firebird
exclude_filter; - включаемые коды GDS —
include_gds_codes; - исключаемые коды GDS —
exclude_gds_codes.
Пустое поле означает, что соответствующий фильтр не используется. Синтаксис регулярных выражений проверяет Firebird при запуске trace-сессии.
¶ Несколько баз в одной трассировке
Добавьте базы в список и настройте каждую отдельно. В trace-конфиг попадают только базы с установленным флажком Включить базу.
DBTrace запускает одну пользовательскую trace-сессию с отдельной секцией database для каждой включенной базы. Вывод fbtracemgr сохраняется в общий исходный лог текущего запуска.
¶ Запуск трассировки
Перед запуском проверьте:
- выбран правильный Firebird;
- порт соответствует нужной службе Firebird;
- добавлена хотя бы одна включенная база;
- у каждой включенной базы указан путь;
- числовые ограничения находятся в допустимом диапазоне.
Нажмите Старт. DBTrace сохранит активный trace-конфиг и запустит fbtracemgr в фоне.
Конфигурация всегда включает print_perf = true. Благодаря этому завершенные SQL-события содержат время выполнения и счетчики чтений, записей и выборок.
Активный лог создается в папке:
Temp\trace_log
Пример имени:
ARM_trace_20260813_150503.log
¶ Работа при активной трассировке
Если закрыть окно крестиком во время активной трассировки, DBTrace не завершится, а свернется в область уведомлений Windows. Чтобы вернуть окно, дважды нажмите значок DBTrace в трее.
Если трассировка не запущена, крестик закрывает программу.
¶ Остановка трассировки
Нажмите Стоп. DBTrace отправит команду остановки созданной им trace-сессии, дождется завершения своего процесса fbtracemgr и добавит время остановки к имени лога.
Пример:
ARM_trace_20260813_150503__20260813_151245.log
DBTrace управляет только тем процессом и той trace-сессией, которые запустил сам. Программа не завершает посторонние процессы fbtracemgr.exe.
¶ Где хранятся файлы
Рабочая папка Temp создается рядом с DBTrace.exe. Если программа уже запущена из папки с именем Temp, вложенная папка Temp\Temp не создается.
Основные файлы:
Temp\DBTrace.ini— сохраненная пользовательская сессия и настройки отчетов;Temp\fbtrace.active.conf— последний сформированный trace-конфиг;Temp\trace_log\*.log— новые и еще не обработанные trace-логи;Temp\trace_log\trace_*\— папки сформированных отчетов.
После построения отчета выбранный лог переносится в папку отчета и исчезает из списка необработанных логов.
¶ Построение отчетов
- Откройте вкладку
Отчеты. - Выберите исходный лог в поле
Лог. - Укажите порог
SQL от, мс. - При необходимости включите
Скрывать системные SQL Firebird. - Нажмите
Сформировать.
Порог отчета применяется к уже записанным завершенным запросам. При значении 0 в отчет попадут все завершенные выполнения, включая очень быстрые.
Флажок Скрывать системные SQL Firebird исключает запросы к системным объектам RDB$, MON$ и SEC$. Настройка включена по умолчанию и сохраняется вместе с порогом отчета.
Фильтр намеренно не скрывает обычные SELECT к пользовательским таблицам. Такие запросы мог выполнить как пользователь, так и клиентская программа, и надежно отличить их по trace-логу невозможно.
¶ Почему один SQL больше не дублируется
Firebird обычно пишет два события одного выполнения:
EXECUTE_STATEMENT_START— запрос начался, итогового времени еще нет;EXECUTE_STATEMENT_FINISH— запрос завершился, указано фактическое время.
slow_sql.txt учитывает только EXECUTE_STATEMENT_FINISH. Поэтому один завершенный запрос появляется в отчете один раз. Для старых архивных логов без стандартного имени события используется наличие измеренного времени.
¶ Почему в исходном логе запросов больше, чем действий пользователя
Trace фиксирует все подходящие запросы, пришедшие на Firebird. Например, IBExpert может автоматически читать метаданные, ограничения, поля и повторно загружать измененную запись. DBTrace не создает эти запросы, а только записывает события сервера.
Системные запросы можно убрать из отчета соответствующим флажком. Обычные запросы к пользовательским таблицам останутся видимыми.
¶ Где находится время выполнения
Фактическое время есть в завершенном событии EXECUTE_STATEMENT_FINISH и выводится в slow_sql.txt строкой вида:
Дата события: 13.08.2026 15:05:07.106
Время: 28 ms | БД: ARM | Conn: 1 | Tran: 2
Следом выводятся счетчики Records, Reads, Writes, Fetches, Marks, текст SQL и план, если Firebird его предоставил.
¶ Содержимое папки отчета
Папка создается внутри Temp\trace_log и называется по времени начала и остановки:
trace_20260813_150503_20260813_151245
Внутри находятся:
- исходный trace-лог;
summary.txt— количество событий, среднее и максимальное время SQL, суммарные показатели чтения/записи/выборки;errors.txt— ошибки и предупреждения Firebird;slow_sql.txt— завершенные SQL-запросы, прошедшие порог и фильтр системного SQL.
Все сформированные отчеты сохраняются в UTF-8.
¶ Кодировка trace-лога и отчетов
DBTrace сначала читает исходный лог как UTF-8. Если конкретная версия fbtracemgr в Windows записала вывод в OEM-кодировке консоли, программа автоматически повторяет чтение в OEM-кодировке.
Отчеты всегда сохраняются в UTF-8. Это устраняет ошибку No mapping for the Unicode character exists in the target multi-byte code page при формировании отчета с символами, отсутствующими в системной ANSI-кодировке.
¶ Что делать, если лог не появился
Проверьте:
- выбран ли правильный Firebird и порт;
- существует ли файл базы;
- включена ли база;
- соответствует ли имя файла базы созданной маске;
- выполнялись ли действия после запуска трассировки;
- не установлен ли слишком высокий порог времени;
- не исключает ли нужный SQL фильтр
exclude_filter.
Если после старта в базе ничего не происходило, лог может быть пустым или почти пустым.
¶ Что делать при ошибке запуска Firebird Trace
Наиболее частые причины:
- выбран неправильный Firebird или порт;
- путь к
fbtracemgr.exeбольше не существует; - не добавлена ни одна включенная база;
- у базы не указан путь;
- ошибочно задано регулярное выражение SQL;
- указаны неподдерживаемые конкретной версией Firebird параметры;
- другая trace-сессия или права пользователя мешают запуску.
Для диагностики проверьте сообщение в строке состояния и файл Temp\fbtrace.active.conf. DBTrace показывает вывод fbtracemgr, а пароль в диагностических командных строках маскируется.
¶ Сохранение настроек
При закрытии DBTrace сохраняет выбранный Firebird, порт, список баз, все параметры трассировки, порог отчета и флажок системного SQL в Temp\DBTrace.ini.
После обновления программы старый INI остается совместимым: отсутствующие параметры получают безопасные значения по умолчанию.
¶ Краткий рабочий сценарий
- Запустите DBTrace.
- Выберите Firebird и проверьте порт.
- Добавьте и включите базу.
- Выберите профиль или настройте события вручную.
- Нажмите
Старт. - Воспроизведите диагностируемую операцию.
- Нажмите
Стоп. - Откройте вкладку
Отчеты. - Выберите лог и задайте порог.
- Оставьте включенным скрытие системного SQL, если метаданные Firebird не нужны.
- Нажмите
Сформировать. - Откройте созданную папку в
Temp\trace_log.
¶ Проверка качества
Основные сценарии DBTrace покрыты автоматическими тестами DUnitX: параметры trace-конфига и их ограничения, сохранение INI без пароля, форматы событий Firebird, кодировки, время выполнения, планы, счетчики производительности, отчеты, исключение событий START и фильтр системного SQL.