Managing WSO2 WSAS using MC4J

Submitted on January 25, 2008 - 03:07. Story :

Tutorials

Level :

Introductory

Project :

WSAS > Java

Realm :

Tooling

Java Management Extensions(JMX) is a technology that allows you to implement management interfaces for Java applications. In this tutorial, Afkham Azeez describes how to manage WSAS via JMX using the MC4J console.

Introduction

Axis2 Java Management Extensions(JMX) is a technology that allows you to 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, called an ObjectName, in an MBeanServer. To manage resources in your application, you would write an MBean that defines 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. The first version of JMX based monitoring is available in the WSAS 2.2 release. Some of the monitoring & management capabilities available in the WSAS Management Console have also been exposed via a JMX interface.

During the course of this article, we will be looking in to the management and monitoring functionality exposed via JMX in WSAS, as well as on how to use the MC4J monitoring console to manage & monitor a WSAS instance.

Applies To

WSO2 WSAS/Java 2.2

Enabling JMX in WSAS
What is MC4J
The WSAS MBeans
- ServerAdmin MBean
- ServiceAdminMBean
- Statistics MBean

Enabling JMX in WSAS

Enabling or disabling JMX in WSAS is controlled thought the JMX port entry in the WSAS server.xml file. In the WSO2WSAS_HOME/conf/server.xml, commenting out the JMX port will disable JMX while uncommenting or adding this entry will enable JMX. Here is the relevant section is the server.xml file:

<!--
      Ports used by WSAS
      -->
      <Ports>
         ...
         <!--
         The JMX Port
         -->
         <JMX>9999</JMX>
         ...
      </Ports>

The same JMX port entry is used for changing the JMX port. After enabling JMX as shown above, start WSAS. You should see the following or a corresponding line on your command line console or the WSAS log file if the JMX service was successfully started.

JMX Service URL: service:jmx:rmi:///jndi/rmi://10.100.1.74:9999/server

What is MC4J?

MC4J is a project to create management software for J2EE application servers and other Java applications. It is designed to utilize the JMX specification to connect to and introspect information within supported servers and applications. It provides the ability to browse existing managed beans (MBeans), update configurations, monitor operation and execute tasks. In the next few sections, we will look at how to install MC4J and als how to connect to WSAS using the MC4J console.

Dowloading MC4J

MC4J can be downloaded from http://mc4j.org/confluence/display/MC4J/Download. Downloads for various platforms including Windows, Linux & Mac OS are also available here.

Installing MC4J

Once you have dowloaded and saved MC4J to your local disk, run the installer. The file you will have to execute will depend on your installation platform. Figure 1 shows the first screen in the MC4J installation wizard. Simply click 'Next' in this screen.

Installation Step1

Figure 1: MC4J Installation - Step 1

Next, you will have to specify the JRE to be used by MC4J. Note that MC4J requires JRE 1.4 or newer versions, while JRE 1.5 is recommended. The MC4J installation wizard will try to figure out the JVMs installed on your machine and suggest one. If the wizard cannot find a JVM, check that your system contains a JVM. You could specify a JVM using the "Choose Another..." button. See figure 2.

Figure 2: MC4J Installation - Step 2

In the next step, you wil have to specify the MC4J installation home directory. Make sure that you have write access to this directory. If the directory does not exist, the installation wizard will create one for you. See figure 3.

Figure 3: MC4J Installation - Step 3

In the next step of the installation, you will be prompted to create links to MC4J. For convenience sake, you may opt to create a link to the MC4J consol application on your Desktop. You can also refrain from creating any links by selecting the "Don't create links" option. See figure 4.

Figure 4: MC4J Installation - Step 4

Figure 5 shows the installation progress.

Figure 5: MC4J Installation - Step 5

Finally, if the MC4J installation was successful, you will see the following screen titled "Install Complete". See figure 6.

Figure 6: MC4J Installation - Step 6

Connecting to WSAS from MC4J

Once you have successfully installed MC4j, you could start up the MC4J console either from the command line or from the link you created during installation. The MC4J console startup script will be avaialable in the MC4J home directory.

On the welcome screen (figure 7), notice the MC4J Connections tab at the top left hand side corner. Right click on the "MC4J Connections" icon and select "Connect to server...". Now the connection creation wizard will appear. The next step is to define how to connect to the WSAS JMX service.

Figure 7: MC4J Console - Welcome Screen

Figure 8 shows the new connection wizard. In step 1 titled 'Connect to Server', we need to provide all parameters necessary for connecting to the WSAS server. From the drop down list at the top, select J2SE 5.0 (assuming that you started WSAS on J2SE 5.0). Give the connection names as "wsas" or any other of your choice. For the "Initial Context Factory" entry, select "com.sun.jndi.rmi.registry.RegistryContextFactory". For the "Server URL" entry, you will need to provide the JMX service URL of the WSAS JMX service. This is the same URL that was printed out on the WSAS console or log file as explained in the "Enabling JMX in WSAS" section above. For the "Principle" entry, you need to provide the username if an administrative user and for the "Credentials" entry, you need to provide the password of that user. You can type in the default username and password combination admin/admin to login, provided you haven't changed the password of the admin user. If you have changed the admin password, you will need to provide that password. Note that this is the same administrator account that is used for looging in to the WSAS Management Console. Any user having the admin role can connect to the JMX service. Click "Next". In the next step, simply click "Finish".

