|
Oracle® Containers for J2EE Developer's Guide
10g Release 3 (10.1.3) Part No. B14433-01 |
|
 Previous |
 Next |
|
Oracle® Containers for J2EE Developer's Guide
10g Release 3 (10.1.3) Part No. B14433-01 |
|
|
Previous |
Next |
This chapter discusses the Oracle guidelines for implementing logging functionality in applications that will be deployed into OC4J. It includes the following topics:
For information on logging configuration and usage in OC4J, see the Oracle Containers for J2EE Configuration and Administration Guide.
This section provides guidelines for enabling applications that use the standard Java logging framework to take advantage of log analysis tools provided by Oracle. It includes the following topics:
The following section provides an overview of the Java and Oracle logging frameworks, and describes how they are integrated to enable Java log output to be generated in Oracle format.
The Java logging framework, introduced in JDK 1.4, provides extensive logging APIs through the java.util.logging package. For an overview of the java.util.logging package, visit http://java.sun.com/j2se/1.4.2/docs/api/overview-summary.html.
For an overview of the Java logging framework, visit Sun's site on the subject at http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html.
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 in XML, enabling them to be more easily parsed and reused by other Oracle Application Server and custom developed components.
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.
ODL-formatted log files can be viewed through the Web-based Oracle Enterprise Manager 10g 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. See the Oracle Containers for J2EE Configuration and Administration Guide for instructions on viewing log files generated by an OC4J instance.
In the Java logging framework, applications record events by making calls on Logger objects, which are instances of the java.util.logging.Logger class. A Logger is a named entity that is associated with a system or application component. Each Logger is assigned a specific log level, and only records events at that level of severity or higher.
Logging messages are forwarded to a Handler object, which can in turn forward the messages to a variety of destinations for publication. The oracle.core.ojdl.logging package includes a Handler class, ODLHandler class, which generates the Logger output in XML-based ODL format.
The following topics provide guidelines for implementing Java Loggers that will integrate with the Oracle Diagnostic Logging framework.
Java Loggers are named entities, named using a hierarchical dot-separated namespace. The Logger namespace is global, and is shared by all applications running within OC4J. As such, ensure that each Logger name is unique to avoid potential naming conflicts.
Logger names should include the vendor name and component name, and optionally include the module or sub-module. Use the following convention for Logger names:
vendorName.componentName[.moduleName][.subModuleName]
For example:
acme.mycomponent.mymodule
In the Java logging framework, log levels are represented by objects of the java.util.logging.Level class. This class defines seven standard log levels, ranging from SEVERE (the highest priority, with the highest value) to FINEST (the lowest priority, with the lowest value).
Ideally, your applications should utilize these pre-defined Java log levels, which Oracle diagnostic tools provided as part of OC4J map to Oracle Diagnostic Logging (ODL) message types and levels.
The table below illustrates the mapping between the pre-defined Java log levels and ODL message types and levels. Note that the ODL log levels are between 1 and 32, with a lower value indicating a higher severity or less volume of information.
Table 4-1 Mapping between Java log levels and ODL message types/log levels
| Java Log Level | ODL Message Type:Log Level | ODL Description |
|---|---|---|
SEVERE.intValue()+100 |
INTERNAL_ERROR:1 |
The program has experienced an error for some internal or unexpected non-recoverable exception. |
SEVERE |
ERROR:1 |
A problem requiring attention from the system administrator has occurred. |
WARNING |
WARNING:1 |
An action occurred or a condition was discovered that should be reviewed and may require action before an error occurs. |
INFO |
NOTIFICATION:1 |
A report of a normal action or event. This could be a user operation, such as "login completed" or an automatic operation such as a log file rotation. |
CONFIG |
NOTIFICATION:16 |
A configuration-related message or problem. |
FINE |
TRACE:1 |
A trace or debug message used for debugging or performance monitoring. Typically contains detailed event data. |
FINER |
TRACE:16 |
A fairly detailed trace or debug message. |
FINEST |
TRACE:32 |
A highly detailed trace or debug message. |
The Oracle diagnostic tools provide some flexibility to accommodate custom log levels implemented with applications. However, containing log levels to the seven default Java levels (SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST) is recommended.
Each Logger object can optionally have an associated ResourceBundle object which is used to localize log message strings.
If a Logger does not have an associated ResourceBundle, it will inherit the ResourceBundle name from its parent according to the classic classloader hierarchy, recursively up the tree.
Enabling Java Loggers to output log messages in the ODL format is accomplished by mapping each Logger to the ODLHandler. This mapping is managed through a logging configuration file, j2ee-logging.xml, which is generated by OC4J in the ORACLE_HOME/j2ee/home/config directory.
In the current release, the j2ee-logging.xml configuration file must be edited by hand. Re-start OC4J after making any changes to this file.
This configuration file contains two elements within the <logging-configuration> root element:
<log_handlers>
This element defines one or more Handlers within OC4J. It includes one or more <log_handler> elements, each defining the name of a Handler and the class that generates instances of it.
Note that name of the Handler is used only within a <logger> element (described below) to assign the Handler to a Logger.
The Handler class can be either a subclass of java.util.logging.Handler, or a class that implements a HandlerFactory interface. If the class is a java.util.logging.Handler subclass, the default constructor for that class will be used to create a Handler instance.
If the class implements the HandlerFactory interface, additional configuration properties for the Handler can be specified. The only available HandlerFactory class is oracle.core.ojdl.logging.ODLHandlerFactory, which can be used to configure an ODLHandler instance.
The ODLHandlerFactory class accepts the following properties, each specified in a <property> sub-element:
path: Specifies the directory in which the Handler will generate log files. In the case of ODLHander, the directory specified is the destination for all ODL-formatted logs.
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 defines the mapping between each named Logger and the specific Handler that will process its messages, including ODLHandler. Each mapping is defined within a <logger> element, which includes the following:
name: The Logger name.
level: The minimum log level that this Logger acts upon. This level can be 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. This value is true by default.
<handler>: The name of a Handler to use, as defined in a <log_handler> element. Note that only Handlers defined within a <log_handler> element can be specified.
The following example shows the definition of the ODLHandler and the mapping of the default oracle and custom acme.scheduler Loggers to the ODLHandler within j2ee-logging.xml.
<logging_configuration>
<log_handlers>
<log_handler name='oc4j-handler'
class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='path' value='%ORACLE_HOME%/j2ee/log/oc4j'/>
<property name='maxFileSize' value='10485760'/>
<property name='maxLogSize' value='104857600'/>
</log_handler>
</log_handlers>
<loggers>
<logger name='oracle' level='NOTIFICATION:1' useParentHandlers='false'>
<handler name='oc4j-handler'/>
</logger>
<logger name='acme.scheduler' level='TRACE:1' useParentHandlers='false'>
<handler name='oc4j-handler'/>
</logger>
</loggers>
</logging_configuration>
