Monitor scheduled tasks in a Laravel app
This package will monitor your Laravel schedule. It will write an entry to a log table in the db each time a schedule tasks starts, end, fails or is skipped. Using the list command you can check when the scheduled tasks have been executed.
This package can also sync your schedule with Oh Dear. Oh Dear will send you a notification whenever a scheduled task doesn't run on time or fails.
Support us
We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.
Installation
You can install the package via composer:
composer require spatie/laravel-schedule-monitorIf you need Laravel 8 support, you can install v2 of the package using composer require spatie/laravel-schedule-monitor:^2.
Preparing the database
You must publish and run migrations:
php artisan vendor:publish --provider="Spatie\ScheduleMonitor\ScheduleMonitorServiceProvider" --tag="schedule-monitor-migrations"
php artisan migratePublishing the config file
You can publish the config file with:
php artisan vendor:publish --provider="Spatie\ScheduleMonitor\ScheduleMonitorServiceProvider" --tag="schedule-monitor-config"This is the contents of the published config file:
return [
/*
* The schedule monitor will log each start, finish and failure of all scheduled jobs.
* After a while the `monitored_scheduled_task_log_items` might become big.
* Here you can specify the amount of days log items should be kept.
*
* Use Laravel's pruning command to delete old `MonitoredScheduledTaskLogItem` models.
* More info: https://laravel.com/docs/9.x/eloquent#mass-assignment
*/
'delete_log_items_older_than_days' => 30,
/*
* The date format used for all dates displayed on the output of commands
* provided by this package.
*/
'date_format' => 'Y-m-d H:i:s',
'models' => [
/*
* The model you want to use as a MonitoredScheduledTask model needs to extend the
* `Spatie\ScheduleMonitor\Models\MonitoredScheduledTask` Model.
*/
'monitored_scheduled_task' => Spatie\ScheduleMonitor\Models\MonitoredScheduledTask::class,
/*
* The model you want to use as a MonitoredScheduledTaskLogItem model needs to extend the
* `Spatie\ScheduleMonitor\Models\MonitoredScheduledTaskLogItem` Model.
*/
'monitored_scheduled_log_item' => Spatie\ScheduleMonitor\Models\MonitoredScheduledTaskLogItem::class,
],
/*
* Oh Dear can notify you via Mail, Slack, SMS, web hooks, ... when a
* scheduled task does not run on time.
*
* More info: https://ohdear.app/cron-checks
*/
'oh_dear' => [
/*
* You can generate an API token at the Oh Dear user settings screen
*
* https://ohdear.app/user/api-tokens
*/
'api_token' => env('OH_DEAR_API_TOKEN', ''),
/*
* The id of the site you want to sync the schedule with.
*
* You'll find this id on the settings page of a site at Oh Dear.
*/
'site_id' => env('OH_DEAR_SITE_ID'),
/*
* To keep scheduled jobs as short as possible, Oh Dear will be pinged
* via a queued job. Here you can specify the name of the queue you wish to use.
*/
'queue' => env('OH_DEAR_QUEUE'),
/*
* `PingOhDearJob`s will automatically be skipped if they've been queued for
* longer than the time configured here.
*/
'retry_job_for_minutes' => 10,
],
];Cleaning the database
The schedule monitor will log each start, finish and failure of all scheduled jobs. After a while the monitored_scheduled_task_log_items might become big.
Use Laravel's model pruning feature , you can delete old MonitoredScheduledTaskLogItem models. Models older than the amount of days configured in the delete_log_items_older_than_days in the schedule-monitor config file, will be deleted.
// app/Console/Kernel.php
use Spatie\ScheduleMonitor\Models\MonitoredScheduledTaskLogItem;
class Kernel extends ConsoleKernel
{
protected function schedule(Schedule $schedule)
{
$schedule->command('model:prune', ['--model' => MonitoredScheduledTaskLogItem::class])->daily();
}
}Syncing the schedule
Every time you deploy your application, you should execute the schedule-monitor:sync command
schedule-monitor:syncThis command is responsible for syncing your schedule with the database, and optionally Oh Dear. We highly recommend adding this command to the script that deploys your production environment.
In a non-production environment you should manually run schedule-monitor:sync. You can verify if everything synced correctly using schedule-monitor:list.
Usage
To monitor your schedule you should first run schedule-monitor:sync. This command will take a look at your schedule and create an entry for each task in the monitored_scheduled_tasks table.
To view all monitored scheduled tasks, you can run schedule-monitor:list. This command will list all monitored scheduled tasks. It will show you when a scheduled task has last started, finished, or failed.
The package will write an entry to the monitored_scheduled_task_log_items table in the db each time a schedule tasks starts, end, fails or is skipped. Take a look at the contest of that table if you want to know when and how scheduled tasks did execute. The log items also hold other interesting metrics like memory usage, execution time, and more.
Naming tasks
Schedule monitor will try to automatically determine a name for a scheduled task. For commands this is the command name, for anonymous jobs the class name of the first argument will be used. For some tasks, like scheduled closures, a name cannot be determined automatically.
To manually set a name of the scheduled task, you can tack on monitorName().
Here's an example.
// in app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
$schedule->command('your-command')->daily()->monitorName('a-custom-name');
$schedule->call(fn () => 1 + 1)->hourly()->monitorName('addition-closure');
}When you change the name of task, the schedule monitor will remove all log items of the monitor with the old name, and create a new monitor using the new name of the task.
Setting a grace time
When the package detects that the last run of a scheduled task did not run in time, the schedule-monitor list will display that task using a red background color. In this screenshot the task named your-command ran too late.
The package will determine that a task ran too late if it was not finished at the time it was supposed to run + the grace time. You can think of the grace time as the number of minutes that a task under normal circumstances needs to finish. By default, the package grants a grace time of 5 minutes to each task.
You can customize the grace time by using the graceTimeInMinutes method on a task. In this example a grace time of 10 minutes is used for the your-command task.
// in app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
$schedule->command('your-command')->daily()->graceTimeInMinutes(10);
}Ignoring scheduled tasks
You can avoid a scheduled task being monitored by tacking on doNotMonitor when scheduling the task.
// in app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
$schedule->command('your-command')->daily()->doNotMonitor();
}Storing output in the database
You can store the output by tacking on storeOutputInDb when scheduling the task.
// in app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
$schedule->command('your-command')->daily()->storeOutputInDb();
}The output will be stored in the monitored_scheduled_task_log_items table, in the output key of the meta column.
Multitenancy
If you're using spatie/laravel-multitenancy you should add the PingOhDearJob to
the not_tenant_aware_jobs array in config/multitenancy.php.
'not_tenant_aware_jobs' => [
// ...
\Spatie\ScheduleMonitor\Jobs\PingOhDearJob::class,
]Without it, the PingOhDearJob will fail as no tenant will be set.
Getting notified when a scheduled task doesn't finish in time
This package can sync your schedule with the Oh Dear cron check. Oh Dear will send you a notification whenever a scheduled task does not finish on time.
To get started you will first need to install the Oh Dear SDK.
composer require ohdearapp/ohdear-php-sdkNext you, need to make sure the api_token and site_id keys of the schedule-monitor are filled with an API token, and an Oh Dear site id. To verify that these values hold correct values you can run this command.
php artisan schedule-monitor:verify
To sync your schedule with Oh Dear run this command:
php artisan schedule-monitor:sync
After that, the list command should show that all the scheduled tasks in your app are registered on Oh Dear.
To keep scheduled jobs as short as possible, Oh Dear will be pinged via queued jobs. To ensure speedy delivery to Oh Dear, and to avoid false positive notifications, we highly recommend creating a dedicated queue for these jobs. You can put the name of that queue in the queue key of the config file.
Oh Dear will wait for the completion of a schedule tasks for a given amount of minutes. This is called the grace time. By default, all scheduled tasks will have a grace time of 5 minutes. To customize this value, you can tack on graceTimeInMinutes to your scheduled tasks.
Here's an example where Oh Dear will send a notification if the task didn't finish by 00:10.
// in app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
$schedule->command('your-command')->daily()->graceTimeInMinutes(10);
}Unsupported methods
Currently, this package does not work for tasks that use these methods:
betweenunlessBetweenwhenskip
Third party scheduled task monitors
We assume that, when your scheduled tasks do not run properly, a scheduled task that sends out notifications would probably not run either. That's why this package doesn't send out notifications by itself.
These services can notify you when scheduled tasks do not run properly:
Testing
composer testChangelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security
If you've found a bug regarding security please mail [email protected] instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.