Primeros pasos con Tracy

La biblioteca Tracy es una ayuda diaria muy útil para los programadores de PHP. Le ayuda a:

  • detectar y corregir errores rápidamente
  • registrar los errores
  • volcar variables
  • medir el tiempo de ejecución de scripts y consultas
  • ver el consumo de memoria

PHP es un lenguaje perfectamente preparado para crear errores difíciles de detectar, porque da a los desarrolladores una libertad considerable. Eso hace que una herramienta de depuración como Tracy resulte aún más valiosa. Representa la cumbre absoluta entre las herramientas de diagnóstico para PHP.

Si hoy se encuentra con Tracy por primera vez, créase que su vida empezará a dividirse en el tiempo anterior a Tracy y el tiempo con ella. ¡Bienvenido a la mejor parte!

Instalación

La mejor manera de instalar Tracy es descargar el último paquete o usar Composer:

composer require tracy/tracy

Alternativamente puede descargar el paquete entero o el archivo tracy.phar.

Uso

Tracy se activa llamando al método Tracy\Debugger::enable() lo antes posible, al principio del programa, antes de enviar cualquier salida:

use Tracy\Debugger;

require 'vendor/autoload.php'; // o bien tracy.phar

Debugger::enable();

Lo primero que notará en la página es la Tracy Bar en la esquina inferior derecha. Si no la ve, puede significar que Tracy está funcionando en modo de producción. Y es que Tracy solo es visible en localhost por motivos de seguridad. Para probar si funciona puede ponerla temporalmente en modo de desarrollo con el parámetro Debugger::enable(Debugger::Development).

Tracy Bar

La Tracy Bar es un panel flotante que se muestra en la esquina inferior derecha de la página. Puede moverlo con el ratón y recordará su posición tras recargar la página.

A la Tracy Bar puede añadirle otros paneles útiles. Encontrará algunos interesantes en los complementos o puede crear los suyos.

Si no quiere mostrar la Tracy Bar, ponga:

Debugger::$showBar = false;

Visualización de errores y excepciones

Seguro que sabe cómo informa PHP de los errores: imprime algo así en el código fuente de la página:

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

o de una excepción no capturada:

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

Orientarse en una salida así no es precisamente fácil. Si activa Tracy, los errores y las excepciones se muestran de una forma completamente distinta:

El mensaje de error literalmente grita. Puede ver la parte del código fuente con la línea resaltada en la que se produjo el error. El mensaje Call to undefined method Nette\Http\User::isLogedIn() explica el error con claridad. Toda la página es interactiva; puede ir pulsando para ver más detalles. Pruébelo.

¿Y sabe qué? Los errores fatales se capturan y se muestran de la misma manera. Sin necesidad de instalar ninguna extensión.

Errores como una errata en el nombre de una variable o el intento de abrir un archivo que no existe generan avisos de nivel E_NOTICE o E_WARNING. Es fácil que pasen desapercibidos dentro de la maquetación gráfica de la página, o incluso que sean completamente invisibles (a no ser que mire el código fuente). Deje que se ocupe de ellos Tracy:

O se pueden mostrar como errores:

Debugger::$strictMode = true; // muestra todos los errores
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // todos los errores salvo los avisos de obsolescencia

Nota: al activarse, Tracy cambia el nivel de notificación de errores a E_ALL. Si quiere cambiarlo, hágalo después de llamar a enable().

Modo de desarrollo frente a modo de producción

Como ve, Tracy es bastante habladora, lo que se agradece en el entorno de desarrollo, mientras que en el servidor de producción sería un desastre. Y es que allí no debería mostrarse ninguna información de depuración. Por eso Tracy tiene autodetección del entorno. Si el ejemplo se ejecuta en un servidor en producción, el error se registrará en lugar de mostrarse y el visitante solo verá un mensaje amable:

El modo de producción suprime la visualización de toda la información de depuración enviada con dump() y, por supuesto, también de todos los mensajes de error generados por PHP. Así que, si ha olvidado algún dump($obj) en el código, no tiene que preocuparse: en el servidor de producción no se mostrará nada.

¿Cómo funciona la autodetección del modo? El modo es de desarrollo si la aplicación se ejecuta en localhost (es decir, con la dirección IP 127.0.0.1 o ::1) y no hay ningún proxy (es decir, su cabecera HTTP no está presente). En caso contrario funciona en modo de producción.

Si quiere activar el modo de desarrollo en otros casos, por ejemplo para los desarrolladores que acceden desde una dirección IP concreta, puede indicarlo como parámetro del método enable():

