NAME

JMX::Jmx4Perl - Access to JMX via Perl

SYNOPSIS

   my $jmx = new JMX::Jmx4Perl(url => "http://localhost:8080/j4p-agent");
   my $request = new JMX::Jmx4Perl::Request(type => READ_ATTRIBUTE,
                                            mbean => "java.lang:type=Memory",
                                            attribute => "HeapMemoryUsage",
                                            path => "used");
   my $response = $jmx->request($request);
   print "Memory used: ",$response->value(),"\n";

DESCRIPTION

Jmx4Perl is here to connect the Java and Perl Enterprise world by providing transparent access to the Java Management Extensions (JMX) from the perl side.

It uses a traditional request-response paradigma for performing JMX operations on a remote Java Virtual machine.

There a various ways how JMX information can be transfered. For now, a single operational mode is supported. It is based on an agent, a small (~30k) Java Servlet, which needs to deployed on a Java application server. It plays the role of a proxy, which on one side communicates with the MBeans server in the application server and transfers JMX related information via HTPP and JSON to the client (i.e. this module). Please refer to JMX::Jmx4Perl::Manual for installation instructions howto deploy the agent servlet (which can be found in the distribution as agent/j4p-agent.war).

An alternative, and more 'java like' approach, is the usage of JSR 160 connectors. However, the default connectors provided by the Java Virtual Machine (JVM) since version 1.5 support only propriertary protocols which require serialized Java objects to be exchanged. This implies that a JVM needs to be started on the client side, adding quite some overhead if used from within Perl. Nevertheless, plans are underway to support this operational mode as well, which allows for monitoring of Java application which are not running in a servlet container.

For further discussion comparing both approaches, please refer to JMX::Jmx4Perl::Manual

JMX itself knows about the following operations on so called MBeans, which are specific "managed beans" designed for JMX and providing access to management functions:

• Reading an writing of attributes of an MBean (like memory usage or connected users)

• Executing of exposed operations (like triggering a garbage collection)

• Registering of notifications which are send from the application server to a listener when a certain event happens.

For now only reading of attributes are supported, but development has start to support writing of attributes and executing of JMX operations. Notification support might come (or not ;-)

METHODS

$jmx = JMX::Jmx4Perl->new(mode => <access module>, ....)

Create a new instance. The call is dispatched to an Jmx4Perl implementation by selecting an appropriate mode. For now, the only mode supported is "agent", which uses the JMX::Jmx4Perl::Agent backend. Hence, the mode can be submitted for now.

Any other named parameters are interpreted by the backend, please refer to its documentation for details (i.e. JMX::Jmx4Perl::Agent)

$resp => $jmx->get_attribute(...)

  $value = $jmx->get_attribute($mbean,$attribute,$path) 
  $value = $jmx->get_attribute({ domain => <domain>, 
                                properties => { <key> => value }, 
                                attribute => <attribute>, 
                                path => <path>)

Read a JMX attribute. In the first form, you provide the MBean name, the attribute name and an optional path as positional arguments. The second variant uses named parameters from a hashref.

The Mbean name can be specified with the canoncial name (key mbean), or with a domain name (key domain) and one or more properties (key properties or props) which contain key-value pairs in a Hashref. For more about naming of MBeans please refer to http://java.sun.com/j2se/1.5.0/docs/api/javax/management/ObjectName.html for more information about JMX naming.

This method returns the value as it is returned from the server

$value = $jmx->list($path)

Get all MBeans as registered at the specified server. A $path can be specified in order to fetchy only a subset of the information. When no path is given, the returned value has the following format

  $value = { 
              <domain> => 
              { 
                <canonical property list> => 
                { 
                    "attr" => 
                    { 
                       <atrribute name> => 
                       {
                          desc => <description of attribute>
                          type => <java type>, 
                          rw => true/false 
                       }, 
                       .... 
                    },
                    "op" => 
                    { 
                       <operation name> => 
                       { 
                         desc => <description of operation>
                         ret => <return java type>
                         args => [{ desc => <description>, name => <name>, type => <java type>}, .... ]
                       },
                       ....
                },
                .... 
              }
              .... 
           };

A complete path has the format "<domain/<property list>/("attribute"|"operation")/<index>"> (e.g. java.lang/name=Code Cache,type=MemoryPool/attribute/0). A path can be provided partially, in which case the remaining map/array is returned.

$formatted_text = $jmx->formatted_list($path)

$formatted_text = $jmx->formatted_list($resp)

Get the a formatted string representing the MBeans as returnded by list(). $path is the optional inner path for selecting only a subset of all mbean. See list() for more details. If called with a JMX::Jmx4Perl::Response object, the list will be taken from the provided response object and not fetched from the server

$resp = $jmx->request($request)

Send a request to the underlying agent and return the response. This is an abstract method which needs to be overwritten by a subclass. The argument must be of type JMX::Jmx4Perl::Request and it returns an object of type JMX::Jmx4Perl::Response.

ROADMAP

• Suport for writing attributes

• Support for executing JMX operations

• Providing aliases for common MBean Attributes, which can be used for any application server

• JSR-160 access to a remote JMX Mbean-Server, which requires integration of a JVM (with something like Java::Import)

LICENSE

This file is part of jmx4perl.

Jmx4perl is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

jmx4perl is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with jmx4perl. If not, see <http://www.gnu.org/licenses/>.

A commercial license is available as well. Please contact roland@cpan.org for further details.

PROFESSIONAL SERVICES

Just in case you need professional support for this module (or Nagios or JMX in general), you might want to have a look at http://www.consol.com/opensource/nagios/. Contact roland.huss@consol.de for further information (or use the contact form at http://www.consol.com/contact/)

AUTHOR

roland@cpan.org