/ 
Log-Fine-0.20
River stage zero No dependents
/ Log::Fine

NAME

Log::Fine - Yet another logging framework

SYNOPSIS

Provides fine-grained logging and tracing.

use Log::Fine;
use Log::Fine qw( :masks );          # log masks
use Log::Fine qw( :macros :masks );  # everything

# grab our logger object
my $log = Log::Fine->getLogger("foo");

# register a handle, in this case a handle that logs to console.
my $handle = Log::Fine::Handle::Console->new();
$log->registerHandle( $handle );

# log a message
$log->log(INFO, "Log object successfully initialized");

# create a clone of a Logger object and a handle object
my $clone1 = $log->clone();          # <-- clone of $log
my $clone2 = $log->clone($handle);

DESCRIPTION

Log::Fine provides a logging framework for application developers who need a fine-grained logging mechanism in their program(s). By itself, Log::Fine provides a mechanism to get one or more logging objects (called loggers) from its stored namespace. Most logging is then done through a logger object that is specific to the application.

Handles

Handlers provides a means to output log messages in one or more ways. Currently, the following handles are provided:

See the relevant perldoc information for more information. Additional handlers can be defined to the user's taste.

Log Levels

Log::Fine bases its log levels on those found in Sys::Syslog. For convenience, the following shorthand macros are exported.

  • EMER

  • ALRT

  • CRIT

  • ERR

  • WARN

  • NOTI

  • INFO

  • DEBG

Each of these corresponds to the appropriate logging level.

Masks

Log masks can be exported for use in setting up individual handles (see Log::Fine::Handle). Log::Fine exports the following masks corresponding to their log level:

  • LOGMASK_EMERG

  • LOGMASK_ALERT

  • LOGMASK_CRIT

  • LOGMASK_ERR

  • LOGMASK_WARNING

  • LOGMASK_NOTICE

  • LOGMASK_INFO

  • LOGMASK_DEBUG

See Log::Fine::Handle for more information.

In addition, the following shortcut constants are provided. Note that these are not exported by default, rather you have to reference them explicitly, as shown below.

  • Log::Fine->LOGMASK_ALL

    Shorthand constant for all log masks.

  • Log::Fine->LOGMASK_ERROR

    Shorthand constant for LOGMASK_EMERG through LOGMASK_ERR. This is not to be confused with LOGMASK_ERR.

In addition, you can specify your own customized masks as shown below:

# we want to log all error masks plus the warning mask
my $mask = Log::Fine->LOGMASK_ERROR | LOGMASK_WARNING;

Formatters

A formatter specifies how Log::Fine displays messages. When a message is logged, it gets passed through a formatter object, which adds any additional information such as a time-stamp or caller information.

By default, log messages are formatted as follows using the Basic formatter object.

[<time>] <LEVEL> <MESSAGE>

For more information on the customization of log messages, see Log::Fine::Formatter.

METHODS

The Log::Fine module, by itself, simply exports a few constants, and allows the developer to get a new logger. After a logger is created, further actions are done through the logger object. The following two constructors are defined:

new()

Creates a new Log::Fine object.

getLogger($name)

Creates a logger with the given name. This method can also be used as a constructor for a Log::Fine object

clone([$obj])

Clone the given Log::Fine object, returning the newly cloned object. If not given an object, then returns a clone of the calling object.

ACKNOWLEDGMENTS

I'd like the thank the following people for either inspiration or past work on logging: Josh Glover for his work as well as teaching me all I know about object-oriented programming in perl. Dan Boger for taking the time and patience to review this code and offer his own suggestions. Additional thanks to Tom Maher and Chris Josephs for encouragement.

The following logging frameworks provided inspiration for parts of Log::Fine.

  • Dave Rolsky's Log::Dispatch module

  • Sun Microsystem's java.utils.logging framework

  • The Python logging package

SEE ALSO

perl, syslog, Log::Fine::Handle, Log::Fine::Formatter, Log::Fine::Logger, Sys::Syslog,

AUTHOR

Christopher M. Fuhrman, <cfuhrman at panix.com>

BUGS

Please report any bugs or feature requests to bug-log-fine at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Log-Fine. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Log::Fine

You can also look for information at:

REVISION INFORMATION

$Id: Fine.pm 94 2008-07-05 17:54:27Z cfuhrman $

COPYRIGHT & LICENSE

Copyright (c) 2008 Christopher M. Fuhrman, All rights reserved.

This program is free software licensed under the...

The BSD License

The full text of the license can be found in the LICENSE file included with this module.