Basic Usage

Basic Usage

Laravel ChronoTrace helps you understand what happens during request execution by capturing and replaying traces. This guide covers the fundamental concepts and common workflows.

---

🎯 Core Workflow

1. Recording Traces

ChronoTrace automatically records traces based on your configuration. By default, it records traces when errors occur:

# Check current recording status
php artisan chronotrace:diagnose

# Start manual recording for specific requests
php artisan chronotrace:record --duration=30s

2. Viewing Traces

List all captured traces to see what's been recorded:

# List recent traces
php artisan chronotrace:list

# List with filtering
php artisan chronotrace:list --status=error --limit=10
php artisan chronotrace:list --method=POST --route="api/*"

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    │
└────────────┴─────────────────────┴────────┴──────────┴─────────────────────────┴──────────┘

3. Analyzing Traces

Replay a specific trace to see detailed execution flow:

# Replay complete trace
php artisan chronotrace:replay abc123def456

# Filter by event types
php artisan chronotrace:replay abc123def456 --filter=database,http
php artisan chronotrace:replay abc123def456 --filter=cache

---

📊 Understanding Trace Output

Request Information

Every trace starts with basic request information:

┌─ REQUEST INFORMATION ────────────────────────────────────────┐
│ Trace ID: abc123def456789                                    │
│ Method: POST /api/users                                      │
│ Status: 500 Internal Server Error                           │
│ Duration: 245ms                                              │
│ Memory: 12.5MB                                               │
│ Timestamp: 2024-08-06 14:30:15                             │
└──────────────────────────────────────────────────────────────┘

Event Timeline

Events are displayed chronologically with timing information:

┌─ DATABASE EVENTS ────────────────────────────────────────────┐
│ [+0ms] SELECT * FROM users WHERE email = ? [john@example.com] (2ms)
│ [+15ms] INSERT INTO user_activities (user_id, action) VALUES (?, ?) [123, 'login'] (1ms)
│ [+45ms] UPDATE users SET last_login = ? WHERE id = ? ['2024-08-06 14:30:15', 123] (3ms)
└──────────────────────────────────────────────────────────────┘

┌─ HTTP EVENTS ────────────────────────────────────────────────┐
│ [+120ms] POST https://api.external.com/webhook (89ms)
│          Status: 200 OK
│          Payload: {"user_id": 123, "action": "registered"}
└──────────────────────────────────────────────────────────────┘

┌─ CACHE EVENTS ───────────────────────────────────────────────┐
│ [+25ms] GET user:123:profile (HIT)
│ [+180ms] SET user:123:last_activity (3600s TTL)
└──────────────────────────────────────────────────────────────┘

---

🎛️ Recording Modes

ChronoTrace offers flexible recording modes to suit different environments:

Development Mode

Record all requests for comprehensive debugging:

# In .env
CHRONOTRACE_MODE=always
CHRONOTRACE_ENABLED=true

Production Mode

Record only errors and sample successful requests:

# In .env
CHRONOTRACE_MODE=record_on_error
CHRONOTRACE_SAMPLE_RATE=0.001  # 0.1% of successful requests

Targeted Recording

Record specific routes or conditions:

# In .env
CHRONOTRACE_MODE=targeted

# In configuration
'targeted_routes' => [
    'api/orders/*',
    'checkout/*',
    'admin/reports/*'
],

---

🔍 Event Filtering

Focus on specific types of events during analysis:

Database Events

php artisan chronotrace:replay {trace-id} --filter=database

Shows:

• SQL queries with bindings
• Execution times
• Connection information

Cache Events

php artisan chronotrace:replay {trace-id} --filter=cache

Shows:

• Cache hits/misses
• Keys accessed
• TTL information

HTTP Events

php artisan chronotrace:replay {trace-id} --filter=http

Shows:

• External API calls
• Request/response headers
• Response times

Queue Events

php artisan chronotrace:replay {trace-id} --filter=jobs

Shows:

• Dispatched jobs
• Job payloads
• Queue connections

---

🛠️ Common Debugging Scenarios

Debugging 500 Errors

1. Find the error trace:

   php artisan chronotrace:list --status=error

2. Replay the trace:

   php artisan chronotrace:replay {trace-id}

3. Focus on the issue:

   • Look for the last successful database query
   • Check HTTP calls that might have failed
   • Examine job dispatches that could have thrown exceptions

Performance Analysis

1. Find slow requests:

   php artisan chronotrace:list --min-duration=1000  # > 1 second

2. Analyze the bottleneck:

   php artisan chronotrace:replay {trace-id}

3. Identify issues:

   • Long-running database queries
   • Excessive cache misses
   • Slow external API calls

API Integration Issues

1. Filter HTTP events:

   php artisan chronotrace:replay {trace-id} --filter=http

2. Check for:

   • Failed API calls
   • Timeout issues
   • Incorrect request/response formats

---

🧹 Maintenance

Clean Up Old Traces

ChronoTrace automatically purges old traces, but you can manually clean up:

# Remove traces older than 7 days
php artisan chronotrace:purge --days=7

# Remove all traces
php artisan chronotrace:purge --all

# Remove only error traces
php artisan chronotrace:purge --status=error

Check Storage Usage

# See storage statistics
php artisan chronotrace:diagnose --storage

---

🔧 Quick Configuration

Enable/Disable Recording

# Temporarily disable
php artisan down --secret="maintenance-key"
CHRONOTRACE_ENABLED=false

# Re-enable
CHRONOTRACE_ENABLED=true

Adjust Event Capture

# In .env - disable noisy events
CHRONOTRACE_CAPTURE_CACHE=false
CHRONOTRACE_CAPTURE_EVENTS=false

# Keep essential debugging events
CHRONOTRACE_CAPTURE_DATABASE=true
CHRONOTRACE_CAPTURE_HTTP=true
CHRONOTRACE_CAPTURE_JOBS=true

---

🎯 Best Practices

For Development

1. Record everything: Use always mode to understand your application flow
2. Focus your analysis: Use event filtering to reduce noise
3. Regular cleanup: Don't let traces accumulate indefinitely

For Staging

1. Sample + errors: Use record_on_error with low sample rate
2. Test edge cases: Manually record during integration testing
3. Monitor performance: Watch for slow traces

For Production

1. Error-only mode: Minimize performance impact
2. Scrub PII: Ensure sensitive data is masked
3. Automate cleanup: Set appropriate retention policies

---

📝 Next Steps

• Configuration - Detailed configuration options
• Recording Modes - Advanced recording strategies
• Event Capturing - Configure what events to capture
• Commands - Complete command reference
• Troubleshooting - Common issues and solutions

---

Need help? Check the Troubleshooting Guide or open an issue on GitHub.