Poradniki

Content Security Policy

Jeśli Twoja strona używa Content Security Policy, będziesz musiał dodać te same 'nonce-<value>' i 'strict-dynamic' do script-src, aby Tracy działała poprawnie. Niektóre dodatki stron trzecich mogą wymagać dodatkowych ustawień. Nonce nie jest obsługiwane w dyrektywie style-src, jeśli używasz tej dyrektywy, musisz dodać 'unsafe-inline', ale w trybie produkcyjnym powinieneś tego unikać.

Przykład konfiguracji dla Nette Framework:

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

Przykład w czystym PHP:

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

Szybsze ładowanie

Uruchomienie jest proste, jednak jeśli masz na stronie wolno ładujące się skrypty blokujące, mogą one spowolnić ładowanie Tracy. Rozwiązaniem jest umieszczenie <?php Tracy\Debugger::renderLoader() ?> w swoim szablonie przed wszystkimi skryptami:

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

Debugowanie żądań AJAX

Tracy automatycznie przechwytuje żądania AJAX utworzone za pomocą jQuery lub natywnego API fetch. Żądania są wyświetlane w pasku Tracy jako dodatkowe wiersze, co umożliwia łatwe i wygodne debugowanie AJAX.

Jeśli nie chcesz automatycznie przechwytywać żądań AJAX, możesz wyłączyć tę funkcję, ustawiając zmienną JavaScript:

window.TracyAutoRefresh = false;

Aby ręcznie monitorować określone żądania AJAX, dodaj nagłówek HTTP X-Tracy-Ajax z wartością zwróconą przez Tracy.getAjaxHeader(). Oto przykład użycia z funkcją fetch:

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

To podejście umożliwia selektywne debugowanie żądań AJAX.

Przechowywanie danych

Tracy potrafi wyświetlać panele w pasku Tracy i Bluescreeny dla żądań AJAX i przekierowań. Tracy tworzy własną sesję, przechowuje dane we własnych plikach tymczasowych i używa ciasteczka tracy-session.

Tracy można również skonfigurować tak, aby używała natywnej sesji PHP, którą uruchamiamy jeszcze przed włączeniem Tracy:

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

W przypadku, gdy uruchomienie sesji wymaga bardziej złożonej inicjalizacji, możesz uruchomić Tracy natychmiast (aby mogła przetworzyć ewentualne powstałe błędy), a następnie zainicjować obsługę sesji i na koniec poinformować Tracy, że sesja jest gotowa do użycia za pomocą funkcji dispatch():

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

// następuje inicjalizacja sesji
// i uruchomienie sesji
session_start();

Debugger::dispatch();

Funkcja setSessionStorage() istnieje od wersji 2.9, wcześniej Tracy zawsze używała natywnej sesji PHP.

Własny scrubber

Scrubber to filtr, który zapobiega wyciekowi wrażliwych danych podczas dumpowania, takich jak hasła czy dane dostępowe. Filtr jest wywoływany dla każdego elementu dumpowanej tablicy lub obiektu i zwraca true, jeśli wartość jest wrażliwa. W takim przypadku zamiast wartości wypisywane jest *****.

// zapobiega wypisywaniu wartości kluczy i właściwości takich jak `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD`, itp.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// użyjemy go dla wszystkich zrzutów wewnątrz BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;

Własny logger

Możemy stworzyć własny logger, który będzie logował błędy, nieprzechwycone wyjątki, a także będzie wywoływany przez metodę Tracy\Debugger::log(). Logger implementuje interfejs Tracy\ILogger.

use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// wyśle żądanie do Slack
	}
}

A następnie go aktywujemy:

Tracy\Debugger::setLogger(new SlackLogger);

Jeśli używamy pełnego Nette Framework, możesz go ustawić w pliku konfiguracyjnym NEON:

services:
	tracy.logger: SlackLogger

Integracja Monolog

Pakiet Tracy dostarcza adapter PSR-3, który umożliwia integrację z 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'); // zapisuje: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // zapisuje: [<TIMESTAMP>] main-channel.WARNING: warning [] []

nginx

Jeśli Tracy nie działa na serwerze nginx, prawdopodobnie jest on źle skonfigurowany. Jeśli w konfiguracji jest coś takiego jak:

try_files $uri $uri/ /index.php;

zmień to na:

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