edocs Home      dev2dev Home      Dev Centers      CodeShare      Community      Newsgroups     

ALUI Development Environment: Debugging

Configuring ALI Logging Utilities

ALI Logging Utilities (formerly Plumtree Logging Utilities) are used to receive messages from the IDK (EDK) and other logging message senders. For details on IDK logging, see Configuring IDK Logging Options.

The ALI Logging Utilities package includes three log message receivers that allow for a wide variety of logging solutions. This page includes instructions on how to configure these receivers. To download the utilities, go to the ALUI Developer Center on dev2dev.

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

• ALI Logger: ALI Logger (formerly Plumtree Logger) runs as an unattended background process that receives log messages from the ALI 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 ALI 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.

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

Logging Levels

There are eight logging severity levels:

ALI Logging Spy

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

The default path to launch ALI Logging Spy in Windows is Start | Programs | plumtree | PT Logging Utilities | Logging Spy. (The shortcut location is configured during installation. If you changed the default, use the location you chose.)

The default path to launch ALI Logging Spy in Unix is: <install directory>/ptlogging/6.0/bin/PTSpy.sh

The buttons below the menus invoke the following features:

Click the Set Filters button to open the Filter Settings dialog. This interface allows you configure which applications to log and which logging levels to retrieve. To add a new application, click Edit | Add Message Sender.

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 ALI components use the naming convention productname.machinename.username. If you do not see an application name for your sender, see the instructions in the Logging FAQ.  

The message sender is displayed as a top node in the Filter Settings dialog. If ALI 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.

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.)

The ALI 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 ALI 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 the Logging FAQ.  This page also explains how to configure the memory allowance for ALI Logging Spy.

For details on enabling logging for IDK components, see Configuring IDK Logging Options.

ALI Logger

ALI Logger (formerly Plumtree Logger) runs as an unattended background process that receives log messages from the ALI 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, ALI Logger is also able to deal with log messages in a wide variety of ways.

The primary use of ALI 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 ALI Logger is <install directory>\ptlogging\logs.

Configuring ALI Logger (ptLogger.xml)

ALI Logger uses an XML configuration file called ptLogger.xml (<install directory>\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.

1. 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.

2. 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.

1. 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 ALI 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.)

2. 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 ALI Collaboration. This name is used in the <filters> node to associate the appender with a server.

3. 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.

4. 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.

5. 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.

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

3. A <filters> node is used to specify a log message sender from which ALI 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.

The <filters> node has two required attributes (server and appender), two optional attributes (enabled and restrict-to-local). Each node has zero or more <component> sub-nodes and an optional <component-defaults> sub-node.

• The server attribute (required) is the application name of the log message sender from which ALI 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 ALI products follow the naming convention [product-name].[machine-name].[user-name].

• The appender attribute (required) is the name of the appender node to which ALI 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) allows you to restrict the scope of the filter messages it sends out to the local machine. If the attribute is omitted, the value defaults to false. If the attribute is set to true, the ALI Logger assumes that the log message sender resides on the same machine on the network; no messages will be sent over the network. If you do not know whether or not the log message sender will reside on the same machine as ALI Logger, the value of this attribute should be set to false.  

• 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, ALI 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 or not 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.

Earlier versions of ALI Logger used a similar XML format that did not allow you to define filters for specific appenders. Every server was mapped to every appender. For backward compatibility, these semantics are still supported.

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

Starting ALI Logger

In Windows, ALI Logger is a Windows service. Start and stop the service by clicking Start | Programs | plumtree | PT Logging Utilities | Logger Start and Logger Stop.

In Unix, ALI Logger is a Unix daemon. Start and stop the daemon using the shell script [install-dir]/ptlogging/6.0/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 ALI 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 ALI Logging Spy.

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

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\6.0\bin\consoleLogger.bat.

To run Console Logger in Unix, execute [install-dir]/ptlogging/6.0/bin/consoleLogger.sh.

Next: Configuring IDK Logging Options