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
⚙️ Job Events - Queue job processing, failures, completions, dispatching
📝 Laravel Events - Custom events, model events, lifecycle events (optional)
📧 Mail Events - Email sending, queuing, failures
🔔 Notification Events - Push notifications, SMS, webhooks

Basic Event Filtering

View All Events

# See comprehensive trace information
php artisan chronotrace:replay abc12345-def6-7890-abcd-ef1234567890

# Detailed view with context, headers, and content
php artisan chronotrace:replay abc12345 --detailed

# Maximum information including Laravel context
php artisan chronotrace:replay abc12345 --detailed --context --headers --content --bindings

Filter by Single Event Type

# Database events only
php artisan chronotrace:replay abc12345 --db

# Cache operations only  
php artisan chronotrace:replay abc12345 --cache

# External HTTP requests only
php artisan chronotrace:replay abc12345 --http

# Queue job events only
php artisan chronotrace:replay abc12345 --jobs

Combine Multiple Filters

# Database and cache events
php artisan chronotrace:replay abc12345 --db --cache

# HTTP and job events
php artisan chronotrace:replay abc12345 --http --jobs

# Database with SQL bindings
php artisan chronotrace:replay abc12345 --db --bindings

# Everything except jobs
php artisan chronotrace:replay abc12345 --db --cache --http

Advanced Database Analysis

Finding Performance Issues

# Show all database queries with execution times
php artisan chronotrace:replay abc12345 --db

# Show SQL bindings for debugging parameters
php artisan chronotrace:replay abc12345 --db --bindings

# Find slow queries (>100ms)
php artisan chronotrace:replay abc12345 --db | grep -E "[0-9]{3,}ms"

# Identify potential N+1 queries
php artisan chronotrace:replay abc12345 --db | grep -E "SELECT.*WHERE.*IN"

Example Output:

📊 DATABASE EVENTS
  🔍 [14:30:22.123] Query: SELECT * FROM users WHERE active = ? (15ms on mysql)
      Bindings: [1]
  🔍 [14:30:22.145] Query: SELECT * FROM roles WHERE user_id IN (?, ?, ?) (8ms on mysql)
      Bindings: [1, 2, 3]
  ⚠️  [14:30:22.200] Query: SELECT * FROM posts WHERE user_id = ? (250ms on mysql)
      Bindings: [1]

Transaction Analysis

# Show transaction events
php artisan chronotrace:replay abc12345 --db | grep -E "(Transaction|COMMIT|ROLLBACK)"

# Find failed transactions
php artisan chronotrace:replay abc12345 --db | grep "ROLLBACK"

Cache Event Analysis

Understanding Cache Patterns

# View all cache operations
php artisan chronotrace:replay abc12345 --cache

# Focus on cache misses (optimization opportunities)
php artisan chronotrace:replay abc12345 --cache | grep "MISS"

# Check cache hit ratio
php artisan chronotrace:replay abc12345 --cache | grep -E "(HIT|MISS)" | sort | uniq -c

Example Output:

🗄️ CACHE EVENTS
  ❌ [14:30:22.120] Cache MISS: users:list (store: redis)
  💾 [14:30:22.150] Cache WRITE: users:list (store: redis, ttl: 3600)
  ✅ [14:30:22.200] Cache HIT: config:app (store: redis)
  🗑️ [14:30:22.250] Cache DELETE: users:1:profile (store: redis)

HTTP Event Analysis

External Service Monitoring

# View all external HTTP requests
php artisan chronotrace:replay abc12345 --http

# Check for failed requests
php artisan chronotrace:replay abc12345 --http | grep -E "(Failed|[45][0-9][0-9])"

# Monitor response times
php artisan chronotrace:replay abc12345 --http | grep -E "[0-9]{2,}ms"

Example Output:

🌐 HTTP EVENTS
  📤 [14:30:22.200] HTTP Request: GET https://api.external.com/users/123
      Headers: {"Authorization": "Bearer ***", "Accept": "application/json"}
  📥 [14:30:22.450] HTTP Response: GET https://api.external.com/users/123 → 200 (1,234 bytes, 250ms)
  📤 [14:30:22.500] HTTP Request: POST https://webhook.service.com/notify
  ❌ [14:30:22.800] HTTP Response: POST https://webhook.service.com/notify → 500 (Connection timeout)

