README.md

   1 khatus
   2 ======
   3 ![mascot](mascot.jpg)
   4
   5 Experimental, system monitor and status (bar) reporter I use with
   6 [dwm](https://dwm.suckless.org/) on GNU/Linux.
   7
   8 ![screenshot](screenshot.jpg)
   9
  10
  11 Design
  12 ------
  13
  14 ```
  15 parallel    +----------+  +----------+          +----------+
  16 stateless   | sensor_1 |  | sensor_2 |    ...   | sensor_n |
  17 collectors  +----------+  +----------+          +----------+
  18                  |             |           |         |
  19                data          data        data      data
  20                  |             |           |         |
  21                  V             V           V         V
  22 serial      +----------------------------------------------+
  23 stateful    |                controller                    |
  24 observer    +----------------------------------------------+
  25                                |
  26                        decision messages
  27 decision                       |
  28 messages                       |
  29 copied to                      |
  30 any number                     |
  31 of interested                  |
  32 filter/actuator                |
  33 combinations                   |
  34                                |
  35                                V
  36                  +-------------+-+---------+---------+
  37                  |               |         |         |
  38                  V               V         V         V
  39 parallel    +------------+ +------------+     +------------+
  40 stateless   | filter_1   | | filter_2   | ... | filter_n   |
  41 filters     +------------+ +------------+     +------------+
  42                  |               |         |         |
  43                  V               V         V         V
  44 parallel    +------------+ +------------+     +------------+
  45 stateless   | actuator_1 | | actuator_2 | ... | actuator_n |
  46 executors   +------------+ +------------+     +------------+
  47                  |              |          |         |
  48               commands       commands   commands  commands
  49                  |              |          |         |
  50                  V              V          V         V
  51             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  52             ~~~~~~~~~~~~~ operating system ~~~~~~~~~~~~~~~~~
  53             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  54 ```
  55
  56 ### Actuator
  57 Actuator is anything that takes action upon controller messages. A few generic
  58 ones are included:
  59
  60 - `khatus_actuate_alert_to_notify_send`
  61 - `khatus_actuate_status_bar_to_xsetroot_name`
  62
  63 and, by default, are left disconnected from the controller's output, so if
  64 desired - it needs to be manually attached when starting `khatus`. For example,
  65 in my `.xinitrc` I have:
  66
  67 ```sh
  68 $BIN/khatus \
  69 2> >($BIN/twrap >> $HOME/var/log/khatus.log) \
  70 | tee \
  71     >($BIN/khatus_actuate_status_bar_to_xsetroot_name) \
  72     >(grep -v MpdNowPlaying | $BIN/khatus_actuate_alert_to_notify_send) \
  73 2> >($BIN/twrap >> $HOME/var/log/khatus-actuators.log) \
  74 &
  75 ```
  76 (where `twrap` is a simple script which prefixes a timestamp to each line)
  77
  78 The idea is to give maximum flexibility for what to do with the controller
  79 output, say, for instance:
  80
  81 ```sh
  82 $BIN/khatus \
  83 | tee \
  84 ... \
  85 >(grep '^REPORT' | actuate_report_to_email) \
  86 >(grep '^ALERT' | grep mpd | actuate_alert_to_email) \
  87 >(grep '^ALERT' | grep IntrusionAttempt | actuate_intruder_to_iptables_drop) \
  88 >(grep '^ALERT' | grep NewDevice | actuate_alert_to_notify_send)
  89 >(grep '^ALERT' | grep DiskError | actuate_call_mom)
  90 ...
  91 ```
  92 ... and so on, for any other such fun you might imagine.
  93
  94 ### Errors
  95 Any errors encountered by any sensor are propagated as alerts by the
  96 controller, which are in turn actualized as desktop notifications by the
  97 `khatus_actuate_alert_to_notify_send` actuator:
  98
  99 ![screenshot-self-error-propagation](screenshot-self-error-propagation.jpg)
 100
 101 TODO
 102 ----
 103
 104 - retry/cache for sensors fetching flaky remote resources (such as weather)
 105 - throttling of broken sensors (constantly returns errors)
 106 - alert specification language
 107     - trigger threshold
 108     - above/bellow/equal to threshold value
 109     - priority
 110     - snooze time (if already alerted, when to re-alert?)
 111     - text: subject/body
 112 - use `nmcli monitor` instead of polling