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)

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

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

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