README.md 3.46 KB
Newer Older
Bram Daams's avatar
Bram Daams committed
1
2
3
# SmartCronHelper
A cron shell wrapper for registering and updating cron jobs automatically in
[healthchecks](https://healthchecks.io) or your own hosted copy of Healthchecks.
Bram Daams's avatar
Bram Daams committed
4

Bram Daams's avatar
Bram Daams committed
5
> warning: this software package should be considered "alpha"
Bram Daams's avatar
Bram Daams committed
6

Bram Daams's avatar
Bram Daams committed
7
8

## Installation
Bram Daams's avatar
Bram Daams committed
9
Install the `sch` shell and it's dependencies by running pip in the cloned
Bram Daams's avatar
Bram Daams committed
10
repository:
Bram Daams's avatar
Bram Daams committed
11
``` console
Bram Daams's avatar
Bram Daams committed
12
13
$ cd sch
$ sudo pip install .
Bram Daams's avatar
Bram Daams committed
14
15
```

Bram Daams's avatar
Bram Daams committed
16
17
18
19
Create a configuration file:
``` console
sudo cp sch.conf.example /etc/sch.conf
```
Bram Daams's avatar
Bram Daams committed
20
And fill in the API URL and the key obtained from the Healthchecks project
Bram Daams's avatar
Bram Daams committed
21
settings block labeled "API Access".
Bram Daams's avatar
Bram Daams committed
22

Bram Daams's avatar
Bram Daams committed
23
### Monitoring cron jobs
Bram Daams's avatar
Bram Daams committed
24
Just decorate your existing cron tabs by specifying the alternative `sch`:
Bram Daams's avatar
Bram Daams committed
25
26
27
28
```
SHELL=/usr/local/bin/sch
```
This line should be above the cron lines you want to have monitored by Healthchecks.
Bram Daams's avatar
Bram Daams committed
29

Bram Daams's avatar
Bram Daams committed
30
31
32
33
34
Only jobs with the environment variable `JOB_ID`, ie:
```
*/5 * * * * root JOB_ID=some_id /path/to/some_command
```
The value of `JOB_ID` should be unique for the host.
35

Bram Daams's avatar
Bram Daams committed
36
37
The combination of the `JOB_ID` environment variable and the `sch` shell is enough
to have the job checked in Healthchecks.
Bram Daams's avatar
Bram Daams committed
38

Bram Daams's avatar
Bram Daams committed
39
40
41
42
43
44
At each run of the job, `sch` will 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 the `JOB_ID` (or it will create a new check).
 
### Other meta data
The following data is used to configure a corresponding Healthchecks check:
Bram Daams's avatar
Bram Daams committed
45
46
47
- `JOB_ID`: the environment variable is used for the name of the check and a tag named `job_id={value of JOB_ID}`
- the cron lines' comment is used for the description of the check. The comment line just above a cron line or the inline comment is used
- `JOB_TAGS`: use this environment variable in a job to specify tag names separated by a comma to specify additional tags
Bram Daams's avatar
Bram Daams committed
48
49
- `$USER`: the current user running the cron command is used to create a tag named `user=$USER`
- the jobs schedule and the hosts timezone is used to set the checks schedule
Bram Daams's avatar
Bram Daams committed
50

Bram Daams's avatar
Bram Daams committed
51
52
53
54
55
56
An 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/true
```
Bram Daams's avatar
Bram Daams committed
57
Although above cron job is useful, a more realistic could look like:
Bram Daams's avatar
Bram Daams committed
58
59
60
61
62
63
```
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 /usr/local/bin/run-db-backups
``

Bram Daams's avatar
Bram Daams committed
64
65
66
67
68
69
70
### Job execution
`sch` takes over the role of the shell. Jobs not containing the `JOB_ID` environment variable are directly executed with `os.system`.
For `sch` managed jobs:
- `sch` will start with pinging `/start` endpoint of the check
- os.sytem executes the command
- depending on the exit code, it will ping for success or ping the `/fail` end point on failure

Bram Daams's avatar
Bram Daams committed
71
72
73
74
75
76
## Development environment
### Setup environment
``` console
$ python -m venv venv
$ . venv/bin/activate
$ pip install --editable .
Bram Daams's avatar
Bram Daams committed
77
```
Bram Daams's avatar
Bram Daams committed
78

Bram Daams's avatar
Bram Daams committed
79
### Testing
Bram Daams's avatar
Bram Daams committed
80
Create a file named `sch.conf` and edit the Healthchecks API URL and key:
Bram Daams's avatar
Bram Daams committed
81
82
83
``` console
cp sch.conf.example sch.conf
```
Bram Daams's avatar
Bram Daams committed
84
The configuration file looks like:
Bram Daams's avatar
Bram Daams committed
85
86
87
88
89
90
91
92
93
94
95
``` console
 $ cat sch.conf.example 
[hc]
healthchecks_api_url = https://hc.example.com/api/v1/
healthchecks_api_key = xxmysecretkeyxx
```
Create a test cron job:
``` console
$ sudo cp doc/testcrontab /etc/cron.d/test
$ ./testshell.sh
```
Bram Daams's avatar
Bram Daams committed
96

Bram Daams's avatar
Bram Daams committed
97
98
### Syntax check
Style Guide Enforcement:
Bram Daams's avatar
Bram Daams committed
99
100
101
102
103
``` console
$ pip install flake8
$ flake8 *py
```

Bram Daams's avatar
Bram Daams committed
104
### References
Bram Daams's avatar
Bram Daams committed
105
* python-crontab <https://pypi.org/project/python-crontab/>