Laravel Disk Monitor Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-disk-monitor
   

   Publish the config file:

   php artisan vendor:publish --provider="Spatie\DiskMonitor\DiskMonitorServiceProvider"
   

2. Configuration: Edit config/disk-monitor.php to specify which disks to monitor (e.g., local, s3). Defaults to monitoring all configured disks in config/filesystems.php.

3. First Use Case: Run the monitor command to fetch disk metrics:

   php artisan disk:monitor
   

   Outputs a JSON array with disk names and their file counts (e.g., {"local": 1234, "s3": 5678}).

4. Viewing Results: Metrics are stored in storage/disk-monitor.json by default. Access via:

   $metrics = Spatie\DiskMonitor\Facades\DiskMonitor::getMetrics();
   

Implementation Patterns

Workflows

1. Scheduled Monitoring: Add a cron job to app/Console/Kernel.php:

   protected function schedule(Schedule $schedule)
   {
       $schedule->command('disk:monitor')->hourly();
   }
   

   Logs metrics to storage/disk-monitor.json automatically.

2. Custom Metrics: Extend the Spatie\DiskMonitor\DiskMonitor class to track additional metrics (e.g., disk space):

   use Spatie\DiskMonitor\DiskMonitor as BaseMonitor;
   
   class CustomDiskMonitor extends BaseMonitor
   {
       public function getMetrics()
       {
           $metrics = parent::getMetrics();
           foreach ($metrics as $disk => $files) {
               $metrics[$disk]['free_space'] = Storage::disk($disk)->freeSpace();
           }
           return $metrics;
       }
   }
   

   Bind the custom class in AppServiceProvider:

   $this->app->bind('disk-monitor', function () {
       return new CustomDiskMonitor();
   });
   

3. Integration with Monitoring Tools: Push metrics to external services (e.g., Datadog, Prometheus) by hooking into the disk.monitored event:

   // In AppServiceProvider
   DiskMonitor::monitored(function ($metrics) {
       // Send to external service
   });
   

4. Conditional Monitoring: Dynamically enable/disable monitoring for specific disks:

   DiskMonitor::monitor(['local', 's3']); // Only monitor these disks
   

API Usage

• Fetch Metrics:

  $metrics = DiskMonitor::getMetrics(); // Returns array of disk names => file counts
  

• Clear Stored Metrics:

  DiskMonitor::clearMetrics(); // Deletes storage/disk-monitor.json
  

Gotchas and Tips

Pitfalls

1. Performance on Large Disks:

   • Monitoring disks with millions of files may be slow. Use ->withoutVisibility() to exclude hidden files or filter by extension:

     DiskMonitor::monitor(['local'], function ($disk) {
         return $disk->files()->where(function ($file) {
             return str_ends_with($file->path(), '.log');
         });
     });
     

2. Concurrency Issues:

   • Avoid running disk:monitor concurrently in production (e.g., via multiple cron jobs). Use a lock (e.g., laravel-shift/lock) if needed.

3. Filesystem Permissions:

   • Ensure the Laravel storage directory (storage/) is writable for the web server user. Errors may occur if storage/disk-monitor.json can’t be written.

4. Outdated Metrics:

   • Metrics are static until refreshed. For real-time data, cache the results with a short TTL (e.g., 5 minutes) or use the monitored event to push updates dynamically.

Debugging

• Log Errors: Enable debug mode in config/disk-monitor.php to log issues:

  'debug' => env('DISK_MONITOR_DEBUG', false),
  

  Check storage/logs/laravel.log for errors during monitoring.

• Verify Disk Configuration: Ensure disks in config/filesystems.php are correctly configured. Test connectivity manually:

  Storage::disk('s3')->exists('test.txt'); // Should return false (file doesn’t exist, but tests connection)
  

Tips

1. Exclude Directories: Skip monitoring specific directories (e.g., node_modules):

   DiskMonitor::monitor(['local'], function ($disk) {
       return $disk->files()->reject(function ($file) {
           return str_contains($file->path(), 'node_modules');
       });
   });
   

2. Human-Readable Output: Format metrics for CLI output:

   $metrics = DiskMonitor::getMetrics();
   foreach ($metrics as $disk => $count) {
       echo "Disk {$disk}: {$count} files\n";
   }
   

3. Testing: Mock the monitor in tests:

   $monitor = Mockery::mock(Spatie\DiskMonitor\DiskMonitor::class);
   $monitor->shouldReceive('getMetrics')->andReturn(['local' => 100]);
   $this->app->instance(Spatie\DiskMonitor\DiskMonitor::class, $monitor);
   

4. Custom Storage Path: Change the storage path in config/disk-monitor.php:

   'storage_path' => storage_path('app/disk-metrics.json'),
   

5. Laravel 8+ Optimization: Use Laravel’s FilesystemManager directly for better performance if extending:

   $filesystem = app(\Illuminate\Contracts\Filesystem\Filesystem::class);
   $count = $filesystem->disk('local')->count();