# Artisan Commands ChronoTrace provides a comprehensive set of Artisan commands for managing traces, controlling recording, and analyzing application behavior. --- ## ๐Ÿ“‹ Quick Reference | Command | Purpose | Usage | |---------|---------|-------| | `chronotrace:list` | List captured traces | View and filter traces | | `chronotrace:replay` | Replay a specific trace | Analyze request execution | | `chronotrace:record` | Start manual recording | Control recording sessions | | `chronotrace:purge` | Clean up old traces | Manage storage space | | `chronotrace:diagnose` | System diagnostics | Check configuration | | `chronotrace:install` | Install ChronoTrace | Initial setup | | `chronotrace:test-internal` | Test functionality | Verify installation | | `chronotrace:middleware-test` | Test middleware | Debug middleware issues | --- ## ๐Ÿ” Listing & Analysis Commands ### `chronotrace:list` List all captured traces with filtering options. ```bash # Basic usage php artisan chronotrace:list # Show recent traces (default: 20) php artisan chronotrace:list --limit=50 # Filter by status php artisan chronotrace:list --status=error php artisan chronotrace:list --status=success php artisan chronotrace:list --status=422 # Filter by HTTP method php artisan chronotrace:list --method=POST php artisan chronotrace:list --method=GET,PUT # Filter by route pattern php artisan chronotrace:list --route="api/*" php artisan chronotrace:list --route="admin/users/*" # Filter by minimum duration (in milliseconds) php artisan chronotrace:list --min-duration=1000 # Filter by date range php artisan chronotrace:list --since="2024-08-01" php artisan chronotrace:list --since="yesterday" php artisan chronotrace:list --before="2024-08-06" # Combine filters php artisan chronotrace:list --status=error --method=POST --since="yesterday" ``` **Example Output:** ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ Trace ID โ”‚ Timestamp โ”‚ Method โ”‚ Status โ”‚ Route โ”‚ Duration โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ abc123... โ”‚ 2024-08-06 14:30:15 โ”‚ POST โ”‚ 500 โ”‚ api/users โ”‚ 245ms โ”‚ โ”‚ def456... โ”‚ 2024-08-06 14:28:42 โ”‚ GET โ”‚ 200 โ”‚ dashboard โ”‚ 89ms โ”‚ โ”‚ ghi789... โ”‚ 2024-08-06 14:25:18 โ”‚ PUT โ”‚ 422 โ”‚ api/users/123 โ”‚ 156ms โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ Found 3 traces matching criteria. ``` ### `chronotrace:replay` Replay a specific trace to see detailed execution flow. ```bash # Basic replay (shows all events) php artisan chronotrace:replay abc123def456 # Filter by event types php artisan chronotrace:replay abc123def456 --filter=database php artisan chronotrace:replay abc123def456 --filter=database,http php artisan chronotrace:replay abc123def456 --filter=cache,jobs # Available filters php artisan chronotrace:replay abc123def456 --filter=database # SQL queries php artisan chronotrace:replay abc123def456 --filter=cache # Cache operations php artisan chronotrace:replay abc123def456 --filter=http # External HTTP calls php artisan chronotrace:replay abc123def456 --filter=jobs # Queue jobs php artisan chronotrace:replay abc123def456 --filter=events # Laravel events # Show only slow events (>100ms) php artisan chronotrace:replay abc123def456 --min-duration=100 # Export to JSON php artisan chronotrace:replay abc123def456 --format=json # Save to file php artisan chronotrace:replay abc123def456 --output=/path/to/trace.log ``` --- ## ๐ŸŽฅ Recording Commands ### `chronotrace:record` Start manual recording session (overrides configuration). ```bash # Record for 30 seconds php artisan chronotrace:record --duration=30s # Record for 5 minutes php artisan chronotrace:record --duration=5m # Record for 1 hour php artisan chronotrace:record --duration=1h # Record until stopped manually php artisan chronotrace:record --continuous # Record specific routes only php artisan chronotrace:record --routes="api/*,admin/*" --duration=10m # Record with custom sample rate php artisan chronotrace:record --sample-rate=0.5 --duration=1h # Record only errors during session php artisan chronotrace:record --errors-only --duration=30m ``` **Example Output:** ``` ๐ŸŽฌ Starting manual recording session... Duration: 30 seconds Routes: All routes Sample Rate: 100% โฑ๏ธ Recording active... (Press Ctrl+C to stop early) ๐Ÿ“Š Recording complete! Duration: 30.2 seconds Traces Captured: 15 Errors: 2 Average Duration: 124ms ``` ### Stop Recording ```bash # Stop any active recording session php artisan chronotrace:record --stop ``` --- ## ๐Ÿงน Maintenance Commands ### `chronotrace:purge` Clean up old traces to manage storage space. ```bash # Remove traces older than default retention (15 days) php artisan chronotrace:purge # Remove traces older than specific number of days php artisan chronotrace:purge --days=7 php artisan chronotrace:purge --days=30 # Remove all traces (be careful!) php artisan chronotrace:purge --all # Remove only error traces php artisan chronotrace:purge --status=error # Remove only successful traces php artisan chronotrace:purge --status=success # Remove traces for specific routes php artisan chronotrace:purge --route="api/test/*" # Dry run (show what would be deleted) php artisan chronotrace:purge --dry-run # Force deletion without confirmation php artisan chronotrace:purge --force # Show detailed information during purge php artisan chronotrace:purge --verbose ``` **Example Output:** ``` ๐Ÿงน Purging traces older than 15 days... Found 145 traces to purge: - 98 successful traces (67%) - 47 error traces (33%) - Total size: 23.4 MB Proceed with deletion? (yes/no) [no]: yes โœ… Purged 145 traces (23.4 MB freed) ``` --- ## ๐Ÿ”ง Diagnostic Commands ### `chronotrace:diagnose` Check system status and configuration. ```bash # Basic diagnostics php artisan chronotrace:diagnose # Include storage statistics php artisan chronotrace:diagnose --storage # Include detailed configuration php artisan chronotrace:diagnose --config # Check specific storage driver php artisan chronotrace:diagnose --storage-driver=s3 # Verbose output with recommendations php artisan chronotrace:diagnose --verbose ``` **Example Output:** ``` โœ… ChronoTrace Diagnostics ๐Ÿ“‹ Configuration Enabled: Yes Mode: record_on_error Sample Rate: 0.1% Storage Driver: local ๐Ÿ’พ Storage Driver: local Path: /app/storage/chronotrace Writable: Yes โœ“ Free Space: 15.2 GB ๐Ÿ“Š Statistics Total Traces: 1,234 Error Traces: 89 (7.2%) Average Size: 145 KB Total Size: 179 MB โšก Performance Queue Workers: 3 active โœ“ Async Storage: Enabled โœ“ Average Write Time: 12ms โš ๏ธ Recommendations - Consider increasing retention to 30 days - Enable Redis for better queue performance - Monitor storage growth rate ``` --- ## ๐Ÿ› ๏ธ Setup & Testing Commands ### `chronotrace:install` Install and configure ChronoTrace. ```bash # Basic installation php artisan chronotrace:install # Force reinstallation (overwrites existing config) php artisan chronotrace:install --force # Install with specific storage driver php artisan chronotrace:install --storage=s3 # Install with custom configuration php artisan chronotrace:install --config=production ``` ### `chronotrace:test-internal` Test ChronoTrace functionality. ```bash # Basic functionality test php artisan chronotrace:test-internal # Test specific components php artisan chronotrace:test-internal --component=storage php artisan chronotrace:test-internal --component=recording php artisan chronotrace:test-internal --component=replay # Generate test traces for demo php artisan chronotrace:test-internal --generate-samples=10 ``` ### `chronotrace:middleware-test` Test middleware functionality and route detection. ```bash # Test middleware on specific route php artisan chronotrace:middleware-test /api/users # Test with specific HTTP method php artisan chronotrace:middleware-test /api/users --method=POST # Test with request data php artisan chronotrace:middleware-test /api/users --method=POST --data='{"name":"John"}' # Test middleware chain php artisan chronotrace:middleware-test /admin/dashboard --show-middleware ``` --- ## ๐ŸŽฏ Advanced Usage Examples ### Debugging Production Issues ```bash # Find error traces from last 24 hours php artisan chronotrace:list --status=error --since="24 hours ago" # Analyze a specific error php artisan chronotrace:replay abc123def456 --filter=database,http # Clean up after analysis php artisan chronotrace:purge --status=error --days=1 ``` ### Performance Analysis ```bash # Find slow requests (>1 second) php artisan chronotrace:list --min-duration=1000 # Analyze bottlenecks php artisan chronotrace:replay slow-trace-id --min-duration=50 # Record performance during load test php artisan chronotrace:record --duration=10m --sample-rate=0.1 ``` ### Development Workflow ```bash # Start debugging session php artisan chronotrace:record --duration=5m # Make test requests to your application curl -X POST localhost:8000/api/test # Review captured traces php artisan chronotrace:list --limit=5 # Analyze specific trace php artisan chronotrace:replay latest-trace-id # Clean up when done php artisan chronotrace:purge --days=0 ``` --- ## ๐Ÿ”— Command Chaining You can chain commands for complex workflows: ```bash # Record, analyze, and clean up php artisan chronotrace:record --duration=1m && \ php artisan chronotrace:list --limit=5 && \ php artisan chronotrace:purge --days=0 # Diagnostic workflow php artisan chronotrace:diagnose && \ php artisan chronotrace:test-internal && \ php artisan chronotrace:list --limit=3 ``` --- ## ๐Ÿ“ Output Formats Most commands support different output formats: ```bash # Table format (default) php artisan chronotrace:list # JSON format php artisan chronotrace:list --format=json # CSV format php artisan chronotrace:list --format=csv # Save to file php artisan chronotrace:list --format=json > traces.json ``` --- ## ๐Ÿšจ Common Issues ### Command Not Found ```bash # Clear command cache php artisan optimize:clear composer dump-autoload ``` ### Permission Denied ```bash # Fix storage permissions sudo chown -R www-data:www-data storage/chronotrace ``` ### Memory Issues with Large Traces ```bash # Increase memory limit temporarily php -d memory_limit=512M artisan chronotrace:replay large-trace-id ``` --- ## ๐Ÿ“š Related Documentation - **[Basic Usage](Basic-Usage.md)** - Learn fundamental workflows - **[Configuration](Configuration.md)** - Configure command behavior - **[Troubleshooting](Troubleshooting.md)** - Solve common issues --- **Need help with a specific command?** Use `php artisan help chronotrace:command-name` for detailed usage information.