Skip Headers
Oracle® Containers for J2EE Configuration and Administration Guide
10g (10.1.3.1.0)

Part Number B28950-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

11 Logging in OC4J

This chapter provides instructions on using the system and application logging features available in OC4J. It covers the following topics:

Overview of Log Files Generated by OC4J

Each OC4J process generates a number of log files to aid in troubleshooting. If multiple processes are running for an OC4J instance, multiple sets of log files are generated.

OC4J can generate two types of log files:

Log files are generated in different locations, depending on the component or application that data is being recorded for. The logging configuration for each component or application is defined in component-specific XML configuration files.

Table 11-1 lists the names and locations of the various log files generated, as well as the XML configuration file containing the logging configuration for each component. Unless otherwise indicated, all paths indicated are within ORACLE_HOME/j2ee/home for standalone OC4J or ORACLE_HOME/j2ee/instance for OPMN-managed OC4J instances.

Table 11-1 List of Log Files Generated for OC4J

Component Configuration File Default Log File Name and Location

OC4J components using Java logging

See "Configuring OC4J Logging" for details on configuring this ODL-formatted log file.

Standalone OC4J:

/log/oc4j/log.xml

OPMN-managed OC4J:

/log/instance_default_group_1/oc4j/log.xml

Application Server Control Console


/application-deployments/ascontrol/orion-application.xml

Standalone OC4J:

/log/ascontrol-application.log

OPMN-managed OC4J:

/log/instance_default_group_1/ascontrol-application.log

Applications deployed into OC4J

/application-deployments/app_name/orion-application.xml

Standalone OC4J:

/application-deployments/app_name/application.log

OPMN-managed OC4J:

/application-deployments/app_name/instance_default_group_1/application.log

Global (default) application

/config/application.xml

Standalone OC4J:

/log/global-application.log

OPMN-managed OC4J:

/log/instance_default_group_1/global-application.log

Default Web site access logging

/config/default-web-site.xml

Standalone OC4J:

/log/default-web-access.log

OPMN-managed OC4J:

/log/instance_default_group_1/default-web-access.log

OC4J server

/config/server.xml

Standalone OC4J:

/log/server.log

OPMN-managed OC4J:

/log/instance_default_group_1/server.log

JMS

/config/jms.xml

Standalone OC4J:

/log/jms.log

OPMN-managed OC4J:

/log/instance_default_group_1/jms.log

RMI

/config/rmi.xml

Standalone OC4J:

/log/rmi.log

OPMN-managed OC4J:

/log/instance_default_group_1/rmi.log

OPMN

ORACLE_HOME/opmn/conf/opmn.xml

ORACLE_HOME/opmn/logs


Using Plain Text File Logging

Plain text logging is the default format used in OC4J.

This mechanism separates messages in alignment with the XML files. However, instead of writing to multiple log files of the same size, all messages for that component are written into a single log file. The following topics describe how to use text logging:

Enabling or Disabling Text File Logging

Text logging is enabled or disabled through elements in the XML configuration files listed in Table 11-1, except for the default-web-site.xml file. (See "Configuring Web Site Access Logging" for details on configuring Web site access logging.)

Logging is enabled via the <file> subelement of the <log> element of the XML configuration file for each component. The element contains a single path attribute which specifies the name and optionally the location of the log file generated:

<log>
  <file path="application.log" />
</log> 

To turn off text logging for a component, remove or comment out the <file> element from the appropriate configuration file. If you do not remove this line and you enable ODL, both logging options will be enabled.

For example, to disable text logging for an application, comment out the following element in the application's orion-application.xml file:

<!-- 
<log>
  <file path="application.log" />
</log> 
-->

Although both ODL and text logging can be enabled simultaneously, one of these options should be disabled to save disk space.

Managing Text Log Files

It is important to monitor your log files, as text logging does not have any imposed size limits or log rotation capability. If left unchecked, log files will continue to grow and can overrun the disk.

The only way to manage these files is to stop OC4J, remove the files, and then restart OC4J to start the log files over.

Viewing Text Log Files

All text log files are generated by default in the locations listed in Table 11-1, "List of Log Files Generated for OC4J". Text log files are identified by the log extension.

Text log files generated for OC4J components can be viewed through the Application Server Control Console, as follows:

  1. Click the Logs link at the bottom of any Application Server Control Console page.

  2. Expand OC4J.

  3. Expand <instanceName>. The default instance name is home.

Text log files for deployed J2EE applications cannot be viewed through the Application Server Control Console.

Using Oracle Diagnostic Logging (ODL)

The Oracle Diagnostic Logging framework, or ODL, provides plug-in components that complement the standard Java framework to automatically integrate log data with Oracle log analysis tools.

In the ODL framework, log files are formatted as XML documents, enabling logs to be parsed and reused by other Oracle Application Server and custom-developed components, including Application Server Control Console. Another key benefit of ODL is that, unlike in text-based logging, log file rotation is supported.

Enabling or Disabling ODL

ODL is enabled by adding the <odl> element within the <log> element in any of the XML files listed in Table 11-1.


Notes:

  • You can enable ODL for an application at the time the application is deployed by setting values for odls in the log property through the deployment plan editor.

    See the Oracle Containers for J2EE Deployment Guide for details on configuring an application using the deployment plan editor.

  • ODL for Web sites uses a different configuration. See "Configuring Web Site Access Logging" for details on configuring Web site access logging.

  • Both ODL and text file logging can be enabled simultaneously. However, you should disable one of these options to save disk space.


The <odl> element has the following attributes. All are required.

  • path: The path to the directory where the log.xml files for this component will be generated.


    Important:

    Specify the path as ../log/appName, as shown in the example below. This path is required to enable log files to be viewed through Application Server Control Console.


  • max-file-size: The maximum size, in kilobytes, that an individual log file is allowed to grow to. When this limit is reached, a new log file is generated.

  • max-directory-size: Sets the maximum size, in kilobytes, allowed for the log file directory. When this limit is exceeded, log files are purged, beginning with the oldest files.

For example, the following entry in the petstore application's orion-application.xml file will cause log.xml files to be generated for this application. It will also set log files to a maximum of 1,000 KB and the directory maximum to 10,000 KB.

<log>
  <odl path="../log/petstore/" max-file-size="1000" max-directory-size="10000" />
</log>

Using this configuration, petstore log files will be generated in the following locations, depending on your OC4J installation.

  • Standalone OC4J:

    Log files will be generated in ORACLE_HOME/j2ee/home/application-deployments/log/petstore.

  • OPMN-managed OC4J:

    Files will be generated in an OC4J instance- specific directory named ORACLE_HOME/j2ee/instance/application-deployments/log/instance_default_group_1/petstore.

Managing ODL Log Files

The ODL framework provides support for managing log files, including log file rotation. The maximum log file size and the maximum size of log directories can also be defined. In addition, using ODL provides these benefits:

  • You can limit the total amount of diagnostic information saved.

  • Older segment files are removed and newer segment files are saved in chronological fashion.

  • Components can remain active and do not need to be shut down when diagnostic logging files are cleaned.

An ODL log is a set of log files that includes the current log file, log.xml, and zero or more ODL Archives (segment files), which contain older messages. After you enable ODL, each new message is added to the end of log.xml. When this log file reaches the rotation point, it is renamed and a new log.xml file is created.

Segment files are created when the current log file reaches the rotation point, specified by the maximum ODL segment size, and for some OC4J logs, the rotation time and rotation frequency. Thelog.xml file is renamed to logn.xml, in which n is an integer., starting at 1. The new log.xml file is created when the component generates new diagnostic messages.

When the last log file is full, the following procedure occurs:

  1. The oldest log file is erased to provide space in the directory.

  2. The log.xml file is written to the latest logn.xml file, in which n increments by one over the most recent log file.

Size-Based Log Rotation

To limit the size of the ODL log, components, you use a configuration option specifying the maximum size of the logging directory. Whenever the sum of the sizes of all of the files in the directory reaches the maximum, the oldest archive is deleted to keep the total size under the specified limit.


Note:

The most recent segment file is never deleted.

For example, when the maximum directory size is reached, with the starting segment file named log9872, the following files could be present in the log file directory:

File                        Size

log.xml                     10002
log9872.xml                 15000
log9873.xml                 15000
log9874.xml                 15000
log9875.xml                 15000
log9876.xml                 15000

In this case, when log.xml fills up, log9872.xml is removed and log.xml is moved to the new file log9877.xml. New diagnostic messages then are written to a new log.xml file.

For example, to specify the maximum ODL segment size and maximum directory size for an OC4J application named petstore, you would add the following entry to the file ORACLE_HOME/j2ee/instance_name/application-deployments/petstore/orion-application.xml:

<log>
<odl path="../log/petstore/" max-file-size="1000" max-directory-size="10000" />
</log>

For OC4J components that are configured in the j2ee-logging.xml file, you can specify a rotation time and rotation frequency, in addition to a maximum segment size and directory size.

Time-Based Log Rotation

For time-based log rotation, you can specify the following properties in a <log_handler> subelement of the <log-handlers> element of the <logging-configuration> root element:

  • baseRotationTime: (Optional.) The base time for the rotation. The format for the base time can be any of the following:

    • hh:mm, for example, 04:20. This format uses the local time zone.

    • yyyy-MM-dd, for example, 2006-08-01. This format uses the local time zone.

    • yyyy-MM-ddThh:mm, for example 2006-08-01T04:20. This format uses the local time zone.

    • yyyy-MM-ddThh:mm:ss.sTZD, where TZD is the timezone indicator. TZD can be Z, indicating UTC, or {+|-}hh:mm. For example, 2006-03-01T04:20:00-08:00 represents March 1, 2006 4:20:00 in US Pacific Standard Time time zone.

    If you do not specify baseRotationTime, the default value is Jan. 1, 1970, 00:00 UTC.

  • rotationFrequency: The frequency of the rotation, in minutes. In addition, you can specify one of the following values: hourly, daily, weekly.

You specify these properties in the following file:

ORACLE_HOME/j2ee/instance_name/config/j2ee-logging.xml

For example, to specify that the log files are rotated every day at 4:00AM local time, or when they reach 2000000 bytes in size, use the following:

<log_handler name="h1" class="oracle.core.ojdl.logging.ODLHandlerFactory">
     <property name="path" value="log"/>
     <property name="baseRotationTime" value="04:00"/>
     <property name="rotationFrequency" value="daily"/>
     <property name="maxFileSize" value=" 2000000"/> 
</log_handler>

Viewing ODL Log Files

ODL-formatted log files can be viewed by clicking the Logs link in the Web-based Application Server Control Console, allowing administrators to aggregate and view the logging output generated by all components and applications running within OC4J from one centralized location.

ODL log files are identified in the Log Files page by the .xml extension.

  1. Click the Logs link at the bottom of any Application Server Control Console page.

  2. Expand OC4J.

  3. Expand <instanceName>. In both standalone OC4J and OAS, the default instance name is home.

  • To view the OC4J log files, expand Diagnostic Message Logs, then open log.xml.

  • To view ODL logs for a specific J2EE application:

    • Expand the Application <applicationName> node.

    • Expand Diagnostic Message Logs. Open and view the log.xml file generated within this director.

Configuring OC4J Logging

The various components of OC4J utilize Java loggers that write to the OC4J log file. The OC4J log file is generated in XML format using the Oracle Diagnostic Logging framework and can be viewed through Application Server Control Console.

The section covers the following topics:

Using and Configuring the OC4J Component Loggers

OC4J provides a number of component loggers that write to the OC4J log file (log.xml). The available component loggers can be viewed and configured through the Logger Configuration page in Application Server Control Console.

The Java log level can be set for each individual component logger. If set to NULL, a logger inherits the log level set for its parent.

Therefore, the default level for all loggers is INFO—which maps to the NOTIFICATION Java log level—as that is the default value inherited from the oracle logger. See "Configuring the oracle Logger" for details on changing this default value.

The log level set on a logger through the Logger Configuration page is not persisted, but is applied to the OC4J runtime only. When OC4J is restarted, the log level reverts back to the default setting inherited from the parent logger.

Table 11-2 below illustrates the log levels that can be set through Application Server Control Console and the ODL message type:log level that each maps to.

Table 11-2 OC4J Logger Log Levels

Java Log Level ODL Message Type:Log Level ODL Description
NULL


The logger will inherit the log level set for its parent.

SEVERE
ERROR:1

Log system errors requiring attention from the system administrator.

WARNING
WARNING:1

Log actions or conditions discovered that should be reviewed and may require action before an error occurs.

INFO
NOTIFICATION:1

Log normal actions or events. This could be a user operation, such as login completed, or an automatic operation, such as a log file rotation.

CONFIG
NOTIFICATION:16

Log configuration-related messages or problems.

FINE
TRACE:1

Log trace or debug messages used for debugging or performance monitoring. Typically contains detailed event data.

FINER
TRACE:16

Log fairly detailed trace or debug messages.

FINEST
TRACE:32

Log highly detailed trace or debug messages.


To configure OC4J component loggers through Application Server Control Console:

  1. Click the Administration link.

  2. Click Logger Configuration.

  3. Set Log Level to a value listed in the left-hand column of Table 11-2 above.

  4. Click Apply to apply your changes to the OC4J runtime.

Viewing the OC4J Log File

The OC4J log file can be viewed through Application Server Control Console. To view the file:

  1. Click the Logs link at the bottom of any Application Server Control Console page.

  2. Expand OC4J.

  3. Expand <instanceName>. In both standalone OC4J and OAS, the default instance name is home.

  4. Expand Diagnostic Message Logs.

As with all ODL log files, each new message goes into the current log file, named log.xml. Once the maximum size is reached, the log is copied to an archival log file, named logn.xml, in which n is an integer starting at 1.

Configuring the oracle Logger

The configuration for the oracle logger is defined in j2ee-logging.xml, which is installed in the ORACLE_HOME/j2ee/instance/config directory.

In OC4J 10g (10.1.3.1.0), you can set the log levels for loggers through the Application Server Control Console, as follows:

  1. On the OC4J Home page, click Administration.

  2. From the administration tasks, select Logger Configuration to display the Logger Configuration page.

  3. Click Expand All to view the entire list of loggers currently loaded for the OC4J instance.

  4. Select a log level for any of the loggers shown on the page.

You can also edit the j2ee-logging.xml configuration file by hand. Restart OC4J after making any changes to this file.

The configuration file contains two elements within the <logging-configuration> root element:

  • <log_handlers>

    This element includes <log_handler> elements defining three different log handlers:

    • oc4j-handler

      This is the log handler for the oracle logger.

    • oracle-webservices-management-auditing-handler

      This is the log handler for the oracle.webservices.management.auditing logger.

    • oracle-webservices-management-logging-handler

      This is the log handler for the oracle.webservices.management.logging logger.

    The following properties are specified in <property> subelements for each log handler:

    • path: Specifies the directory in which the handler will generate log files. Do not modify this value.

    • maxFileSize: Sets the maximum size, in bytes, that any log file in the directory will be allowed to grow to. When a file exceeds this limit, a new file is generated.

    • maxLogSize: Sets the maximum size, in bytes, allowed for the log file directory. When this limit is exceeded, log files are purged, beginning with the oldest files.

  • <loggers>

    This element includes a <logger> element defining the following:

    • name: The Logger name. Do not modify this value.

    • level: The minimum log level that this Logger acts upon. This level is set by default to the ODL NOTIFICATION:1 value, which maps to the INFO Java log level displayed on the Logger Configuration page in Application Server Control Console.

      You can set this value to either a Java logging level (FINE) or an ODL Message Type:Log Level (TRACE:1).

    • useParentHandlers: Indicates whether or not the Logger should use its parent Handlers. Because this value is set to false by default, the oracle logger does not inherit the log level set for its parent, the root logger.

    • <handler>: The name of the Handler to use. Do not modify this value.

The following example sets the default log level to FINEST by specifying TRACE:32 as the ODL Message Type:Log Level.

<logging_configuration>
  <log_handlers>
    <log_handler name='oc4j-handler'
        class='oracle.core.ojdl.logging.ODLHandlerFactory'>
      <property name='path' value='%ORACLE_HOME%/j2ee/%OPMN_PROC_TYPE%/log/
           %OPMN_PROC_TYPE%_%OPMN_PROC_SET%_%OPMN_PROC_INDEX%/oc4j'/>
      <property name='maxFileSize' value='10485760'/>
      <property name='maxLogSize' value='104857600'/>
    </log_handler>
  </log_handlers>
  <loggers>
    <logger name='oracle' level='TRACE:32' useParentHandlers='false'>
      <handler name='oc4j-handler'/>
    </logger>
  </loggers>
</logging_configuration>