Configuration Examples

Configuration Examples

This guide provides practical configuration examples for different environments, use cases, and deployment scenarios.

Environment-Specific Configurations

Development Environment

Goal: Maximum debugging information with immediate feedback

// config/chronotrace.php for development
return [
    'enabled' => true,
    'mode' => 'always',           // Capture everything for debugging
    'storage' => 'local',
    'path' => storage_path('chronotrace'),
    'retention_days' => 7,        // Short retention to save disk space
    'debug' => true,              // Enable debug logging
    
    'capture' => [
        'database' => true,
        'cache' => true,
        'http' => true,
        'jobs' => true,
        'events' => true,         // Enable for full debugging visibility
        'request' => true,
        'response' => true,
        'filesystem' => true,     // Include file operations for debugging
    ],
    
    'compression' => [
        'enabled' => false,       // Disable for faster writes and easier reading
    ],
    
    'async_storage' => false,     // Synchronous for immediate availability
    
    'scrub' => [
        'password',
        'token',
        'secret',                 // Minimal scrubbing for easier debugging
    ],
];

Environment Variables for Development:

# Basic Configuration
CHRONOTRACE_ENABLED=true
CHRONOTRACE_MODE=always
CHRONOTRACE_STORAGE=local
CHRONOTRACE_RETENTION_DAYS=7
CHRONOTRACE_DEBUG=true

# Capture Settings
CHRONOTRACE_CAPTURE_DATABASE=true
CHRONOTRACE_CAPTURE_CACHE=true
CHRONOTRACE_CAPTURE_HTTP=true
CHRONOTRACE_CAPTURE_JOBS=true
CHRONOTRACE_CAPTURE_EVENTS=true

# Performance Settings
CHRONOTRACE_ASYNC_STORAGE=false

Staging Environment

Goal: Representative production testing with moderate capture

// config/chronotrace.php for staging
return [
    'enabled' => true,
    'mode' => 'sample',           // Sample requests for performance testing
    'sample_rate' => 0.05,        // 5% of requests
    'storage' => 's3',            // Use S3 to match production
    'retention_days' => 15,
    'debug' => false,
    
    'capture' => [
        'database' => true,
        'cache' => true,
        'http' => true,
        'jobs' => true,
        'events' => false,        // Disable verbose events
        'request' => true,
        'response' => true,
        'filesystem' => false,    // Disable for performance
    ],
    
    'compression' => [
        'enabled' => true,
        'level' => 6,
    ],
    
    'async_storage' => true,      // Test async behavior
    'queue_connection' => 'redis',
    
    's3' => [
        'bucket' => 'staging-chronotrace',
        'region' => 'us-east-1',
        'path_prefix' => 'staging/traces',
    ],
    
    'scrub' => [
        'password', 'token', 'secret', 'key', 'authorization',
        'cookie', 'session', 'credit_card', 'ssn', 'email', 'phone',
    ],
];

Production Environment

Goal: Minimal performance impact with error capture only

// config/chronotrace.php for production
return [
    'enabled' => true,
    'mode' => 'record_on_error',  // Only capture on 5xx errors
    'storage' => 's3',
    'retention_days' => 30,
    'debug' => false,
    
    'capture' => [
        'database' => true,
        'cache' => true,
        'http' => true,
        'jobs' => true,
        'events' => false,        // Disabled for performance
        'request' => true,
        'response' => true,
        'filesystem' => false,    // Disabled for performance
    ],
    
    'compression' => [
        'enabled' => true,
        'level' => 6,             // Good compression/speed balance
        'max_payload_size' => 1024 * 1024, // 1MB
    ],
    
    'async_storage' => true,      // Essential for production
    'queue_connection' => 'redis',
    'queue_fallback' => true,     // Fallback to sync if queue fails
    
    's3' => [
        'bucket' => 'production-chronotrace',
        'region' => 'us-east-1',
        'path_prefix' => 'production/traces',
    ],
    
    'scrub' => [
        'password', 'token', 'secret', 'key', 'authorization',
        'cookie', 'session', 'credit_card', 'ssn', 'email', 'phone',
        'address', 'ip_address', 'user_agent',
        // Add application-specific sensitive fields
        'internal_id', 'customer_number', 'account_id',
    ],
];

