NAME
Paraniod::Log - Log Functions
MODULE VERSION
$Id: Log.pm,v 0.9 2008/02/27 06:49:23 acorliss Exp $
SYNOPSIS
use Paranoid::Log;
clearLogDist();
initLogDist();
$rv = enableFacility($name, $facility, $logLevel, $scope, @args);
$rv = disableFacility($name);
$rv = plog($severity, $message);
$rv = psyslog($severity, $message);
# The following functions are not exported by default
clearLogDist();
initLogDist();
$timeStamp = ptimestamp();REQUIREMENTS
Paranoid::Debug
Paranoid::Module
DESCRIPTION
This module provides a unified interface and distribution for multiple logging mediums. By calling one function (plog) you can have that message stored in multiple mediums depending on what you've enabled at what severities. For instance, you could have a critical message not only automatically logged in a log file and syslog, but it could also generate an e-mail.
You can also use your own logging facility modules as long as you adhere to the expected API (detailed below). Just pass the name of the module as the facility in enableFacility.
LOGGING FACILITIES
Each logging facility is implemented as separate module consisting of non-exported functions with conform to a a consistent API. Each facility module must have the following functions:
Function Description
------------------------------------------------------
init Called when module first loaded
remove Removes a named instance of the facility
log Logs the passed message
dump Dumps internal informationThe init function is only called once -- the first time the module is used and accessed.
The remove function allows you to remove a specific named instance of the logging facility from use.
The log function is used to actually log an entry into the facility.
The dump function is used to dump pertinent internal data on the requested named instance. This is primarily intended for use with facilities like the log buffer, in which case it dumps the contents of the named buffer. Other uses for this is left to the developer of individual facility modules.
FUNCTIONS
clearLogDist
clearLogDist();This empties all enabled loggers from the distribution processor. It doesn't erase any named logging facilities already put into place, simply takes out of the distribution system so no further log entries will be processed.
This can be used to temporarily halt all logging.
initLogDist
initLogDist();This goes through the list of named loggers and sets up the distribution processor to feed them the applicable log entries as they come in.
This can be used to re-enable logging.
enableFacility
$rv = enableFacility($name, $facility, $logLevel, $scope, @args);This function enables the specified logging facility at the specified levels. Each facility (or permutation of) is associated with an arbitrary name. This name can be used to bypass log distribution and log only in the named facility.
The following facilities are available within Paranoid:
facility description
=====================================================
stderr prints messages to STDERR
buffer stores messages in a named buffer
file prints messages to a file
syslog sends message to the syslog daemon
email sends message to an e-mail recipientIf you have your own custom facility that complies with the Paranoid::Log calling conventions you can pass this the name of the module (for example, Log::Foo). The first letter of the module will always be uppercased before attempting to load it.
Log levels are modeled after syslog:
log level description
=====================================================
emerg, panic system is unusable
alert action must be taken immediately
crit critical conditions
err, error error conditions
warn, warning warning conditions
notice normal but significant conditions
info informational
debug debug-level messagesIf omitted level defaults to 'notice'.
Scope is defined with the following characters:
character definition
=====================================================
= log only messages at this severity
+ log only messages at this severity
or higher
- log only messages at this severity
or lowerIf omitted scope defaults to '+'.
Only the first two arguments are mandatory. What you put into the @args, and whether you need it at all, will depend on the facility you're using. The facilities provided directly by Paranoid are as follows:
facility arguments
=====================================================
stderr none
buffer bufferSize (optional)
file filename
syslog none
email mailhost, recipient, sender (optional),
subject (optional)disableFacility
$rv = disableFacility($name)Removes the specified logging facility from the configuration and re-initializes the distribution processor.
plog
$rv = plog($severity, $message);This call logs the passed message to all facilities enabled at the specified log level.
ptimestamp
$ts = ptimestamp();This function returns a syslog-style timestamp string for the current time. You can optionally give it a value as returned by time() and the stamp will be for that timme.
psyslog
$rv = psyslog($severity, $message);This function's name may be a bit misleading. This does not cause the message to be syslogged (that's the duty of the syslog facility), but rather the message is logged in a syslog-style format according to the following template:
{timestamp} {hostname} {process}[{pid}]: {message}You may want to use this if you're using, say, a file logging mechanism but you still want the logs in a syslog-styled format.
EXAMPLES
Enabling various facilities
# STDERR facility
$rv = enableFacility("console-err", "stderr", "warn", "+");
# Log buffer w/100 message capacity
$rv = enableFacility("buffer1", "buffer", "warn", "=", 100);
# Log file (/var/log/app-debug.log)
$rv = enableFacility("debug", "file", "warn", "=",
"/var/log/app-debug.log");
# Syslog under mail facility
$rv = enableFacility("mail", "syslog", "warn", "+");
# E-mail critical or higher errs
$rv = enableFacility("mail", "email", "crit", "+", "localhost",
'root@localhost', undef, 'Critical Alert');HISTORY
None as of yet.
AUTHOR/COPYRIGHT
(c) 2005 Arthur Corliss (corliss@digitalmages.com)