Paranoid::Log(3) Log Functions

VERSION

$Id: lib/Paranoid/Log.pm, 2.01 2016/06/23 00:34:49 acorliss Exp $

SYNOPSIS


use Paranoid::Log;
$rv = startLogger($name, $mechanism, PL_WARN, PL_GE, { %options });
$rv = stopLogger($name);
$rv = plog($severity, $message);

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.

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
  =====================================================
  Stderr          none
  Buffer          bufferSize (optional)
  File            file, mode (optional), perm (optional),
                  syslog (optional)

stopLogger

  $rv = stopLogger($name);

Removes the specified logging mechanism 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.

DEPENDENCIES

  • Paranoid::Debug
  • Paranoid::Input
  • 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>");

BUGS AND LIMITATIONS

AUTHOR

Arthur Corliss ([email protected])

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 - 2015, Arthur Corliss ([email protected])

LAST SEARCHED