NAME

Krang::Log - Krang logging module

SYNOPSIS

  use Krang::ClassLoader Log => qw(debug info critical ASSERT assert affirm should shouldnt);

  # logging messages
  debug("I'm inside of block X and \$a == $a.");

  critical("This is a critical application failure!!!!");

  info("Supply informative message here.");

  # assertion functions from Carp::Assert
  assert($positive >= 0) if ASSERT
  affirm { $positive >= 0 } if ASSERT;
  should($nine, 9) if ASSERT;
  shouldnt($nine, 10) if ASSERT;

  # reopen log file (usually after a fork)
  reopen_log();

DESCRIPTION

This module logs messages to file based on the configuration directives set in 'krang.conf'. The relevant configuration directives are:

• LogLevel
  
Determines the minimum log level to be recorded. This value may be set to a single integer. The acceptable values for this setting are the integers 1-3 which correspond to functions: critical, info, debug. For example, to see all messages:

  LogLevel 3

Optionally, log levels may be set for specific modules. For example, if you were working on Krang::CGI::Story and didn't want to see debug messages from other modules:

  LogLevel 2,Krang::CGI::Story=3

You can also specify a regex to match against module names. For example, to suppress debug messages from all CGI modules:

  LogLevel 3,/^Krang::CGI/=2

• Assertions
  
If set to true assertions will be active. This is the default for 'make test' but setting it in krang.conf will activate assertions all the time.

On compilation, the log object is created and all the functions provided in the import list are exported into the caller's namespace. No functions are exported by default.

The following log levels are supported and available as exported functions:

• debug (3)
  
Verbose debugging messages should use this level. Messages at this level need only be useful to a developer working on the code.
• info (2)
  
Generally useful informational messages belong at this level. These messages should highlight the actions the application is taking at a moderate level of detail.
• critical (1)
  
Error messages resulting from uncaught exceptions will be written at this level. Other messages that should *always* make their way to the log file should use this level too. Explicit use of this log-level should be very rare.

Output from this module resembles the following:

   [timestamp] [level] message

Please note, a newline character will be appended to the message if one is not included.

INTERFACE

• log
  
Most of the work for this module is done here. All calls to convenience methods are routed through AUTOLOAD() to here; function calls exported via import() are redirected to AUTOLOAD() which in turn end up here.

This method takes two arguments:

• level
  
This arg must be one of the valid levels in %valid_functions or an error is thrown. The valid levels in increasing severity are: debug, info, critical. The integers 1-3 are also valid arguments; on output they are converted to their corresponding strings
• message
  
The string to be logged to the logfile.

• debug($msg)
  
Log a message at the debug level. Available for export.
• info($msg)
  
Log a message at the info level. Available for export.
• critical($msg)
  
Log a message at the critical level. Available for export.
• assert
  
• affirm
  
• should
  
• shouldnt
  
These functions are exported directly from Carp::Assert, with one change. Instead of using the DEBUG constant, use the ASSERT constant exported by Krang::Log. For all other information, see Carp::Assert.
• reopen_log()
  
Closes and reopens the logfile. This call should be used in the event that the running code is forking child processes. Child processes cannot share the filehandle held by their parent, and need to make this call to reopen_log to regain logging ability.

Will croak if it cannot open the logfile.

TO DO

• Fix flock() bugs and re-enable flock() around print() to log.
  
• Log tracing for errors.
  

SEE ALSO

Krang, Krang::Conf, Time::Piece