corosync/man/logsys_overview.8

.\"/*
.\" * Copyright (c) 2007 Red Hat, Inc.
.\" *
.\" * All rights reserved.
.\" *
.\" * Author: Steven Dake (sdake@redhat.com)
.\" *
.\" * This software licensed under BSD license, the text of which follows:
.\" * 
.\" * Redistribution and use in source and binary forms, with or without
.\" * modification, are permitted provided that the following conditions are met:
.\" *
.\" * - Redistributions of source code must retain the above copyright notice,
.\" *   this list of conditions and the following disclaimer.
.\" * - Redistributions in binary form must reproduce the above copyright notice,
.\" *   this list of conditions and the following disclaimer in the documentation
.\" *   and/or other materials provided with the distribution.
.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
.\" *   contributors may be used to endorse or promote products derived from this
.\" *   software without specific prior written permission.
.\" *
.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
.\" * THE POSSIBILITY OF SUCH DAMAGE.
.\" */
.TH LOGSYS_OVERVIEW 8 2007-05-15 "corosync Man Page" "Corosync Cluster Engine Programmer's Manual"
.SH OVERVIEW
The logsys library provides a generically usable logging and tracing system for
use by applications.  It supports many features including:
.PP
Configurable subsystem logging or single system logging
.PP
Threaded non-blocking logging of log output data for better non-blocking performance
.PP
Support for 8 tracing levels and tracing the entering and leaving of functions
.PP
Declaration of logging system or subsystem without calling any functions
.PP
Dynamic reconfiguration of the logging system parameters
.PP
Logging to syslog, file, stderr.

.SH 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>

... (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.

.SH 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.

.SH 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\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);

.SH "SEE ALSO"
.BR logsys_config_mode_set (3),
.BR logsys_config_file_set (3),
.BR logsys_config_facility_set (3),
.BR logsys_config_facility_set (3),
.BR logsys_config_priority_set (3),
.BR logsys_config_subsys_set (3),
.BR logsys_config_subsys_get (3),
.BR logsys_facility_id_get (3),
.BR logsys_priority_id_get (3),
.BR logsys_flush (3),
.BR logsys_atsegv (3),
.PP