18.0 Monitoring the MBean Attributes

Attributes in the MBean can be monitored using the AdventNet Monitor Service.

18.1 Monitor Service : An Overview

18.2 Counter monitor

18.3 Gauge monitor

18.4 String Monitor

18.5 Table Monitor

18.6 Monitor Notification

18.7 Running the Example

18.1 Monitor Service : An Overview

The Monitoring service allows you to observe the variation over time of attribute values in MBeans and emit notifications at threshold events. All monitors have a configurable granularity period that determines how often the attribute is polled. There are three monitor MBeans, one for counter attributes, another for gauge-like attributes, and the third for strings.

These monitors send notifications when the observed attribute meets certain conditions, mainly equalling or exceeding a threshold. The conditions are specified when the monitor is initialized. Monitors may also send notifications when certain error cases are encountered during the observation.

The monitor derives a value from the observation, called the derived gauge. This derived gauge is either the exact value of the observed attribute, or the difference between two consecutive observed values of a numeric attribute.

The time interval during which the attribute is monitored is called the Granularity period. It is specified in milliseconds. For example, if the granularity period is 5000, the attribute is monitored every 5 seconds.

Note: Counter Monitor, String Monitor, and Gauge Monitor are not supported for Tabular Data. In this release, AdventNet provides a new feature called "Table Monitor" to monitor MBean attribute values represented in Tabular format.

18.2 Counter Monitor

The Counter Monitor observes an attribute of type byte, short, int and long that is monotonically increasing. That means,

Their value is always positive or null
They can only be incremented

The counter monitor has a threshold value and an offset value to detect counting intervals. The counter monitor resets the threshold if the counter rolls over.

Creating a Counter Monitor MBean

You can create a Counter Monitor using the JMX Compiler UI or using API.

Using JMX Compiler UI

To add a Counter Monitor entry using JMX Compiler, please follow the steps given below:

Select Project -> Settings option. In the Settings Tree Structure, select JMX Standard Services -> Monitors -> Counter. This displays the dialog for the Counter Monitor on the right side.
Select the Add option. This displays the Entry Parameters for the Counter Monitor and Counter Attributes available in the loaded MIB.
Enter the following details:

Attribute : Select the Attribute that has to be monitored from the attributes listed in the attribute tree. Only those attributes in the MIB that are of "Integer, Timeticks, Integer32, Counter, Counter32, Counter64, TruthValue, TimeInterval, Storage Type, TestAndIncr" types will be displayed in the tree.

Threshold : Specify the comparison value with derived gauge to send notification.

Offset : Specify the value to increment in threshold after derived gauge reaches or exceeds threshold. If the offset value is not zero, whenever the threshold is triggered by the counter value reaching a comparison level, that comparison level is incremented by the offset value.

Enable Notification : The Counter Monitor Service sends a notification when the value of the counter reaches or exceeds a threshold known as the comparison level.

Difference Mode : Specify, derived gauge value calculation type, i.e., difference between two observations or not.

Granularity Period : Specify the time interval taken for monitoring the attribute, in milliseconds.

Click OK to add the entry to the table.

Example : Let us assume we want to monitor an MBean attribute "asmtimeTicksScalar" defined in MIB with default value of 0. The comparison level (threshold) is 10 and the offset value is 5. The attribute is monitored every five seconds as specified in the Granularity Period.

In this example, the Observed Attribute is asmtimeTicksScalar, the default attribute value is 0, the threshold value is 10, the time interval (granularity period) for monitoring the attribute is 5 seconds.

If Enable Notification option is selected, the Monitor service sends a notification , when the "asmTimeTicksScalar" value reaches the threshold value 10. Because the offset value is specified as 5, the comparison value (10) is incremented by 5, when the comparison level is reached.

Using API

A Counter Monitor can also be created by adding the relevant code directly in the generated main file inside registerJMXServices method. The following code snippet creates a Counter Monitor with the values as specified in the above example. The start() method is used to start the counter monitor service.

import javax.management.monitor.CounterMonitor;
CounterMonitor cm_0 = new CounterMonitor();
name = "Services:type=CounterMonitor,name=CounterMonitor_0";
cm_0.setObservedObject(new ObjectName"AdventNetJMXAgent:type=GroupV2NodeInstrument"));
cm_0.setObservedAttribute("Integerv22");
cm_0.setGranularityPeriod(5000);
cm_0.setDifferenceMode(false);
cm_0.setThreshold(new Integer (10));
cm_0.setOffset(new Integer (5));
server.registerMBean(cm_0, new ObjectName(name));
server.addNotificationListener(new ObjectName(name),notifImpl,notifImpl,(new Object()));
cm_0.start();

