Erste Schritte mit Tracy

Die Bibliothek Tracy ist ein nützlicher Alltagshelfer für PHP-Programmierer. Sie hilft Ihnen:

  • Fehler schnell zu finden und zu beheben
  • Fehler zu protokollieren
  • Variablen auszugeben
  • die Ausführungszeit von Skripten/Queries zu messen
  • den Speicherverbrauch zu sehen

PHP ist eine Sprache, die sich hervorragend dafür eignet, schwer auffindbare Fehler zu erzeugen, denn sie gibt Entwicklern beträchtliche Freiheit. Umso wertvoller ist ein Debugging-Werkzeug wie Tracy. Sie stellt die absolute Spitze unter den Diagnosewerkzeugen für PHP dar.

Wenn Sie Tracy heute zum ersten Mal begegnen, glauben Sie uns: Ihr Leben wird sich künftig in die Zeit vor Tracy und die Zeit mit ihr teilen. Willkommen im besseren Teil!

Installation

Am besten installieren Sie Tracy, indem Sie das neueste Paket herunterladen oder Composer verwenden:

composer require tracy/tracy

Alternativ können Sie das ganze Paket oder die Datei tracy.phar herunterladen.

Verwendung

Tracy wird aktiviert, indem Sie die Methode Tracy\Debugger::enable() so früh wie möglich am Anfang des Programms aufrufen, bevor irgendeine Ausgabe gesendet wird:

use Tracy\Debugger;

require 'vendor/autoload.php'; // alternativ tracy.phar

Debugger::enable();

Das Erste, was Ihnen auf der Seite auffällt, ist die Tracy Bar in der rechten unteren Ecke. Sehen Sie sie nicht, kann das bedeuten, dass Tracy im Produktionsmodus läuft. Denn Tracy ist aus Sicherheitsgründen nur auf localhost sichtbar. Um zu testen, ob es funktioniert, können Sie sie mit dem Parameter Debugger::enable(Debugger::Development) vorübergehend in den Entwicklungsmodus versetzen.

Tracy Bar

Die Tracy Bar ist ein schwebendes Panel, das in der rechten unteren Ecke der Seite angezeigt wird. Sie können sie mit der Maus verschieben, und sie merkt sich ihre Position auch nach dem Neuladen der Seite.

In die Tracy Bar können Sie weitere nützliche Panels einfügen. Interessante finden Sie in den Addons, oder Sie können eigene erstellen.

Wenn Sie die Tracy Bar nicht anzeigen wollen, setzen Sie:

Debugger::$showBar = false;

Visualisierung von Fehlern und Exceptions

Sie wissen sicher, wie PHP Fehler meldet: Es gibt in den Quelltext der Seite etwa Folgendes aus:

Parse error:  syntax error, unexpected '}' in HomePresenter.php on line 15

oder eine nicht abgefangene Exception:

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

Sich in einer solchen Ausgabe zurechtzufinden, ist nicht gerade leicht. Wenn Sie Tracy aktivieren, werden Fehler und Exceptions in einer völlig anderen Form angezeigt:

Die Fehlermeldung schreit förmlich. Sie sehen den Teil des Quellcodes mit der hervorgehobenen Zeile, in der der Fehler aufgetreten ist. Die Meldung Call to undefined method Nette\Http\User::isLogedIn() erklärt den Fehler eindeutig. Die gesamte Seite ist interaktiv; Sie können sich zu weiteren Details durchklicken. Probieren Sie es aus.

Und wissen Sie was? Fatale Fehler werden auf dieselbe Weise abgefangen und angezeigt. Ohne dass irgendeine Extension installiert werden müsste.

Fehler wie ein Tippfehler im Namen einer Variablen oder der Versuch, eine nicht existierende Datei zu öffnen, erzeugen Meldungen auf der Stufe E_NOTICE oder E_WARNING. Diese lassen sich im grafischen Layout der Seite leicht übersehen oder sind sogar völlig unsichtbar (es sei denn, man sieht in den Quelltext). Überlassen Sie sie Tracy:

