Logging in Oracle BI Server

This section describes logging specifically in Presentation Services .

Topics include:

See Understanding Diagnostic Log Files and Log Configuration Files.

Using the Oracle BI Presentation Services Logging Facility

You can troubleshoot issues and errors using the Oracle BI Presentation Services logs.

By default, Oracle BI Presentation Services is configured to log all error events and informational and warning events of sufficient importance. An example of an important informational event is a server starting up or a server shutting down. Log files are named sawlogxx.log, where the xx is replaced by an incremented number.

To debug specific issues that a user might be encountering, the logging level can be increased to log more information than the default configuration. For example, while debugging a particular Oracle BI Presentation Services connectivity issue, you can increase the maximum logging on the saw.odbc log source only. This adds detailed logging for that component, without cluttering the log with detailed logging from other events. All Oracle BI Presentation Services configuration information is loaded from the instanceconfig.xml file.

Caution:

Because logging affects performance, do not increase the logging on a production implementation, except to diagnose specific issues.

Setting the Logging Levels for Oracle BI Presentation Services

You use options on the Administration page in Presentation Services to affect logging levels.

In the global header, click Administration.
In the Maintenance and Troubleshooting area, select the logging level to use under Reload Log Configuration.
Click Reload Log Configuration to allow the change to take effect without restarting Presentation Services.

The change remains in effect even when you stop and restart Presentation Services.
Click the Manage Sessions link to display the Manage Sessions page.
For each session, specify the appropriate level in the Log Level column of the table.

The updated level takes effect immediately for that session. When you select a level, ensure that its severity value is smaller than or equal to the value specified for all messages in Presentation Services.

Structure for the Oracle BI Presentation Services Configuration File

The structure of the Oracle BI Presentation Services configuration file allows system output to be presented properly.

The structure of the configuration file is shown in the following example. The cardinality of each node is shown in brackets.

Example 6-3 Structure of Log Section in instanceconfig.xml File

Logging [1..1]
Writers [0..1]
Writer [0..1]
WriterClassGroups [0..1]
Filters [0..1]
FilterRecord [0..n]

An example of an instanceconfig.xml file that has four writers is shown below.

Example 6-4 instanceconfig.xml File with Four Writers

<?xml version="1.0" ?>
<Server>
. . . . . . .
<Logging>
<Writers>
<Writer implementation="FileLogWriter" name="Global File Logger"
writerClassId="1" dir="{%ORACLE_BIPS_INSTANCE_LOGDIR%}" filePrefix="sawlog"
maxFileSizeKb="10000" filesN="10" fmtName="ODL-Text" ODLLogFilePath="{%ORACLE_BIPS_INSTANCE_LOGDIR%}/diagnostic.log"/>
<Writer implementation="CoutWriter" name="Global Output Logger"
writerClassId="2" />
<Writer implementation="EventLogWriter" name="Event Logger"
writerClassId="3" />
<Writer implementation="CrashWriter" name="CrashWriter"
writerClassId="4"
/>
</Writers>
<WriterClassGroups>
<WriterClassGroup name="All">1,2,3,4</WriterClassGroup>
<WriterClassGroup name="File">1</WriterClassGroup>
<WriterClassGroup name="Console">2</WriterClassGroup>
<WriterClassGroup name="EventLog">3</WriterClassGroup>
<WriterClassGroup name="Crash">4</WriterClassGroup>
</WriterClassGroups>
<Filters>
<FilterRecord writerClassGroup="Console" path = "saw" information="1" warning="31" error="31" trace="0" incident_error="32" />
<FilterRecord writerClassGroup="File" path = "saw" information="1" warning="31" error="31" trace="0" incident_error="32" />
<FilterRecord writerClassGroup="File" path="saw.mktgsqlsubsystem.joblog" information="1" warning="2" error="31" trace="0" incident_error="32"/>
<FilterRecord writerClassGroup="File" path="saw.httpserver.request"
information="16" warning="32" error="32" trace="0" incident_error="32"/>
<FilterRecord writerClassGroup="File" path="saw.httpserver.response"
information="16" warning="32" error="32" trace="0" incident_error="32"/>
</Filters>
</Logging>
</Server>

