Laravel Log Cleaner Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Lightweight & Focused: Addresses a single, well-defined use case (log management) without introducing unnecessary complexity.
  • Laravel-Native: Leverages Laravel’s Artisan command system, service providers, and event dispatching, ensuring seamless integration with the framework’s ecosystem.
  • Configurable: Published config file allows customization of defaults (e.g., retention days, backup behavior) without modifying core logic.
  • Event-Driven: Dispatches events (LogCleaning, LogCleaned, LogFileCleaned) for extensibility (e.g., logging, notifications, or auditing).
  • Memory-Efficient: Supports large-file processing via --memory-efficient flag and configurable thresholds.
  • Safety-First: Includes dry-run mode, backups, file locking, and disk-space validation to mitigate risks.

• Cons:

  • Limited Scope: Only targets Laravel’s default log files (e.g., laravel.log). Custom log handlers (e.g., Monolog, Syslog) or external log storage (e.g., ELK, S3) are out of scope.
  • No Retention Policy Enforcement: Requires manual invocation (e.g., via cron) for automated log rotation; lacks built-in scheduling.
  • Dependency on File System: Relies on direct file operations, which may introduce race conditions or permission issues in shared environments.

Integration Feasibility

• High: Designed for Laravel 9–13 with minimal prerequisites (PHP 8.2+). Composer installation and service provider registration are standard Laravel patterns.
• Compatibility:
  • Laravel Core: No conflicts with Laravel’s logging system (uses storage/logs/ by default).
  • Third-Party Loggers: Neutral; does not interfere with Monolog or custom log handlers unless they override storage/logs/ paths.
  • CI/CD: Safe for deployment pipelines (dry-run mode for testing).
• Customization:
  • Facade/API: Programmatic usage (LogCleaner::clear()) enables integration into custom scripts or middleware.
  • Events: Extensible for auditing or triggering downstream actions (e.g., Slack alerts).

Technical Risk

• Low to Medium:
  • File Locking: Risk of deadlocks if multiple processes invoke the command simultaneously (mitigated by --no-lock flag).
  • Permission Issues: Requires write access to storage/logs/ (standard Laravel requirement).
  • Backup Bloat: Unchecked backup retention could fill disk space (configurable via max_backups).
  • Performance: Large log files may impact memory (addressed by --memory-efficient).
• Mitigations:
  • Use --dry-run in CI/CD to validate operations.
  • Schedule backups during low-traffic periods.
  • Monitor disk space post-deployment.

Key Questions

1. Log Storage Location:
   • Are logs stored in non-standard locations (e.g., S3, database)? If so, this package may need extension or replacement.
2. Automation Needs:
   • Should log rotation be automated (e.g., via cron)? If yes, how will this package fit into the existing schedule?
3. Compliance/Auditing:
   • Are there regulatory requirements for log retention? If so, does this package’s backup/compression align with policies?
4. Multi-Environment:
   • Will configuration differ across dev/staging/prod? If yes, how will config publishing be managed?
5. Monitoring:
   • Should log-cleaning operations be monitored (e.g., via events or metrics)? If yes, how will events be consumed?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Artisan Commands: Native integration with Laravel’s CLI tools.
  • Service Provider: Registers commands and events without manual bootstrapping.
  • Events: Leverages Laravel’s event system for extensibility.
• PHP/PHPStan:
  • PHP 8.2+ required (type safety, attributes).
  • PHPStan level 8 ensures code quality (recommended for new projects).
• Testing:
  • Pest framework for unit/feature tests (compatible with Laravel’s testing stack).

Migration Path

1. Assessment Phase:
   • Audit current log management (location, rotation, retention).
   • Validate compatibility with Laravel version and PHP environment.
2. Pilot Deployment:
   • Install in a staging environment:

     composer require jiordiviera/laravel-log-cleaner
     php artisan vendor:publish --provider="JiordiViera\LaravelLogCleaner\LaravelLogCleanerServiceProvider" --tag="log-cleaner-config"
     

   • Test with --dry-run and adjust config as needed.
3. Gradual Rollout:
   • Replace manual log-cleaning scripts with php artisan log:clear.
   • For automated rotation, integrate with cron or Laravel’s task scheduler:

     // app/Console/Kernel.php
     protected function schedule(Schedule $schedule)
     {
         $schedule->command('log:clear --days=30 --backup')
                  ->dailyAt('2:00');
     }
     

4. Extension (if needed):
   • Extend the package to support custom log paths or handlers via events or facade overrides.

Compatibility

• Laravel Versions: 9–13 (tested; no breaking changes expected).
• PHP Versions: 8.2+ (required for attributes and type safety).
• Dependencies:
  • No external services (self-contained).
  • Uses Laravel’s filesystem and events (no conflicts).
• Edge Cases:
  • Custom Log Handlers: If logs are written to non-standard paths, extend the package or use the facade to target specific files.
  • Windows Paths: Test file locking and path handling on Windows (Laravel’s filesystem is cross-platform).

Sequencing

1. Pre-Installation:
   • Backup existing logs manually.
   • Review config/log-cleaner.php for default values.
2. Installation:
   • Composer install + config publish.
3. Testing:
   • Run php artisan log:clear --dry-run to validate.
   • Test edge cases (empty logs, large files, permission errors).
4. Production Rollout:
   • Schedule automated runs (cron/scheduler).
   • Monitor disk space and log events.
5. Post-Launch:
   • Review backup retention and adjust max_backups.
   • Consider adding event listeners for auditing.

Operational Impact

Maintenance

• Pros:
  • Minimal Overhead: Single Artisan command replaces manual scripts.
  • Centralized Config: All settings in config/log-cleaner.php (no scattered logic).
  • Event-Driven: Extensible for logging or alerts without modifying core code.
• Cons:
  • Configuration Drift: Custom configs may diverge across environments if not version-controlled.
  • Dependency Updates: Requires monitoring for breaking changes in Laravel/PHP (though this package is stable).

Support

• Troubleshooting:
  • Common Issues:
    • Permission errors: Verify storage/logs/ permissions (chmod -R 775 storage/logs/).
    • File locking: Use --no-lock for scripted operations or adjust locking.timeout.
    • Disk space: Monitor min_free_disk_space_mb and backup retention.
  • Debugging:
    • Enable verbose output with --verbose.
    • Check events for detailed logs (LogCleaning, LogCleaned).
• Documentation:
  • Comprehensive README with examples and config options.
  • Events and exceptions are well-documented for customization.

Scaling

• Performance:
  • Large Logs: Use --memory-efficient for files >50MB (configurable via memory_threshold).
  • Concurrency: File locking prevents race conditions (disable with --no-lock if needed).
  • Backup Impact: Compression reduces storage overhead (--compress).
• Horizontal Scaling:
  • Stateless operations (no shared state beyond file locks).
  • Safe for multi-server deployments (each instance manages its own logs).
• Resource Usage:
  • Memory: Linear with log size (mitigated by --memory-efficient).
  • CPU: Compression adds overhead (adjust compression.level).

Failure Modes