Java Management Interface, coming in 5.2 RC1

Credit Where It's Due

This blog post would not have been possible without the diligent and thoughtful assistance of Stéphane Lacoin. Stephain gave me the big clues on how to configure the current Nuxeo 5.2 "head" to make all the JMX stuff "turn on" and also personally tracked down and squashed a number of bugs that made this article possible (including one in JBoss!). Somebody, please give that man a croissant!

Not Quite in 5.2.0.m4

This blog post is about a feature that did not quite make it into the 4th milestone release of Nuxeo 5.2. It is in the current source code build (or you can get it from the nightly snapshots) but I thought those that are waiting for the release candidate release might be interested to see what's "coming down the pike." As of the time of this writing, it is expected to be in the 5.2 RC1 release.

JMX: The Java Management Extensions

The Java Management Extensions or JMX debuted with Java 1.5. These extensions allow an client application to manage and monitor a collection of devices, computers, and services. A simple example might be a three-tiered web application, deployed on three separate servers. One would like to all the feedback for monitoring sent to a single place, often called the management client, where a human can look at the incoming data or the management client itself can process the data with some type of analysis procedure. The data from a three-tiered web application would include data from all the software layers such as database, application server, and application itself, but might also include reports from the network connecting the layers, and some type of hardware monitoring daemons as well. Once this has been analyzed, by a human, computer, or both, then one may want to take some time of actions to manage the objects being monitored; in the example of the three-tiered application one can easily a imagine a scenario where you would want to begin an orderly shutdown procedure. Coordinating all the layers of software, on different machines, to do this gracefully is clearly a management problem!

Configuring Nuxeo

You need to install one extra bundle into your build of Nuxeo 5.2 to get this to work, the bundle is nuxeo-runtime-management. You should put the bundle in <nuxeo-install-dir>/server/default/deploy/nuxeo.ear/plugins. Nuxeo is smart enough to "pick up" this additional modules and its features the next time you fire it up just because it is present. So, go ahead and restart (or start) your server with the script bin/run.sh (or run.cmd for windows).

Connecting JConsole to the running Nuxeo

With Nuxeo now running and exposing its management interfaces you need to hook up a JMX client to see what's going inside the Nuxeo system. You can do this with the program "jconsole" that is supplied with the Java development kit (at least if you got your JDK fairly recently). When you fire it up, you'll need to enter these three values:

The first one is the tricky one, obviously! The hostname of the machine running nuxeo in this example is "localhost" and the nuxeo server, at the time of this writing, exposes its java management interface on port 2009. Normally, the nuxeo server does not require a username and password, the second and third values, since the management service is "turned off" by default and you have to turn it on by installing bundles.

Getting information about the system state

Once you have connected, you will see the set of mbeans (management beans) that are exposed by Nuxeo:

When you drill down into a category you can get statistics about the objects in that category. In the previous screenshot, for example, if you click on the "metric" you will get information about the number of http sessions that have been created and destroyed while the nuxeo server is running. Also shown in the previous screen shot is the "probe" mbean. This mbean does a probe of the repository periodically (about every 30 seconds) and keeps track of the successes and failures. Here's what you would see if you drilled down into that item:

So, from this display you can see that the probe has been run 25 times without failures and the last probe took 111 milliseconds.

Running Methods

You can not only see data with the JMX interface to Nuxeo, but you can execute management functions as well. For example in the previous screen shot, if you click on the "Operations" button you will be presented with a list of methods that you can execute from the management interface. One of these is "disable" that you can use to turn off the probe behavior. When you run a method via the management interface, normally you get a message like this:

More fun, though, is to map the Nuxeo Runtime's inventory with the RuntimeInventory's factory object. You can click on that object (shown in the upper left) of the probe screenshots under category "nx" then category "Runtime" inventory. You will have your choice of a number of methods on that screen that give information about your system, but the most interesting one is "bindTree". The result of clicking this button to invoke that method is shown in this screenshot:

This takes all the bundles and components that the runtime knows about and makes them available via the JMX interface, so you can get some statistics about them, although in many cases this is quite minimal. You can, of course, unbind that tree of objects with "unbindTree" as shown in the screenshot above.

Getting audited isn't all bad...

Athough it's getting perilously close to tax day for our friends in the United States (tax days come in September in France), we are going to bring up the subject of auditing anyway. Many of the actions that users peform when using Nuxeo are audited (assuming you have deployed the auditing bundle) and some summary statistics can be seen via the JMX interface. The following screen shot gives you a feeling for what types of actions can be seen via the NXAuditService category:

The JMX interfaces are a nice way to interact with enterprise software systems like Nuxeo and not only keep an eye on how they are running but also perform many basic management functions. This is going to be a standard feature of Nuxeo starting with the 5.2 GA release and you can expect that we will gradually be exposing more functionality through JMX is we go forward.

If you have questions or comments about Nuxeo and JMX, or this article, drop me a note at ismith [at] nuxeo [point] com. We would especially love to hear from folks who have specific needs for functions to be exposed by Nuxeo through the management interface.