Queue Job Analysis

Job Performance and Reliability

# View all job events
php artisan chronotrace:replay abc12345 --jobs

# Check for failed jobs
php artisan chronotrace:replay abc12345 --jobs | grep "Failed"

# Monitor job processing times
php artisan chronotrace:replay abc12345 --jobs | grep -E "[0-9]{3,}ms"

Example Output:

⚙️ JOB EVENTS
  🔄 [14:30:22.300] Job STARTED: ProcessUserRegistration (queue: default)
  ✅ [14:30:22.450] Job COMPLETED: ProcessUserRegistration (150ms)
  🔄 [14:30:22.500] Job STARTED: SendWelcomeEmail (queue: emails)
  ❌ [14:30:22.600] Job FAILED: SendWelcomeEmail (Connection refused)
  🔄 [14:30:22.700] Job RETRY: SendWelcomeEmail (attempt 2/3)

Output Format Options

JSON Output for Programmatic Analysis

# Export trace as JSON
php artisan chronotrace:replay abc12345 --format=json > trace.json

# Process with jq
php artisan chronotrace:replay abc12345 --format=json | jq '.database[] | select(.duration > 100)'

# Extract database queries only
php artisan chronotrace:replay abc12345 --format=json | jq '.database[].sql'

# Get HTTP response codes
php artisan chronotrace:replay abc12345 --format=json | jq '.http[].status'

Raw Output for Custom Processing

# Raw format for custom parsers
php artisan chronotrace:replay abc12345 --format=raw

# Pipe to custom analysis scripts
php artisan chronotrace:replay abc12345 --format=raw | ./custom-analyzer.py

Advanced Filtering Scenarios

E-commerce Checkout Analysis

# Record checkout process
php artisan chronotrace:record /checkout/process \
  --method=POST \
  --data='{"cart_id": "123", "payment_method": "stripe"}'

# Analyze payment processing
TRACE_ID=$(php artisan chronotrace:list --limit=1 --full-id | grep "│" | head -1 | awk '{print $2}')

echo "🛒 E-commerce Checkout Analysis"
echo "================================"

# Check database performance (order creation, inventory updates)
echo "📊 Database Operations:"
php artisan chronotrace:replay $TRACE_ID --db --bindings | grep -E "(orders|inventory|payments)"

# Monitor payment gateway calls
echo ""
echo "💳 Payment Gateway Integration:"
php artisan chronotrace:replay $TRACE_ID --http | grep -E "(stripe|paypal|payment)"

# Check background job processing (email, inventory updates)
echo ""
echo "⚙️ Background Processing:"
php artisan chronotrace:replay $TRACE_ID --jobs

Multi-Step Workflow Analysis

# Step 1: Registration form
php artisan chronotrace:record /register --method=GET
REG_FORM_TRACE=$(php artisan chronotrace:list --limit=1 --full-id | grep "│" | head -1 | awk '{print $2}')

# Step 2: Registration submission
php artisan chronotrace:record /register \
  --method=POST \
  --data='{"name":"Test User","email":"test@example.com","password":"password123"}'
REG_SUBMIT_TRACE=$(php artisan chronotrace:list --limit=1 --full-id | grep "│" | head -1 | awk '{print $2}')

# Step 3: Email verification
php artisan chronotrace:record /email/verify/123 --method=GET
VERIFY_TRACE=$(php artisan chronotrace:list --limit=1 --full-id | grep "│" | head -1 | awk '{print $2}')

echo "📊 Workflow Performance Summary:"
echo "================================"

