# Event Filtering

Learn how to effectively filter, analyze, and understand different types of events captured by ChronoTrace.

## Understanding Event Types

ChronoTrace captures comprehensive event data across multiple categories:

- **📊 Database Events** - SQL queries, transactions, connections, bindings
- **🗄️ Cache Events** - Hits, misses, writes, deletions, store operations  
- **🌐 HTTP Events** - External API calls, responses, failures, timeouts

## 🔍 Database Event Filtering

### Basic Database Filtering

Filter database events to focus on specific aspects of your application's data layer:

```bash
# Show only database events
php artisan chronotrace:replay {trace-id} --filter=database

# Show only slow database queries (>100ms)
php artisan chronotrace:replay {trace-id} --filter=database --min-duration=100

# Show database events with specific patterns
php artisan chronotrace:replay {trace-id} --filter=database --search="users"
```

### Database Query Analysis

```bash
# Example database event output
┌─ DATABASE EVENTS (8 queries, 145ms total) ──────────────────┐
│ [+0ms] SELECT * FROM users WHERE id = ? [123] (5ms)
│        Connection: mysql, Rows: 1
│ 
│ [+15ms] SELECT * FROM posts WHERE user_id = ? [123] (25ms)
│         Connection: mysql, Rows: 50
│ 
│ [+45ms] SELECT * FROM comments WHERE post_id IN (?, ?, ...) (85ms) ⚠️
│         Connection: mysql, Rows: 1,500
│ 
│ [+135ms] UPDATE users SET last_seen = ? WHERE id = ? (5ms)
│          Connection: mysql, Affected: 1
└──────────────────────────────────────────────────────────────┘
```

**What to look for:**
- ⚠️ **Slow queries** (>100ms) - Usually indicate missing indexes
- 🔄 **N+1 patterns** - Multiple similar queries in sequence
- 📊 **Large result sets** - High row counts may need pagination
- 🔗 **Connection issues** - Multiple connections when one should suffice

### Advanced Database Filtering

```bash
# Filter by query type
php artisan chronotrace:replay {trace-id} --filter=database --query-type=select
php artisan chronotrace:replay {trace-id} --filter=database --query-type=insert,update

# Filter by table
php artisan chronotrace:replay {trace-id} --filter=database --table=users,posts

# Filter by connection
php artisan chronotrace:replay {trace-id} --filter=database --connection=mysql,pgsql
```

---

## 💾 Cache Event Filtering

### Basic Cache Filtering

```bash
# Show only cache events
php artisan chronotrace:replay {trace-id} --filter=cache

# Show cache misses only
php artisan chronotrace:replay {trace-id} --filter=cache --cache-result=miss

# Show cache operations on specific keys
php artisan chronotrace:replay {trace-id} --filter=cache --search="user:"
```

### Cache Performance Analysis

```bash
# Example cache event output
┌─ CACHE EVENTS (6 operations) ───────────────────────────────┐
│ [+25ms] GET user:123:profile (HIT) 
│         Store: redis, TTL: 3600s, Size: 2.1KB
│ 
│ [+35ms] GET products:featured (MISS) ⚠️
│         Store: redis, Fallback to database
│ 
│ [+180ms] SET products:featured (TTL: 1800s, Size: 15.6KB)
│          Store: redis, Operation: 12ms
│ 
│ [+195ms] GET shipping:rates:90210 (HIT)
│          Store: redis, TTL: 7200s, Size: 890B
└──────────────────────────────────────────────────────────────┘
```

**What to look for:**
- ⚠️ **Cache misses** followed by expensive operations
- 🔄 **Cache stampeding** - Multiple misses for same key
- ⏰ **TTL optimization** - Keys expiring too quickly/slowly
- 📏 **Large cache values** - May indicate inefficient caching

### Cache Efficiency Analysis

```bash
# Analyze cache hit rates
php artisan chronotrace:replay {trace-id} --filter=cache --stats

# Expected output:
Cache Statistics:
- Total Operations: 15
- Cache Hits: 12 (80%)
- Cache Misses: 3 (20%)
- Average Operation Time: 3ms
- Total Cache Size: 45.7KB
```

