B Logging Features

This chapter describes the logging features available with Oracle WebCenter Interaction.

It includes the following sections:

• About the Logging Features

• Logging Levels

• Logging Spy

• Logger

• Console Logger

• Logging FAQ

About the Logging Features

Oracle WebCenter Interaction has several logging features available to help you monitor the health of your portal and troubleshoot any problems you might have.

• Job logs: If you must troubleshoot a problem with an authentication source, content crawler, or operation, you can view the logs for the job associated with that object. To view a job log, open the job and click the Job Logs page. For more information, see Viewing Job Status and Job Logs.

• The System Health Monitor is an administrative portal tool that provides real-time access to performance information on remote servers, custom objects, and Oracle WebCenter Interaction services. To access the System Health Monitor, go to portal administration and click Select Utility, then System Health Monitor. For details, see the portal online help.

• Log files: Each Oracle WebCenter Interaction component has its own log files. For example, the portal's log file is located in install_dir\ptportal\10.3.3\settings\logs.

• Logging Spy: Logging Spy (formerly PTSpy) is the primary log message receiver for Oracle WebCenter Interaction's logging framework. A GUI-based application for displaying log messages as they stream in from the portal and other log message senders.

• Logger: Logger runs as an unattended background process that receives log messages from the Oracle WebCenter Interaction logging framework and uses the Log4J framework to write messages to a disk file or other repository.

• Console Logger: Console Logger is similar to the Logger, but runs in a console window instead of in an unattended background process. Console Logger uses the Log4J console appender to display log messages in the console window.

Logging Levels

There are eight logging severity levels:

Table B-1 Logging Levels

