|<http://www.jolokia.org/agent.html>||Overview of all Jolokia agents|
|<http://www.jolokia.org/reference/html/index.html>||Reference manul which contains detailed installation instructions for various platforms.|
jmx4perl allows for simple access to JMX MBeans and much more from the command line and is a good starting point.
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 an introduction to JMX. But in short, one can distinguish three kinds of operational modes:
Attribute reading and writing An MBean can have one or more attributes, which can be read and/or written. jmx4perl knows how to read and write MBean attributes. Execution of operations A MBean can expose certain operations, which can be executed via JMX calls. With jmx4perl, JMX operations can be executed. Notifications Listeners can register to get notified for certain notifications by 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 dont 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.
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 classical approach as suggested by the JMX specification itself.
This approach works for the following environments:
Beside this restriction concerning the runtime environment, this agent based approach has also quite some advantages:
o JEE Servers where a webapplication in the standard WAR format can be deployed. o For the Mule ESB as dedicated Mule agent can be used for exposing JMX to the outside. o Within an OSGi container where the agent gets deployed as an bundle. Two variants are available: One, which requires an installed OSGi HttpService and one, which comes with an embedded HTTP server. o For every Java 6 application running with Suns (pardon, Oracles) JVM, a JVM level agent is available which uses the HTTP server embedded in every Sun Java 6 JDK.
o 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. o No Java installation required on the client for using the agent o No overhead with regard to startup times of a JVM o Since the agent is a standard Java Webapplication it can be secured by standard JEE means like any other Webapplication. o Firewall friendly since all HTTP communication goes over a single port.
o The agent can be deployed only to certain Java runtime container (Servlet container, Mule Agent, OSGi container, every Java 6 appliction). But please read on, even when your runtime environment doesnt fit in here. With the proxy approach arbitrary Java applications can be connected to.
Although the agent based is the most simplest way to access JMX, there are circumstances which prevent the deployment of a dedicated agent servlet. This kind of restrictions are mostly politically motivated. For these situations, jmx4perl provides an operational mode known as the proxy mode with which the target platform can be monitored without installing the j4p agent servlet on it. This works by using j4p.war as a JMX Proxy, which translates our JSON/HTTP protocol on the frontside to JSR-160 JMX remote requests on the backend and vice versa.
A dedicated proxy serlvet server is needed for hosting j4p.war, which supports the agent mode as well as the proxy mode. A lightweight container like Tomcat or Jetty is a perfect choice for this mode. The setup is straight forward:
Said all this, the proxy mode has some limitations:
o Install Jetty (<http://www.mortbay.org/jetty/>) or Tomcat (<http://tomcat.apache.org/>) o Deploy j4p.war from the jmx4perl distribution by copying it into the webapp directory. o Enable remote JMX commonicutaion on the target plattform. Please consult the documentation of your Appserver for further details. o Use the --target option for jmx4perl or check_jmx4perl with a JMX service URL (like service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi) in order to specify the target server. Use the proxy servers URL as the agent URL:
jmx4perl http://localhost:8080/jolokia \ --target service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi list
To summarize, the proxy mode should be used only when required. The agent servlet on its own is more powerful than the proxy mode since it eliminates an additional layer, which adds to the overall complexity and performance. Also, minor additional features like merging of MBeanServers are not available in the proxy mode.
o There is no automatic merging of JMX MBeanServers as in the case of the direct mode. Most application servers uses an own MBeanServer in addition to the PlatformMBeanServer (which is always present). Each MBean is registered only in one MBeanServer. The choice, which MBeanServer to use has to be given upfront, usually as a part of the JMX Service URL. But even then (as it is the case for JBoss 5.1) you might run into problem when selecting the proper MBeanServer. o Proxying adds an additional remote layer which causes additional problems. I.e. the complex operations like list might fail in the proxy mode because of serialization issues. E.g. for JBoss it happens that certain MBeanInfo objects requested for the list operation are not serializable. This is a bug of JBoss, but I expect similar limitations for other application servers as well. o Certain workarounds (like the JBoss can not find MXBeans before MBeanInfo has been fetched bug) works only in agent mode. o It is astonishingly hard to set up an application server for JSR-160 export. And there are even cases (combinations of JDK and AppServer Version) which dont work at all properly (e.g. JDK 1.5 and JBoss 5). For certain application servers, detailed setup instructions are published at http://labs.consol.de/tags/jsr-160/
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.
In order to download the Jolokia WAR agent into the local directory as jolokia.war, use the following command
To test it, you can use jmx4perl with the URL of the deployed agent:
Consult jmx4perl for further details.
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.
It is easy to execute JMX operations, even with arguments. However, they same restrictions 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.
Jmx4Perl is able to autodectect various application servers. This is done by querying a certain MBean attribute which is unique for this specific product. Many application servers has been tested to work with Jolokia and hence with Jmx4Perl. In fact, Jmx4Perl comes with an integrastion test suite, which is used for integration testing the Jolokia agents. 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 Im 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 described below.
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 its 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.
The agent jolokia can be switched into a history tracking mode, where it records the values for read, write and exec operations. 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 oldest value gets removed from the list in case of an overflow.
Full featured Nagios plugin CWcheck_jmx4perlA full functional Nagios plugin called check_jmx4perl is provided in the scripts directory. It can be used to monitor any JMX Mbeans attribute with a numeric value. Thresholds for warning and critical values can be provided in the formats 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 MBeans attribute. An incremental mode can be used to measure the growth rate of certain value (like number of threads). Also, it can monitor the return value of JMX operations as well. check_jmx4perl can use a configuration file with a sophisticated syntax including inheritance, parameterizatiosn and multi-check definitions.
Please refer to check_jmx4perl for a detailed documentation (which has a 30+ pages manual on its own).
There are several entry points for jmx4perl. The easiest is to start to play around with jmx4perl. This is a full featured command line tool 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 your 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 this, if you need programmatical access to JMX. Dont 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.
Another resource is the jmx4perl Blog located at <http://labs.consol.de>. It contains various post about different jmx4perl use case and best practices. Dont forget to add <http://labs.consol.de/tags/jmx4perl/feed/rss/> to your RSS Feedreader if you want to keep in touch with the latest jmx4perl evolution (there is quite something in the pipeline).
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 or Digest 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 repack the agent if you want to use this feature, though. To do this, heres the recipe (assuming the agent is stored as jolokia.war in the current directory):
1. Download a sample jolokia-access.xml to a local directory:
2. Edit jolokia-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. Via the remote section access to certain IP adresses and subnets can be restricted. 3. Repack the agent: 4. Deploy the jolokia.war which was created in Step 4.
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 firstname.lastname@example.org for further information.
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/open-source-monitoring/>. Contact email@example.com for further information (or use the contact form at <http://www.consol.com/contact/>)
|perl v5.20.3||JMX::JMX4PERL::MANUAL (3)||2016-04-03|