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.
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.
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" }
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.
The library follows the usual autotools way of installation:
$ git clone git://github.com/deirf/libumberlog.git $ cd libumberlog $ autoreconf -i $ ./configure && make && make install
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.
- It is not a goal to support anything else but
syslog()payload. - It is not a goal to go to great lengths to discover things about the running process: only a few things that are easily available, no matter how reliable this information may be.
- It is not a goal to support complex values, or anything other than plain C strings.
This library is released under a two-clause BSD license, see the LICENSE file for details.