Plugin Development Center

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

Plugins are the interface between Hyperic HQ and products on the network you want to manage. HQ can detect hundreds of products thanks to its standard plugins, but you can extend HQ's functionality to products (or parts of products) not yet covered by HQ by developing your own custom plugins. This page gives you an overview of plugins and points you to detailed instructions for specific plugin types.

All HQ bundled plugins are available in both the Enterprise and Open Source versions of HQ. The only difference is that, as reflected in the HQ feature list, plugins in the Enterprise version enable more management features.

For a soup-to-nuts lesson on writing your own custom plugins, please see our Plugins Tutorial.

What do plugins do? An overview
Technical overview
How do I write a plugin?
Testing your plugin
Deploying your plugin
Plugin Examples

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

What Do Plugins Do? An Overview

Proper development and functioning of HQ plugins rely on a thorough understanding of the HQ inventory model and of the four HQ functions that plugins implement:

Auto-Discovery: Plugins can implement HQ auto-discovery of servers and services (not platforms, which are discovered via the Product plugin). Custom plugins will usually just call on the existing, HQ-provided auto-inventory plugin.
Monitoring: Plugins can implement HQ monitoring, defining and collecting metrics and configuring them for display in the UI. Measurement plugins implement monitoring.
Control: Plugins can implement the HQ control feature, defining control actions used to control resources. Control plugins implement control.
Event Management

In addition, the Product Plugin provides the deployment entry point on both the Server and Agent. It defines the resource types and plugin implementations for measurement, control, and auto-discovery (auto-inventory).

You can use plugins discover, collect data from, and control resources; plugins cannot be used to change alerting, reporting, or similar, Server-side functionality.

How Plugins Use the HQ Inventory Model

One of the places where users get tripped up most often when writing plugins is not sufficiently understanding (the importance of) the HQ inventory model and its influence on the structure of plugins. A plugin should implement a hierarchy that reflects the hierarchy of the inventory model; it should not be flat. The tutorials and example plugins in the Plugin Development Center illustrate how the servers and services (and, less frequently, platforms) being targeted by the plugin are organized according to the inventory model.

For example, to discover a service, first discover its hosting server, and then discover the services running on the server. For a more specific example: SNMP has multiple network interfaces. Each of those network interfaces should be mapped to/treated as a separate service in the plugin, not all combined into one big platform.

One of the benefits of modeling a plugin after the Inventory Model is that you can then implement actions (gathering metrics, controlling, etc.) at each inventory level and there will no confusion or difficulty about which level of resource the plugin should be acting on.

What Role do the Server and Agent Play in Plugins?

Plugins must be deployed on both the Server and Agent. The Server and Agent each play different roles vis-a-vis plugins:

The Agent does the work of gathering all the data from resources and generally communicating with the resource. Using the plugin, the Agent can:

Auto-discover a resource. In the case of a server, say, the plugin can also auto-discover all the server's hosted services. (Learn more about auto-discovery.)
Gather metrics from a resource, including Response Time data. (Learn more about monitoring and measuring resource behavior and about response-time data.) See the XML descriptor syntax for defining and gathering metrics.
Control a resource. (Learn more about controlling resources.)

The Server deals in meta-data, which is to say, it knows about:

Platform, server, and service resource types and how the plugin's targeted resources map to the inventory model. See the XML descriptor syntax for specifying servers and services.
The configuration schema for each resource type (the same data you see displayed on the "Resource Configuration" screen). See the XML descriptor syntax for specifying configuring properties.
Data Display (Learn more about viewing metrics)
Resource-type-specific help text that instructs users how to set up their environment to properly run the plugin. See the XML descriptor syntax for specifying help text.
Definitions of control actions. (Learn more about controlling resources.)

back to top

Technical Overview

Hyperic HQ plugins are self-contained .jar or .xml files which are deployed on both the Server and every Agent that you want to run the plugin. Every plugin contains, at a minimum, an XML descriptor, which is either a standalone .xml file or embedded in the .jar file.

Learn more about the XML descriptor syntax.

Plugin Implementations

For the sake of discussion, we'll call measurement, control, etc. the "types" of plugins. They can be created for any kind of resource. Depending on the kind of resource and how it communicates and surfaces its data, however, you will write different "implementations" of those plugin types. The different implementations are:

Script
JMX
SQL
SNMP
...

Using Support Classes to Simplify Your Plugin

HQ provides a bunch of "support classes" (that is, plugins) that you can invoke in your own plugins to abstract and simplify its construction. HQ provides the following support classes:

Category	Support Classes	When You Would Invoke This Support Class
Scripting	qmail, Sendmail, Sybase
SNMP	Squid, Cisco IOS
JMX	JBoss, WLS, WAS, ActiveMQ, Jetty
JDBC	MySQL, PostgreSQL, Oracle	To gather database system tables metrics
Win-Perf Counters	IIS, Exchange, DS, .NET	To gather metrics from an application that surfaces perf counters
SIGAR	System, Process, Netstat	To communicate with an operating system. SIGAR is HQ's proprietary OS-independent API.
Net Protocols	HTTP, FTP, SMTP, etc. (A full list can be found on the "Add New Platform Service" screen, in Service Type.)	To communicate with platform services that HQ already has built-in, but you might want to gather additional metrics from it
Vendor	Citrix, DB2, VMware

