IBM Enterprise Records, Version 5.1.+            

Configuring the log4j.properties file

The IBM® Enterprise Records application includes a sample log4j.properties file that you can configure.

The log4j.properties file is located in the ier_install_path\ RecordsManagerSweep folder, and you can configure the logging behavior by specifying values in the file for the following:

Each logger in the log4j.properties file is assigned a level. If you do not assign a level to a logger, then log4j automatically assigns the level of the parent logger to the unassigned logger. By default, the WARN level is assigned to a logger.

You can configure the log4j.properties file with different settings of logger, appender, and layout. The log4j.properties file must be available to the application at run time from the class path. You can comment out entries in the sample file by prefixing the statement with a hash symbol (#); the entries marked with the hash symbol (#) will not be executed at run time.

To open the log4j.properties file, navigate to the ier_install_path\RecordsManagerSweep folder, then open the file using a text editor.

Set logger and logging level

You first need to set the logger. You can have a number of loggers to classify the type of logging you require for the application. To enable logging for all classes of com.filenet.rm and its sub packages, specify the logger as shown in the following statement:

log4j.logger.com.filenet.rmor 

You can specify any name for the logger. For example, you can name your logger APILOG as shown in the following statement:

log4j.logger.com.filenet.rm=warn, APILOG

You need to set a logging level to establish the detail level of messages recorded by log4j at runtime. log4j supports five normal levels of logging as shown in the table below.

Table 1. Level of messages recorded by log4j at runtime
Level Description
DEBUG Designates fine-grained informational events that are most useful to debug an application.
INFO Designates informational messages that highlight the progress of the application at coarse-grained level.
WARN Designates potentially harmful situations.
ERROR Designates error events that might still allow the application to continue running.
FATAL Designates very severe error events that will presumably lead the application to abort.

See the log4j documentation on the Apache web site for information about special and custom logging levels. By default, the application starts in the WARN level. This can be modified to DEBUG, INFO, ERROR, WARN, or FATAL levels at run time. You can also include several logger statements, each for the same logger but with different levels (such as DEBUG for one, WARN for another). You can comment out one or the other in the sample file by prefixing the statement with a hash symbol (#) and switch as necessary between DEBUG and WARN levels. The entries marked with the hash symbol (#) will not be executed at run time. A logger that does not have a level automatically inherits the level of its parent logger. By default, the WARN level is assigned to the RM API logger in IBM Enterprise Records.

Set appenders

A logger is associated with one or more appenders to enable its log messages to be written to output media. You can set different kinds of appenders in the log4j.properties file that sends the log information to the specified output location. The following table provides a list of all the appenders being used in the log4j.properties file along with brief descriptions and related options.

Table 2. Appenders, descriptions, and code fragments
Appender Description and Code Fragments
NTEventLogAppender

Appends to the Microsoft Windows NT Event Log. This appender can only be installed and used on a Windows system.

log4j.appender.APILOG=org.apache.log4j.nt.NTEventLogAppender
ConsoleAppender

Appends log messages to System.out (the default) or System.err stream using a layout specified by the user.

 log4j.appender.APILOG=org.apache.log4j.ConsoleAppender

Options:

  • Threshold=WARN: This appender will not log any messages with priority lower than the one specified here even if the logger's priority is set lower. This is useful to cut down the number of messages, for example, in a file log while displaying all messages on the console.
  • ImmediateFlush=true: The default setting is true, meaning log messages are not buffered at all. If ImmdiateFlush is set to false, the last few log events may not be written to constant media when problem occurs with the application. The recommended setting is true.
FileAppender

Appends log messages to a file.

 log4j.appender.APILOG=org.apache.log4j.FileAppender

Options:

  • Threshold=WARN: This appender will not log any messages with priority lower than the one specified here even if the logger's priority is set lower. This is useful to cut down the number of messages, for example, in a file log while displaying all messages on the console.
  • ImmediateFlush=true: By default, it is set to true, meaning log messages are not buffered at all. If ImmdiateFlush is set to false, the last few log events may not be written to constant media when problem occurs with the application. The recommended setting is true.
  • File=mylog.txt: File name to log to. You can use ${some_property_key} (for example, java.home or user.home system properties) to specify the path.
  • Append=false: By default is set to true, which means append to the end of the file. False overwrites the file at the start of each program run.
RollingFileAppender

Extends FileAppender to back up the log files when they reach a certain size.

 log4j.appender.APILOG=org.apache.log4j.RollingFileAppender

Options:

  • Threshold=INFO: This appender will not log any messages with priority lower than the one specified here even if the logger's priority is set lower. This is useful to cut down the number of messages, for example, in a file log while displaying all messages on the console.
  • ImmediateFlush=true: By default, it is set to true, meaning log messages are not buffered at all. If ImmdiateFlush is set to false, the last few log events may not be written to constant media when problem occurs with the application. The recommended setting is true.
  • File=mylog.txt: File name to log to. You can use ${some_property_key} (for example, java.home or user.home system properties) to specify the path in front.
  • Append=false: By default, it is set to true, which means append to the end of the file. false overwrites the file at the start of each program run.
  • MaxFileSize=100KB: Suffixes can be KB, MB or GB. Roll the log file after this size is reached . Append takes a boolean value that determines if output files will be overwritten (false) or appended to (true). Setting the value to false (default) keeps files from growing outbounded, and is recommended for development environments in which you will make occasional one-time runs. Setting the value to true appends output to an existing log file on each JVM run. You can limit the output file's size by setting the MaxFileSize keyword. For example, if you configure an output file, cjapi_log.txt, with MaxFileSize=128KB and MaxBackupIndex=1, when the file exceeds 128 KB, its contents are automatically moved to cjapi_log.txt.1 and writing continues to an empty cjapi_log.txt.file.
  • MaxBackupIndex=2: Maintain a maximum of 2 (for example) backup files. Erases oldest file(s). 0 means no backup files are kept.

Set layouts

You can set different layouts in the log4j.properties file that specify the log message format. You can specify that log messages include the date, time, module name, thread name, and so on. These configuration settings are used at run time while logging the message.

The following table provides a list of all the layouts being used in the IBM Enterprise Records log4j.properties file along with brief descriptions and options.

Table 3. Layouts and descriptions
Layout Description and code fragement
SimpleLayout

Prints the Level, then a dash (-) followed by the log message text.

org.apache.log4j.SimpleLayout
PatternLayout

Formats logging events according to a specified conversion pattern. Conversion patterns are composed of literal text and conversion specifiers. Literal text is output as is. Conversion specifiers consist of the % character followed by an optional format modifier and a mandatory conversion character. For example, %-5p [%t]: %m%n is a conversion pattern composed of a priority (a.k.a. level) conversion specifier followed by the literal text " [", followed by a thread conversion specifier, followed by literal text "]: " followed by a message conversion specifier and a system dependent line separator.

org.apache.log4j.PatternLayout

Options:

  • ConversionPattern=%-5p, [%t]:%m%n: How to format each log message (what information to include).
HTMLLayout

Formats the output as an HTML table.

org.apache.log4j.HTMLLayout

Options:

  • LocationInfo=true: Outputs Javaâ file name and line number. Default setting is false.
  • Title=My app title: Sets the <title> tag of HTML. Default setting is Log4J Log Messages.
 

Formats the output as XML.

org.apache.log4j.xml.XMLLayout

Options:

  • LocationInfo=true: Outputs Java file name and line number. Default setting is false.

The log4j.properties file supplied with IBM Enterprise Records uses PatternLayout for log message format. The following table provides a list of conversion patterns that can be declared in the configuration file along with their brief descriptions:

Table 4. Conversion patterns and descriptions
Pattern Description
%t Name of the thread making the log request
%c Name of the logger associated with the log request
%-60c Left-justify the logger name within 60 spaces minimum
%r Number of milliseconds elapsed since start of the application
%p Level of the log statement
%m Message
%Time Time at which logging occurs
%d Date of the logging event
%n New line

The following code statement shows how to enable PatternLayout and specify a simple conversion pattern:

log4j.appender.APILOG.layout=org.apache.log4j.PatternLayout
log4j.appender.APILOG.layout.ConversionPattern=%-5p %d {dd MMM yyyy HH:mm:ss,SSS}, -%m, %r, [%M] % n

For example:

WARN, 20 Jun 2005 14:48:20,900, -[enter] getObjectStoreXML(ObjectStores), 102042, [setLoggerMessage]
WARN, 20 Jun 2005 14:48:21,100, -[exit] getObjectStoreXML(ObjectStores), 102342, [setLoggerMessage]


Feedback

Last updated: August 2011
configure_rm_logging.htm

© Copyright IBM Corporation 2011.
This information center is powered by Eclipse technology. (http://www.eclipse.org)