10 Configuring the Logging System

This chapter describes the Apache log4j-based logging framework used by OCMS. This chapter includes the following sections:

"Overview of log4j Logging in OCMS"
"Defining Rolling File Appenders for Core Components"
"Setting the Log Levels for Core Components"
"Exposing a Component's Log Levels through the SIP Servlet Container Logging MBean"
"Viewing Application Log Files"

Overview of log4j Logging in OCMS

The global log4j.xml file enables you to modify the logging for OCMS. Changes made to this file persist; changes that you make to the logging file through the SIP Servlet Container Logging MBean are temporary.

You configure the log4j logging system by editing the global log4j.xml properties file, located within ORACLE_HOME/j2ee/home/lib/ext in Oracle Containers for J2EE (OC4J). Upon initialization of the application server, the log4j logging system configures itself by reading the global log4j.xml properties file.

Defining Rolling File Appenders for Core Components

You define the appenders and categories used for logging of SIP traffic, JMX, and system components events in the global log4j.xml file. SIP traffic is logged through the file's traffic component, the JMX component logs JMX-related events. The system component logs all of the OCMS system-level log events. The default configuration of log4j.xml (illustrated in Example 10-1) defines rolling file appenders for each of these core components.

Example 10-1 The Default Rolling File Appenders in log4j.xml

<!-- A time/date based rolling appender -->
  <appender name="JMX_FILE_SIZE"
    class="org.apache.log4j.RollingFileAppender">
    <param name="File" value="${oracle.j2ee.home}/log/sdp/jmx.log" />
    <param name="Append" value="true" />
    <param name="Encoding" value="UTF-8" />
    <param name="MaxFileSize" value="100000KB" />
    <param name="MaxBackupIndex" value="10" />
 
    <layout class="org.apache.log4j.PatternLayout">
      <!-- The default pattern: Date Priority [Category] Message\n -->
      <param name="ConversionPattern"
        value="%d{yyyy-MM-dd HH:mm:ss,SSSZ} %-5r %-5p [%c] (%t:%x) %m%n" />
    </layout>
  </appender>
 
  <!-- A time/date based rolling appender -->
  <appender name="SYSTEM_FILE_SIZE"
    class="org.apache.log4j.RollingFileAppender">
    <param name="File" value="${oracle.j2ee.home}/log/sdp/system.log" />
    <param name="Append" value="true" />
    <param name="Encoding" value="UTF-8" />
    <param name="MaxFileSize" value="100000KB" />
    <param name="MaxBackupIndex" value="10" />
 
    <layout class="org.apache.log4j.PatternLayout">
      <!-- The default pattern: Date Priority [Category] Message\n -->
      <param name="ConversionPattern"
        value="%d{yyyy-MM-dd HH:mm:ss,SSSZ} %-5r %-5p [%c] (%t:%x) %m%n" />
    </layout>
  </appender>
 
  <!-- A time/date based rolling appender -->
  <appender name="TRAFFIC_FILE_SIZE"
    class="org.apache.log4j.RollingFileAppender">
    <param name="File" value="${oracle.j2ee.home}/log/sdp/traffic.log" />
    <param name="Append" value="true" />
    <param name="Encoding" value="UTF-8" />
    <param name="MaxFileSize" value="100000KB" />
    <param name="MaxBackupIndex" value="10" />
 
    <layout class="org.apache.log4j.PatternLayout">
      <!-- The default pattern: Date Priority [Category] Message\n -->
      <param name="ConversionPattern"
        value="%d{yyyy-MM-dd HH:mm:ss,SSSZ} %-5r %-5p [%c] (%t:%x) %m%n" />
    </layout>
  </appender>
 
  <appender name="EVENTLOGGER_FILE_SIZE"
    class="org.apache.log4j.RollingFileAppender">
    <param name="File" value="${oracle.j2ee.home}/log/sdp/events.log" />
    <param name="Append" value="true" />
    <param name="Encoding" value="UTF-8" />
    <param name="MaxFileSize" value="100000KB" />
    <param name="MaxBackupIndex" value="10" />
    <layout class="oracle.sdp.eventlogger.BasicLayout"></layout>
  </appender>

The output of the traffic, system and JMX components is written to the traffic.log, system.log and jmx.log files located within the log/sdp directory of the OCMS OC4J instance's J2EE home. In standalone OC4J, the log files are located within ORACLE_HOME/j2ee/home; in Oracle Application Server, the log files are located at ORACLE_HOME/j2ee/OCMS. These components write output using the pattern of

Date MS Priority
Category (Thread:NDC) Message

