Your First Trace

Your First Trace

A step-by-step walkthrough to capture, analyze, and understand your first ChronoTrace. Perfect for getting familiar with the basic workflow.

---

🎯 What You'll Learn

• How to capture your first trace
• How to analyze trace output
• How to identify issues in traces
• Basic filtering and analysis techniques

Prerequisites: ChronoTrace should be installed and configured.

---

📋 Step 1: Verify Installation

First, let's make sure ChronoTrace is working correctly:

# Check if ChronoTrace is properly installed
php artisan chronotrace:diagnose

Expected output:

✅ ChronoTrace Configuration
   Enabled: Yes
   Mode: record_on_error
   Storage: local (/path/to/storage/chronotrace)

✅ Storage
   Writable: Yes
   Free Space: 15.2 GB

If you see any ❌ errors, check the Troubleshooting Guide.

---

🎬 Step 2: Enable Recording

For this tutorial, we'll use "always" mode to capture everything:

# Temporarily enable full recording (in .env)
CHRONOTRACE_MODE=always
CHRONOTRACE_ENABLED=true

# Clear config cache to apply changes
php artisan config:clear

---

🚀 Step 3: Generate a Test Request

Let's create a simple test request that we can trace. You have several options:

Option A: Use Built-in Test Command

# Generate a test trace with sample events
php artisan chronotrace:test-internal

Option B: Make a Real Request

# Make a request to your application
curl -X GET http://localhost:8000/

# Or make a POST request with data
curl -X POST http://localhost:8000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com"}'

Option C: Use Your Browser

Simply visit your application in a browser and navigate to any page.

---

📋 Step 4: List Your Traces

Now let's see what traces were captured:

# List recent traces
php artisan chronotrace:list

You should see output like this:

┌────────────┬─────────────────────┬────────┬──────────┬─────────────────────────┬──────────┐
│ Trace ID   │ Timestamp           │ Method │ Status   │ Route                   │ Duration │
├────────────┼─────────────────────┼────────┼──────────┼─────────────────────────┼──────────┤
│ abc123...  │ 2024-08-06 14:30:15 │ GET    │ 200      │ /                       │ 89ms     │
│ def456...  │ 2024-08-06 14:28:42 │ POST   │ 201      │ api/users               │ 156ms    │
└────────────┴─────────────────────┴────────┴──────────┴─────────────────────────┴──────────┘

Found 2 traces.

Understanding the output:

• Trace ID: Unique identifier for this trace
• Timestamp: When the request was made
• Method: HTTP method (GET, POST, PUT, DELETE)
• Status: HTTP response code
• Route: The route that was accessed
• Duration: How long the request took

---

🔍 Step 5: Replay Your First Trace

Now let's examine a trace in detail. Copy a Trace ID from the list and replay it:

# Replace 'abc123...' with your actual Trace ID
php artisan chronotrace:replay abc123def456789

📊 Understanding Trace Output

Request Information

The trace starts with basic request information:

┌─ REQUEST INFORMATION ────────────────────────────────────────┐
│ Trace ID: abc123def456789                                    │
│ Method: GET /                                                │
│ Status: 200 OK                                               │
│ Duration: 89ms                                               │
│ Memory: 8.2MB                                                │
│ Timestamp: 2024-08-06 14:30:15 UTC                         │
│ User Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)      │
│ IP Address: 127.0.0.1                                       │
└──────────────────────────────────────────────────────────────┘

Key information:

• Duration: Total request processing time
• Memory: Peak memory usage during request
• Status: HTTP response code (200 = success)

Event Timeline

Next, you'll see events organized by type and time:

Database Events

┌─ DATABASE EVENTS (3 queries, 12ms total) ───────────────────┐
│ [+0ms] SELECT * FROM users WHERE email = ? ['john@example.com'] (4ms)
│        Connection: mysql, Rows: 1
│ 
│ [+15ms] SELECT * FROM user_profiles WHERE user_id = ? [123] (3ms)
│         Connection: mysql, Rows: 1
│ 
│ [+45ms] UPDATE users SET last_login = ? WHERE id = ? ['2024-08-06 14:30:15', 123] (5ms)
│         Connection: mysql, Affected: 1
└──────────────────────────────────────────────────────────────┘

Understanding database events:

• [+0ms]: Time offset from request start
• SQL Query: The actual query executed
• Bindings: Parameter values (in brackets)
• Duration: Time this query took
• Metadata: Connection, rows returned/affected

Cache Events

┌─ CACHE EVENTS (2 operations) ───────────────────────────────┐
│ [+25ms] GET user:123:profile (HIT) 
│         Store: redis, TTL: 3600s
│ 
│ [+67ms] SET user:123:last_activity (TTL: 3600s)
│         Store: redis, Size: 45 bytes
└──────────────────────────────────────────────────────────────┘

