Plugins Tutorials

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 if HQ dose not yet detect and manage products (or parts of products) you want it to, we encourage you to develop your own custom plugins.

Here we provide tutorials for a couple implementations of a Measurement plugin, with the hope that leading you through the construction of enough different plugins will enable you to understand the plugin gestalt and then to write your own.

Consult the Plugin Development Center for a full and detailed explanation of all things plugin.

• Tutorials by plugin type
• How plugins and the HQ inventory model play nicely together
• Every plugin needs an XML descriptor
• Troubleshooting
• Other sources of help

Tutorials by Plugin Type and Implementation

This tutorial encompasses a variety of smaller tutorials, each dedicated to a specific type of plugin.

back to top

How Plugins and the HQ Inventory Model Play Nicely Together

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.

back to top

Every Plugin Needs an XML Descriptor

For every plugin, you must write an XML descriptor. In many cases, that is all you must write, as the plugin implementation has been templatized.

Learn more about the Plugin XML Descriptor and its components.

XML Descriptor for Measurement Plugins

Auto-Discovery

Every Measurement plugin must implement its own auto-discovery (called "autoinventory" within plugins) so that, once the plugin is deployed, HQ can actually find the product for which the plugin is being written and inventory it.

In almost all cases, you will implement auto-discovery in your plugins for servers or services, not platforms.

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. 

back to top

Troubleshooting

This section describes several things you can do to figure out problems with your plugin.

• Are you having problems with the HQ Server after the plugin is deployed? Turn on DEBUG mode on the Agent.
• What user is running the Agent? It should be the same user that is running the tests of the plugin.
• Do you have the proper permissions for everything (executing scripts, accessing files, etc.)?
• Are your environment variables set up correctly?

Testing the 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

Other Sources of Help

If this tutorial leaves you with questions about how to write your plugin, you can find additional help in the following places:

• Plugin Development Center
• HQ forums
• Contact HQ Support

back to top