Commands

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.

# 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.

# 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).

# 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

# Stop any active recording session
php artisan chronotrace:record --stop

---

🧹 Maintenance Commands

chronotrace:purge

Clean up old traces to manage storage space.

# 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.

# 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.

# 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.

# 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.

# 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

# 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

# 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

# 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:

# 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:

# 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

# Clear command cache
php artisan optimize:clear
composer dump-autoload

Permission Denied

# Fix storage permissions
sudo chown -R www-data:www-data storage/chronotrace

Memory Issues with Large Traces

# Increase memory limit temporarily
php -d memory_limit=512M artisan chronotrace:replay large-trace-id

---

📚 Related Documentation

• Basic Usage - Learn fundamental workflows
• Configuration - Configure command behavior
• Troubleshooting - Solve common issues

---

Need help with a specific command? Use php artisan help chronotrace:command-name for detailed usage information.