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.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

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:

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:

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:

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:

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

gitbook

Contributing

Help is appreciated :-)

You need help?

yes, you can hire me!

xing linkedin twitter

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

PHP Build Version
Package Version
Requires php Version ^8.1 || ^8.2 || ^8.3
macropage/php-to-ascii-table Version dev-master
codedungeon/php-cli-colors Version ^1.0
macropage/ansi-to-html Version dev-master
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package macropage/laravel-scheduler-watcher contains the following files

Loading the files please wait ....