The following table contains a description of each node in the configuration hierarchy.

Element	Attribute	Description
Writers	None	Contains writers configuration. This configuration is loaded on startup.
Writer	None	Configures a writer.
Writer	disableCentralControl	(Optional) Determines that this entry is not updated by Fusion Middleware Control. Default value is true.
Writer	implementation	The following implementations are defined: FileLogWriter. Writes to a disk file. CoutWriter. Writes to standard output. EventLogWriter. Writes to a Windows event log or UNIX syslog. CrashWriter. A Windows only facility that writes to a crash dump file when Presentation Services attempts to log from a specific source file and line number. Used in a production environment for information of some loggable but irrecoverable error (for example, failed NQTEST). Note: Use this implementation with care as it might leave the server in an unstable state. Use this implementation in very rare diagnostic-only scenarios on a test system. On Windows, CrashWriter requires the appropriate version of `dbghelp.dll` (at least 6.0.17.0). The correct `dbghelp.dll` can be found in `support/windows/system64`. Put this DLL in the `WINNT/system64` or in the `main/bin` directory. No registration is required.
Writer	name	Unique name for the writer.
Writer	writerClassId	Specifies an integer number in the range 1 through 10. This number is used by filters to allow or prohibit logging. Each distinct writer must have a unique value, which is used later for filter configuration. Different writers might have the same class ID, but if they do, those writers cannot be distinguished by filters.
Writer	fmtName	(Optional) Specifies the format of logged messages. Valid values are: default - 10g style. Formats messages with identifying headings. ODL-TEXT. Formats messages in Oracle Diagnostic Text format. ODL-XML. Formats messages in Oracle Diagnostic XML format. If you do not set this attribute, then logged messages are displayed in the default format which for file log writers is 10g style and for console is ODL-TEXT. See Examples of the Formats of Logged Messages for examples.
Writer (FileLogWriter specific attribute)	dir	Specifies the directory where log files are created.
Writer (FileLogWriter specific attribute)	ODLLogFilePath	Specifies the file that Fusion Middleware Control displays in the Log Viewer.
Writer (FileLogWriter specific attribute)	maxFileSizeKb	Specifies the maximum size of the logging file in kilobytes. When the file size limit is reached, the file is closed and a new logging file is created.
Writer (FileLogWriter specific attribute)	filePrefix	Specifies the prefix for log files.
Writer (FileLogWriter specific attribute)	filesN	Specifies the maximum number of logging files. When this number is exceeded, the first file is deleted and re-created again. Then the logger starts to write to the beginning of the first file.
Writer (EventLogWriter specific attribute)	winSource	Specifies the event log source for logged events.
Writer (CrashWriter specific attribute)	file	Specifies the dump file path. On Windows, a dump file is created in `bin/coredumps` and Presentation Services continues to run.
Writer (CrashWriter specific attribute)	line	Dump file line number.
WriterClassGroups	None	Contains the definition for writer classes. A writer class is a group of writer class IDs.
WriterClassGroup (Contains [as child text] a comma-delimited list of class IDs.)	name	Specifies the name of the WriterClassGroup.
Filters	None	Contains filter configuration.
FilterRecord	writerClassGroup	Specifies the group of writers to which this record is applied. WriterClassGroup is likely defined previously in the WriterClassGroups section.
FilterRecord	disableCentralControl	(Optional) Determines that this entry is not updated by Fusion Middleware Control. Default value is true.
FilterRecord	path	Specifies the log source path. To enable the logging of SOAP information, enter the following value: `saw.httpserver.request.soaprequest` The current filter record is applied to the software component that is identified by that path and all its subcomponents.
FilterRecord	information	Contains an integer that specifies the severity of the corresponding message type. Only messages with a severity index less than the provided number are logged.
FilterRecord	warning	Contains an integer that specifies the severity of the corresponding message type. Only messages with a severity index less than the provided number are logged.
FilterRecord	error	Contains an integer that specifies the severity of the corresponding message type. Only messages with a severity index less than the provided number are logged.
FilterRecord	trace	Contains an integer that specifies the severity of the corresponding message type. Only messages with a severity index less than the provided number are logged.
FilterRecord	incident_error	Contains an integer that specifies the severity of the corresponding message type. Only messages with a severity index less than the provided number are logged.

