# Troubleshooting

Common issues and solutions when using Laravel ChronoTrace. If you don't find your issue here, please check our [GitHub Issues](https://github.com/Grazulex/laravel-chronotrace/issues).

---

## 🚨 Quick Diagnostics

Always start with the diagnostic command to identify issues:

```bash
php artisan chronotrace:diagnose --verbose
```

This will check:
- ✅ Configuration validity
- ✅ Storage permissions and space
- ✅ Queue workers status
- ✅ PHP extensions
- ✅ Laravel compatibility

---

## 🔧 Installation Issues

### Command Not Found

**Problem:** `Command "chronotrace:install" is not defined`

**Solutions:**
```bash
# Clear Laravel caches
php artisan optimize:clear
php artisan config:clear
php artisan route:clear

# Regenerate autoloader
composer dump-autoload

# Verify package installation
composer show grazulex/laravel-chronotrace

# Manual service provider registration (if auto-discovery fails)
# Add to config.app.php providers array:
Grazulex\LaravelChronotrace\LaravelChronotraceServiceProvider::class,
```

### Package Not Installing

**Problem:** Composer installation fails

**Solutions:**
```bash
# Check PHP version (requires 8.3+)
php --version

# Check Laravel version (requires 10.x or 11.x)
php artisan --version

# Install with verbose output to see errors
composer require --dev grazulex/laravel-chronotrace -vvv

# Clear composer cache if needed
composer clear-cache

# Try installing specific version
composer require --dev grazulex/laravel-chronotrace:^1.0
```

### Configuration Not Publishing

**Problem:** `config/chronotrace.php` not created

**Solutions:**
```bash
# Manual config publishing
php artisan vendor:publish --provider="Grazulex\LaravelChronotrace\LaravelChronotraceServiceProvider" --tag="config"

# Force republishing
php artisan vendor:publish --provider="Grazulex\LaravelChronotrace\LaravelChronotraceServiceProvider" --tag="config" --force

# Check if config exists
ls -la config/chronotrace.php
```

---

## 💾 Storage Issues

### Permission Denied

**Problem:** `Permission denied when writing to storage/chronotrace`

**Solutions:**
```bash
# Fix directory permissions
sudo chown -R www-data:www-data storage/chronotrace
sudo chmod -R 755 storage/chronotrace

# For development (less secure but works)
chmod -R 777 storage/chronotrace

# Create directory if missing
mkdir -p storage/chronotrace/{traces,indexes,temp,metadata}

# Check current permissions
ls -la storage/ | grep chronotrace
```

### Storage Directory Not Created

**Problem:** `storage/chronotrace` directory doesn't exist

**Solutions:**
```bash
# Run installation command
php artisan chronotrace:install

# Manual directory creation
mkdir -p storage/chronotrace/{traces,indexes,temp,metadata}
chmod -R 755 storage/chronotrace
chown -R www-data:www-data storage/chronotrace

# Verify creation
ls -la storage/chronotrace/
```

### Disk Space Issues

**Problem:** Storage running out of space

**Solutions:**
```bash
# Check available space
df -h storage/

# Clean up old traces
php artisan chronotrace:purge --days=7

# Reduce retention period
# In .env:
CHRONOTRACE_RETENTION_DAYS=7

# Enable compression
# In config/chronotrace.php:
'compression' => ['enabled' => true, 'level' => 9],
```

---

## 🔍 Recording Issues

### No Traces Being Recorded

**Problem:** Traces list is empty despite making requests

**Diagnosis:**
```bash
# Check if ChronoTrace is enabled
php artisan chronotrace:diagnose

# Verify configuration
php artisan config:show chronotrace

# Test recording manually
php artisan chronotrace:record --duration=30s
# Make a request
php artisan chronotrace:list
```

**Common Causes & Solutions:**

#### ChronoTrace Disabled
```bash
# Check .env file
CHRONOTRACE_ENABLED=true

# Clear config cache
php artisan config:clear
```

#### Wrong Recording Mode
```bash
# For development, use 'always' mode
CHRONOTRACE_MODE=always

# For production with sampling
CHRONOTRACE_MODE=record_on_error
CHRONOTRACE_SAMPLE_RATE=0.1  # 10% sampling
```

#### Route Exclusions
```php
// Check config/chronotrace.php
'excluded_routes' => [
    // Make sure your routes aren't excluded
],
```

