README.md 2.59 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
9
10

## Installation
Install the `sch` shell and it's dependancies by running pip in the cloned
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
20
21
Create a configuration file:
``` console
sudo cp sch.conf.example /etc/sch.conf
```
And fill in the api url and the key obtained from the Healthchecks project
settings block labeled "API Access".
Bram Daams's avatar
Bram Daams committed
22

Bram Daams's avatar
Bram Daams committed
23
24
25
26
27
28
### Monitoring cron jobs
Just decorate your existing crontabs by specifying the alternative `sch`:
```
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
45
46
47
48
49
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:
- `JOB_ID` env var: this 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` env var: specify tag names separated by a comma to specify additional tags for the check.
- `$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

51

Bram Daams's avatar
Bram Daams committed
52
53
54
55
56
57
## Development environment
### Setup environment
``` console
$ python -m venv venv
$ . venv/bin/activate
$ pip install --editable .
Bram Daams's avatar
Bram Daams committed
58
```
Bram Daams's avatar
Bram Daams committed
59

Bram Daams's avatar
Bram Daams committed
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
### Testing
Create a file named `sch.conf` and edit the Healthchecks api url and key:
``` console
cp sch.conf.example sch.conf
```
The config file looks like:
``` 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
77

Bram Daams's avatar
Bram Daams committed
78
79
### Syntax check
Style Guide Enforcement:
Bram Daams's avatar
Bram Daams committed
80
81
82
83
84
``` console
$ pip install flake8
$ flake8 *py
```

Bram Daams's avatar
Bram Daams committed
85
86
87
88


### References
* python-crontab <https://pypi.org/project/python-crontab/>