| CGI::LogCarp - Error, log and debug streams, httpd style format |
CGI::LogCarp - Error, log and debug streams, httpd style format
CGI::LogCarp redefines the STDERR stream and allows the definition of new STDBUG and STDLOG streams in such a way that all messages are formatted similar to an HTTPD error log.
Methods are defined for directing messages to STDERR, STDBUG, and STDLOG. Each stream can be directed to its own location independent of the others.
It can be used as a version-compatible drop-in replacement for the CGI::Carp module. This means that version 1.10 of CGI::LogCarp provides the same functionality, usage, and features as at least version 1.10 of CGI::Carp.
use CGI::LogCarp qw( :STDBUG fatalsToBrowser );
print "CGI::LogCarp version: ", CGI::LogCarp::VERSION;
DEBUGLEVEL 2;
confess "It was my fault: $!";
cluck "What's going on here?";
warn "This is most unusual.";
carp "It was your fault!";
croak "We're outta here!";
die "I'm dying.\n";
debug "Just for debugging: somevar=", $somevar, "\n";
logmsg "Just for logging: We're here.\n";
trace "detail=", $detail, "\n";
carpout \*ERRFILE;
debugout \*DEBUGFILE;
logmsgout \*LOGFILE;
is_STDOUT(\*ERRFILE)
is_STDERR(\*LOGFILE)
is_STDBUG(\*LOGFILE)
is_STDLOG(\*ERRFILE)
CGI::LogCarp is a Perl package defining methods for directing the existing STDERR stream as well as creating and directing two new messaging streams, STDBUG and STDLOG.
Their use was intended mainly for a CGI development environment, or where separate facilities for errors, logging, and debugging output are needed.
This is because CGI scripts have a nasty habit of leaving warning messages in the error logs that are neither time stamped nor fully identified. Tracking down the script that caused the error is a pain. Differentiating debug output or activity logging from actual error messages is a pain. Logging application activity or producing debugging output are quite different tasks than (ab)using the server's error log for this purpose. This module fixes all of these problems.
Replace the usual
use Carp;
or
use CGI::Carp;
with
use CGI::LogCarp;
And the standard warn(), die(), croak(), confess(),
cluck(), and carp() calls will automagically be replaced with methods
that write out nicely time-, process-, program-, and stream- stamped messages
to the STDERR, STDLOG, and STDBUG streams.
The method to generate messages on the new STDLOG stream
is logmsg(). Calls to logmsg() will write out the same nicely
time-, process-, program-, and stream-stamped messages
described above to both the STDLOG and the STDBUG streams.
The process number and the stream on which the message appeared is embedded in the default message in order to disambiguate multiple simultaneous executions as well as multiple streams directed to the same location.
Messages on multiple streams directed to the same location do not receive multiple copies.
Methods to generate messages on the new STDBUG stream
are debug() and trace().
In order to create the new streams, you must name them on the use line.
This is also referred to as importing a symbol. For example:
use CGI::LogCarp qw( :STDERR :STDLOG :STDBUG );
Note the :STDERR is not really necessary, as it is already defined in perl. Importing the :STDERR symbol will not generate an error.
By default, the STDLOG stream is duplicated from the STDERR stream, and the STDBUG stream is duplicated from the STDOUT stream.
By default, error messages are sent to STDERR. Most HTTPD servers direct STDERR to the server's error log. Some applications may wish to keep private error logs, distinct from the server's error log, or they may wish to direct error messages to STDOUT so that the browser will receive them (for debugging, not for public consumption).
The carpout() method is provided for this purpose.
Because carpout() is not exported by default,
you must import it explicitly by saying:
use CGI::LogCarp qw( carpout );
Note that for carpout(), the STDERR stream is already defined,
so there is no need to explicitly create it by importing the STDERR symbol.
However,
use CGI::LogCarp qw( :STDERR );
will not generate an error, and will also import carpout for you.
For CGI programs that need to send something to the HTTPD server's real error log, the original STDERR stream has not been closed, it has been saved as _STDERR. The reason for this is twofold.
The first is that your CGI application might really need to write something to the server's error log, unrelated to your own error log. To do so, simply write directly to the _STDERR stream.
The second is that some servers, when dealing with CGI scripts, close their connection to the browser when the script closes either STDOUT or STDERR. Some consider this a (mis)feature.
Saving the program's initial STDERR in _STDERR is used to prevent this from happening prematurely.
Do not manipulate the _STDERR filehandle in any other way other than writing
to it.
For CGI applications, the serverwarn() method formats and sends your message
to the HTTPD error log (on the _STDERR stream).
A new stream, STDLOG, can be defined and used for log messages. By default, STDLOG will be routed to STDERR. Most HTTPD servers direct STDERR (and thus the default STDLOG also) to the server's error log. Some applications may wish to keep private activity logs, distinct from the server's error log, or they may wish to direct log messages to STDOUT so that the browser will receive them (for debugging, not for public consumption).
The logmsgout() method is provided for this purpose.
Because logmsgout() is not exported by default,
you must create the STDLOG stream and import them explicitly by saying:
use CGI::LogCarp qw( :STDLOG );
A new stream, STDBUG, can be defined and used for debugging messages. Since this stream is for producing debugging output, the default STDBUG will be routed to STDOUT. Some applications may wish to keep private debug logs, distinct from the application output, or CGI applications may wish to leave debug messages directed to STDOUT so that the browser will receive them (only when debugging). Your program may also control the output by manipulating DEBUGLEVEL in the application.
The debugout() method is provided for this purpose.
Because the debugout() method is not exported by default,
you must create the STDBUG stream and import them explicitly by saying:
use CGI::LogCarp qw( :STDBUG );
Each of these methods, carpout(), logmsgout(), and debugout(),
requires one argument, which should be a reference to an open filehandle
for writing.
They should be called in a BEGIN block at the top of the application
so that compiler errors will be caught.
This example creates and redirects the STDLOG stream, as well as redirecting the STDERR stream to a browser, formatting the error message as an HTML document:
BEGIN {
use CGI::LogCarp qw( :STDLOG fatalsToBrowser );
# fatalsToBrowser doesn't stop messages going to STDERR,
# rather it replicates them on STDOUT. So we stop them here.
open(_STDERR,'>&STDERR'); close STDERR;
open(LOG,">>/var/logs/cgi-logs/mycgi-log")
or die "Unable to open mycgi-log: $!\n";
logmsgout \*LOG;
}
NOTE: carpout(), logmsgout(), and debugout() handle file locking
on systems that support flock so multiple simultaneous CGIs are not an issue.
However, flock might not operate as desired over network-mounted filesystems.
If you want to send errors to the browser, give carpout() a reference
to STDOUT:
BEGIN {
use CGI::LogCarp qw( carpout );
carpout \*STDOUT;
}
If you do this, be sure to send a Content-Type header immediately --
perhaps even within the BEGIN block -- to prevent server errors.
However, you probably want to take a look at importing the
fatalsToBrowser symbol and closing STDERR instead of doing this.
See the example above on how to do this.
You can pass filehandles to carpout(), logmsgout(), and debugout()
in a variety of ways. The ``correct'' way according to Tom Christiansen
is to pass a reference to a filehandle GLOB (or if you are using the
FileHandle module, a reference to a anonymous filehandle GLOB):
carpout \*LOG;
This looks a little weird if you haven't mastered Perl's syntax, so the following syntaxes are accepted as well:
carpout(LOG) -or- carpout(\LOG)
carpout('LOG') -or- carpout(\'LOG')
carpout(main::LOG) -or- carpout(\main::LOG)
carpout('main::LOG') -or- carpout(\'main::LOG')
... and so on
FileHandle and other objects work as well.
Using carpout(), logmsgout(), and debugout(),
is not great for performance, so they are recommended for debugging purposes
or for moderate-use applications. You can also manipulate DEBUGLEVEL
to control the output during the execution of your program.
By default, the messages sent to the respective streams are formatted as helpful time-, process-, program-, and stream-stamped messages.
The process number (represented in the example output below as $$) and the stream on which the message appears are displayed in the default message format and serve to disambiguate multiple simultaneous executions as well as multiple streams directed to the same location.
For example:
[Mon Sep 15 09:04:55 1997] $$ test.pl ERR: I'm confused at test.pl line 3.
[Mon Sep 15 09:04:55 1997] $$ test.pl BUG: answer=42.
[Mon Sep 15 09:04:55 1997] $$ test.pl LOG: I did something.
[Mon Sep 15 09:04:55 1997] $$ test.pl ERR: Got a warning: Permission denied.
[Mon Sep 15 09:04:55 1997] $$ test.pl ERR: I'm dying.
You can, however, redefine your own message formats for each stream
if you don't like this one by using the set_message() method.
This is not imported by default; you should import it on the use() line
like thus:
use CGI::LogCarp qw( fatalsToBrowser set_message );
# fatalsToBrowser doesn't stop messages going to STDERR,
# rather it replicates them on STDOUT. So we stop them here.
open(_STDERR,'>&STDERR'); close STDERR;
set_message("It's not a bug, it's a feature!");
use CGI::LogCarp qw( :STDLOG );
set_message(STDLOG, "Control: I'm here.");
Note the varying syntax for set_message().
The first parameter, if it is a filehandle, identifies the stream whose message is being defined. Otherwise it specifies the message for the STDERR stream. This non-filehandle first parameter form preserves compatibility with CGI::Carp syntax.
You may also pass in a code reference in order to create a custom error message. At run time, your code will be called with the text of the error message that caused the script
BEGIN {
use CGI::LogCarp qw( fatalsToBrowser set_message );
# fatalsToBrowser doesn't stop messages going to STDERR,
# rather it replicates them on STDOUT. So we stop them here.
open(_STDERR,'>&STDERR'); close STDERR;
sub handle_errors {
my $msg = shift;
$msg =~ s/\&/&/gs;
$msg =~ s/</</gs;
$msg =~ s/>/>/gs;
$msg =~ s/"/"/gs;
join("\n",
"<h1>Aw shucks</h1>",
"Got an error:",
"<pre>", $msg, "</pre>",
"");
}
set_message(\&handle_errors);
}
In order to correctly intercept compile-time errors, you should
call set_message() from within a BEGIN block.
If you want to send fatal (die or confess) errors to the browser,
ask to import the special fatalsToBrowser symbol:
BEGIN {
use CGI::LogCarp qw( fatalsToBrowser );
# fatalsToBrowser doesn't stop messages going to STDERR,
# rather it replicates them on STDOUT. So we stop them here.
open(_STDERR,'>&STDERR'); close STDERR;
}
die "Bad error here";
Fatal errors will now be sent to the browser. Any messages sent to the
STDERR stream are now also reproduced on the STDOUT stream.
Using fatalsToBrowser also causes CGI::LogCarp to define a new message
format that arranges to send a minimal HTTP header and HTML document to the
browser so that even errors that occur early in the compile phase will be
shown. Any fatal (die) and nonfatal (warn) messages are still produced
on the STDERR stream. They just also go to STDOUT.
Certain web servers (Netscape) also send CGI STDERR output to the browser. This causes a problem for CGI's because the STDERR stream is not buffered, and thus if something gets sent to the STDERR stream before the normal document header is produced, the browser will get very confused.
The following line solves this problem. See above for examples with context.
open(_STDERR,'>&STDERR'); close STDERR;
The default message generated by fatalsToBrowser is not the normal
LogCarp logging message, but instead displays the error message followed by
a short note to contact the Webmaster by e-mail with the time and date of the
error. You can use the set_message() method to change it as described above.
The default message generated on the STDLOG and STDBUG streams is formatted differently, and is as described earlier.
The Carp methods that are replaced by CGI::LogCarp are useful in your
own modules, scripts, and CGI applications because they act like die()
or warn(), but report where the error was in the code they were called from.
Thus, if you have a routine Foo() that has a carp() in it,
then the carp() will report the error as occurring where Foo() was
called, not where carp() was called.
As a debugging aid, you can force LogCarp to treat a croak
as a confess and a carp as a cluck across all modules.
In other words, force a detailed stack trace to be given.
This can be very helpful when trying to understand why, or from where,
a warning or error is being generated.
This feature is enabled by 'importing' the non-existant symbol 'verbose'. You would typically enable it on the command line by saying:
perl -MCGI::LogCarp=verbose script.pl
or by including the string MCGI::LogCarp=verbose in the PERL5OPT
environment variable.
You would typically enable it in a CGI application by saying:
use CGI::LogCarp qw( verbose );
Or, during your program's run by saying:
CGI::LogCarp::import( 'verbose' );
and calling CGI::LogCarp's import function directly.
NOTE: This is a feature that is in Carp but apparently was not implemented in CGI::Carp (as of v1.10).
Unless otherwise stated all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns a value, failure will be returned as undef or an empty list.
The following methods are for generating a message on the respective stream:
The STDERR stream: warn() and die()
The STDLOG stream: logmsg()
The STDBUG stream: debug() and trace()
The _STDERR stream: serverwarn()
The following methods are for generating a message on the respective stream, but will indicate the message location from the caller's perspective. See the standard Carp.pm module for details.
The STDERR stream: carp(), croak(), cluck() and confess()
The following methods are for manipulating the respective stream:
The STDERR stream: carpout()
The STDLOG stream: logmsgout()
The STDBUG stream: debugout()
The following methods are for manipulating the amount (or level) of output filtering on the respective stream:
The STDBUG stream: DEBUGLEVEL()
The STDLOG stream: LOGLEVEL()
The following method defines the format of messages directed to a stream.
Often used by and/or in conjunction with fatalsToBrowser:
set_message()
By default, the only methods exported into your namespace are:
warn, die, carp, croak, confess, and cluck
When you import the :STDBUG tag, these additional symbols are exported:
*STDBUG, debugmsgout, debug, trace, and DEBUGLEVEL
When you import the :STDLOG tag, these additional symbols are exported:
*STDLOG, logmsgout, logmsg and LOGLEVEL
When you import the :STDERR tag, these additional symbols are exported:
carpout
These additional methods are not exported by default, and must be named:
carpout, logmsgout, debugout, set_message
The following are pseudo-symbols, in that they change the way CGI::LogCarp works, but to not export any symbols in and of themselves.
verbose, fatalsToBrowser
The following methods are not exported but can be accessed directly in the CGI::LogCarp package.
The following methods are for comparing a filehandle to the respective stream:
is_STDOUT()
is_STDERR()
is_STDBUG()
is_STDLOG()
is_realSTDERR()
Each is explained in its own section below.
No variables are exported into the caller's namespace.
However, the STDLOG and STDBUG streams are defined using typeglobs
in the main namespace.
Currently three levels are defined:
0 - No messages are output on the STDBUG stream.
1 - debug() messages are output on the STDBUG stream.
2 - debug() and trace() messages are output on the STDBUG stream.
It is recommended to use the DEBUGLEVEL method to get/set this value.
Currently two levels are defined:
0 - No messages are output on the STDLOG stream.
1 - logmsg() messages are output on the STDLOG stream.
It is recommended to use the LOGLEVEL method to get/set this value.
The value returned by executing the package is 1 (or true).
Operation on Win32 platforms has not been tested.
CGI::Carp has some references to a wrap import symbol,
which appears to be an alternate name for fatalsToBrowser.
Internal comments refer to errorWrap. Since this is poorly
documented, I am speculating this is legacy and/or previous
implementation coding, and as such, have chosen not implement
the wrap symbol import in CGI::LogCarp. If some massively
popular module(s) I am currently unaware of is/are indeed using
this undocumented interface, please let me know.
See importing the verbose pseudo-symbol in Forcing a Stack Trace.
Check out what's left in the TODO file.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Carp, CGI::Carp
carpout(), debugout(), and logmsgout() now perform file locking.
I've attempted to track the features in CGI::LogCarp to the features in
the CGI::Carp module by Lincoln Stein. The version number of CGI::LogCarp
corresponds to the highest version of CGI::Carp module that this module
replicates all features and functionality. Thus version 1.10 of CGI::LogCarp
can be used as a drop-in replacement for versions 1.10 or lower of CGI::Carp.
Due to the implementation of the Symbol.pm module, I have no choice but to replace it with a version that supports extending the list of ``global'' symbols. It is part of the CGI::LogCarp distribution.
For speed reasons, the autoflush method is implemented here instead of pulling in the entire FileHandle module.
Based heavily on the CGI::Carp module by Lincoln D. Stein ( lstein@genome.wi.mit.edu ).
Thanks to Andy Wardley ( abw@kfs.org ) for commenting the original Carp.pm
module.
Thanks to Michael G Schwern ( schwern@starmedia.net ) for the constructive input.
mak - Michael King ( mike808@mo.net )
CGI::LogCarp.pm v1.01 09/15/97 mak v1.12 08/14/98 mak
1.05 first posting to CPAN 1.12 major revision, tracking CGI::Carp
Copyright (C) 1997,1998 Michael King ( mike808@mo.net ) Saint Louis, MO USA.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This module is copyright (c) 1997,1998 by Michael King ( mike808@mo.net ) and is made available to the Perl public under terms of the Artistic License used to cover Perl itself. See the file Artistic in the distribution of Perl 5.002 or later for details of copy and distribution terms.
The latest version of this module is likely to be available from:
http://walden.mo.net/~mike808/LogCarp
The best place to discuss this code is via email with the author.
DEBUGLEVEL is a normal get/set method.
When the scalar argument LEVEL is present, the DEBUGLEVEL will be set to LEVEL. LEVEL is expected to be numeric, with the following case-insensitive character-valued translations:
NO, FALSE, and OFF all equate to a value of 0 (ZERO). YES, TRUE, and ON all equate to a value of 1 (ONE). TRACE or TRACING equate to a value of 2 (TWO).
Values in scientific notation equate to their numeric equivalent.
NOTE:
All other character values of LEVEL equate to 0 (ZERO). This
will have the effect of turning off debug output.
After this translation to a numeric value is performed, the DEBUGLEVEL is set to LEVEL.
Whenever the DEBUGLEVEL is set to a non-zero value (i.e. ON or TRACE), the LOGLEVEL will be also set to 1 (ONE).
The value of DEBUGLEVEL is then returned to the caller, whether or not LEVEL is present.
LOGLEVEL is a normal get/set method.
When the scalar argument LEVEL is present, the LOGLEVEL will be set to LEVEL. LEVEL is expected to be numeric, with the following case-insensitive character-valued translations:
NO, FALSE, and OFF all equate to a value of 0 (ZERO). YES, TRUE, and ON all equate to a value of 1 (ONE).
Values in scientific notation equate to their numeric equivalent.
NOTE:
All other character values of LEVEL equate to 0 (ZERO). This
will have the effect of turning off log output.
After this translation to a numeric value is performed, the LOGLEVEL is set to LEVEL.
The value of LOGLEVEL is then returned to the caller, whether or not LEVEL is present.
This method is a replacement for Perl's builtin warn().
The message is sent to the STDERR, STDLOG, and STDBUG streams.
This method is a replacement for Perl's builtin die().
The message is sent to the STDERR, STDLOG, and STDBUG streams.
This method is a replacement for Carp::carp().
The message is sent to the STDERR, STDLOG, and STDBUG streams.
# mak - this fixes a problem when you passed Carp::carp a list # like the documentation says ( shortmess uses $_[0] and not @_ ). # This has been fixed in later (post-1997) versions of Carp.pm. # Since Carp.pm has no version, I can't tell which one you have.
This method is a replacement for Carp::croak().
The message is sent to the STDERR, STDLOG, and STDBUG streams.
# mak - this fixes a problem when you passed Carp::croak a list # like the documentation says ( shortmess uses $_[0] and not @_ ). # This has been fixed in later (post-1997) versions of Carp.pm. # Since Carp.pm has no version, I can't tell which one you have.
This method is a replacement for Carp::confess().
The message is sent to the STDERR, STDLOG, and STDBUG streams.
This method is a replacement for Carp::cluck().
The message is sent to the STDERR, STDLOG, and STDBUG streams.
This method is a replacement for the CGI::Carp method of the same name.
It defines the message format for the STDERR stream if FILEHANDLE is
not specified. FILEHANDLE specifies which stream is having its message
redefined. $message is typically a reference to a subroutine.
This method operates similarly to the warn() method.
The message is sent to the STDLOG and STDBUG streams.
This method operates similarly to the warn() method.
The message is sent to the STDBUG stream when DEBUGLEVEL > 0.
This method operates similarly to the warn() method.
The message is sent to the STDBUG stream
when DEBUGLEVEL is greater than one.
This method operates similarly to the warn() method.
The message is sent to the STDBUG, STDLOG, STDERR and _STDERR streams.
The _STDERR stream is typically is sent to a webserver's error log
if used in a CGI program.
A method to redirect the STDERR stream to the given FILEHANDLE. It accepts FILEHANDLE as a reference or a string.
See the section on REDIRECTING ERROR MESSAGES and the section on REDIRECTING MESSAGES IN GENERAL.
A method to redirect the STDLOG stream to the given FILEHANDLE. It accepts FILEHANDLE as a reference or a string.
See the section on REDIRECTING ERROR MESSAGES and the section on REDIRECTING MESSAGES IN GENERAL.
A method to redirect the STDBUG stream to the given FILEHANDLE. It accepts FILEHANDLE as a reference or a string.
See the section on REDIRECTING ERROR MESSAGES and the section on REDIRECTING MESSAGES IN GENERAL.
Borrowed directly from CGI.pm by Lincoln Stein. It converts EXPR to a filehandle.
This method compares FILEHANDLE with the STDOUT stream and returns the boolean result.
This method is not exported by default.
This method compares FILEHANDLE with the STDERR stream and returns the boolean result.
This method is not exported by default.
This method compares FILEHANDLE with the STDBUG stream and returns the boolean result.
This method is not exported by default.
This method compares FILEHANDLE with the STDLOG stream and returns the boolean result.
This method is not exported by default.
This method compares FILEHANDLE with the _STDERR stream and returns the boolean result.
This method is not exported by default.
This private method encapsulates Perl's underlying warn() method,
actually producing the message on the STDERR stream.
Locking is performed to ensure exclusive access while appending.
This method is not exportable.
This private method encapsulates Perl's underlying die() method,
actually producing the message on the STDERR stream and then terminating
execution.
Locking is performed to ensure exclusive access while appending.
This method is not exportable.
This private method synthesizes an underlying logmsg() method,
actually producing the message on the STDLOG stream.
Locking is performed to ensure exclusive access while appending.
The message will only be sent when LOGLEVEL is greater than zero.
This method is not exportable.
This private method synthesizes an underlying debug() method,
actually producing the message on the STDBUG stream.
Locking is performed to ensure exclusive access while appending.
The message will only be sent when DEBUGLEVEL is greater than zero.
This method is not exportable.
This private method synthesizes an underlying serverwarn() method,
actually producing the message on the _STDERR stream.
Locking is performed to ensure exclusive access while appending.
This stream is typically directed to the webserver's error log
if used in a CGI program.
This method is not exportable.
This private method returns the file, line, and basename of the currently executing function.
This method is not exportable.
A private method to construct a normalized timestamp prefix for a message.
This method is not exportable.
This private method compares two FILEHANDLE streams to each other and returns the boolean result.
This method is not exportable.
Note: This function is probably not portable to non-Unix-based operating systems (i.e. NT, VMS, etc.).
A private method that uses Perl's builtin flock() and seek()
to obtain an exclusive lock on the stream specified by FILEHANDLE.
A lock is only attempted on actual files that are writeable.
This method is not exportable.
A private method that uses Perl's builtin flock()
to release any exclusive lock on the stream specified by FILEHANDLE.
An unlock is only attempted on actual files that are writeable.
This method is not exportable.
| CGI::LogCarp - Error, log and debug streams, httpd style format |