The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
jmx4perl-0.21
River stage one • 1 direct dependent • 1 total dependent
4 ++
/ 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")
              ->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",
                               product => "jboss");
   my $request = new JMX::Jmx4Perl::Request(type => READ,
                                            mbean => "java.lang:type=Memory",
                                            attribute => "HeapMemoryUsage",
                                            path => "used");
   my $response = $jmx->request($request);
   print "Memory used: ",$response->value(),"\n";

   # Get general server information
   print "Server Info: ",$jmx->info();

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 (< 100k) 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.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.

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. It will throw an exception (die), if an error occurs on the server side, like when the name couldn't be found.

$resp = $jmx->set_attribute(...)
  $new_value = $jmx->set_attribute($mbean,$attribute,$value,$path)
  $new_value = $jmx->set_attribute($alias,$value)
  $new_value = $jmx->set_attribute(ALIAS,$value)  # Literal alias as defined in
                                                  # JMX::Jmx4Perl::Alias
  $new_value = $jmx->set_attribute({ domain => <domain>, 
                                     properties => { <key> => value }, 
                                     attribute => <attribute>, 
                                     value => <value>,
                                     path => <path> })
  $new_value = $jmx->set_attribute({ alias => <alias>, 
                                     value => <value>,
                                     path => <path })

Method for writing an attribute. It has the same signature as "get_attribute" except that it takes an additional parameter value for setting the value. It returns the old value of the attribute (or the object pointed to by an inner path).

As for get_attribute you can use a path to specify an inner part of a more complex data structure. The value is tried to set on the inner object which is pointed to by the given path.

Please note that only basic data types can be set this way. I.e you can set only values of the following types

java.lang.String
java.lang.Boolean
java.lang.Integer
$info = $jmx->info($verbose)

Get a textual description of the server as returned by a product specific handler (see JMX::Jmx4Perl::Product::BaseHandler). It uses the autodetection facility if no product is given explicitely during construction.

If $verbose is true, print even more information

$mbean_list = $jmx->search($mbean_pattern)

Search for MBean based on a pattern and return a reference to the list of found MBeans. If no MBean can be found, undef is returned. For example,

 $jmx->search("*:j2eeType=J2EEServer,*")

searches all MBeans whose name are matching this pattern, which are according to JSR77 all application servers in all available domains.

$ret = $jmx->execute(...)
  $ret = $jmx->execute($mbean,$operation,$arg1,$arg2,...)
  $ret = $jmx->execute(ALIAS,$arg1,$arg2,...)

  $value = $jmx->execute({ domain => <domain>, 
                           properties => { <key> => value }, 
                           operation => <operation>, 
                           arguments => [ <arg1>, <arg2>, ... ] })
  $value = $jmx->execute({ alias => <alias>, 
                           arguments => [ <arg1,<arg2>, .... ]})

Execute a JMX operation with the given arguments. If used in the second form, with an alias as first argument, it is recommended to use the constant as exported by JMX::Jmx4Perl::Alias, otherwise it is guessed, whether the first string value is an alias or a MBean name. To be sure, use the variant with an hashref as argument.

This method will croak, if something fails during execution of this operation or when the MBean/Operation combination could not be found.

The return value of this method is the return value of the JMX operation.

$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.

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

Resolve an alias for an attibute or operation. 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.

For an attribute, this method returns the object, attribute, path triple which can be used for requesting the server or undef if the handler can not handle this alias.

For an operation, the MBean, method name and the (optional) path, which should be applied to the return value, is returned or undef if the handler cannot handle this alias.

A handler can decide to handle the fetching of the alias value directly. In this case, this metod returns the code reference which needs to be executed with the handler as argument (see "delegate_to_handler") below.

$do_support = $self->supports_alias($alias)

Test for checking whether a handler supports a certain alias.

$response = $self->delegate_to_handler($coderef,@args)

Execute a subroutine with the current handler as argument and returns the return value of this subroutine. This method is used in conjunction with resolve_alias to allow handler a more sophisticated way to access the MBeanServer. The method specified by $coderef must return a JMX::Jmx4Perl::Response as answer.

The subroutine is supposed to handle reading and writing of attributes and execution of operations. Optional additional parameters are given to the subref as additional arguments.

$product = $self->product()

For supported application servers, this methods returns product handler which is an object of type JMX::Jmx4Perl::Product::BaseHandler.

This product is either detected automatically or provided during construction time.

The most interesting methods on this object are id(), name() and version()

$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 and the optional path will be taken from the provided response object and not fetched again from the server.

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