NAME

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.

SYNOPSIS

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)

DESCRIPTION

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;

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().

Creating the New Streams

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.

Redirecting Error Messages

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).

Redirecting Log Messages

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 );

Redirecting Debug Messages

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 );

Redirecting Messages in General

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.

Passing filehandles

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.

Changing the Default Message Formats

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/\&/&amp;/gs;
        $msg =~ s/</&lt;/gs;
        $msg =~ s/>/&gt;/gs;
        $msg =~ s/"/&quot;/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.

Making perl Errors Appear in the Browser Window

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;

Changing the fatalsToBrowser message format or document

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.

What are the Carp methods?

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.

Forcing a Stack Trace

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).

METHODS

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.

Streams and their methods

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()

Exported Package Methods

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

Internal Package Methods

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.

Exported Package Variables

No variables are exported into the caller's namespace. However, the STDLOG and STDBUG streams are defined using typeglobs in the main namespace.

Internal Package Variables

$DEBUGLEVEL

A number indicating the level of debugging output that is to occur. At each increase in level, additional debugging output is allowed.

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.

$LOGLEVEL

A number indicating the level of logging output that is to occur. At each increase in level, additional logging output is allowed.

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.

RETURN VALUE

The value returned by executing the package is 1 (or true).

ENVIRONMENT

FILES

ERRORS

WARNINGS

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.

DIAGNOSTICS

See importing the verbose pseudo-symbol in Forcing a Stack Trace.

BUGS

Check out what's left in the TODO file.

RESTRICTIONS

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

CPAN DEPENDENCIES

LOCAL DEPENDENCIES

NOTES

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.

ACKNOWLEDGEMENTS

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.

AUTHOR(S)

mak - Michael King ( mike808@mo.net )

HISTORY

CGI::LogCarp.pm
v1.01 09/15/97 mak
v1.12 08/14/98 mak

CHANGE LOG

1.05 first posting to CPAN
1.12 major revision, tracking CGI::Carp

MODIFICATIONS

COPYRIGHT

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.

AVAILABILITY

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.

PACKAGE PUBLIC METHODS

DEBUGLEVEL $LEVEL

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 $LEVEL

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.

warn @message

This method is a replacement for Perl's builtin warn(). The message is sent to the STDERR, STDLOG, and STDBUG streams.

die @message

This method is a replacement for Perl's builtin die(). The message is sent to the STDERR, STDLOG, and STDBUG streams.

carp @message

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.

croak @message

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.

confess @message

This method is a replacement for Carp::confess(). The message is sent to the STDERR, STDLOG, and STDBUG streams.

cluck @message

This method is a replacement for Carp::cluck(). The message is sent to the STDERR, STDLOG, and STDBUG streams.

set_message $message

set_message FILEHANDLE $message

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.

logmsg @message

This method operates similarly to the warn() method. The message is sent to the STDLOG and STDBUG streams.

debug @message

This method operates similarly to the warn() method. The message is sent to the STDBUG stream when DEBUGLEVEL > 0.

trace @message

This method operates similarly to the warn() method. The message is sent to the STDBUG stream when DEBUGLEVEL is greater than one.

serverwarn @message

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.

carpout FILEHANDLE

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.

logmsgout FILEHANDLE

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.

debugout FILEHANDLE

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.

to_filehandle EXPR

Borrowed directly from CGI.pm by Lincoln Stein. It converts EXPR to a filehandle.

is_STDOUT FILEHANDLE

This method compares FILEHANDLE with the STDOUT stream and returns the boolean result.

This method is not exported by default.

is_STDERR FILEHANDLE

This method compares FILEHANDLE with the STDERR stream and returns the boolean result.

This method is not exported by default.

is_STDBUG FILEHANDLE

This method compares FILEHANDLE with the STDBUG stream and returns the boolean result.

This method is not exported by default.

is_STDLOG FILEHANDLE

This method compares FILEHANDLE with the STDLOG stream and returns the boolean result.

This method is not exported by default.

is_realSTDERR FILEHANDLE

This method compares FILEHANDLE with the _STDERR stream and returns the boolean result.

This method is not exported by default.

PRIVATE METHODS

realwarn @MESSAGE

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.