Measurement Plugins

Available in HQ Open Source unless marked by * for HQ Enterprise only

Measurement plugins implement HQ's monitoring function. They are one of the most common plugins, both for standard plugins and custom. They allow HQ to for identify resources and collect metrics for them. The main (and sometimes sole) task when writing a custom plugin is to write an XML descriptor file.

• Writing the XML descriptor
• Using the MeasurementPlugin helper class
• Defining measurements with the <metric> tag
• Using Templates to collect metric data
• Getting your plugin to auto-discover resources

If you have any comments or suggestions for this help page, please submit them at the bottom of the page by clicking Add Comment.

Writing the XML Descriptor

Each plugin requires an XML descriptor that specifies the type of plugin and, in this case, the resources to look for and the metrics to collect from them. The rest of this page describes the major elements that you need to include in that file.

Consult the Plugin XML Descriptor page to learn about the structure and syntax of this file and generally how to construct one for your plugin.

back to top

Using the MeasurementPlugin Support Class

When writing a measurement plugin, you always identify it as such. The exact syntax depends on the plugin implementation:

<plugin type="measurement" class="org.hyperic.hq.product.MeasurementPlugin"/>

<plugin type="measurement" class="org.hyperic.hq.product.jmx.MxMeasurementPlugin"/>

<plugin type="measurement" class="org.hyperic.hq.product.SNMPMeasurementPlugin"/>

This invokes the HQ "support class" MeasurementPlugin, which defines metrics and implements a single method: getValue(), which it uses to collect configured metrics. The method of collecting metrics is left entirely to the plugin.

Support classes are provided to assist with certain collection methods such as SNMP, URL, JDBC, Windows Perflib Data and SIGAR. Following are some examples of collection methods used by various plugins:

• JMX - JBoss, WebLogic, WebSphere, Tomcat, Resin
• SNMP - Apache, iPlanet/SunONE, Apple Airport
• JDBC - Mysql, PostgreSQL, Oracle, Sybase
• Windows Perflib - .NET, Exchange, Terminal Services, IIS
• SIGAR - System, Server process metrics (NTP, Mysql, VMware, etc)
• Vendor API - Citrix Metaframe, DB2, WebSphere 4.x, SilverStream, VMware

Learn more about support classes.

back to top

Defining Measurements with the <metric> Tag

The sine qua non of Measurement plugins is the collection of metrics. In the XML descriptor, you define the collection of a metric (a "measurement," if you will) using the <metric> tag.

You Must Always Collect the Availability Metric The Availability metric indicates whether a Resource is up or down. A metrics-gathering plugin must determine Availability for every server and every service it monitors. A single plugin will likely gather Availability for multiple Resources. If Availability is not gathered for a Resource, HQ will consider the Resource to be unavailable, and will not show any metrics for it in the Portal. A plugin sets the value of Availability to 1 if the Resource is up, and 0 if it is down.  These values are displayed in the Portal as "available" or "not available". Verifying the existence of a Resource's process is a common technique for determining its Availability. However, the method a plugin uses to determine Availability can vary depending on the Resource Type and the plugin developer's judgment. There might be alternative techniques for determining the Availability of a Resource. For instance, a plugin might determine the Availability of a web server based on whether its process is up, its port is listening, it is responsive to a request, or by some combination of these conditions.

The following explains each each metric attribute, most of which, in fact, are intended for use by th eServer to control display of the metric data.

Example of a simple metric tag:

<metric name="Availability"
            category="AVAILABILITY"
            units="percentage"
            indicator="true"
            collectionType="dynamic"/>

Example of a more complicated one:

<metric name="Availability" 
            alias="Availability" 
            template="sigar:Type=ProcState,Arg=%process.query%:State" 
            category="AVAILABILITY" 
            indicator="true" 
            units="percentage" 
            collectionType="dynamic"/>

back to top

Using Templates to Collect Metric Data

A "template" is a unique string containing all the information required to collect a particular data point. Basically, it tells the plugin how to collect the metric data. Oftentimes this involves invoking another, HQ-provided plugin that knows exactly how to fetch data or how to execute code. Templates are often indirectly assigned to a metric by way of a filter.