back to top

How Do I Write a Plugin?

The interface with HQ plugins is simple. For example, the HQ-provided Measurement plugin has only one method (getValue); the Autoinventory plugin has only one method for each inventory level. The hard part of writing a plugin is figuring out:

How do you get the data out of the managed resource?
Where should this data "live" in the inventory model? At what inventory level (platform, server, or service)?

The easiest way to write your first plugin is to start with an existing plugin that does almost what you want and tweak it to fit your needs. You can start with these example plugins or with our Plugins Tutorial.

back to top

Testing Your Plugin

The PDK allows you to invoke your plugin methods from the command line for quick testing. To perform any of the following tasks (targeted mainly at measurement plugins), run the associated commands from the command line in the HQ Agent directory:

Check the syntax of the plugin: (simply initializes the plugin)

java -jar <Agent Directory>/pdk/lib/hq-product.jar -Dplugins.include=yourPluginName -m lifecycle -Dlog=debug

Make sure the plugin can indeed collect the metrics: (runs the plugin and outputs the metric values)

java -jar <Agent Directory>/pdk/lib/hq-product.jar -Dplugins.include=yourPluginName -m metric

Make sure the plugin can perform auto-discovery: (enables auto-discovery in addition to metric collection)

java -jar <Agent Directory>/pdk/lib/hq-product.jar -Dplugins.include=yourPluginName -m discover -a metric

Enable debug for troubleshooting:

java -jar <Agent Directory>/pdk/lib/hq-product.jar -Dplugins.include=yourPluginName -m discover -a metric -Dlog=debug

Passing in Config Options

When testing your plugin, you need to also pass in values (using the -D argument) for all the config options that are required to make the plugin run, for example, config options that specify credentials. For example, -Djmx.password=<password>. Otherwise you will not be able to run your plugin.

It's a Good Habit to Specify an exec.sleep Value

When running the script plugin from the command line, it is best to assign an explicit value to exec.sleep just in case the script takes longer to run than the default exec.sleep value (30 sec).

java -jar <Agent Directory>/pdk/lib/hq-product.jar -Dexec.sleep=number_of_seconds ...

This doesn't apply to plugins deployed in HQ because there the timeout variable kicks in.

Learn more about invoking plugins outside of the Server and Agent, including more testing commands.

back to top

Deploying Your Plugin

You must deploy your custom plugin on the HQ Server and on all the Agents you want to run the plugin.

Deploying the Plugin in `.xml` or `.jar` Format

You can name your plugin as you please, but the name must end with either -plugin.xml or -plugin.jar, depending on the plugin format.

Plugin Format	Description and Contents
`-plugin.jar`	A standard jar-formatted file, containing `etc/hq-plugin.xml` — the plugin's XML descriptor — and any java class files, scripts, and MIB files.
`-plugin.xml`	For plugins that consist solely of an XML descriptor. It is combined with HQ's plugin support classes (either in the hq-product.jar or other *-plugin.jar plugins). In the case of a script plugin, the script can also be included in a separate file (as opposed to embedded in the XML descriptor).

Where to Place Custom-Plugin Files

Usually you will place your custom-plugin files in a subdirectory of the Server's and Agent's parent directories. By doing this, your plugin files will persist through upgrades. The subdirectory is called hq-plugins. For example:

Non-Windows Installation

If the Server is installed at /usr/local/hyperic/<Server directory>, then add the plugin in /usr/local/hyperic/hq-plugins
If the Agent is installed at /usr/local/hyperic/<Agent directory>, then add the plugin in /usr/local/hyperic/hq-plugins

Windows Installation

If the Server is installed at C:\Program Files\Hyperic HQ\<Server directory>, then add the plugin in C:\Program Files\Hyperic HQ\hq-plugins
If the Agent is installed at C:\Program Files\Hyperic HQ\<Agent directory>, then add the plugin in C:\Program Files\Hyperic HQ\hq-plugins

hq-plugins/ must exist prior to starting the Server

Hot-deployment on the Server side using the custom hq-plugins/ directory requires that the directory exist prior to starting the Server. So, after creating /usr/local/hyperic/hq-plugins/, you must restart the Server.

Alternate File Placement
You can also place the files under the Server and Agent directories:

On the Server: <Server directory>/hq-engine/server/default/deploy/hq.ear/hq-plugins/
On the Agent: <Agent directory>/pdk/plugins/

You should do this when, for example, you are installing a patch to a plugin, or if you want to keep all your Agent-deployment files together.

Hot Deployment of Plugins

The Server supports hot-deployment: plugins can be updated or added without restarting the Server.

The Agent does not support hot-deployment: it must be restarted after a plugin is updated or added.

Invoking Plugins Outside the Server or Agent

When developing plugins, it's helpful to be able to invoke plugin methods directly for quick testing. The Invoking Plugins Standalone document describes this process.

back to top