TraceReplay Documentation
+High-fidelity process tracking, deterministic replay, and AI debugging for Laravel — production & enterprise ready.
+TraceReplay is not a standard error logger. It is a full-fledged execution tracer that captures every step of your complex workflows, reconstructs them with a waterfall timeline, and offers one-click AI debugging when things go wrong. It supports Laravel 10, 11, 12, and 13.
+ +Installation
+composer require iazaran/tracereplayPublish config and migrations:
+php artisan vendor:publish --tag=tracereplay-config
+php artisan vendor:publish --tag=tracereplay-migrationsphp artisan migrateMigrations use json columns for full MySQL, MariaDB, PostgreSQL, and SQLite compatibility.
Publishing Views (Recommended)
+TraceReplay ships with a polished, dark-themed dashboard featuring a waterfall timeline, syntax-highlighted JSON inspector, and live stats — all styled and ready to use out of the box. Publishing the views lets you customise the layout, colours, or add your own branding:
+php artisan vendor:publish --tag=tracereplay-viewsThis copies the Blade templates to resources/views/vendor/tracereplay/ where you can edit them freely. The package will automatically use your published versions instead of its built-in views.
Configuration
+Key options in config/tracereplay.php:
return [
+ 'enabled' => env('TRACEREPLAY_ENABLED', true),
+ 'sample_rate' => env('TRACEREPLAY_SAMPLE_RATE', 1.0), // 0.1 = 10% of requests
+ 'project_id' => env('TRACEREPLAY_PROJECT_ID', null),
+ 'mask_fields' => ['password', 'password_confirmation', 'token', 'api_key',
+ 'authorization', 'secret', 'credit_card', 'cvv', 'ssn', 'private_key'],
+ 'track_db_queries' => env('TRACEREPLAY_TRACK_DB', true),
+ 'middleware' => ['web'], // add 'auth', 'can:...' for production
+ 'api_middleware' => ['api'],
+ 'allowed_ips' => array_filter(explode(',', env('TRACEREPLAY_ALLOWED_IPS', ''))),
+ 'queue' => [
+ 'enabled' => env('TRACEREPLAY_QUEUE_ENABLED', false),
+ 'connection' => env('TRACEREPLAY_QUEUE_CONNECTION', env('QUEUE_CONNECTION', 'sync')),
+ 'queue' => env('TRACEREPLAY_QUEUE_NAME', 'default'),
+ ],
+ 'replay' => [
+ 'default_base_url' => env('TRACEREPLAY_REPLAY_URL', env('APP_URL')),
+ 'timeout' => env('TRACEREPLAY_REPLAY_TIMEOUT', 30),
+ ],
+ 'retention_days' => env('TRACEREPLAY_RETENTION_DAYS', 30),
+ 'notifications' => [
+ 'on_failure' => env('TRACEREPLAY_NOTIFY_ON_FAILURE', false),
+ 'channels' => ['mail'],
+ 'mail' => ['to' => env('TRACEREPLAY_NOTIFY_EMAIL')],
+ 'slack' => ['webhook_url' => env('TRACEREPLAY_SLACK_WEBHOOK')],
+ ],
+ 'ai' => [
+ 'openai_api_key' => env('TRACEREPLAY_OPENAI_KEY'),
+ 'model' => env('TRACEREPLAY_OPENAI_MODEL', 'gpt-4o'),
+ ],
+ 'auto_trace' => [
+ 'jobs' => env('TRACEREPLAY_AUTO_TRACE_JOBS', true),
+ 'commands' => env('TRACEREPLAY_AUTO_TRACE_COMMANDS', false),
+ 'exclude_commands' => ['queue:work', 'queue:listen', 'horizon', 'schedule:run',
+ 'schedule:work', 'tracereplay:prune', 'tracereplay:export'],
+ ],
+];Manual Tracing
+Wrap any complex logic in TraceReplay::step(). Each callback's return value is passed through transparently.
use TraceReplay\Facades\TraceReplay;
+
+class BookingService
+{
+ public function handleBooking(array $payload): void
+ {
+ TraceReplay::start('Flight Booking', ['channel' => 'web']);
+
+ try {
+ $inventory = TraceReplay::step('Validate Inventory', function () use ($payload) {
+ return Inventory::check($payload['flight_id']);
+ });
+
+ TraceReplay::checkpoint('Inventory OK', ['seats' => $inventory->seats]);
+
+ TraceReplay::context(['user_tier' => auth()->user()->tier]);
+
+ TraceReplay::step('Charge Credit Card', function () use ($payload) {
+ return PaymentGateway::charge($payload['amount']);
+ });
+
+ TraceReplay::end('success');
+ } catch (\Exception $e) {
+ TraceReplay::end('error');
+ throw $e;
+ }
+ }
+}API Reference
+| Method | Description |
|---|---|
TraceReplay::start(name, tags[]) | Start a new trace; returns Trace or null |
TraceReplay::step(label, callable, extra[]) | Wrap callable — records timing, memory, DB queries, errors |
TraceReplay::measure(label, callable) | Alias for step() — semantic clarity for benchmarks |
TraceReplay::checkpoint(label, state[]) | Zero-overhead breadcrumb (no callable) |
TraceReplay::context(array) | Merge data into the next step's state_snapshot |
TraceReplay::end(status) | Finalise trace; status: 'success' or 'error' |
TraceReplay::getCurrentTrace() | Returns the active Trace model or null |
HTTP Auto Ingestion
+Automatically trace every HTTP request. Add to app/Http/Kernel.php:
protected $middlewareGroups = [
+ 'web' => [
+ // ...
+ \TraceReplay\Http\Middleware\TraceMiddleware::class,
+ ],
+];For Laravel 11+ (bootstrap/app.php):
->withMiddleware(function (Middleware $middleware) {
+ $middleware->append(\TraceReplay\Http\Middleware\TraceMiddleware::class);
+})Auto Tracing — Jobs & Commands
+Queue jobs are automatically traced when auto_trace.jobs is enabled (default: true). No manual listener registration needed — the service provider wires everything up.
Artisan commands can be auto-traced by enabling auto_trace.commands:
TRACEREPLAY_AUTO_TRACE_COMMANDS=trueInternal commands like queue:work, horizon, and tracereplay:prune are excluded by default (see auto_trace.exclude_commands).
The Dashboard
+Navigate to https://your-app.com/tracereplay.
-
+
- Waterfall timeline — visual duration bars relative to total trace time +
- Live stats — auto-refreshing counters (total, failed, avg duration) +
- Search & filter — by name, IP, user ID; toggle failed-only +
- Step inspector — syntax-highlighted JSON payloads and state snapshots +
- Replay engine — re-run any HTTP step and view a structural JSON diff +
- AI Fix Prompt — one-click prompt for Cursor, ChatGPT, or Claude +
Security
+Add authentication or authorization middleware in config/tracereplay.php:
// config/tracereplay.php
+'middleware' => ['web', 'auth', 'can:view-tracereplay'],
+
+// AuthServiceProvider
+Gate::define('view-tracereplay', fn ($user) =>
+ in_array($user->email, ['admin@example.com'])
+);Or restrict by IP (exact match, comma-separated via env):
+TRACEREPLAY_ALLOWED_IPS=203.0.113.5,10.0.0.1Data Masking
+TraceReplay automatically redacts configured keys from all request/response payloads before they touch the database — including deeply nested values:
+// config/tracereplay.php
+'mask_fields' => ['password', 'token', 'secret', 'api_key', 'credit_card'],
+
+// Input: ['username' => 'alice', 'password' => 'hunter2']
+// Stored: ['username' => 'alice', 'password' => '********']Replay Engine
+When an HTTP request fails, TraceReplay lets you deterministically replay it from the dashboard. The replay engine proxies the original request, captures the new response, and generates an exact structural JSON diff.
+ +AI Debugging
+For any failed trace the dashboard shows an AI Fix Prompt button. It generates a structured markdown prompt containing:
+-
+
- Full execution timeline with per-step timing and DB query stats +
- Exact error message, file, line number, and first 20 stack frames +
- Request/response payloads (sensitive fields masked) +
- Step-by-step state snapshots +
Configure OPENAI_API_KEY and click "Ask AI" to get an answer directly in the dashboard.
MCP / AI-Agent JSON-RPC API
+Autonomous agents can query TraceReplay over JSON-RPC 2.0 at POST /api/tracereplay/mcp.
| Method | Params | Returns |
|---|---|---|
list_traces | limit, status | Array of trace summaries |
get_trace_context | trace_id | Full trace with steps |
generate_fix_prompt | trace_id | Markdown debugging prompt |
trigger_replay | trace_id | Replay result + JSON diff |
{
+ "jsonrpc": "2.0",
+ "method": "generate_fix_prompt",
+ "params": { "trace_id": "9b12f7e4-..." },
+ "id": 1
+}Data Retention
+Prune old traces automatically via the scheduler:
+// app/Console/Kernel.php
+$schedule->command('tracereplay:prune --days=30')->daily();php artisan tracereplay:prune --days=30 --dry-run # preview
+php artisan tracereplay:prune --days=7 --status=error # prune only error tracesExport a trace for archiving:
+php artisan tracereplay:export {id} --format=json
+php artisan tracereplay:export {id} --format=csv
+php artisan tracereplay:export {id} --format=json --output=/tmp/trace.json
+php artisan tracereplay:export --status=error --format=json # all error tracesTesting
+./vendor/bin/pestThe test suite (90 tests, 183 assertions) covers the full engine lifecycle, model scopes & accessors, payload masking, AI prompt & notification services, dashboard UI, MCP JSON-RPC API, middleware (trace & auth), replay engine, Artisan commands (prune & export with validation), and Blade components — all using an in-memory SQLite database.
+ ++
TraceReplay © 2026 — MIT License
+ +