plainblack.com
Username Password
search
Bookmark and Share

Logging

WebGUI has a very powerful logging system that enables you, the Administrator, to get exactly the information you need to keep WebGUI running smoothly and error free. This chapter covers some of the ways in which you can harness the power of the WebGUI logging system.

 

Basic Configuration

All WebGUI logging is controlled through a single configuration file. This configuration file starts out very small and simple, but can grow to become very complex depending upon your needs.

The log file is located in /data/WebGUI/etc and is called log.conf. You have to create this file as part of your WebGUI install, or if you’re using the WRE, it will create the log.conf file for you. If you need to create this file, the easiest way to do it is to copy log.conf.original to log.conf.

This is what the default log file looks like:

 

log4perl.logger = WARN, mainlog

log4perl.appender.mainlog = Log::Log4perl::Appender::File

log4perl.appender.mainlog.filename = /var/log/webgui.log

log4perl.appender.mainlog.layout = PatternLayout

log4perl.appender.mainlog.layout.ConversionPattern = %d - %p - %c - %M[%L] - %m%n

 

 

This can be a bit overwhelming to look at all at once, so let’s break it down into it’s parts, line by line.

The first line tells the logging system that we’re going to create a logging object called “mainlog” and that it’s going to log “WARN”, “ERROR”, and “FATAL” messages. Have a look at that line:

 

log4perl.logger = WARN, mainlog

 

The second line invokes the “appender” or mechanism that we’re going to use to write the log out somewhere. By default we usually like to put logs into files. However, we can put logs out to databases, email addresses, logging servers, or all sorts of other places. In this case, the appender we’re using will put the logging information into a file. Take a look:

 

log4perl.appender.mainlog = Log::Log4perl::Appender::File

 

The third line tells the appender where we’re going to store the log. Given that the appender we’re using writes out to a file, we give it a file path. If the appender used as an email based appender we’d probably specify an email address and mail server configuration. The default location for the WebGUI log is /var/log/webgui.log. Take a look at the line that sets this up:

 

log4perl.appender.mainlog.filename = /var/log/webgui.log

 

The fourth line tells the appender how we want to format the information that the logger is given. There are various logging standards for layout, and we could use one of them, but we want to grant ourselves maximum control, so we’re going to tell the appender that we wish to use a pattern based layout. Take a look at that line:

 

log4perl.appender.mainlog.layout = PatternLayout

 

The fifth and final line specifies the pattern that we want to use to lay out the each line in the log. There are lots of symbols used here, and each represents a piece of data. We’ll get into what each means later, but for now take a look at the line that defines the pattern:

 

log4perl.appender.mainlog.layout.ConversionPattern = %d - %p - %c - %M[%L] - %m%n

 

Log Levels

WebGUI has five levels of logging, and each adds its own distinct kind of information to the log. They are FATAL, ERROR, WARN, INFO, and DEBUG. Each one builds on the previous, so ERROR includes FATAL, and WARN includes ERROR and FATAL, and so on.

 

FATAL

The fatal log level only logs “show-stopper” errors. In other words, errors that are so devastating that WebGUI cannot continue processing the page because doing so is either impossible or would be dangerous. Thankfully the number of things that can cause fatal errors is pretty low. They generally either indicate that WebGUI cannot connect to some critical resource, such as the database or file system, or that a programmer has introduced a bug into the system. You should never see fatal errors.

 

ERROR

The error log level logs all errors that do not fall under the fatal category. These are breaks in functionality, but WebGUI can continue processing the page. Examples are that WebGUI can’t overwrite a file that is write protected, it tries to connect to an external server, but the connection is refused, or perhaps WebGUI detected that a user has entered invalid data into a form. Most things that fall under this category are correctable through configuration changes, or other small adjustments.

 

WARN

The warn log level advises you of warnings, or things that aren’t errors, but could be harmful none-the-less. Examples are when a user tries to do something s/he doesn’t have the privileges to do, or when site visitors are requesting pages that don’t exist.

 

INFO

The info log level gives you some insight into the inner workings of WebGUI. You’ll generally see these when WebGUI is working on multi-step complex process, such as processing workflows. This log level can be extremely useful when you’re trying to troubleshoot a problem with the system.

 

DEBUG

The debug log level is a very verbose log level that tells you everything that’s going on in the internals of WebGUI. It show’s you stack traces for the errors and fatals, it shows you every database query running through the system, and much more. In fact, from an administrator’s point of view there’s really almost too much information being provided at the debug level. Unless you are a developer, or have become very familiar with WebGUI, this log level will likely only serve to confuse you rather than help you diagnose a problem.

 

Separate Log Files Per Site

Creating a separate log file for each of your sites is quite simple. It’s really just a variation on the default logger configuration that comes with WebGUI. Let’s say that you have two sites www.foo.com and www.bar.com and you want a separate log file for each. Furthermore, you want Spectre (the workflow controller) to log it’s messages in its own file as well.

 

log4perl.logger.www.foo.com.conf = WARN, foo

log4perl.appender.foo = Log::Log4perl::Appender::File

log4perl.appender.foo.filename = /var/log/webgui.foo.log

log4perl.appender.foo.layout = PatternLayout

log4perl.appender.foo.layout.ConversionPattern = %d - %p - %c - %M[%L] - %m%n

 

log4perl.logger.www.bar.com.conf = WARN, bar

log4perl.appender.bar = Log::Log4perl::Appender::File

log4perl.appender.bar.filename = /var/log/webgui.bar.log

log4perl.appender.bar.layout = PatternLayout

log4perl.appender.bar.layout.ConversionPattern = %d - %p - %c - %M[%L] - %m%n

 

log4perl.logger.spectre.conf = WARN, spectre

log4perl.appender.spectre = Log::Log4perl::Appender::File

log4perl.appender.spectre.filename = /var/log/spectre.log

log4perl.appender.spectre.layout = PatternLayout

log4perl.appender.spectre.layout.ConversionPattern = %d - %p - %c - %M[%L] - %m%n

 

Notice that we can reference each site (and Spectre), by it’s config file name.

 

log4perl.logger.www.bar.com.conf = WARN, bar

 

And we give each logger object its own unique identifier:

 

log4perl.logger.www.bar.com.conf = WARN, bar

 

Sending Emails From Logs

One way to make absolutely sure that your WebGUI system is operating in good health is to have the system email you on all fatal errors. Some people go so far as to email themselves on all errors and warnings, but depending upon how your users use your site, that can fill up your inbox quite quickly, and be relatively expensive performance-wise.

To send yourself emails directly from the WebGUI log you first need to install a new perl module called Log::Dispatch::Email::MailSend. Here are the commands to do this from the command line.

 

. /data/wre/sbin/setenvironment


cpan

 

Once in the CPAN interactive shell type:

 

install Log::Dispatch::Email::MailSend

exit

 

Now that you’ve installed this module, all you have to do is add a new logger object to your log.conf file, and restart Apache. The new logger object will look similar to the following, be sure to replace our example with your own information where you see bold lettering:

 

log4perl.category = FATAL, MailME
log4perl.appender.MailME = Log::Dispatch::Email::Send
log4perl.appender.MailME.to = info@example.com
log4perl.appender.MailME.subject = Don’t panic but we’ve got a FATAL error
log4perl.appender.MailME.layout = SimpleLayout
log4perl.appender.MailME.buffered = 0

 

You’re now getting emails about fatal errors. Note that these messages are small enough that they can work with email-to-text pagers (like your cell phone).

Keywords: config file configuration debug error fatal info warn

Search | Most Popular | Recent Changes | Wiki Home
© 2018 Plain Black Corporation | All Rights Reserved