l2(3) Flexible Logging l2(3)NAME
OSSP l2 - Flexible Logging
VERSION
OSSP l2 0.9.13 (08-Jun-2007)
SYNOPSIS
...
DESCRIPTION
OSSP l2 is a C library providing a very flexible and sophisticated Unix
logging facility. It is based on the model of arbitrary number of chan‐
nels, stacked together in a top-down data flow tree structure with fil‐
tering channels in internal nodes and output channels on the leave
nodes.
Channel trees can be either constructed manually through lower-level
API functions or all at once with a single API function controlled by a
compact syntactical description of the channel tree. For generating log
messages a printf-style formatting engine is provided which can be
extended through callback functions. The data flow inside the channel
tree is controlled by (eight fixed and nine custom) logging message
severity levels which are assigned to each individual channel.
Channels are implemented by channel handlers which can be even customer
supplied for creating own channels which seamlessly integrate into the
framework. For convenience reasons, OSSP l2 already ships with pre-
implemented filtering (noop, filter, prefix, buffer) and output (null,
fd, file, pipe, socket, syslog, smtp) channels which already cover
mostly all use cases of logging.
A language is provided to allow for channel specification and configu‐
ration. Thus, the channel tree can be constructed either by the API
and its ANSI C bindings or through the use of this OSSP l2 channel def‐
inition language. Applying the API allows fine grained control of the
channel tree. Additionally, the API allows for a more interactive chan‐
nel definition. However, using the channel definition language to
define the channel tree is more convenient, and takes less coding
effort. The channel definition language is almost always sufficient for
an application using OSSP l2.
LOGGING LEVELS
PANIC fatal error -> immediate abort (SIGBUS, SIGSEGV) CRITICAL tem‐
porary failure -> sleep, retry possible (malloc == NULL) ERROR func‐
tionality error WARNING functionality successful NOTICE operation,
statistics, start/stop --- border line production/testing --- INFO
step-by-step TRACE I/O tracing --- border line end-user/developer
DEBUG debugging messages
CHANNEL TREE SPECIFICATION
An OSSP l2 channel tree can be descriped by a textual specification
according to the following Backus-Naur-Form (BNF):
tree ::= stream
stream ::= channel
⎪ channel "->" stream
⎪ channel "->" "{" streams "}"
streams ::= stream
⎪ stream ";" streams
channel ::= channel_level "/" channel_level ":" channel_cons
⎪ channel_level ":" channel_cons
⎪ channel_cons
channel_level ::= IDENTIFIER
⎪ "(" channel_level_mask ")"
channel_level_mask ::= IDENTIFIER
⎪ IDENTIFIER "⎪" channel_level_mask
channel_cons ::= IDENTIFIER channel_params
channel_params ::= EMPTY
⎪ "(" channel_param_list ")"
channel_param_list ::= EMPTY
⎪ channel_param
⎪ channel_param "," channel_param_list
channel_param ::= IDENTIFIER "=" PARAMETER
An example of such a channel tree specification is:
noop -> {
debug: prefix(prefix="[%d-%m-%Y/%H:%M:%S] ")
-> buffer(size=16384)
-> file(path=foo.log, trunc=0);
error: syslog(ident=foo, facility=user,
remotehost=syslog.example.com,
target=remote);
panic: smtp(host=mail.example.com,
rcpt=foo@example.com);
}
FUNCTIONS
The following functions are provided by the OSSP l2 API:
AVAILABLE CHANNEL HANDLERS
Syslog Output Channel Handler (l2_handler_syslog)
The Syslog output channel handler "l2_handler_syslog" sends the incom‐
ing message either via syslog(3) to a local syslogd(8) or via BSD Sys‐
log protocol to a remote Syslog service. It conforms to RFC 3164 (The
BSD syslog Protocol; C. Lonvick; August 2001).
It provides the following channel parameters:
target (optional, "char *")
Sets the location of the target Syslog service. Possible values are
"local" (the default) or "remote". If "remote" is used, the parame‐
ters "remotehost" has to be set, too.
remotehost (optional, "char *")
Host name or IP address of the remote Syslog service. No default
exists, user has to provide value.
remoteport (optional, "int")
Port number of the remote SMTP service. Default is 514.
localhost (optional, "char *")
The name of the local host, without any domain appended.
facility (optional, "char *")
The Syslog facility used for all messages. It has to be one of the
following: "kern", "user", "mail", "daemon", "auth", "syslog",
"lpr", "news", "uucp", "cron", "authpriv", "ftp", "ntp", "secu‐
rity", "console", "clock", "local0", "local1", "local2", "local3",
"local4", "local5", "local6", "local7".
ident (mandatory, "char *")
Arbitrary string identifying the program. There is no default,
user has to provide value.
logpid (optional, "int")
Boolean flag whether to add the Process ID (pid) to the ident tag
in messages. Default is 0.
Pipe Output Channel Handler (l2_handler_pipe)
The Pipe output channel handler "l2_handler_pipe" sends the incoming
message to the standard input of a chosen command, passed to the l2
library as a parameter when calling l2_configure.
Any command that operates on the standard input (c language descriptor
stdin) can be used, but attention is advised due to the wide variety of
commands and their particular exit behaviours.
Attention! Commands that exit on their own and with a success return
value will not be restarted, however those returning with non-zero exit
codes will be restarted. OSSP l2 reopens closed pipe channels due to
faulted command processes in this way. Should such a reconnection be
required after a command's successful self-termination, l2_chan‐
nel_open() may be called again on the same pipe channel pointer previ‐
ously used. Stream logging will then write to the pipe channel handler,
which will forward the log messages to the given command as always. To
find out if a pipe channel has closed due to the behaviour of its com‐
mand process, the l2_channel_write() operation may be called on it with
a non-NULL message parameter, and 0 as the buffsize parameter. The
return result will be L2_OK if the channel is open. Using the C lan‐
guage, such a check might look like:
TODO NOTE FROM MICHAEL: This info will change once the pipe channel
handler is redesigned to allow for proper process termination, signal
handling of such processes, and subsequent channel closing!!!!!!!!!!!
if (l2_channel_write(pPipechannel, L2_LEVEL_NOTICE, "", 0) != L2_OK)
if (l2_channel_open(pPipechannel) != L2_OK)
exit(1); /* failure */
The command passed to the pipe channel handler may also be stopped
while still using a OSSP l2 stream log. If a command process is stopped
no action is taken until further logging occurs. As soon as the pipe
channel handler receives a message due to a l2_stream_log operation, it
will attempt to restart the stopped command process and write to its
standard input. If the effort to restart the command process fails then
the command process is considered dead, and OSSP l2 will terminate the
process and close the channel. A l2_channel_open() will then reopen the
pipe channel using configuration information previously entered with
l2_channel_configure().
It provides the following channel parameters:
command (optional, "char *")
OSSP l2 will execute the command at this user-provided path, and
pipe messages to its standard input when l2_stream_log operations
are called.
SMTP Output Channel Handler (l2_handler_smtp)
The SMTP output channel handler "l2_handler_smtp" sends the incoming
message via Simple Mail Transfer Protocol (SMTP) as an Email to a
remote mail service. It conforms to RFC 2821 (Simple Mail Transfer Pro‐
tocol; J. Klensin; April 2001) and RFC 2822 (Internet Message Format;
P. Resnick; April 2001).
It provides the following channel parameters:
progname (optional, "char *")
Arbitrary string identifying the program using OSSP l2. Default is
"NULL" which means no program identification.
localhost (optional, "char *")
Hostname of the underlying machine. Default is set through
uname(3) or "localhost".
localuser (optional, "char *")
Username corresponding to the UID of the underlying process.
Default is set through resolving getuid(2) or "uid#N".
from (optional, "char *")
Sender Email address for outgoing mails. Default is set through
localuser and localhost.
rcpt (mandatory, "char *")
Recipient Email address for outgoing mails. No default exists,
user has to provide value.
subject (optional, "char *")
Arbitrary string identifying the generated Email message. Default
is "[L2] log channel output on {localhost}".
host (mandatory, "char *")
Host name or IP address of the remote SMTP service. No default
exists, user has to provide value.
port (optional, "char *")
Port name or number of the remote SMTP service. Default is "smtp"
(25).
timeout (optional, "int")
Timeout in seconds for all I/O operations. Default is 30.
08-Jun-2007 L2 0.9.13 l2(3)
