Monitoring WSO2 ESB using JConsole

My latest tutorial on how to monitor WSO2 ESB using JConsole is now published on WSO2 Oxygen Tank

Switching wso2 carbon server to maintenance mode

When wso2 carbon server (WSO2 WSAS, ESB, Registry and BPS) is running in production environments, it may be required to perform some essential upgrades without shutting down the server.
[WSO2 Carbon is the base platform for all WSO2 Java products. wso2 carbon server refers to any of WSAS, ESB, Registry or BPS server]

WSO2 Carbon based products are equipped with JMX based monitoring and management facilities, through which you can switch to maintenance mode.

Step 1
In order to enable JMX management, you must uncomment the JMX port element in CARBON_HOME/conf/carbon.xml

<Ports> <!-- The JMX Port --> <JMX>9999</JMX> </Ports>

CARBON_HOME is the directory where you extracted wso2wsas-3.0, wso2esb-2.0, wso2-registry-2.0 or wso2-bps-1.0 binary distributions.

Step 2

Start your WSO2 carbon server (WSAS, ESB, Registry or BPS).
You will notice that the JMX service URL will be printed in the startup console as follows.



Step 3

You can use JConsole as the client for JMX monitoring and management. Start command prompt (or shell in linux), type Jconsole and hit enter. JConsole:Connect to Agent window will be popped up.
Enter JMX url (service:jmx:rmi:///jndi/rmi://YourHost:9999/server)
Enter admin as user name and password. Note that, any user with admin privileges can log in to JMX.
Click on Connect.
Select MBeans-->org.wso2.carbon-->ServerAdmin-->Operations
You will see the following server admin operations.



Step 4

Suppose you have a web service which is in the process of responding to a client. Now, you may want to do some upgrades in the server without shutting it down.
Click on startMaintenance() button in the jconsole.
Now server is being running on maintenance mode. It does not accepts service requests in this mode. Your client application may get "org.apache.axis2.AxisFault: Connection refused" error.

After server upgrade is done, click on endMaintenance() button. Server will be switching back to normal mode. You will notice that the message transmission of your client will be resumed.

How to use jconsole to monitor and manage WSO2 WSAS

Service or system monitoring and management are essential components of any SOA framework. WSO2 WSAS provides two different mechanisms to manage and monitor web services.
1. Ajax based GUI console
2. JMX based monitoring facility

In this post, I'm going to demonstrate the second option, JMX based service and system monitoring component. You can find more information about WSAS GUI console from here.

JMX (Java Management Extension) provides a set of tools and APIs for applying a standard client/server-based architecture to monitoring and management of a Java application.
J2SE version 5.0 adds core support for the Java Management Extensions (JMX) into the Java standard libraries. We are going to use Jconsole, included in jdk1.5 or newer versions, to explore the management and monitoring capabilities provided by WSO2 WSAS.

Pre-Requisites

Download and install WSO2 WSAS-2.2.1 or later

Step 1

JMX port is disabled by default in WSAS. Open WSO2WSAS_HOME/conf/server.xml and uncomment the following element.

<!--The JMX Port-->
<JMX>9999</JMX>

Step 2

Start WSO2 WSAS (run wso2wsas.bat or sh).

Make a note of the JMX url which will be printed on server startup console
i.e:- JMX Service URL : service:jmx:rmi:///jndi/rmi://YourHost:9999/server

Step 3

Start command prompt (or shell in linux), type Jconsole and hit enter. JConsole:Connect to Agent window will be popped up.



Enter JMX url (service:jmx:rmi:///jndi/rmi://YourHost:9999/server)
Enter admin as user name and password. Note that, any user with admin privileges can log in to JMX.
Click on Connect.

You will be directed to the summary page of Jconsole as follows.



Step 4

Click on MBeans tab. You will see the Mbeans tree in the left pane. Select org.wso2.wsas MBean.
ServerAdmin, ServiceAdmin and StatisticsService MBeans will be listed there.
Select ServerAdmin.



You will see shutdown, restart, restartGracefully, shutdownGracefully, startMaintenance and endMaintenance administrative functions when clicking on Operations tab in the above screen.

Step 5

We observed a few administrative function of WSo2 WSAS which were exposed through JMX in the above step. Lets see how service statistics are monitored using Jconsole.

Click on StatisticsService Mbean at the left pane. Next, select Operations tab.
Following screen will be displayed.



In order to check service statistics, we must invoke a service deployed on WSAS. Open your browser and enter the following URL.
http://localhost:9762/services/version/getVersion
This will send a HTTP GET request to the default Version service.

Now enter 'version' as the value of the getServiceRequestCount operation in above screen and click on getServiceRequestCount.
You will get '1' as the response.



Invoke Version service a few more times (just send http GET requests using the above URL).
Enter 'version' as parameter 1 (p1) and 'getVersion' as parameter 2 (p2) of getOperationRequestCount operation.
You will see a operation return value similar to the one bwlow.



Now, you will be able to proceed with more operations and get the statistics of server and system status.