NAME
Log::ErrLogger - Log errors and error-like events
SYNOPSIS
use Log::ErrLogger;
# Send e-mail for ERROR or worse
my $mail_logger = new Log::ErrLogger::Mail(
SENSITIVITY => Log::ErrLogger::ERROR,
HEADERS => { To => "who@where.com",
Subject => "Errors occurred while running $0" });
# Log INFORMATIONAL or worse to a file
my $file_logger = new Log::ErrLogger::File(
FILE => "/home/who/what.err",
SENSITIVITY => Log::ErrLogger::INFORMATIONAL );
# Print a nice HTML error message
my $sub_logger = new Log::ErrLogger::Sub (
SENSITIVITY => FATAL,
SUB => sub { print STDOUT "<TITLE>Oops!</TITLE><HTML><HEAD1>Please try again later.</HEAD1></HTML>\n";
exit(0); } );
# Capture all output to STDERR as an UNEXPECTED error
my $stderr_logger = Log::ErrLogger::Tie( Log::ErrLogger::UNEXPECTED );
# But don't actually print to STDERR
$stderr_logger->close;
# Log a warning
LogError( WARNING, "Danger, %s!", "Will Robinson" );
DESCRIPTION
Log::ErrLogger provides a means of logging errors and error-like
events (such as warnings and unexpected situations) when
printing to STDERR just will not do.
Error-like events are classified by a severity (see the section
on "ERROR SEVERITIES" below). Programs instantiate error logging
objects which can respond differently to events. The objects
have a sensitivity -- they will respond to any event at least as
severe as their sensitivity, and will ignore any events that are
less severe.
This module instantiates new __DIE__ and __WARN__ handlers that
call LogError( FATAL, die-message) and LogError( WARNING, warn-
message), respectively.
HISTORY
$Id: ErrLogger.pm,v 1.4 1999/09/13 16:37:17 dcw Exp $
$Log: ErrLogger.pm,v $ Revision 1.4 1999/09/13 16:37:17 dcw
Documentation
Revision 1.3 1999/09/01 14:28:28 dcw Backup file, export,
autoflush
Revision 1.2 1999/08/31 17:18:39 dcw Log::ErrLogger::Sub
Revision 1.1 1999/08/30 21:28:43 dcw Initial
AUTHOR
David C. Worenklein <dcw@gcm.com>
COPYRIGHT
Copyright 1999 Greenwich Capital Markets
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
ERROR SEVERITIES
The predefined severities are
DEBUGGING
INFORMATIONAL
UNEXPECTED
WARNING
ERROR
FATAL
They have numerical values from 1 to 6.
NON-METHOD SUBROUTINES
LogError( $severity, $format [,@args] )
Log an error of the specified severity. The text of the
message is the output of sprintf $format, @args. A carriage-
return (\n) will be appended if one is not supplied.
my $stderr_logger = Tie( [$severity] );
Tie the STDERR handle to the Log::ErrLogger module, so that
any output to STDERR will call LogError( $severity, output
).
If $severity is not specified, it will default to
INFORMATIONAL.
METHODS
my $sensitivity = $logger->Sensitivity;
Returns the sensitivty of an error logger object. Objects
respond to events that are at least as severe as their
sensitivity.
my $old_sensitivity = $logger->Sensitivity( $new_sensitivity );
Sets the sensitivty of an error logger object. Objects
respond to events that are at least as severe as their
sensitivity.
Returns what the sensitivity of the object used to be.
my $fh = $logger->FileHandle;
Returns the IO::Handle associated with the error logger
object. Not all error loggers will have a file handle, but
most will.
$logger->SetFileHandle( $handle );
Associates the error logger object with the given (opened)
IO::Handle, and closes the old file handle that used to be
associated with the object (if there was one.)
The handle is set to autoflush, since buffering is usually a
bad idea on error loggers.
$logger->close;
Decommission the error logging object. the LogError manpage
will no longer invoke this object.
Note that this does NOT close the associated file handle.
However, if the error logging object has the only reference
to the file handle, and the program does not have any
references to the error logging object, the handle will have
no references left and will be destroyed.
$logger->Log( $message, $severity);
This is the method called by the LogError manpage, above. It
prints
<time>: <message>
to the associated file handle, where <time> is the output of
the localtime manpage, evaluated in a scalar context.
Additionally, if the object has a TRACE attribute that is at
least as large as the error severity, this method will print
a trace of where the error occurred:
<spaces>: From <subroutine1>, at <filename1>:<line1>
<spaces>: From <subroutine2>, at <filename2>:<line2>
where <spaces> is the number of spaces needed to make all
the colons line up.
CONSTRUCTORS
The following erorr logging classes are provided by the module:
my $logger = new Log::ErrLogger( [parameter-hash] );
Creates a new error logging object that uses the default the
Log manpage given above. The parameters that are understood
are
SENSITIVITY
The sensitivity of the object. Defaults to INFORMATIONAL
or, in the perl debugger, DEBUGGING.
TRACE Events that are at least as severe as the TRACE value will
have their call stack printed.
my $logger = new Log::ErrLogger::File( [parameter-hash] );
Creates an error logging object that logs events to a file.
In addition to the parameters that the Log::ErrLogger
constructor takes, it also takes
FILE Name of the file that in which to log events. Defaults to
/tmp/<program-base-name>.<pid>.err. See the the
SetFileName manpage method, below, for details.
Log::ErrLogger::File objects also provides the following
methods:
my $filename = $filelogger->FileName();
Returns the name of the file to which events are logger.
my $old_filename = $filelogger->SetFile( $new_filename)
Opens the given file for output and sets its FILEHANDLE
to that file. An ERROR event is generated if the file
could not be opened.
Note that the file is opened by putting a ">" at the
beginning and creating a new IO::File object. This means
that if the filename given already begins with a ">",
the file will be opened for appending.
If the file already exists, it is renamed by appending
".bak" to it. A WARNING event is generated if the file
could not be backed up.
Returns the old filename that errors used to be logged
to.
my $logger = new Log::ErrLogger::Mail( [parameter-hash] );
Log events by sending email to interested parties. In
addition to the parameters that the Log::ErrLogger
constructor takes, it also takes
HEADERS A reference to a hash containing the headers of the e-mail,
such as To and Subject.
If no sufficiently severe events occur, no email is sent.
(In other words, you will not get a blank e-mail.)
my $logger = new Log::ErrLogger::Sub( [parameter-hash] );
Calls a user specified subroutine every time a sufficiently
severe events occurs. In addition to the parameters that the
Log::ErrLogger constructor takes, it also takes
SUB A reference (regular or symbolic) to the subroutine to be
called. The subroutine will receive two parameters --
the event message and the error severity. This parameter
MUST be supplied to the constructor.
Note that, within this subroutine, STDERR is what you
would want it to be, even if the program has used Tie to
capture STDERR. Thus, the subroutine does not have to
worry that output to STDERR will cause infinite
recursion.