The measurement template uses an extended form of a JMX ObjectName:

domain:properties:attribute:connection-properties

jboss.system:Type=ServerInfo:FreeMemory:naming.url=%naming.url%

where:

• domain = jboss.system
• properties = Type=ServerInfo
• attribute = FreeMemory
• connection-properties = naming.url=%naming.url%

This is the extension to the JMX ObjectName format. Arbitrary properties generally used to connect to the managed server. In this example, JBoss JMX requires a JNP URL (specified here as a variable, indicated by "%": %naming.url%). The variable is given a value by the MeasurementPlugin.translate method, using the inventory property value for this server instance.

Using Support Classes to Simplify Metric Collection

In a template, the domain can be used to invoke an HQ-provided support class for handling common sources of metrics, such as Process Information, scripts, SQL Queries, and Network Services. (Specific domain names are "registered" with these support classes.) You can see this use of templates in many of the plugin examples.

A template needs to be written in a way that the underlying support class is expecting: the order and kinds of values being passed to it.

In script plugins, the exec domain, in the Script support class, is common. It is invoked with the arguments file (the file to execute) and possibly timeout (to make the timeout value explicit, instead of the default value, for easier troubleshooting) and exec (to specify permissions). For example:

template=exec:timeout=10,file=pdk/work/scripts/sendmail/hq-sendmail-stat,exec=sudo:${alias}

There is also a large class of "protocol checkers" that you can use in a template for easy collection of protocol metrics, for example, for HTTP or SMTP. You can use a protocol checker for any of the platform services that are defined in HQ; all of these platform services are listed on the "New Service" screen (where you add a new platform service to the HQ inventory), in Service Type. Furthermore, you can find all the arguments you can pass to these protocol checkers on the "Resource Configuration" screen; they are the configuration properties listed in bold type. For all of the protocol checkers, the hostname is passed in; for TCP, the port number can be, but is optional. For example:

template=SMTP:hostname=host.example.com,port=25

Using a Filter to Efficiently Apply a Template to Metrics

A filter with variables can be used to easily "macro-ize" templates. The alias variable is particularly useful. For example:

<filter name="template" value="jboss.system:Type=ServerInfo:${alias}:naming.url=%naming.url%"/>

<metric name="Free Memory"
        indicator="true"
        units="B"/>

<metric name="Used Memory"
        indicator="true"
        units="B"/>

Using Variables In plugin XML descriptors, variables are indicated by "%" on either side of the variable name (for example, %process.query%). The variables are assigned the value that was most recently determined. The value of the variable must be determined before the variable is used.

The variable alias, when the filter is applied to each metric, takes on the value of the metric's alias. Neither metrics have an explicit alias value, so it is taken from the metric's name: "FreeMemory" and "UsedMemory". So, the previous code expands to:

<metric name="Free Memory"
        alias="FreeMemory"
        template="jboss.system:Type=ServerInfo:FreeMemory:naming.url=%naming.url%"
        indicator="true"
        units="B"/>

<metric name="Used Memory"
        alias="UsedMemory"
        template="jboss.system:Type=ServerInfo:UsedMemory:naming.url=%naming.url%"
        indicator="true"
        units="B"/>

Learn more about filter tags.

back to top

Getting Your Plugin to Auto-Discover Resources

HQ has already defined an autoinventory plugin for several collection methods, and for the most part, all you need to do in your own plugin is call it.

To auto-discover a server:

• Add this one line within the <server> tag:

  <plugin type="autoinventory" class="org.hyperic.hq.product.jmx.MxServerDetector"/>

  The class name varies by type of plugin. That class is for a JMX plugin. For a script plugin:

  <plugin type="autoinventory" class="org.hyperic.hq.product.DaemonDetector"/>

To auto-discover services on a server:

1. Add one more line that tells the plugin that the server hosts services and please discover them, too:

   <property name="HAS_BUILTIN_SERVICES" value="true"/>

2. For each hosted service enumerated in the plugin, within the <service> tag, you again call the autoinventory plugin, but without a class argument.

   <plugin type="autoinventory"/>

Return to the Plugin Development Center.