# Configuration

ChronoTrace offers extensive configuration options to customize recording behavior, storage, security, and performance to match your application's needs.

---

## 📋 Quick Configuration

### Basic Setup

The most common configuration options for getting started:

```php
// config/chronotrace.php

return [
    // Enable/disable ChronoTrace
    'enabled' => env('CHRONOTRACE_ENABLED', true),
    
    // When to record traces
    'mode' => env('CHRONOTRACE_MODE', 'record_on_error'),
    
    // Storage location
    'storage' => env('CHRONOTRACE_STORAGE', 'local'),
    'path' => env('CHRONOTRACE_PATH', storage_path('chronotrace')),
    
    // How long to keep traces
    'retention_days' => env('CHRONOTRACE_RETENTION_DAYS', 15),
];
```

### Environment Variables

```bash
# .env file - Essential settings
CHRONOTRACE_ENABLED=true
CHRONOTRACE_MODE=record_on_error
CHRONOTRACE_STORAGE=local
CHRONOTRACE_RETENTION_DAYS=15
```

---

## 🎛️ Recording Configuration

### Recording Modes

Control when ChronoTrace captures traces:

```php
'mode' => env('CHRONOTRACE_MODE', 'record_on_error'),
```

Available modes:

#### `always` - Record Everything
```bash
CHRONOTRACE_MODE=always
```
- **Use case:** Development environment
- **Captures:** Every single request
- **Performance impact:** High
- **Storage usage:** Very high

#### `record_on_error` - Error-Only Recording (Recommended for Production)
```bash
CHRONOTRACE_MODE=record_on_error
CHRONOTRACE_SAMPLE_RATE=0.001  # 0.1% of successful requests
```
- **Use case:** Production monitoring
- **Captures:** All failed requests + sample of successful ones
- **Performance impact:** Low
- **Storage usage:** Low

#### `sample` - Statistical Sampling
```bash
CHRONOTRACE_MODE=sample
CHRONOTRACE_SAMPLE_RATE=0.1  # 10% of all requests
```
- **Use case:** Performance monitoring, staging
- **Captures:** Random percentage of all requests
- **Performance impact:** Medium
- **Storage usage:** Medium

#### `targeted` - Selective Recording
```bash
CHRONOTRACE_MODE=targeted
```
```php
'targeted_routes' => [
    'api/orders/*',
    'api/payments/*',
    'admin/users/*',
],
'targeted_conditions' => [
    'user_id' => [123, 456],  // Specific users
    'ip' => ['192.168.1.100'], // Specific IPs
],
```
- **Use case:** Debugging specific features
- **Captures:** Only specified routes/conditions
- **Performance impact:** Very low
- **Storage usage:** Very low

### Sample Rate Configuration

Fine-tune sampling behavior:

```php
'sample_rate' => env('CHRONOTRACE_SAMPLE_RATE', 0.001),

// Advanced sampling
'sampling' => [
    'base_rate' => 0.001,           // 0.1% base rate
    'error_rate' => 1.0,            // 100% of errors
    'slow_request_threshold' => 1000, // Requests > 1s
    'slow_request_rate' => 0.1,     // 10% of slow requests
],
```

---

## 💾 Storage Configuration

### Local Storage (Default)

```php
'storage' => 'local',
'path' => env('CHRONOTRACE_PATH', storage_path('chronotrace')),

'local' => [
    'path' => storage_path('chronotrace'),
    'create_directories' => true,
    'permissions' => [
        'file' => 0644,
        'dir' => 0755,
    ],
],
```

### S3 Storage

```php
'storage' => 's3',

's3' => [
    'bucket' => env('CHRONOTRACE_S3_BUCKET', 'chronotrace'),
    'region' => env('CHRONOTRACE_S3_REGION', 'us-east-1'),
    'endpoint' => env('CHRONOTRACE_S3_ENDPOINT'), // For MinIO
    'path_prefix' => env('CHRONOTRACE_S3_PREFIX', 'traces'),
    'use_path_style_endpoint' => false,
    
    // Storage class for cost optimization
    'storage_class' => 'STANDARD_IA', // STANDARD, STANDARD_IA, GLACIER
    
    // Server-side encryption
    'server_side_encryption' => 'AES256',
],
```

Environment variables for S3:
```bash
CHRONOTRACE_STORAGE=s3
CHRONOTRACE_S3_BUCKET=my-traces-bucket
CHRONOTRACE_S3_REGION=us-west-2
CHRONOTRACE_S3_PREFIX=production/traces
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
```

