Skip to end of metadata
Go to start of metadata

Plugin Development Center

Topics marked with * relate to HQ Enterprise-only features.

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.

Feedback is welcome. Click Add Comment at the bottom of the page.

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:

  • 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

When writing a resource plugin, it is important to take into account the HQ inventory model and its relationship to the structure of a plugin.  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.)
  • 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.
  • 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:

  • ...

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>/bundles/agent-x.y.z/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

Plugin Examples

back to top

Related Information
Return to Development Resources.
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.