Recetas

Política de seguridad de contenidos

Si su sitio utiliza la Política de Seguridad de Contenidos, tendrá que añadir 'nonce-<value>' y 'strict-dynamic' a script-src para que Tracy funcione correctamente. Algunos plugins de terceros pueden requerir directivas adicionales. Nonce no está soportado en la directiva style-src, si usa esta directiva necesitará añadir 'unsafe-inline', pero esto debería evitarse en modo de producción.

Ejemplo de configuración para Nette Framework:

http:
	csp:
		script-src: [nonce, strict-dynamic]

Ejemplo en PHP puro:

$nonce = base64_encode(random_bytes(20));
header("Content-Security-Policy: script-src 'nonce-$nonce' 'strict-dynamic';");

Carga más rápida

La integración básica es sencilla, sin embargo si tienes scripts lentos de bloqueo en la página web, pueden ralentizar la carga de Tracy. La solución es colocar <?php Tracy\Debugger::renderLoader() ?> en tu plantilla antes de cualquier script:

<!DOCTYPE html>
<html>
<head>
	<title>...<title>
	<?php Tracy\Debugger::renderLoader() ?>
	<link rel="stylesheet" href="assets/style.css">
	<script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>
</head>

Depuración de peticiones AJAX

Tracy captura automáticamente las peticiones AJAX realizadas mediante jQuery o la API nativa fetch. Estas peticiones se muestran como filas adicionales en la barra de Tracy, permitiendo una depuración AJAX fácil y cómoda.

Si no desea capturar automáticamente las solicitudes AJAX, puede desactivar esta función configurando la variable JavaScript:

window.TracyAutoRefresh = false;

Para la monitorización manual de peticiones AJAX específicas, añada la cabecera HTTP X-Tracy-Ajax con el valor devuelto por Tracy.getAjaxHeader(). Aquí tiene un ejemplo de uso con la función fetch:

fetch(url, {
    headers: {
        'X-Requested-With': 'XMLHttpRequest',
        'X-Tracy-Ajax': Tracy.getAjaxHeader(),
    }
})

Este enfoque permite la depuración selectiva de peticiones AJAX.

Almacenamiento de datos

Tracy puede mostrar paneles de barras Tracy y Bluescreens para peticiones AJAX y redirecciones. Tracy crea sus propias sesiones, almacena datos en sus propios archivos temporales y utiliza una cookie tracy-session.

Tracy también puede configurarse para usar una sesión nativa PHP, que se inicia antes de que Tracy se active:

session_start();
Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();

En caso de que iniciar una sesión requiera una inicialización más compleja, se puede iniciar Tracy inmediatamente (para que pueda manejar cualquier error que se produzca) y después inicializar el manejador de sesión y finalmente informar a Tracy de que la sesión está lista para ser usada usando la función dispatch():

Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();

// seguido de la inicialización de la sesión
// e iniciar la sesión
session_start();

Debugger::dispatch();

La función setSessionStorage() existe desde la versión 2.9, antes de eso Tracy siempre usaba la sesión nativa de PHP.

Depurador personalizado

Scrubber es un filtro que evita que se filtren datos sensibles de los volcados, como contraseñas o credenciales. El filtro es llamado para cada elemento del array u objeto volcado y devuelve true si el valor es sensible. En este caso, se imprime ***** en lugar del valor.

// evita el volcado de valores clave y propiedades como `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD`, etc.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// lo utilizamos para todos los volcados dentro de BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;

Registrador personalizado

Podemos crear un logger personalizado para registrar errores, excepciones no capturadas, y también ser llamado por Tracy\Debugger::log(). Logger implementa la interfaz Tracy\ILogger.

use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// envía una solicitud a Slack
	}
}

Y luego lo activamos:

Tracy\Debugger::setLogger(new SlackLogger);

Si usamos el Nette Framework completo, podemos configurarlo en el archivo de configuración de NEON:

services:
	tracy.logger: SlackLogger

Integración Monolog

El paquete Tracy proporciona un adaptador PSR-3 que permite la integración de monolog/monolog.

$monolog = new Monolog\Logger('main-channel');
$monolog->pushHandler(new Monolog\Handler\StreamHandler($logFilePath, Monolog\Logger::DEBUG));

$tracyLogger = new Tracy\Bridges\Psr\PsrToTracyLoggerAdapter($monolog);
Debugger::setLogger($tracyLogger);
Debugger::enable();

Debugger::log('info'); // escribe: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // escribe: [<TIMESTAMP>] main-channel.WARNING: advertencia [] []

nginx

Si Tracy no funciona en nginx, probablemente esté mal configurado. Si hay algo como

try_files $uri $uri/ /index.php;

cámbielo por

try_files $uri $uri/ /index.php$is_args$args;