Jmx4Perl
========
INTRODUCTION
Jmx4Perl provides an alternate way for accessing Java JEE Server
management interfaces which are based on JMX (Java Management
Extensions). It is an agent based approach, where a small Java
Webapplication deployed on the application server provides an
HTTP/JSON based access to JMX MBeans registered within the
application server.
HOW IT WORKS
For the agent mode a small Java Agent WAR (web archive) needs to be
deployed on the Java application server. This agent is provided by
the Jolokia project (www.jolokia.org). There is no need to add any
startup parameters to the application server and to open any
additional ports. All communication takes places via HTTP where JSON
objects are exchanged. Additionally, the agent benefits from the
security infrastructure in place which every application server
provides for web application. More information about the agent can
be found at http://www.jolokia.org
The Perl module JMX::Jmx4Perl accesses the deployed agent servlet
and transform the request's results from JSON into a simple Perl
object.
TOOLS
This distribution comes with several tools, which uses the
JMX::Jmx4Perl for accessing the server:
jmx4perl - Command line tool for gathering JMX information
check_jmx4perl - Full featured Nagios Plugin
j4psh - Interactive, readline based JMX shell with context
sensitive command completion
jolokia - Utility for downloading and managing Jolokia
agents.
INSTALLATION
The Perl part installs as any other module via Module::Build, which
you need to have installed. Using
perl Build.PL
./Build installdeps # If there are dependencies missing and you
# have Module::Build >= 0.36 installed.
./Build
./Build test
./Build install
will install the modules. It is highly recommended to install the
recommended dependent modules, too to get the full jmx4perl
power. The set of 'required' modules is kept small and guarantees
only that 'jmx4perl' and the modules around JMX::Jmx4Perl are
working properly. The other tools (check_jmx4perl, j4psh and
jolokia) require the recommended modules for proper working. Look
into Build.PL for which tool requires which module.
In order to download the Jolokia WAR agent into the local directory
as jolokia.war, use the following command
jolokia
This agent "jolokia.war" needs to be deployed on the JEE Server to
monitor. Please consult http://www.jolokia.org/agent.html for more
information how to install the agent. E.g. for Tomcat this war file
needs to be copied into the webapps directory.
To test it, you can use 'jmx4perl' with the URL of the deployed
agent:
jmx4perl http://<jeeserver>:<port>/jolokia
Consult 'man jmx4perl' for more information about this command
utility.
RESOURCES
* Jmx4perl's source is hosted on github.com. You can clone the
repository with git://github.com/rhuss/jmx4perl.git as URL
* Interesting articles around Jmx4Perl, JMX and Nagios can be found
at http://labs.consol.de Checkout the various post categories for
selecting a specific topic.
* www.jmx4perl.org is the canonical entry point for jmx4perl related
information.
NOTE
For you convenience, the latest Module::Build is included in this
distribution, so there is no need of a locally install Module::Build
for installing this suite. More information about Module::Build can
be found http://search.cpan.org/~dagolden/Module-Build/
LICENSE
Copyright (C) 2009-2011 Roland Huss (roland@cpan.org)
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 this module (or
Nagios, JMX or JEE in general), you might want to have a look at
http://www.consol.com/nagios-monitoring . Contact
roland.huss@consol.de for further information (or use the contact
form at http://www.consol.com/contact/ )
ACKNOWLEDGMENTS
Big thanks go to ...
* Gerhard Lausser, who initially pushed me to think harder
about a better way for monitoring JEE Servers with Nagios.
* Danijel Tasov for patching, patching, patching and keeping
an eye on contemporary perl styling.
* All bug reporters and blog commenters for helping me to
increase the overall quality (and for letting me know that
this is not software for the ivory tower)
BUGS
Please report any bugs and/or feature requests at
http://rt.cpan.org/Public/Bug/Report.html?Queue=jmx4perl
AUTHOR
roland@cpan.org