# Installation and Upgrade Guide

# Configuring the Logging Utilities

This chapter discusses how to configure and launch the Logging Utilities.

## Logging Spy

To launch Logging Spy in Windows, click Start | All Programs | BEA | ALI Logging Utilities | Logging Spy. Or, from the command line, <install folder>\ptlogging\6.1\bin\ptspy.exe

To launch Logging Spy in UNIX or Linux, <install folder>/ptlogging/6.1/bin/ptspy.sh

For details on configuring Logging Spy, see the online help provided with the utility.

## Logger

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

In UNIX and Linux, Logger is a daemon. Start and stop the daemon using the shell script
<install folder>/ptlogging/6.1/bin/ptlogger.sh

- To start the daemon, use the command: ./ptlogger.sh start
- To stop the daemon, use the command: ./ptlogger.sh stop

The log files produced by the Logger are located in the following folder:

- For Windows: <installation folder>\ptlogging\logs\
- For UNIX or Linux: <installation folder>/ptlogging/logs/

The primary use of the Logger is to save log messages to a disk file, but it can also be used in other ways, such as sending log messages to an e-mail system. This can be done by modifying the ptLogger.xml configuration file and adding Log4J appender elements as explained below.

The ptLogger.xml configuration file (<install directory>/settings/ptlogging/ptLogger.xml) specifies which servers the logger should receive messages from, and which Log4J appenders 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 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” valued:/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 AquaLogic 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 the Logger should receive messages and an appender to which messages should be channeled. It specifies which logging levels are enabled for the given appender, for each component in the sending application. Here are two examples of <filters> nodes.

    <filters appender=”CollabRollingLogFile” server=”collab.Foo-w2k.BarryF”>

    	<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 appender=”EmailAppender” server=”collab.Foo-w2k.BarryF” 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>

Here is a detailed explanation of the syntax and semantics of a <filters> node:

- A <filters> node has zero or one <component-defaults> sub-nodes. <component-defaults> nodes (described below).
- A <filters> node has zero or more <component> sub-nodes (described below).
- A <filters> node has two required attributes, server and appender, and one optional attribute, enabled.

- The server attribute is required. The value of this attribute is the application name of the log message sender from which you desire to receive log messages.
- The appender attribute is required. The value of this attribute must match the value of the name attribute from one of the <appender> nodes. In the example above, the first <filters> node has appender = “CollabRollingLogFile” which indicates that this appender should receive log messages from the server Collab.Foo-w2k.BarryF. The second <filters> node has appender = “EmailAppender.” Although not shown in the example, there must be an <appender> node named “EmailAppender” in the ptLogger.xml file. Based on the name, this appender most likely uses the appender class org.apache.log4j.net.SMTPAppender, a Log4J appender that sends log messages in an e-mail. Messages from Collab.Foo-w2k.BarryF will also be sent to this appender.
- The enabled attribute is optional. If present its value must be “true” or “false.” If not present, the value “true” is assumed. If the attribute is present and its value is false, this indicates that the <filters> node is temporarily disabled. This attribute offers a convenient way to disable a <filters> node without having to delete it.

- A <component> node has eight <level> sub-nodes (described below).
- A <component> node has one required attribute, name. The value of this attribute is the name of one of the components from the server.
- A <level> node has two required attributes, enabled and value.

- The enabled attribute is required. Its value must be “true” or “false.” This value determines whether log messages of the given logging level from the given component will be sent to the associated appender.
- The value attribute is required. Its value must be “Debug”, “Info”, “Warning”, “Error”, “Fatal”, “Action”, “Performance”, or “Function”. A <component> node must have eight <level> sub-nodes, one for each of the above values.

- A <component-defaults> node has eight <level> sub-nodes. The values of the <level> sub-nodes below a <component-defaults> node apply to all components of the application other than the ones explicitly mentioned in a <component> node.

## Console Logger

To start the Console Logger in Windows, execute
<install folder>\ptlogging\6.1\bin\consolelogger.bat

To start the Console Logger in UNIX or Linux, execute
<install folder>/ptlogging/6.1/bin/consolelogger.sh

The Console Logger uses an XML configuration file called consolelogger.xml. The format for consolelogger.xml is identical to that of ptLogger.xml (see Logger). The 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.