.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 2024-03-07 "perl v5.38.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 lib/Paranoid/Log.pm, 2.10 2022/03/08 00:01:04 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); \& \& $rv = plverbosity(3); .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, 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. .SH "IMPORT LISTS" .IX Header "IMPORT LISTS" This module exports the following symbols by default: .PP .Vb 3 \& PL_DEBUG PL_INFO PL_NOTICE PL_WARN PL_ERR PL_CRIT \& PL_ALERT PL_EMERG PL_EQ PL_NE PL_GE PL_LE \& startLogger stopLogger plog plverbosity .Ve .PP The following specialized import lists also exist: .PP .Vb 3 \& List Members \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& all @defaults .Ve .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 API. 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 \fIPL_NOTICE\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 \fIPL_GE\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 8 \& mechanism arguments \& ===================================================== \& Stdout none \& Stderr none \& Buffer bufferSize (optional) \& File file, mode (optional), perm (optional), \& syslog (optional) \& PDebug none .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); \& \& # If the PDebug mechanism is enabled \& $rv = plog($severity, $message, @substitutions); .Ve .PP This call logs the passed message to all facilities enabled at the specified log level. If you have \fBPDebug\fR 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. .PP \&\fBNOTE:\fR \fIPDebug\fR support is meant to be a convenience to unify both normal logging and the Paranoid::Debug::pdebug \fBSTDERR\fR tracing mechanism. That said, note than enabling it means that \fBall\fR log messages are passed to pdebug, since it has its own mechanism for deciding what gets sent to \&\fBSTDERR\fR or not. .PP \&\fIPDebug\fR support may not make sense for if your logging and debug output can't be neatly lined up with the syslog-styled severities. .SS plverbosity .IX Subsection "plverbosity" .Vb 1 \& $rv = plverbosity($level); .Ve .PP This function provides a simpler way to enable \fBStdout\fR/\fBStderr\fR logging to the appropriate level, if you consider \fBPL_DEBUG\fR to \fBPL_NOTICE\fR to be normal operation messages appropriate for \fBSTDOUT\fR messages, and \fBPL_WARN\fR through \fBPL_EMERG\fR to be error messages appropriate for \fBSTDERR\fR. .PP 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 messages. .PP \&\fBNOTE:\fR \fIPL_EMERG\fR and \fIPL_ALERT\fR are always enabled if you use this function. Any error messages that should always be printed to the console regardless of verbosity settings should be sent to one of those two levels. The remaining levels (\fIPL_WARN\fR through \fIPL_CRIT\fR) will be optionally enabled, just like \fIPL_DEBUG\fR> through \fIPL_NOTICE\fR. .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! "); .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 free software. Similar to Perl, you can redistribute it and/or modify it under the terms of either: .PP .Vb 7 \& a) the GNU General Public License \& as published by the \& Free Software Foundation ; either version 1 \& , or any later version \& , or \& b) the Artistic License 2.0 \& , .Ve .PP subject to the following additional term: No trademark rights to "Paranoid" have been or are conveyed under any of the above licenses. However, "Paranoid" may be used fairly to describe this unmodified software, in good faith, but not as a trademark. .PP (c) 2005 \- 2020, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 \- 2020, Paranoid Inc. (www.paranoid.com)