logsys_overview

Langue: en

Version: 2007-05-15 (fedora - 06/07/09)

Section: 8 (Commandes administrateur)

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 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 declaration 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 declaration 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_SHORT_FILELINE: When using LOG_DEBUG level or LOG_MODE_DISPLAY_FILELINE, typically the absolute path to the file (derived at compile-time) is displayed. Enabling this flag ensures that only the filename and line are displayed. LOG_MODE_DISPLAY_TIMESTAMP: Output the timestamp of the message. 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 declaration is specified in the declaration 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. LOG_MODE_NOSUBSYS: Enabling this mode removes the subsystem tag from the beginning of the log lines. This is not recommended for programs which have multiple subsystems. LOG_MODE_FILTER_DEBUG_FROM_SYSLOG: Enabling this mode will stop debug messages from being sent to syslog.

An example declaration would be:

#include <corosync/logsys.h>

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.

Declaration of subsystems or no subsystems

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 declaration is specified within will be logged to the SYS1 subsystem identifier.

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: 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, 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(); LEAVE_VOID(); }

An example of using ENTER is void function (char *name) { ENTER ("The name is %s, name); LEAVE ("Bye); }

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, name);

SEE ALSO

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),