WebGUI uses the log4perl logging system. The log4perl configuration file is located at:

/data/WebGUI/etc/log.conf

and by default will log only errors and fatal messages to:

/var/log/webgui.log

Some log configuration recipes are given below. You need to restart apache/spectre/wre for the changes to come into effect.

Changing the Log Level

Log4perl has 6 pre-defined logging levels:

• TRACE
• DEBUG
• INFO
• WARN
• ERROR
• FATAL

listed in increasing level of severity.

As mentioned above, by default WebGUI is configured to log messages at level WARN and above to a file. This is controlled by the following line in log.conf:

log4perl.logger = ERROR, mainlog

ERROR is the log level, mainlog is the name of the appender (defined further down in the file). If you want to change the log level, simply change ERROR to your desired level. All messages at that severity level and above will be logged.

N.B. To log all levels, you have to specify the level as ALL not TRACE.

For example, to log absolutely everything, change the line to read:

log4perl.logger = ALL, mainlog

The WebGUI code base makes use of all log levels. The following stats (generated on the 1st December, 2008) may or may not help you decide which levels you should be monitoring:

patspam $> for i in trace debug info warn error fatal; do echo -n "$i: "; ack ">$i" | wc -l; done
trace: 1
debug: 85
info: 158
warn: 178
error: 501
fatal: 27

Email On Error

It's nice to discover errors before your users do. Having log4perl email you every time an error is encountered can help in this regard, and a flood of emails can also be a surprisingly good motivator for getting the problem fixed ;)

At the time of writing the WRE does not include the Log::Dispatch::Email::MailSend module, so you may need to install it first for this to work:

> cpan install Log::Dispatch::Email::MailSend

Now, add a new appender called mailer to the end of the log4perl.logger line (top of the log.conf file):

log4perl.logger = ERROR, mainlog, mailer

Then, at the bottom of the file, define the new appender as follows:

log4perl.appender.mailer                                 = Log::Dispatch::Email::MailSend
log4perl.appender.mailer.layout                      = PatternLayout
log4perl.appender.mailer.layout.ConversionPattern     = %d - %p - %c - %M[%L] - %m%n
log4perl.appender.mailer.to                              = my_email@gmail.com
log4perl.appender.mailer.subject                     = Something's broken!
#log4perl.appender.mailer.buffered                     = 0

The first line defines the new appender, called mailer. The next 2 lines determine what the log message will look like (we're using the same layout as WebGUI's default appender). The "to" and "subject" lines control the email. The last line is optional. By default log4perl will buffer the email and only send it after the number of messages exceeds a threshold. If you uncomment this line, emails will be generated and sent immediately, one per log message.

Filtering Log Messages

Since WebGUI is designed to serve multiple sites from a single installation, the Log4perl "category" (which is the field typically used for filtering messages) is used to designate which site the log messages are coming from. This makes it easy to change the log-level on a per-site basis.

However, it's very desirable to be able to selectively filter WebGUI log messages from the particular module that you're working on (whether you're developing something new or trying to track down a bug). For example, if you're trying to track down a bug in Thingy it's nice to be able to turn on DEBUG for WebGUI::Asset::Wobject::Thingy without having to turn it on for all of WebGUI (massive information overload).

The simplest solution to this problem is to simply filter the flood of messages through grep. However this is less that ideal.

You can achieve the desired result by installing Log::Log4perl::Filter::CallerMatch. This is a custom Log4perl filter that lets you filter by calling Package and/or subroutine. 

For example, to view all DEBUG messages for Thingy, increase your default log level:

log4perl.logger = DEBUG, mainlog

and add the following filter for the default appender:

# Filter with CallerMatch
log4perl.appender.mainlog.Filter = mainfilter
log4perl.filter.mainfilter = Log::Log4perl::Filter::CallerMatch
log4perl.filter.mainfilter.PackageToMatch  = WebGUI::Asset::Wobject::Thingy

SubToMatch and PackageToMatch are both converted into regular expressions, so you can be more fancy if you like. StringToMatch, AcceptOnMatch, and frame-related options are supported too. See the CPAN page for more information.

Combining Filters

You can use Log::Log4perl::Filter::Boolean to combine multiple filters. For example, the following configuration will filter all DEBUG messages for Thingy, and also all WARN messages (and up) for all other modules:

log4perl.logger = DEBUG, mainlog
log4perl.appender.mainlog = Log::Log4perl::Appender::File
log4perl.appender.mainlog.filename = /data/wre/var/logs/webgui.log 
log4perl.appender.mainlog.layout = PatternLayout
log4perl.appender.mainlog.layout.ConversionPattern = %d - %p - %c - %M[%L] - %m%n

# Filters
log4perl.filter.f1                 = Log::Log4perl::Filter::LevelRange
log4perl.filter.f1.LevelMin        = WARN
log4perl.filter.f2                 = Log::Log4perl::Filter::CallerMatch
log4perl.filter.f2.PackageToMatch  = Thingy
log4perl.filter.f3                 = Log::Log4perl::Filter::Boolean
log4perl.filter.f3.logic           = f1 || f2
log4perl.appender.mainlog.Filter   = f3

References

• JT Smith gave a presentation at the 2007 WUC which is now part of WebGUI TV (PDF only)