Log4MT - A plugin for Movable Type v4.x and v5.x

AUTHOR: Jay Allen, Endevver LLC, http://endevver.com
LICENSE: GNU Public License v2
DATE: 08/20/2013

The Log4MT plugin enhances Movable Type with the fantastic and ultra-powerful Log4Perl logging framework. Like Log4perl, Log4MT enables you to debug your code, handle exceptions or send notifications with one of six priorities (trace, debug, info, warn, error, fatal).

The output of those messages can go to any of the following:

The webserver error log
An arbitrary file
Any database
Any socket
One or more arbitrary email addresses
The syslog
...and many more!

What's more, with Log4MT you can completely control not only the formatting of those messages but also exert granular control over what messages should trigger output, which output methods they should trigger or which messages should be ignored altogether.

For an overview on Log4MT's capabilities, see the excellent overview of Log::Log4perl "Retire your debugger, log smartly with Log::Log4perl!"

VERSION

2.0.0

REQUIREMENTS

Movable Type 4.x or greater or any version of Melody
A number of CPAN dependencies (see INSTALLATION)

LICENSE

This program is distributed under the terms of the GNU General Public License, version 2.

INSTALLATION

Install the following CPAN distributions, which are no longer included in this repository
- Log::Dispatch
- Log::Log4perl
- Moo
- strictures
- MooX::Singleton
- Sub::Install
- Sub::Quote
- Path::Tiny
- Carp::Always
- Data::Printer
- Import::Into
- Class::Method::Modifiers
Clone the repository or download the latest version and unpack the archive
Copy (or symlink) the contents of the addons and extlib directories in the archive into the respective directories in your MT/Melody application directory. In the case of extlib/MT, the directory already exists but the files being added are new.
Copy the log4mt.conf file to the root of your MT directory
Modify the log4mt.conf file to specify the desired absolute path to your log file. There are instructions inside the file which will guide you.

We recommend using cpanm for installation of CPAN modules, not only because it's awesome, but also because it supports local::lib installation of depdendencies for those who do no have root privileges on their systems.

cpanm Sub::Install Sub::Quote Log::Dispatch Log::Log4perl    \
      MooX::Singleton Path::Tiny Moo Carp::Always strictures \
      Data::Printer Import::Into Class::Method::Modifiers

And that's it!

UPGRADING

Although we strongly recommend you use the new logging initialization syntax (using MT::Logger::Log4perl) shown in the USAGE section below in any new code, we've tried our best to keep backwards compatibility to older versions.

If you are upgrading from a version earlier than v1.9.0, you will not have to change the use statements, logger initialization or logging statements in your code, which most likely look something like this:

# The easy way
our $logger ||= MT::Log->get_logger()

# Or, before MT initialization...
use MT::Log::Log4perl;
our $logger = MT::Log::Log4perl->new();

# Or, even this, with all the bells and whistles...
use Log::Log4perl qw( :resurrect );
###l4p use MT::Log::Log4perl qw( l4mtdump );
###l4p our $logger ||= MT::Log::Log4perl->new();

That said, you will have to make changes to your current log4mt.conf file to match the configuration of the default loggers and appenders shown in the bundled log4mt.conf. To avoid any problems, it's best to start with the bundled config and port any additions or changes (e.g. your log path, any custom logging levels, etc) you made from your current config to it.

USAGE

Using Log4MT in a basic way (i.e. to log messages to a file) is simple. Follow the installation instructions linked to above and then add the following to your code:

use MT::Logger::Log4perl [ @IMPORTS ]

The @IMPORTS are exactly the same as those you'd use when using Log::Log4perl directly. For example:

get_logger
:resurrect
:easy
:levels
:no_extra_logdie_message
:no_strict
And others. See the Log::Log4perl documentation for more.

Additionally, Log4MT provides one additional import, l4mtdump, that installs a function of the same name which you can (and should) use to serialize objects, references and other complex scalars (see example below).

Once you use MT::Logger::Log4perl, whenever you need to log something, you simply do the following:

my $logger = get_logger();
$logger->trace('I am here');

You can replace trace with any of the Log4perl levels—debug, info, warn, error or fatal—or any of the other logger functions described in the Log::Log4perl documentation (e.g. is_debug, less_logging)

$logger->debug('This is a debug statement');
$logger->info('FWIW, this is interesting...');
$logger->warn('User doesn't have a display name: ', $author->name);
$logger->error('Ran into an error saving entry: ', l4mtdump($entry));
$logger->fatal(sprintf 'Application %s died with error "%s"',
    ref($app), ($app->errstr || $@));

The trace function is somewhat special in that it additionally logs some information about the location of the logging call as well as characters which help to set it off from the rest. This is best used at the top of a method.

CONFIGURATION

For most users, the basic configuration is enough to get you started logging. If, however, you want to turn down the logging level without removing your logging statements or do some more exotic things, the log4mt.conf file is the heart of the an incredible amount of functionality.

Everything you can do with the config file to customize Log4MT is documented in the Log::Log4perl documentation.

ADVANCED FEATURES

Coming soon...

VERSION HISTORY

You can view the release history and changelog in the GitHub repository.

AUTHOR

This plugin was brought to you by Jay Allen, Principal and Chief Architect of Endevver LLC. I hope that you get as much use out of it as I have.

openmelody / mt-plugin-log4mt