NAME

PSA::Error - Handy wrapper for $your_favourite_log_module

SYNOPSIS

# use automatic, unless configured otherwise
my $psa = shift;

# debug/verbose messages
whisper "About to do something small, var1 = $var1";
mutter "Authenticating request";

# These are all logged, `business as usual' conditions
reject "Request invalid (not well formed)"
    unless $psa->request->well_formed;

say "Processing Request";

# Henceforth the error conditions - first soft errors
my $xmlns = $psa->request->xmlns;
if ($xmlns) {
    if ($xmlns ne $proper_xmlns) {
        desist "Incorrect XMLNS on request";
    } else {
        whisper "XMLNS correct";
    }
} else {
    moan "Missing XMLNS, assuming default";
}

# now, bad errors
if (!$psa->storage->ping) {
    complain "Storage went away!";
    barf "Storage not accessible!"
      unless $psa->storage->reconnect;
}

# worse errors - stop a session
$inventoryItem->hotel or choke "Orphaned Inventory Item!";

# worse errors - stop a section / site / account
$hotel->hotelInfo
    or melt "Hotel missing hotelInfo object!";

# serious errors - stop everything
$receipt->payer
    or explode "Making mistakes with money!";

DESCRIPTION

PSA::Error is a class that encapsulates errors from PSA pages, and provides an easy interface for raising them. It doesn't actually stop anything, that is up to the event subscribers.

The logic behind all the different keywords, is that this is ugly:

$inventoryItem->hotel or do {
   my $logger = Log::Log4perl->new("location" => "somewhere");
   $logger->log(FATAL, "some message");
};

What a load of bollocks. Let's just use the resplendant variety of non-colourful expletives provided by the King's English, and get on with coding.

This module is used by default for all PSA pages, so they can all moan, shout and complain to their heart's content. Nice.

DESCRIPTION OF ERROR LEVELS

These aliases hide the complexity of using Log::Log4perl, and ensure that generated pages are easily managable.

All of these methods may take a closure instead of a string (the closure should return the string to say), so that when verbosity has been configured to be less, there are as few ignored `Data::Dumper' runs as possible :-).

Log::Log4perl defines 5 error levels (see Log::Log4perl), however syslog defines 8 (see syslog(3)); they are mapped as follows:

                         |------ PSA::Page ------|
Syslog   Log::Log4perl    dies       no die
debug       DEBUG         drop()     whisper()
info        INFO          abort()    mutter()
notice      NOTICE[*]     reject()   say()
warning     WARN          desist()   moan()
err         ERROR         barf()     complain()
crit        fatal         choke()    shout()
alert       fatal         melt()     yell()
emerg       fatal         explode()  scream()

These error levels are not expressed by the traditional names, as these terms are not consistent between implementations of logging frameworks.

The only difference between the version of the method that calls die(), and the one that doesn't, is the die. Both of them are sent to Log::Log4perl to log. To the logging system, they are identical.

A summary of each log level, and when you'd normally use them follows.

Debugging - drop(), whisper()

These calls are normally only useful when you are debugging the script. They are messages for someone who comes along later to debug the operation of the particular page.

Try not to use this on inner loops, make the messages at least mildly informative. No whisper("got here"), please.

Using drop indicates that there is usually going to be no point in logging the response, and draws its name from similar usage in firewall rules, as I could think of no other situation where an error message is something not normally logged.

Casual Inspection - stop(), mutter()

This is for the sort of messages that you'd expect -v when given to a script to issue. These two conditions are, by definition, not envisioned to be an error.

Summary overview - reject(), say()

This is for the sort of messages you'd expect to be able to find in the logs for a request on a normal day, or to be able to see printed to the terminal when running interactively. Wittering is strongly discouraged.

reject could be considered closer to croak than die.

Correctable Errors - desist(), moan()

These errors mean that something is wrong that might require attention from the administrator and/or development team. However, it is not serious enough to take immediate, automatic action. This will certainly be logged in the per-request log file, and might even raise a touble ticket.

Uncorrectable Errors - barf(), complain()

These errors mean that something is wrong that probably requires attention from the administrator and/or development team. This may indicate behaviour that takes a single user's station off-line, with a message prompting them to call the helpdesk to resolve the situation.

This will probably raise a touble ticket.

Serious Errors - choke(), shout()

Something is seriously wrong. This level of error is likely to take immediate automatic action, such as de-activating a session and marking it as requiring debugging.

Very Serious Errors - melt(), yell()

As before, but this takes the whole Service or wide-scale section of the application off-line. For instance, in a Central Reservation System for the Hotel Industry :), this might take a whole Hotel, Login account or Booking Channel offline. Use with caution.

"Oh, Shit!" Errors - explode(), scream()

This indicates an error that is so serious, that no transactions may proceed. Not even logins, or reading of information. The system is down, wake up the SysAdmin and start escalation procedures.

==head1 SEE ALSO

PSA::Config(3pm), Log::Log4perl(3pm), PSA::Cache(3pm), PSA(3pm)