Oracle E-Business Suite System Administrator's Guide

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.

These messages must be written into the code by developers. For more information, refer to the Oracle E-Business Suite Developer's Guide.

How to Configure Logging

Using Middle-tier Properties to Configure Logging

All middle-tier property settings take precedence over profile option settings. Configuring logging using Java system properties (usually by setting the Apache JServ system properties in the jserv.properties file, or oc4j.properties for OC4J) is a quick way to turn on logging for all sites or users, regardless of current profile option settings. Middle-tier properties only affect the middle-tier code, and do not affect the PL/SQL layer logging.

Using Java

Java system properties can be defined for controlling logging for each JVM.

The following examples show how to turn on logging for all modules and levels using Java system properties.

For this example, we assume that the JVM has write permission for the file "/path/to/apps.log". This file can be changed to any other file for which the JVM has write permission.

If you plan to log to a file, it is highly recommended that you explicitly override the default file "aferror.log" by setting AFLOG_FILENAME. The default does not specify a full file path, and may not be writable by the middle-tier process in some cases.

Command Line JVM System Properties

To enable logging for an application (for example, MyClass) that is run from the command line, add the parameter values to the command line:

/local/java/jdk1.2.2/bin/java \ 
-DAFLOG_ENABLED=TRUE -DAFLOG_LEVEL=STATEMENT \
-DAFLOG_MODULE=% -DAFLOG_FILENAME=/path/to/apps.log MyClass

Apache JServ Java System Properties

To enable logging using Apache JServ JVM system properties, add the following to the jserv.properties file (typically located in $IAS_ORACLE_HOME/Apache/Jserv/etc/):

wrapper.bin.parameters=-DAFLOG_ENABLED=TRUE  
wrapper.bin.parameters=-DAFLOG_LEVEL=STATEMENT  
wrapper.bin.parameters=-DAFLOG_MODULE=%  
wrapper.bin.parameters=-DAFLOG_FILENAME=/path/to/apps.log

A convenient location for the log file in this case is the log directory used by Jserv ($IAS_ORACLE_HOME/Apache/Jserv/logs/).

OC4J Java System Properties

To enable logging for OC4J, add the following to the oc4j.properties file corresponding to your OC4J Container. This is the "oacore" container (typically located in $ORACLE_CONFIG_HOME/j2ee/oacore/config/):

AFLOG_ENABLED=TRUE 
AFLOG_LEVEL=STATEMENT 
AFLOG_MODULE=% 
AFLOG_FILENAME=/path/to/apps.log

