Record and replay Laravel requests deterministically and generate tests from production traces.

#Laravel ChronoTrace

⏱️ Record and replay Laravel requests deterministically — capture all database queries, cache operations, HTTP calls, and queue jobs for debugging and analysis.

#📖 Overview

Laravel ChronoTrace is a powerful debugging and monitoring tool for Laravel applications that allows you to:

• 🎯 Capture HTTP requests and their complete execution context (DB queries, cache operations, external HTTP calls, queue jobs)
• 🔄 Replay traces to analyze what happened during specific requests
• 🔍 Debug production issues with comprehensive event logs
• 📊 Monitor application performance and identify bottlenecks

Perfect for debugging hard-to-reproduce issues, performance analysis, and understanding complex application flows.

#✨ Features

• ⏺️ Smart Recording – Multiple recording modes: always, sample rate, error-only, or targeted routes
• 📊 Comprehensive Event Capture – Database queries, cache operations, HTTP requests, queue jobs, and custom events
• 🔄 Detailed Replay – View complete execution flow with timestamps and performance metrics
• 🎯 Flexible Filtering – Focus on specific event types (DB, cache, HTTP, jobs) during analysis
• 💾 Multiple Storage Options – Local storage, S3, or custom storage adapters
• 🔐 PII Scrubbing – Automatically mask sensitive data (passwords, tokens, emails, etc.)
• ⚡ Async Storage – Queue-based storage for minimal performance impact
• 🗂️ Automatic Cleanup – Configurable retention policies and automatic purging

#📦 Installation

composer require --dev grazulex/laravel-chronotrace

Requirements:

• PHP 8.3+
• Laravel 12.x

#🚀 Quick Start

#1️⃣ Install and Configure

composer require --dev grazulex/laravel-chronotrace
php artisan chronotrace:install

#2️⃣ Configure Recording Mode

Edit config/chronotrace.php or set environment variables:

CHRONOTRACE_ENABLED=true
CHRONOTRACE_MODE=record_on_error  # always | sample | record_on_error | targeted
CHRONOTRACE_STORAGE=local         # local | s3

#3️⃣ Record Traces

For debugging real application issues:

# Record a specific endpoint
php artisan chronotrace:record /api/users
 
# Record with POST data
php artisan chronotrace:record /api/users \
  --method=POST \
  --data='{"name":"John","email":"john@example.com"}'
 
# Record with custom headers
php artisan chronotrace:record /api/protected \
  --method=GET \
  --headers='{"Authorization":"Bearer token123"}'

For testing ChronoTrace configuration:

# Test that ChronoTrace captures internal operations
php artisan chronotrace:test-internal
 
# Test specific operation types
php artisan chronotrace:test-internal --with-db --with-cache

💡 Key Difference: chronotrace:record captures real HTTP requests for debugging actual issues, while chronotrace:test-internal validates that ChronoTrace is properly configured and working.

#4️⃣ View Your Traces

# List all traces
php artisan chronotrace:list
 
# List with full trace IDs
php artisan chronotrace:list --full-id
 
# Replay a specific trace (use ID from list command)
php artisan chronotrace:replay abc12345-def6-7890-abcd-ef1234567890

#5️⃣ Filter Events and Generate Tests

# View only database queries
php artisan chronotrace:replay {trace-id} --db
 
# View only cache operations
php artisan chronotrace:replay {trace-id} --cache
 
# View only HTTP requests
php artisan chronotrace:replay {trace-id} --http
 
# View only queue jobs
php artisan chronotrace:replay {trace-id} --jobs
 
# View detailed information with context, headers, and content
php artisan chronotrace:replay {trace-id} --detailed
 
# Show SQL query bindings for debugging
php artisan chronotrace:replay {trace-id} --db --bindings
 
# Generate Pest tests from traces
php artisan chronotrace:replay {trace-id} --generate-test
 
# Generate tests in custom directory
php artisan chronotrace:replay {trace-id} --generate-test --test-path=tests/Integration
 
# Output as JSON for programmatic processing
php artisan chronotrace:replay {trace-id} --format=json

#🔧 Storage & Configuration

• Local Storage: storage/chronotrace/{date}/{trace-id}/
• S3/Minio: Support for distributed setups with configurable buckets
• Automatic Cleanup: TTL-based purge policies (default: 15 days)
• Compression: Configurable compression for large traces
• PII Scrubbing: Automatic masking of sensitive fields

