smitmartijn / laravel-schedule-monitor
Monitor Laravel scheduled jobs with heartbeats
Requires
- php: ^8.0
- guzzlehttp/guzzle: ^7.0
- illuminate/console: ^8.0|^9.0|^10.0
- illuminate/events: ^8.0|^9.0|^10.0
- illuminate/support: ^8.0|^9.0|^10.0
README
Monitor your Laravel scheduled tasks with automatic heartbeats and receive alerts when jobs fail to run.
Disclaimer: I built this for WhatPulse, and don't intend on productizing it beyond my use cases. PRs are welcome, though!
Installation
You can install the package via composer:
composer require smitmartijn/laravel-schedule-monitor
After installing the package, publish the configuration file:
php artisan vendor:publish --provider="Smitmartijn\ScheduleMonitor\ScheduleMonitorServiceProvider" --tag="config"
Configuration
After publishing the configuration file, you'll find it at config/schedule-monitor.php
. You'll need to set these environment variables in your .env
file:
SCHEDULE_MONITOR_API_URL=https://your-monitor-app.pages.dev
SCHEDULE_MONITOR_API_TOKEN=your-api-token
Make sure the API token matches the one you set in your monitoring application.
Usage
Syncing Your Scheduled Tasks
Before the monitoring can begin, you need to sync your scheduled tasks with the monitoring application. Run the following command:
php artisan schedule:monitor:sync
This will scan all your scheduled tasks and send them to the monitoring application. It's recommended to run this command in your deployment process so that any changes to your scheduled tasks are automatically synced.
Testing Heartbeats
You can send a test heartbeat for a job to verify the monitoring connection is working properly:
php artisan schedule:monitor:test-heartbeat "php artisan your:command"
This will send a test heartbeat for the specified job. The job name should match exactly what appears in the monitoring app after running the sync command.
Options:
--status=success|failure
- Set the job status (default: success)--runtime=0.5
- Set a custom runtime in seconds (default: 0.1)
Example:
# Test a job with failure status php artisan schedule:monitor:test-heartbeat "php artisan emails:send" --status=failure
Customizing Monitoring
By default, all scheduled tasks will be monitored. If you want to exclude specific tasks from monitoring, you can use the withoutMonitoring
method in your scheduler:
// In app/Console/Kernel.php protected function schedule(Schedule $schedule) { // This job will be monitored $schedule->command('emails:send')->daily(); // This job will NOT be monitored $schedule->command('horizon:snapshot') ->everyFiveMinutes() ->withoutMonitoring(); }
Setting Custom Grace Periods
You can set a custom grace period for individual tasks using the graceMinutes
method:
$schedule->command('import:data') ->daily() ->graceMinutes(60); // Allow up to 60 minutes delay before marking as missed
If not specified, the default grace period from the configuration will be used.
How It Works
- When you run the
schedule:monitor:sync
command, all eligible scheduled tasks are sent to the monitoring application. - When a task finishes running, the package automatically sends a heartbeat to the monitoring application.
- The monitoring application checks if tasks are running on schedule and raises alerts when they miss their expected run time.
Monitoring Multiple Applications
You can use the same monitoring application for multiple Laravel applications. Each application will need its own API token, and its jobs will be tracked separately.
Troubleshooting
Heartbeats Not Being Sent
Make sure:
- The Laravel application can reach the monitoring API URL
- The API tokens match on both sides
- The scheduled task isn't excluded by the ignore patterns in the config
Check Connectivity
You can test the connection to the monitoring service by running:
php artisan schedule:monitor:sync
If this command completes successfully, the connection is working.
Security
If you discover any security issues, please use the issue tracker.
License
The MIT License (MIT). Please see License File for more information.