18.3Gauge Monitor

The Gauge Monitor observes an attribute of integer or floating point types that fluctuates within a given range. The gauge monitor has both a high and low threshold, each of which can trigger a distinct notification. The two thresholds can also be used to avoid repeated triggering when an attribute oscillates around a threshold. Notification for a particular threshold would be sent again only after the value crosses the other threshold.

Creating a Gauge Monitor MBean

You can create a Gauge Monitor using the JMX Compiler UI or using API.

Using JMX Compiler UI

To add a Gauge Monitor entry using JMX Compiler, please follow the steps given below:

Select Project -> Settings option. In the Settings Tree Structure, select JMX Standard Services -> Monitors -> Gauge. This displays the dialog for the Gauge Monitor on the right side.
Select the Add option. This displays the Entry Parameters for the Gauge Monitor. The Gauge Attributes defined in the MIB is listed in the Gauge Attributes Tree on the left side.
Enter the following details:

Attribute : Select the Attribute that has to be monitored from the attributes listed in the attribute tree. Only those attributes in the MIB that are of type "Gauge32 and Unsigned32" will be displayed in the tree.
High threshold value : Specify the high comparison value with derived gauge to send notification.
Low threshold value : Specify the low comparison value with derived gauge to send notification.
High Notification : Select this option to send notification, if the attribute value crosses the Maximum value specified.
Low Notification : Select this option to send notification, if the low threshold is crossed.
Difference Mode : Select this option to specify derived gauge value calculation type, i.e., difference between two observations or not.
Granularity Period (milliseconds) : Specify the time interval taken for monitoring the attribute. The default time interval is 1000 milliseconds.

Click OK to add the entry to the table.

Example: Let us assume we want to monitor an MBean attribute "adiskUsed" defined in a sample MIB with default value of 2500. The maximum used capacity of the disk should not exceed 4000 and the minimum capacity used must not fall less than 500.

In this example, the Observed Attribute is adiskUsed, the attribute value is 2500, the maximum value is 4000 and the minimum value is 500, the granularity period is 5 seconds. The attribute is monitored every five seconds.

If the option High Notification is selected, the Monitor service sends a notification , when the adiskUsed value exceeds 4000. If the option Low Notification is selected, the Monitor service sends a notification, when the adiskUsed value falls below 500.

Using API

A Gauge Monitor can also be created by adding the relevant code directly in the generated main file inside registerJMXServices method. The following code snippet creates a Gauge Monitor with the values as specified in the above example. The start() method is used to start the gauge monitor service.

import javax.management.monitor.GaugeMonitor;

GaugeMonitor gm_0 = new GaugeMonitor();
name = "Services:type=GaugeMonitor_0";
gm_0.setObservedObject(new ObjectName("SAMPLE_MIB:type=allscalars"));
gm_0.setObservedAttribute(adiskused);
gm_0.setGranularityPeriod(5000);
gm_0.setDifferenceMode(true);
gm_0.setNotifyHigh(true);
gm_0.setNotifyLow(true);
gm_0.setThresholds (new Integer(4000), new Integer(500));
server.registerMBean(gm_0, new ObjectName(name));

