[khatus.git] / README.md

khatus
======
![mascot](mascot.jpg)

Experimental, system monitor and status (bar) reporter I use with
[dwm](https://dwm.suckless.org/) on GNU/Linux.

![screenshot](screenshot.jpg)


Design
------

```
parallel    +----------+  +----------+          +----------+
stateless   | sensor_1 |  | sensor_2 |    ...   | sensor_n |
collectors  +----------+  +----------+          +----------+
                 |             |           |         |
               data          data        data      data
                 |             |           |         |
                 V             V           V         V
serial      +----------------------------------------------+
stateful    |                controller                    |
observer    +----------------------------------------------+
                               |
                       decision messages
decision                       |
messages                       |
copied to                      |
any number                     |
of interested                  |
filter/actuator                |
combinations                   |
                               |
                               V
                 +-------------+-+---------+---------+
                 |               |         |         |
                 V               V         V         V
parallel    +------------+ +------------+     +------------+
stateless   | filter_1   | | filter_2   | ... | filter_n   |
filters     +------------+ +------------+     +------------+
                 |               |         |         |
                 V               V         V         V
parallel    +------------+ +------------+     +------------+
stateless   | actuator_1 | | actuator_2 | ... | actuator_n |
executors   +------------+ +------------+     +------------+
                 |              |          |         |
              commands       commands   commands  commands
                 |              |          |         |
                 V              V          V         V
            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
            ~~~~~~~~~~~~~ operating system ~~~~~~~~~~~~~~~~~
            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```

### Actuator
Actuator is anything that takes action upon controller messages. A few generic
ones are included:

- `khatus_actuate_alert_to_notify_send`
- `khatus_actuate_status_bar_to_xsetroot_name`

and, by default, are left disconnected from the controller's output, so if
desired - it needs to be manually attached when starting `khatus`. For example,
in my `.xinitrc` I have:

```sh
$BIN/khatus \
2> >($BIN/twrap >> $HOME/var/log/khatus.log) \
| tee \
    >($BIN/khatus_actuate_status_bar_to_xsetroot_name) \
    >(grep -v MpdNowPlaying | $BIN/khatus_actuate_alert_to_notify_send) \
2> >($BIN/twrap >> $HOME/var/log/khatus-actuators.log) \
&
```
(where `twrap` is a simple script which prefixes a timestamp to each line)

The idea is to give maximum flexibility for what to do with the controller
output, say, for instance:

```sh
$BIN/khatus \
| tee \
... \
>(grep '^REPORT' | actuate_report_to_email) \
>(grep '^ALERT' | grep mpd | actuate_alert_to_email) \
>(grep '^ALERT' | grep IntrusionAttempt | actuate_intruder_to_iptables_drop) \
>(grep '^ALERT' | grep NewDevice | actuate_alert_to_notify_send)
>(grep '^ALERT' | grep DiskError | actuate_call_mom)
...
```
... and so on, for any other such fun you might imagine.

### Errors
Any errors encountered by any sensor are propagated as alerts by the
controller, which are in turn actualized as desktop notifications by the
`khatus_actuate_alert_to_notify_send` actuator:

![screenshot-self-error-propagation](screenshot-self-error-propagation.jpg)

TODO
----

- retry/cache for sensors fetching flaky remote resources (such as weather)
- throttling of broken sensors (constantly returns errors)
- alert specification language
    - trigger threshold
    - above/bellow/equal to threshold value
    - priority
    - snooze time (if already alerted, when to re-alert?)
    - text: subject/body
- more-structured controller API: a sensor submits a list of k/v pairs

Redesign notes
--------------

- controller should not do formatting
- need in-memory db for diskless feedback/throttling and cache
Commit	Line	Data
	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	- more-structured controller API: a sensor submits a list of k/v pairs
	113
	114	Redesign notes
	115	--------------
	116
	117	- controller should not do formatting
	118	- need in-memory db for diskless feedback/throttling and cache