What?

The libumberlog library serves two purposes: it's either a drop-in replacement for the syslog() system call, in which case it turns the default syslog messages into CEE-enhanced messages, with a CEE-JSON payload, and some automatically discovered fields. Or, it can be used as a stand-alone library, that provides a syslog()-like API, with the ability to add arbitrary key-value pairs to the resulting JSON payload.

Why?

The legacy syslog() interface, while simple, is starting to show its age. It was meant to be an interface to construct free-form messages, targeted at human readers. However, in this time and age, the amount of logs generated by a busy system is, especially by a central log server in a larger environment does not lend itself well to manual processing.

Instead, we rely more and more on programs to make sense out of the logs, to structure the free-form text into something that's easier to search and corellate, to filter on, and the existing interface does not make this easy. It wasn't written with computer-based post-processing in mind.

This library is an attempt to smoothly introduce structured logging to administrators and developers alike, by taking a legacy interface, syslog(), and improving on it a little. Not only by enhancing the existing function, for example with a high-resolution timestamp, but by providing an extended, but still similar API to developers, to allow them to add more structure to their logs.

How?

An example

One does wonder, how an example might look like, we're happy to oblige, and show one (word wrapped, for an easier read):

SSH Login:

Mar 24 12:01:34 localhost sshd[12590]: @cee:{
    "msg": "Accepted publickey for algernon from 127.0.0.1 port 55519 ssh2",
    "pid": "12590", "facility": "auth", "priority": "info",
    "program": "sshd", "uid": "0", "gid": "0",
    "host": "hadhodrond", "timestamp": "2012-03-24T12:01:34.236987887+0100" }

Requirements

Apart from the autotools, a C compiler, there are no other dependencies when building, except for a sufficiently modern system.

The test suite requires json-c and check too, and docutils is required to build the documentation.

Installation

The library follows the usual autotools way of installation:

$ git clone git://github.com/algernon/libumberlog.git
$ cd libumberlog
$ autoreconf -i
$ ./configure && make && make install

Usage

The library comes in two variants: one to link against, and provides an enhanced, syslog()-like API. For this, please see the API documentation for more information.

The other variant is an LD_PRELOAD-able shared object, installed as libumberlog_preload.so into a subdirectory of one's libdir. This one overrides the system-suploed syslog() calls with its own version, and turns these into CEE-emitting functions. It can be used either on a per-application basis, by setting LD_PRELOAD, or adding the path to the library to /etc/ld.so.preload.

Non-goals

License

This library is released under a two-clause BSD license, see the LICENSE file for details.