Configuration

Location

kibitzr reads configuration from kibitzr.yml file. It tries to find it in following places:

  1. ./kibitzr.yml - current working directory.
  2. ~/.config/kibitzr/kibitzr.yml
  3. ~/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. Another option is script, which is an arbitrary bash script.

Check will be executed every period seconds.

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:

  1. delay - number of seconds to wait after page loaded in browser to process JavaScript.
  2. scenario - python scenario acting on selenium driver after page load.
  3. form - shorthand for simple selenium scenarios.

Browser interaction is a strong side of Kibitzr and a tough article in itself. Please refer to Browser automation documentation.

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.