### MinIO Storage

```bash
CHRONOTRACE_STORAGE=s3
CHRONOTRACE_S3_BUCKET=chronotrace
CHRONOTRACE_S3_ENDPOINT=https://minio.example.com
CHRONOTRACE_S3_REGION=us-east-1
AWS_ACCESS_KEY_ID=minio_access_key
AWS_SECRET_ACCESS_KEY=minio_secret_key
```

---

## 📊 Event Capture Configuration

### Event Types

Control which events to capture:

```php
'capture' => [
    'database' => env('CHRONOTRACE_CAPTURE_DATABASE', true),
    'cache' => env('CHRONOTRACE_CAPTURE_CACHE', true),
    'http' => env('CHRONOTRACE_CAPTURE_HTTP', true),
    'jobs' => env('CHRONOTRACE_CAPTURE_JOBS', true),
    'events' => env('CHRONOTRACE_CAPTURE_EVENTS', false),
    'logs' => env('CHRONOTRACE_CAPTURE_LOGS', false),
],
```

#### Database Events
```php
'database' => [
    'enabled' => true,
    'include_bindings' => true,
    'slow_query_threshold' => 100,  // ms
    'excluded_tables' => [
        'sessions',
        'cache',
        'telescope_*',
    ],
],
```

#### Cache Events
```php
'cache' => [
    'enabled' => true,
    'include_values' => false,  // Don't store cache values (large)
    'excluded_keys' => [
        'session:*',
        'telescope:*',
    ],
],
```

#### HTTP Events
```php
'http' => [
    'enabled' => true,
    'include_request_body' => true,
    'include_response_body' => true,
    'max_body_size' => 64 * 1024,  // 64KB
    'excluded_hosts' => [
        'localhost',
        '127.0.0.1',
    ],
],
```

#### Queue Job Events
```php
'jobs' => [
    'enabled' => true,
    'include_payload' => true,
    'excluded_jobs' => [
        'Laravel\\Telescope\\*',
        'App\\Jobs\\LogCleanup',
    ],
],
```

---

## 🔐 Security & Privacy

### PII Scrubbing

Automatically mask sensitive data:

```php
'scrub' => [
    // Default patterns
    'password',
    'token',
    'secret',
    'key',
    'email',
    'phone',
    'ssn',
    'credit_card',
    
    // Custom field names
    'api_token',
    'auth_key',
    'private_key',
],

'custom_scrubbers' => [
    // Regex patterns with replacements
    '/\b\d{4}-\d{4}-\d{4}-\d{4}\b/' => '****-****-****-****',
    '/api_key_\w+/' => 'api_key_[REDACTED]',
    '/Bearer\s+\S+/' => 'Bearer [REDACTED]',
    '/password":\s*"[^"]*"/' => 'password": "[REDACTED]"',
],
```

### Request Filtering

Exclude sensitive routes from recording:

```php
'excluded_routes' => [
    'password/*',
    'api/auth/login',
    'api/payments/process',
    'admin/sensitive/*',
],

'excluded_ips' => [
    '192.168.1.100',  // Admin IP
    '10.0.0.0/8',     // Internal network
],
```

---

## ⚡ Performance Configuration

### Compression

Reduce storage space with compression:

```php
'compression' => [
    'enabled' => true,
    'level' => 6,  // 1-9, higher = better compression, slower
    'threshold' => 1024,  // Only compress files > 1KB
    'max_payload_size' => 1024 * 1024,  // 1MB limit
],
```

### Async Storage

Use queues for better performance:

```php
'async_storage' => env('CHRONOTRACE_ASYNC_STORAGE', true),
'queue_connection' => env('CHRONOTRACE_QUEUE_CONNECTION', 'redis'),
'queue_name' => env('CHRONOTRACE_QUEUE_NAME', 'chronotrace'),
```

Environment variables:
```bash
CHRONOTRACE_ASYNC_STORAGE=true
CHRONOTRACE_QUEUE_CONNECTION=redis
CHRONOTRACE_QUEUE_NAME=chronotrace
```

### Memory Management

```php
'memory' => [
    'max_trace_size' => 10 * 1024 * 1024,  // 10MB per trace
    'gc_probability' => 100,  // Run garbage collection every request
],
```

---

## 🗂️ Retention & Cleanup

### Automatic Cleanup