for step in "Registration Form:$REG_FORM_TRACE" "Registration Submit:$REG_SUBMIT_TRACE" "Email Verify:$VERIFY_TRACE"; do
    STEP_NAME=$(echo $step | cut -d: -f1)
    TRACE_ID=$(echo $step | cut -d: -f2)
    
    echo "🔍 $STEP_NAME"
    echo "  Trace: $TRACE_ID"
    
    # Performance metrics
    php artisan chronotrace:replay $TRACE_ID | grep -E "(Duration|Memory|Response Status)"
    
    # Database operations
    DB_COUNT=$(php artisan chronotrace:replay $TRACE_ID --db | grep -c "Query:")
    echo "  📊 Database Queries: $DB_COUNT"
    
    # Background jobs
    JOB_COUNT=$(php artisan chronotrace:replay $TRACE_ID --jobs | grep -c "STARTED")
    echo "  ⚙️ Background Jobs: $JOB_COUNT"
    
    echo ""
done

Analysis Scripts

Database Performance Script

#!/bin/bash
# analyze-database-performance.sh

TRACE_ID=$1
if [ -z "$TRACE_ID" ]; then
    echo "Usage: $0 <trace-id>"
    exit 1
fi

echo "🔍 Database Performance Analysis for: $TRACE_ID"
echo "=" | head -c 50; echo

# Count queries
TOTAL_QUERIES=$(php artisan chronotrace:replay $TRACE_ID --db | grep -c "Query:")
echo "📊 Total Queries: $TOTAL_QUERIES"

# Find slow queries
SLOW_QUERIES=$(php artisan chronotrace:replay $TRACE_ID --db | grep -c "[0-9]{3,}ms")
echo "🐌 Slow Queries (>100ms): $SLOW_QUERIES"

if [ $SLOW_QUERIES -gt 0 ]; then
    echo ""
    echo "🔍 Slowest Queries:"
    php artisan chronotrace:replay $TRACE_ID --db --bindings | grep -E "[0-9]{3,}ms" | head -3
fi

# Check for N+1 patterns
N_PLUS_ONE=$(php artisan chronotrace:replay $TRACE_ID --db | grep -c "WHERE.*IN")
if [ $N_PLUS_ONE -gt 2 ]; then
    echo ""
    echo "⚠️  Potential N+1 Queries Detected: $N_PLUS_ONE"
    php artisan chronotrace:replay $TRACE_ID --db | grep "WHERE.*IN" | head -2
fi

Cache Efficiency Script

#!/bin/bash
# analyze-cache-efficiency.sh

TRACE_ID=$1
echo "🗄️ Cache Analysis for: $TRACE_ID"

# Count cache operations
HITS=$(php artisan chronotrace:replay $TRACE_ID --cache | grep -c "HIT")
MISSES=$(php artisan chronotrace:replay $TRACE_ID --cache | grep -c "MISS")
WRITES=$(php artisan chronotrace:replay $TRACE_ID --cache | grep -c "WRITE")
DELETES=$(php artisan chronotrace:replay $TRACE_ID --cache | grep -c "DELETE")

echo "📊 Cache Statistics:"
echo "  ✅ Hits: $HITS"
echo "  ❌ Misses: $MISSES"
echo "  💾 Writes: $WRITES"
echo "  🗑️ Deletes: $DELETES"

if [ $MISSES -gt 0 ] && [ $HITS -gt 0 ]; then
    HIT_RATIO=$(echo "scale=2; $HITS * 100 / ($HITS + $MISSES)" | bc)
    echo "  📈 Hit Ratio: ${HIT_RATIO}%"
    
    if [ $(echo "$HIT_RATIO < 80" | bc) -eq 1 ]; then
        echo "⚠️  Low cache hit ratio - consider cache optimization"
    fi
fi

Best Practices for Event Analysis

1. Start with Overview, Then Focus

# 1. Get the big picture first
php artisan chronotrace:replay abc12345

# 2. Focus on specific areas based on findings
php artisan chronotrace:replay abc12345 --db  # If you see performance issues
php artisan chronotrace:replay abc12345 --http  # If external services are involved

2. Use Filtering for Specific Problems

# Database performance issues
php artisan chronotrace:replay abc12345 --db --bindings | grep -E "[0-9]{3,}ms"

# Cache optimization opportunities  
php artisan chronotrace:replay abc12345 --cache | grep "MISS"

