The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

OpenInteract2::Manual::Logging - Logging in OpenInteract2

SYNOPSIS

This part of the manual describes the logging system, common usages and ways you can modify its behavior.

USE STANDARD SOLUTIONS

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.

QUICK LOG4PERL OVERVIEW

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.)

SAMPLE CONFIGURATION

Here's an example from the configuration file shipped with OI2, found in $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" );

OI CUSTOMIZATIONS

Custom Categories

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.

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.

Custom Appender

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.

SEE ALSO

Log::Log4perl

http://log4perl.sourceforge.net/

OpenInteract2::Log

OpenInteract2::Log::OIAppender

COPYRIGHT

Copyright (c) 2002-2004 Chris Winters. All rights reserved.

AUTHORS

Chris Winters <chris@cwinters.com>