#### Middleware Not Applied
```php
// In App\Http\Kernel.php, verify middleware is registered
protected $middleware = [
    // ...
    \Grazulex\LaravelChronotrace\Middleware\ChronotraceMiddleware::class,
];
```

### Recording Only Errors

**Problem:** Only error traces are captured, no successful requests

**Solution:**
```bash
# Check recording mode
CHRONOTRACE_MODE=sample  # or 'always' for dev
CHRONOTRACE_SAMPLE_RATE=0.1  # 10% of successful requests

# Verify in config
php artisan config:show chronotrace.mode
php artisan config:show chronotrace.sample_rate
```

### Partial Event Capture

**Problem:** Some events missing from traces (DB, cache, HTTP, etc.)

**Solutions:**
```bash
# Check event capture settings in .env
CHRONOTRACE_CAPTURE_DATABASE=true
CHRONOTRACE_CAPTURE_CACHE=true
CHRONOTRACE_CAPTURE_HTTP=true
CHRONOTRACE_CAPTURE_JOBS=true

# Clear config cache
php artisan config:clear

# Test specific event types
php artisan chronotrace:test-internal
```

---

## ⚡ Performance Issues

### High Memory Usage

**Problem:** ChronoTrace consuming too much memory

**Solutions:**
```bash
# Enable async storage
CHRONOTRACE_ASYNC_STORAGE=true
CHRONOTRACE_QUEUE_CONNECTION=redis

# Reduce event capture
CHRONOTRACE_CAPTURE_CACHE=false
CHRONOTRACE_CAPTURE_EVENTS=false

# Limit trace size
# In config/chronotrace.php:
'memory' => [
    'max_trace_size' => 5 * 1024 * 1024,  // 5MB limit
],
```

### Slow Request Performance

**Problem:** Requests slower after enabling ChronoTrace

**Solutions:**
```bash
# Enable async storage with queues
CHRONOTRACE_ASYNC_STORAGE=true

# Start queue workers
php artisan queue:work --queue=chronotrace

# Reduce sampling rate
CHRONOTRACE_SAMPLE_RATE=0.01  # 1% instead of 10%

# Use error-only mode
CHRONOTRACE_MODE=record_on_error
```

### Queue Worker Issues

**Problem:** Queue workers not processing traces

**Diagnosis:**
```bash
# Check queue status
php artisan queue:work --queue=chronotrace --timeout=30

# Monitor failed jobs
php artisan queue:failed

# Check queue configuration
php artisan config:show queue.connections.redis
```

**Solutions:**
```bash
# Restart queue workers
php artisan queue:restart

# Clear failed jobs
php artisan queue:flush

# Use database queue as fallback
QUEUE_CONNECTION=database
php artisan queue:table
php artisan migrate
```

---

## 🔄 Replay Issues

### Trace Not Found

**Problem:** `Trace not found: abc123def456`

**Solutions:**
```bash
# Verify trace ID
php artisan chronotrace:list | grep abc123

# Check storage permissions
ls -la storage/chronotrace/traces/

# Check if trace was purged
php artisan chronotrace:list --all

# Regenerate test trace
php artisan chronotrace:test-internal
```

### Corrupted Trace Data

**Problem:** Error when replaying trace

**Solutions:**
```bash
# Check file integrity
file storage/chronotrace/traces/abc123def456.json

# Try replaying with error handling
php artisan chronotrace:replay abc123def456 --ignore-errors

# Remove corrupted trace
php artisan chronotrace:purge --trace-id=abc123def456

# Check disk space and filesystem
df -h
fsck /dev/sda1  # Replace with your partition
```

---

## 🌐 S3/MinIO Storage Issues

### S3 Connection Failed

**Problem:** Cannot connect to S3/MinIO storage

**Diagnosis:**
```bash
# Test S3 configuration
php artisan chronotrace:diagnose --storage-driver=s3

# Check credentials
aws configure list  # For AWS CLI

# Test connection manually
php artisan tinker
>>> Storage::disk('s3')->put('test.txt', 'test content');
```

**Solutions:**
```bash
# Verify environment variables
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
CHRONOTRACE_S3_BUCKET=your-bucket
CHRONOTRACE_S3_REGION=us-east-1

# For MinIO, add endpoint
CHRONOTRACE_S3_ENDPOINT=https://minio.example.com

# Check bucket permissions
aws s3api get-bucket-acl --bucket your-bucket
```