A convenient location for the log file in this case is the log directory used by Ebiz Rapid-Install deployed OC4J ($LOG_HOME/ora/10.1.3/j2ee/oacore/*).

Using C

Environment variables can be defined for controlling logging for each C process.

The following examples show how to turn on logging for all modules and levels using C Environment variables.

For this example, we assume that the C process has write permission for the file "/path/to/apps.log". This file can be changed to any other file for which the C process has write permission.

!#/bin/csh
setenv AFLOG_ENABLED Y
setenv AFLOG_LEVEL STATEMENT
setenv AFLOG_MODULE %
setenv AFLOG_FILENAME /path/to/apps.log
./C-Executable

Using Oracle Application Object Library Profile Options to Configure Logging

You can configure logging by setting Oracle Application Object Library (FND) profile options. The following table lists profile option names and sample values:

Profile Options
Profile Option Name	User Specified Name	Sample Value
AFLOG_ENABLED	FND: Debug Log Enabled	"Y"
AFLOG_MODULE	FND: Debug Log Module	"%"
AFLOG_LEVEL	FND: Debug Log Level	"ERROR"
AFLOG_FILENAME	FND: Debug Log Filename	"/path/to/apps.log"

The available levels are Site, Application, Responsibility, and User. User settings override Responsibility settings, Responsibility settings override Application settings, and Application settings override Site settings.

To emphasize this point, the following is a summary of the impacts of the different profile option levels:

User: Affects only the given user.
Application: Affects all users for the specific application.
Responsibility: Affects all users in any application for that responsibility.
Site: Affects all users, applications, and responsibilities.

Note: When setting up logging at the Site level, we strongly recommend that you set the logging level to UNEXPECTED. ERROR or EXCEPTION are also possibilities. We strongly discourage setting the logging level for a site to anything other than UNEXPECTED, ERROR, or EXCEPTION.

Using Logging to Screen

In addition to the above methods where log messages are written to a file or the database, Logging to Screen provides:

The ability to enable logging on a per HTTP request or per HTTP session basis.
Dynamic configuration which does not require restarting any servers or changing any log profiles.
A convenient lightweight mechanism to diagnose performance issues. Each message is timestamped to the millisecond.

If Logging to Screen is enabled, then the Java log messages generated for a particular HTTP Request-Response are buffered in memory and appended to the end of the generated HTML page.

This feature does not affect any existing configurations of file or database logging. File or database logging continues to behave per the configured middle tier log properties and/or log profile values.

Note that this mechanism currently provides only Java layer messages. Regular file or database logging should be used if messages from other layers (e.g., PL/SQL) are needed.

Enabling Logging to Screen in Oracle Application Framework Pages

For security reasons, this feature is only accessible if the "FND: Diagnostics" Profile is set to "Yes".

Use the following procedure to enable Logging to Screen in pages based on the Oracle Application Framework:

Click the Diagnostics button.
Select Show Log to Screen from the drop-down list.
Choose an appropriate log level.
Optionally, enter a module filter criteria such as jtf*. [In URLs, use the asterisk symbol (*) as a wildcard character, not the percent sign (%).]

Enabling Logging to Screen in CRM Technology Foundation Pages

For security reasons, this feature is only accessible if the "FND: Diagnostics" Profile is set to "Yes".

To enable logging to screen in pages based on the CRM Technology Foundation, append the following to the page's URL:

jtfdebug

Specify the logging level that should be displayed on the current screen.

jtfdebugfilter

(Optional) If desired, this parameter can be used as a filter to display messages based on a Java package name.

For example: <current_url>&jtfdebug=STATEMENT&jtfdebugfilter=jtf*

[In URLs, use the asterisk symbol (*) as a wildcard character, not the percent sign (%).]

Startup Behavior

At startup, applications do not have access to profile values. If middle-tier properties are not set, then at startup, the system defaults to logging as follows:

Logs are stored in the file aferror.log (in the current directory).
Logs are stored at the level UNEXPECTED.
Logs are stored for all modules.

After a connection to the database has been established, the site-level log profiles are read. When the user, responsibility, and application have been established, the Oracle Application Object Library (FND) profiles are read for that user.

For Java and PL/SQL applications, the logging system is initialized by FND_GLOBAL.INITIALIZE (which is called from APPS_INITIALIZE), which is called normally as part of the startup of every Java application session, form, report, or concurrent program. At that point, it has user information and will log with the proper user profiles. Before the FND_GLOBAL.INITIALIZE, if the logging system is called it will self-initialize and log with the site- level profile values.

For Java applications, this is the sequence of startup steps:

If any of the log parameters are set as Java system properties, then use them.
Logging is not disabled using the Java system property AFLOG_ENABLED=FALSE, and if any of the remaining log parameters are not set as system properties, then retrieve the corresponding Oracle Application Object Library (FND) profile option values from the database. User-level profile values override responsibility-level profile values, which override application-level profile values, which override site-level profile values.
If any of the log parameters are not set either as system properties or as profile values (or they are not accessible due to an error), then use the default values.

Logging Guidelines

Set up your system for logging according to the following guidelines. We recommend that you use Oracle Applications Manager as the user interface for any log management tasks.

Recommended Default Site-Level Settings

For normal operations, we recommend that you configure your system as follows:

Enabled: On
Logging Level: UNEXPECTED
Log Repository: Database
Module Filter: %

Caution: If you set the default site-level logging level to STATEMENT or PROCEDURE, a decrease in system performance could result. Under that configuration, the large amount of generated log messages might significantly slow down the system. Furthermore, if the site-level logging level is set to a low severity for a long time, then the FND_LOG_MESSAGES table could potentially run out of space.

Recommended Settings for Debugging

If you need to lower the logging level in order to gather information about a system error, use the following recommended configurations. (As stated above, the default logging level should be UNEXPECTED. This maintains optimum system performance.)

Using Logging to Screen

For Java-based pages that are based on the Oracle CRM Technology Foundation or the Oracle Application Framework, if you have access to the browser that is displaying the generated HTML, you can use the Logging to Screen feature to view further details if an error is reported. See: Using Logging to Screen.

This lightweight mechanism works best in cases where:

You are interested in Java layer messages only.
Debugging of is required for a particular request-response. For example, a JSP request from a browser.
Debugging is required for all request-responses within a specific session.

Pinpointing an Error to a Specific User

You can use Oracle Application Object Library profiles to enable logging for the specific user, responsibility, and application that were active when the error occurred. Ask the user to log in again for the profile changes to take effect. Remember to return the profiles to their usual values after debugging has been completed.

If you suspect that certain code is causing the problem, then use hierarchical module filters to restrict which messages are logged. For example: fnd.common.%

Set the logging level according to the appropriate level of detail. Recall that EVENT messages report key progress events, while EXCEPTION, ERROR, and UNEXPECTED messages report failures.

For High Volumes

For high load, high volume scenarios, you can log middle-tier messages to a local file, which is faster than logging to a remote database. To do so, define the AFLOG_FILENAME property to write all middle tier logging to a local file. Be sure to limit the number of generated messages:

Use Oracle Application Object Library FND Profiles to restrict logging according to:
- Specific users
- Specific responsibilities
- Specific applications
If you suspect that certain code is causing the problem, then use hierarchical module filters to restrict which messages are logged. For example: fnd.common%
Set the logging level according to the appropriate level of detail. Recall that EVENT messages report key progress events, while EXCEPTION, ERROR, and UNEXPECTED messages report failures.

For maintenance purposes, you should periodically rotate log files and purge old messages from the database table.

Updating Configuration Properties

If you have configured logging using Middle-tier properties, you need to restart the affected processes for any changes to be picked up.

If you have configured logging using FND Log Profiles, you need to request the user to log in again (no restart is needed)

If you have configured logging using Logging to Screen, the update is immediate. No re-login or restart is needed.

How to Completely Disable Logging

Use the following procedure to completely disable logging:

If logging is configured using middle-tier properties, then set the AFLOG_ENABLED middle-tier properties to FALSE in all appropriate middle-tier configuration files (for example, jserv.properties) and/or startup scripts.
If logging is configured using Oracle Application Object Library profiles in the database, then use the logging setup screen in Oracle Applications Manager to turn off logging for all applications, responsibilities, and users. For details, see the Oracle E-Business Suite System Administrator's Guide - Maintenance or the Oracle Applications Manager online help.

See the "Updating Configuration Properties" section above for details on how and when the modified values come into effect.

Purging Log Messages

You should periodically delete old log messages to account for the space limitations of the database table. In addition, you should periodically rotate log files.

There are several ways to purge log messages. They are described below:

Using a Concurrent Program

The concurrent program "Purge Debug Log and System Alerts" (Short name: FNDLGPRG) is the recommended way to purge messages. This program purges all messages up to the specified date, except messages for active transactions (new or open alerts, active ICX sessions, concurrent requests, and so on). This program is by default scheduled to run daily and purge messages older than 7 days. Internally this concurrent program invokes the FND_LOG_ADMIN APIs, which are described later in this document.

Using Oracle Applications Manager

Navigate to System Alerts and Metrics from the Navigate to drop-down list on the Applications Dashboard. Then click Logs.

Using the Oracle CRM System Administrator Console

Navigate to Settings > System > Debug Logging.

Using PL/SQL

You can use the FND_LOG_ADMIN PL/SQL package to delete log messages.

For example:

SET SERVEROUTPUT ON
declare
    del_rows NUMBER;
BEGIN
del_rows := fnd_log_admin.delete_all;
DBMS_OUTPUT.PUT_LINE(del_rows || ' rows deleted');
END;

Viewing Log Messages

This section summarizes the different user interfaces that can be used to view and work with log messages, and how to access log messages from each UI.

CRM System Administrator Console

Navigate to Settings > System > Debug Logging.

Oracle Application Framework Pages

When working in Oracle Application Framework pages, you can use the following procedure to view log messages.

Pages based on the Oracle Application Framework have a global button labeled Diagnostics. Click this button to open a window where you can choose Show Log. (Note that this "Diagnostics" global button does not refer to the Diagnostics feature in Oracle Applications Manager that enables management and execution of diagnostic tests.)
Select Show Log to open the Logs page within Oracle Applications Manager. The Logs page is part of the System Alerts and Metrics feature.

Note: For the Diagnostics global button to be visible, the profile option FND_DIAGNOSTICS must be set to YES.

Oracle Applications Manager

The Logging features in Oracle Applications Manager can be accessed in the following ways:

From the global Diagnostics button in Oracle Application Framework, select Show Log
Using the System Administration responsibility, navigate to Oracle Applications Manager > Logs
From the Oracle Applications Manager Site Map, navigate to Monitoring > Logs (Under Current Activity)
In a Forms-based application, navigate to Help (menu) > Diagnostics > Logging

OAM gives you the capability to perform the following:

Search using various criteria (Concurrent Program Request ID, Session ID, User ID, and so on).
Drill down to view related logs
View log attachments
Add logs and attachments to the Support Cart
Select valid values using Interdependent Lists of Values
Export/Download Logs in CSV format
Delete logs
Configure logs based on logging profiles
View a log summary
Drill down from the OAM Concurrent Processing Request page to the request log

Access to the OAM Logging functionality is controlled using Oracle Application Object Library function security. The seeded responsibilities System Administration and System Administrator have the logging functions assigned. For other responsibilities, use the following:

Full access (Search/Configure/Delete): OAM_BF_SYSLOG_ALL_MENU (Log Search: All Functions) (Menu)

This menu contains:
- Search: OAM_BF_SYSLOG_READ_ONLY_MENU (Log Search: Read Only) (Menu)
- Delete: OAM_BF_SYSLOG_DELETE (Log Delete) (function)
- Configure: OAM_BF_SYSLOG_CONFIG (Log Setup) (function)

Oracle Forms

Navigate to Help > Diagnostics > Logging.