Severity Level	Description	Logging Spy Color Code
Info	Normal but significant event.	black
Action	Significant action between Info and Warning.	black
Function	Brackets the beginning and ending of function and puts bracketed message in context.	black
Performance	A millisecond timestamp (e.g., operation X took # milliseconds) for costly tunable operations.	green
Warn	Minor problem.	pink
Debug	Most common and numerous log call, used for detailed call tracing and parameter logging.	gray
Error	Major problem affecting application function.	red
Fatal	Blocking problem.	white on red

Verbose logging levels can be intrusive. Use the Debug logging level only if you are actively debugging; this level of logging will affect the performance of the portal.

Logging Spy

Logging Spy (formerly PTSpy) is the primary log message receiver for Oracle WebCenter Interaction's logging framework. Logging Spy displays log messages from the portal and other Oracle WebCenter Interaction products and services. It provides additional features including fine-grained filtering, saved log file display, error highlighting, find, and sort.

To launch Logging Spy in Windows, click Start, Programs, Oracle, WebCenter Logging Utilities, then Logging Spy. (The shortcut location is configured during installation. If you changed the default, use the location you chose.)

The default path to launch Logging Spy in UNIX and Linux is: install_dir/ptlogging/10.3.3/bin/PTSpy.sh

The buttons below the menus invoke the following features:

• Open Existing Log File: Loads a *.spy log file into the log buffer for review.

• Save File: Saves the contents of the log buffer to a *.spy log file for later review.

• Copy Selection: Copies the selected log message lines into the system clipboard as text. Click the mouse over a line to select it. Use shift+up arrow or shift+down arrow to extend the selection.

• Clear Log: Clears the contents of the log buffer.

• Set Filters: Invokes the Filter Settings dialog box to change the visibility of various log levels and components.

• Start/Stop Logging: A toggle button to start or stop logging. Stopping logging may be useful when many messages are flowing and you want to concentrate on a set of messages already captured by Logging Spy.

To configure which applications to log and which logging levels to retrieve:

1. Click Set Filters to open the Filter Settings dialog.

2. To add a new application, click Edit, then Add Message Sender.

3. In the Add Message Sender dialog box, select the logging application name of the sender from which you wish to receive log messages and click OK.

   Most Oracle WebCenter Interaction components use the naming convention productname.computername.username. If you do not see an application name for your sender, see the instructions in Logging FAQ.

The message sender is displayed as a top node in the Filter Settings dialog. If Logging Spy detects the application on the network, the application components will appear as sub-nodes in the Filter Settings dialog. Under each component sub-node are eight sub-nodes for the eight logging levels. For information on logging levels, see Logging Levels.

By default, the Warn, Error, Fatal and Action logging levels are enabled for all components. To change these settings, click the corresponding checkbox or use the Edit menu to make changes that affect multiple components. To revert all components to the default settings, click Edit | Reset Filters. Click Apply or OK to save your changes. (The default settings are defined in an XML configuration file called ptspy.xml. The format of ptspy.xml is similar to that of ptLogger.xml. For information on ptLogger.xml, see Configuring Logger (ptLogger.xml).)

The Logging Spy interface displays enabled logging messages from all application components in the order they are received. The view can be filtered by a range of parameters, including component and severity level (Type).

The state of the logging receiver is displayed in the bottom right of the Spy window:

• Not receiving: The logger is stopped and is not receiving messages.

• Receiving autoscroll on: The default state of the receiver is to display all messages in the window and scroll as new messages are received.

• Receiving Messages: Click the highlighted line to start auto-scrolling. Last received message ID: ##: If you click on a logging message line to view a specific message, the receiver stops scrolling. New messages are still added to the bottom of the display. To reactivate auto-scroll, click the selected line again.

• Not displaying some received messages: If you sort the view by a specific column, the receiver only displays the existing messages, ordered by the selected column. New messages are buffered. To reset the window and view all messages, click any logging message line in the window twice.

To view the full text of a logging message, copy the line to a text editor. To select the entire line, click CTRL+C. To select the message text only, click CTRL+M. (To paste the text in the text editor, click CTRL+V.)

If you do not see any messages from your sender, see the instructions in Logging FAQ. This page also explains how to configure the memory allowance for Logging Spy.

Logger

Logger runs as an unattended background process that receives log messages from the Oracle WebCenter Interaction logging framework and uses the Log4J framework to write the messages to a disk file or other repository. Log4J is an open source logging solution from Apache that comes bundled with a wide variety of solutions for dealing with logging messages. In Log4J terminology, these solutions are called appenders. By taking advantage of Log4J appenders, Logger is also able to deal with log messages in a wide variety of ways.

The primary use of Logger is to save log messages to a disk file, but it can also be used in more exotic ways, such as sending log messages to an e-mail system. This can all be done without any coding, simply by modifying the ptLogger.xml configuration file and adding Log4J appender elements as explained below. The default location for the log files produced by Logger is install_dir\ptlogging\logs.

Configuring Logger (ptLogger.xml)

Logger uses an XML configuration file called ptLogger.xml (install_dir\settings\ptlogging). This configuration file specifies which servers the logger should receive messages from, and which Log4J appender(s) should be used for the log messages from each server. Each server can be associated with one or more appenders. You can also specify that only messages at certain logging levels from a given server should be sent to an appender.

The specification for the ptLogger.xml file is as follows.

The root level xml node must be <configuration>. Under <configuration> there are two types of nodes: <appender> and <filters>. There may be zero or more of any of these nodes and they may appear in any order. The syntax and semantics of each node is defined below.

An <appender> node defines the settings for a specific Log4J appender, and must follow the format specified in the Log4J specification, as shown in the example below.

<appender class="org.apache.log4j.RollingFileAppender" name="CollabRollingLogFile">
     <layout class="com.plumtree.openlog.log4jbridge.MyPatternLayout" />
     <!-- The output file name -->
<param name="File" value="c:/collab.log" />
     <!-- The maximum size of each file -->
<param name="MaxFileSize" value="10MB" />
     <!-- The maximum number of files to keep around -->
<param name="MaxBackupIndex" value="1" />
</appender>

• The class attribute specifies the Java class of the appender. In this example, the attribute is "org.apache.log4j.RollingFileAppender," so the Rolling File Appender is being specified. This is the appender used most often by the Logger. The purpose of the Rolling File Appender is to save log messages to a disk file with control over the size of the file. When the file gets too big, a new log file will be started. (Logging messages can be forwarded to any Log4J appender.)

• The name attribute specifies a user-defined name. It is important to specify a unique and meaningful name for each appender. In the example above, the name is "CollabRollingLogFile" indicating that this appender will be used to save log messages from Oracle WebCenter Collaboration. This name is used in the <filters> node to associate the appender with a server.

• The layout element specifies the Java class to use for the layout. This value should never be changed. Every appender node must use the layout class com.plumtree.openlog.log4jbridge.MyPatternLayout.

• The <param> node with attribute name="File" specifies the location of the output file. The value attribute should contain the full path to the desired output file.

• The <param> node with attribute name="MaxFileSize" specifies how large the file is allowed to grow before a new log file is started. See the Log4J documentation for details.

• The <param> node with attribute name="MaxBackupIndex" specifies how many backup log files to keep. See the Log4J documentation for details.

A <filters> node is used to specify a log message sender from which Logger should receive messages and the appender to which messages should be channeled. The filters node defines which logging levels are enabled for each component in the sending application, as shown in the examples below.

<filters server="collab.Foo-w2k.BarryF" appender="CollabRollingLogFile" enabled="true" restrict-to-local="false" >
 
<component-defaults>
<level enabled="false" value="Debug" />
<level enabled="false" value="Info" />
<level enabled="false" value="Warning" />
<level enabled="true" value="Error" />
<level enabled="true" value="Fatal" />
<level enabled="false" value="Action" />
<level enabled="false" value="Performance" />
<level enabled="false" value="Function" />
</component-defaults>
 
<component name="Documents">
<level enabled="false" value="Debug" />  
<level enabled="true" value="Info" />
<level enabled="true" value="Warning" />
<level enabled="true" value="Error" />
<level enabled="true" value="Fatal" />
<level enabled="true" value="Action" />
<level enabled="false" value="Performance" />
<level enabled="false" value="Function" />
</component>
 
</filters>
 
<filters server="collab.Foo-w2k.BarryF" appender="EmailAppender" enabled="true" >
 
<component name="Documents">
<level enabled="false" value="Debug" />
<level enabled="false" value="Info" />
<level enabled="false" value="Warning" />
<level enabled="true" value="Error" />
<level enabled="true" value="Fatal" />
<level enabled="false" value="Action" />
<level enabled="false" value="Performance" />
<level enabled="false" value="Function" />
</component>
 
</filters>

The <filters> node has two required attributes (server and appender), two optional attributes (enabled and restrict-to-local).

• The server attribute (required) is the application name of the log message sender from which Logger should receive log messages. Typically a log message sender will read its application name from a configuration file at start-up. The application name can be any string that meets the following restrictions: it must be no longer than 128 characters and non-empty, it may only contain non-white-space visible ASCII characters and the space character. Most Oracle WebCenter Interaction products follow the naming convention [product-name].[computer-name].[user-name].

• The appender attribute (required) is the name of the appender node to which Logger will send messages. This attribute must reference the name attribute from an existing <appender> node (described above). The first node in the example above references the CollabRollingLogFile appender node defined above. The second node uses an appender called “EmailAppender,” so there must be an <appender> node named “EmailAppender” somewhere in the ptLogger.xml file.

• The enabled attribute (optional) offers a convenient way to disable a server without deleting the entire <filters> node. If the attribute is omitted, the value defaults to true. If the attribute is set to false, the server is temporarily disabled; no log messages from this server will be received.

• The restrict-to-local attribute (optional) enables you to restrict the scope of the filter messages it sends out to the local computer. If the attribute is omitted, the value defaults to false. If the attribute is set to true, the Logger assumes that the log message sender resides on the same computer on the network; no messages will be sent over the network. If you do not know whether the log message sender will reside on the same computer as Logger, the value of this attribute should be set to false.

Each node has zero or more <component> sub-nodes and an optional <component-defaults> sub-node.

• Each <component> sub-node has eight <level> sub-nodes and one required name attribute. The value of the name attribute is the name of one of the components from the server. (A component is a named sub-part of an application. For example, Oracle WebCenter Collaboration uses components named Documents, Discussions, Tasks, Calendar, Search, UI, Infrastructure, and Miscellaneous. The portal uses over 100 different components.) The eight <level> sub-nodes correspond to the eight logging levels: Debug, Info, Warning, Error, Fatal, Action, Performance, and Function.

  Each <level> sub-node has two required attributes: enabled and value.

  • The value attribute is required defines the logging level (Debug, Info, Warning, Error, Fatal, Action, Performance, or Function). As noted above, a <component> node must have eight <level> sub-nodes, one for each logging level.

  • The enabled attribute sets whether a specific logging level is enabled. Its value must be set to either true or false. If a logging level is disabled (enabled="false"), messages in that category will not be sent to the receiver.

• The <component-defaults> sub-node (optional) has eight <level> sub-nodes that follow the syntax described above. The values of the <level> sub-nodes in the <component-defaults> sub-node apply to all components of the application other than the ones explicitly defined in a <component> node.

If you do not see any messages from your sender in the logging file, see the instructions in Logging FAQ.

Starting Logger

In Windows, Logger is a service. Start and stop the service by clicking Start, Programs, Oracle, WebCenter Logging Utilities, then Logger Start or Logger Stop.

In UNIX and Linux, Logger is a daemon. Start and stop the daemon using the shell script install_dir/ptlogging/10.3.3/bin/ptLogger.sh. To start the daemon, use the command: ptLogger.sh start. To stop the daemon, use the command: ptLogger.sh stop.

Console Logger

Console Logger is similar to Logger, except that it runs in a console window. Console Logger uses the Log4J console appender to display logging messages in a console window. Console Logger has limited use; in most cases, it is preferable to use Logging Spy.

Console Logger uses an XML configuration file called consolelogger.xml. The format for consolelogger.xml is identical to that of ptLogger.xml (see Configuring Logger (ptLogger.xml)). Console Logger ships with one <appender> node in consolelogger.xml:

<appender class="org.apache.log4j.ConsoleAppender" name="Console">
<layout class="com.plumtree.openlog.log4jbridge.MyPatternLayout" />
</appender>

This node uses the Log4J Console Appender which, as the name implies, sends log messages to the console. It is possible to add additional <appender> nodes to consolelogger.xml as with ptLogger.xml, but this approach is uncommon.

Starting Console Logger

To run Console Logger in Windows, execute install_dir\ptlogging\10.3.3\bin\consoleLogger.bat.

To run Console Logger in UNIX, execute install_dir/ptlogging/10.3.3/bin/consoleLogger.sh.

Logging FAQ

The following troubleshooting information provides solutions for common problems with logging configuration.

Logging Spy

Q: The application I need does not appear in the list of senders in the Add Message Sender dialog box.

A: First, ensure that the message sender is running. Then check the following:

• If the message sender is running on a different computer, confirm that the sender is configured to allow remote spying. The message sender will have a logging configuration setting named restrictToLocalHost, or something similar. The value of this setting must be set to False to allow remote spying. For details, see the documentation for the message sender.

• If the message sender is running on a computer on a different subnet, confirm that the network routers are configured to allow UDP multicast traffic between the message sender computer and the Logging Spy computer.

• If the message sender or Logging Spy runs on a Microsoft Windows computer, the problem might be due to a known issue on some versions of the Windows operating system. The problem shows up when a Microsoft Windows computer has more than one network adapter installed. This is common if the Microsoft Windows computer has VM Ware installed. There are several workarounds:

  • Install an appropriate hotfix or service pack for the Microsoft Windows operating system. See the Microsoft support page for this issue at http://support.microsoft.com/?kbid=827536.

  • Alternatively, you can remove the additional network adapters. Disable the VMWare adapters. (Go to Control Panel | Network and Dial-Up Connections, right-click on each connection and disabling it.) Get the properties for your Local Area Connection and disable the VMWare Network Bridge.

Q: Where are the messages from my sender? Logging Spy does not display messages from my application.

A: First, go through troubleshooting steps above. In Logging Spy, check the filter settings for the message sender. By default, only Error, Warning, Fatal, and Action are enabled. It is possible that the log message sender is not sending any messages at those logging levels. Try enabling Debug and see if you receive any messages.

Q: How do I increase the amount of memory allotted to Logging Spy?

A: Logging Spy will collect and display log messages until it detects that it is running low on memory. At this point it will refuse to accept messages and will display an alert. This is true both when Spy is displaying messages that are streaming in, and when Spy is displaying messages from a .spy log file. To increase the amount of memory available to Logging Spy, follow the steps below.

Windows:

1. Edit the ptspy.lap file located in install_dir/ptlogging/10.3.3/bin.

2. Locate the following line: -Xmx256m

   The number in this line defines the maximum megabytes of memory available to Logging Spy (256 by default as shown above).

3. Set this number to the desired level. As a first step we recommend doubling the number to 512 (-Xmx512m).

4. Save the file and restart Logging Spy.

UNIX:

1. Edit the ptspy.sh file located in install_dir/ptlogging/10.3.3/bin.

2. Locate the following line: JAVA_MEM_OPTS="-Xms32m -Xmx256m"

   The second number indicates the maximum megabytes of memory available to Logging Spy (256 by default as shown above).

3. Set this number to the desired level. As a first step we recommend doubling the number to 512 (JAVA_MEM_OPTS="-Xms32m -Xmx512m").

4. Save the file and restart Logging Spy.

Logger

Q: Where are the messages from my sender? Logger is not recording messages from my message application.

A: First, go through troubleshooting steps under the first question above. If you are not receiving any messages in a log file from a given message sender, ensure that the Logger Service/Daemon is running. Check the Logger internal diagnostic file at install_dir/ptlogging/logs/ptlogger.out. You should see messages of the form "Starting the Logger service...", "--> Wrapper Started as Service","OpenLog: verbosity level = 2", "Logger: Successfully read configuration file at: C:\Program Files\Oracle\Middleware\wci\ptlogging\10.3.3\bin\..\..\..\settings\ptlogging\ptLogger.xml".

Check the Logger configuration file: install_dir/settings/ptlogging/ptLogger.xml. Ensure that there are appropriate <filters> and <appender> nodes in the configuration file for the message sender from which you are trying to receive messages. For more information, see Logger.