(NOTE: The original post has been slightly edited to improve readability)
The Java Management Extensions (JMX) technology is a great way to check or change the state of variables or to invoke a method in a (remote) running application via a management GUI such as the JConsole. And Spring makes it trivial to expose any POJO as a JMX MBean with only little configuration in a few minutes. The Spring JMX documentation is very good, however there are few points that I struggled with for a while and would therefore like to record here the right solutions.
I needed to monitor a command-line java application using Spring 2.5 on an IBM JVM 1.5 running on a server. Monitoring would be performed with a jconsole on Sun JVM 1.6 as the JMX client on my PC. All the following XML snippets are from the corresponding Spring application-context.xml.
Turning a POJO into an MBean
JMX makes it possible to expose getters, setters and operations taking primitives or complex data types as parameters (though types other than a few special ones require the client to have the classes). You tell Spring to expose a POJO as an MBean as follows:
<bean id="myMBean"
class="my.package.JobPerformanceStats"
factory-method="instance" />
<bean class="org.springframework.jmx.export.MBeanExporter" lazy-init="false">
<property name="beans">
<map>
<entry key="bean:name=MyMBeanName" value-ref="myMBean"/>
</map>
</property>
</bean>
First you declare an instance of the POJO class – the myMBean (for other reasons I’ve an old-fashioned singleton and use JobPerformanceStats.instance() to access the bean). Next you declare an MBeanExporter with lazy-init=”false” and tell it about your bean. (There are also other ways to do it, including auto-discovery.) The bean will be then visible under its key, i.e. “bean:name=MyMBeanName”, which JConsole displays as “MyMBeanName”.
Notice that the MBeanExporter only works under JVM 1.5+ because it uses the new java.lang.management package. Under JDK 1.4, Spring would fail with the following errror:
java.lang.NoClassDefFoundError: javax/management/MBeanServerFactory
at org.springframework.jmx.support.MBeanServerFactoryBean.createMBeanServer
By default it will expose all public methods and attributes. You can change that in various ways, for example with the help of an interface.
If you are not running in a container that already provides an MBean server, which is my case here, you must tell Spring to start one:
<bean class="org.springframework.jmx.support.MBeanServerFactoryBean"/>
Enabling remote access
To make the MBean accessible from another machine, you must expose it to the world by declaring a ConnectorServerFactoryBean configured with an appropriate communication mechanism.
Remote access over JMXMP
By default the ConnectorServerFactoryBean exposes MBeans over the JMX Messaging Protocol (JMXMP) with the address
service:jmx:jmxmp://localhost:9875
<bean class="org.springframework.jmx.support.ConnectorServerFactoryBean" />
However this protocol isn’t supported out of the box and you must include jmxremote_optional.jar, a part of OpenDMK, on the classpath of both the MBean application and the jconsole client to avoid the following exception:
org.springframework.beans.factory.BeanCreationException: Error creating bean with name ‘org.springframework.jmx.support.ConnectorServerFactoryBean#0? defined in class path resource [application-context.xml]: Invocation of init method failed; nested exception is java.net.MalformedURLException: Unsupported protocol: jmxmp
Remote access over RMI
Alternatively you can expose the MBeans over RMI, which has no additional dependencies:
<!-- Now expose the server for remote access via RMI Local access: service:jmx:rmi://localhost/jndi/rmi://localhost:10099/myconnector Remote access: service:jmx:rmi:///jndi/rmi://your.host:10099/myconnector or service:jmx:rmi://localhost/jndi/rmi://localhost:10099/myconnector --> <bean class="org.springframework.jmx.support.ConnectorServerFactoryBean" depends-on="rmiRegistry"> <property name="objectName" value="connector:name=rmi" /> <property name="serviceUrl" value="service:jmx:rmi://localhost/jndi/rmi://localhost:10099/myconnector" /> </bean> <bean id="rmiRegistry" class="org.springframework.remoting.rmi.RmiRegistryFactoryBean"> <property name="port" value="10099" /> </bean>
However there are also some catches you must avoid:
1. You must start an RMI registry so that the connector can register the MBean there; it won’t start one for you
2. You must make sure that the registry is started before the connector tries to use either by declaring it before the connector or by making this dependency explicit with the depends-on attribute
If you don’t set it up correctly you will get an exception like this one:
org.springframework.beans.factory.BeanCreationException: Error creating bean with name ‘org.springframework.jmx.support.ConnectorServerFactoryBean#0? defined in class path resource [application-context.xml]: Invocation of init method failed; nested exception is java.io.IOException: Cannot bind to URL [rmi://localhost:10099/jmxrmi]: javax.naming.ServiceUnavailableException [Root exception is java.rmi.ConnectException: Connection refused to host: localhost; nested exception is: java.net.ConnectException: Connection refused: connect].
Local MBean server accessed over an SSH tunnel
For increased security you may want to prefer not to expose your MBeans to remote access by making them accessible only from the local machine (127.0.0.1) and use na SSH tunnel so that a remote JConsole can access them as a local application. This is certainly possible but may be difficult because normally JMX goes over RMI, which uses two ports: one for the RMI Registry and another one for the actual service (MBean server here), which is usually chosen randomly at the runtime, and you’d need to tunnel both. Fortunately, Spring makes it possible to configure both the ports:
<bean
class="org.springframework.jmx.support.ConnectorServerFactoryBean"
depends-on="rmiRegistry">
<property name="objectName" value="connector:name=rmi" />
<property name="serviceUrl"
value="service:jmx:rmi://127.0.0.1:STUBPORT/jndi/rmi://localhost:REGISTRYPORT/myconnector" />
</bean>
<bean id="rmiRegistry"
class="org.springframework.remoting.rmi.RmiRegistryFactoryBean">
<property name="port" value="REGISTRYPORT" />
</bean>
Replace STUBPORT and REGISTRYPORT with suitable numbers and tunnel those two. Notice that the REGISTRYPORT number is same in the connector’s serviceUrl and in the RMI registry’s port attribute.
WARNING: The configuration above actually doesn’t prevent direct access from a remote application. To really force the RMI registry to only listen for connection from the local host we would likely need to set – under Sun JVM without Spring – the system property com.sun.management.jmxremote. Additionally, to force the registry to use the IP 120.0.0.1, we’d need to set java.rmi.server.hostname=localhost (applies to Spring too). See this discussion about forcing local access. I’m not sure how to achieve the same result with Spring while still preserving the ability to specify both the RMI ports. Check also the JavaDoc for Spring’s RmiServiceExporter.
Related posts and docs:
- Tunneling Debug and JMX for Alfresco (A. uses Spring)- see the second section, SSH Tunneling for JMX
- A custom tunneling RMI agent – uses a configured port instead of a random one
- Monitoring ActiveMQ Using JMX Over SSH
- JMX 1.2 specification and JMX 1.2 Remote API specification; from the JMX spec.: “The MBean server relies on protocol adaptors and connectors to make the agent accessible from management applications outside the agent’s JVM.” On the other hand, the Oracle JMX page reads that if you set com.sun.management.jmxremote (as opposed to …jmxremote.port), you make it possible “to monitor a local Java platform, that is, a JVM running on the same machine” – thus not necessarily from the same JVM.
Connecting with Jconsole
Fire up JConsole and type the appropriate remote address, for example
service:jmx:rmi:///jndi/rmi://your.server.com:10099/myconnector
if connecting to an application on the remote machine your.server.com accessible via RMI.
Regarding the connection URL, if you have a a connector with the serviceUrl of
service:jmx:rmi://myhost:9999/jndi/rmi://localhost:10099/myconnector
then, from a client, you can use either
service:jmx:rmi://myhost:9999/jndi/rmi://your.server.com:10099/myconnector
or simply
service:jmx:rmi:///jndi/rmi://your.server.com:10099/myconnector
because, according to the JMX 1.2 Remote API specification (page 90):
… the hostname and port number
# (myhost:9999 in the examples) are not used by the client and, if
# present, are essentially comments. The connector server address
# is actually stored in the serialized stub (/stub/ form) or in the
# directory entry (/jndi/ form).
IBM JVM, JConsole and JMX configuration
The IBM JVM 5 SDK guide indicates that the IBM SDK also contains JConsole and recognizes the same JMX-related system properties, namely com.sun.management.jmxremote.* (though “com.sun.management.jmxremote” itself isn’t mentioned).
Notice that the IBM JConsole is a bit different, for instance it’s missing the Local tab, which is replaced by specifying the command-line option connection=localhost (search the SDK guide for “JConsole monitoring tool Local tab”).
Further improvements
JVM 1.5: Exposing the MemoryMXBean
Since Java 5.0 there is a couple of useful platform MBeans that provide information about the JVM, including also the java.lang.management.MemoryMXBean, that let you see the heap usage, invoke GC etc.
You can make it available to JConsole and other JMX agents as follows (though there must be an easier way):
<bean class="org.springframework.jmx.export.MBeanExporter" lazy-init="false">
<property name="beans">
<map>
<entry key="bean:name=Memory2" value-ref="memProxy"/>
<!-- other exported beans may follow ... -->
</map>
</property>
</bean>
<bean id="memProxy"
class="java.lang.management.ManagementFactory"
factory-method="getMemoryMXBean"
/>
Update: There indeed seems to be a better way of exposing the platform MBeans directly by replacing the Spring’s MBeanServerFactoryBean with java.lang.management.ManagementFactory using its factory-method getPlatformMBeanServer. Of course this requires JVM 1.5+.
Improving security with password authentication
Access to your MBeans over RMI may be protected with a password. According to a discussion, authentication is configured on the server connector:
<bean
class="org.springframework.jmx.support.ConnectorServerFactoryBean"
depends-on="rmiRegistry">
<property name="objectName" value="connector:name=rmi" />
<property name="serviceUrl"
value="service:jmx:rmi://localhost/jndi/rmi://localhost:10099/myconnector" />
<property name="environment">
<!-- the following is only valid when the sun jmx implementation is used -->
<map>
<entry key="jmx.remote.x.password.file" value="etc/security/jmxremote.password"/>
<entry key="jmx.remote.x.access.file" value="etc/security/jmxremote.access"/>
</map>
</property>
</bean>
The passwd and access files follow the templates that can be found in the JDK/jre/lib/management folder.
Summary
Exposing a POJO as a MBean with Spring is easy, just don’t forget to start an MBean server and a connector. For JMXMP, include the jmxmp_impl. jar on the classpath and for RMI make sure to start a RMI registry before the connector.
Related Articles:
