Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

5. Writing Agent Plug-ins: Procedures

5.1. Tip: Checking XSD Annotations

There are a couple of XSD files that provide elements for agent (resource) plug-ins: rhq-configuration.xsd and rhq-plugin.xsd.
A lot of different properties and attributes are defined in these schema files. All of these are annotated so that you can have a good grasp of what the existing, default schema makes available.
For example, for the subCategory attribute: 
	      <xs:attribute name="subCategory" use="optional">
         <xs:annotation>
            <xs:documentation>
               Resource types can be grouped into subcategories. A subcategory
               defines "like" resource types so they can, for example, be shown together
               in a UI group tab. You can, therefore, define multiple resource types
               and group them together by making their subCategory attributes the same.
            </xs:documentation>
         </xs:annotation>
      </xs:attribute>
Read through the annotations in the XSD files to help plan what your plug-in will do based on what's already available. This can also illuminate any specific configuration that requires custom schema.

5.2. Writing Agent Plug-ins Using a Template

The RHQ source files includes a plug-in generator. The generator goes through a series of questions that cover most of the common configuration options for agent plug-ins, such as whether monitoring is enabled and whether there is a required JMX dependency. The generator creates the basic files including the pom.xml file, rhq-plugin.xml descriptor, and all of the associated Java files for the project. The agent plug-in can then be written and built on that template framework.
  1. It is possible to build the plug-in generator from source; the files are in the rhqInstallDir/modules/helpers/pluginGen/ directory. Alternatively, the latest version can be downloaded from http://rhq-project.org/display/RHQ/Plugins+-+Plugin+Generator.
  2. Launch the generator. 
    java -jar rhq-pluginGen-version_#-jar-with-dependencies.jar
  3. Answer the questions prompted in the generator. The first pass defines the root element for the plug-in descriptor; subsequent series configure children within the plug-in. The prompts are described in Table 15, “Plug-in Generator Questions”.

    Table 15. Plug-in Generator Questions

    Prompt Parameter Description
    The plugin root category PLATFORM(P), SERVER(S), SERVICE(I) Sets the resource type of the root element in the plug-in. The value here corresponds to the <platform>, <server>, and <service>.
    Name Gives the name of the plug-in. This corresponds to the <plugin name="name" value.
    PackagePrefix Sets the name of the classes used by the plug-in. This corresponds to the package attribute in the <plugin element of the descriptor.
    This option is only given for the first plug-in element.
    FileSystemRoot
    Gives an absolute path to the location where the plug-in project directory should be created.
    This option is only given for the first plug-in element.
    ComponentClass Gives the name of the plug-in component Java file to create. This file is created with all of the required imported classes defined, based on the other functionality enabled in the generator.
    DiscoveryClass Gives the name of the discovery component Java file to create. This file is created with all of the resource discovery classes imported.
    If it should support Events Sets whether the plug-in will allow event (log) collection. If so, this options creates an <events> element in the descriptor and a corresponding *EventPoller.java file.
    Description
    ParentType Creates a parent plug-in type (<runs-inside>) element in the descriptor.
    This option is only given for the first plug-in element.
    If it should support Monitoring Sets whether the plug-in will allow monitoring. If so, this options creates a <metric> element in the descriptor.
    If it should support Operations Sets whether the plug-in will allow monitoring. If so, this options creates an <operation> element in the descriptor.
    If it should support Singleton Sets whether the plug-in is a singleton. If yes, it adds the singleton=true attribute to the resource element.
    If it should support ResourceConfiguration Sets whether this resource type has configuration properties that can be managed through the JBoss ON GUI. This corresponds to the <resource-configuration> properties in the descriptor.
    If it should support SupportFacet
    If it should support CreateChildren Sets whether children can be discovered and added to the resource inventory.
    If it should support UsesExternalJarsInPlugin Asks whether external (non-JBoss ON) JAR files are required by the plug-in. These files and classes must be imported by manually editing the plug-in files.
    If it should support DeleteChildren Sets whether children can be deleted from the resource inventory.
    If it should support ManualAddOfResourceType Sets whether children resources can be manually added to the resource's inventory.
    If it should support UsePluginLifecycleListenerApi Sets whether this plug-in will use the listener API.
    This option is only given for the first plug-in element.
    If it should support DependsOnJmxPlugin Sets whether this plug-in requires the JMX plug-in.
    This option is only given for the first plug-in element.
    RhqVersion Gives the version of the JBoss ON server and agent that this is used with.
    This option is only given for the first plug-in element.
    Do you want to add a child to testServer? Prompts whether to add a child element to the plug-in.
  4. The second part of the generator prompts for any children elements to be added within the plug-in. These will commonly be services contained within the plug-in. These have the same series of questions as in step 3.
    The generator continues prompting for children until you enter N to complete the setup.
  5. The generator creates the Maven product for the agent plug-in in the specified directory with the standard directory layout. It also creates templates for all of the required plug-in files:
    • The project pom.xml file
    • The rhq-plugin.xml descriptor file
    • nameComponent.java files for the plug-in and any children
    • nameDiscoveryComponent.java files for the discovery component for the plug-in and any children
    • nameEventPoller.java files for any element which supports events
  6. Edit the generated files to finish out the plug-in.
  7. Build an agent plug-in.
    1. Go to the top directory for the agent plug-in project.
    2. Run the Maven build command: 
      mvn install
      This command builds the plug-in into a JAR file which can be uploaded to the JBoss ON server to deploy to the agents. The JAR file is named pluginName-version.jar and is located in a target/ directory.