Examples of the Formats of Logged Messages

The fmtName attribute of the Writer element formats logged messages in one of three formats: default (10g style), ODL-TEXT, and ODL-XML.

The following example shows the default format.

Example 6-5 Default Format

The default format generates messages with identifying headings, such as:

Type: Information
Severity: 30
Time: Wed Jul 26 11:22:20 2006
File: project\sawserver\sawserver.cpp
Line: 399
Properties: ThreadID-2552
Location: 
             saw.sawserver
             saw.sawserver.initializesawserver
             saw.sawserver
Oracle BI Presentation Services has started successfully.

The following example shows the ODL-TEXT format.

Example 6-6 ODL-TEXT Format

The short format generates messages in a shortened form without identifying headings, such as:

[timestamp] [component id] [messagetype:level] [message-id] [module id] ([field-name: field-value])* message-text [[
supplemental-detail
]]

[2010-05-27T10:51:20.000-07:00] [OBIPS] [NOTIFICATION:1] [] [saw.sawserver] [ecid: 1243446680218334471555761] [tid: 2552] Oracle BI Presentation Services (OBIPS) 11.1.1.2 (Build 0) are starting up.[[
File:sawserver.cpp
Line:432
Location:
   saw.sawserver
   saw.sawserver.initializesawserver
   saw.sawserver
ecid: 1243446680218334471555761 
]]

The following example shows the ODL-XML format.

Example 6-7 ODL-XML Format

The xml format generates messages in XML format, such as:

<msg time="2010-05-08T18:41:05.000+00:00" 
comp_id="OBIPS" type="NOTIFICATION" level="1" msg_id="" 
module="saw.sawserver" ecid="124180446517874242628761" tid="127c"> 
<txt> Oracle BI Presentation Services has started successfully</txt> 
<suppl_detail /> 
</msg>

Oracle BI Presentation Services Message Structure

Each message that is logged by BI Publisher has several components, as described below.

Message Component	Description
Message Text	The text of the log message to the user.
Message Type	One of five types: information, warning, error, incident_error or trace. For information, see What Are Log File Message Categories and Levels?
Severity	The severity is represented as a positive integer. The lower the value, the more important the message. A message with severity of 0 is the most important type of message, whereas a message with a severity of 32 is not important at all.
Message Properties	Properties indicate other kinds of information. The kind varies among messages and might include user name, the IP address of the client browser, the thread ID, and so on.

Oracle BI Presentation Services Log Filters

FilterRecords customize logging details. Use FilterRecords to specify the implementation (output type) and logging levels for categories of web logs: Incident Error, Error, Trace, Warnings, and Information.

In the following example, the first two FilterRecords contain the following string:

path="saw"

This string logs the informational events at level 1, the error messages at level 31, and so on:

<FilterRecord writerClassGroup="Console" path="saw" information="1" warning="31" error="31" trace="0" incident_error="32" />
<FilterRecord writerClassGroup="File" path="saw" information="1" warning="31" error="31" trace="0" incident_error="32" />
<FilterRecord writerClassGroup="File" path="saw.mktgsqlsubsystem.joblog" information="1" warning="2" error="31" trace="0" incident_error="32"/>

This high-level path applies to every event.

