Revision as of 18:00, 13 May 2008

Logging for Web Applications and Web Services

Log4j will be used to do logging in web applications (such as the COSMOS UI) and web services (data managers). Information about log4j can be found at the log4j website.

Logging Configurations

To configure a web applciation to use log4j, we need a configuration file called log4j.properties in the classpath, usually put under WebContent/WEB-INF/classes. Axis2.jar comes with a log4j.properties that contains some default settings.

The installation/configuration program of the COSMOS demo should update the log4j.properties file to include settings appropriate for the COSMOS demo. Deployers can also customize the logging settings.

In order to log all log entries to the same log file, we need to add the following lines to the log4j.properties:

# Configure all classes in the org.eclipse.cosmos namespace to use the COSMOSLOG logger
# Change "ALL" to the desired log level
log4j.logger.org.eclipse.cosmos=ALL, COSMOSLOG

# COSMOSLOG is set to be a File appender using a PatternLayout.
log4j.appender.COSMOSLOG=org.apache.log4j.FileAppender
log4j.appender.COSMOSLOG.File=${CATALINA_HOME}/logs/cosmos.log
log4j.appender.COSMOSLOG.Append=true
log4j.appender.COSMOSLOG.layout=org.apache.log4j.PatternLayout
log4j.appender.COSMOSLOG.layout.ConversionPattern=%d [%t] %-5p %c %x - %m%n

The above configuration will write the logs to cosmos.log file in the logs directory under the Tomcat install directory.

We can also configure log4j to open a log file for each web application or web service, assume each web application or web service has a unique package namespace. For example, if we want the broker to have a separate log file, we can add the following lines to the log4j.properties:

# Logger for COSMOS Broker
log4j.logger.org.eclipse.cosmos=ALL, BROKERLOG

# COSMOSLOG is set to be a File appender using a PatternLayout.
log4j.appender.BROKERLOG=org.apache.log4j.FileAppender
log4j.appender.BROKERLOG.File=${CATALINA_HOME}/logs/cosmos-broker.log
log4j.appender.BROKERLOG.Append=true
log4j.appender.BROKERLOG.layout=org.apache.log4j.PatternLayout
log4j.appender.BROKERLOG.layout.ConversionPattern=%d [%t] %-5p %c %x - %m%n

Logging API

In a java class that requires logging, get an instance of a logger with the following code:

import org.apache.log4j.Logger;
Logger logger = Logger.getLogger(getClass());

The logger can be made a private class variable.

Log4j comes with some convenient methods for logging in different "levels" - the severity of log entry.

This methods are:

public void debug(Object message);
public void info(Object message);
public void warn(Object message);
public void error(Object message);
public void fatal(Object message);

// the following methods will also include the stack trace of the Throwable t passed in as parameter.
public void debug(Object message, Throwable t);
public void info(Object message, Throwable t);
public void warn(Object message, Throwable t);
public void error(Object message, Throwable t);
public void fatal(Object message, Throwable t);

log4j also provided more general logging API that supports localization:

l7dlog(Priority priority, java.lang.String key, java.lang.Throwable t);
l7dlog(Priority priority, java.lang.String key, java.lang.Object[] params, java.lang.Throwable t);

We will discuss the use of log levels and localization of log messages in a subsequent section.

Log Levels

FATAL - rarely used, usually imply imminent crash of the application or the relevant sub-component

ERROR - used for logging a Java exception or an error condition

WARN - indicate minor problems or potential errors.

INFO - provide information about significant events in the normal life cycle of the application

DEBUG - provides information useful for debugging purpose, such as values of some variables or some trace information.

Externalize log messages

All messages, with the exception of debug statements, have to be externalized to allow for translation. Debug statements are usually used for during development and not printed at production. That's why debug statement don't need to be translated.

All messages to be translated are declared in a properties file (resource bundle). The resource bundle can be accessed with a fully qualifed package name. For example, message resource bundle of the example MDR and its translations can be placed under org/eclipse/cosmos/example/mdr.

org/eclipse/cosmos/example/mdr/messages.properties
org/eclipse/cosmos/example/mdr/messages_fr.properties 
org/eclipse/cosmos/example/mdr/messages_ja.properties
org/eclipse/cosmos/example/mdr/messages_zh_TW.properties

The bundle is accessed using "org.eclipse.cosmos.example.mdr.messages".

There are a couples ways to use the resource bundle together with the log4j logging API.

Using the l7dlog API

l7d stands for "localized". (There are 7 letters between 'l' and 'd'.)

Set the resource bundle in the logger immediately after you get the reference of the logger.

logger = Logger.getLogger(getClass());
logger.setResourceBundle(ResourceBundle.getBundle("org.eclipse.cosmos.example.mdr.messages"));

Define messages in messages.properties:

STARTUP_INFO=COSMOS broker is starting up.
REG_FAILED_ERR=Registration of data manager {0} failed.

Note that the curly bracket with a number in it is for substituting values into the message. You can use {1}, {2}, etc, for subsequent values to be substituted.

Call l7dlog as follows:

logger.l7dlog(Level.INFO, "STARTUP_INFO", null);
logger.l7dlog(Level.ERROR, "REG_FAILED_ERR", new Object[] {"Example MDR"}, exception));

The exeption parameter can be null.

IMPORTANT: DO NOT concatinate fragments of a sentense and variables with '+' operator because it will make translation impossible. That is, don't do this: "Registration of data manager" + name + "failed."

Naming Convention for Message Keys

Logging for Eclipse Plugins