4 Logging Implementation Guidelines

The Java Logging Framework

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

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, enabling administrators to aggregate and view the logging output generated by all components and applications running within Oracle Application Server from one centralized location. For information about viewing log files generated by an OC4J instance, see the Oracle Containers for J2EE Configuration and Administration Guide.

How Java Logging and Oracle Diagnostic Logging Work Together

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 records events only 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, which generates the logger output in XML-based ODL format.

Naming Java Loggers

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.

Each logger name should include the vendor name and component name, and optionally include the module or submodule. Use the following convention for logger names:

vendorName.componentName[.moduleName][.subModuleName]

For example:

acme.mycomponent.mymodule

Setting Log Levels

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).

Your applications should utilize these predefined Java log levels, which Oracle diagnostic tools provided as part of OC4J map to Oracle Diagnostic Logging (ODL) message types and levels.

Table 4-1 illustrates the mapping between the predefined Java log levels and ODL message types and levels. The ODL log levels are between 1 and 32, with a lower value indicating a higher severity or less volume of information.

SEVERE.intValue()+100

INTERNAL_ERROR:1

SEVERE

ERROR:1

WARNING

WARNING:1

INFO

NOTIFICATION:1

CONFIG

NOTIFICATION:16

FINE

TRACE:1

FINER

TRACE:16

FINEST

TRACE:32

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.

Adding Localization Support

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 class-loader hierarchy, recursively up the tree.

Enabling HTTPClient Logging with the ODL Framework

You can enable HTTPClient Logging in the j2ee-logging.xml configuration file, using the ODL framework. For information about this file, see"Configuring Java Loggers to Use the ODL Framework".

To enable HTTPClient logging with the ODL framework:

1. Edit thej2ee-logging.xml logging configuration file for standalone OC4J or an OC4J instance or group.

2. Map the HTTPClient logger to ODLHandler, like this:

   <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='HTTPClient' level='TRACE:1' useParentHandlers='false'>
         <handler name='oc4j-handler'/>
       </logger>
     </loggers>
   </logging_configuration>
   

3. Save the j2ee-logging.xml file.

4. Restart OC4J.

To disable HTTPClient logging with the ODL framework:

1. Edit thej2ee-logging.xml logging configuration file for standalone OC4J or an OC4J instance or group.

2. Delete the following HTTPClient logger mapping to ODLHandler from the file:

       <logger name='HTTPClient' level='TRACE:1' useParentHandlers='false'>
         <handler name='oc4j-handler'/>
       </logger>
   

3. Save the j2ee-logging.xml file.

4. Restart OC4J.

Enabling HTTPClient Logging for Standalone OC4J or a Client-Side Application with a System Property

You can enable HTTPClient logging for standalone OC4J or client-side applications by setting HTTPClient.log.level to any of these standard trace log levels:

For information about these log levels and how they map to ODL message types and log levels, see "Setting Log Levels".

For information how to set log levels in Application Server Control, see "Configuring Java Loggers to Use the ODL Framework".

You can disable HTTPClient logging by setting the HTTPClient.log.level to OFF.

Enabling HTTPClient Logging for an OC4J Instance or Group in Oracle Application Server with a System Property

HTTPClient logging for an OC4J instance or group in Oracle Application Server is the same as for standalone OC4J, except that you have the option of setting Java system properties in the Oracle Process Manager and Notification Server (OPMN) configuration file, opmn.xml. Also, HTTPClient logging is directed to system out, which is written to one of the Oracle Application Server logs.

To enable HTTPClient logging for an OC4J instance or group in Oracle Application Server with a system property:

1. Open the ORACLE_HOME/opmn/conf/opmn.xml file.

2. Search for the <process-type> element in which the value of the id attribute matches the name of the OC4J instance or group where you want to enable HTTPClient logging; for example:

   <process-type id="OC4J_Portal" module-id="OC4J">
     <environment>
       <variable id="DISPLAY" value="localhost:0"/>
       <variable id="LD_LIBRARY_PATH" value="/private1/iasinst/OraHome_4/lib32:
         /private1/iasinst/OraHome_4/lib:/private1/iasinst/OraHome_4/network/lib:
         /private1/iasinst/OraHome_4/jdk/jre/lib/sparc"/>
     </environment>
     <module-data>
       <category id="start-parameters">
         <data id="java-options" value="-server
           -Djava.security.policy=/private1/iasinst/OraHome_4/j2ee/OC4J_Portal/config/java2.policy
           -Djava.awt.headless=true -Xmx256m "/>
   

3. Set the system property to enable HTTPClient logging in the value attribute of the <data> element in which the value of the id attribute is java-options, under the <category> element start-parameters, like this:

   <category id="start-parameters">
         <data id="java-options" value="-server
           -Djava.security.policy=/private1/iasinst/OraHome_4/j2ee/OC4J_Portal/config/java2.policy
           -Djava.awt.headless=true -Xmx256m
           -DHTTPClient.log.level=FINE /> 
   

4. Start the OC4J instance or group.

5. Review the HTTPClient log where Oracle Application Server writes to standard out.

   This log might be in ORACLE_HOME/opmn/logs/instance_default_1.

To disable HTTPClient logging for an OC4J instance or group in Oracle Application Server with a system property:

1. Open the ORACLE_HOME/opmn/conf/opmn.xml file.

2. Search for the <process-type> element in which the value of the id attribute matches the name of the OC4J instance or group where you want to disable HTTPClient logging.:

3. Set the HTTPClient.log.level system property to OFF in the value attribute of the <data> element in which the value of the id attribute is java-options, under the <category> element start-parameters, like this:

   <category id="start-parameters">
         <data id="java-options" value="-server
           -Djava.security.policy=/private1/iasinst/OraHome_4/j2ee/OC4J_Portal/config/java2.policy
           -Djava.awt.headless=true -Xmx256m
           -DHTTPClient.log.level=OFF> 
   

4. Start the OC4J instance or group.