Skip Headers

Oracle® Communication and Mobility Server Administrator's Guide Release 10.1.3 Part Number E10292-02 |
Home | Contents | Index | Contact Us

Previous | Next
| View PDF

# 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 behavior of the traffic, system, config, badmsg and statstics component loggers. 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) or in the `$JBOSS_HOME/server/$jboss_server_name/conf` directory in the JBoss Application Server. Upon initialization of the application server, the log4j logging system configures itself by reading the global `log4j.xml` properties file.

Note:

The CUSTOMER_FILE_LOG in Example 10-1 is the system logger.

## Defining Rolling File Appenders for Core Components

You configure the rolling file appenders used for component loggers by defining the global `log4j.xml` file (illustrated in Example 10-1). The default configuration of `log4j.xml` defines rolling file appenders for each of these loggers.

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

    <!-- A size based rolling appender -->
      <appender name="CUSTOMER_FILE_LOG"
        class="org.apache.log4j.RollingFileAppender">
        <param name="File" value="${oracle.j2ee.home}/log/sdp/system/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{1}] (%t:%x) %m%n" />
        </layout>
      </appender>

      <!-- A size based rolling appender -->
      <appender name="TRAFFIC_FILE_LOG"
        class="org.apache.log4j.RollingFileAppender">
        <param name="File" value="${oracle.j2ee.home}/log/sdp/traffic/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{ISO8601} %-5p [%c{1}] (%t:%x) %m%n" />
        </layout>
      </appender>

      <!-- A size based rolling appender -->
      <appender name="BADMSG_FILE_LOG"
        class="org.apache.log4j.RollingFileAppender">
        <param name="File" value="${oracle.j2ee.home}/log/sdp/badmsg/badmsg.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{ISO8601} %-5p [%c{1}] (%t:%x) %m%n" />
        </layout>
      </appender>

      <!-- A size based rolling appender -->
      <appender name="CONFIG_FILE_LOG" class="org.apache.log4j.RollingFileAppender">
        <param name="File" value="${oracle.j2ee.home}/log/sdp/config/config.log" />
        <param name="Append" value="true"/>
        <param name="Encoding" value="UTF-8" />
    <param name="MaxFileSize" value="500KB"/>
    <param name="MaxBackupIndex" value="2"/>

        <layout class="org.apache.log4j.PatternLayout">
          <!-- The default pattern: Date [Category] Message\n -->
          <param name="ConversionPattern"
            value="%d{yyyy-MM-dd HH:mm:ss,SSSZ} [%c{1}] %m%n" />
        </layout>
      </appender>

      <!-- A size based rolling appender -->
      <appender name="STATISTICS_FILE_LOG" class="org.apache.log4j.RollingFileAppender">
        <param name="File" value="${oracle.j2ee.home}/log/sdp/statistics/statistics.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">
          <param name="ConversionPattern"
            value="%d{yyyy-MM-dd HH:mm:ss,SSSZ} %m%n" />
        </layout>
      </appender>

      <appender name="STATISTICS_FORMAT_FILE_LOG" class="org.apache.log4j.RollingFileAppender">
        <param name="File" value="${oracle.j2ee.home}/log/sdp/statistics/statistics.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">
          <param name="ConversionPattern"
            value="%m%n" />
        </layout>
      </appender>

      <!-- A size based rolling 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>

      <!-- ============================== -->
      <!-- Append messages to the console -->
      <!-- ============================== -->
      <appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
        <param name="Threshold" value="ERROR" />
        <param name="Encoding" value="UTF-8" />
        <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} %-5p [%c{1}] %m%n" />
        </layout>
      </appender>

      <appender name="SYSTEM_SOCKET"
        class="org.apache.log4j.net.SocketAppender">
        <param name="RemoteHost" value="127.0.0.1" />
        <param name="Port" value="4477" />
        <param name="Threshold" value="DEBUG" />
      </appender>

      <!-- Syslog events -->
      <appender name="TRAFFIC_SYSLOG"
        class="org.apache.log4j.net.SyslogAppender">
        <param name="Threshold" value="INFO" />
        <param name="Facility" value="LOCAL1" />
        <!-- param name="FacilityPrinting" value="false"/ -->
        <param name="SyslogHost" value="127.0.0.1" />
        <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="SYSTEM_SYSLOG"
        class="org.apache.log4j.net.SyslogAppender">
        <param name="Threshold" value="ERROR" />
        <param name="Facility" value="LOCAL0" />
        <!-- param name="FacilityPrinting" value="false"/ -->
        <param name="SyslogHost" value="127.0.0.1" />
        <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_SYSLOG"
        class="org.apache.log4j.net.SyslogAppender">
        <param name="Threshold" value="ALL" />
        <param name="Facility" value="LOCAL2" />
        <!-- param name="FacilityPrinting" value="false"/ -->
        <param name="SyslogHost" value="127.0.0.1" />
        <layout class="oracle.sdp.eventlogger.BasicLayout"></layout>
      </appender>

### Logging Output

The output of the components is written to the log files located within the log/sdp directory of the OCMS OC4J instance's J2EE home (or through the `$JBOSS_HOME/server/$jboss_server_name/log/sdp` directory of the JBoss Application Server). 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

For more information, see "Viewing Log Files".

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 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 components can be modified at runtime by modifying the attributes of the SIP Servlet Container Logging MBean using either Application Server Control (Figure 10-1) as described in "Accessing SIP Servlet Container MBeans", or through the JBoss application server's JMX console. The attributes of the SIP Servlet Container Logging MBean enable you to set the log levels for the components to OFF, ERROR, WARN, INFO, DEBUG, or ALL.

Note:

Changes made at runtime using Application Server Control or JBoss AS 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. OCMS 10.1.3.3 defines the following logger categories for its traffic, system, config, badmsg and statstics components:

- `oracle.sdp.ocms.traffic`.

- `oracle.sdp.ocms.system`

  Note:

  The following categories in the global `log4j.xml` file control the log level for the system log:

      <category name="oracle.sdp" additivity="false">
        <priority value="INFO"/>

        <appender-ref ref="CUSTOMER_FILE_LOG" />

      </category>

      <category name="com.hotsip" additivity="false">

        <priority value="INFO"/>

        <appender-ref ref="CUSTOMER_FILE_LOG" />

- `oracle.sdp.ocms.config`

- `oracle.sdp.ocms.badmsg`

- `oracle.sdp.ocms.statistics`

As illustrated in Example 10-2, you can change the default log level for the traffic component by setting the `<priority value>` for the traffic category (`oracle.sdp.ocms.traffic`).

Example 10-2 Changing the Default Log Level

    <category name="oracle.sdp.ocms.traffic" additivity="false">
        <!-- change to INFO for logging of traffic -->
        <priority value="INFO"/>
        <appender-ref ref="TRAFFIC_FILE_LOG" />
       </category>

Note:

By default, the traffic and badmsg logs are set to OFF. As a consequence, a system using these default settings will not write any messages to the traffic or badsmg logs.

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 the JBoss Application Server, the file is located within the `JBOSS_HOME/Server/<$jboss_server`_name>/conf 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"