#📊 What Gets Captured

Each trace includes comprehensive information:

=== TRACE INFORMATION ===
🆔 Trace ID: abc12345-def6-7890-abcd-ef1234567890
🕒 Timestamp: 2024-01-15 14:30:22
🌍 Environment: production
🔗 Request URL: https://app.example.com/api/users
📊 Response Status: 200
⏱️  Duration: 245ms
💾 Memory Usage: 18.45 KB
 
=== CAPTURED EVENTS ===
📊 DATABASE EVENTS
  🔍 Query: SELECT * FROM users WHERE active = ? (15ms)
  🔍 Query: SELECT * FROM roles WHERE user_id IN (?, ?) (8ms)
 
🗄️  CACHE EVENTS
  ❌ Cache MISS: users:list (store: redis)
  💾 Cache WRITE: users:list (store: redis)
 
🌐 HTTP EVENTS
  📤 HTTP Request: GET https://api.external.com/validation
  📥 HTTP Response: 200 (1,234 bytes)
 
⚙️  JOB EVENTS
  🔄 Job STARTED: ProcessUserRegistration
  ✅ Job COMPLETED: ProcessUserRegistration

#🔧 Available Commands

#Recording & Analysis Commands

• chronotrace:record – Record real HTTP requests for debugging actual application issues
• chronotrace:list – List stored traces with metadata and filtering options
• chronotrace:replay – Replay and analyze captured traces with advanced filtering and output formats
• chronotrace:purge – Remove old traces based on retention policy

#Setup & Testing Commands

• chronotrace:install – Install and configure ChronoTrace middleware
• chronotrace:test-internal – Test ChronoTrace configuration with internal Laravel operations
• chronotrace:test-middleware – Test middleware installation and activation
• chronotrace:diagnose – Diagnose configuration and potential issues with comprehensive checks

#Command Examples

# Installation and setup
chronotrace:install --force
 
# Validate ChronoTrace is working
chronotrace:test-internal --with-db --with-cache
 
# Record real application traces
chronotrace:record /api/users --method=GET
chronotrace:record /checkout --method=POST --data='{"cart_id": 123}'
chronotrace:record /api/protected --headers='{"Authorization":"Bearer token"}'
 
# Advanced recording with timeout
chronotrace:record /api/slow-endpoint --timeout=60
 
# List and analyze traces
chronotrace:list --limit=10 --full-id
chronotrace:replay {trace-id} --db --cache --bindings
chronotrace:replay {trace-id} --detailed --context --headers
chronotrace:replay {trace-id} --generate-test --test-path=tests/Integration
 
# Output in different formats
chronotrace:replay {trace-id} --format=json
chronotrace:replay {trace-id} --format=raw
 
# Diagnostics and testing
chronotrace:diagnose
chronotrace:test-middleware
 
# Test internal operations when chronotrace:record doesn't capture internal events
chronotrace:test-internal --with-db --with-cache --with-events
chronotrace:test-internal --with-db  # Test only database operations
 
# Maintenance and cleanup
chronotrace:purge --days=7 --confirm

#📊 Use Cases

• Bug Reproduction – No more “can’t reproduce locally” issues
• Test Generation – Build realistic tests from production data
• Performance Audits – Find slow queries, N+1s and cache misses
• Configuration Validation – Diagnose setup issues with built-in tools
• Onboarding – Help new devs understand complex flows via execution graphs

#🔐 Security & Privacy

• PII scrubbing by default (configurable fields)
• Trace encryption at rest
• Trace TTL & purge policies
• Audit log of trace access

#🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for details.

#📚 Documentation

Complete documentation is available in the GitHub Wiki:

• 📦 Installation Guide - Step-by-step installation instructions
• ⚙️ Configuration Guide - Complete configuration reference
• 🔧 Commands Reference - Detailed guide to all commands
• 🎯 Choosing the Right Command - When to use record vs test-internal
• 🧪 Testing Internal Operations - Validate ChronoTrace configuration
• 💡 Examples & Workflows - Practical usage examples and common workflows
• 🔒 Security & Storage - Security features and storage options
• 🔍 Troubleshooting - Common issues and solutions

Laravel ChronoTrace is open-sourced software licensed under the MIT license.