Skip to content

Configuration

Jump to bottom
Jean-Marc Strauven edited this page Aug 6, 2025 · 2 revisions

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:

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

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

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

Available modes:

always - Record Everything

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)

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

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

CHRONOTRACE_MODE=targeted
'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:

'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)

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

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

S3 Storage

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

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

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:

'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

'database' => [
    'enabled' => true,
    'include_bindings' => true,
    'slow_query_threshold' => 100,  // ms
    'excluded_tables' => [
        'sessions',
        'cache',
        'telescope_*',
    ],
],

Cache Events

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

HTTP Events

'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

'jobs' => [
    'enabled' => true,
    'include_payload' => true,
    'excluded_jobs' => [
        'Laravel\\Telescope\\*',
        'App\\Jobs\\LogCleanup',
    ],
],

🔐 Security & Privacy

PII Scrubbing

Automatically mask sensitive data:

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

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

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

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

Environment variables:

CHRONOTRACE_ASYNC_STORAGE=true
CHRONOTRACE_QUEUE_CONNECTION=redis
CHRONOTRACE_QUEUE_NAME=chronotrace

Memory Management

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

🗂️ Retention & Cleanup

Automatic Cleanup

'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

'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

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

'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

'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

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

Middleware Configuration

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

Storage Partitioning

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

📝 Configuration Examples

E-commerce Application

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

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:

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

php artisan chronotrace:diagnose --config

📚 Related Documentation

Need help with configuration? Check the Configuration Examples page for ready-to-use configurations for common scenarios.

Laravel ChronoTrace - Record and replay Laravel requests deterministically

GitHub • Packagist • License

🔗 Quick Links

📖 Popular Pages

Section Page Description
🚀 Basics Your First Trace Step-by-step beginner guide
🎛️ Config Recording Modes Choose when to record traces
🛡️ Security Security & PII Protect sensitive data
🔧 Tools Commands Complete command reference

🆘 Need Help?

ChronoTrace helps Laravel developers debug applications faster with intelligent request tracing.

Made with ❤️ by Grazulex • Documentation updated August 2024

📚 Laravel ChronoTrace Wiki

🏠 Home

🚀 Getting Started

🎯 Core Concepts

⚙️ Configuration

🔧 Commands & Tools

🏭 Advanced Usage

📖 Examples & Guides

🔍 Reference

🤝 Community

Clone this wiki locally