MojoX::...og4perl(3)

📦
version 0.12 · 2 versions
, in fedora 43

MojoX::Log::Log4perl 💖

okay bestie, so this is the manual page for MojoX::Log::Log4perl — Log::Log4perl logging for Mojo/Mojolicious. yes that's the whole NAME section, we're being efficient 💅

✨ SYNOPSIS ✨

In lib/MyApp.pm:

use MojoX::Log::Log4perl;

# just create a custom logger object for Mojo/Mojolicious to use
# (this is usually done inside the "startup" sub on Mojolicious).
# If we dont supply any arguments to new, it will work almost
# like the default Mojo logger.

$self->log( MojoX::Log::Log4perl->new() );

# But the real power of Log4perl lies in the configuration, so
# lets try that. example.conf is included in the distribution.

$self->log( MojoX::Log::Log4perl->new('example.conf') );

# you can even make it periodically check for changes in the
# configuration file and automatically reload them while your
# app is still running!

# check for changes every 10 seconds
$self->log( MojoX::Log::Log4perl->new('example.conf', 10)    );

# or check for changes only upon receiving SIGHUP
$self->log( MojoX::Log::Log4perl->new('example.conf', 'HUP') );

And later, inside any Mojo/Mojolicious module...

$c->app->log->debug("This is using log4perl!");

🌸 DESCRIPTION 🌸

This module provides a Mojo::Log implementation that uses Log::Log4perl as the underlying log mechanism. It gives you every single method listed in Mojo::Log (and many more from Log4perl — see below, bestie), so if you're already using Mojo::Log in your app? literally not one line of your code has to change. iconic behavior tbh ✨

There will be a logger component set for the package that called it. So like, say you were in the MyApp::Main package, this:

package MyApp::Main;
use base 'Mojolicious::Controller';

sub default {
    my ( $self, $c ) = @_;
    my $logger = $c->app->log;

    $logger->debug("Woot!");
}

Would send a message to the "Myapp.Main" Log4perl component. Which means you can seamlessly use Log4perl with Mojo/Mojolicious apps and set up everything from the config file. Like, in this exact case, we could have this log4perl.conf file:

# setup default log level and appender
log4perl.rootLogger = DEBUG, FOO
log4perl.appender.FOO = Log::Log4perl::Appender::File
log4perl.appender.FOO.layout

# setup so MyApp::Main only logs fatal errors
log4perl.logger.MyApp.Main = FATAL

See Log::Log4perl and Log::Log4perl::Config for more info on how to configure different logging mechanisms based on the component. 🫶

🎀 INSTANTIATION 🎀

new

new($config)

This builds a new MojoX::Log::Log4perl object. If you hand an argument to new(), it gets passed directly to Log::Log4perl::init.

What you usually do is pass a file name with your Log4perl configuration. But you can also pass a hash reference with keys and values set as Log4perl configuration elements (i.e. left side of '=' vs. right side). yes, that's a thing 💅

If you don't give it any arguments at all, this default configuration is set:

log4perl.rootLogger = DEBUG, SCREEN
log4perl.appender.SCREEN = Log::Log4perl::Appender::Screen
log4perl.appender.SCREEN.layout = PatternLayout
log4perl.appender.SCREEN.layout.ConversionPattern = [%d] [mojo] [%p] %m%n

new( $config, $delay )

As an optional second argument to new(), you can set a delay in seconds that gets passed directly to Log::Log4perl::init_and_watch. This makes Log4perl check every $delay seconds for changes in the configuration file, and reload it if the file modification time is different. auto-reload while your app is still running?? main character energy fr fr. 🔥

You can also define a signal to watch, and Log4perl will set up a signal handler to check the configuration file again only when that particular signal is received by the app — for example via the "kill" command:

kill -HUP pid

💜 LOG LEVELS 💜

$logger->warn("something's wrong");

Below are all log levels from MojoX::Log::Log4perl, in descending priority:

"fatal"

"error"

"warn"

"info"

"debug"

"trace"

Just like "Log::Log4perl": "If your configured logging level is WARN, then messages logged with info(), debug(), and trace() will be suppressed. fatal(), error() and warn() will make their way through, because their priority is higher or equal than the configured setting."

