|
|
| |
JMX::Jmx4Perl(3) |
User Contributed Perl Documentation |
JMX::Jmx4Perl(3) |
JMX::Jmx4Perl - JMX access for Perl
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();
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.
- $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.
- $agents = JMX::Jmx4Perl->discover_agents($timeout)
- Discover agents by sending a multicast request on which Jolokia agents are
listening. The optional $timeout can be used to
tune how long to wait for discovery answers (in seconds). By default 1
seconds is waited. This functionality requires IO::Socket::Multicast to be
installed.
This methods returns an array ref, which looks like
[
{
'version' => '1.2.0-SNAPSHOT',
'server_version' => '7.0.50',
'server_product' => 'tomcat',
'secured' => 0,
'url' => 'http://10.9.11.2:8778/jolokia/',
'server_vendor' => 'Apache',
'confidence' => 100,
'type' => 'response'
}
]
Please refer to Jolokia's reference documentation for the
meaning of the keys. The most important part it
"url" which points to the agent's URL
which can be used to construct a new JMX::Jmx4Perl object.
- ($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
paths.
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.
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.
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/)
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |