Configure logging

IBM FileNet Workplace XT uses the Apache log4j product to manage its logging. During logging, information about application activity is written to output locations such as the console or files. Support and development personnel use the information in log entries to analyze application activity as well as diagnose and solve problems. Logging is for diagnostic purposes only and does not provide security or audit trail information.

Enable or disable logging

The log4j product is installed during Workplace XT installation. By default, logging is not enabled during installation.

To enable or disable logging

  1. Navigate to the Workplace XT configuration folder specified during installation. The default path is:
  2. The sample logging configuration file is called __log4j.properties.

Configure logging settings

The sample log4j.properties file has a set of default options, specified as keyword=value pairs. To change the defaults, open log4j.properties with a text editor, modify as necessary, and save the file. You can configure logging settings at any time after installation. Changes you make to the logging configuration file are automatically recognized; you do not have to restart the application or the application server.

The following topics provide you with some information about some of the logging configuration options you'll see in the file. For more information about logging options, refer to the Apache web site (http://apache.org) under the Logging Project, and the Apache logging web site (http://logging.apache.org/log4j/).

Logger

A logger writes enabled logging requests to appenders. In the log4j.properties file, the first keyword describes the root logger. The root logger is the highest level logger in the hierarchy and supplies global defaults; any child logger that does not have explicitly set options inherits its behavior from the root logger.

Appender

You can specify where log data is written by configuring an appender, which sends formatted log entries to a specified output destination. Destination types can be a file or the console; output can be redirected to a Windows® Event log, forwarded to a remote log4j server, and so on. (See the Apache log4j documentation for all of the output destination and formatting options.) A single logger can have more than one appender. For example, you can write the output to a console and to a file at the same time. Increasing the number of destinations can impact performance.

In Workplace XT, two appenders are configured by default. One appender writes the log data in the IBM Common Base Event (CBE) format, which is used by IBM Support Assistant tools to process the log, and the other in a format that is more human readable. You can change the latter to reduce the amount of output, or you can turn it off completely.

NOTES 

Logging level

The logging level you specify determines the type and amount of information collected. A direct correlation exists between the amount of information collected and the performance impact on the system.

The Workplace XT application log supports standard INFO, WARN, ERROR, and FATAL levels, as well as ALL and OFF levels. The following table briefly describes the standard levels; see your Apache log4j documentation for more information about levels.

Level Description
INFO Requests informational messages that describe the progress of the application at a coarse-grained level.
WARN Requests logging for potentially harmful situations.
ERROR Requests logging exceptions thrown from within the application.
FATAL Requests logging for only very severe error events that can presumably lead to application failure.

The level you specify determines the amount of information collected. A direct correlation exists between the amount of information collected and the performance impact on the system.

Output file format

When configuring the appender, you can use the layout keyword to specify the format in which the data is written. You choose a PatternLayout and ConversionPattern. The PatternLayout specifies a particular pattern for log entries, and the ConversionPattern, which identifies the pattern of elements that is written to the appender, defines the pattern. Consider this example:

log4j.appender.ErrorOutputFile=org.apache.log4j.RollingFileAppender log4j.appender.ErrorOutputFile.layout=org.apache.log4j.PatternLayout
log4j.appender.ErrorOutputFile.layout.ConversionPattern=%d [%t] - %-5p %m\r\n

results in the following formatted log entry:

2007-05-31 17:36:12:801 [cwrap] - Document/Checkin ConnectionWrapper.send send.before

For more information about formatting options, refer to the Apache log4j documentation.

NOTE  Do not change the layout for the IBM Common Base Event (CBE) log entries. Doing so will render the output unreadable by IBM Support Assistant tools.

Analyze the output

Support personnel can examine entries in a log file to analyze application activity and diagnose problems that occur in the application. In addition, the use of IBM Support Assistant (ISA) tools automate the analysis phase. The ISA tools consume the CBE entries in the logging output from log4j.

You can also use a tool like Apache Chainsaw, a GUI-based log viewer to examine non-CBE log entries yourself.