I’m happy to announce the new jmx4perl release 0.70 with a lot of new features. The most exciting new stuff are configuration files and multi-checks for check_jmx4perl, a new Java client library and the start of a readline based JMX shell j4psh with syntax highlighting and command line completion.

The Jmx4Perl summer update

It took some time (and nerves), but finally jmx4perl is now available at version 0.70 with quite some new features. Although the jump in the version number is quite minor, this is probably the release with the largest feature delta to its predecessor.

check_jmx4perl

The documentation for check_jmx4perl has been largely extended. It contains now about 30 pages including a quick start style tutorial, background information and reference documentation.

In addition to the traditional way of specifying the check parameters via command line options, checks can now be defined in the configuration files, too. A configuration file is divided into two parts: A section for defining server connection parameters and a section for check configurations. A sample config file looks like:

# Define server connection parameters
 <Server tomcat>
    Url = http://localhost:8080/j4p
 </Server>

 # A simple heap memory check with a critical threshold of
 # 90% of the maximum heap memory.
 <Check memory_heap>
   Value = java.lang:type=Memory/HeapMemoryUsage/used
   Base = java.lang:type=Memory/HeapMemoryUsage/max
   Label = Heap-Memory: %.2r% used (%.2v %u / %.2b %u)
   Critical = 90
 </Check>

This configuration file then can be used by check_jmx4perl:

check_jmx4perl --config path/to/config --server tomcat --check memory_heap

Advanced features tunable with the configuration syntax are:

• Checks can inherit from parent checks via the Use directive
• Parameterized checks. Positional placeholders like $0 are filled in from inherited checks or command line arguments.
• Check parameters can take default values
• Multiple checks can be combined with <MultiCheck> by referencing already defined checks. A multi-check uses only a single server turnaround for fetching the values.
• A set of prefedefined checks comes with this release (threads.cfg, memory.cfg, tomcat.cfg, jetty.cfg)

Java client library

Starting with 0.70, a Java client library has been added for accessing the j4p-Agent. It provides an easy to use, typeless semantics and supports bulk requests. The usages is fairly easy:

J4pClient j4pClient = new J4pClient("http://localhost:8080/j4p");
  J4pReadRequest request = new J4pReadRequest("java.lang:type=Memory","HeapMemoryUsage");
  J4pReadResponse response = j4pClient.execute(request);
  long usedMemory = Long.parseLong(response.getValue().get("used"));

Currently, reading and writing attributes and execution of operations is supported. List and search operations are scheduled for the next release. Note also, that the API is somewhat in flux, so consider this release in beta state for the moment.

j4psh

In the same spirit as osgish (my litte OSGi shell) j4psh provides interactive access to remote MBeans which are exposed with via the j4p-agent. It is the perfect tool for exploring the JMX namespace and accessing attributes or executing operations interactively.

j4psh provides:

• GNU Readline support with history saved accross sessions
• Context sensitive command line completion
• Emacs key bindings ;-)
• Consistent syntax highlighting (switchable) with color theme support
• Listing of MBeans, reading and writing of attributes, execution of operations

Here’s a first screenshot, a screencast will follow:

Security enhancements

Since quite some time jmx4perl knows about policy files (j4p-access.xml) for enabling fine granular security. The syntax of this configuration has been extended in order to allow wildcards (*) for attribute and operation names as well as separate <allow> and <deny> sections for overwriting default behaviour.

Example:

<restrict>
   <!-- For each command type missing in a given <commands> section,
           for certain MBeans (which might be a pattern, too)
           a command be allowed. Note that an <allow> entry e.g.
           for reading an attribute of an certain MBean has no influence if reading
           is enabled globally anyway -->
   <allow>
     <!-- Allow access to the j4p configuration operations, which are needed
              for proper check_jmx4perl operation -->
     <mbean>
       <name>jmx4perl:type=Config</name>
       <operation>*</operation>
       <attribute>*</attribute>
     </mbean>
   </allow>

   <!-- MBean access can be restricted by a <deny> section
            for commands enabled in a <commands> section
            (or when the <commands> section is missing completely
            in which case all commands are allowed)
   -->
   <deny>
     <mbean>
       <!-- Exposes user/password of data source, so we forbid this one always -->
       <name>com.mchange.v2.c3p0:type=PooledDataSource*</name>
       <attribute>properties</attribute>
     </mbean>
   </deny>
 </restrict>

Minor fixes and enhancements

Finally, some minor bug fixes and enhancements has been included, too:

• check_jmx4perl: Added --value as a shortcut for –mbean/–attribute/–value
• Path elements containing ‘/’ can now be escaped with ‘\/’
• j4p-osgi-bundle including pax-web-bundle so only a single bundle is needed for deploying (when no OSGi HttpService is installed)
• Relaxed version requirements on core and compendium OSGi classes for j4p-osgi bundle.
• Added logging (level info) for printing out which security policy is used during startup
• Switched from JUnit to TestNG for testing because of support for testing groups
• New servlet init parameter option ‘mbeanQualifier’ to allow multiple j4p-servlet in a single application server

I hope you have much fun with this release, any feedback is highly appreciated (as always).