Skip Headers

Oracle E-Business Suite Developer's Guide
Release 12.1
Part Number E12897-04
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Logging Framework Overview

Overview

The Oracle E-Business Suite Logging Framework provides the ability to store and retrieve log messages for debugging, error reporting, and alerting purposes.

You can set up, view, and purge log messages through HTML-based user interface pages that are located in Oracle Applications Manager. For more information about these pages, refer to the Oracle E-Business Suite System Administrator's Guide Documentation Set or the Oracle Applications Manager online help.

Target Audience

The target audience of this and other chapters related to logging are as follows:

Key Features

Terminology

The following sections describe some terms used in the Logging Framework.

Log Message

A complete log message has a set of message identifiers and the actual text of the log message. The only identifiers that developers must provide are the message, module, and severity. Everything else is automatically captured by the Logging Framework.

Log messages include the following:

Module Filter

A module filter is an optional comma-delimited list of strings that you can configure to perform logging for specific modules. You can use a wildcard (%) if desired. For example: "fnd%, jtf%, store%, cart%".

Severity

Each log message belongs to one of the following six severities (listed from least severe to most severe): 1-STATEMENT, 2-PROCEDURE, 3-EVENT, 4-EXCEPTION, 5-ERROR, or 6-UNEXPECTED.

Logging Level

A logging level is a threshold that you can set to control the logging of messages. You can set the logging level to any of the six severities defined above. When you set a logging level, only messages that have a severity greater than or equal to the defined level are logged. For example, if you set the logging level to 5-ERROR, then logging occurs for messages that are 5-ERROR and 6-UNEXPECTED. If you set the logging level to the lowest severity, 1-STATEMENT, then messages of all six severities are logged.

Logging Configuration Parameters

Overview

The following parameters govern logging:

These parameters can be set as middle-tier properties, Oracle Application Object Library (FND) profile option values, or a combination of both. Middle-tier properties are set using Java system properties or C environment variables. The middle-tier settings take precedence over database settings. This allows you to control logging globally from the database, or locally from the middle tier.

If a parameter is not set as either a middle-tier property or an Oracle Application Object Library (FND) profile option value, then the default value is used. The middle-tier properties only affect the middle-tier logging, and do not affect the database (PL/SQL) layer logging.

Each log message has an associated module and level, which are determined by the author of the message. Whether a log message is actually logged during an enabled instance (AFLOG_ENABLED=TRUE) depends on how the message's level and module compare to the settings of AFLOG_LEVEL and AFLOG_MODULE. The message's level must be greater than or equal to the value of AFLOG_LEVEL, and the module must match the filter AFLOG_MODULE.

Detailed descriptions of the logging parameters follow.

AFLOG_ENABLED

AFLOG_ENABLED determines if logging is enabled. In the database tier, the possible values are "Y" and "N". In the middle tier, the possible values are "TRUE" and "FALSE".

If AFLOG_ENABLED is set to "FALSE" using middle-tier properties, then no logging occurs in the middle tier. If AFLOG_ENABLED is set to "N" using Oracle Application Object Library (FND) profiles, then no logging occurs in the database tier.

If AFLOG_ENABLED is set to "TRUE", then log messages of the appropriate level and module will be logged either to the database or to a file. Since parameter values set as middle-tier properties take precedence over values set as database profile option values, logging can be globally enabled or disabled for a specific middle-tier process using properties. For example, to completely disable middle-tier logging in a JVM, use "-DAFLOG_ENABLED=FALSE".

For example:

/local/java/jdk1.2.2/bin/java -DAFLOG_ENABLED=FALSE org.apache.jserv.JServ

When AFLOG_ENABLED is set in this way, it overrides any value set using database profile option values.

Likewise, logging can be globally enabled. If "-DAFLOG_ENABLED=TRUE" is used, logging will be enabled, even for users whose database profile option value for AFLOG_ENABLED is "N".

The following table shows how middle-tier parameters take precedence over database profile option values:

