Using the Counter Monitoring System

This chapter describes how to use the Counter Monitoring System to view real time statistical data on your portal, reported by various performance counters. This chapter includes the following sections:

About Counter Monitoring

The Counter Monitoring System collects information from various performance counters for portal applications and exposes them for diagnosis and review. This system can be used to examine counters from any AquaLogic User Interaction application that resides on a remote host, provided the two machines are on a network in which they can reach each other via UDP.

The following table lists the key counters provided with the portal. Each category of performance has one or more instances. Each instance in a category can be monitored with the counters for that category.

Setting up Counter Log Files

You can specify the location, size, and format of the counter log file(s), how often the counter values are polled, as well as filter which counters are written to the file(s).

In the PORTAL_HOME\bin directory, enter the following command:

opencounterslogger.bat (or opencounterslogger.sh on Unix) ServerName ContextName
-d LogDirectory -l LogOutputStyle -s MaxLogSize -r PollingInterval -f FilterExpression

Where these parameters are:

ServerName - The name of the server where the portal you want to monitor is installed, for example: ptserver2. The value of this name is set in the opencounters:application-name element in the
serverconfig.xml file (in PT_HOME\settings\common). This value is case-sensitive.

ContextName - The name of the AquaLogic User Interaction application you want to monitor, for example: portal. The value of this name is set in the context element in the serverconfig.xml file. This value is case-sensitive.

-d LogDirectory - (Optional) The local directory in which to create counter log files. The directory must exist prior to executing the opencounterslogger.bat command.

-l LogOutputStyle - (Optional) The log output style can be any combination of the following:

c - Log counter values in a .csv file, with counters sorted by counter name. CSV signifies a comma-delimited file, which can be read by applications like Excel, for convenient graphing of the values.
t - Log counter values in a .csv file, with counters sorted by time stamp.
f - Stream counter information to the file, with each line consisting of a counter name/value pair
s - Stream counter information to the screen, with each line consisting of a counter name/value pair.

-s MaxLogSize - (Optional) An integer that specifies the maximum size of any log file in kilobytes. Once this log file size is reached, the log is rolled over to a new file.

-r PollingInterval - (Optional) The rate, in seconds, at which counter values should be logged to file.

Note:

decreasing the polling interval (i.e., increasing the polling rate) can affect overall portal performance. Retaining the out-of-the-box setting should only affect performance by a maximum of 2%.

-f FilterExpression - (Optional) An expression that filters which counters are logged. Expressions are case-insensitive. Use Table B-1 to look up Category, Instance, and Counter names, then write the expression in the following format:

CategoryNameContains:InstanceNameContains:CounterNameContains

Each condition in the above expression is optional, and is used to limit the counter values returned.

For example:

-f Cache::Num will match all counters with a category name that contains Cache and a counter name that contains Num. The instance name will not be filtered.

Example of the opencounterslogger Command:

opencounterslogger.bat PtServer2admin collab -d C:\logdir -l t -s 1000 -r 10 -f open:sql:

At this point, if the logger is able to successfully connect to the server, you will see the following:

You can now check the logging directory for log files. Log files will not appear until there is at least one counter created on the counter server.

Running the Counter Monitoring Console

In addition to monitoring counter log files, you can view specified counter values through a console.

In the PORTAL_HOME\bin directory, enter the following command:

opencountersconsole.bat (opencountersconsole.sh on Unix) ServerName ContextName

Where these parameters are:

Once you enter the command, you see the counter console startup messages. If the connection to the specified server succeeds, you should see the following (with the server and application names you are monitoring displayed before the command prompt):

... Connection success!

[ServerName.ContextName]>

Example:

opencountersconsole.bat PtServer2 collab

This command opens a console to monitor the collab application on PtServer2. In this example, AquaLogic Interaction Collaboration is installed.

From the console command prompt, use any of the available commands (shortcut keys are in parentheses):

help (h) - Displays the help menu
last (l) - Performs the last command that was entered
num (n) - Gets the total number of counters that are available in the host server.
info (i) - Returns all counter names with their current values and additional description information. Optionally, you can enter a filter expression after the command to limit the information returned. A filter expression has the following format:

CategoryNameContains:InstanceNameContains:CounterNameContains

Each condition in the above expression is optional, and matches a substring of the category, instance, or counter names. See Table B-1 for some key category, instance, and counter names.

Example: info cache:pref:num

values (v) - Returns all counter names with their current values. Optionally, you can enter a filter expression after the command to limit the information returned. See the above example.

Example: values cache:pref:num

filterset (fs) - Sets the current filter for the category name, instance name, and counter name. This filter limits the information returned when using the filterget command. If filterset is not specified, the filterget command matches all available counters. This command uses a filter expression as described under the info command above.

Example: filterset cache:pref:num

Using this example command, followed by the command filterget, gives the same result as using the command values cache:pref:num by itself.

The filterset you specify remains in effect until you set a new one. To reset the filterset to the default value, enter filterset by itself. The default filterset matches all counters.

filtercategory (fc) - Sets the current category name filter. This affects the counters that are returned by the filtergetvalues command. The category names returned contain the substring you enter.

Example: filtercategory Open

The category filter you specify remains in effect until you set a new one.

filterinstance (fi) - Sets the current instance name filter. This affects the counters that are returned by the filtergetvalues command. The instance names returned contain the substring you enter.

Example: filterinstance Total

The instance filter you specify remains in effect until you set a new one.

filtercounter (fr) - Sets the current counter name filter. This affects the counters that are returned by the filtergetvalues command. The counter names returned contain the substring you enter.

Example: filtercounter Bytes

The counter filter you specify remains in effect until you set a new one.

filtergetvalues (fg) - Returns counter names with their current values. This command only retrieves counters that match the filters you have set using any of these commands: filterset,
filtercategory, filterinstance, filtercounter. If no filters have been set, the command matches all counters.
verbose (vb) - Toggles verbosity level on and off (default is OFF). When verbosity is set to On, the values command returns counter values with additional counter information (such as a counter description). When verbosity is set to Off, the values command returns counter values without additional counter information.
connect (c) - Connects to another host server. This disconnects from the current host server if one is already connected.

Example: connect PtServer4 portal

disconnect (d) - Disconnects from the current host server, if connected.
exit (e) - Exits the console application

Using Windows Perfmon to View Counter Data

The Counter Monitoring System integrates with the Windows Perfmon application. Once you start the portal, the Perfmon adaptor will add AquaLogic User Interaction counters to the list of possible counters to monitor. You can then start Perfmon (or any other monitoring application that works with Windows Performance Counters) and see AquaLogic User Interaction counters in the list of available counters.

Go to Start | Run.
Enter perfmon.exe and click OK.

Note:

In Perfmon, the category name is prefixed by the context name. The context name is set in the context element in the serverconfig.xml file (in PT_HOME\settings\common).

Disabling the Perfmon Adaptor

The Perfmon adaptor adds a few percentage points of overhead to overall system performance. If you want to disable the Perfmon adaptor, in PT_HOME\settings\serverconfig.xml, set
opencounters:perfmon-enabled to false.

Administrator Guide