Troubleshooting

Troubleshooting

Common issues and solutions when using Laravel ChronoTrace. If you don't find your issue here, please check our GitHub Issues.

---

🚨 Quick Diagnostics

Always start with the diagnostic command to identify issues:

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:

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

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

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

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

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

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

# 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

# Check .env file
CHRONOTRACE_ENABLED=true

# Clear config cache
php artisan config:clear

Wrong Recording Mode

# 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

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

Middleware Not Applied

// 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:

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

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

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

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

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

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

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

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

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

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

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

composer dump-autoload
php artisan optimize:clear

"Call to undefined method ..."

Cause: Laravel version incompatibility

Solution:

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

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

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

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

   php artisan chronotrace:diagnose --verbose

2. Check logs:

   tail -f storage/logs/laravel.log

3. Test with minimal configuration:

   CHRONOTRACE_MODE=always
   CHRONOTRACE_CAPTURE_CACHE=false
   CHRONOTRACE_CAPTURE_EVENTS=false

Reporting Bugs

When reporting issues on GitHub, 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 - Bug reports and feature requests
• GitHub Discussions - Community support
• Configuration Examples - Ready-to-use configurations

---

🎯 Prevention Tips

Development Best Practices

# 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 with detailed information about your problem.