README

High-fidelity process tracking, deterministic replay, and AI-powered 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.

✨ Key Features

Feature	TraceReplay	Telescope	Debugbar	Clockwork
Manual step instrumentation	✅	❌	❌	❌
Waterfall timeline UI	✅	❌	✅	✅
Deterministic HTTP replay	✅	❌	❌	❌
Visual JSON diff on replay	✅	❌	❌	❌
AI fix-prompt generator	✅	❌	❌	❌
OpenAI / Anthropic / Ollama	✅	❌	❌	❌
Cache & HTTP tracking	✅	✅	✅	✅
Mail & Notification tracking	✅	❌	❌	❌
DB query tracking per step	✅	✅	✅	✅
Memory tracking per step	✅	❌	✅	✅
Peak memory tracking	✅	✅	❌	❌
Livewire Hydrate Tracing	✅	❌	❌	❌
PII / sensitive-field masking	✅	❌	❌	❌
Queue-job auto-tracing	✅	✅	❌	❌
Artisan-command auto-tracing	✅	✅	❌	❌
Probabilistic Sampling	✅	❌	❌	❌
Dashboard auth & Gate gate	✅	✅	❌	N/A
Multi-tenant scoping	✅	❌	❌	❌
W3C Traceparent support	✅	❌	❌	❌
Octane Compatible	✅	✅	❌	❌

🛠 Installation

composer require iazaran/trace-replay

Publish the config:

php artisan vendor:publish --tag=trace-replay-config

Run migrations:

php artisan migrate

Note: Migrations run automatically without publishing. They use json columns and decimal precision for timings, compatible with MySQL 5.7+, MariaDB, PostgreSQL, and SQLite.

Publishing Views

To customize the dashboard UI:

php artisan vendor:publish --tag=trace-replay-views

This copies the Blade templates to resources/views/vendor/trace-replay/ where you can customize the layout, colors, or add your own branding.

Recommended: Enable HTTP Middleware

To automatically trace all HTTP requests, add the TraceMiddleware to your application. This provides instant visibility into every request without manual instrumentation.

For Laravel 10 (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);
})

⚙️ Configuration

Open config/trace-replay.php. Key options include:

return [
    'enabled' => env('TRACE_REPLAY_ENABLED', true),

    // 0.1 = trace 10% of requests/jobs/commands
    'sample_rate' => env('TRACE_REPLAY_SAMPLE_RATE', 1.0),

    // Automatically mask these keys in payloads
    'mask_fields' => ['password', 'token', 'api_key', 'authorization', 'secret'],

    // Dashbord security: only users passing the "view-trace-replay" gate can access
    'middleware' => ['web', 'auth'],

    // AI Troubleshooting (Drivers: openai, anthropic, ollama)
    'ai' => [
        'driver' => env('TRACE_REPLAY_AI_DRIVER', 'openai'),
        'api_key' => env('TRACE_REPLAY_AI_KEY'),
        'model' => env('TRACE_REPLAY_AI_MODEL', 'gpt-4o'),
    ],

    // Async batch persistence via queue (Reduces overhead)
    'queue' => [
        'enabled' => env('TRACE_REPLAY_QUEUE_ENABLED', false),
    ],

    // Auto-tracing
    'auto_trace' => [
        'jobs'     => true,
        'commands' => false,
        'livewire' => true,
    ],
];

🚀 Usage

