Configuration of the Apache log4j Java-based logging utility

Use this information to understand how to use the Apache log4j Java-based logging utility in the context of the Cúram Social Program Management environment.

The Apache log4j Java-based logging utility provides extensive support for configuring the destination of the trace information. The documentation that follows does not attempt to duplicate the log4j documentation but places this information in the context of IBM® Cúram Social Program Management. The configuration information needs to be placed in a file pointed at by the curam.trace.configfile.location property.

If the curam.trace.configfile.location property is not set, the default log4j setting is to use a Console Appender. The Console Appender outputs everything output at the default (or higher) log4j level to System Out. The default log4j level for the top-level logger (and all inherited loggers) is set to DEBUG.¹

Configuration results in trace information to be written to a rolling file appender. This operation means that the output is placed in a file until it reaches a specified size. After it reaches this size it is rolled-over, and it is renamed by appending a .1 to the file name. If a .1 file exists, it first is renamed to .2, and so on.

This procedure is suitable for development environments where a historical trace can be useful.

Figure 1. Configuring log4j

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<!--
   | For more configuration information and examples
   | see the Jakarta Log4j website:
   | http://jakarta.apache.org/log4j
-->

<log4j:configuration
  xmlns:log4j="http://jakarta.apache.org/log4j/"
  debug="false">

  <!-- ========================== -->
  <!-- Append messages to a File -->
  <!-- ========================== -->
  <appender name="OutputToFile"
            class="org.apache.log4j.RollingFileAppender">
    <param name="File"
           value="d:/CuramProps/CuramAppLog.log" />
    <param name="Threshold"
           value="debug"/>
    <param name="MaxBackupIndex"
           value="3"/>

    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern"
           value="[%-5p] [%X{user}] [%X{alternateuserid}] [%d{dd MMM yyyy HH:mm:ss}] [%c] - %m%n"/>
    </layout>
  </appender>

  <!-- ======================= -->
  <!-- Setup the Root category -->
  <!-- ======================= -->
  <root>
    <level value="INFO"/>
    <appender-ref ref="OutputToFile"/>
  </root>

</log4j:configuration>

A number of customizable values exist in this file:

The name of the log file is set to be d:/CuramProps/CuramAppLog.log.
The maximum number of previously rolled back files that are preserved is set to 3.
The maximum file size is not explicitly set so the default of 10 Mb is used.
The conversion pattern has several parameters that results in the following output:
- %-5p - The level of the trace message after it is left padded to be a five character string.
- %X{user} - This operation adds the user name associated with a transaction to the logs.
- %X{alternateuserid}- This operation adds the alternate login ID for the user associated with a transaction to the logs. If the user is not logged on using the alternate login ID, then the user who is associated with the transaction is added.
- %c - The category of the trace message.
- %m - The trace message itself.
- %n- A platform-specific line separator.
The log4j level is set to INFO, which means that all items that are logged at the DEBUG level are ignored. This operation overwrites the default level of DEBUG set by the infrastructure.

Two application properties examined when the process populates the {user} and {alternateuserid} parameters:

Table 1. Application properties examined when the {`user`} and {`alternateuserid`} parameters are populated
Property Name	Explanation
`curam.security.altlogin.enabled`	A Boolean flag to indicate that users can log in to the application by using their alternate login ID
`curam.trace.deferred.user.name`	A Boolean flag for deferred processing transactions which, when set to true, indicates that the name of the user who initiates the deferred process transaction is made available for logging purposes

The tables that follow represent use cases that can be achieved with the new feature. The feature contains two aspects - online transactions and deferred process transactions.

Depending on the values that are specified for the two properties that were described previously, the following data is made available for logging in the {user} and {alternateuserid} parameters:

Table 2. Use case scenarios for online transactions
Property name: curam.security.altlogin.enabled	User Name	Alternate Login ID	Login Used	Available Values
`TRUE`	`caseworker`	`caseworkeralt`	`caseworker`	user=caseworker alternateuserid=`caseworkeralt`
`TRUE`	`caseworker`	`caseworkeralt`	`caseworkeralt`	user=`caseworker` alternateuserid=caseworkeralt
`TRUE`	`caseworker`	-	`caseworker`	user=`caseworker` alternateuserid=`caseworker`
`TRUE`	`caseworker`	-	`caseworkeralt`	`ERROR`
`FALSE`	`caseworker`	`caseworkeralt`	`caseworker`	user=`caseworker` alternateuserid=`””`
`FALSE`	caseworker	`caseworkeralt`	`caseworkeralt`	`ERROR`
`FALSE`	`caseworker`	-	`caseworker`	user=`caseworker` alternateuserid=`””`

Table 3. Use case scenarios for deferred process transactions
Property name: curam.trace.deferred.user.name	curam.security.altlogin.enabled	Username	Alternate Login ID	Deferred User Name	Deferred User Name Alternate Login ID	Login Used	Available Values
`TRUE`	`TRUE`	`SYSTEM`	-	`beantester`	`beantesteralt`	`beantester`	user=beantester alternateuserid=beantesteralt
`TRUE`	`FALSE`	`SYSTEM`	-	`beantester`	`beantesteralt`	`beantester`	user=beantester alternateuserid=””
`FALSE`	`TRUE`	`SYSTEM`	-	beantester	beantesteralt	beantester	user=SYSTEM alternateuserid=””
`FALSE`	`FALSE`	`SYSTEM`	-	`beantester`	`beantesteralt`	`beantester`	user=SYSTEM; alternateuserid=””

However, direct access to a file might not be an ideal mechanism if the trace output needs to be monitored. Configuration results in trace information to be written to a socket. A listener (such as Apache Chainsaw that is delivered with log4j) can then be used to display the resultant information.

Figure 2. Configuring log4j to log to a socket

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<!--
   | For more configuration information and examples
   | see the Jakarta Log4j website:
   | http://jakarta.apache.org/log4j
-->

<log4j:configuration
  xmlns:log4j="http://jakarta.apache.org/log4j/"
  debug="false">

  <!-- =========================== -->
  <!-- Append messages to a Socket -->
  <!-- =========================== -->
  <appender name="OutputToSocket
            class="org.apache.log4j.net.SocketAppender">
    <param name="RemoteHost"
           value="localhost" />
    <param name="Port"
           value="4445"/>

    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern"
          value="[%-5p] [%X{user}] [%d{dd MMM yyyy HH:mm:ss}] [%c] - %m%n"/>
    </layout>
  </appender>

  <!-- ======================= -->
  <!-- Setup the Root category -->
  <!-- ======================= -->
  <root>
    <level value="INFO"/>
    <appender-ref ref="OutputToSocket"/>
  </root>

</log4j:configuration>

The conversion pattern that is used in this file is the same, but some extra customizable values have been introduced:

The host name and port of the remote server are set to localhost for the host name and 4445 for the port of the remote server.

Numerous other possibilities exist for this configuration and the explanation that is presented here does not attempt to duplicate the existing log4j documentation. However, it is worth noting that Nested Diagnostic Contexts are not currently supported.

¹ The set of possible levels (in order of priority) defined by log4j is ALL, DEBUG, INFO, WARN, ERROR, FATAL, and OFF. Only those items that are logged at the specified level or higher levels are included in the log.