corosync/man/logsys_overview.8

.\"/*
.\" * Copyright (c) 2007-2009 Red Hat, Inc.
.\" *
.\" * All rights reserved.
.\" *
.\" * Author: Steven Dake (sdake@redhat.com)
.\" * Author: Fabio M. Di Nitto (fdinitto@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 2009-06-16 "corosync Man Page" "Corosync Cluster Engine Programmer's Manual"
.SH NAME
logsys_overview \- Logsys Library Overview
.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, 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>

... (other #includes)

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 */


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

.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:
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 %d\n", string, value);

Tracing of functions can be done using ENTER(), LEAVE();

An example of using ENTER is
void function (char *name) {
ENTER();
... function contents ...
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 %s\n", name);

Note that ENTER/LEAVE/TRACE* calls are recorded only in the flight recorder.

.SH "SEE ALSO"
.BR logsys_fork_completed (3),
.BR logsys_atexit (3),
.BR logsys_log_rec_store (3),
.BR logsys_format_set (3),
.BR logsys_format_get (3),
.BR logsys_config_mode_set (3),
.BR logsys_config_file_set (3),
.BR logsys_config_syslog_facility_set (3),
.BR logsys_config_syslog_facility_get (3),
.BR logsys_config_mode_set (3),
.BR logsys_config_mode_get (3),
.BR logsys_config_file_set (3),
.BR logsys_config_logfile_priority_set (3),
.BR logsys_config_debug_set (3),
.BR logsys_facility_id_get (3),
.BR logsys_facility_name_get (3),
.BR logsys_priority_id_get (3),
.BR logsys_priority_name_get (3),
.PP