#ADR 0006: Retain the current debug and error stack instead of Tracy

• Status: accepted
• Date: 2026-08-21

#Context

K0smos already separates five concerns: Symfony/Laminas own global and PSR-15 error flow, Whoops renders development exception HTML, PHPDebugBar injects request-local diagnostics, Clockwork persists request/query/timeline data, Monolog writes structured logs, and GlitchTip reports sanitized production errors remotely. The P8 backlog requested a replacement-oriented Tracy review.

A disposable Tracy 2.12.0 install was tested on PHP 8.5.9 outside the project. It is compatible and provides a strong BlueScreen, bar, dumps, logging, AJAX and CLI support. Enabling it also registers global shutdown, exception, and error handlers. In five identical processes it added 1,302,376 bytes of live memory and 1,413,840 bytes of peak memory. Configured dumps hid the synthetic secret; the default structured log path retained it.

#Decision

Do not adopt Tracy in 0.26.0.

Tracy could replace parts of Whoops and PHPDebugBar, but it does not replace Clockwork's current DBAL/Monolog request store or GlitchTip's remote production reporting. Adopting it alongside the existing stack would introduce a competing global handler; replacing the current components would require new PSR-15, PSR-7 AJAX, lifecycle, query, incident-ID, and redaction adapters without closing a measured gap.

K0smos keeps one global error-handler owner and the existing component roles. The Tracy package and bootstrap hooks remain absent.

#Re-evaluation triggers

Re-open only if:

1. Whoops or PHPDebugBar becomes incompatible with the supported PHP line;
2. a measured debugging scenario cannot be represented through DebugLogger and HttpDebugTracer;
3. the replacement removes at least one existing component and matches current redaction, JSON, CLI, DBAL, incident-correlation, and production-safety tests;
4. Tracy exposes a non-global integration suitable for the PSR-15 error owner, or k0smos intentionally replaces that owner.

#Evidence

See doc/public/en/architecture/evaluations/tracy.md and tools/benchmarks/tracy-spike.php.