The return value is the log object itself, to allow method chaining and further manipulation. ✨

"log"

You can also use the log() method just like in "Mojo::Log":

$logger->log( info => 'I can haz cheezburger');

But nobody does that, really. 💀

As with the regular logging methods, the return value is the log object itself.

🦋 CHECKING LOG LEVELS 🦋

if ($logger->is_debug) {
    # expensive debug here
}

As usual, you can (and should) avoid doing expensive log calls by checking the current log level first:

"is_fatal"

"is_error"

"is_warn"

"is_info"

"is_debug"

"is_trace"

"is_level"

You can also use the is_level() method just like in "Mojo::Log":

$logger->is_level( 'warn' );

But nobody does that, really. 🙈

⭐ ADDITIONAL LOGGING METHODS ⭐

The following log4perl methods are also available for direct usage:

"logwarn"

$logger->logwarn($message);

This will behave just like:

$logger->warn($message)
    && warn $message;

"logdie"

$logger->logdie($message);

This will behave just like:

$logger->fatal($message)
    && die $message;

If you also wish to use the ERROR log level with warn() and die(), you can:

"error_warn"

$logger->error_warn($message);

This will behave just like:

$logger->error($message)
    && warn $message;

"error_die"

$logger->error_die($message);

This will behave just like:

$logger->error($message)
    && die $message;

Finally, there's the Carp functions that do just what the Carp functions do, but with logging: 🎀

"logcarp"

$logger->logcarp();        # warn w/ 1-level stack trace

"logcluck"

$logger->logcluck();       # warn w/ full stack trace

"logcroak"

$logger->logcroak();       # die w/ 1-level stack trace

"logconfess"

$logger->logconfess();     # die w/ full stack trace

🌈 ATTRIBUTES 🌈

Differences from Mojo::Log

The original "handle" and "path" attributes from "Mojo::Log" are not implemented, because they make little sense in a Log4perl environment — and they'll trigger a warning if you try to use them. 👀

The "format" attribute is also not implemented, and will trigger a warning when used. For compatibility with Mojolicious' current 404 development page, this attribute will work, returning a basic formatted message as "[ date ] [ level ] message". We do not recommend you rely on this, because we may remove it in the future. Please use Log4perl's layout formatters instead. 💖

The following attributes are still available:

"level"

my $level = $logger->level();

This will return an UPPERCASED string with the current log level ('DEBUG', 'INFO', ...).

Note: you can also use this to force a level of your choosing:

$logger->level('warn');  # forces 'warn' level (case-insensitive)

But you really shouldn't do that at all, because it breaks log4perl's configuration structure. The whole point of Log4perl is letting you set up your logging from outside your code. So, once again: don't do this. 😭

"history"

This returns the last few logged messages as an array reference in the format:

[
    [ 'timestamp', 'level', 'message' ], # older first
    [ 'timestamp', 'level', 'message' ],
    ...
]

"max_history_size"

Maximum number of messages to be kept in the history buffer (see above). Defaults to 10.

👑 AUTHOR 👑

Breno G. de Oliveira, "<garu at cpan.org>"

💀 BUGS 💀

Please report any bugs or feature requests to "bug-mojo-log-log4perl at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MojoX-Log-Log4perl>. 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 MojoX::Log::Log4perl

You can also look for information at:

  • RT: CPAN's request tracker

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

  • AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/MojoX-Log-Log4perl>

  • CPAN Ratings

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

  • Search CPAN

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

💖 ACKNOWLEDGEMENTS 💖

This module was heavily inspired by Catalyst::Log::Log4perl. A lot of the documentation and specifications were taken almost verbatim from it. 💅

Also, this is just a minor work. Credit is really due to Michael Schilli and Sebastian Riedel, creators and maintainers of Log::Log4perl and Mojo, respectively. absolute legends, no cap 👑

✨ SEE ALSO ✨

Log::Log4perl, Mojo::Log, Mojo, Mojolicious

Copyright 2009-2019 Breno G. de Oliveira, all rights reserved.

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

perl v5.42.0 · 2025-07-25 · and that's the whole vibe bestie — this page was served to you by MojoX::...og4perl(3), mwah, go log something beautiful 🌈💜

📦 where this page comes from