Provided by: libparanoid-perl_2.07-1_all bug


       Paranoid::Log - Log Functions


       $Id: lib/Paranoid/, 2.07 2019/01/30 18:25:27 acorliss Exp $


         use Paranoid::Log;

         $rv = startLogger($name, $mechanism, PL_WARN, PL_GE, { %options });
         $rv = stopLogger($name);

         $rv = plog($severity, $message);


       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


       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


         $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

         $rv = stopLogger($name);

       Removes the specified logging mechanism from the configuration and re-initializes the
       distribution processor.

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

           $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

       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


       o   Paranoid::Debug

       o   Paranoid::Input

       o   Paranoid::Module


       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>");


       o   Paranoid::Log::Buffer

       o   Paranoid::Log::File



       Arthur Corliss (


       This software is licensed under the same terms as Perl, itself.  Please see for more information.

       (c) 2005 - 2017, Arthur Corliss (