Writing a RHQ plugin Part 1

Red Hat and Hyperic released Project RHQ in the open in February. Meanwhile we released the first GA version of RHQ together with JBossON 2.0 at JavaOne 2008.

This post and the next few will try to show how to write your own plugins for RHQ.
As an example scenario the plugin will try to reach a http server, see if the base URL is available and return the status code + the time it took to reach it.

General architecture of RHQ

Before we go into detailed plugin writing, I first want to show the general architecture of RHQ and its plugin system.

RHQ follows a hub and spoke approach: A central server (or cluster) processes data coming in from agents. The data is stored in a database connected to the server. Users / admin can look at the data and trigger operations through a web-based GUI on the server



Agents do not have a fixed functionality, but can be extended through plugins which we will see below. Usually there is one agent running per machine with resources to manage. The RHQ server itself is able to run an agent embedded in the server. This is mostly for demo and test scenarios, but it is well able to monitor the server machine.

Server services

The server hosts a number of services like

• It has a view on the complete Inventory


• It processes incoming measurement data


• It triggers alerts to be sent


• It triggers operations on managed resources


• It hosts the graphical user interface


• It hosts the user management


• ...

Some of those services are reflected in the agent like inventory syncing, gathering of measurement data or running operations on a managed resource, while alert processing or hosting of the GUI is purely on the server.

Agent architecture

The agent is sort of a container that hosts some common functionality like the communication interface with the server, logging, starting and stopping of plugins or reading configuration files. In addition to this, it hosts plugin containers, who host the actual plugins. When you write a plugin, you talk to the plugin container.



The agent is in addition to the plugin containers also hosting common service like the communication with the RHQ server, logging or the handling of the command line and interactive command prompt.

Central functionality: Inventory

The central functionality of RHQ is the inventory. Each resource that you want to manage or monitor must be present in that inventory. RHQ has mechanisms to autodetect and also manually add resources. We'll come back to that later when we are talking about implementing plugins.

Each org.rhq.core.domain.resource.Resource has a certain org.rhq.core.domain.resource.ResourceCategory:

• Platform: This is basically a host where things run on


• Server: Things like database server, JBossAS instance or the RHQ agent


• Service: (Fine grained) Services offered by a server

The ResourceCategory is sort of hierarchic as you can see on the next image:



A platform hosts servers, a server can host other servers and services and a service can host other services. In theory it is also possible that a platform is hosting other platforms.
As an example: you have a Red Hat Linux platform, which hosts the RHQ Agent and JBossAS as a server. This AS it self is hosting a Tomcat server. Both JBossAS and Tomcat themselves are hosting services like JMS or Connectors.
So at the end this will result in a tree of resources with the Linux platform as its root.

In addition to the category each Resource also is of a certain org.rhq.core.domain.resource.ResourceType. For a platform this might e.g. "Max OS X", "Red Hat Linux", "Debian Linux" etc. Or the JBossAS and Tomcat from above are both of category Server, but have different ResourceType.

The RHQ wiki has an overview of the inventory db schema.

Ok, that's it for now. As a homework, check out the documentation at the RHQ wiki and the source code from the RHQ svn

Greg Hinkle also put a high level overview of the plugin system online.

Joseph Marques has written an article about things to consider before writing a plugin and will soon write a second part of it (actually it is already online).

---

Part 2
Part 3
Part 4
Part 5

Technorati Tags:
RHQ, Java, JBoss