Configuring the log4j.properties file for Records Manager Sweep

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

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

Logger: Services log requests from applications at run time and controls logging behavior. Each class in an application can have an individual logger or a common logger. The log4j package provides a root logger, which is the high-level logger in the logger hierarchy.
Appender: Sends the formatted log message to its specified destination. Destination examples are the console, a file, or a remote server that collects log in data to a central location. A combination of Appenders can be attached to a logger if multiple destinations or message formats are required.
Layout: Specifies the log message format. You can specify that log messages include the date, time, module name, thread name, and other information. log4j uses these configuration settings at run time when the message is logged.

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 (#) are skipped at run time.

To open the log4j.properties file, go to the ier_install_path\RecordsManagerSweep folder, then open the file by 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.rm

Or 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 that are recorded by log4j at run time. log4j supports five normal levels of logging as shown in the following table:

Table 1. Level of messages recorded by log4j at run time
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 severe error events that might cause the application to stop running.

See the log4j documentation on the Apache website for information about special and custom logging levels. By default, the application starts in the WARN level. This level 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 (#). Then, switch, as necessary, between DEBUG and WARN levels. The entries marked with the hash symbol (#) are skipped 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 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 that are 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
NTEventLog Appender	Appends to the Microsoft Windows NT Event Log. This appender can be installed and only 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 by using a layout that is specified by the user. `log4j.appender.APILOG=org.apache.log4j.ConsoleAppender` Options: Threshold=WARN: This appender does not log any messages with priority less than the one specified here even if the priority is set to a lesser level. This setting is useful to cut down the number of messages, for example, in a file log while all messages are shown on the console. ImmediateFlush=true: The default setting is true. A setting of true means that log messages are not buffered at all. If ImmdiateFlush is set to false, the last few log events are not written to constant media when problem occurs with the application.
FileAppender	Appends log messages to a file. `log4j.appender.APILOG=org.apache.log4j.FileAppender` Options: Threshold=WARN: This appender does not log any messages with priority less than the one specified here even if the priority is set to a lesser level. This setting is useful to reduce the number of messages, for example, in a file log while all messages are shown on the console. ImmediateFlush=true: The default setting is true. A true setting means that log messages are not buffered at all. If ImmdiateFlush is set to false, the last few log events are not written to constant media when problem occurs with the application. 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: The default setting is true. A true setting means to 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 does not log any messages with priority less than the one specified here even if the priority is set to less. This setting is useful to reduce the number of messages, for example, in a file log all messages are shown on the console. ImmediateFlush=true: The default setting is true. A true setting means that log messages are not buffered at all. If ImmdiateFlush is set to false, the last few log events are not written to constant media when problem occurs with the application. 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=100 KB: Suffixes can be KB, MB, or GB. Roll the log file after this size is reached. Append takes a Boolean value that determines whether output files are overwritten (false) or appended to (true). Setting the value to false (default) keeps files from growing unbounded. Use this setting in a development environment where you 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 size of the output file by setting the MaxFileSize keyword. For example, if you configure an output file, cjapi_log.txt, with MaxFileSize=128 KB and MaxBackupIndex=1, when the file exceeds 128 KB, its contents are automatically moved to cjapi_log.txt.1. Writing continues to an empty cjapi_log.txt file. MaxBackupIndex=2: Maintain a maximum of 2 (for example) backup files. Erases oldest files. 0 means that 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 other information. These configuration settings are used at run time while the message is logged.

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

Table 3. Layouts and descriptions
Layout	Description and code fragment
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 that is composed of a priority conversion specifier followed by the literal text " [". This string is followed by a thread conversion specifier, followed by literal text "]: ". This string is 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 that is 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 that makes the log request
%c	Name of the logger that is associated with the log request
%-60c	Left-align 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]