Debugging Series: Fusion Applications Logging

Fusion Applications Logging

All Fusion Applications products implement the Oracle standard framework for logging, known as Oracle Diagnostic Logging (ODL). This incorporates using a set of underlying logging API’s and runtime libraries as well as adhering to specific format.

The output of Fusion Applications logs include the core ODL data attributes plus some compliant extensions, all prefixed with APPS_ for easy identification. Figure 1 below provides a comprehensive summary. In addition, log output from programs run by SOA and ESS components have further extensions with related information, such as the Composite Application Name, and the ESS job ID.

Figure 1 – Content of a Fusion Applications log line (click here to expand).

Most log attributes values come from the runtime context, and it is really only the APPS_SOURCE, MESSAGE-TEXT and LEVEL values that are actually populated by runtime code.

Log Configuration

Configuration for Fusion Applications logging is done through a number of profile options, each prefixed with “AFLOG_” as illustrated below. This can be configured either from the Fusion Applications Help menu, from Functional Setup Manager, or from within Enterprise Manager, with precise steps given in the Administrators Guide and in MyOracleSupport Note 1380027.1.

Figure 2 – The Profile Options for configuring logging

The Java API

Since the majority of the code in Fusion Applications is Java or based on artifacts that run in a Java Container, the most commonly used process is through AppsLogger.class.
This API originates from the utility ApplCore.log package and supports a variety of ways to write logs. The overloaded write() method supports creating output from plain text passed to it, or calling the message service to reuse a predefined message from the database. It also allows the addition of an exception object (call stack) which goes into Supplemental Attributes on the end of the log line.

Using the API is straight forwards, requiring first a context check and then the write statement. The first variable is always the current code object, best passed using the “this” keyword.  After that, pass in your text (or a standard message), and complete with the log level. All the other data for the log line is pulled from the context by the logging API automatically.

if(AppsLogger.isEnabled(AppsLogger.FINE) ){
AppsLogger.write(this, logTextVar, AppsLogger.FINE);
}

Tip: On a new line in the JDeveloper code editor, enter alog and press Ctrl+Enter. This pops-up a selection but where the above code can be quickly added.

The PL/SQL API

A very similar implementation is available for PL/SQL code, with the FND_LOG utility package available containing procedure for writing either text strings or standard database messages. This accepts the same parameter types as before; log level, current code module name, and the output.

if ( FND_LOG.LEVEL_FINEST >= FND_LOG.G_CURRENT_RUNTIME_LEVEL) then
fnd_log.string(fnd_log.level_finest, MY_MODULE, myStringMsg);
end if;

Obviously the output of this goes to the PL/SQL log file stored on the database tier.

The C API

Just the same, for applications code written in C there is a corresponding logging API to use. This is the aflog module and again provides program signatures for logging either text strings or standard database messages.

oratext *module_name = “my.module.name”;
if (aflogtest(AFLOG_ODL_FINEST, module_name)) {
aflogstr(AFLOG_ODL_FINEST, module_name, “My String Message”);
}

It has its own location for log output, as set by the Profile ‘AFLOG_FILENAME’.

The SOA API

Since there are more than 400 SOA composite applications that support Fusion Applications business processes, logging and error handling in this area is vital. So in addition to the standard logs from these components, Fusion Applications supports two methods for creating output for troubleshooting issues.

1. The SOA Mediator component should be extended using additional variables that call the AppsLoggerService, the webservice implementation of Java AppsLogger API.
2. BPEL Processes should be instrumented with new Sensors and use the standard variables that handle the data to be logged and the log level to use. These are numerous, but are all named LOG_*_VAR, with examples include LOG_MESSAGE_VAR and LOG_FINEST_VAR.

Output from these logging methods go into the Java log, as the entire SOA Suite runs inside WebLogic Server.

Logging Recommendations

The following are a few tips and tricks on effective use of logging gleaned from developing and supporting Fusion Applications so far.

