# API Logging & Monitoring

## Logging Architecture

### Dedicated Log Channels
Configured in `config/logging.php`:
- `settlement.log` - Settlement operations (90-day retention)
- `mt5.log` - MT5 sync operations (90-day retention)
- `reconciliation.log` - Reconciliation results (365-day retention)
- `queue.log` - Queue job operations (30-day retention)

### Log Channels Usage

#### Settlement Logging
```php
use App\Services\FinanceLoggingService;

class ProfitSharingService
{
    private FinanceLoggingService $loggingService;

    public function __construct(FinanceLoggingService $loggingService)
    {
        $this->loggingService = $loggingService;
    }

    public function distributeDailyProfit(Carbon $date): ProfitDistribution
    {
        $this->loggingService->logDistributionStart($distributionId, $date);
        
        // ... settlement logic ...
        
        $this->loggingService->logDistributionComplete($distributionId, $summary);
        
        return $distribution;
    }
}
```

#### MT5 Sync Logging
```php
use App\Services\FinanceLoggingService;

class Mt5SyncService
{
    private FinanceLoggingService $loggingService;

    public function syncTrades(array $data): void
    {
        $this->loggingService->logMt5Sync('Sync started', [
            'trades_count' => count($data['trades']),
        ]);
        
        // ... sync logic ...
        
        $this->loggingService->logMt5Sync('Sync completed', [
            'synced_count' => $syncedCount,
        ]);
    }
}
```

#### Reconciliation Logging
```php
use App\Services\FinanceLoggingService;

class ReconciliationService
{
    private FinanceLoggingService $loggingService;

    public function reconcileDistribution(ProfitDistribution $distribution): array
    {
        $result = $this->performReconciliation($distribution);
        
        $this->loggingService->logReconciliation($result);
        
        if (!$result['is_balanced']) {
            $this->loggingService->logReconciliationError('Reconciliation failed', $result);
        }
        
        return $result;
    }
}
```

#### Queue Job Logging
```php
use App\Services\FinanceLoggingService;

class ProcessMt5Sync implements ShouldQueue
{
    private FinanceLoggingService $loggingService;

    public function __construct(FinanceLoggingService $loggingService)
    {
        $this->loggingService = $loggingService;
    }

    public function handle()
    {
        $this->loggingService->logQueueJob('ProcessMt5Sync', 'Job started', [
            'job_id' => $this->job->getJobId(),
        ]);
        
        // ... job logic ...
        
        $this->loggingService->logQueueJob('ProcessMt5Sync', 'Job completed', [
            'job_id' => $this->job->getJobId(),
        ]);
    }

    public function failed(\Throwable $exception)
    {
        $this->loggingService->logQueueJobError('ProcessMt5Sync', $exception->getMessage(), [
            'job_id' => $this->job->getJobId(),
            'trace' => $exception->getTraceAsString(),
        ]);
    }
}
```

## API Request Logging Middleware

### Apply to API Routes
```php
// routes/api.php
Route::middleware(['auth:sanctum', 'api.logging'])->prefix('v1')->group(function () {
    // API routes
});
```

### Register Middleware
```php
// app/Http/Kernel.php
protected $middlewareAliases = [
    'api.logging' => \App\Http\Middleware\ApiRequestLogging::class,
];
```

## Admin Action Logging

### Log All Admin Actions
```php
use Illuminate\Support\Facades\Log;

class AdminInvestorController extends Controller
{
    public function recalculateUnits(Request $request): JsonResponse
    {
        $investorId = $request->investor_id;
        
        Log::channel('queue')->info('Admin action: recalculate units', [
            'admin_id' => auth()->id(),
            'action' => 'recalculate_units',
            'target_investor_id' => $investorId,
            'timestamp' => now()->toISOString(),
        ]);
        
        // ... action logic ...
    }
}
```

## Suspicious Activity Logging

### Detect and Log Suspicious Patterns
```php
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;

class SuspiciousActivityLogger
{
    public function logSuspiciousActivity(string $type, array $context): void
    {
        Log::channel('queue')->warning('Suspicious activity detected', [
            'type' => $type,
            'context' => $context,
            'ip' => request()->ip(),
            'user_id' => auth()->id(),
            'timestamp' => now()->toISOString(),
        ]);
    }

    public function checkRateLimitExceeded(string $key, int $maxAttempts): bool
    {
        $attempts = Cache::get($key, 0);
        
        if ($attempts > $maxAttempts) {
            $this->logSuspiciousActivity('rate_limit_exceeded', [
                'key' => $key,
                'attempts' => $attempts,
                'max_attempts' => $maxAttempts,
            ]);
            return true;
        }
        
        return false;
    }
}
```

