/ 
Log-ErrLogger-1.5
River stage zero No dependents
/ Log::ErrLogger

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
  log_error( 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 "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 log_error( FATAL, die-message) and log_error( WARNING, warn-message), respectively.

HISTORY

$Id: ErrLogger.pm,v 1.6 1999/09/23 21:37:24 dcw Exp $

$Log: ErrLogger.pm,v $ Revision 1.6 1999/09/23 21:37:24 dcw Incorporated Tim Ayers <tayers@bridge.com> suggestions

Revision 1.5 1999/09/13 17:59:48 dcw Copyright

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

log_error( SEVERITY, FORMAT [,LIST] )

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 log_error( $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. There are two special sensitivities. Objects with a sensitivity of NONE do not respond to any events. Objects with a sensitivity of ALL respond to all events.

my $old_sensitivity = $logger->sensitivity( 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->file_handle;

Returns the IO::Handle associated with the error logger object. Not all error loggers will have a file handle, but most will.

$logger->set_file_handle( 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. log_error 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( SEVERITY, MESSAGE );

This is the method called by log_error, above. It prints

<time>: <message>

to the associated file handle, where <time> is the output of localtime, 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 log 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 set_file 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->set_file( $new_filename [, mode [, perms]])

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.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 446:

=over without closing =back

Around line 675:

=over without closing =back