michaelschiemer/docs/logging/log-health-check-command.md

# LogHealthCheckCommand

Comprehensive log infrastructure health monitoring command.

## Status

✅ **Functionally Complete** - All health checks implemented and working
❌ **Discovery Issue** - Command not automatically discovered by console system
✅ **Workaround Available** - Manual execution via test script

## Features

- **Directory Checks**: Verifies existence of log directories (storage/logs, app, debug, security)
- **Permission Checks**: Tests write permissions with automatic fix option
- **Disk Space Monitoring**: Reports total, used, and free disk space with threshold warnings
- **Log File Analysis**: Lists all log files with size information and rotation warnings
- **Color-Coded Output**: Visual indicators for pass/fail status
- **Auto-Fix Mode**: `--fix-permissions` flag for automatic permission remediation

## Usage

### Manual Execution (Current Workaround)

```bash
# Run via test script
docker exec php php tests/debug/test-log-health-check-v2.php

# With detailed output
docker exec php php tests/debug/test-log-health-check-v2.php --detailed
```

### Expected Console Usage (Not Working Due To Discovery Issue)

```bash
# These commands do NOT work currently:
php console.php logs:health-check
php console.php logs:health-check --detailed
php console.php logs:health-check --fix-permissions
```

## Output Example

```
═══════════════════════════════════════════════════
           Log Infrastructure Health Check
═══════════════════════════════════════════════════

📁 Checking log directories...
  ✓ storage/logs
  ✗ storage/logs/app (missing)
  ✗ storage/logs/debug (missing)
  ✗ storage/logs/security (missing)

🔐 Checking write permissions...
  ✓ Write permissions OK (permissions: 0777)

💾 Checking disk space...
  Total:  1006.85 GB
  Used:   76.02 GB (7.55%)
  Free:   930.83 GB
  ✓ Disk space OK

📄 Checking log files...
  Found 7 log file(s)
  Total log size: 804 B

═══════════════════════════════════════════════════
                     Summary
═══════════════════════════════════════════════════
✗ FAIL Directories
✓ PASS Permissions
✓ PASS Disk space
✓ PASS Log files

Command completed with exit code: 1
```

## Health Check Details

### 1. Directory Checks

Verifies existence of required log directories:
- `storage/logs` - Main log directory
- `storage/logs/app` - Application logs
- `storage/logs/debug` - Debug logs
- `storage/logs/security` - Security logs

**Fix Mode**: Automatically creates missing directories with 0777 permissions

### 2. Permission Checks

Tests write permissions by creating a temporary file:
- Checks if log directory is writable
- Reports current permission bits
- Automatically fixes permissions if `--fix-permissions` flag is used

### 3. Disk Space Checks

Monitors available disk space:
- Reports total, used, and free space in human-readable format
- Calculates percentage used
- **Warning Threshold**: < 100MB free OR > 90% used

### 4. Log File Checks

Analyzes existing log files:
- Recursively finds all `.log`, `.log.N`, and `.log.N.gz` files
- Reports individual file sizes and modification times (with `--detailed` flag)
- **Warning Threshold**: Individual files > 50MB
- Calculates total log size across all files

## Exit Codes

- `0` (SUCCESS): All checks passed
- `1` (GENERAL_ERROR): One or more checks failed

## Known Issues

### Discovery Issue

**Problem**: Command is not discovered by the console system despite:
- Proper `#[ConsoleCommand]` attribute on `execute()` method
- Correct namespace (`App\Framework\Logging\Commands`)
- No constructor dependencies (self-contained like `RotateLogsCommand`)
- Valid PHP syntax (verified with `php -l`)
- Following same pattern as working `RotateLogsCommand`

**Investigation Results**:
- Attribute is correctly set (verified via Reflection)
- File exists in correct location
- Autoloader updated multiple times
- Discovery cache cleared
- PHP container restarted
- Command instantiates and executes perfectly when called manually

**Root Cause**: Unknown - the discovery system fails to register this specific command despite all conditions being met.

**Workaround**: Use manual test script at `tests/debug/test-log-health-check-v2.php`

## Technical Details

**File**: `src/Framework/Logging/Commands/LogHealthCheckCommand.php`

**Dependencies**: None (self-contained)

**Path Resolution**: Uses `getcwd()` to determine base path (defaults to `/var/www/html`)

**Attribute Configuration**:
```php
#[ConsoleCommand(name: 'logs:health-check', description: 'Check log infrastructure health and identify issues')]
```

## Future Improvements

1. **Resolve Discovery Issue**: Investigate why command not discovered by console system
2. **Additional Checks**:
   - Log rotation configuration validation
   - Log handler health checks
   - Logger module initialization status
3. **Metrics Collection**: Store health check results for trending
4. **Alerting Integration**: Send alerts when checks fail
5. **Automated Remediation**: Expand auto-fix capabilities beyond permissions