Configuration¶
Location¶
kibitzr reads configuration from kibitzr.yml file.
It tries to find it in following places:
./kibitzr.yml- current working directory.~/.config/kibitzr/kibitzr.yml~/kibitzr.yml
kibitzr-creds.yml can be used to store credentials,
it must be placed in the same directory as kibitzr.yml.
Format¶
kibitzr serves list of checks.
Each check may have a name. If name is present it must be unique.
If no name is provided, it will be auto-generated.
The name is used in notifications and internally as a check identifier.
Check may have url.
If it is provided, it will be used to fetch data. Optionally verify-cert can be set
to False to skip verificaiton of the SSL certificate.
Alternativelly data can be fetched by script, which is an arbitrary shell script.
Check will be executed every period seconds and/or on every schedule.
See Schedule documentation for a complete list of possibilities.
Fetched data from url (or script output) is passed
to a pipeline of transformations defined under transform key.
See Transforms documentation for a complete list of
supported transformations.
Finally transformed data is passed to a list of notifiers
defined under notify key.
See Notifier documentation for a complete list of
supported notifiers.
Kibitzr supports browser interactions. They can be activated by using any of keys:
Browser interaction is a strong side of Kibitzr and a tough article in itself. Please refer to Browser automation documentation.
Environment variables¶
Kibitzr provides read access to environment variables in a number of ways.
Inside Python support scripts, use Pythonic builtin module os:
import os
os.environ['NAME']
In shell scripts use bash syntax:
echo ${NAME}
Jinja templates have env dictionary in their context:
{{ env.NAME }}
kibitzr-creds.yml supports bash-like environment interpolation provided by yamlenv library:
service:
username: ${ USERNAME }
password: ${ PASSWORD }
Example break down¶
Let’s start with something simple. It’s not very useful check, but it shows the basics.
checks:
- name: Current Time
url: https://www.worldtimeserver.com/current_time_in_US-NY.aspx
transform:
- css: "span#theTime"
- text
notify:
- python: print(content)
period: 15
Copy paste it to your kibitzr.yml and launch kibitzr.
You will see something like this:
$ kibitzr once
2017-03-28 22:02:39,465 [INFO] kibitzr.checker: Fetching Current Time at https://www.worldtimeserver.com/current_time_in_US-NY.aspx
2017-03-28 22:02:39,687 [INFO] kibitzr.notifier.custom: Executing custom notifier
10:02:39 pm
EDT
2017-03-28 22:02:39,687 [INFO] kibitzr.main: Scheduling checks for 'Current Time' every 15 seconds
2017-03-28 22:02:39,688 [INFO] kibitzr.main: Starting infinite loop
2017-03-28 22:02:54,705 [INFO] schedule: Running job Every 15 seconds do check() (last run: [never], next run: 2017-03-28 22:02:54)
2017-03-28 22:02:54,705 [INFO] kibitzr.checker: Fetching Current Time at https://www.worldtimeserver.com/current_time_in_US-NY.aspx
2017-03-28 22:02:54,823 [INFO] kibitzr.notifier.custom: Executing custom notifier
10:02:54 pm
EDT
Let’s follow the configuration file line-by-line to see how it works.
On the first line we define a dictionary key checks:
checks:
Then, starting with indentation and dash goes the name of the first check:
- name: Current Time
It’s an arbitrary string, the only constraint is that it must be unique within the checks list.
Right after name, we define URL:
url: https://www.worldtimeserver.com/current_time_in_US-NY.aspx
Please note, that all keys are in lower case.
So far so good, we came to transformations:
transform:
- css: "span#theTime"
- text
transform value must be a list (as denoted by dashes).
Please note how list items indentation is deeper, than of transform.
Each transform item can be a simple transform name (like text, which extracts text from HTML),
or a name: argument pair (like css: "#qlook > div" which crops HTML using CSS selector "#qlook > div")
As you can see, we first crop whole page to a single HTML tag and then extract plain text from it.
Having all the hard job behind, we came to notification settings.
kibitzr supports many different notifiers,
but here we are using the one, that does not require credentials management - arbitrary Python script.
notify:
- python: print(content)
It is exactly the code, that produced
10:02:39 pm
EDT
in the kibitzr output.
Last line of configuration file is the period:
period: 15
The number of seconds to wait between (start of) checks.
Kibitzr understands time to the extent, you can write 1 hour instead of 3600.
For the more complete list of available formats refer to pytimeparse docs.
