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:

    *   Log::Fine::Handle::Console

        Provides logging to "STDERR" or "STDOUT"

    *   Log::Fine::Handle::File

        Provides logging to a file

    *   Log::Fine::Handle::File::Timestamp

        Same thing with support for time-stamped files

    *   Log::Fine::Handle::Syslog

        Provides logging to syslog

    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
    patience to review this code and offer his own suggestions. Additional
    thanks to Tom Maher and Chris Joseph for encouragement.

  Related Modules/Frameworks
    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:

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/Log-Fine>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/Log-Fine>

    *   RT: CPAN's request tracker

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Log-Fine>

    *   Search CPAN

        <http://search.cpan.org/dist/Log-Fine>

REVISION INFORMATION
      $Id: README 59 2008-05-25 22:14:22Z 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.

