Writing a RHQ plugin Part 5

Welcome back

As promised in the last part, I will talk a little bit more about the Facets of a plugin. But before we come to this, I want to show you how to detect physical processes on a machine via process scans. And last but least, I'm gonna talk a little bit about the skeleton plugin -- basically a plugin template that you can use to write your own plugins.

Using Process scans for discovery

Often when you want to discover resources, they are not virtual like the remote http servers in our examples, but processes on the local machine. The RHQ agent offers through its SIGAR library to query the process table in order to detect those resources. As you may have guessed, this involves the plugin descriptor, so lets have a look at this first before going to the discovery component

Process-scans in the plugin descriptor

As you have seen in part 2, each of platform/server/service can have <proces-scan> elements. The element itself is empty, but has two required attributes: name and query. Name just names this specific scan method. Query is the intersting part. It is a string written in PIQL (Process Info Query Language), which is documented in the JavaDoc to its class. I don't want to go into detail here and just show two queries. Visit the page just mentioned to learn more.

Query 1: find a JBossAS

process|basename|match=^java.*,arg|org.jboss.Main|match=.*

We want to query for a process, whose name is starting with java and which has an argument of org.jboss.Main -- a JBoss Server. The matching entry from ps is:

hrupp     2035   0.0 -1.5   724712  30616  p7  S+    9:49PM   0:01.61 java
 -Dprogram.name=run.sh -Xms128m -Xmx512m -Dsun.rmi.dgc.client.gcInterval=3600000
 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djboss.platform.mbeanserver
 -Djava.endorsed.dirs=/devel/jboss-4.0.5.GA/lib/endorsed
 -classpath /devel/jboss-4.0.5.GA/bin/run.jar:/lib/tools.jar
 org.jboss.Main -c minimal

Query 2: find a process by its pid

Here the program id is stored in a file in a well known place

process|pidfile|match=/etc/product/lock.pid

PIQL will take the pid from /etc/product/lock.pid and search for a process with that id

Discovery component revisited

Ok, now that we have seen what we can do with the <process-scan> in the plugin descriptor, lets see how we can process that info. And .. as you may have alreay expected this is again very simple:

   List<ProcessScanResult> autoDiscoveryResults = 
      context.getAutoDiscoveredProcesses();
   for (ProcessScanResult result : autoDiscoveryResults) {
       ProcessInfo procInfo = result.getProcessInfo();
       ....
       // as before
       DiscoveredResourceDetails detail = 
          new DiscoveredResourceDetails(
              resourceType, key, name, null,
              description, childConfig, procInfo
          );
       result.add(detail);
   }

So basically you jut need to obtain the list of resources discovered by process scan (autodiscovered as opposed to a manual add) and create the DiscoveredResourceDetails as before. You can use ProcessInfo to get more information about the process and to even decide not to include it in the list of autodiscovered resources (imagine, the PIQL query would have looked for processes where the name starts with post. This would apply to postgres and postmaster. Here you could still filter the ones you really want.

A few more Facets

We have seen the MeasurementFacet in the previous articles. In this section I will briefly mention the other kinds of facets, so that you can get an idea what plugins are capable to do.

ConfigurationFacet

This facet indicats that the plugin is able to read and write the configuration of a managed resource. It goes hand in hand with <resource-configuration> in the plugin descriptor.

OperationFacet

An operation allows you to invoke functionality on the managed resource. This could be a restart operation or whatever you want to invoke on a target. Operations are described in <operation> elements in the plugin descriptor. They can have argument and return values.

ContentFacet

This facet allows the uploading content like files or archives into the managed resource. That way it is possible to centrally manage software distribution into managed resources. There exists a <content> element as counterpart.

The skeleton plugin

The skeleton plugin is a stub to get you started writing a plugin. So instead of copying an existing project like we did in the first place, you can take the skeleton, rename a few things on it and start with writing the plugin. It comes with a plugin descriptor that is filled with comments and also skeletons for the class files.
It is not yet complete, but expect it to be downloadable within the next few days. And if you are all nice to my colleague Jason, he will write a little installer for it, so a few of he manual steps can just be skipped :)

Plugin community

The RHQ wiki now hosts a plugin community page that shows available plugins:
RHQ Plugin Community.
Check it out for any updates about plugin related information - including lists of new plugins.

The end

Ok, that's it. I hope you have enjoyed the posts in the series. I am looking to forward to see you using RHQ and writing great plugins for it.

Please provide feedback - here or at the RHQ forums.

And join us in #rhq on irc.freenode.net

---

Part 1
Part 2
Part 3
Part 4