Using the JMX Proxy Servlet

What is JMX Proxy Servlet

The JMX Proxy Servlet is a lightweight proxy to get and set the tomcat internals. (Or any class that has been exposed via an MBean) Its usage is not very user friendly but the UI is extremely help for integrating command line scripts for monitoring and changing the internals of tomcat. You can do two things with the proxy: get information and set information. For you to really understand the JMX Proxy Servlet, you should have a general understanding of JMX. If you don’t know what JMX is, then prepare to be confused.

JMX Query command

This takes the form:

http://webserver/manager/jmxproxy/?qry=STUFF

Where STUFF is the JMX query you wish to perform. For example, here are some queries you might wish to run:

qry=*%3Atype%3DRequestProcessor%2C* –> type=RequestProcessor which will locate all workers which can process requests and report their state.
qry=*%3Aj2eeType=Servlet%2c* –> j2eeType=Servlet which return all loaded servlets.
qry=Catalina%3Atype%3DEnvironment%2Cresourcetype%3DGlobal%2Cname%3DsimpleValue –> Catalina:type=Environment,resourcetype=Global,name=simpleValue which look for a specific MBean by the given name.

You’ll need to experiment with this to really understand its capabilites. If you provide no qry parameter, then all of the MBeans will be displayed. We really recommend looking at the tomcat source code and understand the JMX spec to get a better understanding of all the queries you may run.

JMX Get command

The JXMProxyServlet also supports a “get” command that you can use to fetch the value of a specific MBean’s attribute. The general form of the get command is:

http://webserver/manager/jmxproxy/?get=BEANNAME&att=MYATTRIBUTE&key=MYKEY

You must provide the following parameters:

get: The full bean name
att: The attribute you wish to fetch
key: (optional) The key into a CompositeData MBean attribute

If all goes well, then it will say OK, otherwise an error message will be shown. For example, let’s say we wish to fetch the current heap memory data:

http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&att=HeapMemoryUsage

Or, if you only want the “used” key:

http://webserver/manager/jmxproxy/

?get=java.lang:type=Memory&att=HeapMemoryUsage&key=used

JMX Set command

Now that you can query an MBean, its time to muck with Tomcat’s internals! The general form of the set command is :

http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE

So you need to provide 3 request parameters:

set: The full bean name
att: The attribute you wish to alter
val: The new value

If all goes ok, then it will say OK, otherwise an error message will be shown. For example, lets say we wish to turn up debugging on the fly for the ErrorReportValve. The following will set debugging to 10.

http://localhost:8080/manager/jmxproxy/

?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost

&att=debug&val=10

and my result is (YMMV):

Result: ok

Here is what I see if I pass in a bad value. Here is the URL I used, I try set debugging equal to ‘cow’:

http://localhost:8080/manager/jmxproxy/

?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost

&att=debug&val=cow

When I try that, my result is

Error: java.lang.NumberFormatException: For input string: “cow”

JMX Invoke command