Paranoid::Log(3pm)					User Contributed Perl Documentation					Paranoid::Log(3pm)

NAME

       Paranoid::Log - Log Functions

VERSION

       $Id: Log.pm,v 0.14 2010/06/03 19:03:32 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();

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.

SYMBOL TAG SETS

       By default, only the following are exported:

	 enableFacility
	 disableFacility
	 plog
	 psyslog

       You can get everything using :all, including:

	 clearLogDist
	 initLogDist
	 ptimestamp

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 information

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

SUBROUTINES
/METHODS
   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 recipient

       If 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
	 emergency
	 alert		 action must be taken immediately
	 crit, critical  critical conditions
	 err, error	 error conditions
	 warn, warning	 warning conditions
	 notice 	 normal but significant conditions
	 info		 informational
	 debug		 debug-level messages

       If 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 lower
	 !		 log at all levels but this severity

       If 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.  More often
       than not, though, you do not want to use this function.

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
	 enableFacility("debug", "file", "debug", "=",
	   "/var/log/myapp-debug.log");
	 enableFacility("daemon", "syslog", "notice", "+", "myapp");
	 enableFacility("console-err", "stderr", "critical", "+");
	 enableFacility("smtp-err", "email", "critical", "+",
	   "localhost", "root@localhost", "myapp@localhost",
	   "MyApp Critical Alert");

	 # Log some messages
	 #
	 # Since this is only going to the debug log, we'll use psyslog
	 # so we get the timestamps, etc.
	 psyslog("debug", "Starting application");

	 # Log a notification
	 plog("notice", "Uh, something happened...");

	 # Log a critical error
	 plog("emerg", "Ack! <choke... silence>");

SEE ALSO

       o   Paranoid::Log::Buffer

       o   Paranoid::Log::Email

       o   Paranoid::Log::File

       o   Paranoid::Log::Syslog

BUGS AND LIMITATIONS

AUTHOR

       Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT

       This software is licensed under the same terms as Perl, itself.	Please see http://dev.perl.org/licenses/ for more information.

       (c) 2005, Arthur Corliss (corliss@digitalmages.com)

perl v5.14.2							    2010-06-03							Paranoid::Log(3pm)