Figure 8: MC4J Console - Create New Connection Step 1

If MC4J was able to successfully connect to WSAS, you should be able to see a new connection named "wsas". Note that the connection name wil be the one you provided during connection creation step. Double clicking on the "wsas" connection will expand that node in the tree and you should be able to view serveral JMX domains including org.wso2.wsas & Catalina. Under the org.wso2.wsas domain, you should be able to see 3 MBeans; ServerAdmin, ServiceAdmin & Statistics.

The WSAS MBeans

In this section, we will take a detailed look at WSAS MBeans. At the moment, WSAS exposes three MBeans and they are: ServerAdmin, ServiceAdmin & Statistics. Each MBean contains a set of attributes & operations. In the next section, we will take a look at each of these attributes & operations. On the MC4J console, by clicking on the relevant attribute you could view the value of the attribute. Similarly, by double clicking on each operation, another window pops up prompting you to enter the values for the operation parameters and to invoke it.

ServerAdmin MBean

The ServerAdmin MBean is used for administering the WSAS server instance.

Attributes

Figure below shows the value of the ServerDataAsString that provides information about the server. There are several other server attributes such as the ServerStatus & ServerVersion. The ServerStatus can be either RUNNING, SHUTTING_DOWN, RESTARTING or IN_MAINTENANCE. ServerVersion provides the version of this WSAS instance.

Operations

The above screen shows the operations available in the ServerAdmin MBean.

shutdown - forcefully shuts down the server.
restart - forcefully restarts the server.
restartGracefully - wait till all current requests are served and then restart.
shutdownGracefully - wait till all current requests are served and then shuts down.
startMaintenance - switches the server to maintenance mode. No new requests will be accepted while the server is in maintenance mode.
endMaintenance - switch the server to normal mode, if it is in maintenance mode.

ServiceAdmin MBean

The ServiceAdmin MBean is used for adminsitering services deployed on WSAS.

Attributes

The above screen shows the attributes in ServiceAdmin:

NumberOfActiveServices - The number of services that can currently serve requests
NumberOfInactiveServices - The number of services that have been disabled by an administrator
NumberOfFaultyServices - The number of services that are faulty

Operations

The above screen shows the operations available in the ServiceAdmin MBean.

startService(p1:string) - The p1 parameter is the service name. You can activate a service using this operation.
stopService(p1:string) - The p1 parameter is the service name. You can deactivate/disable a service using this operation.

Statistics MBean

The Statistics MBean is used for monitoring system and server statistics.

Attributes

The above screen shows the following attributes:

AvgSystemResponseTime - The average response time for all the services deployed in the system. The beginning of the measurement is the time at which the server started.
MaxSystemResponseTime - The maximum response time for all the services deployed in the system. The beginning of the measurement is the time at which the server started.
MinSystemResponseTime - The minimum time for all the services deployed in the system. The beginning of the measurement is the time at which the server started.
SystemFaultCount - The total number of faults that occurred in the system since the server was started.
SystemRequestCount - The total number of requests that has been served by the system since the server was started
SystemResponseCount - The total number of response that has been sent by the system since the server was started

Operations

The above screen shows the operations available in the Statistics MBean

getServiceRequestCount(p1:string) - The p1 parameter is the service name. You can get the total number of requests received by this service since the time it was deployed, using this operation.
getServiceResponseCount(p1:string) - The p1 parameter is the service name. You can get the total number of responses sent by this service since the time it was deployed, using this operation.
getServiceFaultCount(p1:string) - The p1 parameter is the service name. You can get the total number of fault responses sent by this service since the time it was deployed, using this operation.
getMaxServiceResponseTime(p1:string) - The p1 parameter is the service name. You can get the maximum response time of this service since deployment.
getMinServiceResponseTime(p1:string) - The p1 parameter is the service name. You can get the minimum response time of this service since deployment.
getAvgServiceResponseTime(p1:string) - The p1 parameter is the service name. You can get the average response time of this service since deployment.
getOperationRequestCount(p1:string, p2:string) - The p1 parameter is the service name. The p2 parameter is the operation name. You can get the total number of requests received by this operation since the time its service was deployed, using this operation.
getOperationResponseCount(p1:string, p2:string) - The p1 parameter is the service name. The p2 parameter is the operation name. You can get the total number of responses sent by this operation since the time its service was deployed, using this operation.
getOperationFaultCount(p1:string, p2:string) - The p1 parameter is the service name. The p2 parameter is the operation name. You can get the total number of fault responses sent by this operation since the time its service was deployed, using this operation.
getMaxOperationResponseTime(p1:string, p2:string) - The p1 parameter is the service name. The p2 parameter is the operation name. You can get the maximum response time of this operation since deployment.
getMinOperationResponseTime(p1:string, p2:string) - The p1 parameter is the service name. The p2 parameter is the operation name. You can get the minimum response time of this operation since deployment.
getAvgOperationResponseTime(p1:string, p2:string) - The p1 parameter is the service name. The p2 parameter is the operation name. You can get the average response time of this operation since deployment.

Conclusion

This tutorial discussed monitoring WSAS using the MC4J console. Any other JMX monitoring tool of your choise can be used for monitoring WSAS. jconsole which ships with JDK 1.5 and newer versions is also another such popular tool. Reference [1] talks about how console can be used for monitoring WSAS.