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.

1 Configuring JMX in WSO2 Open Banking
2 Monitoring a WSO2 product with JConsole
3 Monitoring a WSO2 product with Jolokia

Configuring JMX in WSO2 Open Banking

JMX is enabled in WSO2 Open Banking by default, which ensures that the JMX server starts automatically when you start the solution. Additionally, you can enable JMX separately for the various datasources that are used by the solution. 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 <WSO2_OB_APIM_HOME>/repository/conf and <WSO2_OB_KM_HOME>/repository/conf directories) 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 <WSO2_OB_APIM_HOME>/repository/conf/etc and <WSO2_OB_KM_HOME>/repository/conf/etc directories) 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 <WSO2_OB_APIM_HOME>/repository/conf/datasources and <WSO2_OB_KM_HOME>/repository/conf/datasources directories).

<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 <WSO2_OB_KM_HOME>/bin and <WSO2_OB_APIM_HOME>/bin directories.
Execute the product startup script (wso2server.sh for Linux and wso2server.bat for Windows) to start the server.

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.
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.
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:

Operation	Description

Operation	Description
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 ServiceAdmin MBean

This MBean is used for administering services deployed in your product. Its attributes are as follows:

Attribute	Description

Attribute	Description
NumberOfActiveServices	The number of services which can currently serve requests.
NumberOfInactiveServices	The number of services which have been disabled by an administrator.
NumberOfFaultyServices	The number of services which are faulty.