Provided by: libparanoid-perl_2.10-1_all 
NAME
Paranoid::Log - Log Functions
VERSION
$Id: lib/Paranoid/Log.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $
SYNOPSIS
use Paranoid::Log;
$rv = startLogger($name, $mechanism, PL_WARN, PL_GE, { %options });
$rv = stopLogger($name);
$rv = plog($severity, $message);
$rv = plverbosity(3);
DESCRIPTION
Paranoid::Log provides a logging and message distribution framework that's modeled heavily
on syslog. It follows syslog in that it allows one to log messages at various levels of
severity and have those messages distributed across multiple log mechanisms automatically.
Within the Paranoid distribution itself it supports logging to files, STDERR, and named
buffers. Additional modules exist on CPAN to allow for distribution to e-mail, syslog,
and more. It is also relatively trivial to write your own log mechanism to work with this
framework.
IMPORT LISTS
This module exports the following symbols by default:
PL_DEBUG PL_INFO PL_NOTICE PL_WARN PL_ERR PL_CRIT
PL_ALERT PL_EMERG PL_EQ PL_NE PL_GE PL_LE
startLogger stopLogger plog plverbosity
The following specialized import lists also exist:
List Members
--------------------------------------------------------
all @defaults
LOGGING MECHANISMS
Each logging mechanism is implemented as separate module consisting of non-exported
functions that conform to a a consistent API. Each mechanism module must have the
following functions:
Function Description
------------------------------------------------------
init Called when module first loaded
addLogger Add a named instance of the mechanism
delLogger Removes a named instance of the mechanism
logMsg Logs the passed message
The init function is only called once -- the first time the module is used and accessed.
No arguments are passed, and if unnecessary for a particular mechanism it can simply
return a boolean true.
The logMsg function is used to actually pass a log message to the mechanism. It is called
with a record hash based on the following template:
my %record = (
name => $name,
mechanism => $name,
msgtime => time,
severity => $level,
scope => $scope,
message => $message,
options => {},
);
The options key will be a hash reference to any logger-specific options, should the
mechanism require one.
The addLogger function is called whenever a logger is started. It is called with the
logger record above, minus a message and msgtime.
The delLogger function is called whenevever a logger is stopped. It is called with the
logger record above, minus a message and msgtime.
Please see the source for Paranoid::Logger::File for a simple example of a mechanism
module.
SUBROUTINES/METHODS
startLogger
$rv = startLogger($name, $mechanism, PL_WARN, PL_GE, { %options });
This function enables the specified logging mechanism at the specified levels. Each
mechanism (or permutation of) is associated with an arbitrary name. This name can be used
to bypass log distribution and log only in the named mechanism.
If you have your own custom mechanism that complies with the Paranoid::Log calling
conventions you can pass this the name of the module (for example, MyLog::Foo).
Log levels are modeled after syslog:
log level description
=====================================================
PL_EMERG system is unusable
PL_ALERT action must be taken immediately
PL_CRIT critical conditions
PL_ERR error conditions
PL_WARN warning conditions
PL_NOTICE normal but significant conditions
PL_INFO informational
PL_DEBUG debug-level messages
If omitted level defaults to PL_NOTICE.
Scope is defined with the following characters:
character definition
=====================================================
PL_EQ log only messages at this severity
PL_GE log only messages at this severity
or higher
PL_LE log only messages at this severity
or lower
PL_NE log at all levels but this severity
If omitted scope defaults to PL_GE.
Only the first two arguments are mandatory. What you put into the %options, and whether
you need it at all, will depend on the mechanism you're using. The facilities provided
directly by Paranoid are as follows:
mechanism arguments
=====================================================
Stdout none
Stderr none
Buffer bufferSize (optional)
File file, mode (optional), perm (optional),
syslog (optional)
PDebug none
stopLogger
$rv = stopLogger($name);
Removes the specified logging mechanism from the configuration and re-initializes the
distribution processor.
plog
$rv = plog($severity, $message);
# If the PDebug mechanism is enabled
$rv = plog($severity, $message, @substitutions);
This call logs the passed message to all facilities enabled at the specified log level.
If you have PDebug enabled as a mechanism this function can also provide an equivalent
sprintf functionality using the additional arguments, and that processed output will be
shared with all other mechanisms that are enabled.
NOTE: PDebug support is meant to be a convenience to unify both normal logging and the
Paranoid::Debug::pdebug STDERR tracing mechanism. That said, note than enabling it means
that all log messages are passed to pdebug, since it has its own mechanism for deciding
what gets sent to STDERR or not.
PDebug support may not make sense for if your logging and debug output can't be neatly
lined up with the syslog-styled severities.
plverbosity
$rv = plverbosity($level);
This function provides a simpler way to enable Stdout/Stderr logging to the appropriate
level, if you consider PL_DEBUG to PL_NOTICE to be normal operation messages appropriate
for STDOUT messages, and PL_WARN through PL_EMERG to be error messages appropriate for
STDERR.
This is primarily a convenience function for those simple, non-interactive
programs/functions that need support varying levels of verbosity for the console. From
that perspective, it will be assumed that all user notifications would be simple one-line
messages.
NOTE: PL_EMERG and PL_ALERT are always enabled if you use this function. Any error
messages that should always be printed to the console regardless of verbosity settings
should be sent to one of those two levels. The remaining levels (PL_WARN through PL_CRIT)
will be optionally enabled, just like PL_DEBUG> through PL_NOTICE.
DEPENDENCIES
o Paranoid::Debug
o Paranoid::Input
o Paranoid::Module
EXAMPLES
The following example provides the following behavior: debug messages go to a file,
notice & above messages go to syslog, and critical and higher messages also go to console
and e-mail.
# Set up the logging facilities
startLogger("debug-log", "File", PL_DEBUG, PL_GE,
{ file => '/var/log/myapp-debug.log' });
startLogger("console-err", "Stderr", PL_CRIT, PL_GE);
# This goes only to the debug log
plog(PL_DEBUG, "Starting application");
# Again, only the debug log
plog(PL_NOTICE, "Uh, something happened...");
# This goes to STDERR and the debug log
plog(PL_EMERG, "Ack! <choke... silence>");
SEE ALSO
o Paranoid::Log::Buffer
o Paranoid::Log::File
BUGS AND LIMITATIONS
AUTHOR
Arthur Corliss (corliss@digitalmages.com)
LICENSE AND COPYRIGHT
This software is free software. Similar to Perl, you can redistribute it and/or modify it
under the terms of either:
a) the GNU General Public License
<https://www.gnu.org/licenses/gpl-1.0.html> as published by the
Free Software Foundation <http://www.fsf.org/>; either version 1
<https://www.gnu.org/licenses/gpl-1.0.html>, or any later version
<https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
b) the Artistic License 2.0
<https://opensource.org/licenses/Artistic-2.0>,
subject to the following additional term: No trademark rights to "Paranoid" have been or
are conveyed under any of the above licenses. However, "Paranoid" may be used fairly to
describe this unmodified software, in good faith, but not as a trademark.
(c) 2005 - 2020, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 - 2020, Paranoid Inc.
(www.paranoid.com)