Jetty JMX Webservice

Jetty JMX Webservice is a webapp providing a RESTful API to query JMX mbeans and invoke mbean operations without the hassle that comes with RMI. No more arguments with your firewall admin, just a single http port.
That alone might not be a killer feature, but Jetty JMX Webservice also aggregates multiple mbeans having the same ObjectName in the same JVM (e.g. jmx beans for multiple webapps) as well as from multiple jetty instances. That way you’ve a single REST api aggregating JMX mbeans for one or more jetty instances you can use to feed your favourite monitoring system for example.
The whole module is in an early development phase and may contain some rough edges. But we wanted to check for interest of the community early and get some early feedback.
We’ve started a very simple JQuery based webfrontend as a showcase on what the REST api can be used for.
Instance Overview:

Or a realtime memory graph gathering memory consumption from the REST api. This is an accordion like view. You see an accordion line for each node showing the current heap used. You can open each line and get a realtime graph of memory consumption. The memory used in the accordion and the graphs are updated in realtime which is hard to show in a picture:

Pretty cool. Note that this is just a showcase on how the REST api can be used.
URLs Paths of the webservice
/ws/ – index page
/ws/nodes – aggregated basic node information
/ws/mbeans – list of all aggregated mbeans
/ws/mbeans/[mbean objectName] – detailed information about all attributes and operations this mbean offers
/ws/mbeans/[mbean objectName]/attributes – aggregate page containing the values of all attributes of the given mbean
/ws/mbeans/[mbean objectName]/attributes/[attributeName] – aggregated values of a specific attribute
/ws/mbeans/[mbean objectName]/operation/[operationName] – invoke specified operation
Examples URLs:
/ws/mbeans/java.lang:type=Memory
/ws/mbeans/java.lang:type=Memory/operations/gc
How to get it running

Here’s all you need to do to get jetty-jmx-ws running in your jetty instance and some examples how the REST api looks like and how it can be used. Should take less than 15 min.

1. Checkout the sandbox project
   svn co https://svn.codehaus.org/jetty-contrib/sandbox/jetty-jmx-ws
2. cd into the new directory and build the project
   cd jetty-jmx-ws && mvn clean install
3. Make sure you got the [INFO] BUILD SUCCESS message
4. Copy the war file you’ll find in the projects target directory into the webapps directory of your jetty instance
   cp target/jetty-jmx-ws-[version].war [pathToJetty]/webapps
5. Access the webapp by browsing to:
   http://[jettyinstanceurl]/jetty-jmx-ws-[version]/ws/
   e.g.:
   http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/
6. You’re done. 🙂

How to use it: Starting point

As it is a RESTful api it will guide you from the base URL to more detailed pages. The base URL will return:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Index>
<mBeans>http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans</mBeans>
<nodes>http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/nodes</nodes>
</Index>

It shows you two URLs.
The first one will guide you through a list of mbeans which is aggregated. This means it’ll show you mbeans which do exist on ALL configured instances. mebans which exist only on a single instance will be filtered out.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MBeans>
<MBean>
<ObjectName>JMImplementation:type=MBeanServerDelegate</ObjectName>
<URL>http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans/JMImplementation:type=MBeanServerDelegate</URL>
</MBean>
<MBean>
<ObjectName>com.sun.management:type=HotSpotDiagnostic</ObjectName>
<URL>http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans/com.sun.management:type=HotSpotDiagnostic</URL>
</MBean>
<MBean>
<ObjectName>java.lang:type=Memory</ObjectName>
<URL>http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans/java.lang:type=Memory</URL>
</MBean>
SNIPSNAP - lots of mbeans
</MBeans>

The second URL shows you basic node information for all configured nodes:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Index>
<nodes>
<name>localhost:1099</name>
<jettyVersion>7.4.1-SNAPSHOT</jettyVersion>
<threadCount>42</threadCount>
<peakThreadCount>45</peakThreadCount>
<heapUsed>41038176</heapUsed>
<heapInit>0</heapInit>
<heapCommitted>85000192</heapCommitted>
<heapMax>129957888</heapMax>
<jmxServiceURL>service:jmx:rmi:///jndi/rmi://localhost:1099/jettyjmx</jmxServiceURL>
</nodes>
<nodes>
<name>localhost:1100</name>
<jettyVersion>7.4.1-SNAPSHOT</jettyVersion>
<threadCount>45</threadCount>
<peakThreadCount>47</peakThreadCount>
<heapUsed>73915872</heapUsed>
<heapInit>0</heapInit>
<heapCommitted>129957888</heapCommitted>
<heapMax>129957888</heapMax>
<jmxServiceURL>service:jmx:rmi:///jndi/rmi://localhost:1100/jettyjmx</jmxServiceURL>
</nodes>
</Index>

Howto query a single mbean
This example shows how to let you guide through the REST api to query a specific mbean. This example will guide you through to the memory mbean.

1. From the base URL follow the link to the mbeans list:
   http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans
2. Search for the mbean name you’re looking for:

   <MBean>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <URL>http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans/java.lang:type=Memory</URL>
   </MBean>

3. Open the link inside the URL tag
   http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans/java.lang:type=Memory