Use Case-Specific Configurations

High-Traffic E-commerce Site

return [
    'enabled' => true,
    'mode' => 'record_on_error',
    'sample_rate' => 0.0001,      // Very low sample rate (0.01%)
    'storage' => 's3',
    'async_storage' => true,
    'retention_days' => 45,       // Longer retention for business analysis
    
    'capture' => [
        'database' => true,        // Critical for checkout issues
        'cache' => false,          // Disable - too much volume
        'http' => true,            // External payment/shipping APIs
        'jobs' => true,            // Order processing jobs
        'events' => false,
    ],
    
    'compression' => [
        'enabled' => true,
        'level' => 9,              // Maximum compression for cost savings
    ],
    
    'targets' => [
        'routes' => [
            'checkout/*',
            'payment/*', 
            'orders/*',
        ],
    ],
];

API-First Application

return [
    'enabled' => true,
    'mode' => 'sample',
    'sample_rate' => 0.01,        // 1% sample rate
    'storage' => 's3',
    
    'capture' => [
        'database' => true,
        'cache' => true,
        'http' => true,            // External API dependencies
        'jobs' => true,
        'events' => false,
        'request' => true,         // Full request details for API debugging
        'response' => true,        // Response analysis
    ],
    
    'scrub' => [
        'password', 'token', 'secret', 'api_key', 'authorization',
        'client_secret', 'refresh_token', 'access_token',
    ],
];

Microservices Architecture

return [
    'enabled' => true,
    'mode' => 'targeted',
    'storage' => 's3',
    
    'targets' => [
        'routes' => [
            'api/internal/*',      // Inter-service communication
            'webhooks/*',          // External webhook handlers
        ],
    ],
    
    'capture' => [
        'database' => true,
        'cache' => true,
        'http' => true,            // Critical for service-to-service calls
        'jobs' => true,
        'events' => false,
    ],
    
    's3' => [
        'bucket' => 'microservice-traces',
        'path_prefix' => env('SERVICE_NAME', 'unknown') . '/traces',
    ],
];

Storage Configurations

AWS S3 with KMS Encryption

return [
    'storage' => 's3',
    's3' => [
        'bucket' => 'secure-chronotrace',
        'region' => 'us-east-1',
        'path_prefix' => 'encrypted-traces',
        'server_side_encryption' => 'aws:kms',
        'kms_key_id' => 'arn:aws:kms:us-east-1:123456789:key/12345678-1234-1234-1234-123456789012',
    ],
];

MinIO Self-Hosted

return [
    'storage' => 's3',
    's3' => [
        'bucket' => 'chronotrace',
        'region' => 'us-east-1',
        'endpoint' => 'https://minio.internal.company.com',
        'use_path_style_endpoint' => true,
        'path_prefix' => 'traces',
    ],
];

Multi-Region S3 Setup

return [
    'storage' => 's3',
    's3' => [
        'bucket' => 'chronotrace-' . env('AWS_DEFAULT_REGION', 'us-east-1'),
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
        'path_prefix' => env('APP_ENV', 'production') . '/traces',
    ],
];

Performance Configurations

High-Performance Setup

return [
    'enabled' => true,
    'mode' => 'record_on_error',
    'async_storage' => true,
    'queue_connection' => 'redis',
    
    'compression' => [
        'enabled' => true,
        'level' => 3,              // Lower compression for speed
        'max_payload_size' => 512 * 1024, // 512KB threshold
    ],
    
    'capture' => [
        'database' => true,
        'cache' => false,          // Disable high-volume events
        'http' => true,
        'jobs' => true,
        'events' => false,
        'filesystem' => false,
    ],
];

Low-Resource Environment

return [
    'enabled' => true,
    'mode' => 'record_on_error',
    'async_storage' => false,      // Avoid queue overhead
    'retention_days' => 3,         // Short retention
    
    'compression' => [
        'enabled' => false,        // Avoid CPU overhead
    ],
    
    'capture' => [
        'database' => true,        // Only essential events
        'cache' => false,
        'http' => true,
        'jobs' => false,
        'events' => false,
    ],
];