You can customize FilterRecords by adding new FilterRecords, such as the third one shown in the preceding example, with finer-grain specification of log levels for events of various types. In this example, information is being logged to a disk file from saw.mktgsqlsubsystem.log, which generates Marketing job events.

You can disable logging of job details by changing the information level from 1 to 0, as shown in the following example, or by commenting out the lines:

<FilterRecord writerClassGroup="Console" path="saw" information="1" warning="31" error="31" trace="0" incident_error="32" />
<FilterRecord writerClassGroup="File" path="saw" information="1" warning="31" error="31" trace="0" incident_error="32" />
<FilterRecord writerClassGroup="File" path="saw.mktgsqlsubsystem.joblog" information="1" warning="2" error="31" trace="0" incident_error="32"/>

Diagnosing Issues with Agents

This section contains the following topics:

Debugging Agents Using Fusion Middleware Control

Agent error and debug log entries are written to the main scheduler log file nqscheduler.log, and are visible in Log Viewer usingFusion Middleware Control.

See Using Fusion Middleware Control to View Log Information, Error Messages, and Alerts.

An agent log entry includes key agent events, and provides information on a single trace line. For example:

Agent Chain Completed. Status: Completed, Agent ID: /users/weblogic/ChainedAgent, UserID: weblogic, OBIPS: example.com:0:9710, Job/Instance ID: 123/4567.

The table below details agent event logging, and associated trace types and levels.

Event	State	Message Type:Level
Agent Chain Started	Running	TRACE:1
Agent Chain Started	ReRunning	NOTIFICATION:1
Agent Chain Complete	Failed	ERROR:1
Agent Chain Complete	Timed Out	ERROR:1
Agent Chain Complete	Timed Out	WARNING:1
Agent Chain Complete	Warning	WARNING:1
Agent Chain Complete	Cancelled	NOTIFICATION:1
Agent Chain Complete	Try Again	NOTIFICATION:1
Agent Chain Complete	Completed	TRACE:1
Agent Started	N/A	TRACE:1
Agent Finished	N/A	TRACE:1

You can determine the log output detail written to the nqscheduler.log file by setting the level in Fusion Middleware Control. See Configuring Log File Rotation Policy and Specifying Log Levels. You can also filter log entries using ECID to find information specific to a particular agent chain.

Manually Debugging Agents Using instanceconfig.xml

If an agent fails to execute fully or if debugging is turned on in Oracle BI Scheduler, then a log file is generated for the agent.

You manually enable debugging by setting the Debug element to true in the Oracle BI Scheduler instanceconfig.xml file. For example, located at:

oraclehome/user_projects/domains/bi/config/fmwconfig/biconfig/OBISCH

See What Are Diagnostic Log Configuration Files and Where Are They Located?

The location for agent log files is also specified in the instanceconfig.xml file for the Oracle BI Scheduler (see Agent Scheduler Configuration Settings.) The default location for log files is the Log directory in the Oracle Business Intelligence installation directory on the computer where the Oracle BI Scheduler is installed.

The log file name has the following format:

Agent-JobID-InstanceID.xxx

In this file name:

Agent is the prefix for all agent log files.
JobID is the Oracle BI Scheduler job identifier for the agent.
InstanceID is the Oracle BI Scheduler instance identifier for the agent.
xxx is the file extension:
- .err for agent error log files.
- .log for debug log files.

The agent error and debug log files are written as separate files for each agent instance that fails to execute. You can use a text editor to view the files. Entries are generally self-explanatory.

The presence of an error log does not necessarily mean that an agent failed completely. For example, suppose an agent delivers content to multiple email addresses. If some addresses are invalid or the mail server is down, then an error log is generated for the agent.

You can also view error messages and exit codes for job instances in Job Manager. For information, see Instance Properties in Job Manager in Scheduling Jobs Guide for Oracle Business Intelligence Enterprise Edition). Exit status shows the number of deliveries successfully completed.