# 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](Installation.md) and configured.

---

## 📋 Step 1: Verify Installation

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

```bash
# 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](Troubleshooting.md).

---

## 🎬 Step 2: Enable Recording

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

```bash
# 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
```bash
# Generate a test trace with sample events
php artisan chronotrace:test-internal
```

### Option B: Make a Real Request
```bash
# 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:

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

```bash
# 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
```bash
php artisan chronotrace:replay abc123def456789 --filter=database
```

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

### View Only HTTP Events
```bash
php artisan chronotrace:replay abc123def456789 --filter=http
```

Perfect for debugging external API integration issues.

### View Multiple Event Types
```bash
php artisan chronotrace:replay abc123def456789 --filter=database,http
```

Combines database and HTTP events while hiding cache operations.

### View Only Slow Events
```bash
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
```bash
# 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:

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

```bash
# 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](Basic-Usage.md)** - Learn more advanced workflows
2. **[Event Capturing](Event-Capturing.md)** - Configure what events to capture
3. **[Configuration](Configuration.md)** - Customize ChronoTrace for your needs
4. **[Commands](Commands.md)** - Explore all available commands

### Production Usage

When you're ready for production:

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

Check the [Production Monitoring](Production-Monitoring.md) 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](Example-Database-Debugging.md) for real-world debugging techniques!