Рецепты

Политика безопасности контента

Если на вашем сайте используется политика безопасности содержимого, вам нужно добавить 'nonce-<value>' и 'strict-dynamic' к script-src, чтобы Tracy работал правильно. Некоторые третьи плагины могут потребовать дополнительные директивы. Nonce не поддерживается в директиве style-src, если вы используете эту директиву, вам нужно добавить 'unsafe-inline', но этого следует избегать в производственном режиме.

Пример конфигурации для Nette Framework:

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

Пример на чистом PHP:

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

Ускоренная загрузка

Базовая интеграция проста, однако если на веб-странице есть медленные блокирующие скрипты, они могут замедлить загрузку Tracy. Решение заключается в том, чтобы поместить <?php Tracy\Debugger::renderLoader() ?> в ваш шаблон перед любыми скриптами:

<!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>

Отладка AJAX-запросов

Tracy автоматически перехватывает AJAX-запросы, выполненные с помощью jQuery или собственного API fetch. Эти запросы отображаются в виде дополнительных строк в панели Tracy, что позволяет легко и просто отлаживать AJAX.

Если вы не хотите автоматически перехватывать AJAX-запросы, вы можете отключить эту функцию, установив переменную JavaScript:

window.TracyAutoRefresh = false;

Для ручного мониторинга определенных AJAX-запросов добавьте HTTP-заголовок X-Tracy-Ajax со значением, возвращаемым функцией Tracy.getAjaxHeader(). Вот пример его использования с функцией fetch:

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

Такой подход позволяет выборочно отлаживать AJAX-запросы.

Хранение данных

Tracy может отображать панели Tracy bar и Bluescreens для AJAX-запросов и редиректов. Tracy создает собственные сессии, хранит данные в собственных временных файлах и использует cookie tracy-session.

Tracy также может быть настроен на использование собственной сессии PHP, которая запускается до включения Tracy:

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

В случае, если запуск сессии требует более сложной инициализации, вы можете запустить Tracy сразу (чтобы он мог обработать любые возникающие ошибки), затем инициализировать обработчик сессии и, наконец, сообщить Tracy, что сессия готова к использованию, используя функцию dispatch():

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

// затем инициализация сеанса
// и начать сеанс
session_start();

Debugger::dispatch();

Функция setSessionStorage() существует с версии 2.9, до этого Tracy всегда использовал родную сессию PHP.

Пользовательский скраббер

Scrubber – это фильтр, который предотвращает утечку конфиденциальных данных из дампов, таких как пароли или учетные данные. Фильтр вызывается для каждого элемента массива или объекта дампа и возвращает true, если значение является чувствительным. В этом случае вместо значения выводится *****.

// позволяет избежать дампа значений ключей и свойств, таких как `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD` и т.д.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// мы используем его для всех дампов внутри BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;

Пользовательский регистратор

Мы можем создать пользовательский логгер, который будет регистрировать ошибки, невыявленные исключения, а также вызываться Tracy\Debugger::log(). Logger реализует интерфейс Tracy\ILogger.

use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// отправляет запрос в Slack
	}
}

Затем мы активируем его:

Tracy\Debugger::setLogger(new SlackLogger);

Если мы используем полный Nette Framework, мы можем установить его в конфигурационном файле NEON:

services:
	tracy.logger: SlackLogger

Monolog Integration

Пакет Tracy предоставляет адаптер PSR-3, позволяющий интегрировать 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'); // пишет: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // пишет: [<TIMESTAMP>] main-channel.WARNING: warning [] []

nginx

Если Tracy не работает на nginx, скорее всего, он неправильно настроен. Если есть что-то вроде

try_files $uri $uri/ /index.php;

измените его на

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