NAME

MojoX::Log::Dispatch - Log::Dispatch For Mojo

VERSION

Version 0.06

SYNOPSIS

    use MojoX::Log::Dispatch;

    # Create a Log::Dispatch whith logging object that will log to STDERR by default
    # or to file if exists attribute path
    
    my $log = MojoX::Log::Dispatch->new();

    $log->add(Log::Dispatch::File->new(name => 'file1',
                                       min_level => $self->level,
                                       filename => 'logfile' 
                                       ));
                                              
    #Add some exotic loggers
    $log->add(Log::Dispatch::Twitter->new(  username  => "foo",
                                            password  => "bar",
                                            min_level => "critical",
                                            name      => "twitter",
                                           ));
                                              
	#and now as in Mojo::Log

    $log->debug("Why isn't this working?");
    $log->info("FYI: it happened again");
    $log->warn("This might be a problem");
    $log->error("Garden variety error");
    $log->fatal("Boom!");
    $log->emergency("Boom! Boom!");
    $log->alert("Hello!");
    $log->critical("This might be a BIG problem");
    $log->warning("This might be a problem");#=warn
    $log->notice("it happened again");
    
    #OR:
    $log->log('debug' => 'This should work');
    
    
    #In your Mojo App
    # create a custom logger object for Mojo/Mojolicious to use
    # (this is usually done inside the "startup" sub on Mojolicious).
    
    use MojoX::Log::Dispatch;
    use Log::Dispatch::Syslog;
    
    my $dispatch = MojoX::Log::Dispatch->new('path' => '/home/green/tmp/mySupEr.log',
                                             'remove_default_log_obj' => 0);
	
	$dispatch->add(Log::Dispatch::Syslog->new( name      => 'logsys',
                                               min_level => 'debug',
                                               ident     => 'MyMojo::App',
                                               facility  => 'local0' 
                                               ));
	$self->log($dispatch);
	
	#and then
	$self->log->debug("Why isn't this working?");

DESCRIPTION

MojoX::Log::Dispatch wrapper around Log::Dispatch module. Log::Dispatch manages a set of Log::Dispatch::* objects, allowing you to add and remove output objects as desired.

Include log statements at various levels throughout your code. Then when you create the new logging object, set the minimum log level you want to keep track off. Set it low, to 'debug' for development, then higher in production.

ATTRIBUTES

`handle`

 my $handle = $log->handle;

Returns a Log::Dispatch object for logging if called without arguments. Returns the invocant if called with arguments.

`level`

my $level = $log->level;
$log      = $log->level('debug');

Returns the minimum logging level if called without arguments. Returns the invocant if called with arguments. Valid value are: debug, info, warn, error and fatal.

`callbacks`

    $log->callbacks( callbacks( \& or [ \&, \&, ... ] ) );
	See  Log::Dispatch->new for details

`remove_default_log_obj`

	default 1	
	
    $log->remove_default_log_obj;
	
	If true remove default log objects when C<add> new Log::Dispatch::* object

METHODS

`new`

Returns a new MojoX::Log::Dispatch object. This method takes one optional parameter (for Log::Dispatch->new):

`add`

add( Log::Dispatch::* OBJECT )

example:

$log->add(Log::Dispatch::Syslog->new( name => 'mysyslog1', min_level => 'info', facility => 'local0' ));

Adds a new a Log::Dispatch::* object to the dispatcher. If an object of the same name already exists, then that object is replaced. A warning will be issued if the $^W is true.

NOTE: This method can really take any object that has methods called 'name' and 'log'.

`log`

Like in C<Mojo::Log> (not as Log::Dispatch)

$log = $log->log(log_level_name => $ or & )

EXAMPLE

$log = $log->log('debug' => 'This should work');
$log = $log->log('alert' => 'hello');

OR

$log = $log->log('critical' => \&);

Sends the message (at the appropriate level) to all the Log::Dispatch::* objects that the dispatcher contains (by calling the log_to method repeatedly).

This method also accepts a subroutine reference as the message argument. This reference will be called only if there is an output that will accept a message of the specified level.

`log_to`

log_to( name => $, level => $, message => $ )

Sends the message only to the named object.

`would_log`

would_log( $string )

Given a log level, returns true or false to indicate whether or not anything would be logged for that log level.

`level_is_valid`

level_is_valid( $string )

Returns true or false to indicate whether or not the given string is a valid log level. Can be called as either a class or object method.

`remove`

remove('logname')

Removes the object that matches the name given to the remove method. The return value is the object being removed or undef if no object matched this.

`log_and_die`

log_and_die( level => $, message => $ or \& ) Has the same behavior as calling log() but calls _die_with_message() at the end.

`log_and_croak`

log_and_croak( level => $, message => $ or \& )

This method adjusts the $Carp::CarpLevel scalar so that the croak comes from the context in which it is called.

`_die_with_message`

_die_with_message( message => $, carp_level => $ )

This method is used by log_and_die and will either die() or croak() depending on the value of message: if it's a reference or it ends with a new line then a plain die will be used, otherwise it will croak.

You can throw exception objects by subclassing this method.

If the carp_level parameter is present its value will be added to the current value of $Carp::CarpLevel.

`output`

output( $name )

Returns an output of the given name. Returns undef or an empty list, depending on context, if the given output does not exist.

`dispatcher`

Returns a Log::Dispatch object

MojoX::Log::Dispatch inherits all methods from Mojo::Log and implements the following new ones.

LOG LEVELS

The log levels that Log::Dispatch (and MojoX::Log::Dispatch) uses are taken directly from the syslog man pages (except that I expanded them to full words). Valid levels are:

debug
info
notice
warning (=warn for Mojo::Log compatibility )
error
critical
alert
emergency (=fatal for Mojo::Log compatibility )

The syslog standard of 'err', 'crit', and 'emerg' is also acceptable.

`debug`

$log = $log->debug('You screwed up, but thats ok');

`info`

$log = $log->info('You are bad, but you prolly know already');

`notice`

   $log = $log->notice('it happened again');

`warning`

   $log = $log->warning("This might be a problem");

`warn`

   $log = $log->warn("This might be a problem");

`error`

$log = $log->error('You really screwed up this time');

`err`

$log = $log->err('You really screwed up this time');

`critical`

   $log = $log->critical("This might be a BIG problem");

`crit`

   $log = $log->crit("This might be a BIG problem");

`alert`

   $log = $log->alert("Hello!");;

`fatal`

$log = $log->fatal('Its over...');

`emergency`

   $log = $log->emergency("Boom! Boom!");;

`emerg`

   $log = $log->emerg("Boom! Boom!");;

CHEKING LOG LEVELS