Command-line JMX Management with jManage

Although JConsole and VisualVM offer freely available and highly useful JMX clients, there are some features of jManage that make it worth using in conjunction with these other JMX clients.

Two of jManage's features that are particularly useful are the interfaces it exposes for managing and monitoring JMX-enabled applications. jManage provides a web interface that can be useful in situations where the managing and monitoring client needs to access server-side JMX support behind a firewall. This same advantage can be achieved with an HTML Adapter or with with the JMX Web Services Connector, but the Adapter is not a standard JSR 160 connector and the JSR-160-compliant Web Services Connector is not yet finalized.

The following screen snapshot shows what the jManage web interface looks like.



For this blog entry, I want to focus on the second interface mechanism that jManage provides for managing and monitoring JMX-enabled applications. The command-line interface (CLI) that jManage provides can be used to run scripts or to run jManage interactively. In this blog entry, I'll focus on running jManage's command-line interface (CLI) interactively.

For the brief examples I demonstrate in this blog entry, I will be using the server-side code from my previous blog entry on JMX Querying to run jManage against.

If you have not set up jManage before, there are only a few steps to follow to get it up and running. I summarize the steps here, but you should reference the JManage Installation wiki page for complete details. The steps you must follow to start using jManage include:

1. Set JAVA_HOME appropriately. Mine is currently set to C:\Program Files\Java\jdk1.6.0_07 for these examples.

2. Unzip/unjar the contents of the downloaded jManage file (such as jmanage-2.0-RC1.zip in my case) into an installation directory (C:\jmanage-2.0-RC1 in my case).

3. Go to the "bin" directory of your jManage directory with the newly unjarred/unzipped contents of the jManage download and run the appropriate (for your operating system) "keygen" command. When prompted for the password (password for "admin"), I just used the default "123456" (no quotes) for this example.

4. From the same "bin" subdirectory in your jManage installation, run the appropriate (for your operating system) "startup" command. You will need to provide the password you specified in step #3.

5. In a web browser, navigate to http://localhost:9090/ if running the web browser from the same machine as jManage or else replace localhost with the name of the machine on which jManage is running.

6. At this point, you'll have a typical web form login page. Enter "admin" for the "Username" and the password you created in step #3 for "Password." Once you have authenticated you can browse this web application. For now, though, I will do just enough to use the command-line interface. The step necessary for this is to create the jManage application and associate it with my application exposing a JSR-160 compliant connector.

7. The following screen snapshot shows the fields that need to be set up for a JSR-160 JMX connection. I got to this screen by choosing to create a new jManage application and then selecting JSR-160 as the type of the application.



8. When step #7 has been accomplished, jManage's web page will list the associated applications as shown in the next screen snapshot.



Rather than using the web browser to manage our applications, we can use the jManage command-line interface to manage and monitor our JMX-friendly application. While we could write and run a script file with the jManage command-line tool, I'll focus on using the command-line tool interactively.

It is simple to start the interactive jManage command-line tool. Assuming the default password setting for admin, it is simply a matter of running the command "jmanage -username admin -password 123456". Because no script file was specified, the command-line tool will run interactively as evidenced in the next screen snapshot by the jmanage> prompt.



The above screen snapshot not only demonstrates running of the jManage command-line tool, but also demonstrates how the "help" command displays usage information and the "apps" command displays applications jManage is managing. In this case, there are three applications: jManage itself, an Oracle database connection, and the JMX Querying Example.

From the usage information printed out for the "help" request, we see that we can run several different and interesting management commands. In the next screen snapshot, I demonstrate using the "mbeans" command to see the MBeans associated with the "JMX Querying Example" application. This screen snapshot also demonstrates a very important point. You cannot specify single values with spaces by surrounding them with quotes. Instead, you must use the tilde character (~) in place of any spaces. So, the request for the MBeans for the JMX Querying Example was actually expressed as "mbeans JMX~Querying~Example". This displays the MBeans associated with this application that we would see when using similar queries with JConsole.



If I wish to find metadata about one of the MBeans returned from the "mbeans" command, I can use the "info" command as demonstrated in the next screen snapshot. As the snapshot indicates, I use the command "info JMX~Querying~Example/dustin:type=complex,name=One". The returned output is metadata information about that particular MBean, including the ObjectName, the underlying class, a description, the attributes, and the available operations.



I can use the "execute" command of the jManage CLI to execute an operation. This is demonstrated in the next screen snapshot where I use the command "execute JMX~Querying~Example/dustin:type=complex,name=One/retrieveStatusString" and get that result: "Successful".



The "help" usage information supplies other commands that can be run from the jManage CLI as well. Also, additional information can be retrieved for each command by running that command without arguments. The command's usage will then be displayed.

I mostly use JConsole and VisualVM for my JMX client needs. However, jManage provides significant advantages such as firewall friendliness via its web browser interface and script-friendliness via its command-line interface. In this blog entry, I've attempted to demonstrate how easy it is to apply jManage to manage JMX-enabled applications supporting a JSR-160 compliant connector. I did not demonstrate the use of a script with jManage and I also did not demonstrate many of jManage's other features, including its JFreeChart-based and customizable dashboards.