Oder sie lassen sich wie Fehler anzeigen:

Debugger::$strictMode = true; // alle Fehler anzeigen
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // alle Fehler außer deprecated notices

Hinweis: Wenn Tracy aktiviert wird, ändert es die Stufe des Error Reporting auf E_ALL. Wollen Sie das ändern, tun Sie es nach dem Aufruf von enable().

Entwicklungs- vs. Produktionsmodus

Wie Sie sehen, ist Tracy recht gesprächig, was man in der Entwicklungsumgebung zu schätzen weiß, auf dem Produktionsserver aber eine Katastrophe wäre. Denn dort dürfen keinerlei Debugging-Informationen angezeigt werden. Tracy hat deshalb eine automatische Erkennung der Umgebung. Läuft das Beispiel auf einem Live-Server, wird der Fehler protokolliert statt angezeigt, und der Besucher sieht nur eine verständliche Meldung:

Der Produktionsmodus unterdrückt die Anzeige aller mit dump() gesendeten Debugging-Informationen und natürlich auch aller von PHP erzeugten Fehlermeldungen. Wenn Sie also im Code irgendein dump($obj) vergessen haben, müssen Sie sich keine Sorgen machen, auf dem Produktionsserver wird nichts angezeigt.

Wie funktioniert die automatische Erkennung des Modus? Der Modus ist Entwicklung, wenn die Anwendung auf localhost läuft (also unter der IP-Adresse 127.0.0.1 oder ::1) und kein Proxy vorhanden ist (sein HTTP-Header also fehlt). Andernfalls läuft sie im Produktionsmodus.

Wenn Sie den Entwicklungsmodus auch in anderen Fällen aktivieren wollen, zum Beispiel für Entwickler, die von einer bestimmten IP-Adresse zugreifen, können Sie das als Parameter der Methode enable() angeben:

Debugger::enable('23.75.345.200'); // Sie können auch ein Array von IP-Adressen angeben

Wir empfehlen unbedingt, die IP-Adresse mit einem Cookie zu kombinieren. Speichern Sie ein geheimes Token, z. B. secret1234, im Cookie tracy-debug und aktivieren Sie so den Entwicklungsmodus nur für Entwickler, die von einer bestimmten IP-Adresse zugreifen und das genannte Token im Cookie haben:

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

Sie können den Entwicklungs- bzw. Produktionsmodus auch direkt mit den Konstanten Debugger::Development oder Debugger::Production als Parameter der Methode enable() setzen.

Wenn Sie das Nette Framework verwenden, sehen Sie sich an, wie Sie den Modus dafür einstellen; er wird dann auch für Tracy verwendet.

Fehlerprotokollierung

Im Produktionsmodus protokolliert Tracy alle Fehler und abgefangenen Exceptions automatisch in ein Textlog. Damit die Protokollierung funktioniert, müssen Sie den absoluten Pfad zum Log-Verzeichnis in der Variablen $logDirectory setzen oder ihn als zweiten Parameter an die Methode enable() übergeben:

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

Die Fehlerprotokollierung ist außerordentlich nützlich. Stellen Sie sich vor, alle Benutzer Ihrer Anwendung sind in Wirklichkeit Betatester, die kostenlos erstklassige Arbeit beim Finden von Fehlern leisten – und Sie wären töricht, ihre wertvollen Berichte ungesehen in den Papierkorb zu werfen.

Wenn Sie eigene Meldungen oder abgefangene Exceptions protokollieren müssen, verwenden Sie die Methode log():

Debugger::log('Unexpected error'); // Textmeldung

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // Exception protokollieren
	// oder
	Debugger::log($e, Debugger::ERROR); // sendet außerdem eine E-Mail-Benachrichtigung
}

