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.
composer require iazaran/tracereplaycomposer require iazaran/trace-replayPublish config and migrations:
-php artisan vendor:publish --tag=tracereplay-config
-php artisan vendor:publish --tag=tracereplay-migrationsphp artisan vendor:publish --tag=trace-replay-config
+php artisan vendor:publish --tag=trace-replay-migrationsphp artisan migrateMigrations use json columns for full MySQL, MariaDB, PostgreSQL, and SQLite compatibility.
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.
php artisan vendor:publish --tag=trace-replay-viewsThis copies the Blade templates to resources/views/vendor/trace-replay/ where you can edit them freely. The package will automatically use your published versions instead of its built-in views.
Key options in config/tracereplay.php:
Key options in config/trace-replay.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),
+ 'enabled' => env('TRACE_REPLAY_ENABLED', true),
+ 'sample_rate' => env('TRACE_REPLAY_SAMPLE_RATE', 1.0), // 0.1 = 10% of requests
+ 'project_id' => env('TRACE_REPLAY_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),
+ 'track_db_queries' => env('TRACE_REPLAY_TRACK_DB', true),
'middleware' => ['web'], // add 'auth', 'can:...' for production
'api_middleware' => ['api'],
- 'allowed_ips' => array_filter(explode(',', env('TRACEREPLAY_ALLOWED_IPS', ''))),
+ 'allowed_ips' => array_filter(explode(',', env('TRACE_REPLAY_ALLOWED_IPS', ''))),
'queue' => [
- 'enabled' => env('TRACEREPLAY_QUEUE_ENABLED', false),
- 'connection' => env('TRACEREPLAY_QUEUE_CONNECTION', env('QUEUE_CONNECTION', 'sync')),
- 'queue' => env('TRACEREPLAY_QUEUE_NAME', 'default'),
+ 'enabled' => env('TRACE_REPLAY_QUEUE_ENABLED', false),
+ 'connection' => env('TRACE_REPLAY_QUEUE_CONNECTION', env('QUEUE_CONNECTION', 'sync')),
+ 'queue' => env('TRACE_REPLAY_QUEUE_NAME', 'default'),
],
'replay' => [
- 'default_base_url' => env('TRACEREPLAY_REPLAY_URL', env('APP_URL')),
- 'timeout' => env('TRACEREPLAY_REPLAY_TIMEOUT', 30),
+ 'default_base_url' => env('TRACE_REPLAY_REPLAY_URL', env('APP_URL')),
+ 'timeout' => env('TRACE_REPLAY_REPLAY_TIMEOUT', 30),
],
- 'retention_days' => env('TRACEREPLAY_RETENTION_DAYS', 30),
+ 'retention_days' => env('TRACE_REPLAY_RETENTION_DAYS', 30),
'notifications' => [
- 'on_failure' => env('TRACEREPLAY_NOTIFY_ON_FAILURE', false),
+ 'on_failure' => env('TRACE_REPLAY_NOTIFY_ON_FAILURE', false),
'channels' => ['mail'],
- 'mail' => ['to' => env('TRACEREPLAY_NOTIFY_EMAIL')],
- 'slack' => ['webhook_url' => env('TRACEREPLAY_SLACK_WEBHOOK')],
+ 'mail' => ['to' => env('TRACE_REPLAY_NOTIFY_EMAIL')],
+ 'slack' => ['webhook_url' => env('TRACE_REPLAY_SLACK_WEBHOOK')],
],
'ai' => [
- 'openai_api_key' => env('TRACEREPLAY_OPENAI_KEY'),
- 'model' => env('TRACEREPLAY_OPENAI_MODEL', 'gpt-4o'),
+ 'openai_api_key' => env('TRACE_REPLAY_OPENAI_KEY'),
+ 'model' => env('TRACE_REPLAY_OPENAI_MODEL', 'gpt-4o'),
],
'auto_trace' => [
- 'jobs' => env('TRACEREPLAY_AUTO_TRACE_JOBS', true),
- 'commands' => env('TRACEREPLAY_AUTO_TRACE_COMMANDS', false),
+ 'jobs' => env('TRACE_REPLAY_AUTO_TRACE_JOBS', true),
+ 'commands' => env('TRACE_REPLAY_AUTO_TRACE_COMMANDS', false),
'exclude_commands' => ['queue:work', 'queue:listen', 'horizon', 'schedule:run',
- 'schedule:work', 'tracereplay:prune', 'tracereplay:export'],
+ 'schedule:work', 'trace-replay:prune', 'trace-replay:export'],
],
];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).
TRACE_REPLAY_AUTO_TRACE_COMMANDS=trueInternal commands like queue:work, horizon, and trace-replay:prune are excluded by default (see auto_trace.exclude_commands).
Navigate to https://your-app.com/tracereplay.
Navigate to https://your-app.com/trace-replay.
Add authentication or authorization middleware in config/tracereplay.php:
// config/tracereplay.php
-'middleware' => ['web', 'auth', 'can:view-tracereplay'],
+ Add authentication or authorization middleware in config/trace-replay.php:
+ // config/trace-replay.php
+'middleware' => ['web', 'auth', 'can:view-trace-replay'],
// AuthServiceProvider
-Gate::define('view-tracereplay', fn ($user) =>
+Gate::define('view-trace-replay', 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.1
+ TRACE_REPLAY_ALLOWED_IPS=203.0.113.5,10.0.0.1
Data Masking
TraceReplay automatically redacts configured keys from all request/response payloads before they touch the database β including deeply nested values:
- // config/tracereplay.php
+ // config/trace-replay.php
'mask_fields' => ['password', 'token', 'secret', 'api_key', 'credit_card'],
// Input: ['username' => 'alice', 'password' => 'hunter2']
@@ -318,7 +318,7 @@ AI Debugging
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.
+ Autonomous agents can query TraceReplay over JSON-RPC 2.0 at POST /api/trace-replay/mcp.
Method Params Returns MCP / AI-Agent JSON-RPC API
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 traces
+$schedule->command('trace-replay:prune --days=30')->daily();
+ php artisan trace-replay:prune --days=30 --dry-run # preview
+php artisan trace-replay:prune --days=7 --status=error # prune only error traces
Export 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 traces
+ php artisan trace-replay:export {id} --format=json
+php artisan trace-replay:export {id} --format=csv
+php artisan trace-replay:export {id} --format=json --output=/tmp/trace.json
+php artisan trace-replay:export --status=error --format=json # all error traces
Testing
./vendor/bin/pest
diff --git a/docs/robots.txt b/docs/robots.txt
index 77e19f7..aaf55be 100644
--- a/docs/robots.txt
+++ b/docs/robots.txt
@@ -1,3 +1,3 @@
User-agent: *
Allow: /
-Sitemap: https://iazaran.github.io/tracereplay/sitemap.xml
+Sitemap: https://iazaran.github.io/trace-replay/sitemap.xml
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
index 651a20f..4216178 100644
--- a/docs/sitemap.xml
+++ b/docs/sitemap.xml
@@ -1,7 +1,7 @@
- https://iazaran.github.io/tracereplay/
+ https://iazaran.github.io/trace-replay/
2024-05-01T00:00:00+00:00
weekly
1.0
diff --git a/phpunit.xml b/phpunit.xml
index ff1499b..b244bc1 100644
--- a/phpunit.xml
+++ b/phpunit.xml
@@ -22,7 +22,7 @@