Manual Instrumentation

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 validated', ['seats_left' => $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` if disabled/sampled-out
`TraceReplay::step(label, callable, extra[])`	Wrap callable, record timing, memory, DB queries, errors
`TraceReplay::measure(label, callable)`	Alias for `step()` — semantic clarity for benchmarks
`TraceReplay::checkpoint(label, state[])`	Record a 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`)
`TraceReplay::setWorkspaceId(id)`	Scope subsequent traces to a workspace
`TraceReplay::setProjectId(id)`	Scope subsequent traces to a project

Testing Helper

Use TraceReplay::fake() to verify your instrumentation in tests without hitting the database:

use TraceReplay\Facades\TraceReplay;

public function test_booking_records_steps()
{
    $fake = TraceReplay::fake();

    $this->post('/book', ['flight_id' => 123]);

    $fake->assertTraceStarted('Flight Booking');
    $fake->assertStepRecorded('Validate Inventory');
    $fake->assertStepRecorded('Charge Credit Card');
    $fake->assertCheckpointRecorded('Inventory validated');
    $fake->assertTraceEnded('success');
    $fake->assertTraceCount(1);
}

Available assertions:

Assertion	Description
`assertTraceStarted(name)`	Assert a trace with the given name was started
`assertNoTraceStarted()`	Assert no trace was started at all
`assertTraceCount(n)`	Assert exactly `n` traces were started
`assertStepRecorded(label)`	Assert a step with the given label was recorded
`assertCheckpointRecorded(label)`	Assert a checkpoint with the given label was recorded
`assertStepCount(n, traceName?)`	Assert exactly `n` steps in total (or in a named trace)
`assertTraceEnded(status)`	Assert a trace with the given final status exists

Auto Queue-Job Tracing

Queue jobs are automatically traced when auto_trace.jobs is enabled (default: true). No manual listener registration is needed — the service provider wires everything up.

To disable, set TRACE_REPLAY_AUTO_TRACE_JOBS=false in your .env.

Auto Artisan-Command Tracing

Artisan commands can be auto-traced by enabling auto_trace.commands:

TRACE_REPLAY_AUTO_TRACE_COMMANDS=true

Internal commands like queue:work, horizon, and trace-replay:prune are excluded by default (see auto_trace.exclude_commands in the config).

Debug Bar Component

Drop the <x-trace-replay-trace-bar /> Blade component into your layout for instant in-page trace inspection:

{{-- resources/views/layouts/app.blade.php --}}
@if(config('app.debug'))
    <x-trace-replay-trace-bar />
@endif

🎨 The Dashboard

Access the built-in dashboard at https://your-app.com/trace-replay.

Features:

Waterfall timeline — visual bars show each step's exact duration relative to the total trace
Live stats — auto-refreshing counters (total traces, failed, avg duration)
Search & filter — filter by name, IP, user ID; toggle failed-only view
Date range filter — quickly filter traces by today, yesterday, last 7 days, or last 30 days
Step inspector — syntax-highlighted JSON for request payload, response payload, and state snapshot
Replay engine — re-execute any HTTP step and view a structural JSON diff
AI Fix Prompt — one-click prompt ready for Cursor, ChatGPT, or Claude

Securing the Dashboard

Add authentication or authorization middleware in config/trace-replay.php:

'middleware' => ['web', 'auth', 'can:view-trace-replay'],

Then define the gate:

// app/Providers/AuthServiceProvider.php
Gate::define('view-trace-replay', function ($user) {
    return in_array($user->email, config('trace-replay.admin_emails', []));
});

Or use IP allowlisting (exact match, comma-separated via env):

TRACE_REPLAY_ALLOWED_IPS=203.0.113.5,10.0.0.1

🤖 AI Debugging

For any failed trace the dashboard shows an AI Fix Prompt button that generates a structured markdown prompt including:

Full execution timeline with timing and DB stats
The exact error message, file, line, and first 20 stack frames
Request/response payloads (sensitive fields masked)
Step-by-step state snapshots

No API Key Required

The AI prompt feature works without any API key. Copy the generated prompt and paste it into ChatGPT, Claude, or any other AI assistant.

Optional: Direct AI Integration

For a seamless experience, configure an AI driver to get answers directly in the dashboard:

# OpenAI (default)
TRACE_REPLAY_AI_DRIVER=openai
TRACE_REPLAY_AI_KEY=sk-your-openai-key
TRACE_REPLAY_AI_MODEL=gpt-4o

# Or Anthropic Claude
TRACE_REPLAY_AI_DRIVER=anthropic
TRACE_REPLAY_AI_KEY=sk-ant-your-key
TRACE_REPLAY_AI_MODEL=claude-3-5-sonnet-latest

# Or Ollama (local, no API key needed)
TRACE_REPLAY_AI_DRIVER=ollama
TRACE_REPLAY_AI_MODEL=llama3
TRACE_REPLAY_AI_BASE_URL=http://localhost:11434/api/generate

With a key configured, clicking "Ask AI" sends the prompt to your chosen AI provider and displays the response in the dashboard.

🤖 MCP / AI-Agent JSON-RPC API

TraceReplay exposes a JSON-RPC 2.0 endpoint at POST /api/trace-replay/mcp for autonomous AI agents.

Available methods:

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

Example request:

{
  "jsonrpc": "2.0",
  "method": "generate_fix_prompt",
  "params": { "trace_id": "9b12f7e4-..." },
  "id": 1
}

🧹 Data Retention

Automatically prune old traces with the built-in Artisan command. Add to your scheduler:

// app/Console/Kernel.php
$schedule->command('trace-replay:prune --days=30')->daily();

Options:

php artisan trace-replay:prune --days=30                # Delete traces older than 30 days
php artisan trace-replay:prune --days=30 --dry-run      # Preview what would be deleted
php artisan trace-replay:prune --days=7 --status=error  # Only prune error traces

📤 Export

Export a trace to JSON or CSV for archiving or external analysis:

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  # Export all error traces

🧪 Testing

composer install
./vendor/bin/pest

104 tests, 208 assertions. The test suite covers:

Trace lifecycle (start, step, checkpoint, context, end, duration precision)
Error capturing, step ordering, DB query tracking
Model scopes (failed, successful, search)
Model accessors (error_step, total_db_queries, total_memory_usage, completion_percentage)
PayloadMasker — recursive PII field redaction, case-insensitivity
AiPromptService — prompt generation, OpenAI integration (mocked), null-safety
NotificationService — mail and Slack dispatch, null-safety
ReplayService — HTTP replay and JSON diff
Dashboard — index, filters, search, show, stats, export, replay, AI prompt
MCP API — REST endpoints and JSON-RPC (all methods + error handling)
Middleware — TraceMiddleware (route skipping, disabled config), AuthMiddleware (IP allow/block)
Artisan trace-replay:prune (delete, dry-run, status filter, validation)
Artisan trace-replay:export (JSON, CSV, file output, status filter, validation)
TraceReplayFake — assertions for started/count/steps/checkpoints/ended
Log call tracking per step
NotificationService — error_reason array/string serialisation safety
Blade components — TraceBar rendering with enabled/disabled states

🛡️ License

The MIT License (MIT). See LICENSE for details.

iazaran / trace-replay

Maintainers

Package info

Statistics

Security