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.
- What do plugins do? An overview
- Technical overview
- How do I write a plugin?
- Testing your plugin
- Deploying your plugin
- Plugin Examples
Feedback is welcome. Click Add Comment at the bottom of the page.
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.
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.
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. (Learn more about monitoring and measuring resource behavior.) 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.)
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.
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:
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 .)||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|
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.
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)
Make sure the plugin can indeed collect the metrics: (runs the plugin and outputs the metric values)
Make sure the plugin can perform auto-discovery: (enables auto-discovery in addition to metric collection)
Enable debug for troubleshooting:
|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).
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.
You must deploy your custom plugin on the HQ Server and on all the Agents you want to run the plugin.
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).|
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:
- 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
- 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.
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.
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.
- qmail Plugin (combines Protocol, Process and Script)