Middle Tier Values versus Database Tier Values
Database Tier Value Middle Tier Value Result
Y TRUE Logging occurs in both the middle tier and the database.
Y FALSE Logging occurs in the database only.
N TRUE Logging occurs in the middle tier only.
N FALSE No logging occurs.

AFLOG_LEVEL

AFLOG_LEVEL specifies the logging level. In order to be logged, messages must have a severity greater than or equal to the value of AFLOG_LEVEL.

Any values set using middle-tier properties take precedence over profile option values set in the database. For example, the logging level could be set to "EXCEPTION" in the system properties as:

/local/java/jdk1.2.2/bin/java  -DAFLOG_LEVEL=EXCEPTION org.apache.jserv.JServ

The following table lists the supported logging levels for failure reporting:

Logging Levels for Failure Reporting
Logging Level Value Meaning Audience Examples
Unexpected 6 Indicates an unhandled internal software failure. (Typically requires code or environment fix.) System administrators at customer sites, and Oracle development and support teams. "Out of memory." "Required file not found." "Data integrity error." "Configuration error; required property not set, cannot access configuration file." "Failed to place new order due to DB SQLException." "Failed to obtain connection for processing request."
Error 5 Indicates an external end user error. (Typically requires end user fix.) System administrators at customer sites, and Oracle development and support teams. "Invalid username or password." "User entered a duplicate value for field."
Exception 4 Indicates a handled internal software failure. (Typically requires no fix.) Oracle development and support teams. "Profile not found." "Session timed out." "Network routine could not connect; retrying"

The following table lists the supported logging levels for progress reporting:

Logging Levels for Progress Reporting
Logging Level Value Meaning Audience Examples
Event 3 Used for high-level progress reporting. Oracle development and support teams. "User authenticated successfully." "Retrieved user preferences successfully." "Menu rendering completed."
Procedure 2 Used for API-level progress reporting. Oracle development and support teams. "Calling PL/SQL procedure XYZ." "Returning from PL/SQL procedure XYZ."
Statement 1 Used for low-level progress reporting. Oracle development and support teams. "Obtained Connection from Pool." "Got request parameter." "Set Cookie with name, value."

AFLOG_MODULE

Module names have the following form:

<application short name>.<directory>.<file>.<routine>.<label>

For example: "fnd.common.AppsContext.logOut.begin", where <application short name> = "fnd", <directory> = "common", <file> = "AppsContext", <routine> = "logOut", and <label> = "begin".

The Java framework write methods that take a "Class" or "this" Object as a parameter automatically construct the module from the name of the Class. For example, if a log message is being written from an instance of "oracle.apps.fnd.common.AppsContext.class", then the module name will be "fnd.common.AppsContext". Note that the leading "oracle.apps" is always dropped.

The AFLOG_MODULE parameter is a filter against which the module names of log messages are compared. The percent sign (%) is used as a wildcard character. To select all modules, set AFLOG_MODULE to "%". To only log messages from the Class oracle.apps.fnd.common.AppsContext, set AFLOG_MODULE to "fnd.common.AppsContext%".

AFLOG_FILENAME

The default value is NULL (Log to database. If database logging fails, then log to the default file ./aferror.log).

AFLOG_FILENAME specifies the file where middle-tier log messages are written. If a filename is specified as a middle-tier property, then middle-tier log messages are written to that file. Messages at the PL/SQL layer are always logged to the database table.

If a filename is not specified as a middle-tier property, then the following occurs:

If the middle-tier process does not have write permission on the specified file, then it logs to the default file. If it cannot write to the default log file, then it writes log messages to STDERR.

If the full path is not specified in the filename, then the path is considered as relative to the current working directory.

If a separate log file for each middle-tier process is needed, then give each process a middle-tier property value for AFLOG_FILENAME.

AFLOG_ECHO

In addition to the four standard log parameters described above, AFLOG_ECHO is available only in the Java tier. It is used to send log messages to STDERR.

If -DAFLOG_ECHO=TRUE and logging is enabled, then all filtered messages are also logged to STDERR in addition to the configured file or database.