Installation

Installation & Setup

Get Laravel ChronoTrace up and running in your Laravel application quickly and easily.

---

📋 Requirements

• PHP 8.3+
• Laravel 10.x or 11.x
• Composer

Optional for advanced features:

• Redis (for queue-based async storage)
• AWS S3 or MinIO (for cloud storage)

---

🚀 Quick Installation

1. Install via Composer

composer require --dev grazulex/laravel-chronotrace

2. Run Installation Command

php artisan chronotrace:install

This command will:

• Publish the configuration file to config/chronotrace.php
• Create the storage directory structure
• Set up basic environment variables
• Display configuration recommendations

3. Configure Environment

Add to your .env file:

# Basic configuration
CHRONOTRACE_ENABLED=true
CHRONOTRACE_MODE=record_on_error

# Storage (local by default)
CHRONOTRACE_STORAGE=local
CHRONOTRACE_PATH="${APP_STORAGE_PATH}/chronotrace"

# Retention (15 days by default)
CHRONOTRACE_RETENTION_DAYS=15

4. Test Installation

# Verify installation
php artisan chronotrace:diagnose

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

---

⚙️ Configuration Options

Recording Modes

Choose when ChronoTrace should record traces:

# Development: Record everything
CHRONOTRACE_MODE=always

# Production: Only errors + sampling
CHRONOTRACE_MODE=record_on_error
CHRONOTRACE_SAMPLE_RATE=0.001  # 0.1% of successful requests

# Testing: Sample all requests
CHRONOTRACE_MODE=sample
CHRONOTRACE_SAMPLE_RATE=0.1   # 10% of all requests

# Selective: Only specific routes
CHRONOTRACE_MODE=targeted

Event Capture Settings

Control what events to capture:

# Essential events (recommended for production)
CHRONOTRACE_CAPTURE_DATABASE=true
CHRONOTRACE_CAPTURE_HTTP=true
CHRONOTRACE_CAPTURE_JOBS=true

# Optional events (can be noisy)
CHRONOTRACE_CAPTURE_CACHE=false
CHRONOTRACE_CAPTURE_EVENTS=false

Storage Configuration

Local Storage (Default)

CHRONOTRACE_STORAGE=local
CHRONOTRACE_PATH="${APP_STORAGE_PATH}/chronotrace"

S3 Storage

CHRONOTRACE_STORAGE=s3
CHRONOTRACE_S3_BUCKET=my-chronotrace-bucket
CHRONOTRACE_S3_REGION=us-east-1
CHRONOTRACE_S3_PREFIX=traces

MinIO Storage

CHRONOTRACE_STORAGE=s3
CHRONOTRACE_S3_BUCKET=chronotrace
CHRONOTRACE_S3_ENDPOINT=https://minio.example.com
CHRONOTRACE_S3_REGION=us-east-1

---

🔧 Advanced Setup

Queue Integration (Recommended for Production)

For better performance, use queues for async trace storage:

1. Configure Queue Driver:

   # In .env
   QUEUE_CONNECTION=redis  # or database

2. Run Queue Workers:

   php artisan queue:work --queue=chronotrace

3. Enable Async Storage:

   # In config/chronotrace.php
   'async_storage' => true,
   'queue_connection' => 'redis',

Middleware Setup (Optional)

Add middleware to specific routes for targeted recording:

// In routes/web.php or routes/api.php
Route::middleware(['chronotrace'])->group(function () {
    Route::post('/api/orders', [OrderController::class, 'store']);
    Route::put('/api/users/{user}', [UserController::class, 'update']);
});

Custom Storage Driver

Register a custom storage driver in your AppServiceProvider:

use Grazulex\LaravelChronotrace\Storage\Manager;

public function boot()
{
    $this->app->afterResolving(Manager::class, function (Manager $manager) {
        $manager->extend('custom', function ($app, $config) {
            return new CustomStorageDriver($config);
        });
    });
}

---

🛡️ Security Considerations

PII Scrubbing

Configure sensitive data scrubbing:

// In config/chronotrace.php
'scrub' => [
    'password',
    'token',
    'secret',
    'key',
    'email',           // Add email scrubbing
    'phone',           // Add phone scrubbing
    'ssn',             // Add SSN scrubbing
    'credit_card',     // Add credit card scrubbing
],

'custom_scrubbers' => [
    // Custom regex patterns
    '/\b\d{4}-\d{4}-\d{4}-\d{4}\b/' => '****-****-****-****',
    '/api_key_\w+/' => 'api_key_[REDACTED]',
],

Production Environment

For production, use these security-focused settings:

# Only record errors
CHRONOTRACE_MODE=record_on_error

# Minimal sampling
CHRONOTRACE_SAMPLE_RATE=0.001

# Essential events only
CHRONOTRACE_CAPTURE_CACHE=false
CHRONOTRACE_CAPTURE_EVENTS=false

# Short retention
CHRONOTRACE_RETENTION_DAYS=7

# Scrub everything
CHRONOTRACE_SCRUB_PII=true

---

📁 Directory Structure

After installation, ChronoTrace creates this structure:

storage/
├── chronotrace/
│   ├── traces/           # Individual trace files
│   ├── indexes/          # Search indexes
│   ├── temp/            # Temporary files
│   └── metadata/        # Trace metadata

Permissions

Ensure proper permissions:

# Set directory permissions
chmod -R 755 storage/chronotrace
chown -R www-data:www-data storage/chronotrace

# For shared hosting
chmod -R 777 storage/chronotrace

---

🔍 Verification

Test Installation

# Check configuration and system status
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
   
✅ Dependencies
   PHP Version: 8.3.x ✓
   Laravel Version: 11.x ✓
   Required Extensions: ✓

⚠️  Recommendations
   - Enable queue workers for better performance
   - Configure Redis for production use

Create Test Trace

# Generate a test trace
php artisan chronotrace:test-internal

# List traces to verify
php artisan chronotrace:list

# Replay the test trace
php artisan chronotrace:replay {trace-id}

---

🚨 Troubleshooting Installation

Common Issues

Permission Denied

# Fix storage permissions
sudo chown -R www-data:www-data storage/chronotrace
sudo chmod -R 755 storage/chronotrace

Missing Extensions

# Install required PHP extensions
sudo apt-get install php8.3-json php8.3-mbstring php8.3-zip

Storage Not Writable

# Check disk space
df -h

# Check directory permissions
ls -la storage/

Configuration Not Published

# Manually publish configuration
php artisan vendor:publish --provider="Grazulex\LaravelChronotrace\LaravelChronotraceServiceProvider"

Getting Help

If you encounter issues:

1. Check the Troubleshooting Guide
2. Run diagnostics: php artisan chronotrace:diagnose
3. Check logs: tail -f storage/logs/laravel.log
4. Report bugs: GitHub Issues

---

📝 Next Steps

Now that ChronoTrace is installed:

• Basic Usage - Learn the fundamentals
• Your First Trace - Step-by-step walkthrough
• Configuration - Detailed configuration options
• Commands - Complete command reference

---

Installation complete! Start making requests to your application and use php artisan chronotrace:list to see captured traces.