view release on metacpan or  search on metacpan

Log.pm  view on Meta::CPAN

Log messages of type "status" and "success" are not manipulated or modified.
Whatever you put in is what you get back.

Log messages of type "error" are stored in two formats.  The first is the
format that in the output above.  The second is suitable for returning to
the user.  (It doesn't include the call trace.)  By default it includes
the error message from the variable $!.  If this is not desirable,
call Log->ui_no_error()


=head1 TIPS/TRICKS

=over 4

=item

It is nice to be able to add as many debugging messages without having
to worry about slowing down your application when it gets deployed.
Calling Log->debug_off will set the instance variable DEBUG_FLAG to
undefined, and will prevent any messages in the current process from
being stored.  e.g.

	if ($config{DEBUG} eq "Off")	## pretend %config holds global
	{				##   configuration info
		Log->debug_off;
	}
	Log->debug("this debug message won't be saved because debugging is off.");

=item

Even though the debug() function won't do anything when debugging is
turned off (it returns immediately), there is still the overhead of a
function call for each debug message.  If you really want to get obsessive
about performance you can try redefining the debug() method.  e.g.

	use CGI::Log;
	sub CGI::Log::debug () { 1 };		## redefine with prototype so it gets inlined
						## note: I haven't tested the efficiency of this!
						##
						## note: prototypes are from perl 5.002 +


=item

It is very handy to be able to turn on debugging from the URL.  e.g.

	http://somewhere.com/cgi-bin/test.pl?debug=secret

In your perl code you could have:

	if ($param{debug} ne "secret" 		## $param{debug} holds the CGI variable "debug" 
		|| $DEBUG != 1)			## $DEBUG is a config variable
	{
		Log->debug_off();
	}

This can be a huge timesaver if access to the webserver is difficult.
This can be huge trouble if you have confidential or security related
information in your debugging messages.  (That is why "debug" in the above
example is the string "secret" and not "1" or something easy to guess.)

=item

You can add nice status messages to your web application by doing something like:


	if (Log->is_error)
	{
		print "<font color=\"#ff0000\">ERROR</font><BR>\n";
		for (Log->get_error) { print $_ . "<BR>\n"; }
	}
	elsif (Log->is_success)
	{
		print "<img src=\"smiley_face.gif\">";
		for (Log->get_success) { print $_ . "<BR>\n"; }
	}

	for (Log->get_status) { print $_ . "<BR>\n"; }

=item

Make sure you have "Log" and not "log" or you will get the run-time error:

	Can't take log of 0

=item

At the end of your script (whether a CGI or mod_perl) you will almost always want a:

	Log->clear;

=back


Documentation for CGI::Log was created by h2xs. 

=head1 BUGS

- too much noise in the debug call tracing under mod_perl. e.g.

	[main:0 (eval):0 Apache::Registry::handler:141 (eval):141 Apache::ROOT::perl::test_5flog_2epl::handler:16] debug message.

- not thread-safe.

- if you are using mod_perl and you do not remember to clean out the log with Log->clean(), 
you will waste lots of memory.

- CGI::Log takes the Log:: namespace by default.  This might be seen as rude, or cause
problems if it is already being used.  (Check if %Log:: is defined???)


=head1 AUTHOR

Jason Moore, 1998 <jmoore@sober.com>

=head1 SEE ALSO

perl(1). 

modperl(1).