NAME
logsys_overview - Logsys Library Overview
OVERVIEW
The logsys library provides a generically usable logging and tracing
system for use by applications. It supports many features including:
Configurable subsystem logging or single system logging
Threaded non-blocking logging of log output data for better non-
blocking performance
Support for 8 tracing levels and tracing the entering and leaving of
functions
Declaration of logging system or subsystem without calling any
functions
Dynamic reconfiguration of the logging system parameters
Logging to syslog, file, stderr.
Declaration of the System logger
The logsys library is initially configured by including logsys.h and
declaring a logger. Once the logger is declared, optional subsystem
loggers can be declared in every file.
The definition LOGSYS_DECLARE_SYSTEM is placed after the include
section of one C file in the application. This declaration creates a
constructor function which will be called automatically before main()
is executed. This technique avoids the need for calling any setup
functions in short applications that don’t require it and enables full
logging capabilities before any application code is executed.
#define LOGSYS_DECLARE_SYSTEM (name, mode, debug, file, file_priority,
syslog_facility, syslog_priority, format, fltsize)
The name parameter is the name of the application or system.
The mode parameter is the logging mode of the system. The following
modes can be configured by logically ORing these flags:
LOGSYS_MODE_OUTPUT_FILE: Output all log data to the file parameter of
this declaration
LOGSYS_MODE_OUTPUT_STDERR: Output all log data to the stderr descriptor
LOGSYS_MODE_OUTPUT_SYSLOG: Output all log data to syslog using a non-
blocking thread
LOGSYS_MODE_FORK: This flags tells logsys to queue all data untill the
application has forked. The application is then responsible to call
logsys_fork_completed to flush the queue and start logging.
LOGSYS_MODE_THREADED: Starts a separate thread to handle non-blocking
logging operations. If this flag is not specified, the logging
operations are blocking.
The debug parameter, if enabled, turns off all messages priority
filtering, recording everything everywhere.
The file parameter specifies the filename that should be used to log
messages. This parameter may be NULL and no log file will be created.
The file_priority parameter specifies the message priority that should
be logged to file.
The syslog_facility parameter is the syslog facility that should be
used when logging messages.
The syslog_priority, similar to file_priority, specifies the message
priority that should be logged to syslog.
The format parameter allows to set custom output format. Set to NULL
to use built-in default.
The fltsize parameter specifies the flight recorder buffer size in
bytes. The requested value is increased by the size of 2 unsigned ints
and rounded to the next PAGE_SIZE.
An example declaration would be:
#include <corosync/logsys.h>
LOGSYS_DECLARE_SYSTEM ("test", /* name */
LOGSYS_MODE_OUTPUT_STDERR | LOGSYS_MODE_THREADED, /* mode */
0, /* debug */
NULL, /* logfile
path */
LOGSYS_LEVEL_INFO, /*
logfile_priority */
LOG_DAEMON, /* syslog
facility */
LOGSYS_LEVEL_INFO, /* syslog
level */
NULL, /* use
default format */
1000000); /* flight
recorder size */
Declaration of subsystems
The logsys library supports the logging of information to one main
system or subsystem. This is specified in each individual object C
file in the system and it is entirely optional.
An example:
LOGSYS_DECLARE_SUBSYS ("subsystest");
It is possible to use the same subsystem name in separate object files.
In this case, the individual logging parameters for those subsystem
identifier will be used.
A newly created subsystem inherits the system configuration at the time
of creation.
It is possible to override every configuration option on a subsystem
base throught the configuration API.
Logging Messages
The definition log_printf is used to log information to the log. It
works in a similiar fashion to printf, except it has a first parameter
of level which may be the following: LOGSYS_LEVEL_EMERG
LOGSYS_LEVEL_ALERT LOGSYS_LEVEL_CRIT LOGSYS_LEVEL_ERR
LOGSYS_LEVEL_WARNING LOGSYS_LEVEL_NOTICE LOGSYS_LEVEL_INFO
LOGSYS_LEVEL_DEBUG
An example of using log_printf would be
log_printf (LOGSYS_LEVEL_EMERG, "This is an emergency %s value %d0,
string, value);
Tracing of functions can be done using ENTER(), LEAVE();
An example of using ENTER is void function (char *name) { ENTER();
LEAVE(); }
Individual tracing levels are supported through the macros
TRACE1(format, args) TRACE2(format, args) TRACE8(format, args)
An example of using TRACE is
char *name = "test"; TRACE7 ("This is a trace 7 log with name %s0,
name);
Note that ENTER/LEAVE/TRACE* calls are recorded only in the flight
recorder.
SEE ALSO
logsys_fork_completed(3), logsys_atexit(3), logsys_log_rec_store(3),
logsys_format_set(3), logsys_format_get(3), logsys_config_mode_set(3),
logsys_config_file_set(3), logsys_config_syslog_facility_set(3),
logsys_config_syslog_facility_get(3), logsys_config_mode_set(3),
logsys_config_mode_get(3), logsys_config_file_set(3),
logsys_config_logfile_priority_set(3), logsys_config_debug_set(3),
logsys_facility_id_get(3), logsys_facility_name_get(3),
logsys_priority_id_get(3), logsys_priority_name_get(3),