server.addNotificationListener(new ObjectName(name),notifImpl,notifImpl,(new Object())
gm_0.start();

18.4 String Monitor

The String Monitor observes an attribute of type String. The string monitor performs a full string comparison between the observed attribute and its match string. A string monitor sends notifications both when the string matches and when it differs at the observation time.

Note: Notification will be sent to all registered Notification listeners , when the monitors observed attribute value matches or differs with the given "string to compare" value. The Notification Listeners for the notification must be specified.

Creating a String Monitor MBean

You can create a String Monitor using the JMX Compiler UI or using API.

Using JMX Compiler UI

To add a String Monitor entry using JMX Compiler, please follow the steps given below:

Select Project -> Settings option. In the Settings Tree Structure, select JMX Standard Services -> Monitors -> String. This displays the dialog for the String Monitor on the right side.
Select the Add option. This displays the Entry Parameters for the String Monitor. The String Attributes defined in the MIB are listed in the String Attributes Tree on the left side.
Enter the following details:

Attribute : Select the Attribute that has to be monitored from the attributes listed in the attribute tree. Only those attributes in the MIB that are of type "String", will be displayed in the tree.
String to Compare : The String Monitor Service is configured with a value for the string called string-to-compare. Specify the String whose value is to be compared with the Attribute value.
Notification difference : Selecting this option sends a notification, whenever there is a difference between the Attribute value and the String that is being compared by the String Monitor.
Notification Matching : Selecting this option sends a notification, if the Attribute value matches with the String to compare.
Granularity period : Specify the Time interval for observing the attribute value. The default time interval is 1000 milliseconds.

Click OK to add the entry to the table.

Example: Let us assume, that we want to monitor the scalar attribute agentDescr of AGENT-SAMPLE-MIB, which has a default value AgentDescr.

In this example, the Observed Attribute is agentDescr, the attribute value is snmp-agent, the String to Compare is jmx-agent, the granularity period is 5 seconds.

If the option Notification difference is selected, the Monitor service sends a notification , when the attribute value differs from the comparable string jmx-agent.

If the option Notification Matching is selected, the Monitor service sends a notification, when the attribute value is the same as the compared value jmx-agent.

The attribute is monitored every five seconds.

Using API

A String Monitor can also be created by adding the relevant code directly in the generated main file inside registerJMXServices method. The following code snippet creates a String Monitor with the values as specified in the above example. The start() method is used to start the string monitor service.

import javax.management.monitor.StringMonitor;

StringMonitor sm_0 = new StringMonitor();
name = "Services:type=StringMonitor,name=StringMonitor_0";
sm_0.setObservedObject(new ObjectName("AdventNetJMXAgent:type=GroupV2NodeInstrument"));
sm_0.setObservedAttribute("OctetString");
sm_0.setGranularityPeriod(5000);
sm_0.setStringToCompare("jmx-agent");
sm_0.setNotifyDiffer(true);
sm_0.setNotifyMatch(false);
server.registerMBean(sm_0, new ObjectName(name));
server.addNotificationListener(new ObjectName(name),notifImpl,notifImpl,(new Object()));

sm_0.start();

18.5 Table Monitor

AdventNet provides a new feature called "Table Monitor" to monitor table column values at intervals specified by the granularity period. The Table Monitor observes an attribute of type Integer or floating point types. The Monitoring can be done only for the column level and not the row level. Notifications will be emitted, if there is a change in any of the rows of the column, for which monitor is set.

Creating Table Monitor MBean

You can create a Table Monitor MBean using the JMX Compiler UI or using API.

Using JMX Compiler UI

To add a Table Monitor entry using JMX Compiler, please follow the steps given below:

Select Project -> Settings option. In the Settings Tree Structure, select JMX Standard Services -> Monitors -> Table. This displays the dialog for the Table Monitor on the right side.
Select the Add option. This displays the Entry Parameters for the Table Monitor. All the Table Nodes defined in the MIB are listed on the left side.
Enter the following details:

Attribute : Select the Attribute that has to be monitored from the Table Nodes listed in the tree.
High Threshold: Specify the high comparison value with derived gauge to send notification.
Low Threshold : Specify the low comparison value with derived gauge to send notification.
Granularity period : Specify the Time interval for observing the attribute value. The default time interval is 1000 milliseconds.

Click OK to add the entry to the table.

Using API

A Table Monitor can also be created by adding the relevant code directly in the generated main file inside registerJMXServices method. The following code snippet creates a Table Monitor for monitoring the table column "ADiskCapacity" of the AdiskTable. The attribute is monitored every 5 seconds. The start() method is used to start the Table monitor service.

import com.adventnet.services.monitor.TableMonitor;

TableMonitor tm_0 = new TableMonitor();
name = "Services:type=TableMonitor,name=TableMonitor_0";
tm_0.setObservedObject(new ObjectName("AdventNetJMXAgent:type=AdiskTableExt"));
tm_0.setObservedAttribute("AdiskCapacity");
tm_0.setObservedColumn("AdiskEntry","Integer ");
tm_0.setGranularityPeriod(5000);
tm_0.setThresholds(new Integer (10),new Integer (0));
server.registerMBean(tm_0, new ObjectName(name));
server.addNotificationListener(new ObjectName(name),notifImpl,notifImpl,(new Object()));
tm_0.start();

18.6 Monitor Notification

Monitor notifications contain the following,

notification Type
name of the observed MBean
name of the observed attribute
notification time-stamp
notification message

Using this information, listeners know which MBean triggered an event, and they do not need to access the MBean before taking the appropriate action.

18.7 Running the Example

Please refer to the Monitor Example present in the <Agent Toolkit Home>/example/jmx/monitor directory. This is a simple example to illustrate the usage of illustrate the usage of Monitor MBeans. It uses the String Monitor MBean for monitoring the attribute of a Standard MBean.

The Readme.html file explains the usage of the example and the steps involved in running the example .