JMX Monitoring with WSO2 BAM

  • By Ishan Somasiri
  • 23 Feb, 2013


The JMX agent for WSO2 Business Activity Monitor (WSO2 BAM) was created to let the user
periodically monitor the desired JMX attributes using a WSO2 Carbon based
server. The JMX agent can run on any Carbon based server and can be
configured to publish data to a WSO2 BAM server.

Applies To

WSO2 BAM 2.0.0
WSO2 BAM 2.0.1
WSO2 BAM 2.0.2



The JMX agent is capable of
monitoring JMX attributes from any Java process that exposes a JMX
server. But because of limitations imposed by the Cassandra
database which WSO2 BAM uses to store data, the JMX agent will only allow to
monitor JMX attributes which returns the following data types.

  • String
  • Long
  • Integer
  • Boolean
  • Double
  • or Composite data objects that returns the above types


When monitoring a JMX server, the user needs to create a profile for
that server. The profile will contain details of the JMX server such as
URL, login credentials, which attributes needs to be monitored, and how
often they need to get monitored. A single profile can be used to
monitor only a single JMX server. But multiple profiles can be used to
monitor the attributes of a single JMX server. A profile can be
activated or deactivated in order to start or stop monitoring.

Basic Architecture

alt="JMX agent in pull configuration" src="/files/archi_0.png">

The Profile Manager is responsible for the tasks such as storing the profiles in the registry, retrieving the persisted profiles from the registry and creating the instances of the Profile classes relevant to them, and updating the profile data when needed.

The Scheduler is used to periodically monitor the JMX attributes specified in the enabled profiles. Attributes of each enabled profile will be periodically monitored by the scheduler. The time interval for an individual profile can be set as the user desires. The values of the attributes that are retrieved by the scheduler will be persisted in a user defined database. In most cases, this will be a Cassandra based database. But upon the configuration, the target database could change.

Working Modes

The JMX agent can be configured to work in two ways.


The JMX agent can be installed on any carbon based server and can be
configured to publish the monitored data to a separate WSO2 BAM server.

JMX agent in push configuration


The JMX agent can be installed on a WSO2 BAM server and can be configured to
publish the monitored data to the same BAM server.

alt="JMX agent in pull configuration" src="/files/JMX pull mode archi.jpg">


Accessing the JMX agent

After installing the JMX agent it can be accessed from the Main Menu

alt="Menu Entry" src="/files/jmx%20agent%20menu%20entry.png">

After clicking on the menu entry the following page will be displayed
in which the list of current JMX monitoring profiles will be displayed.

alt="Menu Entry" src="/files/index page.png">

From this page, the user can add new profiles, enable or disable
profiles, edit profiles, delete profiles, and view the profile version
number (more on this later).

Adding a profile

A new profile can be added from the Add
profile link in the JMX
Monitoring profiles page.

add profile button src="/files/add%20profile%20button.png">

After clicking on the link, the user will be presented with the New profile page.
There the user can set the parameters required by a JMX attribute
monitoring profile. These parameters are divided in to sections. The
first section is the Basic Information
section. The only parameter that needs to be set is the name of the
profile. The name of a profile should be unique in order to distinguish
it from other profiles. If an existing name is added, a warning
will appear informing the user about it.

Next is the Data Receiver information.
The user needs to enter the details of the data receiving server there
(ideally the details of a BAM server). Receiver
address is the address that is used to send data. Secure address
is the address that is used to authenticate the data publishing
request.  The user can enter the credentials to log in to the data
receiver using the user name and
password entries. Using the Schedule option,
the user can configure the frequency that the selected attributes get
monitored. The user can select from a list of preset cron expressions
or else can input a custom cron expression.

Finally is the JMX server information
section. This is used to configure all the details related to the JMX
server that is being monitored. First the user has to enter the JMX
server url and the login credentials for the JMX server.  Then he
click on the Load MBeans button.

load mbeans src="/files/load%20mbeans.png">

Then the list of the MBeans that is exposed by the JMX server will be

MBeans list src="/files/mbeans list_0.png">

The user can also reload the MBeans list using the reload button.
By clicking on a mbean name, the user can load the attributes that are
exposed by the mbean.

attributes list src="/files/attributes_list_res.png">

By selecting an attribute from the Select
drop-down list, the user can select an attribute to be monitored. The
selected attributes will be displayed on a table as follows.


Each row corresponds to an attribute that was selected. An Alias  is
used to make it easy to identify the attribute in the Cassandra
database (more on this later). The user can edit the alias to fit his
needs. Using the Remove button,
the attribute can be removed.

After filling all the necessary details of the profile, the user can
save the profile using the save button.
Once the profile is saved, it will be automatically scheduled.

Accessing the published data

The published data can be viewed using the Cassandra Explorer.

Cassandra explorer src="/files/Cassandra%20explorer.png">

The user first needs to connect to the cluster that the data was
published to.

alt="Cassandra Explorer connect screen"

Then entry to access the data that was published can be found under the EVENT_KS. The name would be
displayed in the org_wso2_jmx_agent_TheNameOfTheProfile

Event_KS src="/files/event_ks.png">

After clicking on the relevant entry, the user will be redirected to
the page where the data that was dumped is displayed. By clicking on view more the user can view the
details of an event that has been published. Following is an example

published data src="/files/published_data_res.png">

The alias that the user gave when creating the profile can be seen with
the payloads (circled in black).

Editing a profile

A profile can be edited by clicking on the profile name or the edit button in the index page. The Data receiver information and JMX server information can be edited
using this option. When saving the changes made to a profile using the save button, the user will be asked
to decide whether to increment the version of the profile or not.

alt="Increment version confirmation"

The version of the profile is used to indicate the difference after
editing a profile. If the version of the profile is incremented, a new
stream definition will be created for the profile on the next time the
data is being published. This is specially useful when the user needs
to update the stream definition when the attributes that are being
monitored are changed.


WSO2 BAM ships with a toolbox that allows the user to monitor various
details on CPU usage, non-heap and heap memory usages of the local server
with the the help of the JMX agent.

Setting up

It's pretty easy to set-up the toolbox. First the user needs to deploy the
JMX monitoring profile using the "Deploy
toolbox profile" link in the JMX agent home page

alt="Deploy Toolbox profile"
src="/files/deploy toolbox profile.png">

When that link is selected, a new profile will be added to the profiles
list named "toolbox". Once enabled, this profile will periodically monitor the attributes
that are needed by the toolbox and will publish them to the Cassandra database.

alt="Toolbox profile deployed"
src="/files/toolbox prof deployed.png">

Then the user can deploy the toolbox from the toolboxes menu in WSO2 BAM

Monitoring a different server

The toolbox can be used to monitor not only WSO2 Carbon based servers, but also
any Java process that exposes the attributes mentioned in the following table.
The user needs to set the aliases according to the table so that the Hive
queries used in the toolbox can properly map them to its database.

MBean Attribute Alias
java.lang:type=Memory HeapMemoryUsage - committed heap_mem_committed
java.lang:type=Memory HeapMemoryUsage - init heap_mem_init
java.lang:type=Memory HeapMemoryUsage - max heap_mem_max
java.lang:type=Memory HeapMemoryUsage - used heap_mem_used
java.lang:type=Memory NonHeapMemoryUsage - committed non_heap_mem_committed
java.lang:type=Memory NonHeapMemoryUsage - init non_heap_mem_init
java.lang:type=Memory NonHeapMemoryUsage - max non_heap_mem_max
java.lang:type=Memory NonHeapMemoryUsage - used non_heap_mem_used
java.lang:type=OperatingSystem ProcessCpuTime processCpuTime
java.lang:type=OperatingSystem AvailableProcessors availableProcessors
java.lang:type=Runtime Uptime uptime


If a tenant needs to monitor JMX attributes using the JMX agent, the
carbon.xml file located in CARBON_HOME/repository/conf should be edited. This
is done to make the rmi context available to all tenants. There will be a
section in the file as follows.

!-- Contexts that are common to all tenants --> <AllTenants>
<UrlContext> <Scheme>java</Scheme>
</UrlContext><!-- <UrlContext>
</UrlContext> --> </UrlContexts>

The rmi context needs to be added to this. Adding the following
lines would do the trick

<UrlContext> <Scheme>rmi</Scheme>

Different use cases

Publishing the monitored data to WSO2 BAM is not the only use case for the JMX agent . The JMX agent can be used with many other data received in WSO2 Carbon based servers. As an example, a JMX monitoring profile can be configured to publish data to WSO2 Complex Event Processor (WSO2 CEP) so that, that data can be analyzed using WSO2 CEP for any server behavior abnormalities such as CPU and memory usage spikes and take particular actions depending up on the scenario.


The JMX agent for WSO2 BAM is a convenient tool to monitor a set of JMX attributes and store that data in BAM for future analysis. WSO2 BAM can be used to store JMX related data that will span many years. When needed, this data can be conveniently accessed and analysed at a later date.


About Author

  • Ishan Somasiri
  • Intern
  • WSO2