Tracy Documentation

The Logger::log() method appends text lines to <level>.log files. When a Throwable is logged, Tracy generates an HTML BlueScreen report and a .md companion file.

To prevent log flooding, Tracy uses hash-based deduplication:

1. It generates a hash of the exception chain (class, message, code, file, line, and trace without arguments) using xxh128, truncated to 10 characters.
2. Because arguments are stripped from the trace, identical exceptions thrown with different argument values produce the same hash.
3. If a report with that hash already exists, Tracy will not overwrite it; it will only append a new line to the <level>.log file. This ensures that recurring errors do not repeatedly generate heavy HTML reports.

You can manually control the mode or restrict development access to specific IP addresses or via a cookie.

• Force Development mode: Debugger::enable(Debugger::Development)
• Force Production mode: Debugger::enable(Debugger::Production)
• Restrict to specific IP(s): Debugger::enable('23.75.345.200') or Debugger::enable(['127.0.0.1', '192.168.1.1'])
• Secure access via IP + Cookie: Use the format IP@secret_token. Tracy will only enable development mode if the user accesses from that IP and has a cookie named tracy-debug containing the secret token.

Tracy uses a DeferredContent mechanism to ensure debug information (like the Tracy Bar or BlueScreen) is displayed even when the initial response cannot contain a body, such as during a Redirect or an AJAX request.

Instead of rendering directly into the current response, the content is stored in the session and delivered via a second HTTP request made by the browser. This allows debug output to 'survive' redirects and appear on the subsequent page, or be fetched as a separate payload during AJAX operations.

Tracy's PHP side and client-side JavaScript (bar.js, bluescreen.js, dumper.js, etc.) are coupled via string-based contracts. This means function names, element IDs, attribute names, and storage keys must match exactly between PHP and JS. Renaming a symbol on one side without updating the other will cause silent runtime failures.

Key areas of coupling include:

• JS Method Calls: PHP uses DeferredContent::addSetup($method, $argument) to emit literal JS calls that must match symbols on window.Tracy.
• Data Attributes: The dumper uses specific data-tracy-* attributes to handle lazy loading and snapshots.
• DOM IDs: Specific IDs like tracy-debug-bar and tracy-bs are expected by the JS logic.
• Storage Keys: Tracy uses localStorage and sessionStorage with specific keys for persistence (e.g., tracy-debug-bar).

The render() method behaves differently depending on the request type to ensure the toolbar appears correctly:

• AJAX/Deferred: It adds a setup script Tracy.Debug.loadAjax to render the ajax partial.
• Redirect: It pushes the partial onto the session redirect queue so the toolbar appears after the destination page loads.
• Normal HTML:
  • It renders the main partial.
  • It drains the redirect queue (processing items in reverse order) so that bars from previous redirects are displayed.
  • It either adds Tracy.Debug.init via a setup script or requires loader.phtml directly.

Note on Headers: If a Content-Length header has already been sent, Tracy will log a LogicException and skip injecting the markup to avoid corrupting the response.

When determining where a dump originated, findCallerLocation() may silently skip certain frames in the call stack. It ignores frames if:

• The frame's docblock contains the @tracySkipLocation annotation.
• The frame is located under paths defined in Debugger::$transparentPaths.

BlueScreen is the component responsible for generating the HTML error page. It provides several rendering methods depending on the desired output:

• render(): Builds the standard HTML error page using page.phtml.
• renderToAjax(...): Defers rendering via an AJAX call (using addSetup('Tracy.BlueScreen.loadAjax', ...)).
• renderToFile(string $path): Writes the HTML error page to a file using fopen(..., 'x'). This ensures existing files are never overwritten. It also creates a .md companion file.
• renderAgent(): Produces a markdown variant of the error report.

All these methods rely on renderTemplate, which assembles the headers, CSS/JS assets, dumpers, and a live shared snapshot used for data capture during the rendering process.

The isHtmlMode() helper acts as a global gate to determine if Tracy is allowed to inject debug information (like the Tracy Bar) into the current HTTP response. It returns false in the following scenarios:

• The request is an AJAX request (detected via X-Requested-With or X-Tracy-Ajax headers).
• The environment is CLI.
• The HTTP_HOST is missing.
• The response has already sent a Content-Type header that is not text/html.

Tracy manages deferred content in the session with specific cleanup rules:

• Automatic Cleanup: The clean() method keeps only the last 10 items per key and only those younger than 60 seconds. This runs inside sendAssets() before content is fetched.
• Data Requirement: Every item stored in the session must carry a time key; otherwise, clean() will silently discard it.
• Static Assets: The URL ?_tracy_bar=js serves merged static assets (minified CSS and IIFE-wrapped JS) with a long Cache-Control header.

Session Types:

• FileSession: Uses a cookie tracy-session and files named tracy-<id>. Warning: This uses blocking flock(LOCK_EX) which can cause concurrent requests (like an AJAX call and a main page load) to serialize/block each other.