```php
'retention_days' => env('CHRONOTRACE_RETENTION_DAYS', 15),
'auto_purge' => env('CHRONOTRACE_AUTO_PURGE', true),

'purge' => [
    'schedule' => 'daily',  // Run cleanup daily
    'batch_size' => 100,    // Process 100 traces at a time
    'keep_errors_longer' => true,  // Keep error traces 2x longer
    'compress_old_traces' => true, // Compress traces older than 7 days
],
```

### Custom Retention Policies

```php
'retention_policies' => [
    'error_traces' => 30,      // Keep errors for 30 days
    'slow_traces' => 21,       // Keep slow requests for 21 days
    'success_traces' => 7,     // Keep successful requests for 7 days
    'api_traces' => 14,        // Keep API calls for 14 days
],
```

---

## 🌍 Environment-Specific Configurations

### Development Environment

```php
// config/chronotrace.php
'mode' => 'always',
'capture' => [
    'database' => true,
    'cache' => true,
    'http' => true,
    'jobs' => true,
    'events' => true,  // Enable verbose events
],
'retention_days' => 3,  // Short retention for dev
'async_storage' => false,  // Synchronous for immediate debugging
```

### Staging Environment

```php
'mode' => 'sample',
'sample_rate' => 0.1,  // 10% sampling
'capture' => [
    'database' => true,
    'cache' => false,   // Reduce noise
    'http' => true,
    'jobs' => true,
    'events' => false,
],
'retention_days' => 7,
'async_storage' => true,
```

### Production Environment

```php
'mode' => 'record_on_error',
'sample_rate' => 0.001,  // 0.1% sampling
'capture' => [
    'database' => true,
    'cache' => false,   // Minimal noise
    'http' => true,
    'jobs' => true,
    'events' => false,
],
'retention_days' => 15,
'async_storage' => true,
'scrub_pii' => true,    // Important for production
```

---

## 🔧 Advanced Configuration

### Custom Event Handlers

```php
'custom_events' => [
    'user_login' => \App\ChronoTrace\Events\UserLoginHandler::class,
    'payment_processed' => \App\ChronoTrace\Events\PaymentHandler::class,
],
```

### Middleware Configuration

```php
'middleware' => [
    'enabled' => true,
    'priority' => 10,  // Middleware priority
    'excluded_routes' => [
        'health-check',
        'metrics',
    ],
],
```

### Storage Partitioning

```php
'partitioning' => [
    'strategy' => 'date',  // date, size, hash
    'date_format' => 'Y/m/d',
    'max_files_per_directory' => 1000,
],
```

---

## 📝 Configuration Examples

### E-commerce Application

```php
return [
    'mode' => 'targeted',
    'targeted_routes' => [
        'api/orders/*',
        'api/payments/*',
        'checkout/*',
    ],
    'capture' => [
        'database' => true,
        'http' => true,      // Payment gateways
        'jobs' => true,      // Order processing
        'cache' => false,
    ],
    'scrub' => [
        'credit_card',
        'cvv',
        'bank_account',
        'payment_token',
    ],
];
```

### API-Heavy Application

```php
return [
    'mode' => 'sample',
    'sample_rate' => 0.05,  // 5% sampling
    'capture' => [
        'database' => false,  // Minimal DB usage
        'http' => true,       // Focus on API calls
        'jobs' => true,
        'cache' => true,      // API response caching
    ],
    'http' => [
        'max_body_size' => 128 * 1024,  // Larger API responses
    ],
];
```

---

## 🚨 Configuration Validation

ChronoTrace validates your configuration on startup. Common validation errors:

```bash
# Invalid mode
CHRONOTRACE_MODE=invalid_mode
# Error: Invalid recording mode. Must be one of: always, sample, record_on_error, targeted

# Invalid sample rate
CHRONOTRACE_SAMPLE_RATE=1.5
# Error: Sample rate must be between 0.0 and 1.0

# Invalid storage driver
CHRONOTRACE_STORAGE=invalid_driver
# Error: Storage driver 'invalid_driver' is not supported
```

Use the diagnose command to check configuration:

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

---

## 📚 Related Documentation

- **[Installation](Installation.md)** - Setup instructions
- **[Storage Options](Storage.md)** - Detailed storage configuration
- **[Security & PII](Security.md)** - Security best practices
- **[Production Monitoring](Production-Monitoring.md)** - Production configuration

---

**Need help with configuration?** Check the [Configuration Examples](Configuration-Examples.md) page for ready-to-use configurations for common scenarios.