Download the PHP package macropage/laravel-scheduler-watcher without Composer
On this page you can find all versions of the php package macropage/laravel-scheduler-watcher. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download macropage/laravel-scheduler-watcher
More information about macropage/laravel-scheduler-watcher
Files in macropage/laravel-scheduler-watcher
Package laravel-scheduler-watcher
Short Description logs artisan commands run via scheduler to mysql with plenty of infos, prevent running command again in case of error, allows full monitoing of artisan commands
License MIT
Homepage https://github.com/macropage/laravel-scheduler-watcher
Informations about the package laravel-scheduler-watcher
Monitor your laravel crons like a pro
Log your scheduled commands with start, end, duration, exitcode and output in a seperate database.
Share a custom Mutex between Scheduler and Artisan-Command to identify each call with all parameters and options.
This package is made for php 8.x and Laravel 9
If you are working with something older, feel free to fork this project.
Why?
Because you should!
Laravel offers some nice hooks like onFailure but I am totally missing a solution to catch
all important informations of the job-execution itself, like start, stop, duration and exitcode.
My personal goal is to monitor jobs with the following criteria:
- notify me if a job did not run in the last X days/hours/minutes
- notify me if a job ended with exitcode>0
- notify me if a jobs duration takes much longer as it should
- monitor something from a central point even in distributed environments
- monitor individual jobs with my good old nagios (yeah, don´t blame me)
- confirm failed jobs via web
/scheduler-watcher
Installation
You can install the package via composer:
Publish config & migration using php artisan vendor:publish --provider="macropage\LaravelSchedulerWatcher\LaravelSchedulerWatcherServiceProvider"
Set mysql_connection
in: app/config/scheduler-watcher.php
In case you want a specific table prefix, because you already have a table named "jobs", you can add one in the config.
Create mysql tables: php artisan migrate
Usage
Write your cron-jobs as usal, but use the "description" to control your logging:
- log
- nooutput
- force
Example 1:
Nothing happens, no logging, laravel default... (i hope so)
Example 2:
Command gets logged into DB, but doesn´t run again, if last exitcode>0
Example 3:
Command gets logged, but without output. You can use this to keep the logging-DB small.
Example 4:
The switch "force" lets run your command, ignoring last exitcode. be careful: this can spam your DB.
Personally I would use "force" only with "nooutput".
Kernel.php
To use the logging, you have to include the Trait LaravelSchedulerWatcher
into your app\Console\Kernel.php
Inside the schedule
function, call the monitor. This is the place where all the magic happens ;)
inside your artisan-command
The Scheduler needs to be able to get the CustomMutex
generated from your Artisan-Command.
Because I don´t know (for now) how the Scheduler can talk directly to an Artisan-Command,
you have to make some very little modifications there, too.
The things you have to do here:
use LaravelSchedulerCustomMutex;
- set your
Signature
with the helpersetSignature
instead directly (because --mutex gets added automatically) - inside
handle
add thecheckCustomMutex
with that, you are good to start.
Logging to File
The last Output-File (the file that captured the output of your job) will be written to /tmp/<mutex>.scheduler.output.log
.
<mutex>
= the custom mutex generated based on your command + all arguments and parameters.
The last output-logfile does not get deleted, this is intentional.
I thought it´s a good idea so you always have quick access to the last output for debugging without looking into the DB.
Mutex
In case you never heard "mutex", you might want to read this.
The <mutex>
is not the same Mutex laravel uses for handling withoutOverlapping
.
withoutOverlapping
is still handled by laravel itself. The custom Mutex of this package is only used to identify your commands
with a simple md5-hash.
The Mutex does NOT contain the crontab info * * * * 5
itself, because from my point of view,
it´s not important "when" something is running, it´s more important "what" is running. And for this, you need to know the
command itself, the arguments and options. Check the function getCustomMutex
in case it´s not clear ;)
Helper Artisan Commands
scheduler-watcher:info
There are currently two helper command:
artisan scheduler-watcher:info <mutex> --last-output
Example: artisan scheduler-watcher:info 4a1a273959acfc335fb3fd01a069bec9 --last-output
This helper gives you a quick overview of the last events and, if you want, the last output of the last run:
hint: job_md5
is my custome-mutex i am talking all along ;)
scheduler-watcher:checklastevent
artisan scheduler-watcher:checklastevent <mutex>
Example: artisan scheduler-watcher:checklastevent 4a1a273959acfc335fb3fd01a069bec9
This Helper only returns the last output of the last run of your job and exits with the same exitcode of this last run:
With that you are able to build checks for your monitoring system, for instance Nagios.
Of course you can use the data directly from the DB, this is just something I created for myself ;)
scheduler-watcher:cleanup
artisan scheduler-watcher:cleanup <mutex> --keep <int>
Example: artisan scheduler-watcher:cleanup 4a1a273959acfc335fb3fd01a069bec9 --keep 20
This Command deletes all job_event entries of your job from table job_events
except tha last 20 newest
scheduler-watcher:cleanup-all
artisan scheduler-watcher:cleanup-all --keep <int>
Example: artisan scheduler-watcher:cleanup --keep 20
This Command deletes all job_event entries of ALL your jobs from table job_events
except tha last 20 newest of each job
FAQ
is there any webinterface?
a new route gets published /scheduler-watcher
which only gives you an overview of failed jobs
and the opportunity to confirm a failed job so it is able to run again - very simple.
in other words, you are to update job_events set jobe_exitcode=0 WHERE jobe_id=?
via web,
very useful if you are on the go.
are notifications included in this package?
no, it´s up to you what you do with your logging.
there are some helper artisan commands, that give you an idea, how you
can build your own rules to notify you in case something is not as you expect it to be.
can i monitor none artisan jobs, too?
yes, but currently there is no option to stop logging in case the last run failed, this is on my todo.
when calling artisan commands: can i choose to not run the command, if last run failed?
yes, the last exitcode gets fetched from DB, if you want, that is optional.
can i use a seperate database to log my cron?
of course.
can i use a different database than mysql?
not yet tested, let me know.
i don´t get it: why use a custom mutex and not the same like laravel internally uses?
1) in case i am not wrong here: the mutex only exists in context of the scheduler.
if you want to work with the logging-db within an artisan-command that is not called by the scheduler, you don´t have any mutex.
so you need to know the job_md5
and there for you can call getCustomMutex
within your artisan-command.
with that every artisan command is able to check itself, for instance show last duration, last exitcode, whatever you want.
2) laravel does 'framework'.DIRECTORY_SEPARATOR.'schedule-'.sha1($this->expression.$this->command);
and I don´t want
$this->expresseion
(example: * 0 * * 5
) part of this mutex. In case I am wrong and it makes sense because someone
wants to identify two identical jobs running at different times, we can change this, I am open to that ;)
how exactly do i montior my jobs now?
use the table job_events
. with the information there, you can write your own selects to check:
- last time the job has been executed (jobe_start)
- last time the job has been executed successfully (jobe_start + jobe_exitcode)
- how long did the job take (jobe_duration)
if any of these informations do not fit into your personal range, send yourself a notification, that´s it.
last exitcode was > 0 and i don´t want to use "force", how do i keep my jobs running after a problem has been solved?
yeah, good question. because there is currently no pid-file involved and the database is used to check if the "last run"
was okay or not, you are forced to set the exitcode (jobe_exitcode) of your last run to "0". i know, it´s not perfect
changing log-entries afterwards, but nothing is forever. you should clean your database anyway after a while.
if you prefer having log-informations on a long term, i suggest to add new table job_events_archiv
and a trigger
that duplicates all entries. with that you don´t loose performance with the active table job_events
and you are
able to collect data for a long time, for instance you want to check the duration of your jobs over months.
i am using [log] but there is no entry in table 'job_events'
you will see entries in job_events
and job_event_outputs
ONLY if your job
generates any output at all. if your job does "nothing" because of some conditions,
make sure you do at least something like: $this->info('nothing todo....');
how do i keep my tables clean and prevent them from growing till i run out of space?
check tha artisan commands cleanup
and cleanup-all
the output of php artisan schedule:run
shows me the error: The "--mutex" option does not exist.
inside your artisan command, you didn´t use the trait LaravelSchedulerCustomMutex
, please read the
section inside your artisan-command in this document.
More Documentation
Contributing
Help is appreciated :-)
You need help?
yes, you can hire me!
Credits
License
The MIT License (MIT). Please see License File for more information.
Laravel Package Boilerplate
This package was generated using the Laravel Package Boilerplate.
All versions of laravel-scheduler-watcher with dependencies
macropage/php-to-ascii-table Version dev-master
codedungeon/php-cli-colors Version ^1.0
macropage/ansi-to-html Version dev-master