Tracy をはじめる

Tracy ライブラリは PHP プログラマーの日々の頼もしい助っ人です。次のことを助けてくれます。

  • エラーを素早く見つけて直す
  • エラーを記録する
  • 変数をダンプする
  • スクリプトやクエリの実行時間を測る
  • メモリの使用量を見る

PHP は開発者にかなりの自由を与える言語なので、見つけにくいエラーを作るのにうってつけです。だからこそ Tracy のようなデバッグの道具はいっそう価値があります。これは PHP の診断の道具の中でも文句なしの頂点です。

今日はじめて Tracy に出会ったのなら、これからあなたの人生は 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; // 非推奨の通知を除くすべてのエラー

注意: 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 アドレスとクッキーを組み合わせることを強くおすすめします。tracy-debug のクッキーに秘密のトークン、たとえば secret1234 を入れておき、そのトークンをクッキーに持つ、特定の IP アドレスからアクセスする開発者にだけ開発モードを有効にします。

Debugger::enable('secret1234@23.75.345.200');

enable() メソッドのパラメータに Debugger::Development または Debugger::Production の定数を渡して、開発／本番モードを直接設定することもできます。

Nette Framework を使っているなら、そちらでのモードの設定をご覧ください。それが Tracy にも使われます。

エラーの記録

本番モードでは、Tracy はすべてのエラーと捕まえた例外をテキストのログに自動的に記録します。記録が働くには、$logDirectory 変数にログのディレクトリへの絶対パスを設定するか、enable() メソッドの第 2 パラメータとして渡す必要があります。

Debugger::$logDirectory = __DIR__ . '/log';

エラーの記録はとても役に立ちます。あなたのアプリケーションのすべての利用者が、実はエラー探しをただで見事にこなすベータテスターだと考えてみてください。その貴重な報告を、気づかれないままゴミ箱に捨ててしまうのは愚かなことです。

自分のメッセージや捕まえた例外を記録したいなら、log() メソッドを使います。

Debugger::log('Unexpected error'); // テキストのメッセージ

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // 例外を記録します
	// または
	Debugger::log($e, Debugger::ERROR); // メールの通知も送ります
}

E_NOTICE や E_WARNING のような PHP のエラーを、詳しい情報（HTML の報告）付きで Tracy に記録させたいなら、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 は同じ内容を markdown で書いた .md の兄弟ファイルを置きます。メッセージ、スタックトレース、ソースコードの抜粋です。これらのファイルは、AI エージェントがアプリケーションを扱っているかどうかに関わらず、いつでも作られます。

その目的はまとめて処理することです。何百もの HTML の報告をひとつずつクリックして見ていく代わりに、ログのディレクトリ全体を AI エージェントに渡して、報告のそれぞれを今のコードの状態と照らし合わせ、直し方を提案させられます。

AI エージェントへの対応

AI エージェントがブラウザ越しにあなたのアプリケーションを動かしているとき（Chrome DevTools MCP、Playwright、Puppeteer）、Tracy は JavaScript の navigator.webdriver プロパティでそれを見分け、いつもの UI と並べて、大事な診断の情報の markdown 版をブラウザのコンソールへ送ります。

  • BlueScreen – 例外、スタックトレース、変数の値を、赤い画面と並べて console.error() へ送ります。同期の描画でも AJAX のエラーでも同じです。
  • Tracy Bar – 主なパネル（SQL、Errors、Dumps）の markdown の要約を console.log() へ送ります。
  • Debugger::dump() – ふだんの HTML の出力と並べて平文の版も出すので、ダンプがページに埋もれません。
  • 本番の 500 のページ – console.error() が、エラーが起きたことと、詳細がサーバーに記録されたことをエージェントに伝えます。

見分けがつくと tracy-webdriver=1 のクッキーが設定されます。DevTools で手で設定すれば、ふつうのブラウザからでも markdown の出力を有効にできます。エージェントが認識されたかどうかは、log/exception-*.html の隣に書かれる .md の兄弟ファイルには影響しません。あれはいつでも作られ、本番のログをまとめて処理するための土台になります。

Tracy Bar の独自のパネルは、getAgentInfo()を実装すれば自分の markdown を出せます。Claude Code の利用者向けには、Nette のプラグインに tracy-debugging のスキルが入っていて、list_console_messages() から Tracy の出力を読む方法をエージェントに教えます。

エディタでファイルを開く

エラーのページが表示されているとき、ファイル名をクリックすると、対応する行にカーソルを置いた状態でエディタが開きます。ファイルを作る（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 への非公式の移植版の一覧です。