### S3 Upload Failures

**Problem:** Traces not uploading to S3

**Solutions:**
```bash
# Check bucket permissions (need PutObject, GetObject, DeleteObject)
# Add IAM policy:
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::your-bucket/*"
        }
    ]
}

# Test upload manually
php artisan tinker
>>> Storage::disk('s3')->put('traces/test.json', '{"test": true}');

# Check error logs
tail -f storage/logs/laravel.log
```

---

## 🐛 Common Error Messages

### "Class 'Grazulex\LaravelChronotrace\...' not found"

**Cause:** Autoloader not updated or package not properly installed

**Solution:**
```bash
composer dump-autoload
php artisan optimize:clear
```

### "Call to undefined method ..."

**Cause:** Laravel version incompatibility

**Solution:**
```bash
# Check Laravel version
php artisan --version

# Update to compatible version
composer update laravel/framework

# Check package requirements
composer show grazulex/laravel-chronotrace
```

### "Queue connection [chronotrace] not configured"

**Cause:** Queue connection not set up

**Solution:**
```bash
# Use existing queue connection
CHRONOTRACE_QUEUE_CONNECTION=redis

# Or configure in config/queue.php:
'connections' => [
    'chronotrace' => [
        'driver' => 'redis',
        'connection' => 'default',
        'queue' => 'chronotrace',
    ],
],
```

---

## 🔧 Debug Mode

Enable debug mode for detailed error information:

```bash
# In .env
APP_DEBUG=true
LOG_LEVEL=debug

# Enable ChronoTrace debug
CHRONOTRACE_DEBUG=true

# Monitor logs in real-time
tail -f storage/logs/laravel.log | grep -i chronotrace
```

---

## 📊 Performance Monitoring

Monitor ChronoTrace's impact on your application:

```bash
# Check memory usage
php artisan chronotrace:diagnose --memory

# Monitor queue performance
php artisan queue:monitor chronotrace

# Check storage growth
du -sh storage/chronotrace/
```

---

## 🆘 Getting Additional Help

### Before Reporting Issues

1. **Run diagnostics:**
   ```bash
   php artisan chronotrace:diagnose --verbose
   ```

2. **Check logs:**
   ```bash
   tail -f storage/logs/laravel.log
   ```

3. **Test with minimal configuration:**
   ```bash
   CHRONOTRACE_MODE=always
   CHRONOTRACE_CAPTURE_CACHE=false
   CHRONOTRACE_CAPTURE_EVENTS=false
   ```

### Reporting Bugs

When reporting issues on [GitHub](https://github.com/Grazulex/laravel-chronotrace/issues), include:

- PHP version: `php --version`
- Laravel version: `php artisan --version`
- ChronoTrace version: `composer show grazulex/laravel-chronotrace`
- Diagnostic output: `php artisan chronotrace:diagnose --verbose`
- Error logs (sanitized)
- Steps to reproduce

### Community Resources

- **[GitHub Issues](https://github.com/Grazulex/laravel-chronotrace/issues)** - Bug reports and feature requests
- **[GitHub Discussions](https://github.com/Grazulex/laravel-chronotrace/discussions)** - Community support
- **[Configuration Examples](Configuration-Examples.md)** - Ready-to-use configurations

---

## 🎯 Prevention Tips

### Development Best Practices

```bash
# Use appropriate mode for environment
CHRONOTRACE_MODE=always          # Development
CHRONOTRACE_MODE=sample          # Staging
CHRONOTRACE_MODE=record_on_error # Production

# Monitor storage usage
php artisan chronotrace:diagnose --storage

# Regular cleanup
php artisan schedule:run  # If auto-purge enabled
# or
php artisan chronotrace:purge --days=7
```

### Production Checklist

- ✅ `CHRONOTRACE_MODE=record_on_error`
- ✅ `CHRONOTRACE_ASYNC_STORAGE=true`
- ✅ Queue workers running
- ✅ Reasonable retention period (7-30 days)
- ✅ PII scrubbing enabled
- ✅ Storage monitoring in place
- ✅ Regular backups if using local storage

---

**Still having issues?** Don't hesitate to [open an issue](https://github.com/Grazulex/laravel-chronotrace/issues) with detailed information about your problem.