/ 
jmx4perl-1.01
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 MBean aliases 

print "Memory Used: ",
       JMX::Jmx4Perl
           ->new(url => "http://localhost:8080/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. Jmx4Perl is based on a Jolokia agent (www.jolokia.org), which needs to deployed on the target platform. It plays the role of a proxy, which on one side communicates with the MBeanServer within in the application server and transfers JMX related information via HTTP and JSON to the client (i.e. this module). Please refer to JMX::Jmx4Perl::Manual for installation instructions for how to deploy the Jolokia agent.

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 proprietary 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. If you absolutely require JSR 160 communication (e.g. because a agent can not be deployed on the target for some reason), you can still use Jmx4Perl operating with the so called proxy mode.

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 and 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>, ....)

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.

Options can be given via key value pairs (or via a hash). Recognized options are:

server

You can provide a server name which is looked up in a configuration file. The configuration file's name can be given via config_file (see below) or, by default, .j4p in the users home directory is used.

config_file

Path to a configuration file to use

config

A JMX::Jmx4Perl::Config object which is used for configuraton. Use this is you already read in the configuration on your own.

product

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

timeout

Timeout in seconds for an HTTP request

method

Default HTTP method to use for requests which can be overridden for each specific request

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

$value => $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 canonical 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.

Additionally you can use a pattern and/or an array ref for attributes to combine multiple reads into a single request. With an array ref as attribute argument, all the given attributes are queried. If $attribute is undef all attributes on the MBean are queried.

If you provide a pattern as described for the "search"" in " method, a search will be performed on the server side, an for all MBeans found which carry the given attribute(s), their value will be returned. Attributes which doesn't apply to an MBean are ignored.

Note, that the path feature is not available when using MBean patterns or multiple values.

Depending on the arguments, this method return value has a different format:

Single MBean, single attribute

The return value is the result of the serverside read operation. It will throw an exception (die), if an error occurs on the server side, e.g. when the name couldn't be found.

Example:

$val = $jmx->get_attribute("java.lang:type=Memory","HeapMemoryUsage");
print Dumper($val);

{
  committed => 174530560,
  init => 134217728,
  max => "1580007424",
  used => 35029320
}
Single MBean, multiple attributes

In this case, this method returns a map with the attribute name as keys and the attribute values as map values. It will die if not a single attribute could be fetched, otherwise unknown attributes are ignored.

$val = $jmx->get_attribute(
    "java.lang:type=Memory",
    ["HeapMemoryUsage","NonHeapMemoryUsage"]
);
print Dumper($val);

{
  HeapMemoryUsage => {
    committed => 174530560,
    init => 134217728,
    max => "1580007424",
    used => 37444832
  },
  NonHeapMemoryUsage => {
    committed => 87552000,
    init => 24317952,
    max => 218103808,
    used => 50510976
  }
}
MBean pattern, one or more attributes
$val = $jmx->get_attribute(
    "java.lang:type=*",
    ["HeapMemoryUsage","NonHeapMemoryUsage"]
);
print Dumper($val);

{
  "java.lang:type=Memory" => {
    HeapMemoryUsage => {
      committed => 174530560,
      init => 134217728,
      max => "1580007424",
      used => 38868584
    },
    NonHeapMemoryUsage => {
      committed => 87552000,
      init => 24317952,
      max => 218103808,
      used => 50514304
    }
  }
}

The return value is a map with the matching MBean names as keys and as value another map, with attribute names keys and attribute value values. If not a singel MBean matches or not a single attribute can be found on the matching MBeans this method dies. This format is the same whether you are using a single attribute or an array ref of attribute names.

Please don't overuse pattern matching (i.e. don't use patterns like "*:*" except you really want to) since this could easily blow up your Java application. The return value is generated completely in memory. E.g if you want to retrieve all attributes for Weblogic with

$jmx->get_attribute("*:*",undef);

you will load more than 200 MB in to the Heap. Probably not something you want to do. So please be nice to your appserver and use a more restrictive pattern.

$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 names (as string). 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.

If you are calling an overloaded JMX operation (i.e. operations with the same name but a different argument signature), the operation name must include the signature as well. This is be done by adding the parameter types comma separated within parentheses:

...
operation => "overloadedMethod(java.lang.String,int)"
...

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->version()

This method return the version of the agent as well as the j4p protocol version. The agent's version is a regular program version and corresponds to jmx4perl's version from which the agent has been taken. The protocol version is an integer number which indicates the version of the protocol specification.

The return value is a hash with the keys agent and protocol

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

This method throws an exception if an error occurs.

($domain,$attributes) = $jmx->parse_name($name)

Parse an object name into its domain and attribute part. If successful, $domain contains the domain part of the objectname, and $attribtutes is a hahsref to the attributes of the name with the attribute names as keys and the attribute's values as values. This method returns undef when the name could not be parsed. Result of a search() operation can be savely feed into this method to get to the subparts of the name. JMX quoting is taken into account properly, too.

Example:

my ($domain,$attrs) = 
    $jmx->parse_name("java.lang:name=Code Cache,type=MemoryPool");
print $domain,"\n",Dumper($attrs);

java.lang
{
  name => "Code Cache",
  type => "MemoryPool"
}
$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