4. You’ll get a list of all operations which can be executed on that mbean and all attributes which can be queried:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <MBean>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Operations>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Operation>
   <Name>gc</Name>
   <Description>gc</Description>
   <ReturnType>void</ReturnType>
   <URL>http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans/java.lang:type=Memory/operations/gc</URL>
   </Operation>
   </Operations>
   <Attributes>
   <Attribute>
   <Name>HeapMemoryUsage</Name>
   <description>HeapMemoryUsage</description>
   <type>javax.management.openmbean.CompositeData</type>
   <isReadable>true</isReadable>
   <isWritable>false</isWritable>
   <uri>http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans/java.lang:type=Memory/attributes/HeapMemoryUsage</uri>
   </Attribute>
   SNIPSNAP - lots of attributes cutted
   </Attributes>
   </MBean>

5. Besides some information about all operations and attributes you’ll find URLs to invoke operations like:
   http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans/java.lang:type=Memory/operations/gc
which will invoke a garbage collection.And URLs to display the attributes’ values like:
   http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans/java.lang:type=Memory/attributes/HeapMemoryUsage
   Will show you: 

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <mBeanAttributeValueJaxBeans>
   <Attribute>
   <AttributeName>HeapMemoryUsage</AttributeName>
   <NodeName>localhost:1099</NodeName>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Value>javax.management.openmbean.CompositeDataSupport(compositeType=javax.management.openmbean.CompositeType(name=java.lang.management.MemoryUsage,items=((itemName=committed,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=init,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=max,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=used,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)))),contents={committed=85000192, init=0, max=129957888, used=28073528})</Value>
   </Attribute>
   <Attribute>
   <AttributeName>HeapMemoryUsage</AttributeName>
   <NodeName>localhost:1100</NodeName>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Value>javax.management.openmbean.CompositeDataSupport(compositeType=javax.management.openmbean.CompositeType(name=java.lang.management.MemoryUsage,items=((itemName=committed,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=init,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=max,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=used,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)))),contents={committed=129957888, init=0, max=129957888, used=69793976})</Value>
   </Attribute>
   </mBeanAttributeValueJaxBeans>

6. You can as well get an aggregated view of all attributes for an mbean by just adding attributes to the mbeans url: http://localhost:8080/jetty-jmx-ws-7.4.1-SNAPSHOT/ws/mbeans/java.lang:type=Memory/attributes
   will return: 

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <mBeanAttributeValueJaxBeans>
   <Attribute>
   <AttributeName>HeapMemoryUsage</AttributeName>
   <NodeName>localhost:1099</NodeName>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Value>javax.management.openmbean.CompositeDataSupport(compositeType=javax.management.openmbean.CompositeType(name=java.lang.management.MemoryUsage,items=((itemName=committed,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=init,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=max,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=used,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)))),contents={committed=85000192, init=0, max=129957888, used=30005472})</Value>
   </Attribute>
   <Attribute>
   <AttributeName>HeapMemoryUsage</AttributeName>
   <NodeName>localhost:1100</NodeName>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Value>javax.management.openmbean.CompositeDataSupport(compositeType=javax.management.openmbean.CompositeType(name=java.lang.management.MemoryUsage,items=((itemName=committed,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=init,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=max,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=used,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)))),contents={committed=129957888, init=0, max=129957888, used=68043064})</Value>
   </Attribute>
   <Attribute>
   <AttributeName>NonHeapMemoryUsage</AttributeName>
   <NodeName>localhost:1099</NodeName>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Value>javax.management.openmbean.CompositeDataSupport(compositeType=javax.management.openmbean.CompositeType(name=java.lang.management.MemoryUsage,items=((itemName=committed,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=init,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=max,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=used,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)))),contents={committed=85356544, init=24317952, max=136314880, used=52749944})</Value>
   </Attribute>
   <Attribute>
   <AttributeName>NonHeapMemoryUsage</AttributeName>
   <NodeName>localhost:1100</NodeName>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Value>javax.management.openmbean.CompositeDataSupport(compositeType=javax.management.openmbean.CompositeType(name=java.lang.management.MemoryUsage,items=((itemName=committed,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=init,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=max,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)),(itemName=used,itemType=javax.management.openmbean.SimpleType(name=java.lang.Long)))),contents={committed=92868608, init=24317952, max=136314880, used=78705952})</Value>
   </Attribute>
   <Attribute>
   <AttributeName>ObjectPendingFinalizationCount</AttributeName>
   <NodeName>localhost:1099</NodeName>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Value>0</Value>
   </Attribute>
   <Attribute>
   <AttributeName>ObjectPendingFinalizationCount</AttributeName>
   <NodeName>localhost:1100</NodeName>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Value>0</Value>
   </Attribute>
   <Attribute>
   <AttributeName>Verbose</AttributeName>
   <NodeName>localhost:1099</NodeName>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Value>false</Value>
   </Attribute>
   <Attribute>
   <AttributeName>Verbose</AttributeName>
   <NodeName>localhost:1100</NodeName>
   <ObjectName>java.lang:type=Memory</ObjectName>
   <Value>false</Value>
   </Attribute>
   </mBeanAttributeValueJaxBeans>

Security
It’s a webapp with some servlets. So secure it the same way you would any servlet.
What’s next?
There’s two more features which I didn’t describe. I will write a follow up soon describing how to use them.

1. You can filter by nodes with QueryParams
2. Invoke operations whith parameters
3. Configuration for multiple instances
4. Get JSON instead of XML by setting accept header

If there’s interest in this project, I will also take care to write some manuals and add them to the wiki pages.