.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Paranoid::Log 3pm"
.TH Paranoid::Log 3pm "2018-11-09" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Paranoid::Log \- Log Functions
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR lib/Paranoid/Log.pm, 2.06 2018/08/05 01:21:48 acorliss Exp $
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Paranoid::Log;
\&
\&  $rv = startLogger($name, $mechanism, PL_WARN, PL_GE, { %options });
\&  $rv = stopLogger($name);
\&
\&  $rv = plog($severity, $message);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBParanoid::Log\fR provides a logging and message distribution framework that's
modeled heavily on \fIsyslog\fR.  It follows \fIsyslog\fR 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, \s-1STDERR,\s0 and named buffers.
Additional modules exist on \s-1CPAN\s0 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.
.SH "LOGGING MECHANISMS"
.IX Header "LOGGING MECHANISMS"
Each logging mechanism is implemented as separate module consisting of
non-exported functions that conform to a a consistent \s-1API.\s0  Each
mechanism module must have the following functions:
.PP
.Vb 6
\&  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
.Ve
.PP
The \fBinit\fR 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.
.PP
The \fBlogMsg\fR function is used to actually pass a log message to the 
mechanism.  It is called with a record hash based on the following template:
.PP
.Vb 9
\&        my %record  = (
\&            name      => $name,
\&            mechanism => $name,
\&            msgtime   => time,
\&            severity  => $level,
\&            scope     => $scope,
\&            message   => $message,
\&            options   => {},
\&            );
.Ve
.PP
The options key will be a hash reference to any logger-specific options,
should the mechanism require one.
.PP
The \fBaddLogger\fR function is called whenever a logger is started.  It is
called with the logger record above, minus a message and msgtime.
.PP
The \fBdelLogger\fR function is called whenevever a logger is stopped.  It is
called with the logger record above, minus a message and msgtime.
.PP
Please see the source for Paranoid::Logger::File for a simple example of a
mechanism module.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "startLogger"
.IX Subsection "startLogger"
.Vb 1
\&  $rv = startLogger($name, $mechanism, PL_WARN, PL_GE, { %options });
.Ve
.PP
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.
.PP
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).
.PP
Log levels are modeled after syslog:
.PP
.Vb 10
\&  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
.Ve
.PP
If omitted level defaults to \fI\s-1PL_NOTICE\s0\fR.
.PP
Scope is defined with the following characters:
.PP
.Vb 8
\&  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
.Ve
.PP
If omitted scope defaults to \fI\s-1PL_GE\s0\fR.
.PP
Only the first two arguments are mandatory.  What you put into the \f(CW%options\fR, 
and whether you need it at all, will depend on the mechanism you're using.  The
facilities provided directly by \fBParanoid\fR are as follows:
.PP
.Vb 6
\&  mechanism        arguments
\&  =====================================================
\&  Stderr          none
\&  Buffer          bufferSize (optional)
\&  File            file, mode (optional), perm (optional),
\&                  syslog (optional)
.Ve
.SS "stopLogger"
.IX Subsection "stopLogger"
.Vb 1
\&  $rv = stopLogger($name);
.Ve
.PP
Removes the specified logging mechanism from the configuration and
re-initializes the distribution processor.
.SS "plog"
.IX Subsection "plog"
.Vb 1
\&  $rv = plog($severity, $message);
.Ve
.PP
This call logs the passed message to all facilities enabled at the specified
log level.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "o" 4
.IX Item "o"
Paranoid::Debug
.IP "o" 4
.IX Item "o"
Paranoid::Input
.IP "o" 4
.IX Item "o"
Paranoid::Module
.SH "EXAMPLES"
.IX Header "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.
.PP
.Vb 4
\&  # Set up the logging facilities
\&  startLogger("debug\-log", "File", PL_DEBUG, PL_GE,
\&    { file => \*(Aq/var/log/myapp\-debug.log\*(Aq });
\&  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>");
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "o" 4
.IX Item "o"
Paranoid::Log::Buffer
.IP "o" 4
.IX Item "o"
Paranoid::Log::File
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Corliss (corliss@digitalmages.com)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This software is licensed under the same terms as Perl, itself. 
Please see http://dev.perl.org/licenses/ for more information.
.PP
(c) 2005 \- 2017, Arthur Corliss (corliss@digitalmages.com)