/ 
jmx4perl-0.15_3
River stage one • 1 direct dependent • 1 total dependent
/ JMX::Jmx4Perl

NAME

JMX::Jmx4Perl - Access to JMX via Perl

SYNOPSIS

Simple:

use strict;
use JMX::Jmx4Perl;
use JMX::Jmx4Perl::Alias;   # Import certains aliases for MBeans

print "Memory Used: ",
       JMX::Jmx4Perl
           ->new(url => "http://localhost:808get0/j4p-agent")
           ->get_attribute(MEMORY_HEAP_USED);

Advanced:

use strict;
use JMX::Jmx4Perl;
use JMX::Jmx4Perl::Request;   # Type constants are exported here

my $jmx = new JMX::Jmx4Perl(url => "http://localhost:8080/j4p-agent",
                            product => "jboss");
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>, product => <id>, ....)

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.

If you provide a product id via the named parameter product you can given jmx4perl a hint which server you are using. By default, this module uses autodetection to guess the kind of server you are talking to. You need to provide this argument only if you use jmx4perl's alias feature and if you want to speed up things (autodetection can be quite slow since this requires several JMX request to detect product specific MBean attributes).

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($alias)
$value = $jmx->get_attribute(ALIAS)       # Literal alias as defined in
                                          # JMX::Jmx4Perl::Alias
$value = $jmx->get_attribute({ domain => <domain>, 
                               properties => { <key> => value }, 
                               attribute => <attribute>, 
                               path => <path> })
$value = $jmx->get_attribute({ alias => <alias>, 
                               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.

Alternatively, you can provide an alias, which gets resolved to its real name by so called product handler. Several product handlers are provided out of the box. If you have specified a product id during construction of this object, the associated handler is selected. Otherwise, autodetection is used to guess the product. Note, that autodetection is potentially slow since it involves several JMX calls to the server. If you call with a single, scalar value, this argument is taken as alias (without any path). If you want to use aliases together with a path, you need to use the second form with a hash ref for providing the (named) arguments.

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

($object,$attribute,$path) = $self->resolve_attribute_alias($alias)

Resolve an alias for an attibute. This is done by querying registered product handlers for resolving an alias. This method will croak if a handler could be found but not such alias is known by jmx4perl.

If the product was not set during construction, the first call to this method will try to autodetect the server. If it cannot determine the proper server it will throw an exception.

Returns the object, attribute, path triple which can be used for requesting the server or undef if the handler can not resolve this aliase

$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. See also JMX::Jmx4Perl::Agent::Protocol for a more detailed discussion of inner pathes.

$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