The log files are automatically backed up by log4j's Rolling File Appender implementation. A minimum number of backups is maintained (up to the MaxBackupIndex), each backup having a maximum file size as specified in the MaxFileSize log4j configuration parameter.

Setting the Log Levels for Core Components

You can set the logging level of the traffic, system, and JMX components dynamically through a JMX console (such as the Oracle Application Server System MBean browser), or statically by editing the global log4j.xml file. On Oracle Application Server, the log4j configuration changes that are made to the log4j.xml file are picked up automatically every 60 seconds and do not require a server reboot. On a standalone OC4J instance, the server must be restarted for the configuration changes to take effect.

Setting the Log Levels through the Oracle Application Server Control MBean Browser

The log level for the system, traffic, and JMX components can be modified at runtime by modifying the attributes of the SIP Servlet Container Logging MBean using Application Server Control (Figure 10-1) as described in "Accessing SIP Servlet Container MBeans". The attributes of the SIP Servlet Container Logging MBean enable you to set the log levels for the core components (as well as logging levels for the SDP call flow) to OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, or ALL.

Note:

Changes made at runtime using Application Server Control will not be persisted. Restarting the SIP Servlet Container resets the log levels for the core components to the default values set in the global log4j.xml file.

For more information on these logging levels and the parameters of the SIP Servlet Container Logging MBean, see "SIP Servlet Container Logging".

Figure 10-1 Attributes of the SIP Servlet Container Logging MBean

Description of "Figure 10-1 Attributes of the SIP Servlet Container Logging MBean"

Setting the Default Log Levels by Updating the log4j Configuration

You can also set the default log level for the core components by modifying the global log4j.xml file for the corresponding categories. As illustrated in Example 10-2, you can change the default log level for the traffic component by setting the <priority value> for the log4j category named com.hotsip.log.traffic.

Example 10-2 Changing the Default Log Level

<category name="oracle.sdp">
   <priority value="ERROR"/>
   <appender-ref ref="SYSTEM_FILE_DAILY"/>
</category>
…
<category name="com.hotsip.log.traffic">
   <priority value="INFO"/>
   <appender-ref ref="TRAFFIC_FILE_DAILY"/>
   </category>

The mapping of the core components to log4j categories is located in the sdp-log-components.xml file. In a standalone instance of OC4J, this file is located within ORACLE_HOME/j2ee/home/config directory. In Oracle Application Server, this file is located at ORACLE_HOME/J2EE/ocms/config.

Note:

All instances of OC4J with a given Oracle home share the same log4j logging system configuration since the log4j logging system is deployed and configured as a global library. Applications employing log4j for logging must add the appropriate configuration to the global log4j.xml properties file.

Exposing a Component's Log Levels through the SIP Servlet Container Logging MBean

You can use the OCMS logging framework to configure logging for a component and then expose the log levels through the SIP Servlet Container Logging MBean. To do this, you first configure the log4j categories corresponding to the components and then map these categories to the component. For more information, see "SIP Servlet Container Logging".

Defining log4j Appenders and Categories

Before you can write logs to the log4j system from the Java classes, you must first define the log4j categories and appenders. You can configure the log4j system either programatically or by updating the global log4j.xml properties file (illustrated in Example 10-3).

Example 10-3 Configuring a log4j Category for a Component in log4j.xml

<category name="com.company.component">
   <priority value= "INFO"/>
   <appender-ref ref="CONSOLE"/>
</category>

Refer to http://logging.apache.org/log4j/docs/ for more information on adding and configuring log4j categories and appenders.

Exposing the log4j Log Level for the Component

After you configure the categories in the log4j subsystem, you map them to the component by adding an entry to the sdp-log-components.xml file as illustrated in Example 10-4. This entry must include the name of the component and a list of the categories configured in the log4j system. When you complete the entry, the component is exposed as an attribute of the SIP Servlet Container Logging MBean. Setting the value for this attribute sets the log level for all of the categories defined for the component in the sdp-log-components.xml file.

Note:

For these changes to take effect, the Oracle Application Server must be restarted.

Example 10-4 Mapping log4j Categories to the Component in sdp-log-components.xml

<component name="example component">
   <logger name= "com.company.component"/>
</component>

Viewing Application Log Files

You can access the J2EE-specific logging data for OMCS applications from the Log Files page of the Oracle 10g Application Server Control Console. To access this page, first click Logs. In the Log Files page that appears, expand the OCMS entry to view the deployed applications. Use the View task to examine the application.log file for an OCMS application (Figure 10-2). For more information on viewing log files, refer to Oracle Application Server Administrator's Guide.

Figure 10-2 Viewing Logging Data for an OCMS Application

Description of "Figure 10-2 Viewing Logging Data for an OCMS Application"