# 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

```bash
composer require --dev grazulex/laravel-chronotrace
```

### 2. Run Installation Command

```bash
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:

```bash
# 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

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

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

```bash
# 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)
```bash
CHRONOTRACE_STORAGE=local
CHRONOTRACE_PATH="${APP_STORAGE_PATH}/chronotrace"
```

#### S3 Storage
```bash
CHRONOTRACE_STORAGE=s3
CHRONOTRACE_S3_BUCKET=my-chronotrace-bucket
CHRONOTRACE_S3_REGION=us-east-1
CHRONOTRACE_S3_PREFIX=traces
```

#### MinIO Storage
```bash
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:**
   ```bash
   # In .env
   QUEUE_CONNECTION=redis  # or database
   ```

2. **Run Queue Workers:**
   ```bash
   php artisan queue:work --queue=chronotrace
   ```

3. **Enable Async Storage:**
   ```bash
   # In config/chronotrace.php
   'async_storage' => true,
   'queue_connection' => 'redis',
   ```

### Middleware Setup (Optional)

Add middleware to specific routes for targeted recording:

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

```php
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:

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

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

```bash
# 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

```bash
# 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

```bash
# 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
```bash
# Fix storage permissions
sudo chown -R www-data:www-data storage/chronotrace
sudo chmod -R 755 storage/chronotrace
```

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

#### Storage Not Writable
```bash
# Check disk space
df -h

# Check directory permissions
ls -la storage/
```

#### Configuration Not Published
```bash
# Manually publish configuration
php artisan vendor:publish --provider="Grazulex\LaravelChronotrace\LaravelChronotraceServiceProvider"
```

### Getting Help

If you encounter issues:

1. **Check the [Troubleshooting Guide](Troubleshooting.md)**
2. **Run diagnostics:** `php artisan chronotrace:diagnose`
3. **Check logs:** `tail -f storage/logs/laravel.log`
4. **Report bugs:** [GitHub Issues](https://github.com/Grazulex/laravel-chronotrace/issues)

---

## 📝 Next Steps

Now that ChronoTrace is installed:

- **[Basic Usage](Basic-Usage.md)** - Learn the fundamentals
- **[Your First Trace](Your-First-Trace.md)** - Step-by-step walkthrough
- **[Configuration](Configuration.md)** - Detailed configuration options
- **[Commands](Commands.md)** - Complete command reference

---

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