Home

Laravel ChronoTrace

⏱️ Record and replay Laravel requests deterministically

Capture all database queries, cache operations, HTTP calls, and queue jobs for debugging and analysis.

---

🚀 Quick Start

Laravel ChronoTrace is a powerful debugging and monitoring tool that helps you understand exactly what happens during Laravel request execution. Perfect for debugging production issues, performance analysis, and understanding complex application flows.

What can you do with ChronoTrace?

• 🎯 Capture complete HTTP request execution context
• 🔄 Replay traces to analyze what happened during specific requests
• 🔍 Debug production issues with comprehensive event logs
• 📊 Monitor application performance and identify bottlenecks

Installation

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

Your First Trace

1. Enable recording (already enabled by default in development)
2. Make a request to your application
3. View the trace using php artisan chronotrace:list
4. Replay the trace with php artisan chronotrace:replay {trace-id}

---

📚 Documentation Structure

Getting Started

• Installation & Setup - Install and configure ChronoTrace
• Basic Usage - Learn the fundamentals and common workflows
• Your First Trace - Step-by-step guide to recording and analyzing traces

Core Concepts

• Understanding Traces - Learn how ChronoTrace captures application state
• Event Capturing - Configure what events to capture (DB, cache, HTTP, jobs)
• Event Filtering - Focus on specific event types during analysis

Configuration

• Configuration - Complete configuration reference
• Recording Modes - Choose when to record traces
• Storage Options - Local, S3, and custom storage backends

Commands & Tools

• Artisan Commands - Complete command reference
• Testing Internal Operations - Test ChronoTrace functionality

Advanced Usage

• Production Monitoring - Best practices for production use
• Custom Storage - Implement custom storage adapters
• Security & PII - Protect sensitive data in traces

Examples & Guides

• Debugging Database Issues - Real-world database debugging scenarios
• Performance Analysis - Identify and fix performance bottlenecks
• API Integration Debugging - Debug external API calls and integrations

Reference

• API Reference - Complete API documentation
• Configuration Examples - Ready-to-use configuration examples
• Troubleshooting - Common issues and solutions

---

🎯 Key Features

Smart Recording Modes

• Always - Record every request (development)
• Sample - Record percentage of successful requests
• Error-only - Record only failed requests (production)
• Targeted - Record specific routes or conditions

Comprehensive Event Capture

• Database queries with bindings and execution time
• Cache operations (get, set, forget, etc.)
• HTTP requests to external APIs
• Queue jobs and their payloads
• Custom events for application-specific tracking

Flexible Analysis

• Complete timeline of request execution
• Performance metrics and bottleneck identification
• Event filtering to focus on specific areas
• Replay capability for detailed investigation

Production Ready

• Minimal performance impact with async storage
• PII scrubbing to protect sensitive data
• Automatic cleanup with configurable retention
• Multiple storage backends (local, S3, custom)

---

💡 Common Use Cases

🐛 Debugging Production Issues

Record traces when errors occur to understand exactly what went wrong, including all database queries and external API calls that led to the failure.

⚡ Performance Optimization

Identify slow queries, excessive cache misses, or inefficient API calls by analyzing trace timelines and performance metrics.

🔍 Understanding Complex Flows

Trace multi-step processes involving databases, caches, queues, and external services to understand the complete execution flow.

🧪 Testing & Development

Record traces during development to ensure your application behaves as expected and to document complex business logic.

---

🤝 Getting Help

• Troubleshooting Guide - Solutions to common problems
• GitHub Issues - Report bugs or request features
• Configuration Examples - Copy-paste configurations for common scenarios

---

Ready to start? Head over to Installation & Setup to get ChronoTrace running in your Laravel application!