From 99dd3a3f8dc881c0f4939205dc4c04bb6ea0c149 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sat, 24 Mar 2012 12:31:57 +0100 Subject: README: Yet more updates Signed-off-by: Gergely Nagy --- README.rst | 51 +++++++++++++++++++++++++-------------------------- 1 file changed, 25 insertions(+), 26 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 00708c3..5d30d59 100644 --- a/README.rst +++ b/README.rst @@ -3,41 +3,40 @@ 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. +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. -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 primary goal of the library is to smoothly introduce people - -administrators and developers alike - to structured logging. The -library aims to not only replace the traditional ``syslog()`` system -call, but to extend it too. - -The extensions (unless turned off) provide information not normally -available via traditional syslog, such as a high-resolution timestamp, -making them just that more useful. +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? ==== -All of this is accomplished in a way that allows for -**LD_PRELOAD**-ing the library, either on a case-by-case basis, or -system-wide, and seamlessly transform traditional syslog messages, -without any further work required. - -Even better, the library provides new functions, that are modelled -after the traditional ``syslog()`` API, but provide a few -improvements, such as the ability to add arbitrary key-value pairs to -the structured message, and reasonable error handling. - -More details -============ - An example ---------- -- cgit