WLWatchman Manual :: Alerts and Formatters

	Overview

Alerts are attached to attributes and are specified in wlwatchman-config.xml. (A post-1.3 release will have this functionality in the console) The generic form is

<attribute name="ExecuteThreadCurrentIdleCount" type="primitive">
   <alert class="[class]"/>
</attribute>

where [class] extends net.wlwatchman.alerts.AlertMonitor. The alert tag can have an arbitrary number of alert-parameter sub elements, the precise number and their values depends on the Alert you're using.

For example, the following XML fragment configures an alert on the ExecuteThreadCurrentIdleCount attribute of an ExecuteQueueRuntime object:

<attribute name="ExecuteThreadCurrentIdleCount" type="primitive">
 <alert class="net.wlwatchman.alerts.ThresholdAlert">
    <alert-parameter name="bound" value="lower"/>
    <alert-parameter name="limit" value="5"/>
    <alert-parameter name="action" value="log"/>
    <alert-parameter name="logfile" value="alerts.log"/>
    <alert-parameter name="message" value="$o.$a on $s has crossed its threshold."/>
  </alert>
</attribute>

The OOTB alerts are detailed below.

Alerts can be raised asynchronously through a central AlertLogger mechanism which outputs the alert messages to a file, WLWatchman-alerts.log, by default. The format of an alert in this file is:

<date> <Alert> <alert msg>

It is convenient to include the server name, object and attribute names in the alert message passed to AlertLogger, as in the ThresholdAlert class.

The following OOTB alerts are intended both for use and as examples on how to write alerts.

	ThresholdAlert

ThresholdAlert is designed to be attached to an attribute that has a numeric value and assesses whether the attribute has gone above or below a threshold value. A good example is the number of idle threads - you configure a ThresholdAlert to watch for when this drops below a value which indicates that the server is running into difficulty.

These are the parameters that this alert can take:

bound	takes values "upper" or "lower". This parameter determines whether the threshold value is an upper or lower bound, ie whether the value of the attribute in a normal running system should be below or above this value, respectively.
limit	the value of the threshold. This is the numeric value of the threshold.
action	takes values "log," "report" or "output." This determines what action the alert takes if the threshold is passed. "log" causes it to write to a file, the root of which is given in the "logfile" attribute; "report" causes it to raise an alert via the AlertLogger (see above) and "output" prints the alert message to stderr.
logfile	name of the logfile root for this alert. The full name of the alert log is this root prefixed with the server, object and attribute names.
message	the message that gets reported when the alert is raised. ThresholdAlert does some variable interpretation in this message: $s is translated as the server name, $o as the object name and $a as the attribute name; for example, "$o.$a on $s" could become "default.ExecuteThreadCurrentIdleCount on myserver" for the relevant attribute.

Currently, this alert can only be attached to primitive-type attributes with numeric values, eg. ExecuteThreadCurrentIdleCount on an ExecuteQueueRuntime object.

	MemoryAlert

MemoryAlert shows how to use multiple attributes to determine the server condition. It can be attached to HeapSizeCurrent or HeapFreeCurrent in the JVMRuntime and provides a "traffic light" on the current free heap size. It takes the following parameters:

redLevel	the percentage, as an integer, at "red"
amberLevel	the percentage, as an integer, at "amber"

The alert reads the values of HeapSizeCurrent and HeapFreeCurrent and calculates the percentage of the heap that is free. This then outputs the percentage to file and raises an alert through AlertLogger if it is red or amber. It is assumed that below amber the state is green.

	Overview

Each monitored object can have a number of formatters attached to it to format and output the values of the attributes being monitored. A formatter extends net.wlwatchman.formatter.Formatter and is created at runtime by the FormatterFactory class in the same package. A Formatter has access to the monitor runtime through the m_thread member variable and to the full list of attributes through the m_wrapper member variable.

In earlier versions of WLWatchman, each object has one Formatter configured as an attribute in the <object> tag:

<object name="default" location="myserver"
	  type="ExecuteQueueRuntime"
	  formatter="net.wlwatchman.formatter.CSVObjectOutput">

WLWatchman 1.3 introduces multiple formatters, specified in a list inside the object tag in wlwatchman-config.xml:

<formatter-list>
  <formatter class="net.wlwatchman.formatter.DefaultFormatter" />
</formatter-list>

The OOTB formatters are listed below.

	CSVObjectOutput

A formatter for printing CSV files for insertion into Excel.

	GraphFormatter

A formatter for sending data to the data collector for the appropriate GraphFrame. This is automatically added to the list of formatters when the GraphFrame for the object is opened in the console.