1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
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
|
