JMX-Based Monitoring

Java Management Extensions (JMX) is a technology that lets you implement management interfaces for Java applications. A management interface, as defined by JMX, is composed of named objects called MBeans (Management Beans). MBeans are registered with a name (an ObjectName) in an MBeanServer. To manage a resource or many resources in your application, write an MBean that defines its management interface. Then register that MBean in your MBeanServer. The content of the MBeanServer can then be exposed through various protocols, implemented by protocol connectors, or protocol adaptors.

JMX is enabled in WSO2 Carbon by default. You can change the JMX configuration by editing the jmx.xml file, which is inside the <PRODUCT_HOME>/repository/conf/etc/ directory. You can configure JMX ports, RMIRegistryPort and RMIServerPort from the "Ports" section of the carbon.xml file, which is inside the <PRODUCT_HOME>/repository/conf/ directory.

<JMX>
     <!--The port RMI registry is exposed-->
     <RMIRegistryPort>9999</RMIRegistryPort>
     <!--The port RMI server should be exposed-->
     <RMIServerPort>11111</RMIServerPort>
</JMX>

If JMX is enabled, when the server starts up, it will print the JMX Server URL on the console as follows.

INFO {org.wso2.carbon.core.init.CarbonServerManager} -  JMX Service URL  : service:jmx:rmi://<your-ip>:11111/jndi/rmi://<your-ip>:9999/jmxrmi

Using 'jconsole' to manage and monitor a Carbon product

Jconsole is a JMX-compliant monitoring tool. It comes with the Java Development Kit (JDK) 1.5 and newer versions and can be found in <JDK_HOME>/bin/ directory. For information on installing JDK, refer to Installing JDK on Windows, Linux or Solaris. 

You can start the tool by simply typing jconsole in a command (shell) prompt from <JDK_HOME>/bin.

Once the console is opened, you can connect to Carbon by providing the following URL as the Remote Process URL. You can type in the default username and password combination admin/admin to login. Note that this is the same administrator account that is used to log in to the product's management console. Any user having the admin role can log in to JMX.

The Java Monitoring & Management Console opens. The first window you see looks similar to the following:

Click the MBeans tab to see the "org.wso2.carbon" domain, which contains some MBeans as follows:

The "ServerAdmin" MBean

The ServerAdmin MBean is used for administering the product server instance. There are several server attributes such as "ServerStatus", "ServerData" and "ServerVersion". The "ServerStatus" attribute can take any of the following values:

• RUNNING
• SHUTTING_DOWN
• RESTARTING
• IN_MAINTENANCE

The ServerAdmin MBean has the following operations:

• shutdown - Forcefully shut down the server.
• restart - Forcefully restart the server.
• restartGracefully - Wait till all current requests are served and then restart.
• shutdownGracefully - Wait till all current requests are served and then shutdown.
• startMaintenance - Switch the server to maintenance mode. No new requests will be accepted while the server is in maintenance.
• endMaintenance - Switch the server to normal mode if it was switched to maintenance mode earlier.