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.

.. _CEE\-enhanced messages: #an-example

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.

.. _json\-c: http://oss.metaparadigm.com/json-c/
.. _check: http://check.sourceforge.net/
.. _docutils: http://docutils.sourceforge.net/

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

.. image:: https://secure.travis-ci.org/algernon/libumberlog.png?branch=master

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``.

.. _API documentation: http://algernon.github.com/libumberlog/umberlog.html

Non-goals
---------

* 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.

License
-------

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

.. _LICENSE: https://raw.github.com/algernon/libumberlog/master/LICENSE