/ 
Log-Dispatchouli-1.100670
River stage three • 15 direct dependents • 837 total dependents
/ Log::Dispatchouli

NAME

Log::Dispatchouli - a simple wrapper around Log::Dispatch

VERSION

version 1.100670

SYNOPSIS

my $logger = Log::Dispatchouli->new({
  ident     => 'stuff-purger',
  facility  => 'daemon',
  to_stdout => $opt->{print},
  debug     => $opt->{verbose}
})

$logger->log([ "There are %s items left to purge...", $stuff_left ]);

$logger->log_debug("this is extra often-ignored debugging log");

$logger->log_fatal("Now we will die!!");

DESCRIPTION

Log::Dispatchouli is a thin layer above Log::Dispatch and meant to make it dead simple to add logging to a program without having to think much about categories, facilities, levels, or things like that. It is meant to make logging just configurable enough that you can find the logs you want and just easy enough that you will actually log things.

Log::Dispatchouli can log to syslog (if you specify a facility), standard error or standard output, to a file, or to an array in memory. That last one is mostly useful for testing.

In addition to providing as simple a way to get a handle for logging operations, Log::Dispatchouli uses String::Flogger to process the things to be logged, meaning you can easily log data structures. Basically: strings are logged as is, arrayrefs are taken as (sprintf format, args), and subroutines are called only if needed. For more information read the String::Flogger docs.

METHODS

new

my $logger = Log::Dispatchouli->new(\%arg);

This returns a new logger, a Log::Dispatchouli object.

Valid arguments are:

ident      - the name of the thing logging (mandatory)
to_self    - log to the logger object for testing; default: false
to_file    - log to PROGRAM_NAME.YYYYMMDD in the log path; default: false
to_stdout  - log to STDOUT; default: false
to_stderr  - log to STDERR; default: false
facility   - to which syslog facility to send logs; default: none
log_pid    - if true, prefix all log entries with the pid; default: true
fail_fatal - a boolean; if true, failure to log is fatal; default: true
debug      - a boolean; if true, log_debug method is not a no-op
             defaults to the truth of the DISPATCHOULI_DEBUG env var

The log path is either /tmp or the value of the DISPATCHOULI_PATH env var.

If the DISPATCHOULI_NOSYSLOG env var is true, we don't log to syslog.

new_tester

This returns a new logger that logs only to_self. It's useful in testing. If no ident arg is provided, one will be generated.

log

$logger->log(@messages);

$logger->log(\%arg, @messages);

This method uses String::Flogger on the input, then logs the result. Each message is flogged individually, then joined with spaces.

If the first argument is a hashref, it will be used as extra arguments to logging. At present, all entries in the hashref are ignored.

This method can also be called as info, to match other popular logging interfaces. If you want to override this method, you must override log and not info.

log_fatal

This behaves like the log method, but will throw the logged string as an exception after logging.

This method can also be called as fatal, to match other popular logging interfaces. If you want to override this method, you must override log_fatal and not fatal.

log_debug

This behaves like the log method, but will only log (at the debug level) if the logger object has its debug property set to true.

This method can also be called as debug, to match other popular logging interfaces. If you want to override this method, you must override log_debug and not debug.

set_debug

$logger->set_debug($bool);

This sets the logger's debug property, which affects the behavior of log_debug.

is_debug

is_debug also exists as a read-only accessor. Much less usefully, is_info and is_fatal exist, both of which always return true.

dispatcher

This returns the underlying Log::Dispatch object. This is not the method you're looking for. Move along.

events

This method returns the arrayref of events logged to an array in memory (in the logger). If the logger is not logging to_self this raises an exception.

clear_events

This method empties the current sequence of events logged into an array in memory. If the logger is not logging to_self this raises an exception.

SEE ALSO

Log::Dispatch

String::Flogger

AUTHOR

Ricardo SIGNES <rjbs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Ricardo SIGNES.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.