5.9 Logging from portlets

< Day Day Up >

Testing provides quality assurance and confidence in an application. Logging, on the other hand, equips the developer with detailed context for application failures. Logging and testing should not be confused; they are complementary techniques. When logging is wisely used, it can prove to be a valuable tool, and it is one of the key issues to consider in portlet development work.

Inserting log statements into your portlet code is a low-tech method for debugging it. However, some people argue that log statements pollute source code and decrease legibility. In the Java language, where a preprocessor is not available, log statements increase the size of the code and reduce its speed, even when logging is turned off. Given that a reasonably sized application may contain thousands of log statements, speed is of particular importance.

In this section we introduce two different mechanism to do logging. First we describe how the WebSphere Portal server itself can handle portlet logging. Then we explain how to build your own flexible mechanism to log from portlets.

WebSphere Portal-based log

WebSphere Portal uses the Logging Toolkit for Java (JLog) to help operate, maintain, and troubleshoot the portal and portlets. JLog creates detailed log and debug files while working in the background, thereby reducing the use of system resources.

JLog supports the logging of messages as errors and status information, and the logging of debugging messages called traces. These traces are useful for fixing problems; however, to save system resources, they are switched off by default.

Message and trace logging

Portlets can write message and trace information to log files, which are maintained in the wps_root/app/web/WEB-INF/log/ directory. The log files help the portal administrator investigate portlet errors and special conditions and help the portlet developer test and debug portlets. The Portlet API provides the PortletLog class, which has methods to write message and trace information to the logs:

debug() writes trace information to PortletTraces.log
info() writes informational messages to Portlet.log
error() writes error messages to Portlet.log
warn() writes warning messages to Portlet.log

If you access the portlet log multiple times in a method, it is a good idea to assign the log reference to a variable, for example:

    private PortletLog myLogRef = getPortletLog();

Since logging operations are expensive, PortletLog provides methods to determine if logging is enabled for a given level. Your portlets should write to the log of a given level only if the log is tracking messages on that level. For example:

    if( getPortletLog().isDebugEnabled() )      {        myLogRef.debug("Warning, Portlet Resources are low!");      }

Location of log files

The log files created by JLog are located in the directory wps_root/app/web/WEB-INF/log, and they are updated if an error occurs.

Each component of WebSphere Portal uses its own log file. These can be found when you log into the portal as administrator and select Portal Administrator → Portal Settings → Enable tracing. The most useful traces to switch on for portlet developers are traces that start with "Portlet," for example, PortletTraceLogger.

To enable the creation of these messages for uses such as debugging during portlet development, you need to change the configuration files.

All configuration files ending with TraceLogger.properties contain the key isLogging which is set to false. To activate the logging of debug messages for the relevant WebSphere Portal component, set this key to true. Any changes you make to the configuration files become active only after restarting the application server.

Example 5-10: Example code using logging

 public void init (PortletConfig portletConfig) throws UnavailableException    {         super.init( portletConfig);         if ( getPortletLog().isDebugEnabled() ) {             getPortletLog().debug("HelloWorld: init called");         }         // The default Hello String is obtained from the portlet configuration parameters         defaultString = portletConfig.getAttribute("defaultHelloString");     }

Creating your own logging mechanism with log4j

The portal's standard way to log from portlets can be hard to use, since all the important portlet logging is put in the same big file. It can be a time consuming and frustrating task to find out which entry came in from which portlet, as they all share the same log file.

With log4j (log for Java) you can build your own logging mechanism individually for each portlet. With log4j it is possible to enable logging at runtime without modifying the application binary. Furthermore, the log4j package is designed so that these statements can remain in shipped code without incurring a heavy performance cost.

Implementing this tailored logging is easy: you import the log4j.jar file into your project, add some coding, and set parameters, and you have a working logging mechanism. In the integration techniques section we give an example.

The target of the log output can be a file, an OutputStream, a java.io.Writer, a remote log4j server, a remote UNIX Syslog daemon, or even an NT Event logger, among many other output targets.

Tip

Logging behavior can be controlled by editing a configuration file, without touching the application binary.

One of the distinctive features of log4j is the notion of inheritance in loggers. Using a logger hierarchy, it is possible to control which log statements are output at arbitrarily fine granularity, and to do so with great ease. This helps reduce the volume of logged output and minimize the cost of logging.

Inserting log requests into the application code requires a fair amount of planning and effort. Observation shows that approximately 4 percent of code is dedicated to logging. Consequently, even moderately sized applications will have thousands of logging statements embedded within their code. Given their number, it becomes imperative to manage these log statements without the need to modify them manually.

The log4j environment is fully configurable programmatically. However, it is far more flexible to configure log4j using configuration files. Currently, configuration files can be written in XML or in Java properties (key=value) format.

Basics of log4j

The use of log4j revolves around 3 main concepts:

Public class Logger. Logger is responsible for handling the majority of log operations.
Public interface Appender. Appender is responsible for controlling the output of log operations.
Public abstract class Layout. Layout is responsible for formatting the output for Appender.

Logger

The logger is the core component of the logging process. In log4j, there are 5 normal levels of logger available, not including custom Levels.

As identified in the log4j API, the levels are the following:

Static Level DEBUG: The DEBUG Level designates fine-grained informational events that are most useful to debug an application.
Static Level INFO: The INFO level designates informational messages that highlight the progress of the application at a coarse-grained level.
Static Level WARN: The WARN level designates potentially harmful situations.
Static Level ERROR: The ERROR level designates error events that might still allow the application to continue running.
Static Level FATAL: The FATAL level designates very severe error events that will presumably lead the application to abort.

In addition, there are two special levels of logging available:

Static Level ALL: The ALL Level has the lowest possible rank and is intended to turn on all logging.
Static Level OFF: The OFF Level has the highest possible rank and is intended to turn off logging.

The preceding descriptions are from the log4j API at:

http://jakarta.apache.org/log4j/docs/api/index.html

The behavior of loggers is hierarchical. Figure 5-18 illustrates this.

click to expand
Figure 5-18: Log4j logging levels

A logger will only output messages that are of a level greater than or equal to it. If the level of a logger is not set it will inherit the level of the closest ancestor.

Appender

The public interface Appender controls how the logging is output. The Appenders are described in the log4j API. There are 10 established appenders, and you can also implement the Appender interface to create your own ways of outputting log statements. The list of appenders is found on the Apache Web site at:

http://jakarta.apache.org/log4j/docs/api/index.html

We used FileAppender to append log events to a file.

Layout

The Appender must have an associated Layout so it knows how to format the output. There are three types of Layout available:

HTMLLayout formats the output as a HTML table.
PatternLayout formats the output based on a conversion pattern specified, or if none is specified, the default conversion pattern.
SimpleLayout formats the output in a very simple manner: it prints the Level, then a dash '-' and then the log message.

We provide examples of using log4j in the next chapter.

Note

In addition to log4j, there are other technologies to accomplish this type of logging.

< Day Day Up >