LOGSYS_OVERVIEW(8)         Corosync Cluster Engine Programmer's Manual         LOGSYS_OVERVIEW(8)



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 capa‐
       bilities 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  config‐
       ured 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 mes‐
       sages.

       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_con‐
       fig_syslog_facility_set(3),       logsys_config_syslog_facility_get(3),        logsys_con‐
       fig_mode_set(3),  logsys_config_mode_get(3), logsys_config_file_set(3), logsys_config_log‐
       file_priority_set(3), logsys_config_debug_set(3), logsys_facility_id_get(3), logsys_facil‐
       ity_name_get(3), logsys_priority_id_get(3), logsys_priority_name_get(3),

corosync Man Page                           2009-06-16                         LOGSYS_OVERVIEW(8)