Skip Headers

Oracle® Containers for J2EE Developer's Guide 10g Release 3 (10.1.3) Part No. B14433-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 4 Logging Implementation Guidelines

This chapter discusses the Oracle guidelines for implementing logging functionality in applications that will be deployed into OC4J. It includes the following topics:

- Integrating Java Logging with Oracle Diagnostic Logging in OC4J

For information on logging configuration and usage in OC4J, see the Oracle Containers for J2EE Configuration and Administration Guide.

## Integrating Java Logging with Oracle Diagnostic Logging in OC4J

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:

- Overview of the Java and Oracle Logging Frameworks

- Java Logging Guidelines

- Configuring Java Loggers to Use the ODL Framework

### Overview of the Java and Oracle Logging Frameworks

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

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

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

### Java Logging Guidelines

The following topics provide guidelines for implementing Java Loggers that will integrate with the Oracle Diagnostic Logging framework.

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

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

#### Setting Log Levels

In the Java logging framework, log levels are represented by objects of the j`ava.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.

#### 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 classloader hierarchy, recursively up the tree.

### Configuring Java Loggers to Use the ODL Framework

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>