Wenn Sie wollen, dass Tracy PHP-Fehler wie E_NOTICE oder E_WARNING mit ausführlichen Informationen (HTML-Bericht) protokolliert, setzen Sie Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Für einen echten Profi ist das Fehlerlog eine zentrale Informationsquelle, und er will über jeden neuen Fehler sofort informiert werden. Tracy kommt ihm entgegen, indem es E-Mail-Benachrichtigungen über neue Einträge im Log senden kann. Die Variable $email bestimmt, wohin diese E-Mails gehen:

Debugger::$email = 'admin@example.com';

Wenn Sie das gesamte Nette Framework verwenden, können Sie dies und anderes in der Konfigurationsdatei einstellen.

Damit Ihr Postfach nicht überflutet wird, sendet Tracy nur eine Nachricht und legt eine Datei email-sent an. Erhält ein Entwickler die E-Mail-Benachrichtigung, sieht er ins Log, korrigiert die Anwendung und löscht die Überwachungsdatei email-sent. Damit wird das Senden von E-Mails wieder aktiviert.

Markdown-Berichte

Neben jede log/exception-*.html schreibt Tracy ein .md-Geschwisterchen mit demselben Inhalt in Markdown: die Meldung, den Stacktrace und die Ausschnitte des Quellcodes. Diese Dateien entstehen bedingungslos, unabhängig davon, ob ein KI-Agent mit der Anwendung arbeitet.

Ihr Zweck ist die Stapelverarbeitung. Statt Hunderte HTML-Berichte einzeln durchzuklicken, können Sie das gesamte Log-Verzeichnis einem KI-Agenten übergeben und ihn jeden Bericht mit dem aktuellen Zustand des Codes vergleichen und Korrekturen vorschlagen lassen.

Unterstützung für KI-Agenten

Wenn ein KI-Agent Ihre Anwendung über einen Browser steuert (Chrome DevTools MCP, Playwright, Puppeteer), erkennt Tracy das über die JavaScript-Property navigator.webdriver und sendet neben der üblichen Oberfläche eine Markdown-Fassung der wichtigsten Diagnosen in die Browserkonsole:

  • BlueScreen – Exception, Stacktrace und Werte der Variablen, neben dem roten Bildschirm an console.error() gesendet, sowohl beim synchronen Rendern als auch bei AJAX-Fehlern.
  • Tracy Bar – Markdown-Zusammenfassung der wichtigsten Panels (SQL, Errors, Dumps), an console.log() gesendet.
  • Debugger::dump() – eine Klartextvariante neben der üblichen HTML-Ausgabe, damit Dumps nicht in der Seite untergehen.
  • 500er-Seite in der Produktion – console.error() informiert den Agenten, dass ein Fehler aufgetreten ist und dass die Details auf dem Server protokolliert wurden.

Die Erkennung setzt das Cookie tracy-webdriver=1; Sie können es in den DevTools von Hand setzen, um die Markdown-Ausgabe auch aus einem gewöhnlichen Browser zu aktivieren. Die Aktivierung des Agenten beeinflusst die .md-Geschwisterchen neben jeder log/exception-*.html nicht – die entstehen bedingungslos und bilden die Grundlage für die Stapelverarbeitung von Produktionslogs.

Eigene Panels der Tracy Bar können ihr eigenes Markdown liefern, indem sie getAgentInfo() implementieren. Für Nutzer von Claude Code enthält das Nette-Plugin den Skill tracy-debugging, der dem Agenten beibringt, die Ausgabe von Tracy aus list_console_messages() zu lesen.

Dateien im Editor öffnen

Wenn die Fehlerseite angezeigt wird, können Sie auf Dateinamen klicken, und sie öffnen sich in Ihrem Editor mit dem Cursor auf der entsprechenden Zeile. Dateien lassen sich auch anlegen (Aktion create file) oder Fehler darin beheben (Aktion fix it). Dafür müssen Sie den Browser und das System konfigurieren.

Unterstützte PHP-Versionen

Tracy Kompatibel mit 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

Gilt für die jeweils letzten Patch-Versionen.

Ports

Das ist eine Liste inoffizieller Portierungen für andere Frameworks und CMS: