A simple systemd monitor sending events to an MQTT queue

Clone this repo:
  1. c71e83a tox: use py34 instead of py35 by Tristan Cacqueray · 6 years ago master 0.2.1
  2. 68342f1 Fix journalctl events not being visible to ochlero by mhuin · 6 years ago
  3. be9c3a1 prepare tag 0.2.0 by mhuin · 6 years ago 0.2.0
  4. 05014c6 fix call to usermod instead of useradd by mhuin · 6 years ago
  5. 28484c0 spec: allow service user access to journal by mhuin · 6 years ago

OCHLERO

Ochlero is a script that monitors the systemd journal for specific events that trigger publications on an MQTT queue.

"Ochlero" comes from "Ochlerotatus Triseriatus", a species of tree hole breeding mosquitoes (https://en.wikipedia.org/wiki/Ochlerotatus_triseriatus), ie mosquitoes that like logs...

Running and testing

Ochlero is tested against and runs on python 2.7 and python 3.5.

With python 2.x you need to install the systemd and mqtt wrappers on your system. On CentOS or Fedora, you can do so with the following command (extra repositories such as EPEL might need to be activated):

sudo yum install systemd-python python-paho-mqtt

This is necessary due to a problem in the PyPI version of the systemd wrapper.

With python 3.5, running

pip install -r requiremenits.txt

should be enough.

To start ochlero, simply run

ochlero -c /path/to/config/file.yaml

The configuration file

Ochlero uses a yaml configuration file to define the mosquitto service to publish to, and the processes and events to look for. See etc/ochlero.yaml for an example.

Writing patterns

When ochlero is running, it will attempt to match log lines associated with a given unit or command against patterns. A pattern is basically a regular expression. Please refer to python's documentation for details on syntax, for example https://docs.python.org/2/howto/regex.html

Most of the time, you will want to pick some information from the log line and publish it to MQTT. These elements of interest are defined in the pattern like bash variables, ie "${ELEMENTNAME}. You must then define the regex matching for each variable in the directive "where" of your event. For example:

events
  - name: hello world
    pattern: "hello, my name is ${PERSON}"
    where:
      PERSON: [A-Za-z]+
    publish: "Hi ${PERSON}!"

A log message like "Hello, my name is Mark" will publish the message "Hi Mark!".

Predefined substitution types

To make it easier for you, some substitutions are included in ochlero so you don't have to write annoying regular expressions:

  • _ALPHANUMERIC_
  • _INT_
  • _URL_
  • _EMAIL_
  • _IPv4_
  • _SYSLOGTIMESTAMP_

Writing messages to publish

Variables can be reused as they are in publish messages (see previous example). Some predefined "macros" can also be used:

  • _EPOCH_ : the Unix Epoch timestamp at parsing time.

Contributing

Ochlero is developped in Software Factory and contributions follow a review workflow.

To contribute:

  1. Log in once to Software Factory at https://softwarefactory-project.io
  2. Set up your ssh key in Gerrit's settings page
  3. Clone the project:
git clone ssh://<your_username>@softwarefactory-project.io:29418/software-factory/ochlero.git
  1. Set up git review
cd ochlero && git review -s
  1. Work on your feature, make a commit, then send the review
git commit -m'my feature' && git review