Oracle® Containers for J2EE Configuration and Administration Guide 10g (10.1.3.1.0) Part Number B28950-01 |
|
|
View PDF |
This chapter provides instructions on using the system and application logging features available in OC4J. It covers the following topics:
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:
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 the 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 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 ( |
/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 |
|
|
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 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.
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 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:
Click the Logs link at the bottom of any Application Server Control Console page.
Expand OC4J.
Expand <instanceName>. The default instance name is home
.
Text log files for deployed J2EE applications cannot be viewed through the 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 11-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 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
.
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 log
n
.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:
The oldest log file is erased to provide space in the directory.
The log.xml
file is written to the latest log
n
.xml
file, in which n
increments by one over the most recent log file.
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.
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>
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.
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:
Click the Administration link.
Click Logger Configuration.
Set Log Level to a value listed in the left-hand column of Table 11-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 log
n
.xml
, in which n
is an integer 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 OC4J 10g (10.1.3.1.0), you can set the log levels for loggers through the Application Server Control Console, as follows:
On the OC4J Home page, click Administration
.
From the administration tasks, select Logger Configuration
to display the Logger Configuration page.
Click Expand All
to view the entire list of loggers currently loaded for the OC4J instance.
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>