Laravel Schedule Monitor Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-schedule-monitor
   php artisan vendor:publish --provider="Spatie\ScheduleMonitor\ScheduleMonitorServiceProvider" --tag="schedule-monitor-migrations"
   php artisan migrate
   

2. First Sync:

   php artisan schedule-monitor:sync
   

3. Verify Sync:

   php artisan schedule-monitor:list
   

First Use Case

Monitor a critical scheduled job (e.g., a nightly report) to ensure it runs reliably:

// app/Console/Kernel.php
protected function schedule(Schedule $schedule) {
    $schedule->command('generate:nightly-report')
             ->dailyAt('23:00')
             ->monitorName('Nightly Report')
             ->graceTimeInMinutes(10);
}

Run php artisan schedule-monitor:list to check execution status.

Implementation Patterns

Core Workflows

1. Task Monitoring:

   • Automatically logs starts, finishes, failures, and skips for all scheduled tasks.
   • Use monitorName() to override default naming (e.g., closures or ambiguous tasks).

2. Grace Time Management:

   • Set per-task grace periods (default: 5 minutes) to account for expected execution time:

     $schedule->command('long-running-job')->hourly()->graceTimeInMinutes(30);
     

3. Output Storage:

   • Capture command output in the database for debugging:

     $schedule->command('backup:database')->daily()->storeOutputInDb();
     

4. Oh Dear Integration:

   • Sync with Oh Dear for external alerts:

     php artisan schedule-monitor:sync --keep-old  # Non-destructive sync
     

   • Configure in .env:

     OH_DEAR_API_TOKEN=your_token
     OH_DEAR_MONITOR_ID=123
     

5. Database Maintenance:

   • Prune old logs daily (configurable retention in schedule-monitor.php):

     // app/Console/Kernel.php
     $schedule->command('model:prune', [
         '--model' => \Spatie\ScheduleMonitor\Models\MonitoredScheduledTaskLogItem::class
     ])->daily();
     

Integration Tips

• Deployments: Run schedule-monitor:sync in your deployment script to ensure Oh Dear stays in sync.
• Multitenancy: Add PingOhDearJob to not_tenant_aware_jobs in config/multitenancy.php.
• Custom Queues: Use a dedicated queue for PingOhDearJob to avoid delays:

  'oh_dear' => [
      'queue' => 'oh-dear-pings',
  ]
  

Gotchas and Tips

Pitfalls

1. Name Changes:

   • Renaming a task (e.g., monitorName()) deletes all historical logs for the old name. Use cautiously in production.

2. Oh Dear Sync Issues:

   • Destructive Syncs: The default schedule-monitor:sync removes all non-Laravel cron jobs from Oh Dear. Use --keep-old to preserve external monitors.
   • Queue Delays: If PingOhDearJob is stuck, check the oh-dear queue and adjust retry_job_for_minutes in config.

3. Grace Time Misconfiguration:

   • Too short → False positives for slow but normal tasks.
   • Too long → Missed alerts for genuinely failing jobs.

4. Output Storage Overhead:

   • Storing command output (storeOutputInDb) can bloat the meta column. Use sparingly for verbose commands.

Debugging

• Failed Pings: Enable debug logging:

  OH_DEAR_DEBUG_LOGGING=true
  

  Check logs for cURL timing, connection details, and response data.

• Missing Logs:

  • Verify the schedule:run command is in your server’s cron (default: * * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1).
  • Ensure tasks aren’t marked doNotMonitor().

• Oh Dear Verification:

  php artisan schedule-monitor:verify
  

  Fix any missing api_token or monitor_id errors.

Extension Points

1. Custom Models:

   • Extend MonitoredScheduledTask or MonitoredScheduledTaskLogItem to add fields (e.g., tenant_id for multitenancy).

2. Log Pruning:

   • Override the pruning logic in app/Console/Kernel.php for custom retention rules.

3. Alert Customization:

   • Subclass PingOhDearJob to modify payloads or add metadata (e.g., environment tags).

4. UI Integration:

   • Query MonitoredScheduledTaskLogItem directly for custom dashboards:

     $recentFailures = MonitoredScheduledTaskLogItem::where('type', 'failed')
         ->orderBy('created_at', 'desc')
         ->limit(10)
         ->get();