Recipes
Content Security Policy
If your site uses Content Security Policy, you'll need to add 'nonce-<value>' and
'strict-dynamic' to script-src for Tracy to work properly. Some 3rd plugins may require additional
directives. Nonce is not supported in the style-src directive, if you use this directive you need to add
'unsafe-inline', but this should be avoided in production mode.
Configuration example for Nette Framework:
http:
csp:
script-src: [nonce, strict-dynamic]
Example in pure PHP:
$nonce = base64_encode(random_bytes(20));
header("Content-Security-Policy: script-src 'nonce-$nonce' 'strict-dynamic';");
Faster Loading
The basic integration is straightforward, however if you have slow blocking scripts in web page, they can slow the Tracy
loading. The solution is to place <?php Tracy\Debugger::renderLoader() ?> into your template before any
scripts:
<!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>
Debugging AJAX Requests
Tracy automatically captures AJAX requests made using jQuery or the native fetch API. These requests are displayed
as additional rows in the Tracy bar, enabling easy and convenient AJAX debugging.
If you do not want to capture AJAX requests automatically, you can disable this feature by setting the JavaScript variable:
window.TracyAutoRefresh = false;
For manual monitoring of specific AJAX requests, add the HTTP header X-Tracy-Ajax with the value returned by
Tracy.getAjaxHeader(). Here is an example of using it with the fetch function:
fetch(url, {
headers: {
'X-Requested-With': 'XMLHttpRequest',
'X-Tracy-Ajax': Tracy.getAjaxHeader(),
}
})
This approach allows for selective debugging of AJAX requests.
Data Storage
Tracy can display Tracy bar panels and Bluescreens for AJAX requests and redirects. Tracy creates its own sessions, stores data
in its own temporary files, and uses a tracy-session cookie.
Tracy can also be configured to use a native PHP session, which is started before Tracy is turned on:
session_start();
Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();
In case starting a session requires more complex initialization, you can start Tracy immediately (so that it can handle any
errors that occur) and then initialize the session handler and finally inform Tracy that the session is ready to be used using the
dispatch() function:
Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();
// followed by session initialization
// and start the session
session_start();
Debugger::dispatch();
The setSessionStorage() function has existed since version 2.9, before that Tracy always used the native PHP
session.
Custom Scrubber
Scrubber is a filter that prevents sensitive data from leaking from dumps, such as passwords or credentials. The filter is
called for each item of the dumped array or object and returns true if the value is sensitive. In this case,
***** is printed instead of the value.
// avoids dumping key values and properties such as `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD`, etc.
$scrubber = function(string $key, $value, ?string $class): bool
{
return preg_match('#password#i', $key) && $value !== null;
};
// we use it for all dumps inside BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;
Custom Logger
We can create a custom logger to log errors, uncatched exceptions, and also be called by Tracy\Debugger::log().
Logger implements the interface Tracy\ILogger.
use Tracy\ILogger;
class SlackLogger implements ILogger
{
public function log($value, $priority = ILogger::INFO)
{
// sends a request to Slack
}
}
And then we activate it:
Tracy\Debugger::setLogger(new SlackLogger);
If we use the full Nette Framework, we can set it in the NEON configuration file:
services:
tracy.logger: SlackLogger
Monolog Integration
Tracy package provides a PSR-3 adapter, allowing for integration of 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'); // writes: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // writes: [<TIMESTAMP>] main-channel.WARNING: warning [] []
nginx
If Tracy does not work on nginx, it is probably misconfigured. If there is something like
try_files $uri $uri/ /index.php;
change it to
try_files $uri $uri/ /index.php$is_args$args;
