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

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

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

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

```bash
# In .env
CHRONOTRACE_MODE=always
CHRONOTRACE_ENABLED=true
```

### Production Mode
Record only errors and sample successful requests:

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

### Targeted Recording
Record specific routes or conditions:

```bash
# 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
```bash
php artisan chronotrace:replay {trace-id} --filter=database
```
Shows:
- SQL queries with bindings
- Execution times
- Connection information

### Cache Events
```bash
php artisan chronotrace:replay {trace-id} --filter=cache
```
Shows:
- Cache hits/misses
- Keys accessed
- TTL information

### HTTP Events
```bash
php artisan chronotrace:replay {trace-id} --filter=http
```
Shows:
- External API calls
- Request/response headers
- Response times

### Queue Events
```bash
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:**
   ```bash
   php artisan chronotrace:list --status=error
   ```

2. **Replay the trace:**
   ```bash
   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:**
   ```bash
   php artisan chronotrace:list --min-duration=1000  # > 1 second
   ```

2. **Analyze the bottleneck:**
   ```bash
   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:**
   ```bash
   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:

```bash
# 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

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

---

## 🔧 Quick Configuration

### Enable/Disable Recording

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

# Re-enable
CHRONOTRACE_ENABLED=true
```

### Adjust Event Capture

```bash
# 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](Configuration.md)** - Detailed configuration options
- **[Recording Modes](Recording-Modes.md)** - Advanced recording strategies  
- **[Event Capturing](Event-Capturing.md)** - Configure what events to capture
- **[Commands](Commands.md)** - Complete command reference
- **[Troubleshooting](Troubleshooting.md)** - Common issues and solutions

---

**Need help?** Check the [Troubleshooting Guide](Troubleshooting.md) or [open an issue](https://github.com/Grazulex/laravel-chronotrace/issues) on GitHub.