---

## 🌐 HTTP Event Filtering

### Basic HTTP Filtering

```bash
# Show only HTTP events
php artisan chronotrace:replay {trace-id} --filter=http

# Show failed HTTP requests only
php artisan chronotrace:replay {trace-id} --filter=http --status=4xx,5xx

# Show slow HTTP requests (>1 second)
php artisan chronotrace:replay {trace-id} --filter=http --min-duration=1000
```

### HTTP Request Analysis

```bash
# Example HTTP event output
┌─ HTTP EVENTS (3 requests) ───────────────────────────────────┐
│ [+78ms] POST https://api.stripe.com/v1/charges (1,234ms)
│         Status: 200 OK
│         Request: 2.1KB, Response: 890B
│         Connection: 45ms, DNS: 12ms
│
│ [+1,350ms] GET https://api.shipping.com/rates (2,156ms) ⚠️
│            Status: 200 OK  
│            Request: 456B, Response: 1.2KB
│            Connection: 1,200ms (slow), DNS: 15ms
│
│ [+3,520ms] POST https://webhook.example.com/notify (567ms)
│            Status: 200 OK
│            Request: 1.8KB, Response: 125B
└──────────────────────────────────────────────────────────────┘
```

**What to look for:**
- ⚠️ **Slow connections** - High connection time indicates network issues
- 🔄 **Failed requests** - 4xx/5xx status codes
- ⏰ **Timeout patterns** - Requests approaching timeout limits
- 📊 **Large payloads** - Oversized requests/responses

### HTTP Error Analysis

```bash
# Focus on failed requests
php artisan chronotrace:replay {trace-id} --filter=http --status=error

# Show timeout issues
php artisan chronotrace:replay {trace-id} --filter=http --min-duration=30000

# Filter by specific hosts
php artisan chronotrace:replay {trace-id} --filter=http --host="api.stripe.com"
```

---

## 🔄 Queue Job Filtering

### Basic Job Filtering

```bash
# Show only job events
php artisan chronotrace:replay {trace-id} --filter=jobs

# Show failed jobs only
php artisan chronotrace:replay {trace-id} --filter=jobs --status=failed

# Show jobs from specific queues
php artisan chronotrace:replay {trace-id} --filter=jobs --queue=emails,payments
```

### Job Performance Analysis

```bash
# Example job event output
┌─ QUEUE EVENTS (4 jobs) ──────────────────────────────────────┐
│ [+195ms] DISPATCH SendWelcomeEmail
│          Queue: emails, Delay: 0s, Tries: 3
│          Payload: {"user_id": 123, "template": "welcome"}
│
│ [+200ms] DISPATCH ProcessPayment
│          Queue: payments, Delay: 5s, Tries: 5
│          Payload: {"order_id": 789, "amount": 99.99}
│
│ [+205ms] DISPATCH UpdateInventory
│          Queue: default, Delay: 0s, Tries: 1
│          Payload: {"product_id": 456, "quantity": -2}
└──────────────────────────────────────────────────────────────┘
```

---

## 🎯 Combined Filtering

### Multi-Event Analysis

```bash
# Combine multiple event types
php artisan chronotrace:replay {trace-id} --filter=database,http
php artisan chronotrace:replay {trace-id} --filter=cache,jobs

# Show all events but filter by duration
php artisan chronotrace:replay {trace-id} --min-duration=50

# Complex filtering
php artisan chronotrace:replay {trace-id} --filter=database,http --min-duration=100 --search="payment"
```

### Performance Correlation

```bash
# Identify performance bottlenecks across event types
php artisan chronotrace:replay {trace-id} --performance-analysis

# Expected output:
Performance Breakdown:
- Database: 145ms (32% of total)
- HTTP: 289ms (64% of total) ⚠️ Bottleneck
- Cache: 8ms (2% of total)
- Jobs: 12ms (3% of total)

Recommendations:
- Optimize HTTP calls to external APIs
- Consider caching API responses
- Implement timeout strategies
```

---

## 📊 Advanced Filtering Techniques

### Pattern Recognition

