NAME

Contentment::Hooks - Handles logging for Contentment

DESCRIPTION

This logger is smart enough to queue up early error messages and allows for multiple logs. This uses the Contentment::Hooks system to actually post the logs. Each log has a hook named "Contentment::Log::logname".

This log API doesn't really do much on it's own. Hooks must be registered for it to really do anything. You might want to see the information in the Log plugin for Contentment, since it is generally used to setup the actual file logging and such.

Contentment::Log->log(\%args);

This is the most basic log method. All the other methods are just wrappers for this one.

It is normally assumed thet %args will be passed via an anonymous reference. Be aware that log() will make changes to the reference passed in, in the interest of speed. Mostly, it will replace the message argument with an interpolated version. However, other changes might occur to (depending on if the code has changed and this documentation has not).

This method takes the following arguments:

name (required)

The name of the log to send the message to. This method will then call the hook named "Contentment::Log::$name".

message (required)

This is a string that will be passed as the message to the hook handlers. This string may be formatted as for sprintf with the interpolation variables passed in the "args" argument. (The reason for offering this kind of interpolation is that I hope to add internationalization at some later point, which will be more easily done this way.)

args (optional)

This is a reference to an array of values used to interpolate the "message" argument.

level (optional)

This argument is specific to the "error" log, but is shown here since it's common. This should be one of the following string values:

DEBUG

INFO

WARNING

ERROR

These are just suggestions, but these are the levels currently used by Contentment internally. Additional log levels may be added in the future.

would_log (optional)

If this argument is specified and set to a true value, then the handlers registered are not supposed to log anything, but return whether or not they would log anything. The logical disjunction (OR) of all the results will be returned.

In addition to these arguments, any other named argument may be passed to contain other information.

The hook handlers will be passed this reference with the message string interpolated, but otherwise unchanged.

This method will returned a logical disjunction (OR) of all the return values from all the handlers. When the would_log argument is passed with a true value this result will be whether or not any log handler will use the logged information. When the would_log argument is false or not passed, this result will be whether or not any log handler did successfully do something with the log.

Contentment::Log->would_log(\%args)

This method is exactly the same as the log() method with a couple exceptions. First, it makes sure the would_log argument is set to a true value. Second, it does not perform any string interpolation of the given message and args.

It can be used as a quick short cut to see if a call to log() will have any affect:

Contentment::Log->would_log(name => 'error', level => 'DEBUG')
    && Contentment::Log->debug(
           # Some expensive operation
       );

This method will also use the log named "error" by default. Therefore, the following is the same as before:

Contentment::Log->would_log(level => 'DEBUG')
    && Contentment::Log->debug(
           # Some expensive operation
       );

Contentment::Log->debug(@msg, \@args)

This is a shortcut for calling:

  Contentment::Log->log(
      name    => "error", 
	  level   => "DEBUG", 
	  message => join($,, @msg), 
	  args    => $args,
  );

The \@args array is optional.

Contentment::Log->info(@msg, \@args)

This is a shortcut for calling:

  Contentment::Log->log(
      name    => "error", 
	  level   => "INFO", 
	  message => join($,, @msg), 
	  args    => $args,
  );

The \@args array is optional.

Contentment::Log->warning(@msg, \@args)

This is a shortcut for calling:

  Contentment::Log->log(
      name    => "error", 
	  level   => "WARNING", 
	  message => join($,, @msg), 
	  args    => $args,
  );

The \@args array is optional.

Contentment::Log->error(@msg, \@args)

This is a shortcut for calling:

  Contentment::Log->log(
      name    => "error", 
	  level   => "ERROR", 
	  message => join($,, @msg), 
	  args    => $args,
  );

The \@args array is optional.

CUSTOM LOG HANDLERS

If you wish to write a custom log handler. You simply need a method that will accept all the arguments passed to the log() method. The would_log argument must be handled such that a true would_log flag doesn't result in logging, but a check to see whether logging will occur.

Log handlers don't need to worry about string interpolation. String interpolation is already handled within the log() method.

HOOKS

Contentment::Log::logname

The system provides the ability for multiple logs. If your module needs a special log for something, you may register for any logname you want and then use the log() method to log there:

Contentment::Log->log({
    name => 'my_foo_log',
    some_other_custom_foo_arg => 'foo foo FOO!',
    message => 'Log to foo, foo!'
});

Contentment::Log::error

This is the priamry log hook for the system. The error log has much the same functionality as Apache's error_log. (Indeed, the default configuration currently sends all of the information logged to this hook to that file when running under Apache.)

Contentment::Log::access

This log is currently not in use, but is planned for use by Contentment. It will be used to record page accesses handled by the system for the creation of statistics.

HOOK HANDLERS

Contentment::Log::default_logger

This is the hook hook handler performs a queue-register-reply role prior to any other hooks being registered for the "Contentment::Log::error" hook.

When the Contentment::Log package is first loaded, this default logger is registered for "Contentment::Log::error". This log handler checks to see if any other handler has been registered between log calls. If no handler has been registered, it queues up messages each time it's called. This will continue until another handler is registered for the hook. Once that happens, the default log handler unregisters itself and replays the queued log. This way, no log messages are lost even though most log handlers are going to be added as plugins late in the game.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

COYPRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

Contentment is licensed and distributed under the same terms as Perl itself.