5.3. Validating Agent Plug-ins

If the agent plug-in was generated using the JBoss ON plug-in generator and then built with Maven, the plug-in itself can be validated using Maven. The JBoss ON/RHQ plug-in source files have a special validation class which can help ensure that the agent plug-in is valid before deploying it (and potentially harming an agent). 
mvn org.rhq:rhq-plugin-validator:rhq-plugin-validate
If the agent plug-in was not created using the JBoss ON/RHQ plug-in generator, then add a <build> element to point to the validator and a pointer to the <pluginRepositories> element to point to the Maven repository. 
<build>
   <plugins>
      <plugin>
         <groupId>org.rhq</groupId>
         <artifactId>rhq-core-plugin-validator</artifactId>
         <version>1.0.1-SNAPSHOT</version>
      </plugin>
   </plugins>
</build>
...

...
<pluginRepositories>
   <pluginRepository>
      <id>jboss</id>
      <name>JBoss Plugin Repository</name>
      <url>http://repository.jboss.org/maven2/</url>
      <snapshots>
         <enabled>false</enabled>
      </snapshots>
   </pluginRepository>
</pluginRepositories>
...

5.4. Notes on Editing Agent Plug-ins

The settings for a resource plug-in can be changed by editing the rhq-plugin.xml file and rebuilding the plug-in.

Important

Do not rename resource types when you edit the resource plug-in. This breaks backward compatibility with any resource that was inventoried using the older version of the plug-in.

5.5. Deploying Agent Plug-ins

Agent plug-in files wind up in the agentInstallDir/rhq-agent/plugins/ directory. Agent plug-ins are deployed, however, by uploading them to the JBoss ON server, and then the JBoss ON servers distribute them to the agents. As with server-side plug-ins, agent plug-ins can be deployed to a local JBoss ON server or through the JBoss ON UI.
Agent plug-ins are loaded when the agent starts. When a new agent plug-in is added, the agent needs to be restarted or a manual plug-in load operation has to be launched.

5.5.1. Remotely Deploying Agent Plug-ins

  1. In the top menu, click the Administration tab.
  2. In the Configuration box on the left navigation bar, click the Plugins link.
  3. In the Agent Plugins tab, scroll to the Upload Plugin section at the bottom of the page.
  4. Click the Add button, and browse to the plug-in JAR file's location. If there are multiple plug-ins to deploy, just hit Add again and add in each one.
  5. When all of the plug-ins to be deployed are listed in the box, click the Upload button.
  6. Tell the agent to upload the new plug-in.
    1. Search for the agent, and then select it from the search results.
    2. Open the agent resource page.
    3. In the Operations tab, select the Update Plugins operation and schedule it to run immediately.
    Agent plug-ins can also be updated by restarting the agent or by running the plugins update command in the agent command line.

5.5.2. Locally Deploying Agent Plug-ins

  1. If the agent plug-in is built or accessible on the same machine as a JBoss ON server, then the agent plug-in can be dropped into a deployment folder: 
    serverRoot/jon-server-3.1.0.GA1/jbossas/server/default/deploy/rhq.ear/rhq-downloads/rhq-plugins
    The JBoss ON server detects the new or updated plug-in and makes it available to the agents with other agent updates.
  2. Have the agent load the new plug-ins. Either restart the agent or pass a command through the agent command line to upload the new plug-in. 
    > plugins update

5.6. Removing and Re-deploying Agent Plug-ins

An agent plug-in, like a server-side plug-in, can be in one of three states:
  • Deployed and active
  • Deleted (disabled)
  • Purged
Both active and disabled plug-ins present, as JAR files, in the server and agent configuration. When a plug-in is present but disabled, it prevents any future updates of the plug-in from being deployed. Purging an agent plug-in permanently removes it from the configuration, which allows a new version of that agent plug-in to be deployed.

5.6.1. Deleting a Plug-in

  1. In the top menu, click the Administration tab.
  2. In the Configuration box on the left navigation bar, click the Agent Plugins link.
  3. Select the plug-ins to delete.
  4. Click the Delete button.
To view all of the undeployed plug-ins, click the SHOW DELETED button.

5.6.2. Purging and Re-deploying an Agent Plug-in

  1. In the top menu, click the Administration tab.
  2. In the Configuration box on the left navigation bar, click the Agent Plugins link.
  3. Click the SHOW DELETED button at the bottom of the plug-ins list.
  4. Select the checkbox by the plug-in to re-deploy, and then click the PURGE button. This removes the entry in the JBoss ON database that tells the servers to ignore that plug-in and any updates to it.
  5. Add and upload the plug-in like it is being deployed as new. This is described in Section 5.5, “Deploying Agent Plug-ins”.