# External service reliability
php artisan chronotrace:replay abc12345 --http | grep -E "[45][0-9][0-9]"

3. Combine with System Monitoring

# Export for external analysis
php artisan chronotrace:replay abc12345 --format=json | \
  jq '{duration: .info.duration, db_queries: (.database | length), http_calls: (.http | length)}'

4. Create Reusable Analysis Scripts

# comprehensive-analysis.sh
#!/bin/bash
TRACE_ID=$1

echo "🔍 Comprehensive Trace Analysis: $TRACE_ID"
echo "=========================================="

# Performance overview
echo "📊 Performance Metrics:"
php artisan chronotrace:replay $TRACE_ID | grep -E "(Duration|Memory|Response Status)"

# Database analysis
echo ""
echo "💾 Database Analysis:"
DB_COUNT=$(php artisan chronotrace:replay $TRACE_ID --db | grep -c "Query:")
SLOW_COUNT=$(php artisan chronotrace:replay $TRACE_ID --db | grep -c "[0-9]{3,}ms")
echo "  Total queries: $DB_COUNT"
echo "  Slow queries: $SLOW_COUNT"

# Cache analysis
echo ""
echo "🗄️ Cache Analysis:"
CACHE_HITS=$(php artisan chronotrace:replay $TRACE_ID --cache | grep -c "HIT")
CACHE_MISSES=$(php artisan chronotrace:replay $TRACE_ID --cache | grep -c "MISS")
echo "  Cache hits: $CACHE_HITS"
echo "  Cache misses: $CACHE_MISSES"

# HTTP analysis
echo ""
echo "🌐 HTTP Analysis:"
HTTP_COUNT=$(php artisan chronotrace:replay $TRACE_ID --http | grep -c "HTTP Request:")
HTTP_FAILURES=$(php artisan chronotrace:replay $TRACE_ID --http | grep -c -E "[45][0-9][0-9]")
echo "  HTTP requests: $HTTP_COUNT"
echo "  HTTP failures: $HTTP_FAILURES"

Next Steps

Laravel ChronoTrace - Record and replay Laravel requests deterministically

• •

🔗 Quick Links

Getting Started - Install and configure ChronoTrace
Examples - Real-world debugging scenarios
Production Guide - Deploy safely in production
Troubleshooting - Solve common issues

📖 Popular Pages

Section	Page	Description
🚀 Basics	Your First Trace	Step-by-step beginner guide
🎛️ Config	Recording Modes	Choose when to record traces
🛡️ Security	Security & PII	Protect sensitive data
🔧 Tools	Commands	Complete command reference

🆘 Need Help?

💬 GitHub Discussions - Community support
🐛 Report Issues - Bug reports & feature requests
📧 Contact - Direct support
💡 Feature Requests - Suggest improvements

ChronoTrace helps Laravel developers debug applications faster with intelligent request tracing.

Uh oh!

Event Filtering

Event Filtering

Understanding Event Types

Basic Event Filtering

View All Events

Filter by Single Event Type

Combine Multiple Filters

Advanced Database Analysis

Finding Performance Issues

Transaction Analysis

Cache Event Analysis

Understanding Cache Patterns

HTTP Event Analysis

External Service Monitoring

Queue Job Analysis

Job Performance and Reliability

Output Format Options

JSON Output for Programmatic Analysis

Raw Output for Custom Processing

Advanced Filtering Scenarios

E-commerce Checkout Analysis

Multi-Step Workflow Analysis

Analysis Scripts

Database Performance Script

Cache Efficiency Script

Best Practices for Event Analysis

1. Start with Overview, Then Focus

2. Use Filtering for Specific Problems

3. Combine with System Monitoring

4. Create Reusable Analysis Scripts

Next Steps

🔗 Quick Links

📖 Popular Pages

🆘 Need Help?

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

📚 Laravel ChronoTrace Wiki

🏠 Home

🚀 Getting Started

🎯 Core Concepts

⚙️ Configuration

🔧 Commands & Tools

🏭 Advanced Usage

📖 Examples & Guides

🔍 Reference

🤝 Community

Clone this wiki locally