The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
jmx4perl-0.35_2
River stage one • 1 direct dependent • 1 total dependent
/ JMX::Jmx4Perl::Manual

NAME

JMX::Jmx4Perl::Manual - Manual for jmx4perl

DESCRIPTION

JMX (Java Management Extensions) is the standard management solution in the Java world. Since JDK 1.5 it is available in every Java Virtual Machine and especially JEE application servers use this technology intensively for exposing managable entities. In fact, the popular JEE Server JBoss 4 is based on a JMX kernel.

For the Perl world, it's not that easy to access JMX MBeans. MBeans are is the Java term for JMX managed entities. The existing solutions are mostly based on the Java standard JSR-160 (http://jcp.org/en/jsr/detail?id=160), which defines how JMX can be accessed remotely. The problem of JSR-160 with respect to Perl is, that the default communication protocols rely on exchanging serialized Java objects. Hence they require to start a Java Virtual Machine, in the one way or other. This has quite some implications concerning installation requirements (you need a Java virtual machine with the proper version installed) and performance (firing up a JVM is not something you get for free)

The ultimate goal of jmx4perl is to bridge both worlds in the most simplest way. This is done with an agent based approach as described below. In short, the building blocks of this bridge are based on standards well known and used in both worlds: HTTP and JSON.

Another goal is to provide an abstraction for accessing certain, commonly known MBeans for various supported JEE application server, which differ in naming from brand to brand. For now, the JEE servers supported are JBoss 4 & 5, Oracle WebLogic 9 & 10, Websphere 6 & 7, Glassfish 2, Jonas 4 and Geronimo 2 as well as the pure servlet containers Jetty 5 and 6, Tomcat 4, 5 & 6. Other platforms might work as well, however they are not yet tested. Please let me know, whether jmx4perl works for you on other servers as well (which is highly likely due to the simplistic nature of the agent webapp). jmx4perl is not an academic exercise. In fact it originates from the need to let Nagios (a hopefully well known open source monitoring solution, see http://www.nagios.org) access JEE appliation servers in a painless way. You can find a nagios check in the scripts directory, which is a prefactored check directly usable in a Nagios setup.

Additionally, there is a command line tool called (incidentally ;-) jmx4perl which allows for simple access to JMX MBeans and much more features.

MBean Features

JMX is a complex specification, which can not be completely revealed in this short documentation. Refer to http://java.sun.com/docs/books/tutorial/jmx/index.html for a JMX tutorial. But in short, one can distinguish between three kinds of operational modes:

Attribute reading and writing

An MBean can have one or more attributes, which can be read and/or written.

Execution of operations

A MBean can expose certain operations, which can be executed via JMX calls.

Notifications

Listeners can register to get notified for certain notifications by the MBeans. This is not yet supported by jmx4perl and it is technically quite challenging, since HTTP, our transport protocol, is a typical request-response based protocol which is unidirectional by nature. However, there are already ideas how to overcome this limitation, but please don't hold your breath. This is on the roadmap, but with very low priority only. Tell me your use case if you want to push it up.

In short, jmx4perl supports only reading of attributes for the moment. In most cases this is sufficient for monitoring purposes, i.e. Nagios monitoring.

AGENT APPROACH

As mentioned above we are using an agent based approach. An agent based approach requires you to install a small Java Webapplication within your JEE application server. It registers itself locally to the JMX MBeanServer, and listens to HTTP requests whose results are translated into a JSON representation. This reponse can be easily picked up by a Perl module, JMX::Jmx4Perl in our case. This kind of approach differs from the canonical approach as suggested by the JMX specification itself quite a bit. It only works for application servers, where Java web applications can be deployed. Otherwise, it has also quite some advantages:

Advantages

  • No special startup options for the JEE server are required for exposing JMX informations as it would be the case for exporting JMX via JSR-160 connectors.

  • No Java installation required on the client for using the agent

  • No overhead with regard to startup times of a JVM

  • Since the agent is a standard Java Webapplication it can be secured by standard JEE means like any other Webapplication.

  • Firewall friendly since all HTTP communication goes over a single port.

Disadvantages

  • Only applicable for JEE server or servlet container, where a WAR (Java Web Archive) can be deployed.

  • For now, only reading of MBean attributes is supported. However, support for writing of attributes and execution of operations are underway. Notifications are bit more involved, but chances are good that some sort of support will be incorporated into a future version as well.

INSTALLATION

The Perl part installs as any other module via Module::Build, which you need to have installed. Using

perl Build.PL
./Build
./Build test
./Build install

will install the modules. If you have Java and "ant" (a Java build tool) installed, the Java agent will be compiled and packaged as well. However, this is not required. A precompiled j4p.war can be found in the agent directory.

For the module to work, you need to deploy j4p.war to the JEE Server to monitor. The concrete steps depend on the specific way for deploying on the target server, which in most cases is as simple as copying the agent into a specific directory. Please consult the documentation of your Java application server for the details (look for "deployment" and "web application" (or "war)))

To test it, you can use jmx4perl with the URL of the depolyed agent:

jmx4perl http://jeeserver:port/j4p

Consult jmx4perl for further details.

FEATURES

Reading and Writing Attributes

Jmx4Perl knows how to read any attribute and how to write to certain attributes for whose types are string-to-object conversions are known. Currently, writing of attributes of type String, int, long and boolean is supported. As a special features, Jmx4Perl has the notion of an inner path which is a XPath like expression for pointing into the object returned by a read or write operation.

Execution of JMX operations

It is easy to execute JMX operations, even with arguments. However, they same restriction for the argument types apply as for writing attributes: There must be an easy way to deserialize an argument from a string representation. The same types as for writing attributes are supported.

Autodetection and Product Support

Jmx4Perl is able to autodectect various application servers. This is done by querying a certain MBean attribute which is unique for this specific product. The following application servers can be autodetected:

All these application servers has been tested to work with jmx4perl. The testing environment is a 64bit Ubuntu 9.04 installation, running in a virtual machine. However, this should not make any difference for another platform, so I'm pretty confident that the application servers from the list above will work with jmx4perl on any OS. Please open a bug at http://rt.cpan.org/Public/Bug/Report.html?Queue=jmx4perl if you encounter any problems.

Please note, that autodetection is not for free with respect to performance. It takes some considerable time to probe various servers. So, if you have the chance to provide the application server type in advance, you should do this. Said this, please note this is only relevant if you are going to use the aliasing feature.

Aliasing

JMX::Jmx4Perl::Alias provides a thin abstraction layer about over the JMX naming scheme so that you can use a single alias value to access the combination (MBean name,attribute) or (MBean name,operation). It also maps the differing naming schemes of different application server to unique names, as far as this is possible. E.g. the alias SERVER_VERSION maps on JBoss to the attribute VersionNumber of MBean jboss.system:type=Server, whereas for Jetty it's mapped to MBean org.mortbay:jetty=default, Attribute version.

Remember, you can always use the the native JMX naming to access your MBeans without worrying about aliasing at all.

History Tracking

The agent j4p can be switched into a history tracking mode, where it records the values for read, write and exec operations (the return value for the late mode). You have to call a certain, jmx4perl specific, MBean to turn it on. If switched on, each request contains an additional history entry containing the list of historical values along with their timestamps. The history is stored in a list with fixed length so that the oldes value gets removed from the list in case of an overflow.

A full functional Nagios plugin called check_jmx4perl is provided in the scripts directory. It can be used to monitor any JMX Mbean's attribute with a numeric value. Thresholds for warning and critical values can be provided in the formas as defined by Nagios::Plugin. You can use autodetection and aliasing here as well. check_jmx4perl can use relative critical and warning thresholds which refer to some base value taken from another MBean's attribute. An incremental mode can be used to measure the growth rate of certain value (like number of threads). Finally, it can monitor the return value of some JMX operations as well. Please refer to check_jmx4perl for a detailed documentation.

WHAT'S NEXT ?

There are several entry points for jmx4perl. The easiest is to start to play around with jmx4perl. This is a complete command lines for exploring the MBeans on your JEE Server.

If you want to use the Nagios Plugin check_jmx4perl start reading its documentation. A Nagios cookbook is on the roadmap. If you want to restrict access to you JMX MBeanServer read the next chapter in this manual which describes a way to build a custom agent containing a policy file.

Next, JMX::Jmx4Perl is the entry module. Use it, if you need programmatical access to JMX. Don't forget to have a look into the examples directory which contains some usage examples for JMX::Jmx4Perl

Of course, you are free to access the agent servlet directly without the usage of the provided module. Even in Java ;-) A description of the request and response format can be found in the protocol description JMX::Jmx4Perl::Agent::Protocol.

ACCESS POLICY

The deployed agent servlet is quite mighty in the default distribution as you can perform any operation exposed by a MBean via JMX. Of course, you should secure the agent via standard mechanism (e.g via Basic Authentication) to allow only access to certain users. But even then, you might not want your monitoring guys to access the heart of the JEE Server. Therefore, you can restrict access to certain MBeans only by using a so called policy file. You have to rebuild the agent if you want to use this feature, though. To do this, here's the recipe:

  1. Change into the directory agent. There you will find a template policy file called j4p-access.xml.template

  2. Copy this template to j4p-access.xml (all within the agent directory).

  3. Edit j4p-access.xml to your needs. In the section commands you can restrict the request types, only those present here are allowed to be called. If the complete commands section is missing, no restriction on a request type is in effect. In the mbeans part you can provide MBeans by name and the allowed attributes and operations. If this section is present, only the MBeans listed can be accessed with the attributes and operations listed. Access to an attribute can be restricted further by giving a mode="read" attribute to the attribute tag in which case the attribute can be accessed read-only.

  4. Call ant. Ah, yes, you need ant installed (http://ant.apache.org). To be on the save side do an ant clean before calling ant without argument.

  5. Deploy the j4p.war which was created in Step 4.

A typical workflow looks like

$ cd agent/
$ cp j4p-access.xml.template j4p-access.xml
$ vi j4p-access.xml
$ ant clean
$ ant
$ jar tvf j4p.war
     0 Thu Jul 30 10:42:24 CEST 2009 META-INF/
    95 Thu Jul 30 10:42:22 CEST 2009 META-INF/MANIFEST.MF
     0 Thu Jul 30 10:42:24 CEST 2009 WEB-INF/
  1872 Tue Jul 28 09:09:32 CEST 2009 WEB-INF/web.xml
     0 Thu Jul 30 10:42:24 CEST 2009 WEB-INF/lib/
 16046 Wed Jul 01 22:26:42 CEST 2009 WEB-INF/lib/json_simple-1.1.jar
 85124 Thu Jul 30 10:42:22 CEST 2009 WEB-INF/lib/j4p-agent.jar
     0 Thu Jul 30 10:42:24 CEST 2009 WEB-INF/classes/j4p-access.xml
$ cp j4p.war $DEPLOYMENT_DIR/

FURTHER DIRECTIONS

As an supplement to the provided agent based approach, the more traditional way of using a JVM for remote communication would be a nice additional option. With help of modules like Java::Import this should fit nicely in the provided API.

Maybe support notifications.

Readline support for jmx4perl would be cool, too.

Any other suggestions ?

LICENSE

Copyright (C) 2009 Roland Huss

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. You can either apply the GPL or obtain a commercial license for closed source development. Please contact roland@cpan.org for further information.

PROFESSIONAL SERVICES

Just in case you need professional support for jmx4perl (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