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, you can write an MBean defining its management interface and 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.

Configuring JMX in a WSO2 product

JMX is enabled in WSO2 products by default, which ensures that the JMX server starts automatically when you start a particular product. Additionally, you can enable JMX separately for the various datasources that are used by the product. Once JMX is enabled, you can log in to the JConsole tool and monitor your product as explained in the next section.

Configuring JMX ports for the server

The default JMX ports (RMIRegistryPort and the RMIServerPort) are configured in the carbon.xml file (stored in the <PRODUCT_HOME>/repository/conf directory) as shown below. If required, you can update these default values.

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

Disabling JMX for the server

The JMX configuration is available in the jmx.xml file (stored in the <PRODUCT_HOME>/repository/conf/etc directory) as shown below. You can disable the JMX server for your product by setting the <StartRMIServer> property to false. Note that this configuration refers to the JMX ports configured in the carbon.xml file.

<JMX xmlns="http://wso2.org/projects/carbon/jmx.xml">
    <StartRMIServer>true</StartRMIServer>
    <!-- HostName, or Network interface to which this RMI server should be bound -->
    <HostName>localhost</HostName>
    <!--  ${Ports.JMX.RMIRegistryPort} is defined in the Ports section of the carbon.xml-->
    <RMIRegistryPort>${Ports.JMX.RMIRegistryPort}</RMIRegistryPort>
    <!--  ${Ports.JMX.RMIRegistryPort} is defined in the Ports section of the carbon.xml-->
    <RMIServerPort>${Ports.JMX.RMIServerPort}</RMIServerPort>
</JMX>

Enabling JMX for a datasource

You can enable JMX for a datasource by adding the <jmxEnabled>true</jmxEnabled> element to the datasource configuration file. For example, to enable JMX for the default Carbon datasource in your product, add the following property to the master-datasources.xml file (stored in the <PRODUCT_HOME>/repository/conf/datasources directory).

<datasource>
            <name>WSO2_CARBON_DB</name>
            <description>The datasource used for registry and user manager</description>
            <jndiConfig>
                <name>jdbc/WSO2CarbonDB</name>
            </jndiConfig>
            <definition type="RDBMS">
                <configuration>
                    <url>jdbc:h2:./repository/database/WSO2CARBON_DB;DB_CLOSE_ON_EXIT=FALSE;LOCK_TIMEOUT=60000</url>
                    <username>wso2carbon</username>
                    <password>wso2carbon</password>
                    <driverClassName>org.h2.Driver</driverClassName>
                    <maxActive>50</maxActive>
                    <maxWait>60000</maxWait>
                    <testOnBorrow>true</testOnBorrow>
                    <validationQuery>SELECT 1</validationQuery>
                    <validationInterval>30000</validationInterval>
                    <defaultAutoCommit>false</defaultAutoCommit>
                    <jmxEnabled>true</jmxEnabled>
                </configuration>
            </definition>
        </datasource>

Monitoring a WSO2 product with JConsole

Jconsole is a JMX-compliant monitoring tool, which comes with the Java Development Kit (JDK) 1.5 and newer versions. You can find this tool inside your <JDK_HOME>/bin directory. See the instructions on Installing the JDK for more information.

Starting the WSO2 product with JMX

First, start the WSO2 product:

Open a command prompt and navigate to the <PRODUCT_HOME>/bin directory.
Execute the product startup script (wso2server.sh for Linux and wso2server.bat for Windows) to start the server.
If JMX is enabled, the JMX server URL will be published on the console when the server starts as shown below.
INFO {org.wso2.carbon.core.init.CarbonServerManager} - JMX Service URL : service:jmx:rmi://<your-ip>:11111/jndi/rmi://<your-ip>:9999/jmxrmi

Once the product server is started, you can start the JConsole tool as follows:

Open a command prompt and navigate to the <JDK_HOME>/bin directory.
Execute the jconsole command to open the log-in screen of the Java Monitoring & Management Console as shown below.
Enter the connection details in the above screen as follows:
1. Enter the JMX server URL in the Remote Process field. This URL is published on the command prompt when you start the WSO2 server as explained above.
  Tip
  If you are connecting with a remote IP address instead of localhost, you need to bind the JMX service to the externally accessible IP address by adding the following system property to the product startup script stored in the <PRODUCT_HOME>/bin directory (wso2server.sh for Linux and wso2server.bat for Windows). For more information, read Troubleshooting Connection Problems in JConsole.
  -Djava.rmi.server.hostname=<IP_ADDRESS_WHICH_YOU_USE_TO_CONNECT_TO_SERVER>
  Be sure to restart the server after adding the above property.
2. Enter values for the Username and Password fields to log in. If you are logging in as the administrator, you can use the same administrator account that is used to log in to the product's management console: admin/admin.
  
  Make sure that the user ID you are using for JMX monitoring is assigned a role that has the Server Admin permission. See Configuring Roles for further information about configuring roles assigned to users. Any user assigned to the admin role can log in to JMX.
Click Connect to open the Java Monitoring & Management Console. The following tabs will be available:

Using the 'ServerAdmin' MBean

When you go to the MBeans tab in the JConsole, the ServerAdmin MBean will be listed under the "org.wso2.carbon" domain as shown below.

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.

Using the 'DataSource' MBean

If you have JMX enabled for a datasource connected to the product, you can monitor the performance of the datasource using this MBean. The DataSource MBean will be listed as shown below.

Example: If you have JMX enabled for the default Carbon datasource in the master-datasources.xml. file, the JDBC connection pool parameters that are configured for the Carbon datasource will be listed as attributes as shown below. See the performance tuning guide for instructions on how these parameters are configured for a datasource.

Using product-specific MBeans

The WSO2 product that you are using may have product-specific MBeans enabled for monitoring and managing specific functions. See the documentation for your product for detailed instructions on such product-specific MBeans.