Debugger::enable('23.75.345.200'); // también puede indicar un array de direcciones IP

Recomendamos sin duda combinar la dirección IP con una cookie. Guarde un token secreto, p. ej. secret1234, en la cookie tracy-debug y active así el modo de desarrollo solo para los desarrolladores que accedan desde una dirección IP concreta y tengan ese token en la cookie:

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

También puede establecer directamente el modo de desarrollo o de producción con las constantes Debugger::Development o Debugger::Production como parámetro del método enable().

Si usa Nette Framework, mire cómo establecer el modo para él; después se usará también para Tracy.

Registro de errores

En modo de producción, Tracy registra automáticamente todos los errores y las excepciones capturadas en un registro de texto. Para que el registro funcione, tiene que establecer la ruta absoluta al directorio del registro en la variable $logDirectory o pasarla como segundo parámetro del método enable():

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

El registro de errores es extremadamente útil. Imagine que todos los usuarios de su aplicación son en realidad beta testers que hacen un trabajo de primera encontrando errores gratis, y que sería una tontería tirar sus valiosos informes a la papelera sin mirarlos.

Si necesita registrar sus propios mensajes o excepciones capturadas, use el método log():

Debugger::log('Unexpected error'); // mensaje de texto

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // registra la excepción
	// o
	Debugger::log($e, Debugger::ERROR); // envía además una notificación por correo
}

Si quiere que Tracy registre los errores de PHP como E_NOTICE o E_WARNING con información detallada (informe HTML), establezca Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Para un verdadero profesional, el registro de errores es una fuente de información clave y quiere estar informado de inmediato de cada error nuevo. Tracy se adapta a ello y sabe enviar notificaciones por correo de las nuevas entradas del registro. La variable $email determina a dónde enviar esos correos:

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

Si usa todo Nette Framework, puede establecer esto y otras cosas en el archivo de configuración.

Para proteger su buzón de correo de una avalancha, Tracy envía un solo mensaje y crea un archivo email-sent. Cuando el desarrollador recibe la notificación por correo, revisa el registro, corrige la aplicación y borra el archivo de control email-sent. Eso reactiva el envío de correos.

Informes en markdown

Junto a cada log/exception-*.html, Tracy escribe un archivo hermano .md con el mismo contenido en markdown: el mensaje, el stack trace y los extractos del código fuente. Estos archivos se crean incondicionalmente, trabaje o no un agente de IA con la aplicación.

Su propósito es el procesamiento por lotes. En lugar de ir pulsando uno a uno cientos de informes HTML, puede entregar todo el directorio del registro a un agente de IA y dejar que compare cada informe con el estado actual del código y proponga correcciones.

Soporte para agentes de IA

Cuando un agente de IA maneja su aplicación mediante un navegador (Chrome DevTools MCP, Playwright, Puppeteer), Tracy lo detecta con la propiedad de JavaScript navigator.webdriver y envía a la consola del navegador una versión en markdown de los diagnósticos clave, junto a la interfaz estándar:

  • BlueScreen: la excepción, el stack trace y los valores de las variables enviados a console.error() junto a la pantalla roja, tanto para el renderizado síncrono como para los errores AJAX.
  • Tracy Bar: un resumen en markdown de los paneles principales (SQL, Errors, Dumps) enviado a console.log().
  • Debugger::dump(): una variante en texto plano junto a la salida HTML habitual, para que los volcados no queden enterrados en la página.
  • Página 500 de producción: console.error() informa al agente de que se ha producido un error y de que los detalles se han registrado en el servidor.

La detección establece la cookie tracy-webdriver=1; puede ponerla a mano en las DevTools para activar la salida en markdown desde un navegador normal. La activación del agente no afecta a los archivos hermanos .md que se escriben junto a cada log/exception-*.html: esos se producen incondicionalmente y son la base del procesamiento por lotes de los registros de producción.

Los paneles propios de la Tracy Bar pueden aportar su propio markdown implementando getAgentInfo(). Para quien use Claude Code, el plugin de Nette incluye la skill tracy-debugging, que enseña al agente a leer la salida de Tracy desde list_console_messages().

Abrir archivos en el editor

Cuando se muestra la página de error puede pulsar en los nombres de los archivos y estos se abrirán en su editor con el cursor en la línea correspondiente. También se pueden crear archivos (acción create file) o corregir errores en ellos (acción fix it). Para eso hay que configurar el navegador y el sistema.

Versiones de PHP soportadas

Tracy Compatible con 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

Vale para las últimas versiones de parche.

Ports

Esta es una lista de ports no oficiales a otros frameworks y CMS: