|
Oracle® Containers for J2EE Configuration and Administration Guide
10g Release 3 (10.1.3) Part No. B14432-01 |
|
 Previous |
 Next |
|
Oracle® Containers for J2EE Configuration and Administration Guide
10g Release 3 (10.1.3) Part No. B14432-01 |
|
|
Previous |
Next |
This chapter provides instructions on using the system and application logging features available in OC4J. It covers the following:
Each OC4J process generates a number of log files to aid in troubleshooting. If there are multiple processes running for an OC4J instance, multiple sets of log files are generated.
There are two types of log files that can be generated by OC4J:
Plain text log files
Plain text logs are the default log files used for OC4J components, and are ideal for use in a development environment. The messages logged in these text files can be read with any editor, including the Oracle Enterprise Manager 10g Application Server Control Console.
Oracle Diagnostic Logging (ODL) Log Files
The messages logged in these files use an XML format that is viewable through Application Server Control Console. The key benefit of ODL is that it supports log file rotation.
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 10-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_name for OPMN-managed instances.
Table 10-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
|
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:
Text logging is enabled or disabled through elements in the XML configuration files listed in Table 10-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> -->
Note that although both ODL and text logging can be enabled simultaneously, one of these options should be disabled to save disk space.
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.
All text log files are generated by default in the locations listed in Table 10-1, "List of Log Files Generated for OC4J". Text log files are identified by the log extension.
Note that text log files generated for OC4J components can be viewed through Application Server Control Console, as follows:
Click the Logs link at the bottom of any Application Server Control Console page.
Expand OC4J.
Expand <instanceName>. The default instance name is home.
Note that text log files for deployed J2EE applications cannot be viewed through Application Server Control Console.
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.
ODL is enabled by adding the <odl> element within the <log> element in any of the XML files listed in Table 10-1.
|
Notes:
|
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 |
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 1000 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_name/application-deployments/log/instance_name_default_group_1/petstore.
A key benefit of the ODL framework is that it 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.
When you enable ODL, each new message goes into the current log file, named log.xml. When the log file is full—that is, the log file size maximum is reached—then it is copied to an archival log file, named logN.xml, where N is a number starting at one. When the last log file is full, the following occurs:
The oldest log file is erased to provide space in the directory.
The log.xml file is written to the latest logN.xml file, where N increments by one over the most recent log file.
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.
Click the Logs link at the bottom of any Application Server Control Console page.
Expand OC4J.
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.
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:
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.
Note that 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 10-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 10-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:
Click the Administration link.
Click Logger Configuration.
Set Log Level to a value listed in the left-hand column of Table 10-2 above.
Click Apply to apply your changes to the OC4J runtime.
The OC4J log file can be viewed through Application Server Control Console. To view the file:
Click the Logs link at the bottom of any Application Server Control Console page.
Expand OC4J.
Expand <instanceName>. In both standalone OC4J and OAS, the default instance name is home.
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, where N is a number starting at 1.
The configuration for the oracle logger is defined in j2ee-logging.xml, which is installed in the ORACLE_HOME/j2ee/instance/config directory.
In the current release, the j2ee-logging.xml configuration file must be edited 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 a <log_handler> element defining oc4j-handler. The following properties are specified in a <property> subelement:
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>
