MojoX::Log::Dispatch::Simple - Simple Log::Dispatch replacement of Mojo::Log
version 1.03
# from inside your startup() most likely...
use Log::Dispatch;
use MojoX::Log::Dispatch::Simple;
my $mojo_logger = MojoX::Log::Dispatch::Simple->new(
dispatch => Log::Dispatch->new,
level => 'debug'
);
my ($self) = @_; # Mojolicious object from inside startup()
$self->log($mojo_logger);
# ...then later inside a controller...
$self->app->log->debug('Debug-level message');
$self->app->log->info('Info-level message');
# ...or back to your startup() to setup some helpers...
$mojo_logger->helpers($self);
$mojo_logger->helpers( $self, qw( debug info warn error ) );
# ...so that in your controllers you can...
$self->debug('Debug-level message');
$self->info('Info-level message');
# ...or do it all at once, in the startup() most likely...
$self->log( MojoX::Log::Dispatch::Simple->new(
dispatch => Log::Dispatch->new,
level => 'debug'
)->helpers($self) );
This module provides a really simple way to replace the built-in Mojo::Log with a Log::Dispatch object, and yet still support all the Mojo::Log log levels and other functionality Mojolicious assumes exists. To make it even easier, you can install helpers to all the log levels, all from the same single line of code.
$self->log( MojoX::Log::Dispatch::Simple->new(
dispatch => Log::Dispatch->new,
level => 'debug'
)->helpers($self) );
The module tries not to make any assumptions about how you want to use Log::Dispatch. In fact, you can if desired use an alternate Log::Dispatch library so long as it offers a similar interface.
These are methods that you would likely use from within your Mojolicious
startup()
subroutine.
This method instantiates an object. It requires a "dispatch" parameter, which should be a Log::Dispatch object (or an object with a similar signature). The method allow accepts an optional "level" parameter, which is used to set the log level for your Mojolicious application.
my $mojo_logger = MojoX::Log::Dispatch::Simple->new(
dispatch => Log::Dispatch->new,
level => 'debug'
);
Optionally, you can also provide a "format_cb" value, which should be a reference to a subroutine that will be used to provide custom formatting to entries that appear on the Mojolicious error reporting web page. This formatting will have nothing at all to do with whatever your Log::Dispatch does; it only formats log entries that appear on the Mojolicious error reporting web page.
my $mojo_logger = MojoX::Log::Dispatch::Simple->new(
dispatch => Log::Dispatch->new,
level => 'debug',
format_cb => sub {
localtime(shift) . ' [' . shift() . '] ' . join( "\n", @_, '' )
},
);
By default, when you're looking at one of these Mojolicious error reporting web pages, you'll see the past 10 log entries listed. You can change that by passing in a "max_history_size" value.
my $mojo_logger = MojoX::Log::Dispatch::Simple->new(
dispatch => Log::Dispatch->new,
max_history_size => 20,
);
You can optionally tell this library to create helpers to each of the log levels, or to a selection of them. This method requires that you pass in a reference to the Mojolicious object. If that's all you pass in, the method will create a helper for every log level.
# from inside your startup()...
$mojo_logger->helpers($mojo_obj);
# now later from inside a controller...
$c->debug('Debug message');
$c->app->log->debug("This is what you'd have to type without the helper");
You can optionally pass in the names of the log levels you want helpers created for, and the method will only create methods for those levels.
$mojo_logger->helpers( $mojo_obj, qw( debug info warn ) );
Unfortunately, Mojolicious and Log::Dispatch have somewhat different ideas as to what log levels should exist. Since this module is a bridge between them, it attempts to support all levels from both sides. That being said, when calling log levels in your application, you will probably want to only use the log levels from Log::Dispatch if you use your Log::Dispatch code in non-Mojo-app areas of your ecosystem, thus keeping things uniform everywhere.
For the purposes of understanding log levels relative to each other, all log levels are assigned a "rank" value. Since Mojolicious has fewer levels than Log::Dispatch and there are 5 of them, a level's "rank" is an integer between 1 and 5.
The following are Log::Dispatch log levels along with their corresponding "rank" integer and any supported aliases:
- debug (1)
- info (2)
- notice (2)
- warning, warn (3)
- error, err (4)
- critical, crit (4)
- alert (5)
- emergency, emerg (5)
The following are Mojolicious log levels along with their corresponding "rank" integer and any supported aliases:
- debug (1)
- info (2)
- warn (3)
- error (4)
- fatal (5)
You can check what log level you're set at by either just reading $obj-
level>
or by running an "is_*" method. For every log level, there's a corresponding
"is_*" method.
my $log_level_at_or_above_notice = $obj->is_notice;
Note that this gets somewhat confusing when dealing with Log::Dispatch log
levels because from the perspective of Log::Dispatch, the "notice" level is
a unique level that's lower than a "warning" and higher than the "info" level.
However, from the perspective of Mojolicious, there's no such log level.
It will assume you're set at the "info" log level. Ergo, if you call
is_notice()
or is_info()
, you'll get the same result.
Following the creation of the object from this library, you can still manipulate various attributes, which are:
- dispatch (a Log::Dispatch object)
- level
- max_history_size
- format_cb (a subref)
- history (an arrayref)
So you can do things like:
$obj->dispatch->remove('debug');
This also means you can manipulate the log history. Why you'd ever want to do that, I can't say; but you can. Freedom is messy.
You can also look for additional information at:
Gryphon Shafer gryphon@cpan.org
This software is copyright (c) 2015 by Gryphon Shafer.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.