Empezando con Tracy
La librería Tracy es una útil ayuda diaria para el programador PHP. Te ayudará a:
- detectar y corregir errores rápidamente
- registrar errores
- imprimir variables
- medir el tiempo de ejecución de scripts y consultas de base de datos
- monitorizar los requisitos de memoria
PHP es un lenguaje perfecto para cometer errores difíciles de detectar, ya que da a los desarrolladores una considerable libertad. Por eso, la herramienta de depuración Tracy es aún más valiosa. Representa la cima absoluta entre las herramientas de diagnóstico para PHP.
Si hoy te encuentras con Tracy por primera vez, créeme, tu vida comenzará a dividirse en la de antes de Tracy y la de después. ¡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
También puedes descargar el paquete completo como un archivo tracy.phar.
Uso
Activamos Tracy 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 tracy.phar
Debugger::enable();
Lo primero que notarás en la página es la Tracy Bar en la esquina inferior derecha. Si no la ves, puede significar que Tracy
se está ejecutando en modo de producción. Tracy, por razones de seguridad, solo es visible en localhost. Para probar si
funciona, puedes cambiarla temporalmente al modo de desarrollo usando el parámetro
Debugger::enable(Debugger::Development)
.
Tracy Bar
La Tracy Bar es un panel flotante que aparece en la esquina inferior derecha de la página. Podemos moverla con el ratón y recordará su posición después de recargar la página.

Se pueden añadir otros paneles útiles a la Tracy Bar. Encontrarás muchos en los complementos, o incluso puedes escribir los tuyos propios.
Si no quieres mostrar la Tracy Bar, configura:
Debugger::$showBar = false;
Visualización de errores y excepciones
Seguro que sabes bien cómo PHP notifica los errores: imprime algo como esto en el código fuente de la página:
Parse error: syntax error, unexpected '}' in HomePresenter.php on line 15
o en caso 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 tal salida no es precisamente fácil. Si activamos Tracy, el error o la excepción se mostrarán de una forma completamente diferente:

El mensaje de error literalmente grita. Vemos parte del código fuente con la línea resaltada donde ocurrió el error y la información Call to undefined method Nette\Http\User::isLogedIn() explica claramente de qué error se trata. Toda la página es además interactiva, podemos hacer clic para ver más detalles. Pruébalo.
¿Y sabes qué? De esta manera captura y muestra incluso errores fatales. Sin necesidad de instalar ninguna extensión.

Errores como un error tipográfico en el nombre de una variable o el intento de abrir un archivo inexistente generan mensajes de nivel E_NOTICE o E_WARNING. Estos pueden pasarse por alto fácilmente en los gráficos de la página, incluso pueden no ser visibles en absoluto (a menos que mires el código fuente de la página).

O pueden mostrarse igual que los errores:
Debugger::$strictMode = true; // mostrar todos los errores
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // todos los errores excepto los avisos de deprecación

Nota: Tracy, después de la activación, cambia el nivel de reporte de errores a E_ALL. Si quieres cambiar este valor, hazlo
después de llamar a enable()
.
Modo de desarrollo vs producción
Como puedes ver, Tracy es bastante locuaz, lo cual se puede apreciar en el entorno de desarrollo, mientras que en un servidor de producción causaría un completo desastre. Allí no se debe imprimir ninguna información de depuración. Tracy, por lo tanto, dispone de autodetección de entorno y si ejecutamos el ejemplo en un servidor en vivo, el error se registrará en lugar de mostrarse y el visitante solo verá un mensaje comprensible para el usuario:

El modo de producción suprime la visualización de toda la información de depuración que enviamos mediante dump(), y por supuesto también de todos los mensajes de error que genera PHP. Por lo
tanto, si has olvidado algún dump($obj)
en el código, no tienes que preocuparte, en el servidor de producción no
se imprimirá nada.
¿Cómo funciona la autodetección de modo? El modo es de desarrollo si la aplicación se ejecuta en localhost (es decir,
dirección IP 127.0.0.1
o ::1
) y no hay presente un proxy (es decir, su cabecera HTTP). De lo contrario,
se ejecuta en modo de producción.
Si queremos habilitar el modo de desarrollo también en otros casos, por ejemplo, para programadores que acceden desde una
dirección IP específica, la indicamos como parámetro del método enable()
:
Debugger::enable('23.75.345.200'); // también se puede indicar un array de direcciones IP
Definitivamente recomendamos combinar la dirección IP con una cookie. En la cookie tracy-debug
guardamos un token
secreto, p.ej. secret1234
, y de esta manera activamos el modo de desarrollo solo para programadores que acceden desde
una dirección IP específica y que tienen el token mencionado en la cookie:
Debugger::enable('secret1234@23.75.345.200');
También podemos establecer directamente el modo de desarrollo/producción usando la constante
Debugger::Development
o Debugger::Production
como parámetro del método enable()
.
Si usas Nette Framework, consulta cómo configurar el modo para él y ese se usará posteriormente también para Tracy.
Registro de errores
En modo de producción, Tracy registra automáticamente todos los errores y excepciones capturadas en un log de texto. Para que
el registro pueda llevarse a cabo, debemos establecer la ruta absoluta al directorio de logs en la variable
$logDirectory
o pasarla como segundo parámetro del método enable()
:
Debugger::$logDirectory = __DIR__ . '/log';
El registro de errores es, al mismo tiempo, extremadamente útil. Imagina que todos los usuarios de tu aplicación son en realidad betatesters que realizan gratuitamente un trabajo excelente en la búsqueda de errores y cometerías una tontería si desecharas sus valiosos reportes sin prestar atención en la papelera.
Si necesitamos registrar nuestro propio mensaje o una excepción que hemos capturado, usamos para ello el método
log()
:
Debugger::log('Ocurrió un error inesperado'); // mensaje de texto
try {
operacionCritica();
} catch (Exception $e) {
Debugger::log($e); // también se puede registrar la excepción
// o
Debugger::log($e, Debugger::ERROR); // también envía una notificación por correo electrónico
}
Si quieres que Tracy registre errores de PHP como E_NOTICE
o E_WARNING
con información detallada
(informe HTML), establece Debugger::$logSeverity
:
Debugger::$logSeverity = E_NOTICE | E_WARNING;
Para un verdadero profesional, el log de errores es una fuente clave de información y quiere ser informado inmediatamente sobre cada nuevo error. Tracy le ayuda en esto, ya que puede informar sobre un nuevo registro en el log por correo electrónico. Determinamos a dónde enviar los correos electrónicos con la variable $email:
Debugger::$email = 'admin@example.com';
Si usas todo el Nette Framework, puedes configurar esto y otros ajustes en el archivo de configuración.
Sin embargo, para que no inunde tu buzón de correo electrónico, siempre envía solo un mensaje y crea el archivo
email-sent
. El desarrollador, después de recibir la notificación por correo electrónico, comprueba el log, corrige
la aplicación y elimina el archivo de monitorización, lo que reactiva el envío de correos electrónicos.
Apertura en el editor
Al mostrar la página de error, se puede hacer clic en los nombres de los archivos y estos se abrirán en tu 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 que esto funcione, es suficiente 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 |
Aplica a la última versión de parche.
Ports
Esta es una lista de ports no oficiales para otros frameworks y 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