## Monitoring Metrics

### Key Metrics to Track
1. **API Response Times** - Average, p50, p95, p99
2. **Error Rates** - 4xx, 5xx errors
3. **Rate Limit Hits** - How often limits are hit
4. **Settlement Success Rate** - Failed vs completed
5. **Queue Job Success Rate** - Failed vs completed
6. **MT5 Sync Success Rate** - Failed vs completed
7. **Reconciliation Failure Rate** - Imbalanced distributions
8. **Concurrent Users** - Active API users
9. **Database Query Performance** - Slow queries
10. **Cache Hit Rate** - Redis cache efficiency

### Monitoring Tools Recommendations
- **Application Monitoring**: New Relic, Datadog, Sentry
- **Log Aggregation**: ELK Stack, Splunk, CloudWatch Logs
- **Infrastructure Monitoring**: Prometheus + Grafana
- **Error Tracking**: Sentry, Bugsnag
- **APM**: Laravel Telescope (development)

## Alerting Strategy

### Critical Alerts (Immediate Notification)
- Settlement failure rate > 5%
- API error rate > 10%
- Database connection failures
- Queue job failures > 20%
- MT5 sync failures > 10%

### Warning Alerts (Within 1 hour)
- Settlement failure rate > 1%
- API error rate > 5%
- Slow API responses (p95 > 2s)
- Queue backlog > 100 jobs
- Reconciliation failures detected

### Info Alerts (Daily Report)
- Daily settlement summary
- API usage statistics
- Error rate trends
- Performance metrics summary

## Log Retention Policy

| Log Type | Retention | Reason |
|----------|-----------|---------|
| settlement.log | 90 days | Audit trail for settlements |
| mt5.log | 90 days | MT5 sync history |
| reconciliation.log | 365 days | Long-term compliance |
| queue.log | 30 days | Queue operation history |
| laravel.log | 14 days | General application logs |

## Log Analysis

### Common Queries

#### Failed Settlements Last 7 Days
```bash
grep "settlement failed" storage/logs/settlement-*.log | tail -n 100
```

#### API Error Rate Last Hour
```bash
grep "status_code.*[45]" storage/logs/queue-*.log | tail -n 100
```

#### Slow API Requests (>1s)
```bash
grep "duration_ms.*1000" storage/logs/queue-*.log | tail -n 50
```

#### MT5 Sync Failures
```bash
grep "MT5 sync error" storage/logs/mt5-*.log | tail -n 50
```

## Performance Logging

### Database Query Logging
```php
// config/database.php
'connections' => [
    'mysql' => [
        // ...
        'slow_log' => true,
        'slow_log_time' => 2.0, // seconds
    ],
],
```

### Slow Query Detection
```php
use Illuminate\Support\Facades\DB;

DB::listen(function ($query) {
    if ($query->time > 1000) {
        Log::channel('queue')->warning('Slow query detected', [
            'sql' => $query->sql,
            'bindings' => $query->bindings,
            'time' => $query->time,
        ]);
    }
});
```

## Security Logging

### Authentication Events
```php
// Log successful logins
Event::listen(\Illuminate\Auth\Events\Login::class, function ($event) {
    Log::channel('queue')->info('User logged in', [
        'user_id' => $event->user->id,
        'ip' => request()->ip(),
        'timestamp' => now()->toISOString(),
    ]);
});

// Log failed logins
Event::listen(\Illuminate\Auth\Events\Failed::class, function ($event) {
    Log::channel('queue')->warning('Login failed', [
        'email' => $event->credentials['email'],
        'ip' => request()->ip(),
        'timestamp' => now()->toISOString(),
    ]);
});
```

### Authorization Failures
```php
Log::channel('queue')->warning('Authorization failed', [
    'user_id' => auth()->id(),
    'route' => request()->route()->getName(),
    'ip' => request()->ip(),
    'timestamp' => now()->toISOString(),
]);
```

## Implementation Checklist

- [ ] Dedicated log channels configured
- [ ] FinanceLoggingService integrated into all services
- [ ] API request logging middleware created
- [ ] Admin action logging implemented
- [ ] Suspicious activity detection implemented
- [ ] Monitoring metrics defined
- [ ] Alerting strategy defined
- [ ] Log retention policy configured
- [ ] Log analysis queries documented
- [ ] Performance logging enabled
- [ ] Security logging implemented
- [ ] Log aggregation service configured (when ready)