RunbookWraps is a set of simple python scripts that can be used to interact with Runbook.io. This repo contains two scripts, monitor.py
and reactor.py
.
monitor.py
is used to run commands or scripts from the shell. If the command exits with an exit code of 0
the monitor.py
process will make a webhook call to Runbook setting the monitor as Healthy. Any other exit code will result in a webhook call setting the monitor as Failed.
To run monitor.py
you can run it from the command line passing a YAML
configuration file.
$ monitor.py -c /path/to/config.yml
When defining a configuration file the first key is monitors
which contains a dictionary of monitors.
monitors:
The second key is a human friendly monitor name which also contains a YAML dictionary.
monitors:
Monitors Human Name:
The individual monitors dictionary requires at least 3 keys.
url
This is a unique URL that you can get from Runbook.io when creating a webhook monitor
check_key
This is a unique token that you can get from the same location as the unique URL
cmd
This is the command that the monitor.py wrapper script should execute.
args
Optional: This can be used to pass arguments to the specified command. You are free to not use this option and simply specify all arguments via the cmd
key.
When put all together the configuration looks like the following.
monitors:
Check nginx:
url: unique_url
check_key: unique_check_key
cmd: /bin/ps -elf | /bin/grep -q nginx
Given the above configuration when called the monitor.py
will execute /bin/ps -elf | grep -q nginx
and based on the success or failure of the command send an appropriate webhook to Runbook via the url
specified, using the check_key
token for authorization.
Where monitor.py
is used to run a check script/command and notify Runbook; reactor.py
is used to check the status of a monitor from Runbook and execute appropriate "reactions". Using the above monitor as an example a reaction would be to execute service nginx restart
.
To run reactor.py
you can also execute it from the command line passing a YAML
configuration file.
$ reactor.py -c /path/to/config.yml
The configuration for reactor.py
follows the same syntax as the monitor.py
configuration file. In fact you can utilize the same YAML
config file for both monitor.py
and reactor.py
(you can see this in config/nginx.yml.sample
). To start a reactor.py
configuration, you must first have a monitor defined. However; this monitor configuration only requires the url
and check_key
keys.
monitors:
Check nginx:
url: unique_url
check_key: unique_check_key
After specifying a monitor, reactions for that monitor can be specified by adding a reactions
key.
monitors:
Check nginx:
url: unique_url
check_key: unique_check_key
reactions:
The reactions
key is a dictionary that can contain multiple reactions. This is similar to the monitors
dictionary.
monitors:
Check nginx:
url: unique_url
check_key: unique_check_key
reactions:
reaction number 1:
The individual reaction requires 3 keys:
trigger
This is used to specify the number of failed or healthy monitors must be performed before the reaction is executed. This uses the failcount
key in the JSON reply from Runbook.io's webhook.
callon
This key can specify either healthy
or failed
and is used to specify when the reaction should be performed.
cmd
This key is similar to the monitor.py
's key in that it is the comand to execute as the reaction
args
Optional: This key is available for passing arguments to the commands specified in the cmd
key. Again, you can simply specify the full command in the cmd
key, if desired.
Put together a full configuration for nginx would look like the following.
monitors:
Check nginx:
url: unique_url
check_key: unique_check_key
cmd: /bin/ps -elf | /bin/grep -q nginx
reactions:
restart nginx:
trigger: 5
callon: failed
cmd: /etc/init.d/nginx restart
Checkout the config/nginx.yml.sample
sample configuration file for more advanced configurations.
Since we have our nginx.yml
configuration put together we can run the monitor.py
and reactor.py
wrappers at a scheduled interval via cron or any other scheduling service.
*/5 * * * * /path/to/monitor.py -c /path/to/config/nginx.yml 2>&1 > /dev/null
*/5 * * * * /path/to/reactor.py -c /path/to/config/nginx.yml 2>&1 > /dev/null
With the above cronjobs our monitor.py
is now monitoring the status of nginx and if it failed it will send an HTTP webhook to Runbook setting the monitor to "failed". Every 5 minutes the reactor.py
process will check with Runbook to see the status of the monitor, if the monitor is failed reactor.py
will then execute through the reactions defined in the nginx.yml
configuration file.