Package: sch2
SmartCronHelperA cron shell wrapper for registering and updating cron jobs automatically inhealthchecksor yourown hosted copy of Healthchecks.WARNING: once setup and configured, the code in this package runs as user specified in the cron jobs and is wrapped around the cron job commands. Errors in this package could prevent your cron jobs from being executed.InstallationInstall sch system wide with pip$sudopip3installsch2Aschcli should now be available:$whichsch/usr/local/bin/schsch --versionshould return something like:sch, version 0.0.2Command line usageSee the--helpoption for usage:Usage: sch [OPTIONS] COMMAND [ARGS]...sch - A cron shell wrapper for registering and updating cron jobsautomatically in Healthchecks. The Healthchecks project api_url andapi_key should be configured in ~/.sch.conf.Options:--version                 Show the version and exit.-c, --shell_command TEXT  Command to execute. This how Cron executes 'sch'when it is set as SHELL.--help                    Show this message and exit.Commands:list  List checks for the configured Healthchecks project.listcommandUsage: sch list [OPTIONS]List checks for the configured Healthchecks project.Options:-l, --localhost / -a, --all     List checks that originate from this host(default) or list all checks.-s, --status [up|down|grace|started|pause|new]Show only checks that have the specifiedstatus.--help                          Show this message and exit.Example output$schlistStatus  Last ping       Name------- --------------- ----------------------------------------up      2 minutes ago   disk-checkup      4 hours ago     resticup      5 days ago      restic_checkConfigurationCreate a configuration file~/.sch.confthat looks like:[hc]healthchecks_api_url=https://hc.example.com/api/v1/healthchecks_api_key=xxmysecretkeyxxAnd fill in the API URL and the key obtained from the Healthchecks project
settings block labeled "API Access".Optionally, specify the log level in the configuration file:[sch]loglevel=DEBUGPossible values for loglevel are explainedhere. The default log level isERROR.Monitoring cron jobsJust decorate your existing cron tabs by specifying the alternativesch:SHELL=/usr/local/bin/schThis line should be above the cron lines you want to have monitored by Healthchecks.Only jobs with the environment variableJOB_ID, ie:*/5 * * * * root JOB_ID=some_id /path/to/some_commandThe value ofJOB_IDshould be unique for the host.The combination of theJOB_IDenvironment variable and theschshell is enough
to have the job checked in Healthchecks.At each run of the job,schwill take care that the schedule, description and
other metadata is synchronized whenever there's a change in the cron job. Just
makes sure to not change theJOB_ID(or it will create a new check).Per job configurable optionsJust like theJOB_IDenvironment described in the previous paragraph. There are
other job specific environment variables that can be used to configure the behavior
of the cron job or the associated Healthchecks check. These are described in the
table below:Environment variableExample valueDescriptionAssociated Healthchecks check settingJOB_ID*backupRequired forschto interact with the Healthchecks APIcheck name, tagsJOB_TAGSfoo,barSpecify tag names separated by a commatagsJOB_GRACE5mGrace time specified in seconds or use the time interval format described below. The grace time will be set to 1.2 times the execution time +JOB_RNDWAIT+ 30 seconds. As per the Healthchecks API, the minimal grace time is 1 minute and the maximum grace time is 30 days.grace timeJOB_RNDWAIT1mMax. wait time in seconds or use the time interval format described below. Use this setting to introduce a random delay.schwill wait a random time between 0 andJOB_RNDWAITbefore executing the job's command.grace timeInterval formatIf no suffixes are used, seconds are assumed.
You can make use of the following suffixes to specify an interval:SuffixIntervalssecondsmminuteshhoursDdaysWweeksMmonthsYyearsAlthough days and weeks are accepted, you might want to limit the interval to several minutes ;-)Examples:IntervalDuration5m300 seconds120120 seconds1h30m5400 secondsOther meta datathe cron lines'commentis used for the description of the check. The comment line just above a cron line or the inline comment is used$USER: the current user running the cron command is used to create a tag nameduser=$USERSome example cron jobsAn example of a cron file that touches most of the functionality would look like:SHELL=/usr/local/bin/sch
# if this check fails, the host is probably offline
* * * * * root JOB_ID=true /bin/trueAlthough above cron job is useful, a more advanced configuration could look like:SHELL=/usr/loca/bin/sch
# super important backup, if this one fails: fix with top priority!
10 8-20/2 * * mon-fri  backup  JOB_ID=db-backups JOB_TAGS=db,backup,my_project JOB_RNDWAIT=2m JOB_GRACE=5m /usr/local/bin/run-db-backupsResulting in the following check:Job executionschtakes over the role of the shell. Jobs not containing theJOB_IDenvironment variable are directly executed withos.system.
Forschmanaged jobs:schwill start with pinging/startendpoint of the checkos.system executes the commanddepending on the exit code, it will ping for success or ping the/failend point on failureReferencespython-crontabhttps://pypi.org/project/python-crontab/crabhttps://github.com/grahambell/crabNotesfully qualified domain nameschuses the FQDN to identify the hosts it's running on. You can check the FQDN with:$hostname--fqdnhost.example.comHowever, on some systems that don't know the domain part, it just returns the
(short) hostname instead:$hostname--fqdnhostIf this is the case, you can fix that by editing the/etc/hostsfile so look
like this:127.0.0.1	localhost
127.0.1.1	host.example.com hostAfterwards,hostname --fqdnshould return the FQDN. Beware thatschwill
create new checks when the FQDN changes.Historyrelease notes for 0.1initial releasetesting the code on a couple of serversrelease notes for 0.2.xchanged file structurefirst release on PyPI.moved all code back intosch.pyprevious released packages where broken...setting the user-agent string to 'sch/{version}' when interacting with the
Healthchecks APIgot rid of outdated development section in the readmerelease notes for 0.3.0added command and filtering options for listing Healthchecks statusrelease notes for 0.4.0changed command line flags for listimproved table alignment for the list commandrelease notes for 0.5.xwhen a command fails, include the command, exit code, stdout and stderr in
the request body of the /fail pinggot rid of ttictoc as it broke on ubuntu 16 for some reason, using time insteadrelease notes for 0.6.xlisting of check status sorted bylast_pingadded configuration option sch:loglevelrelease notes for 0.7.xaddedJOB_RNDWAITconfiguration option to introduce a random waitfixed bug that keeps on creating new checks after an unknown failure