OpenInteract2::Manual::Logging - Logging in OpenInteract2
This part of the manual describes the logging system, common usages and ways you can modify its behavior.
While you could justifiably say that OpenInteract recreates the application server wheel, the framework certainly isn't hesitant about using best-of-breed solutions where they're appropriate. Logging is one of these cases. Instead of the homegrown solution that existed in OI 1.x and early betas of 2.x, we're now using Log::Log4perl to handle the job for us.
Why? It makes for a far more flexible logging solution, allowing you to screen out the chaff and only view the wheat of the matter at hand. You can declare what messages get viewed and where the messages are sent in an external configuration file.
And it's simple to use as well. Here's a simple example:
use Log::Log4perl qw( get_logger ); use OpenInteract2::Constants qw( :log ); sub foo { my ( $self ) = @_; my $log = get_logger( LOG_APP ); $log->is_debug && $log->debug( "Entering the 'foo' method of action" ); }
Line 1 imports the get_logger method as a shortcut, and line 2 imports OI2 logging constants. Line 6 fetches the logger associated with the category referred to by the constant LOG_APP, and lines 7 and 8 actually use the logging object.
get_logger
LOG_APP
For more detailed information see the Log::Log4perl or the website listed in "SEE ALSO".
The main elements of log4perl are log levels, appenders and categories.
A log level comes from the standard syslog list: 'debug', 'info', 'warn', 'error', 'fatal'. No, you may not define more levels. (You don't need them.)
An appender tells log4perl where to send messages. An appender may add messages to a log file, send them to the console, send an email, or even create custom error objects and serialize them (see OpenInteract2::Log::OIAppender for an example).
A category is a classification for a message, and you associate a category with a logging level. This determines whether a message gets displayed. Categories also inherit from one another, so you can control a number of categories by setting the level of a category higher up the tree. Often times you'll use a class name as a category. This has the benefit of having a inheritance built in: a category 'My::App::Custom' will inherit logging levels from 'My::App' if not associated a level itself.
You may also associate a logging level threshold with an appender, which means it will not write messages with a level underneath what's defined.
The log4perl configuration file has associations for the root logger (kind of like the UNIVERSAL class from which all other classes inherit), declared appenders and categories, and the logging levels associated with each. (There are other ways to configure log4perl, but we'll stick with the external file.)
Here's an example from the configuration file shipped with OI2, found in $WEBSITE_DIR/conf/log4perl.conf:
$WEBSITE_DIR/conf/log4perl.conf
######################################## # ROOT CATEGORY log4perl.logger = FATAL, FileAppender, OIAppender ######################################## # OI2 CATEGORIES # This is the root OI2 logger. Lowering its level without specifying # the other OI2 loggers will result in lots of messages. log4perl.logger.OI2 = INFO log4perl.logger.OI2.CONFIG = WARN ... ######################################## # OI2 APPENDERS # Normal file log log4perl.appender.FileAppender = Log::Log4perl::Appender::File log4perl.appender.FileAppender.filename = /logs/oi2.log log4perl.appender.FileAppender.layout = Log::Log4perl::Layout::PatternLayout log4perl.appender.FileAppender.layout.ConversionPattern = %d: %C %L %m %n # Creates an error object and saves it to the database. Don't lower # the threshold too much! log4perl.appender.OIAppender = OpenInteract2::Log::OIAppender log4perl.appender.OIAppender.layout = Log::Log4perl::Layout::PatternLayout log4perl.appender.OIAppender.layout.ConversionPattern = %c && %C && %L && %m log4perl.appender.OIAppender.Threshold = ERROR
The original configuration defines a number of categories under the 'OI2' parent, this only lists two. The parent's level is set to 'INFO'. This means that a message logged with a level of 'DEBUG' will not be written to the appender. The level for one the subcategory 'OI2.CONFIG' is set to 'WARN', which means a message logged with a level of 'DEBUG' or 'INFO' will not be written to the appender.
So the following would write to the appender:
my $log = get_logger( LOG_OI ); $log->info( "This info message will get written" ); $log->warn( "This warn message will get written" ); my $log_conf = get_logger( LOG_CONFIG ); $log_conf->warn( "This warn message will get written" ); $log_conf->error( "This error message will get written" );
But these would not:
my $log = get_logger( LOG_OI ); $log->debug( "This debug message will NOT get written" ); my $log_conf = get_logger( LOG_CONFIG ); $log_conf->debug( "This debug message will NOT get written" ); $log_conf->info( "This info message will NOT get written" );
OI2 has a number of predefined categories in the OpenInteract2::Constants class, such as LOG_ACTION (used for internal processing by OpenInteract2::Action and partners), LOG_CACHE (to see what the cache is doing), LOG_AUTH (for messages about user logins), and more.
LOG_ACTION
LOG_CACHE
LOG_AUTH
Most appropriate for package authors is LOG_APP for applications. You can of course use your own categories but you might find it easier to control using this framework.
OI2 comes with a custom appender which takes a message, creates an error object from it and saves it to the database. From there you can browse it using the OI admin tools.
WARNING: Do not set the 'Threshold' too low on the OI appender. Otherwise your error log will be flooded with messages, making it essentially useless.
Log::Log4perl
http://log4perl.sourceforge.net/
OpenInteract2::Log
OpenInteract2::Log::OIAppender
Copyright (c) 2002-2004 Chris Winters. All rights reserved.
Chris Winters <chris@cwinters.com>
To install OpenInteract2::URL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenInteract2::URL
CPAN shell
perl -MCPAN -e shell install OpenInteract2::URL
For more information on module installation, please visit the detailed CPAN module installation guide.