Начало работы с Tracy
Библиотека Tracy – полезный повседневный помощник PHP-программиста. Она помогает вам:
- быстро находить и исправлять ошибки
- логировать ошибки
- выводить содержимое переменных
- измерять время выполнения скриптов и запросов
- следить за расходом памяти
PHP – язык, прекрасно приспособленный для создания труднообнаружимых ошибок, ведь он даёт разработчику немалую свободу. Тем ценнее такой инструмент отладки, как Tracy. Это абсолютная вершина среди диагностических инструментов для PHP.
Если вы встречаетесь с Tracy сегодня впервые, поверьте: ваша жизнь начнёт делиться на время до Tracy и время с ней. Добро пожаловать в лучшую её часть!
Установка
Лучше всего установить Tracy, скачав последний пакет или воспользовавшись Composer:
composer require tracy/tracy
Как вариант, можно скачать весь пакет или файл tracy.phar.
Использование
Tracy включается вызовом метода Tracy\Debugger::enable() как можно раньше в
начале программы, до отправки какого-либо вывода:
use Tracy\Debugger;
require 'vendor/autoload.php'; // либо tracy.phar
Debugger::enable();
Первое, что вы заметите на странице, – это панель Tracy Bar в правом
нижнем углу. Если вы её не видите, это может означать, что Tracy работает в
продакшн-режиме. Дело в том, что из соображений безопасности Tracy видна
только на localhost. Чтобы проверить, работает ли она, можно временно
перевести её в режим разработки параметром
Debugger::enable(Debugger::Development).
Tracy Bar
Tracy Bar – плавающая панель, отображаемая в правом нижнем углу страницы. Её можно перетаскивать мышью, и после перезагрузки страницы она запомнит своё положение.
В Tracy Bar можно добавлять и другие полезные панели. Интересные найдёте среди дополнений или можете создать собственную.
Если вы не хотите показывать Tracy Bar, задайте:
Debugger::$showBar = false;
Отображение ошибок и исключений
Вы наверняка знаете, как PHP сообщает об ошибках: он выводит в исходный код страницы примерно такое:
Parse error: syntax error, unexpected '}' in HomePresenter.php on line 15
или неперехваченное исключение:
Fatal error: Uncaught Nette\MemberAccessException: Call to undefined method Nette\Application\UI\Form::addTest()? in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php:100
Stack trace:
#0 /sandbox/vendor/nette/utils/src/Utils/Object.php(75): Nette\Utils\ObjectMixin::call(Object(Nette\Application\UI\Form), 'addTest', Array)
#1 /sandbox/app/Forms/SignFormFactory.php(32): Nette\Object->__call('addTest', Array)
#2 /sandbox/app/Presentation/Sign/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presentation\Sign\SignPresenter->createComponentSignInForm('signInForm')
#4 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(139): Nette\ComponentModel\Container->createComponent('signInForm')
#5 /sandbox/temp/cache/latte/15206b353f351f6bfca2c36cc.php(17): Nette\ComponentModel\Co in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php on line 100
Разобраться в таком выводе не так-то просто. Если вы включите Tracy, ошибки и исключения будут показаны совсем в другом виде:
Сообщение об ошибке буквально кричит. Вы видите фрагмент исходного кода с подсвеченной строкой, где произошла ошибка. Сообщение Call to undefined method Nette\Http\User::isLogedIn() внятно объясняет ошибку. Вся страница интерактивна, вы можете кликать и добираться до подробностей. Попробуйте.
И знаете что? Фатальные ошибки перехватываются и отображаются точно так же. Без установки каких-либо расширений.
Такие ошибки, как опечатка в имени переменной или попытка открыть несуществующий файл, порождают сообщения уровня E_NOTICE или E_WARNING. Их легко проглядеть в оформлении страницы или вообще не заметить (если не смотреть в исходный код). Пусть о них позаботится Tracy:
Или их можно показывать как ошибки:
Debugger::$strictMode = true; // показывать все ошибки
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // все ошибки, кроме сообщений deprecated
Замечание: Tracy при включении меняет уровень сообщений об ошибках на
E_ALL. Если вы хотите это изменить, сделайте это после вызова
enable().
Режим разработки и продакшн-режим
Как видите, Tracy довольно многословна, и в среде разработки это ценно, а вот на боевом сервере обернулось бы катастрофой. Ведь там никакая отладочная информация показываться не должна. Поэтому Tracy умеет сама определять окружение. Если пример запустить на живом сервере, ошибка будет не показана, а записана в лог, и посетитель увидит только понятное ему сообщение:
Продакшн-режим подавляет вывод всей отладочной информации,
отправленной через dump(), и, разумеется, всех сообщений об
ошибках, порождаемых PHP. Так что если вы забыли в коде какой-нибудь
dump($obj), беспокоиться не о чем: на боевом сервере ничего не
отобразится.
Как работает автоопределение режима? Режим считается
разработческим, если приложение запущено на localhost (то есть IP-адрес
127.0.0.1 или ::1) и при этом нет прокси (то есть отсутствует
его HTTP-заголовок). Иначе работает продакшн-режим.
Если вы хотите включить режим разработки и в других случаях, например
для разработчиков, заходящих с определённого IP-адреса, укажите его
параметром метода enable():
Debugger::enable('23.75.345.200'); // можно указать и массив IP-адресов
Мы настоятельно рекомендуем сочетать IP-адрес с cookie. В cookie
tracy-debug сохраните секретный токен, например secret1234, и таким
образом включите режим разработки только для разработчиков, заходящих
с определённого IP-адреса и имеющих в cookie этот токен:
Debugger::enable('secret1234@23.75.345.200');
Режим разработки или продакшна можно задать и напрямую константами
Debugger::Development или Debugger::Production в параметре метода
enable().
Если вы используете Nette Framework, посмотрите, как задать режим для него: он затем будет использован и для Tracy.
Логирование ошибок
В продакшн-режиме Tracy автоматически записывает все ошибки и
перехваченные исключения в текстовый лог. Чтобы логирование работало,
нужно задать абсолютный путь к каталогу логов в переменной
$logDirectory или передать его вторым параметром методу
enable():
Debugger::$logDirectory = __DIR__ . '/log';
Логирование ошибок исключительно полезно. Представьте, что все пользователи вашего приложения на самом деле бета-тестеры, которые бесплатно и на отлично ищут ошибки, и было бы глупо выбрасывать их ценные отчёты незамеченными в мусорную корзину.
Если вам нужно записать в лог собственные сообщения или
перехваченные исключения, используйте метод log():
Debugger::log('Неожиданная ошибка'); // текстовое сообщение
try {
criticalOperation();
} catch (Exception $e) {
Debugger::log($e); // записать исключение в лог
// или
Debugger::log($e, Debugger::ERROR); // отправит ещё и уведомление по электронной почте
}
Если вы хотите, чтобы Tracy логировала ошибки PHP вроде E_NOTICE или
E_WARNING с подробной информацией (HTML-отчётом), задайте
Debugger::$logSeverity:
Debugger::$logSeverity = E_NOTICE | E_WARNING;
Для настоящего профессионала лог ошибок – ключевой источник
информации, и он хочет узнавать о каждой новой ошибке сразу же. Tracy идёт
ему навстречу: она умеет отправлять уведомления о новых записях в логе
по электронной почте. Куда их слать, определяет переменная
$email:
Debugger::$email = 'admin@example.com';
Если вы используете весь Nette Framework, это и другое можно задать в конфигурационном файле.
Чтобы не завалить ваш почтовый ящик, Tracy отправляет только одно
сообщение и создаёт файл email-sent. Когда разработчик получит
уведомление по почте, он проверит лог, исправит приложение и удалит
сторожевой файл email-sent. Тем самым отправка почты снова
включится.
Отчёты в формате Markdown
Рядом с каждым log/exception-*.html Tracy записывает файл .md с тем
же содержимым в формате markdown: сообщение, стек вызовов и фрагменты
исходного кода. Эти файлы создаются всегда, независимо от того,
работает ли с приложением AI-агент.
Их назначение – пакетная обработка. Вместо того чтобы по одному прокликивать сотни HTML-отчётов, вы можете передать AI-агенту весь каталог логов и поручить ему сверить каждый отчёт с текущим состоянием кода и предложить исправления.
Поддержка AI-агентов
Когда AI-агент управляет вашим приложением через браузер (Chrome DevTools MCP,
Playwright, Puppeteer), Tracy распознаёт его по JavaScript-свойству navigator.webdriver и
рядом со стандартным интерфейсом отправляет в консоль браузера
markdown-версию ключевой диагностики:
- BlueScreen – исключение, стек вызовов и значения переменных
отправляются в
console.error()рядом с красным экраном, как при обычном отображении, так и при ошибках AJAX. - Tracy Bar – markdown-сводка основных панелей (SQL, Errors, Dumps) отправляется в
console.log(). Debugger::dump()– текстовый вариант рядом с обычным HTML-выводом, чтобы дампы не терялись в странице.- Страница 500 в продакшне –
console.error()сообщает агенту, что произошла ошибка и что подробности записаны в лог на сервере.
Распознавание устанавливает cookie tracy-webdriver=1; вы можете задать
её вручную в DevTools и включить markdown-вывод из обычного браузера. Включение
режима агента не влияет на файлы .md, записываемые рядом с каждым
log/exception-*.html: они создаются всегда и служат основой для пакетной
обработки продакшн-логов.
Собственные панели Tracy Bar могут предоставить свой markdown, реализовав getAgentInfo(). Для пользователей Claude Code плагин Nette содержит навык tracy-debugging,
который учит агента читать вывод Tracy из list_console_messages().
Открытие файлов в редакторе
Когда отображается страница с ошибкой, вы можете кликать по именам
файлов, и они откроются в вашем редакторе с курсором на
соответствующей строке. Файлы можно также создавать (действие
create file) или исправлять в них ошибки (действие fix it). Чтобы
это работало, нужно настроить браузер и систему.
Поддерживаемые версии PHP
| Tracy | Совместима с PHP |
|---|---|
| Tracy 2.10 – 3.0 | PHP 8.0 – 8.4 |
| Tracy 2.9 | PHP 7.2 – 8.2 |
| Tracy 2.8 | PHP 7.2 – 8.1 |
| Tracy 2.6 – 2.7 | PHP 7.1 – 8.0 |
| Tracy 2.5 | PHP 5.4 – 7.4 |
| Tracy 2.4 | PHP 5.4 – 7.2 |
Относится к последним патч-версиям.
Порты
Это список неофициальных портов для других фреймворков и CMS:
- Drupal 7
- Laravel framework: recca0120/laravel-tracy, whipsterCZ/laravel-tracy
- OpenCart
- ProcessWire CMS/CMF
- Slim Framework
- Symfony framework: kutny/tracy-bundle, VasekPurchart/Tracy-Blue-Screen-Bundle
- WordPress