1. Design-in logging, rather than applied as an afterthought when debugging issues. Consider security-sensitive information leaks, and use the appropriate amount of lines and detail based on the complexity and criticality of the code. As an example, limit program entry/exit statements to significant process milestones and at the fine or finest log levels.
2. The two different log message types have different intended use. Standard messages from the database are translated and for use at the higher log levels (info to severe). Detailed text string log output for the lower debug log levels (config to finest). Also note the use of System.out or System.err is discouraged as they do not write to log files, only the JDeveloper console window. The content is also not as consistent and rich as ODL logging.
3. Consider the performance impact of additional logging. As an example just opening a page can produce more than 400 log lines without specifying a log module filter. Use care in crafting the logging API calls (without wrappers), using exception handlers, and define the scope of related variables (i.e. locally).
4. Understand how to use log correlation using the Execution Context Identifier (ECID) printed on each log line. This allows execution flow to be tracked across technology components.
5. Avoid setting debug configuration in the technology components, such as Java startup –D parameters. Whilst it is possible to use these (e.g. -DAFLOG_ENABLED and -DAFLOG_LEVEL) it should only be considered for a system-wide non-production issue.
6. Leverage Implicit Logging, where standard database messages are pre-configured so that they are written to the log file every time they are used. This is done based on the message attributes, defined in the Manage Messages setup screen (based on table FND_MESSAGES_B), and will implicitly log when set as follows:
   a. Logging Enabled (LOGGABLE_ALERTABLE) = Y
   b. Message Type (TYPE) = ERROR
   c. Severity (MESSAGE_SEVERITY) = HIGH, MEDIUM, or LOW
   d. Category (MESSAGE_CATEGORY) = not null
7. Use the features of QuickTrace, a continuous log buffer that captures FINE level log lines for all users. This stores lines in an allocated memory space and flushes them to a file either upon request or incident creation. QuickTrace can be useful in diagnosing hard to reproduce issues, getting a log without changing any configuration (it’s on by default), or in looking across the WebLogic Server instance for general symptoms. More details can be found in the Fusion Applications Administrators Guide.
8. Understand and use Selective Tracing. This offers a simple method of enabling all the loggers for one specific user and dedicated time window. It includes AppsTrace (from Release 5 onwards) which is an extension that incorporates detailed ADF logs and artifact lifecycle information. Again more details can be found in the Fusion Applications Administrators Guide.
9. Don’t just rely on the Fusion Applications logs, as useful information may be written to the technology component logs also. Always review the associated WebLogic Server log file, and consider enabling the loggers for other in-use components. Some examples are:
   a. oracle.adf and oracle.jbo– for ADF and ADFbc issues
   b. oracle.idm and oracle.security -  for the idM products.
   c. oracle.soa -  for all SOA Suite components, including BPEL, Mediator and Human Workflow services.
   d. oracle.webcenter– for collaboration and page customization features
   e. oracle.webservices and oracle.wsm– for the webservices platform
   f. oracle.bi– for the presentation server for reports and dashboards
   g. oracle.as.ess– related to the Enterprise Scheduling Server
10. Use Enterprise Manager to configure and review logs, as it simplifies many steps and has time-saving tools for combining logs from multiple locations, downloading log sections, and slicing up large files into more manageable pieces.  Where direct access to the log file is preferred, the more commonly used files are found in the following locations:
      a. Fusion Applications Diagnostic Log for Java and SOA: [DOMAIN_HOME]/servers/[SERVER_NAME]/log/apps/[servername]-diagnostic.log
      b. Fusion Applications Diagnostic Log for C code: Profile Option AFLOG_FILENAME includes the location and file name.
      c. Fusion Applications Diagnostic Log for PLSQL code: Profile Option AFLOG_PLSQL_FILENAME points to a directory-object stored in the ALL_DIRECTORIES database table that has the filesystem location.  The predefined APPLLOG_DIR object is recommended.
      d. WebLogic Server log file: [DOMAIN_HOME]/servers/[SERVER_NAME]/logs/[servername]-diagnostic.log

Summary

Logging in Fusion Applications has the richest and most comprehensive set of information and options available in almost any Enterprise Application, and reusing the same capabilities is relatively straightforward. Armed with the knowledge of log content, configuration, and the API’s to use, debugging issues should be efficient and effective, especially with the addition of a few tips-and-tricks.

If you have a story or tip to share on using logging in your Fusion Applications development then please post a comment and we’ll discuss and potentially share for the benefit of everyone.

References

More detail on the API’s and steps for implementing logging can be found in the following documents.

• Fusion Applications Administrators Guide- Part III Monitoring
• Fusion Middleware Administrator’s Guide–Chapter 12 – Managing Log Files and Diagnostic Data