What is hume

Hume is a system that helps writing scripts that report status to a central location. The central location might be a Slack workspace, Logstash, syslog, remote-syslog. We are also working on a custom dashboard/humequery system.

The main hume binary can easily be called from within bash scripts. Imagine, you have this script that updates the core and plugins of a couple websites that use wordpress, using WP-CLI. Let's also assume that script runs from cron:

#!/bin/bash
wpcli='/usr/bin/wp'
for dir in "/var/www/site1/htdocs" "/var/www/othersite/htdocs"
do
    cd $dir
    $wpcli core update
    $wpcli plugin update
done

Simple, right? Now, let's add some hume commands:

#!/bin/bash
for dir in "/var/www/site1/htdocs" "/var/www/othersite/htdocs"
do
    cd $dir
    wp core update || hume -L warn "core update failed for $dir"
    wp plugin update || hume -L warn "plugin update failed for $dir"
done

The above hume commands will run if the exit status of wp (the binary for WP-CLI) is non-zero using the classic conditional execution bash provides. (|| is used for errors, and && for OK statuses).

Those hume commands send a specially crafted json message via zmq to a humed server (more on humed later). Hume supports more command line switches. This is the output of hume --help:

usage: hume [-h] [-L {ok,warn,error,info,critical,debug}]
            [-c {counter-start,counter-pause,counter-stop,counter-reset}]
            [-t TASK] [-a] [-T TAGS] [-e ENCRYPT_TO]
            [--recv-timeout RECVTIMEOUT]
            msg

positional arguments:
  msg                   [REQUIRED] Message to include with this update

optional arguments:
  -h, --help            show this help message and exit
  -L {ok,warn,error,info,critical,debug}, --level {ok,warn,error,info,critical,debug}
                        Level of update to send, defaults to 'info'
  -t TASK, --task TASK  [OPTIONAL] Task name, for example BACKUPTASK.
  -a, --append-pstree   Append process calling tree
  -T TAGS, --tags TAGS  Comma-separated list of tags
  --recv-timeout RECVTIMEOUT
                        Time to wait for humed reply to hume message. Default
                        1000ms / 1 second.

(I have removed some parameters from the --help output, specially those still in development phase, particularly --encrypt-to and --hume-cmd).

From the previous example, we know -L or --level help indicate the error level for a hume message (ok, warning, critical, etc). But we can also use a task identifier to better group messages for a particular task. Task identifiers can be almost anything.

But hume also supports tags. If your central location supports advanced search criteria, it can help you query your hume operational database, for instance "Show me all warning, error and critical messages for UPDATE tasks tagged #wordpress for the past year".

Let's further enhance our wordpress update script:

#!/bin/bash
TASKNAME='WEBAPP_UPDATES'
TAGS='wordpress,cron'
hume -a -t $TASKNAME -T $TAGS "Starting wp-cli run"
for dir in "/var/www/site1/htdocs" "/var/www/othersite/htdocs"
do
    cd $dir
    wp core update || hume -t $TASKNAME -T $TAGS -L warn "core update failed for $dir"
    wp plugin update || hume -t $TASKNAME -T $TAGS -L warn "plugin update failed for $dir"
done
hume -t $TASKNAME -T $TAGS "Finished wp-cli run"

Now, this script will always emit two hume info messages, one at the start and one at the end of the script, plus the warning ones in case of a problem in between. Those messages will conform to the WEBAPP_UPDATES task, and be tagged #wordpress and #cron. Additionally, you might have noticed the -a in the first hume message: that flag will include the calling tree for the script that is being run: you will know exactly how that hume command ended up being run.

As you can see, we declare hume to be agnostic because it doesn't care HOW you write your sysadmin scripts (well, besides bash, although you could easily import the hume module from your python scripts and just use it, just saying...).

Now, let's see the humed daemon, which receivs the hume messages and does the useful thing. Check out the next page, How to install hume.