Security-Focused Configurations

HIPAA Compliant

return [
    'enabled' => true,
    'mode' => 'record_on_error',
    'storage' => 's3',
    'retention_days' => 7,         // Short retention for compliance
    
    'scrub' => [
        'password', 'token', 'secret', 'key', 'authorization',
        'ssn', 'patient_id', 'medical_record_number',
        'diagnosis', 'medication', 'date_of_birth',
        'insurance_number', 'email', 'phone', 'address',
    ],
    
    's3' => [
        'bucket' => 'hipaa-compliant-traces',
        'server_side_encryption' => 'aws:kms',
        'kms_key_id' => env('HIPAA_KMS_KEY_ID'),
    ],
];

GDPR Compliant

return [
    'enabled' => true,
    'mode' => 'record_on_error',
    'retention_days' => 14,        // Short retention for privacy
    
    'scrub' => [
        'password', 'token', 'secret', 'key', 'authorization',
        'email', 'phone', 'address', 'name', 'ip_address',
        'user_agent', 'session_id', 'device_id',
    ],
    
    'capture' => [
        'database' => true,
        'cache' => false,          // May contain personal data
        'http' => true,
        'jobs' => true,
        'events' => false,         // May contain personal data
    ],
];

CI/CD and Testing Configurations

Continuous Integration

# .env.testing
CHRONOTRACE_ENABLED=true
CHRONOTRACE_MODE=always
CHRONOTRACE_STORAGE=local
CHRONOTRACE_PATH=/tmp/chronotrace-test
CHRONOTRACE_RETENTION_DAYS=1
CHRONOTRACE_ASYNC_STORAGE=false
CHRONOTRACE_DEBUG=true

Load Testing

return [
    'enabled' => false,            // Disable during load tests
    // Or use minimal configuration:
    'enabled' => true,
    'mode' => 'sample',
    'sample_rate' => 0.0001,       // Extremely low sample rate
    'capture' => [
        'database' => false,
        'cache' => false,
        'http' => false,
        'jobs' => false,
        'events' => false,
    ],
];

Environment Variable Templates

Complete Development Template

# Development .env template
CHRONOTRACE_ENABLED=true
CHRONOTRACE_MODE=always
CHRONOTRACE_STORAGE=local
CHRONOTRACE_PATH="${APP_ROOT}/storage/chronotrace"
CHRONOTRACE_RETENTION_DAYS=7
CHRONOTRACE_DEBUG=true
CHRONOTRACE_ASYNC_STORAGE=false

CHRONOTRACE_CAPTURE_DATABASE=true
CHRONOTRACE_CAPTURE_CACHE=true
CHRONOTRACE_CAPTURE_HTTP=true
CHRONOTRACE_CAPTURE_JOBS=true
CHRONOTRACE_CAPTURE_EVENTS=true

Complete Production Template

# Production .env template
CHRONOTRACE_ENABLED=true
CHRONOTRACE_MODE=record_on_error
CHRONOTRACE_STORAGE=s3
CHRONOTRACE_RETENTION_DAYS=30
CHRONOTRACE_DEBUG=false

CHRONOTRACE_S3_BUCKET=${APP_NAME}-chronotrace-${APP_ENV}
CHRONOTRACE_S3_REGION=us-east-1
CHRONOTRACE_S3_PREFIX=traces

CHRONOTRACE_ASYNC_STORAGE=true
CHRONOTRACE_QUEUE_CONNECTION=redis
CHRONOTRACE_QUEUE=chronotrace-${APP_ENV}

CHRONOTRACE_CAPTURE_DATABASE=true
CHRONOTRACE_CAPTURE_CACHE=true
CHRONOTRACE_CAPTURE_HTTP=true
CHRONOTRACE_CAPTURE_JOBS=true
CHRONOTRACE_CAPTURE_EVENTS=false

Next Steps

• Learn about event filtering
• Set up production monitoring
• Explore storage options
• Configure security settings