logsys_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

Declartion of logging system or subsystem without calling any functions

Dynamic reconfiguration of the logging system parameters

Logging to syslog, file, stderr.

The logsys library is initially configured by including logsys.h and declaring a logger. Once the logger is declared either a subsystem logger or nosubsystem logger is declared in every file. The definition LOGSYS_DECLARE_SYSTEM is placed after the include section of one C file in the application. This declartion creates a constructor function which will be called automatically. This technique avoids the need for calling any setup functions in short applications that don't require it. #define LOGSYS_DECLARE_SYSTEM(name,mode,file,facility) The name parameter is the name of the application. The mode parameter is the logging mode of the system. The following modes can be configured by logically ORing these flags: LOG_MODE_OUTPUT_FILE: Output all log data to the file parameter of this declartion LOG_MODE_OUTPUT_STDERR: Output all log data to the stderr descriptor LOG_MODE_OUTPUT_SYSLOG_THREADED: Output all log data to syslog using a non-blocking thread LOG_MODE_OUTPUT_SYSLOG_LOSSY: Output all log data without using a thread but potentially losing data. This mode is not yet implemented. LOG_MODE_OUTPUT_SYSLOG_BLOCKING: Output all log data without using a thread and potentially blocking at each syslog call. LOG_MODE_DISPLAY_PRIORITY: Output the priority of the log entry in the message contents. This mode is currently not implemented. LOG_MODE_DISPLAY_FILELINE: Output the file and line at which the log message was created. LOG_MODE_DISPLAY_TIMESTAMP: Output the timestamp of the message. LOG_MODE_DISPLAY_DEBUG: Display debug level messages LOG_MODE_BUFFER_BEFORE_CONFIG: This mode is used to buffer log messages before logsys_mode_config is called. This is useful in applications in which the logging file isn't known before the application is compiled and must be set dynamically. It is also useful when an application calls fork to disconnect the local tty and should hold logging of messages until after the fork. LOG_MODE_FLUSH_AFTER_CONFIG: This mode is used to flush any buffered messages when the LOG_MODE_BUFFER_BEFORE_CONFIG declartion is specified in the declartion of the logger. The file parameter specifies the filename that should be used to log messages. This parameter may be NULL if LOG_MODE_OUTPUT_FILE is not specified. The facility parameter is the syslog facility that should be used when logging messages. An example declartion would be: #include <openais/logsys.h> ... (other #includes) LOGSYS_DECLARE_SYSTEM ("my_example_app", LOG_MODE_OUTPUT_STDERR | LOG_MODE_OUTPUT_SYSLOG_THREADED | LOG_MODE_OUTPUT_FILE, "/tmp/log", LOG_DAEMON); This would output any logging messages to stderr, syslog, and the file /tmp/log.

The logsys library supports the logging of information to one main system or subsystem. This is specified in each individual object file in the system. if no subsystems are desired, The define LOGSYS_DECLARE_NOSUBSYS should be declared for every object file in the system. These object files are usually C files. An example of using this would be LOGSYS_DECLARE_NOSUBSYS (LOG_LEVEL_INFO); Any messages of LOG_LEVEL_INFO priority or higher would be logged. If subsystems are desired, the define LOGSYS_DECLARE_SUBSYS should be declared for every object file in the system. 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. An example of using this would be LOGSYS_DECLARE_SUBSYS ("SYS1", LOG_LEVEL_INFO); Any message of LOG_LEVEL_INFO priority or higher would be logged and any logging within the object file this declartion is specified within will be logged to the SYS1 subsystem identifier.

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: LOG_EMERG LOG_ALERT LOG_CRIT LOG_ERR LOG_WARNING LOG_NOTICE LOG_INFO LOG_DEBUG An example of using log_printf would be log_printf (LOG_EMERG, "This is an emergency %s value %d\n", string, value); Tracing of functions can be done using ENTER_VOID() or ENTER (format, args) LEAVE_VOID() or LEAVE (format, args); An exmaple of using ENTER_VOID is void funtion (void) { ENTER_VOID(); ... function contents ... LEAVE_VOID(); } An example of using ENTER is void function (char *name) { ENTER ("The name is %s\n", name); ... function contents ... LEAVE ("Bye\n"); } 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 %s\n", name);

logsys_config_mode_set(3), logsys_config_file_set(3), logsys_config_facility_set(3), logsys_config_facility_set(3), logsys_config_priority_set(3), logsys_config_subsys_set(3), logsys_config_subsys_get(3), logsys_facility_id_get(3), logsys_priority_id_get(3), logsys_flush(3), logsys_atsegv(3),