Plugin Install Guide
 |
Read this first: Deploying Plugins - Basic HOWTO |
Plugin Deployment
Bundled plugins are deployed to both the server and agent in the following locations:
server-3.0.x/hq-engine/server/default/deploy/hq.ear/hq-plugins/ agent-3.0.x/pdk/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 when updating or adding a plugin.
Custom plugins can be added in the directories listed above or to a subdirectory 'hq-plugins' within the parent directory.
For example, if the server is installed at:
/usr/local/hyperic/server-3.0.x/
Add your custom plugins to:
/usr/local/hyperic/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 this directory exists prior to starting the server. |
If the agent is installed at:
/usr/local/hyperic/agent-3.0.x/
Add your custom plugins to:
/usr/local/hyperic/hq-plugins/
Similar on Windows, if the server is installed at:
C:\Program Files\Hyperic HQ\server-3.0.x\
Add your custom plugins to:
C:\Program Files\Hyperic HQ\hq-plugins\
If the agent is installed at:
C:\Program Files\Hyperic HQ\agent-3.0.x\
Add your custom plugins to:
C:\Program Files\Hyperic HQ\hq-plugins\
Using this approach, there is no need to copy custom plugins each time the server or agent is upgraded to a new version.
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 PDK provides a mechanism to invoke plugins outside of the server/agent from a command shell. It is possible to run metric collection, control and autodiscovery using:
java -jar hq-product.jar
The main method sets up the classpath and dispatches commands to the plugins.
Command line arguments
- -p - Product plugin name
Name of the plugin minus -plugin.jar or -plugin.xml. Example: "jboss". - -t - Resource type name
The server or service resource type name. Example: "JBoss 4.0" or "JBoss 4.0 JCA Connection Pool". - -m - The method to invoke:
- control
- metric
- discover
- track
- generate
- -a - Action, depending on which method is specified:
- control - The name of the control action, example: "stop", "start", "restart"
- metric
- getvalue - The default action, translates metric templates and invokes MeasurementPlugin.getValue displaying the results.
- translate - Translates metric templates but does not invoke getValue
- discover
- properties - Generate properties files containing the auto-discovered properties for each resource found. The files are put in ./plugin-properties with subdirectories for each resource type. The name of each property file is that of the resource name with invalid filename characters converted to '_'. The generated file also includes properties equivalent to the -p and -t switches so these files can easily be used to invoke metric or control for a specific resource.
- metric - Get metrics values using the auto-discovered properties
- track
- log - Watch for log events and print events to stdout
- config - Watch for config events and print events to stdout
- generate
- help - Generate help (if any) for each resource type, output to .html files in the ./plugin-help directory.
- metrics-txt - Generates a text formatted summary of supported metrics to stdout.
- metrics-xml - Generates an xml formatted summary of supported metrics to stdout.
- metrics-sgml - Generates an sgml formatted summary of supported metrics to stdout.
- -D - Define a config property
These properties are used to create the ConfigResponse object for use by the plugins. These are the same properties displayed on the Edit Inventory Properties page for each resource. These properties can be generated using -m discover -a properties.
Special Properties:- log - Set the log level
Example: -Dlog=debug - output.dir - Override output directory default '.'
Example: -Doutput.dir=/tmp - metric-collect - For use with metric method, only get metrics with defaultOn=true
Example: -m metric -Dmetric-collect=default - metric-indicator - For use with metric method, only get metrics with indicator=true
Example: -m metric -Dmetric-indicator=true - metric-cat - For use with metric method, only get metrics with the given category
Example: -Dmetric-cat=AVAILABILITY - metric-iter - For use with metric method, do n iterations of getValue for each metric, the time spent in millis is printed rather than the value.
Example: -m metric -Dmetric-iter=100
- log - Set the log level
Examples
Run auto-discovery for all products:
java -jar pdk/lib/hq-product.jar -m discover
Run auto-discovery for all products and save configuration to properties files in the plugin-properties directory:
java -jar pdk/lib/hq-product.jar -m discover -a properties
Run auto-discovery for a specific plugin:
java -jar pdk/lib/hq-product.jar -p jboss -m discover
Fetch metrics for a specific resource type:
java -jar pdk/lib/hq-product.jar -m metric -p jboss \ -t "JBoss 4.0 JMS Destination" \ -Djms.destination=DLQ \ -Djava.naming.naming.url=jnp://localhost:1099
Fetch metrics using auto-discovered configuration:
java -jar pdk/lib/hq-product.jar -m metric \ plugin-properties/jboss-4.0/hammer_JBoss_4.0_all.properties
Execute stop control action:
java -jar pdk/lib/hq-product.jar -m control -a stop \ plugin-properties/jboss-4.0/hammer_JBoss_4.0_all.properties
Execute start control action:
java -jar pdk/lib/hq-product.jar -m control -a start \ plugin-properties/jboss-4.0/hammer_JBoss_4.0_all.properties
Execute control action without using properties file:
java -jar pdk/lib/hq-product.jar -m control -p jboss -a removeAllMessages \ -t "JBoss 4.0 JMS Destination" \ -Djms.destination=DLQ \ -Djava.naming.naming.url=jnp://localhost:1099
Watch for log events:
java -jar pdk/lib/hq-product.jar -p apache -t "Apache 2.0" -m track -a log \ -Dserver.log_track.files=/var/log/httpd/error_log
Watch for config events:
java -jar pdk/lib/hq-product.jar -p apache -t "Apache 2.0" -m track -a config \ -Dserver.config_track.files=/etc/httpd/httpd.conf
