.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Paranoid::Log 3pm"
.TH Paranoid::Log 3pm "2010-06-03" "perl v5.14.2" "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 Log.pm,v 0.14 2010/06/03 19:03:32 acorliss Exp $
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a unified interface and distribution for multiple
logging mediums.  By calling one function (\fBplog\fR) 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.
.PP
You can also use your own logging facility modules as long as you adhere to
the expected \s-1API\s0 (detailed below).  Just pass the name of the module as the
facility in \fBenableFacility\fR.
.SH "SYMBOL TAG SETS"
.IX Header "SYMBOL TAG SETS"
By default, only the following are exported:
.PP
.Vb 4
\&  enableFacility
\&  disableFacility
\&  plog
\&  psyslog
.Ve
.PP
You can get everything using \fB:all\fR, including:
.PP
.Vb 3
\&  clearLogDist 
\&  initLogDist
\&  ptimestamp
.Ve
.SH "LOGGING FACILITIES"
.IX Header "LOGGING FACILITIES"
Each logging facility is implemented as separate module consisting of
non-exported functions with conform to a a consistent \s-1API\s0.  Each
facility module must have the following functions:
.PP
.Vb 6
\&  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
.Ve
.PP
The \fBinit\fR function is only called once \*(-- the first time the module is
used and accessed.
.PP
The \fBremove\fR function allows you to remove a specific named instance of the
logging facility from use.
.PP
The \fBlog\fR function is used to actually log an entry into the facility.
.PP
The \fBdump\fR 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.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "clearLogDist"
.IX Subsection "clearLogDist"
.Vb 1
\&  clearLogDist();
.Ve
.PP
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.
.PP
This can be used to temporarily halt all logging.
.SS "initLogDist"
.IX Subsection "initLogDist"
.Vb 1
\&  initLogDist();
.Ve
.PP
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.
.PP
This can be used to re-enable logging.
.SS "enableFacility"
.IX Subsection "enableFacility"
.Vb 1
\&  $rv = enableFacility($name, $facility, $logLevel, $scope, @args);
.Ve
.PP
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.
.PP
The following facilities are available within Paranoid:
.PP
.Vb 7
\&  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
.Ve
.PP
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.
.PP
Log levels are modeled after syslog:
.PP
.Vb 11
\&  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
.Ve
.PP
If omitted level defaults to 'notice'.
.PP
Scope is defined with the following characters:
.PP
.Vb 8
\&  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
.Ve
.PP
If omitted scope defaults to '+'.
.PP
Only the first two arguments are mandatory.  What you put into the \f(CW@args\fR, and
whether you need it at all, will depend on the facility you're using.  The
facilities provided directly by \fBParanoid\fR are as follows:
.PP
.Vb 8
\&  facility        arguments
\&  =====================================================
\&  stderr          none
\&  buffer          bufferSize (optional)
\&  file            filename
\&  syslog          none
\&  email           mailhost, recipient, sender (optional), 
\&                  subject (optional)
.Ve
.SS "disableFacility"
.IX Subsection "disableFacility"
.Vb 1
\&  $rv = disableFacility($name);
.Ve
.PP
Removes the specified logging facility 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.
.SS "ptimestamp"
.IX Subsection "ptimestamp"
.Vb 1
\&  $ts = ptimestamp();
.Ve
.PP
This function returns a syslog-style timestamp string for the current time.
You can optionally give it a value as returned by \fItime()\fR and the stamp will
be for that timme.
.SS "psyslog"
.IX Subsection "psyslog"
.Vb 1
\&  $rv = psyslog($severity, $message);
.Ve
.PP
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:
.PP
.Vb 1
\&  {timestamp} {hostname} {process}[{pid}]: {message}
.Ve
.PP
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.
.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 8
\&  # 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\e@localhost", "myapp\e@localhost", 
\&    "MyApp Critical Alert");
\&
\&  # Log some messages
\&  #
\&  # Since this is only going to the debug log, we\*(Aqll 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>");
.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::Email
.IP "o" 4
.IX Item "o"
Paranoid::Log::File
.IP "o" 4
.IX Item "o"
Paranoid::Log::Syslog
.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, Arthur Corliss (corliss@digitalmages.com)