From 8e9513948811df9d384805192ee3d6ab58f4605c Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Tue, 20 Mar 2012 08:28:32 +0100 Subject: README.rst: New file. Signed-off-by: Gergely Nagy --- Makefile.am | 2 +- README.rst | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 README.rst diff --git a/Makefile.am b/Makefile.am index d3da3aa..a9f5bf7 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,4 @@ SUBDIRS = lib ACLOCAL_AMFLAGS = -I m4 --install -EXTRA_DIST = LICENSE +EXTRA_DIST = LICENSE README.rst diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..741a677 --- /dev/null +++ b/README.rst @@ -0,0 +1,69 @@ +libcee-syslog +============= + +The libcee-syslog 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. + +Features +-------- + +libcee-syslog is supposed to be a thin layer, that provides a few +benefits over legacy ``syslog()``, within reason, and with +limitations. + +* It overrides **openlog()**, to be able to store extra flags, and + cache some stuff, if so need be. Currently, it caches the *pid* and + the *ident*. +* It overrides **syslog()** (and **vsyslog()**), but does NOT extend + those APIs. It merely turns a legacy syslog message into something + that has a CEE payload, and unless turned off, it adds a few + automatically discovered fields (at the moment, these are *pid*, + *facility* and *priority* and *program*; *timestamp*, *uid*, *gid* + and *thread-id* are easy to collect aswell, the rest not so much, + but suggestions welcome. I do want to keep this list reasonably + short, and the costy discoveries will be toggleable). +* It provides **cee_syslog()** (and **cee_vsyslog()**), which do the + same as the `syslog()` call, have the same auto-discovery mechanism, + but they also allow adding arbitrary key-value pairs. +* It provides **cee_format()** (and **cee_vformat()**), which do the + same as the syslog calls, except the result is a newly allocated + string, that does not have a ``@cee:`` prefix. + +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. + +Requirements +------------ + +Apart from the autotools and a C compiler, there are no other hard +dependencies when building, except for a sufficiently modern system. + +Installation +------------ + +The library follows the usual autotools way of installation: + +:: + + $ git clone git://github.com/algernon/libcee-syslog.git + $ cd libcee-syslog + $ ./autogen.sh + $ ./configure && make && make install + +License +------- + +This library is released under a two-clause BSD license, see the +LICENSE file for details. -- cgit