This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Log/Agent/Channel/Syslog, Next: Log/Agent/Driver, Prev: Log/Agent/Channel/Handle, Up: Module List syslog logging channel for Log::Agent::Logger ********************************************* NAME ==== Log::Agent::Channel::Syslog - syslog logging channel for Log::Agent::Logger SYNOPSIS ======== require Log::Agent::Channel::Syslog; my $channel = Log::Agent::Channel::Syslog->make( # Specific attributes -prefix => prefix, -facility => "user", -showpid => 1, -socktype => "unix", -logopt => "ndelay", ); DESCRIPTION =========== The syslog logging channels directs operations to syslog() via the Sys::Syslog(3) interface. The creation routine make() takes the following switches: `-facility' => facility Tell syslog() which facility to use (e.g. "user", "auth", "daemon"). Unlike the Sys::Syslog(3) interface, the facility is set once and for all: every message logged through this channel will use the same facility. `-logopt' => *syslog options* Specifies logging options, under the form of a string containing zero or more of the words *ndelay*, *cons* or nowait. `-prefix' => prefix The prefix here is syslog's identification string. `-showpid' => flag Set to true to have the PID of the process logged. It is false by default. `-socktype' => (*unix* | *inet*) Specifies the logging socket type to use. The default behaviour is to use Sys:Syslog's default. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::Logger(3).  File: pm.info, Node: Log/Agent/Driver, Next: Log/Agent/Driver/Datum, Prev: Log/Agent/Channel/Syslog, Up: Module List ancestor class for all Log::Agent drivers ***************************************** NAME ==== Log::Agent::Driver - ancestor class for all Log::Agent drivers SYNOPSIS ======== @Log::Agent::Driver::XXX::ISA = qw(Log::Agent::Driver); DESCRIPTION =========== The Log::Agent::Driver class is the root class from which all Log::Agent drivers inherit. It is a *deferred* class, meaning that it cannot be instantiated directly. All the deferred routines need to be implemented by its heirs to form a valid driver. A *deferred* routine is a routine whose signature and semantics (pre and post conditions, formally) are specified, but not implemented. It allows specification of high-level processings in terms of them, thereby factorizing common code in the ancestors without loosing specialization benefits. DRIVER LIST =========== The following drivers are currently fully implemented: Log::Agent::Driver::Default This is the default driver which remaps to simple print(), warn() and die() Perl calls. Log::Agent::Driver::File This driver redirects logs to files. Each logging channel may go to a dedicated file. Log::Agent::Driver::Silent Silence all the logxxx() routines. Log::Agent::Driver::Syslog This driver redirects logs to the syslogd(8) daemon, which will then handle the dispatching to various logfiles, based on its own configuration. INTERFACE ========= You need not read this section if you're only using Log::Agent. However, if you wish to implement another driver, then you should probably read it a few times. The following routines are *deferred* and therefore need to be defined by the heir: channel_eq($chan1, $chan2) Returns true when both channels $chan1 and $chan2 send their output to the same place. The purpose is not to have a 100% accurate comparison, which is almost impossible for the Log::Agent::Driver::File driver, but to reasonably detect similarities to avoid duplicating messages to the same output when Devel::Datum is installed and activated. write($channel, $priority, $logstring) Emit the log entry held in $logstring, at priority $priority and through the specfied $channel name. A trailing "\n" is to be added if needed, but the $logstring should not already have one. The $channel name is just a string, and it is up to the driver to map that name to an output device using its own configuration information. The generic logxxx() routines use only error, output or debug for channel names. The $priority entry is assumed to have passed through the map_pri() routine, which by default returns an empty string (only the Log::Agent::Driver::Syslog driver needs a priority, for now). Ignore if you don't need that, or redefine map_pri(). The $logstring may not really be a plain string. It can actually be a Log::Agent::Message object with an overloaded stringification routine, so the illusion should be complete. make This is the creation routine. Its signature varies for each driver, naturally. prefix_msg($str) Prefix the log message string (a Log::Agent::Message object) with driver-specific information (like the configured prefix, the PID of the process, etc...). Must return the prefixed string, either as a Log::Agent::Message object or as a plain string. This means you may use normal string operations on the $str variable and let the overloaded stringification perform its magic. Or you may return the $str parameter without modification. There is no default implementation here because this is too driver-specific to choose one good default. And I like making things explicit sometimes. The following routines are implemented in terms of write(), map_pri() and prefix_msg(). The default implementation may need to be redefined for performance or tuning reasons, but simply defining the deferred routines above should bring a reasonable behaviour. As an example, here is the default logsay() implementation, which uses the emit() wrapper (see below): sub logsay { my $self = shift; my ($str) = @_; $self->emit('output', 'notice', $str); } Yes, we do show the gory details in a manpage, but inheriting from a class is not for the faint of heart, and requires getting acquainted with the implementation, most of the time. The order is not alphabetical here but by increased level of severity (as expected, anyway): logwrite($channel, $priority, $level, $str) Log message to the given channel, at the specified priority/level, obtained through a call to map_pri(). logsay($str) Log message to the output channel, at the notice priority. logwarn($str) Log warning to the error channel at the warning priority. logxcarp($offset, $str) Log warning to the error channel at the warning priority, from the perspective of the caller. An additional $offset stack frames are skipped to find the caller (added to the hardwired fixed offset imposed by the overall Log::Agent architecture). logerr($str) Log error to the error channel at the error priority. logdie($str) Log fatal error to the error channel at the critical priority and then call die() with "$str\n" as argument. logxcroak($offset, $str) Log a fatal error, from the perspective of the caller. The error is logged to the error channel at the critical priority and then Carp::croak() is called with "$str\n" as argument. An additional $offset stack frames are skipped to find the caller (added to the hardwired fixed offset imposed by the overall Log::Agent architecture). logconfess($str) Confess a fatal error. The error is logged to the error channel at the critical priority and then Carp::confess() is called with "$str\n" as argument. The following routines have a default implementation but may be redefined for specific drivers: emit($channel, $prio, $str) This is a convenient wrapper that calls: write($channel, $self->priority($prio), $self->prefix_msg($str)) using dynamic binding. map_pri($priority, $level) Converts a ("priority", level) tupple to a single priority token suitable for emit(). By default, returns an empty string, which is OK only when emit() does not care! The following routine is frozen. There is no way in Perl to freeze a routine, i.e. to explicitely forbid any redefinition, so this is an informal notification: priority($priority) This routine returns the proper priority for emit() for each of the following strings: "critical", "error", "warning" and "notice", which are the hardwired priority strings, as documented above. It derives a logging level from the $priority given and then returns the result of: map_pri($priority, $level); Therefore, only map_pri() should be redefined. Finally, the following initialization routine is provided: to record the _init($prefix, $penalty) Records the prefix attribute, as well as the Carp `penalty' (amount of extra stack frames to skip). Should be called in the constructor of all the drivers. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent(3), Log::Agent::Driver::Default(3), Log::Agent::Driver::File(3), Log::Agent::Driver::Silent(3), Log::Agent::Driver::Syslog(3), Devel::Datum(3).  File: pm.info, Node: Log/Agent/Driver/Datum, Next: Log/Agent/Driver/Default, Prev: Log/Agent/Driver, Up: Module List interceptor driver to cooperate with Devel::Datum ************************************************* NAME ==== Log::Agent::Driver::Datum - interceptor driver to cooperate with Devel::Datum SYNOPSIS ======== NONE DESCRIPTION =========== The purpose of the interceptor is to cooperate with Devel::Datum by emitting traces to the debug channel via Devel::Datum's traces facilities. This driver is automatically installed by Log::Agent when Devel::Datum is in use and debug was activated through it. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Devel::Datum(3).  File: pm.info, Node: Log/Agent/Driver/Default, Next: Log/Agent/Driver/File, Prev: Log/Agent/Driver/Datum, Up: Module List default logging driver for Log::Agent ************************************* NAME ==== Log::Agent::Driver::Default - default logging driver for Log::Agent SYNOPSIS ======== # Implicit use use Log::Agent; logconfig(-prefix => "prefix"); # optional # Explicit use use Log::Agent; require Log::Agent::Driver::Default; my $driver = Log::Agent::Driver::Default->make("prefix"); logconfig(-driver => $driver); DESCRIPTION =========== The default logging driver remaps the logxxx() operations to their default Perl counterpart. For instance, logerr() will issue a warn() and logwarn() will call warn() with a clear "WARNING: " emphasis (to distinguish between the two calls). The only routine of interest here is the creation routine: make($prefix) Create a Log::Agent::Driver::Default driver whose prefix string will be $prefix. When no prefix is configured, the first letter of each logged string will be uppercased. CHANNELS ======== The error, output and debug channels all go to STDERR. BUGS ==== If logdie() is used within an eval(), the string you will get in $@ will be prefixed. It's not really a bug, simply that wrapping a code into eval() and parsing $@ is poor's man exception handling which shows its limit here: since the programmer using logdie() cannot foresee which driver will be used, the returned string cannot be determined precisely. Morality: use die() if you mean it, and document the string as an exception. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::Driver(3), Log::Agent(3).  File: pm.info, Node: Log/Agent/Driver/File, Next: Log/Agent/Driver/Silent, Prev: Log/Agent/Driver/Default, Up: Module List file logging driver for Log::Agent ********************************** NAME ==== Log::Agent::Driver::File - file logging driver for Log::Agent SYNOPSIS ======== use Log::Agent; require Log::Agent::Driver::File; my $driver = Log::Agent::Driver::File->make( -prefix => "prefix", -duperr => 1, -stampfmt => "own", -showpid => 1, -magic_open => 0, -channels => { 'error' => '/tmp/output.err', 'output' => 'log.out', 'debug' => '../appli.debug', }, ); logconfig(-driver => $driver); DESCRIPTION =========== The file logging driver redirects logxxx() operations to specified files, one per channel usually (but channels may go to the same file). The creation routine make() takes the following arguments: `-channels' => *hash ref* Specifies where channels go. The supplied hash maps channel names (error, output and debug) to filenames. When `-magic_open' is set to true, filenames are allowed magic processing via perl's open(), so this allows things like: -channels => { 'error' => '>&FILE', 'output' => '>newlog', # recreate each time, don't append 'debug' => '|mailx -s whatever user', } If a channel (e.g. 'output') is not specified, it will go to the 'error' channel, and if that one is not specified either, it will go to STDERR instead. If you have installed the additional `Log::Agent::Rotate' module, it is also possible to override any default rotating policy setup via the `-rotate' argument: instead of supplying the channel as a single string, use an array reference where the first item is the channel file, and the second one is the `Log::Agent::Rotate' configuration: my $rotate = Log::Agent::Rotate->make( -backlog => 7, -unzipped => 2, -max_write => 100_000, -is_alone => 1, ); my $driver = Log::Agent::Driver::File->make( ... -channels => { 'error' => ['errors', $rotate], 'output' => ['output, $rotate], 'debug' => ['>&FILE, $rotate], # WRONG }, -magic_open => 1, ... ); In the above example, the rotation policy for the debug channel will not be activated, since the channel is opened via a magic method. See *Note Log/Agent/Rotate: Log/Agent/Rotate, for more details. `-duperr' => flag When true, all messages normally sent to the error channel are also copied to the output channel with a prefixing made to clearly mark them as such: "FATAL: " for logdie(), logcroak() and logconfess(), "ERROR: " for logerr() and "WARNING: " for logwarn(). Note that the "duplicate" is the original error string for logconfess() and logcroak(), and is not strictly identical to the message that will be logged to the error channel. This is a an accidental feature. Default is false. `-file' => file This switch supersedes both `-duperr' and `-channels' by defining a single file for all the channels. `-magic_open' => flag When true, channel filenames beginning with '>' or '|' are opened using Perl's open(). Otherwise, sysopen() is used, in append mode. Default is false. `-prefix' => prefix The application prefix string to prepend to messages. `-rotate' => object This sets a default logfile rotation policy. You need to install the additional `Log::Agent::Rotate' module to use this switch. object is the `Log::Agent::Rotate' instance describing the default policy for all the channels. Only files which are not opened via a so-called *magic open* can be rotated. `-showpid' => flag If set to true, the PID of the process will be appended within square brackets after the prefix, to all messages. Default is false. `-stampfmt' => (name | CODE) Specifies the time stamp format to use. By default, my "own" format is used. The following formats are available: date "[Fri Oct 22 16:23:10 1999]" none own "99/10/22 16:23:10" syslog "Oct 22 16:23:10". You may also specify a CODE ref: that routine will be called every time we need to compute a time stamp. It should not expect any parameter, and should return a string. CHANNELS ======== All the channels go to the specified files. If a channel is not configured, it is redirected to 'error', or STDERR if no 'error' channel was configured either. Two channels not opened via a magic open and whose logfile name is the same are effectively shared, i.e. the same file descriptor is used for both of them. If you supply distinct rotation policies (e.g. by having a default policy, and supplying another policy to one of the channel only), then the final rotation policy will depend on which one was opened first. So don't do that. CAVEAT ====== Beware of chdir(). If your program uses chdir(), you should always specify logfiles by using absolute paths, otherwise you run the risk of having your relative paths become invalid: there is no anchoring done at the time you specify them. This is especially true when configured for rotation, since the logfiles are recreated as needed and you might end up with many logfiles scattered throughout all the directories you chdir()ed to. Logging channels with the same pathname are shared, i.e. they are only opened once by Log::Agent::Driver::File. Therefore, if you specify different rotation policy to such channels, the channel opening order will determine which of the policies will be used for all such shared channels. Such errors are flagged at runtime with the following message: Rotation for 'logfile' may be wrong (shared with distinct policies) emitted in the logs upon subsequent sharing. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::Driver(3), Log::Agent(3), Log::Agent::Rotate(3).  File: pm.info, Node: Log/Agent/Driver/Silent, Next: Log/Agent/Driver/Syslog, Prev: Log/Agent/Driver/File, Up: Module List silent logging driver for Log::Agent ************************************ NAME ==== Log::Agent::Driver::Silent - silent logging driver for Log::Agent SYNOPSIS ======== use Log::Agent; require Log::Agent::Driver::Silent; my $driver = Log::Agent::Driver::Silent->make(); logconfig(-driver => $driver); DESCRIPTION =========== The silent logging driver remaps most of the logxxx() operations to NOPs. Only logconfess() and logdie() respectively call Carp::confess() and die(). CHANNELS ======== All the channels go to /dev/null, so to speak. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::Driver(3), Log::Agent(3).  File: pm.info, Node: Log/Agent/Driver/Syslog, Next: Log/Agent/File/Native, Prev: Log/Agent/Driver/Silent, Up: Module List syslog logging driver for Log::Agent ************************************ NAME ==== Log::Agent::Driver::Syslog - syslog logging driver for Log::Agent SYNOPSIS ======== use Log::Agent; require Log::Agent::Driver::Syslog; my $driver = Log::Agent::Driver::Syslog->make( -prefix => prefix, -facility => "user", -showpid => 1, -socktype => "unix", -logopt => "ndelay", ); logconfig(-driver => $driver); DESCRIPTION =========== The syslog logging driver delegates logxxx() operations to syslog() via the Sys::Syslog(3) interface. The creation routine make() takes the following switches: `-facility' => facility Tell syslog() which facility to use (e.g. "user", "auth", "daemon"). Unlike the Sys::Syslog(3) interface, the facility is set once and for all: every logging message will use the same facility. If you wish to log something to "auth" for instance, then do so via Sys::Syslog directly: there is no guarantee that the application will configure its Log::Agent to use syslog anyway! `-logopt' => *syslog options* Specifies logging options, under the form of a string containing zero or more of the words *ndelay*, *cons* or nowait. `-prefix' => prefix The prefix here is syslog's identification string. `-showpid' => flag Set to true to have the PID of the process logged. It is false by default. `-socktype' => (*unix* | *inet*) Specifies the logging socket type to use. The default behaviour is to use Sys:Syslog's default. CHANNELS ======== All the channels go to syslog(), of course. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::Driver(3), Log::Agent::Channel::Syslog(3).  File: pm.info, Node: Log/Agent/File/Native, Next: Log/Agent/File/Rotate, Prev: Log/Agent/Driver/Syslog, Up: Module List low-overhead IO::File ********************* NAME ==== Log::Agent::File::Native - low-overhead IO::File SYNOPSIS ======== require Log::Agent::File::Native; my $fh = Log::Agent::File::Native->make(\*main::STDERR); DESCRIPTION =========== This class is a stripped down implementation of IO::File, to avoid using the IO::* hierarchy which does not work properly for my simple needs. make glob This is the creation routine. Encapsulates the glob reference so that we can use object-oriented calls on it. print args Prints args to the file. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::File::Rotate(3), Log::Agent::Driver::File(3).  File: pm.info, Node: Log/Agent/File/Rotate, Next: Log/Agent/Logger, Prev: Log/Agent/File/Native, Up: Module List a rotating logfile set ********************** NAME ==== Log::Agent::File::Rotate - a rotating logfile set SYNOPSIS ======== # # This class is not user-visible. # # It is documented only for programmers wishing to inherit # from it to further extend its behaviour. # require Log::Agent::Driver::File; require Log::Agent::Rotate; require Log::Agent::File::Rotate; my $config = Log::Agent::Rotate->make(...); my $driver = Log::Agent::Driver::File->make(...); my $fh = Log::Agent::File::Rotate->make("file", $config, $driver); DESCRIPTION =========== This class represents a rotating logfile and is used drivers wishing to rotate their logfiles periodically. From the outside, it exports a single print routine, just like `Log::Agent::File::Native'. Internally, it uses the parameters given by a `Log::Agent::Rotate' object to transparently close the current logfile and cycle the older logs. Its exported interface is: make file, config This is the creation routine. The config object is an instance of `Log::Agent::Rotate'. print args Prints args to the file. After having printed the data, monitor the file against the thresholds defined in the configuration, and possibly rotate the logfiles according to the parameters held in the same configuration object. When the is_alone flag is not set in the configuration, the logfile is checked everytime a print is issued to see if its inode changed. Indeed, when several instances of the same program using rotating logfiles are running, each of them may decide to cycle the logs at some point in time, and therefore our opened handle could point to an already renamed or unlinked file. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::Rotate(3), Log::Agent::Driver::File(3).  File: pm.info, Node: Log/Agent/Logger, Next: Log/Agent/Message, Prev: Log/Agent/File/Rotate, Up: Module List a logging interface ******************* NAME ==== Log::Agent::Logger - a logging interface SYNOPSIS ======== require Log::Agent::Logger; my $log = Log::Agent::Logger->make( -channel => $chan, -max_prio => 'info', -min_prio => 'emerg', ); $log->error("can't open file %s: $!", $file); $log->warning("can't open file: $!"); DESCRIPTION =========== The `Log::Agent::Logger' class defines a generic interface for application logging. It must not be confused with the interface provided by Log::Agent, which is meant to be used by re-usable modules that do not wish to commit on a particular logging method, so that they remain true building blocks. By contrast, `Log::Agent::Logger' explicitely requests an object to be used, and that object must commit upon the logging channel to be used, at creation time. Optionally, minimum and maximum priority levels may be defined (and changed dynamically) to limit the messages to effectively log, depending on the advertised priority. The standard syslog(3) priorities are used. CHANNEL LIST ============ The following channels are available: Standard Log::Agent Channels ---------------------------- Those channels are documented in *Note Log/Agent/Channel: Log/Agent/Channel,. Other Channels -------------- Future `Log::Agent::Logger' extension will extend the set of available channels. INTERFACE ========= Creation Routine ---------------- The creation routine is called make and takes the following switches: `-channel' This defines the `Log::Agent::Channel' to be used for logging. Leaving this undefined will create a logger object that will never output anything. `-min_prio' Defines the minimum priority to be logged (included). Defaults to "emerg". `-max_prio' Defines the maximum priority to be logged (included). Defaults to "debug". Logging Interface ----------------- Each routine is documented to take a single string, but you may also supply a code reference as the first argument, followed by extra arguments. That routine will be called, along with the extra arguments, to generate the message to be logged. If that sounds crazy, think about the CPU time we save by NOT calling the routine. If nothing is returned by the routine, nothing is logged. If more than one argument is given, and the first argument is not a code reference, then it is taken as a printf() format, and the remaining arguments are used to fill the various "%" placeholders in the format. The special "%m" placeholder does not make use of any extra argument and is replaced by a stringification of the error message contained in $!, aka errno. There is a logging routine defined for each syslog(3) priority, along with aliases for some of them. Here is an exhaustive table, sorted by decreasing priority. Syslog Alias -------- --------- emerg emergency alert crit critical err error warning warn notice info debug We shall document only one routine for a given level: for instance, we document warn but you could also use the standard warning to achieve exactly the same funciton. `emergency($str)' Log at the "emerg" level, usually just before panicing. Something terribly bad has been detected, and the program might crash soon after logging this. `alert($str)' Log at the "alert" level, to signal a problem requiring immediate attention. Usually, some functionality will be missing until the condition is fixed. `critical($str)' Log at the "crit" level, to signal a severe error that prevents fulfilling some activity. `error($str)' Log at the "err" level, to signal a regular error. `warn($str)' Log at the "warning" level, which is an indication that something unusual occurred. `notice($str)' Log at the "notice" level, indicating something that is fully handled by the applicaiton, but which is not the norm. A significant condition, as they say. `info($str)' Log at the "info" level, for their amusement. `debug($str)' Log at the "debug" level, to further confuse them. Closing Channel --------------- close This routine closes the channel. Furhter logging to the logger is permitted, but will be simply discarded without notice. Attribute Access ---------------- The following access routines are defined: channel The defined logging channel. Cannot be changed. `max_prio' and `max_prio_str' Returns the maximum priority recorded, either as a numeric value or as a string. For the correspondance between the two, see *Note Log/Agent/Priorities: Log/Agent/Priorities,. `min_prio' and `min_prio_str' Returns the minimum priority recorded, either as a numeric value or as a string. For the correspondance between the two, see *Note Log/Agent/Priorities: Log/Agent/Priorities,. `set_max_prio($prio)' and `set_min_prio($prio)' Used to modify the maximum/minimum priorities. You can use either the string value or the numerical equivalent, as documented in *Note Log/Agent/Priorities: Log/Agent/Priorities,. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent::Channel(3).  File: pm.info, Node: Log/Agent/Message, Next: Log/Agent/Priorities, Prev: Log/Agent/Logger, Up: Module List a log message ************* NAME ==== Log::Agent::Message - a log message SYNOPSIS ======== require Log::Agent::Message; my $msg = Log::Agent::Message->make("string"); $msg->prepend("string"); $msg->append("string"); my $copy = $msg->clone; print "Message is $msg\n"; # overloaded stringification DESCRIPTION =========== The Log::Agent::Message class represents an original log message (a string) to which one may prepend or append other strings, but with the special property that prepended strings aggregate themselves in FIFO order, whilst appended strings aggregate themselves in LIFO order, which is counter-intuitive at first sight. In plain words, this means that the last routine that prepends something to the message will get its prepended string right next to the original string, regardless of what could have been prepended already. The behaviour is symetric for appending. INTERFACE ========= The following routines are available: append($str) Append suppled string $str to the original string (given at creation time), at the head of all existing appended strings. append_last($str) Append suppled string $str to the original string (given at creation time), at the tail of all existing appended strings. clone Clone the message. This is not a shallow clone, because the list of prepended and appended strings is recreated. However it is not a deep clone, because the items held in those lists are merely copied (this would matter only when other objects with overloaded stringification routines were supplied to prepend() and append(), which is not the case today in the basic Log::Agent framework). make($string) This is the creation routine. prepend($str) Prepend supplied string $str to the original string (given at creation time), at the tail of all existing prepended strings. prepend_first($str) Prepend supplied string $str to the original string (given at creation time), at the head of all existing prepended strings. stringify This is the overloaded "" operator, which returns the complete string composed of all the prepended strings, the original string, and all the appended strings. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent(3).  File: pm.info, Node: Log/Agent/Priorities, Next: Log/Agent/Rotate, Prev: Log/Agent/Message, Up: Module List conversion between syslog priorities and levels *********************************************** NAME ==== Log::Agent::Priorities - conversion between syslog priorities and levels SYNOPSIS ======== Not intended to be used directly DESCRIPTION =========== This package contains routines to convert between syslog priorities and logging levels: level_from_prio("crit") yields 2, and prio_from_level(4) yields "warning", as does prio_from_level(5). Here are the known priorities (which may be abbreviated to the first 2 letters, in a case-insensitive manner) and their corresponding logging level: Name Level Traditional Export --------- ----- -------------- ------ none -1 NONE (special, see text) emergency 0 (emerg, panic) EMERG alert 1 ALERT critical 2 (crit) CRIT error 3 (err) ERROR warning 4 WARN notice 6 NOTICE info 8 INFO debug 10 DEBUG The values between parenthesis show the traditional syslog priority tokens. The missing levels (5, 7, 9) are there for possible extension. They currently map to the level immediately below. The Export column lists the symbolic constants defined by this package. They can be imported selectively, or alltogether via the `:LEVELS' tag, as in: use Log::Agent::Priorities qw(:LEVELS); The special token "none" may be used (and spelled out fully) on special occasions: it maps to -1, and is convenient when specifying a logging level, for instance: specifying "none" ensures that *no logging* will take place, even for emergency situations. Anywhere where a priority is expected, one may specify a number taken as a logging level or a string taken as a priority. If the default mapping outlined above is not satisfactory, it can be redefined by specifying, for instance `"notice:9"'. It will be taken as being of level 9, but with a notice priority nonetheless, not info as it would have been implicitely determined otherwise. The routine priority_level() decompiles `"notice:9"' into ("notice", 9), and otherwise uses prio_from_level() or level_from_prio() to compute the missing informatin. For instance, given "critical", priority_level() routine will return the tuple ("critical", 2). AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent(3), Log::Agent::Logger(3).  File: pm.info, Node: Log/Agent/Rotate, Next: Log/Agent/Stamping, Prev: Log/Agent/Priorities, Up: Module List parameters for logfile rotation ******************************* NAME ==== Log::Agent::Rotate - parameters for logfile rotation SYNOPSIS ======== require Log::Agent::Rotate; my $policy = Log::Agent::Rotate->make( -backlog => 7, -unzipped => 2, -is_alone => 0, -max_size => 100_000, -max_time => "1w", ); DESCRIPTION =========== The `Log::Agent::Rotate' class holds the parameters describing the logfile rotation policy, and is meant to be supplied to instances of Log::Agent::Driver::File via arguments in the creation routine, such as `-rotate', or by using array references as values in the `-channels' hashref: See complementary information in *Note Log/Agent/Driver/File: Log/Agent/Driver/File,. As rotation cycles are performed, the current logfile is renamed, and possibly compressed, until the maximum backlog is reached, at which time files are deleted. Assuming a backlog of 5 and that the latest 2 files are not compressed, the following files can be present on the filesystem: logfile # the current logfile logfile.0 # most recently renamed logfile logfile.1 logfile.2.gz logfile.3.gz logfile.4.gz # oldest logfile, unlinked next cycle The following switches are available to the creation routine make(), listed in alphabetical order, all taking a single integer value as argument: backlog The total amount of old logfiles to keep, besides the current logfile. Defaults to 7. is_alone The argument is a boolean stating whether the program writing to the logfile will be the only one or not. This is a hint that drives some optimizations, but it is up to the program to *guarantee* that noone else will be able to write to or unlink the current logfile when set to *true*. Defaults to false. max_size The maximum logfile size. This is a threshold, which will cause a logfile rotation cycle to be performed, when crossed after a write to the file. If set to 0, this threshold is not checked. Defaults to 1 megabyte. max_time The maximum time in seconds between the moment we opened the file and the next rotation cycle occurs. This threshold is only checked after a write to the file. The value can also be given as a string, postfixed by one of the following letters to specify the period unit (e.g. "3w"): Letter Unit ------ ------- m minutes h hours d days d days w weeks M months (30 days of 24 hours) y years Defaults to 0, meaning it is not checked. max_write The maximum amount of data we can write to the logfile. Like max_size, this is a threshold, which is only checked after a write to the logfile. This is not the total logfile size: if several programs write to the same logfile and max_size is not used, then the logfiles may never be rotated at all if none of the programs write at least max_write bytes to the logfile before exiting. Defaults to 0, meaning it is not checked. single_host The argument is a boolean stating whether the access to the logfiles will be made from one single host or not. This is a hint that drives some optimizations, but it is up to the program to *guarantee* that it is accurately set. Defaults to false, which is always a safe value. unzipped The amount of old logfiles, amongst the most recent ones, that should not be compressed but be kept as plain files. Defaults to 1. To test whether two configurations are strictly identical, use is_same(), as in: print "identical\n" if $x->is_same($y); where both $x and $y are `Log::Agent::Rotate' objects. All the aforementionned switches also have a corresponding querying routine that can be issued on instances of the class to get their value. It is not possible to modify those attributes. For instance: my $x = Log::Agent::Rotate->make(...); my $mwrite = $x->max_write(); would get the configured max_write threshold. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent(3), Log::Agent::Driver::File(3), Log::Agent::Rotate::File(3).  File: pm.info, Node: Log/Agent/Stamping, Next: Log/Common, Prev: Log/Agent/Rotate, Up: Module List time-stamping routines ********************** NAME ==== Log::Agent::Stamping - time-stamping routines SYNOPSIS ======== Not intended to be used directly DESCRIPTION =========== This package contains routines to generate the leading time-stamping on logged messages. Formats are identified by a name, and the stamping_fn() function converts that name into a CODE ref, defaulting to the "own" format when given an unknown name. Here are the known formats: date "[Fri Oct 22 16:23:10 1999]" none own "99/10/22 16:23:10" syslog "Oct 22 16:23:10" Channels or Drivers which take a `-stampfmt' switch expect either a string giving the format name (e.g. "date"), or a CODE ref. That referenced routine will be called every time we need to compute a time stamp. It should not expect any parameter, and should return a stamping string. AUTHOR ====== Raphael Manfredi `' SEE ALSO ======== Log::Agent(3), Log::Agent::Channel(3), Log::Agent::Driver(3).  File: pm.info, Node: Log/Common, Next: Log/Dispatch, Prev: Log/Agent/Stamping, Up: Module List log messages in the httpd access and error log styles ***************************************************** NAME ==== Log::Common - log messages in the httpd access and error log styles SYNOPSIS ======== use Log::Common; $l = new Log::Common(access => "/var/log/search-hits", error => "/usr/local/log/error_log", no_stderr => 1, class => "debug"); $l->error(message => "Uh-oh... :-(", fatal => 1); $l->access(user => "martin", message => "$query_string", code => 200); DESCRIPTION =========== This class defines two methods which may be used to write messages to *httpd* common log file style access and error log files, such as those maintained by the Apache and NCSA WWW servers. The log file is locked whilst being written to avoid corruption when multiple processes attempt to write to the same file at the same time. For convenience both methods support a parameter which, if specified, results in "exit" being called to bomb out of the program. If the environmental variable GATEWAY_INTERFACE isn't set, error messages are also sent to STDERR - though this behaviour can be overridden if undesired. This is so that Perl programs which use this class can trivially dump out messages both to their end user and to a system log file at the same time. Error log file entries are written with a leading UTC timestamp, in the common HTTP server usage. METHODS ======= access( [ OPTIONS ] ); error( [ OPTIONS ] ); PARAMETERS ========== When creating a Log::Common object: access => *access_log_filename* This is the filename to use when logging via the access method. error => *error_log_filename* This is the filename to use when logging via the error method. class => *class_name* The default class of error log messages. You can use this to distinguish between debugging info, security related info, messages from WWW servers, messages from the mail system, and so on. This default value can be overridden in an individual call to the error logging method. no_stderr => 0 or 1 Suppress the printing of the message to STDERR if set to 1, defaults to 0. This can be overridden when the error method is invoked. Common to both methods: fatal => *exit_code* This indicates that whatever happened was a fatal error, and causes the program to croak after the log file entry has been written. The value given will be used as the program's exit code. message => *message_string* The actual message to write to the log file. For the access method only: count => number Normally the number of bytes transferred - 0 if not supplied. code => *response_code* Normally the number of bytes transferred - 0 if not supplied. host => host_name The domain name or IP address of the calling/client host. If not supplied, the process environment will be checked for REMOTE_HOST and REMOTE_ADDR (as set by CGI) in turn. If neither of these is present this field in the log file will be set to *0.0.0.0*. ident => *value_of_ident_lookup* Normally the result of an IDENT (AUTH) lookup on the calling host and port. If not supplied, the value of REMOTE_IDENT in the process environment will be used, or "-". user => *authenticated_user_name* Normally the user name which has been authenticated, e.g. using basic HTTP authentication. If not supplied, the value of REMOTE_USER in the process environment will be used instead, or "-". For the error method only: class => *class_name* Overrides default setting for this invocation - see above. info => *info_string* Additional info - this will be rendered enclosed in round brackets at the end of this line in the log file. no_stderr => 0 or 1 Overrides default setting for this invocation - see above. FILE FORMATS ============ Note that these are the common field usages - you don't have to put the same things in the same fields, though it would probably make life easier if you were planning to process these log files through existing HTTP server log file analysis tools. The error log file is structured as follows :- *the date* This is prettyprinted in GMT (UTC) using the gmtime function and enclosed in square brackets. It's always generated for you. *the class of message* This will be followed by a colon character ':'. Taken from the class parameter. This overrides any default value set for the object as a whole. *any supplementary information* Taken from the info parameter. This will be enclosed in round brackets. The access log file is structured as follows :- *client host name/IP address* Taken from the host parameter. *remote user name* Taken from the ident parameter. This is normally found via the AUTH/IDENT protocol - RFC 1413, RFC 931. *remote user name* Taken from the user parameter. This is normally from HTTP authentication. timestamp Generated using localtime, with a GMT (UTC) offset. This will be enclosed in square brackets, and will always be generated automatically for you. *the message itself* Taken from the message parameter. *response status code* Taken from the code parameter. This is normally numeric. *bytes transferred count* Taken from the count parameter. This is normally numeric. BUGS ==== None ? :-) TODO ==== Extended log file format (dump variable X as field Y in the log file entry?) might be useful. COPYRIGHT ========= Copyright (c) 1998 Martin Hamilton and Jon Knight . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. It was developed by the Department of Computer Studies at Loughborough University of Technology, as part of the ROADS project. This work was funded by the Joint Information Systems Committee (JISC) of the Higher Education Funding Councils under the UK Electronic Libraries Programme (eLib), the European Commission DESIRE project, and the TERENA development programme. AUTHORS ======= Jon Knight Martin Hamilton  File: pm.info, Node: Log/Dispatch, Next: Log/Dispatch/ApacheLog, Prev: Log/Common, Up: Module List Dispatches messages to multiple Log::Dispatch::* objects ******************************************************** NAME ==== Log::Dispatch - Dispatches messages to multiple Log::Dispatch::* objects SYNOPSIS ======== use Log::Dispatch; my $dispatcher = Log::Dispatch->new; $dispatcher->add( Log::Dispatch::File->new( name => 'file1', min_level => 'debug', filename => 'logfile' ) ); $dispatcher->log( level => 'info', message => 'Blah, blah' ); my $sub = sub { my %p = @_; return reverse $p{message}; }; my $reversing_dispatcher = Log::Dispatch->new( callbacks => $sub ); DESCRIPTION =========== This module manages a set of Log::Dispatch::* objects, allowing you to add and remove output objects as desired. METHODS ======= * new Returns a new Log::Dispatch object. This method takes one optional parameter: * - callbacks( \& or [ \&, \&, ... ] ) This parameter may be a single subroutine reference or an array reference of subroutine references. These callbacks will be called in the order they are given and passed a hash containing the following keys: ( message => $log_message, level => $log_level ) It's a hash in case I need to add parameters in the future. The callbacks are expected to modify the message and then return a single scalar containing that modified message. These callbacks will be called when either the log or `log_to' methods are called and will only be applied to a given message once. If they do not return the message then you will get no output. Make sure to return the message! * add( Log::Dispatch::* OBJECT ) Adds a new a Log::Dispatch::* object to the dispatcher. If an object of the same name already exists, then that object is replaced. A warning will be issued if the '-w' flag is set. NOTE: This method can really take any object that has methods called 'name' and 'log'. * remove($) Removes the object that matches the name given to the remove method. The return value is the object being removed or undef if no object matched this. * log( level => $, message => $ ) Sends the message (at the appropriate level) to all the Log::Dispatch::* objects that the dispatcher contains (by calling the `log_to' method repeatedly). * log_to( name => $, level => $, message => $ ) Sends the message only to the named object. * level_is_valid( $string ) Returns true or false to indicate whether or not the given string is a valid log level. Can be called as either a class or object method. CONVENIENCE METHODS =================== Version 1.6 of Log::Dispatch adds a number of convenience methods for logging. You may now call any valid log level (including valid abbreviations) as a method on the Log::Dispatch object with a single argument that is the message to be logged. This is converted into a call to the log method with the appropriate level. For example: $dispatcher->alert('Strange data in incoming request'); translates to: $dispatcher->log( level => 'alert', message => 'Strange data in incoming request' ); These methods act like Perl's print built-in when given a list of arguments. Thus, the following calls are equivalent: my @array = ('Something', 'bad', 'is', here'); $dispatcher->alert(@array); my $scalar = join $,, @array; # That is not a typo. See perldoc perlvar for info on $, $dispatcher->alert($scalar); One important caveat about these methods is that its not that forwards compatible. If I were to add more parameters to the log call, it is unlikely that these could be integrated into these methods without breaking existing uses. This probably means that any future parameters to the log method will never be integrated into these convenience methods. OTOH, I don't see any immediate need to expand the parameters given to the log method. Log Levels ---------- The log levels that Log::Dispatch uses are taken directly from the syslog man pages (except that I expanded them to full words). Valid levels are: debug info notice warning error critical alert emergency Alternately, the numbers 0 through 7 may be used (debug is 0 and emergency is 7). The syslog standard of 'err', 'crit', and 'emerg' is also acceptable. USAGE ===== This logging system is designed to be used as a one-stop logging system. In particular, it was designed to be easy to subclass so that if you want to handle messaging in a way other than one of the modules used here, you should be able to implement this with minimal effort. The basic idea behind Log::Dispatch is that you create a Log::Dispatch object and then add various logging objects to it (such as a file logger or screen logger). Then you call the log method of the dispatch object, which passes the message to each of the objects, which in turn decide whether or not to accept the message and what to do with it. This makes it possible to call single method and send a message to a log file, via email, to the screen, and anywhere else all in one simple command. The logging levels that Log::Dispatch uses are borrowed from the standard UNIX syslog levels, except that where syslog uses partial words ('err') Log::Dispatch also allows the use of the full word as well ('error'). Please note that because this code uses pseudo-hashes and compile-time object typing that it will only run under Perl 5.005 or greater. Making your own logging objects ------------------------------- Making your own logging object is generally as simple as subclassing Log::Dispatch::Output and overriding the new and log methods. See the *Note Log/Dispatch/Output: Log/Dispatch/Output, docs for more details. If you would like to create your own subclass for sending email then it is even simpler. Simply subclass *Note Log/Dispatch/Email: Log/Dispatch/Email, and override the `send_email' method. See the *Note Log/Dispatch/Email: Log/Dispatch/Email, docs for more details. Why doesn't Log::Dispatch add a newline to the message? ------------------------------------------------------- A few people have written email to me asking me to add something that would tack a newline onto the end of all messages that don't have one. This will never happen. There are several reasons for this. First of all, Log::Dispatch was designed as a simple system to broadcast a message to multiple outputs. It does not attempt to understand the message in any way at all. Adding a newline implies an attempt to understand something about the message and I don't want to go there. Secondly, this is not very cross-platform and I don't want to go down the road of testing Config values to figure out what to tack onto messages based on OS. I think people's desire to do this is because they are too focused on just the logging to files aspect of this module. In this case newlines make sense. However, imagine someone is using this module to log to a remote server and the interactions between the client and server use newlines as part of the control flow. Casually adding a newline could cause serious problems. However, the 1.2 release adds the callbacks parameter for the Log::Dispatch object which you can easily use to add newlines to messages if you so desire. RELATED MODULES =============== Log::Dispatch::Tk ----------------- Dominique Dumont has written Log::Dispatch::Tk which allows log messages to show up in a window. This code is available from CPAN. AUTHOR ====== Dave Rolsky, SEE ALSO ======== Log::Dispatch::ApacheLog, Log::Dispatch::Email, Log::Dispatch::Email::MailSend, Log::Dispatch::Email::MailSendmail, Log::Dispatch::Email::MIMELite, Log::Dispatch::File, Log::Dispatch::Handle, Log::Dispatch::Output, Log::Dispatch::Screen, Log::Dispatch::Syslog