```bash
# Find N+1 query patterns
php artisan chronotrace:replay {trace-id} --detect-n-plus-one

# Identify cache stampeding
php artisan chronotrace:replay {trace-id} --detect-cache-stampede

# Find slow operation chains
php artisan chronotrace:replay {trace-id} --detect-slow-chains
```

### Custom Filtering

```bash
# Use grep-like patterns
php artisan chronotrace:replay {trace-id} --filter=database --grep="SELECT.*users"
php artisan chronotrace:replay {trace-id} --filter=http --grep="stripe\.com"

# Exclude specific patterns
php artisan chronotrace:replay {trace-id} --filter=database --exclude="session"
```

### Timeline Filtering

```bash
# Show events in specific time ranges
php artisan chronotrace:replay {trace-id} --time-range=0-100ms
php artisan chronotrace:replay {trace-id} --time-range=100ms-500ms

# Show events before/after specific timestamp
php artisan chronotrace:replay {trace-id} --before=100ms
php artisan chronotrace:replay {trace-id} --after=200ms
```

---

## 🔧 Filtering Best Practices

### 1. Start Broad, Then Narrow

```bash
# 1. First, see the complete picture
php artisan chronotrace:replay {trace-id}

# 2. Identify the problem area
php artisan chronotrace:replay {trace-id} --min-duration=100

# 3. Focus on specific event types
php artisan chronotrace:replay {trace-id} --filter=database --min-duration=50
```

### 2. Use Performance-Based Filtering

```bash
# Focus on slow operations first
php artisan chronotrace:replay {trace-id} --min-duration=100

# Then drill down by event type
php artisan chronotrace:replay {trace-id} --filter=http --min-duration=1000
```

### 3. Combine Filters Strategically

```bash
# Database performance issues
php artisan chronotrace:replay {trace-id} --filter=database --min-duration=50 --search="SELECT"

# API integration problems
php artisan chronotrace:replay {trace-id} --filter=http --status=error,timeout

# Cache efficiency analysis
php artisan chronotrace:replay {trace-id} --filter=cache --cache-result=miss
```

### 4. Save Useful Filter Combinations

```bash
# Create aliases for common patterns
alias ct-db-slow="php artisan chronotrace:replay \$1 --filter=database --min-duration=100"
alias ct-api-errors="php artisan chronotrace:replay \$1 --filter=http --status=error"
alias ct-cache-analysis="php artisan chronotrace:replay \$1 --filter=cache --stats"

# Usage
ct-db-slow abc123def456
ct-api-errors abc123def456
```

---

## 📈 Filtering for Different Scenarios

### Debugging Performance Issues

```bash
# 1. Find the bottleneck
php artisan chronotrace:replay {trace-id} --performance-analysis

# 2. Focus on the slow area
php artisan chronotrace:replay {trace-id} --filter=http --min-duration=1000

# 3. Analyze patterns
php artisan chronotrace:replay {trace-id} --filter=http --detect-timeout-patterns
```

### Debugging Database Issues

```bash
# 1. Check for N+1 queries
php artisan chronotrace:replay {trace-id} --filter=database --detect-n-plus-one

# 2. Find slow queries
php artisan chronotrace:replay {trace-id} --filter=database --min-duration=100

# 3. Analyze query patterns
php artisan chronotrace:replay {trace-id} --filter=database --search="SELECT.*WHERE.*IN"
```

### Debugging Cache Issues

```bash
# 1. Check cache efficiency
php artisan chronotrace:replay {trace-id} --filter=cache --stats

# 2. Find cache misses
php artisan chronotrace:replay {trace-id} --filter=cache --cache-result=miss

# 3. Look for stampeding
php artisan chronotrace:replay {trace-id} --detect-cache-stampede
```

---

## 📚 Related Documentation

- **[Understanding Traces](Understanding-Traces.md)** - Learn trace structure and content
- **[Event Capturing](Event-Capturing.md)** - Configure what events to capture
- **[Commands](Commands.md)** - Complete command reference
- **[Performance Analysis](Example-Performance-Analysis.md)** - Advanced analysis techniques

---

**Master event filtering to quickly identify and solve issues!** Use these filtering techniques to focus on specific problems and reduce noise in your trace analysis.