¶ DBTrace
DBTrace — утилита для запуска пользовательской трассировки Firebird через fbtracemgr.exe, сохранения исходного trace-лога и формирования отчетов по событиям, ошибкам и времени выполнения SQL-запросов.
Если говорить совсем просто, DBTrace — это «черный ящик» для программы, работающей с базой Firebird. Пока DBTrace включен, он записывает, что происходило на сервере: какие запросы запускались, какие процедуры и триггеры выполнялись, были ли ошибки и сколько времени заняли завершенные операции. Эти сведения помогают программисту понять причину зависания, медленной работы или ошибки.
Обычному пользователю не требуется знать SQL, устройство базы или параметры Firebird Trace. Для первого сбора почти всегда достаточно рекомендуемого пресета — DBTrace сама выставит безопасный и достаточно полный набор настроек.
Билд программы находится в папке:
\\\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.
Пароль в DBTrace.ini не сохраняется. Техническое имя активной trace-сессии сохраняется: оно нужно, чтобы после перезапуска DBTrace найти уже работающую серверную сессию и не запустить дубликат.
Выберите 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
¶ Работа при активной трассировке и перезапуск Firebird
Если закрыть окно крестиком во время активной трассировки или ожидания Firebird, DBTrace не завершится, а свернется в область уведомлений Windows. Чтобы вернуть окно, дважды нажмите значок DBTrace в трее.
Если трассировка не запущена, крестик закрывает программу.
DBTrace проверяет состояние своего fbtracemgr каждые 5 секунд. Если Firebird был перезапущен, серверная trace-сессия и обслуживающий ее fbtracemgr завершаются. DBTrace замечает это и с интервалом 15 секунд пытается создать новую trace-сессию. После возвращения Firebird сбор продолжается автоматически, новые события дописываются в тот же активный лог.
В строке состояния и подсказке значка в трее отображается, работает трассировка или ожидается восстановление Firebird.
Если перезапущен сам DBTrace, программа читает сохраненное техническое имя сессии и сначала проверяет, не продолжает ли прежняя серверная сессия работать. Если она существует, дубликат не создается. Если сессия потеряна, DBTrace запускает новую и продолжает тот же сбор.
Важно:
- кнопка
Стопявно отменяет автоматическое восстановление; - если Firebird недоступен во время нажатия
Стоп, DBTrace локально завершает свойfbtracemgr, закрывает лог и не запускает трассировку снова; - если процесс DBTrace принудительно завершен или компьютер перезагружен, автоматическое восстановление начнется только после следующего запуска DBTrace;
- DBTrace не является службой Windows и не может восстанавливать трассировку, пока сама программа не запущена.
¶ Работа при активной трассировке
Если закрыть окно крестиком во время активной трассировки, 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 его предоставил.
¶ Как читать сводку и счетчики
В summary.txt можно увидеть, например:
Всего событий: 2400017
SQL с измеренным временем: 1
Среднее время SQL: 39138 ms
Максимальное время SQL: 39138 ms
Суммарно: reads=1, writes=1010, fetches=6288916
Сессии 1
SQL 4
Процедуры 200001
Триггеры 2200011
Значения означают следующее:
Всего событий— количество всех распознанных событий Firebird в логе. Это не количество действий пользователя и не количество SQL-запросов;SQL с измеренным временем— количество завершенных SQL, у которых Firebird указал длительность;Среднее время SQL— среднее время этих завершенных SQL;Максимальное время SQL— самое большое измеренное время;reads— страницы базы, которые Firebird пришлось физически прочитать с диска;writes— страницы базы, записанные Firebird. Это не число командUPDATEи не число измененных строк;fetches— обращения к страницам через буферный кэш Firebird. Это не число полученных строк и не число запросов;Records— операции со строками, если Firebird предоставил этот показатель;Marks— страницы, помеченные как измененные в кэше;Сессии,SQL,Процедуры,Триггеры— количество событий соответствующего типа.
Большое значение fetches при маленьком reads обычно означает, что Firebird много раз обращался к страницам, которые уже находились в памяти, и редко читал их с диска. Само по себе это не ошибка, но вместе с долгим временем может указывать на большой объем работы или неудачный план запроса.
Значение writes=1010 не означает, что пользователь выполнил 1010 обновлений. Две команды UPDATE могут вызвать множество триггеров, изменить индексы и служебные страницы, а также затронуть много записей. Firebird считает работу на уровне страниц базы, а не на уровне нажатий пользователя.
¶ Почему событий процедур и триггеров могут быть миллионы
Одно действие пользователя может запустить один SQL, тот — процедуру, а процедура — триггеры для большого количества строк. Каждый запуск и завершение объекта записываются отдельными trace-событиями. Поэтому два UPDATE могут породить сотни тысяч или миллионы событий процедур и триггеров.
Это не означает, что DBTrace продублировал два действия миллионы раз. Сводка показывает фактическую внутреннюю работу Firebird. Для анализа важно сопоставлять эти числа с временем проблемы, SQL, планами и счетчиками производительности.
¶ Содержимое папки отчета
Папка создается внутри 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.