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 Maintenance Guide.
The target audience of this and the following chapter on logging is as follows:
Application Developers and Consultants - You can use this guide to learn how to add alerts and log messages to your code. Also, you can review log messages for debugging purposes.
System Administrators - System Administrators should monitor alerts and log messages to manage system activities and troubleshoot problems. For more information, see the Oracle E-Business Suite Maintenance Guide.
All Oracle E-Business Suite log messages are stored in a central repository.
Messages can be correlated across application-tier and database servers.
Autonomous transactions are used to log to the database.
Context information is captured internally to facilitate the analysis of messages.
Configurable System Alerts allow for e-mail and pager notification.
Messages can have attachments up to 4 GB in size.
Implementations in Java, PL/SQL, and C.
Multiple ways to control which messages are logged:
Set Oracle Application Object Library (FND) profiles in the database to turn on logging, based on the application user, responsibility, application, or site.
Set the logging level to control which messages are logged, based on their severity. There are six severities, ranging from STATEMENT (least severe) to UNEXPECTED (most severe).
Filter log messages by source module. Use of a wildcard character (%) is supported.
Turn on logging for individual processes.
Turn on logging for individual threads within a JVM.
The following sections describe some terms used in the Logging Framework.
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:
Time Stamp: The time the message was recorded.
Log Sequence: A unique sequence number internally generated for the message.
User ID: A unique identifier for the application user (foreign key to FND_USER).
Responsibility ID: The user's current responsibility (foreign key to FND_RESPONSIBILITY).
Application ID: The user's current application (foreign key to FND_APPLICATION).
Session ID: A unique identifier for the application user session (foreign key to ICX_SESSIONS).
Transaction ID: A unique identifier to identify the runtime context of the application. Four different transaction types are currently supported:
Concurrent Program (CP): the CP ID (foreign key to FND_CONCURRENT_PROGRAMS), Request-Id (foreign key to FND_CONCURRENT_REQUESTS) are automatically captured.
Form Function: the Form ID (foreign key to FND_FORMS), Function-Id (foreign key to FND_FORM_FUNCTIONS) are automatically captured.
ICX: the ICX Session ID (foreign key to ICX_SESSIONS) and ICX Transaction-Id (foreign key to ICX_TRANSACTIONS) are automatically captured.
Service: the Process ID (foreign key to fnd_concurrent_processes), Concurrent-Queue ID (foreign key to fnd_concurrent_queues) are automatically captured.
Node: The host name of the machine where the message was generated.
Node IP Address: The IP address of the machine where the message was generated.
JVM ID: A unique identifier for the Java process where the message was generated.
AUDSID: A unique identifier for the database connection (userenv('SESSIONID')).
Process ID: A unique identifier for the database process (v$session.Process).
Thread ID: A unique identifier for the thread within the Java process where the message was generated.
Severity: One of six predefined values that indicate the importance of the message. See the full definition below.
Module: Represents the source of the message. Typically in Java this is the full class name. When a class name starts with "oracle.apps", then the leading "oracle.apps." is dropped in the logged message. For example: "oracle.apps.jtf.util.Encoder" is logged as "jtf.util.Encoder".
Message Text: The descriptive body of the message. 4000 bytes is the maximum length currently supported. Please accommodate for multibyte characters appropriately. If additional space is required, then log attachments of up to 4 GB can be added.
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%".
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.
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.
The following parameters govern logging:
AFLOG_ENABLED
Specifies if logging is enabled or not. The default value is NULL (False).
AFLOG_LEVEL
Specifies the logging level. The default value is NULL (Log.UNEXPECTED).
AFLOG_MODULE
Specifies which modules are logged. The default value is NULL (%).
AFLOG_FILENAME
Specifies the file where application-tier log messages are written.
These parameters can be set as application-tier properties, Oracle Application Object Library (FND) profile option values, or a combination of both. Application-tier properties are set using Java system properties or C environment variables. The application-tier settings take precedence over database settings. This allows you to control logging globally from the database, or locally from the application tier.
If a parameter is not set as either an application-tier property or an Oracle Application Object Library (FND) profile option value, then the default value is used. The application-tier properties only affect the application-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 determines if logging is enabled. In the database tier, the possible values are "Y" and "N". In the application tier, the possible values are "TRUE" and "FALSE".
If AFLOG_ENABLED is set to "FALSE" using application-tier properties, then no logging occurs in the application 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 application-tier properties take precedence over values set as database profile option values, logging can be globally enabled or disabled for a specific application-tier process using properties. For example, to completely disable application-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 application-tier parameters take precedence over database profile option values:
| Database Tier Value | Application Tier Value | Result |
|---|---|---|
| Y | TRUE | Logging occurs in both the application tier and the database. |
| Y | FALSE | Logging occurs in the database only. |
| N | TRUE | Logging occurs in the application tier only. |
| N | FALSE | No logging occurs. |
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 application-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 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 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." |
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%".
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 application-tier log messages are written. If a filename is specified as an application-tier property, then application-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 an application-tier property, then the following occurs:
If the database profile option value for the filename is not set in the database or is inaccessible due to an error, then the log messages are written to the default file (aferror.log).
If the database profile option value for AFLOG_FILENAME is accessible, then the database value is read.
If the database profile option value is null, then messages are logged to the database.
If the database profile option is not null, then messages are logged to the specified file.
If the application-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 application-tier process is needed, then give each process an application-tier property value for AFLOG_FILENAME.
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.