Understanding cache events:

• GET/SET/FORGET: Cache operation type
• HIT/MISS: Whether cache lookup succeeded
• TTL: Time-to-live in seconds
• Size: Data size for SET operations

HTTP Events

┌─ HTTP EVENTS (1 request) ────────────────────────────────────┐
│ [+78ms] POST https://api.example.com/webhook (45ms)
│         Status: 200 OK
│         Request Size: 234 bytes
│         Response Size: 89 bytes
│         Headers: Content-Type: application/json
└──────────────────────────────────────────────────────────────┘

Understanding HTTP events:

• URL: External API called
• Duration: Time the external request took
• Status: Response code from external API
• Sizes: Request and response payload sizes

---

🎯 Step 6: Practice with Filtering

Let's focus on specific types of events:

View Only Database Events

php artisan chronotrace:replay abc123def456789 --filter=database

This shows only SQL queries, making it easier to identify database performance issues.

View Only HTTP Events

php artisan chronotrace:replay abc123def456789 --filter=http

Perfect for debugging external API integration issues.

View Multiple Event Types

php artisan chronotrace:replay abc123def456789 --filter=database,http

Combines database and HTTP events while hiding cache operations.

View Only Slow Events

php artisan chronotrace:replay abc123def456789 --min-duration=10

Shows only events that took longer than 10ms.

---

🐛 Step 7: Create an Error Trace

Let's intentionally create an error to see how ChronoTrace captures failures:

Option A: Make an Invalid Request

# Request a non-existent endpoint
curl -X GET http://localhost:8000/non-existent-page

Option B: Create a Controller with an Error

Create a test route that throws an exception:

// In routes/web.php
Route::get('/test-error', function () {
    throw new \Exception('This is a test error for ChronoTrace');
});

Then visit: http://localhost:8000/test-error

View the Error Trace

# List traces, look for 500 status
php artisan chronotrace:list --status=error

# Replay the error trace
php artisan chronotrace:replay error-trace-id

Error traces show:

• Complete execution flow up to the error
• The exact point where the error occurred
• Stack trace and error message
• All database queries before the failure
• External API calls that might have caused issues

---

📈 Step 8: Performance Analysis

Let's create a slow request to practice performance analysis:

Create a Slow Endpoint

// In routes/web.php
Route::get('/test-slow', function () {
    // Simulate slow database query
    sleep(1);
    
    // Simulate external API call
    $response = Http::timeout(30)->get('https://httpbin.org/delay/2');
    
    return response()->json(['status' => 'completed']);
});

Generate and Analyze the Trace

# Make the slow request
curl -X GET http://localhost:8000/test-slow

# Find slow traces (>1000ms)
php artisan chronotrace:list --min-duration=1000

# Analyze the slow trace
php artisan chronotrace:replay slow-trace-id

Look for:

• Long-running database queries
• Slow external HTTP calls
• Memory usage spikes
• Overall request timeline

---

🧹 Step 9: Clean Up

After testing, let's clean up:

# Remove test traces
php artisan chronotrace:purge --days=0

# Reset to production-safe mode
CHRONOTRACE_MODE=record_on_error

# Clear config cache
php artisan config:clear

---

🎓 What You've Learned

Congratulations! You've successfully:

• ✅ Captured traces using different methods
• ✅ Listed and filtered traces by various criteria
• ✅ Replayed traces to see detailed execution flow
• ✅ Analyzed different event types (database, cache, HTTP)
• ✅ Debugged errors with complete context
• ✅ Identified performance issues in slow requests
• ✅ Used filtering to focus on specific problems

---

🚀 Next Steps

Now that you understand the basics:

1. Basic Usage - Learn more advanced workflows
2. Event Capturing - Configure what events to capture
3. Configuration - Customize ChronoTrace for your needs
4. Commands - Explore all available commands

Production Usage

When you're ready for production:

# Set production-safe configuration
CHRONOTRACE_MODE=record_on_error
CHRONOTRACE_SAMPLE_RATE=0.001
CHRONOTRACE_ASYNC_STORAGE=true

Check the Production Monitoring guide for best practices.

---

💡 Pro Tips

1. Bookmark useful traces: Note trace IDs of important requests for future reference
2. Use targeted recording: Focus on specific routes during debugging
3. Regular cleanup: Set up automatic purging to manage storage
4. Filter smartly: Use event filtering to reduce noise in complex traces
5. Monitor performance: Watch for trends in request duration and memory usage

---

Ready for more advanced usage? Check out our example scenarios for real-world debugging techniques!