This page is referring to agent plugins only. This page does not provide information about server plugins.

Bottom Line

The following is a quick introduction to what it takes to write an agent plugin. Details on each point are flushed out throughout the rest of this site.

• A plugin provides the business logic that uses the core features provided by the platform.
• A plugin is packaged as a JAR file.
• A plugin contains an XML file, called the plugin descriptor, that indicates the types of resources that are handled by the plugin, along with the capabilities the plugin has with regard to what it can do to these resources.
• A plugin contains compiled code that will perform the capabilities indicated in the descriptor. Certain interfaces are implemented by this plugin code in order to allow the agent, or more specifically the plugin container running inside the agent, to make calls into it.
• A plugin is initially deployed to the server. Agents automatically download and load plugins from the server.

What is a plugin?

A plugin provides a way to integrate specific software packages (typically called "resources" in RHQ nomenclature) into the RHQ platform. The plugin provides a description of what the external software package is and what features of the RHQ platform it will utilize. The plugin also contains the code necessary to actually connect to the resource and perform the requested operations on it.

Put more simply, plugins make the RHQ platform useful for specific needs. Need to inventory and monitor a Postgres database? The Postgres plugin provides the ability. Want to see CPU and network adapter metrics? The platform plugin provides the hook into your machine to retrieve these values.

Have a need to manage a product that is not currently supported? Want to tie in your own applications and leverage all of the features of the platform? That's where the Plugin Community comes in. Open APIs provide a way for anyone to integrate a specific set of needs into the platform.

What can I do with a plugin?

For each resource type defined in a plugin, any combination of a number of core subsystems can be used to provide a customized, rich feature set for resources of that type. For more information on the set of subsystems available, visit the subsystems page.

What are the pieces that make up a plugin?

A plugin is packaged into a single JAR file. This file is present on both the server and agent. See the section on deploying for more information on how plugins are sent between the server and agent.

There are two main pieces of any plugin:

Plugin Descriptor

A plugin descriptor is a description of what the plugin provides for the platform. At it's simplest level, it defines the types of resources that are supported by the plugin. By this means, plugins are able to introduce new types into the platform, along with a detailed description of the resource type's capabilities.

The plugin descriptor is written as an XML document. In all plugins, it must be named rhq-plugin.xml and be located in the plugin's META-INF directory. The schema is provided as part of the Plugin Developer's Kit.

A plugin descriptor may define any of the following for each resource type. Keep in mind that multiple resource types may be defined per plugin.

• The types of resources that are supported by the plugin.
• The configuration properties that are used, per resource, to connect to a specific instance of that resource type.
• A definition of what metrics can be collected for each resource type.
• A set of operations that can be invoked on an inventoried resource. For instance, many resources expose the ability to start or stop the resource.
• A definition of what properties may be configured on inventoried resources.
• The relationships between resource types. Resource types may be defined as being a child of another resource type. The resulting hierarchy is used to model the resources in the scope of the plugin as well as being used in the user interface to express this hierarchy to the user.

Plugin API Implementations

In order for the RHQ agent, or more specifically the plugin container, to interact with the plugin, the plugin must implement a set of the provided plugin API classes. These implementations provide the concrete code that will be executed by the plugin container to fulfill the functionality defined in the plugin descriptor. The set of APIs that must be implemented correspond to the features exposed in the plugin descriptor. In other words, if the plugin descriptor defines metrics for a resource type, the metric APIs must be implemented to provide the necessary hook.

Plugins may also bundle in any external libraries or dependencies they need. The plugin container takes care to keep the plugin classloaders separate to prevent any conflicts in dependency versions between plugins.

Resource Type Checklist

In summary, the following tasks need to be accomplished for each resource type defined in the plugin.

Plugin Descriptor Metadata
Define the resource type in the plugin descriptor, specifying general information on the resource type such as name and description.
Specify the name of the class that will be used to discover resources of this type.
Specify the name of the class that will be used to connect to and provide hooks for any subsystems in use.
Add metadata to describe which subsystems the plugin will support for the resource type, such as indicating what properties may be used to configure the resource or what operations may be executed.

Code Implementations
Implement the class that will perform discovery of resources (the name of this class is indicated in the metadata above).
Implement the class that will connect to the resource (resource component). There will be one instantiation of this class for each resource of this type that is discovered.
Implement the required interfaces on the resource component for each subsystem indicated in use by the plugin descriptor. In other words, if the plugin descriptor indicates the resource can be configured, the configuration interface must be implemented by the resource component for this resource type.

How do I write a plugin?

The easiest way to write a plugin is to start with our skeleton plugin and add whatever else you need. The skeleton plugin will provide the necessary project structure and maven POM files to build the plugin and put the necessary files in their required locations. The skeleton plugin also provides a stubbed out plugin descriptor to get started with. See the Skeleton Plugin page for more details on how to get started using it.

How do I deploy a new plugin?

Plugin Deployment Checklist

Copy the plugin file to the plugins directory on the RHQ server
Get the agent to download the plugin by doing one of the following:

• restarting the agent
• execute the "plugins update" command in the agent console
• execute the agent's Update Plugins operation (only if you have the RHQ Agent imported in inventory)

Plugin deployment is simple. Plugins are initially deployed to the RHQ server, which is as simple as copying the packaged plugin (a JAR file) to the server's dropbox plugins directory at <server-install-dir>/plugins. This dropbox was not supported in RHQ 2.3 or earlier; for those versions, you copy the agent plugin to the directory directory:
jbossas/server/default/deploy/rhq.ear/rhq-downloads/rhq-plugins. Another alternative is to use the plugins administration page in the UI - it allows you to upload the jar file directly from your browser.

After that, it's as simple as starting the agent. At startup, the RHQ agent will contact the server and download any new or updated plugins automatically. Alternatively, plugins can be updated by going to the agent console and running the command:

plugins update

or (if you have the RHQ Agent imported into inventory) you can execute the agent operation to update plugins.