A web-based monitoring tool for IBM WebSphere MQ

QianLi Jin (jinql@cn.ibm.com) April 06, 2016

Senior Software Engineering Manager (First published November 06, 2013)
IBM

ZiHan Tang (zhtang@cn.ibm.com)

WebSphere MQ Software Engineer
IBM

Bin Zhang (zhbinbj@cn.ibm.com)

WebSphere MQ Software Engineer
IBM

This article shows you how to use a simple, downloadable, web-based monitoring tool for IBM®
WebSphere® to provide visualization and custom alert conditions for WebSphere MQ objects,
including channels, listeners, topics, queues, and queue managers.
Editor's note (April 2016): This article is updated with a new Downloads section that contains
a zip file of the IBM WebSphere MQ monitoring tool, documentation, and scripts. The original
article hosted these resources on Github.

Introduction
This article shows you how to use a simple web-based monitoring tool for IBM® WebSphere®
MQ available in the Download section. The article targets WebSphere MQ administrators and
users who would like to take advantage of the monitoring tool features, such as visualization of
WebSphere MQ system health and custom alert conditions for WebSphere MQ objects, including
queues, topics, channels, listeners, and queue managers.

Monitoring tool features

• Monitor multiple queue mangers on multiple hosts.
• Monitor MQ objects using relevant statistics and custom settings. For example, you can
monitor the currentQDpeth of ORDERS.QUEUE and display the status in a line chart.
• Define alert condition rules for each monitor to track the health status of an MQ object.
• Display all alerts in a table in the web UI, and enable query alerts using specific criteria.
• Deactivate and reactivate monitors as needed.
• Persist historical monitoring statistics in a database with specified time ranges.

© Copyright IBM Corporation 2013, 2016 Trademarks

A web-based monitoring tool for IBM WebSphere MQ Page 1 of 20
developerWorks® ibm.com/developerWorks/

• Provide multiple dashboards with multiple patterns to aggregate a set of monitors.

The monitoring tool supports two patterns:

• Simple pattern: allow any monitors.

• Sender-receiver pattern: only allow two queue monitors and two channel monitors.

Statistics for monitored MQ objects and overall system status are displayed in real-time charts on
a dashboard:

• Monitor MQTT client connections

• Test connectivity of MQTT clients
• Simple and flexible deployment of Java® servlet containers
• Configurable database for storing statistics

Architecture
• Back-end: Java™ standard web application
• Front-end: Dojo based web UI.
• Database: IBM DB2®, embedded Derby (the default), MySQL®, and Oracle®.
• Development: The monitoring tools was developed using the Dojo Toolkit.

Deployment
This monitoring tool is easy to install, because it is implemented as a standard Java web
application. You can easily deploy it on any Java EE application server or any Java servlet engine.
After deployment, the monitoring application is up and running.

Prerequisites
Make sure you have the following software installed before installing the WebSphere MQ
monitoring tool.

• Install WebSphere MQ V7.1 or later.

A web-based monitoring tool for IBM WebSphere MQ Page 2 of 20

ibm.com/developerWorks/ developerWorks®

• Install a Java EE application server, such as WebSphere Application Server for Developers,
or a servlet engine, such as Apache Tomcat, that supports Servlet 2.5 or later.

For information on installing WebSphere MQ or a Java EE application server, see Installing

WebSphere MQ, Installing WebSphere Application Server, or similar information for another Java
EE application server or servlet engine.

Installation
Deploy the monitoring application as a WAR file to a Java EE application Server or servlet engine.
For customization, you unpack the WAR file, modify the configuration files as needed, and
redeploy.

Configuration
To customize settings, unpack the WAR file, find the config.properties file in the WEB-INF
directory, and update application-specific settings according to the comments inside this
configuration file. Edit the file carefully, because invalid settings may prevent the monitoring
application from starting up.

The monitor uses an embedded Apache Derby database by default. To configure the database
or use a different one, unpack the WAR file, find the jdbc.properties file in the WEB-INF directory,
and edit the configuration file to switch to your preferred database. You will also need to drop the
corresponding database driver JAR file to the WEB-INF/lib directory. The monitor uses Apache
OpenJPA as a persistence provider, so any database supported by Apache OpenJPA should work.
The database schema is automatically generated when the monitor starts up. For heavy data
loads, consider switching to a more powerful database such as MySQL, because Apache Derby
may not work very well when many monitors are running with large volumes of data are being
collected.

Login and passwords

The monitor requires login and authentication. Enter the default userID/password of mqadmin/
mqadmin and then click Login. After your first login, you are redirected to the home page, where
you should immediately change the password to something more secure.

To log out, click Username at the upper right of the homepage, click Sign out from the dropdown
list, and then click OK to confirm. If you do not log out and do not use the tool for an extended
period, it will log you out automatically and ask you to log in again.

To change your password, click Username at the upper right, select Edit profile from the
dropdown list, enter your current password and new password, and the click Save to confirm the
change.

Creating a connection
Click the Connection tab to monitor a queue manager.

A web-based monitoring tool for IBM WebSphere MQ Page 3 of 20

developerWorks® ibm.com/developerWorks/

Connection tab

Click New QM Connection to create a connection which stands for a connection to a queue
manager.

Create connection dialog

The following connection metadata is required to connect to a remote queue manager:

• Name -- Unique identifier for a connection.

A web-based monitoring tool for IBM WebSphere MQ Page 4 of 20

ibm.com/developerWorks/ developerWorks®

• Server Host -- Host of the Queue Manager you are trying to connect.
• Server Port -- Listening port of the Queue Manager you are trying to connect.
• Server Connection Channel -- Server connection channel of the Queue Manager.
• MQ User ID -- Authorized MCA User ID for the server connection channel.
• Description -- Basic description of the connection.

QueueManager tab

Once the queue manager is connected, the Monitors tab is available. And if the MQTT service of
the queue manager is Available, which means it is configured and started, the MQTT tab will be
available.

Creating a monitor
Click the selected connection to open a new tab named after the connection name, and then open
the Monitors tab:

A web-based monitoring tool for IBM WebSphere MQ Page 5 of 20

developerWorks® ibm.com/developerWorks/

Monitors tab

There are six buttons in the Monitors tab:

Toolbar in Monitors tab

• Add -- Open a dialog to create a monitor.

• Refresh -- Refresh all monitors of the current connection.
• Edit -- Select a monitor and open the property dialog to edit the monitor settings.
• Delete -- Select and delete a monitor.
• Activate -- Activate the monitor and start collecting data from queue manager.
• Deactivate -- Deactivate the monitor and stop collecting data from queue manager.

Click Add to open the Create Monitor dialog:

A web-based monitoring tool for IBM WebSphere MQ Page 6 of 20

ibm.com/developerWorks/ developerWorks®

Create Monitor Dialog

The monitor metadata includes the following information in order to monitor an MQ object:

• Monitor Name -- Unique identifier for a monitor.

• Monitor Category -- Category of a monitor: Queue, Topic, Channel, or Listener.
• Monitor Type -- Detailed MQ object type for a monitor.
• Monitor Measurement -- Property of an MQ object that is monitored.
• View Type -- View that the monitor will displayed: Line or Area.
• Monitor Object -- MQ object name that is monitored.
• Update Every -- Monitor view update frequency.
• Sliding Window -- Monitor view display interval: The latest N minutes, hours, or days are
displayed.
• Data Expiration Time -- How long to save historical data. After N minutes, hours, or days, the
data will be removed from the database.
• Alert Rule -- Rules used to evaluate the health of the monitored MQ object and generate
alerts that can be viewed in alert tab. An LDAP filter syntax is used, as shown below:
boolean-operator ::= '&' | '|'
operator ::= '>' | '<' | '>=' | '<=' | '!='
property ::= the value defined in the monitor measurement
dropdown list
value ::= most of cases are numeric values, and also there
are status values that are different from object
to object
expr ::= (property operator value)
alert-rule ::= warn(boolean-operator(expr)(expr)(expr)... ),
error(boolean-operator(expr)(expr)(expr)... )

A web-based monitoring tool for IBM WebSphere MQ Page 7 of 20

developerWorks® ibm.com/developerWorks/

Examples
Queue alert rule 1
Rule -- Warn(|(currentQDepth>1000)(openInputCount>100)), error(&(currentQDepth>30000)
(openInputCount>200))

Description -- Warning alert if currentQDepth>1000 or openInputCount>100; Error alert if

currentQDepth>30000 and openInputCount>200

Queue alert rule

Rule -- Warn(currentQDepth>1000), error(currentQDepth>4000)

Description -- Warning alert if currentQDepth>1000; Error alert if currentQDepth>4000

Topic alert rule

Rule -- warn(publishedMessagesCount>1000)

Description -- Warning alert if publishedMessagesCount>1000

Channel alert rule

Rule -- Warn(channelStatus=Stopped). Available channelStatus values are Stopped, Running,
Stopping, Inactive, Initializing, Binding, Starting, Paused, Retrying, and Requesting.

Description -- Warning alert if channelStatus is Stopped.

Listener alert rule

Rule -- Warn(listenerStatus=Stopped). Available listenerStatus values are Starting, Running,
Stopping, and Stopped.

Description -- Warning alert if listenerStatus is Stopped.

Queue Manager alert rule

Rule -- Error(queueManagerStatus=Unavailable). Available queueManagerStatus values are
Starting, Running, Quiescing, and Unavailable.

Description -- Error alert if queueManagerStatus is Unavailable.

Notes for these rules

An invalid property input to the alert rule prevents the monitor from evaluating the health of
the monitored MQ object. No validation is performed on the property and no alert message is
generated.

A web-based monitoring tool for IBM WebSphere MQ Page 8 of 20

ibm.com/developerWorks/ developerWorks®

Anther way to create a monitor is to right-click on the selected connection in the left navigation of
Connection tab, and the click Create Monitor from the dropdown menu.

Connection right-click menu

• Create Monitor -- Open the Create Monitor dialog.

• Edit Connection -- Open the Edit Connection dialog to edit connection property.
• Delete Connection -- Delete connection. If you delete the connection, all the related monitors
that are created in that connection are deleted as well.

Managing monitors
If create monitor succeeded, all monitors will be shown in the grid of the Monitors tab.

Monitors management

Select a monitor and click Activate to start the monitor or Deactivate to stop the monitor.

Monitoring MQTT clients

If an MQTT service is configured and started, the MQTT tab will be enabled:

A web-based monitoring tool for IBM WebSphere MQ Page 9 of 20

developerWorks® ibm.com/developerWorks/

Monitor MQTT clients

Toolbar actions:

• Filter -- Check box to enable or disable the MQTT filter search.

• Filter object -- Dropdown list. Select a filter object from client id, channel name,
connection name, or channel status.
• Filter string -- Input text box to enter filter string, with support for wildcards such as "*".
• Search -- Search MQTT client.
• Refresh -- Refresh search results.
• Previous page -- Previous 100 search results.
• Next page -- Next 100 search results.
• Monitor -- Click to open Monitor MQTT tab.

• If a filter object or string is changed, or a filter is enabled or disabled, click Search to refresh
the table below. Clicking Refresh only refreshes the latest search result.
• Each request can have up to 100 results, which are paged at the bottom of this tab.

Monitoring MQTT pub/sub

Click Monitor to open the Message tab to monitor MQTT:

A web-based monitoring tool for IBM WebSphere MQ Page 10 of 20

ibm.com/developerWorks/ developerWorks®

Message Tab

Click Configuration to add topics:

Add and Remove topics

This step is the same as Add/Remove monitors in Simple Dashboard. Select a topic from the
Topic dropdown list. The topic monitor will be activated automatically. The topic measurement is
published messages count, so when sending message to the selected topic, the monitor will be
updated accordingly.

A web-based monitoring tool for IBM WebSphere MQ Page 11 of 20

developerWorks® ibm.com/developerWorks/

Select a topic to monitor

Send message to topic or MQTT client

• Mode -- Message sending mode -- default is PubSub.

• Destination -- If mode is Pubsub, it lists all available topics. If mode is P2P, it lists all
available MQTT clients.

Select a destination, type text in the text box, and click Send. If the message is sent successfully,
the history record will be displayed in the box.

Creating a dashboard
A dashboard is the visual display of a set of monitors. A dashboard can apply a display pattern for
certain use cases. Currently, simple and sender-receiver patterns are supported. With the pattern,
the dashboard can display the monitors in a more appropriate way that better fits the business
scenario:

A web-based monitoring tool for IBM WebSphere MQ Page 12 of 20

ibm.com/developerWorks/ developerWorks®

Create dashboard

The dashboard metadata contains the following information:

• Name -- Unique identifier for a dashboard.

• Type -- Dashboard display pattern
• Simple -- Arbitrary monitors are allowed.
• SenderReceiver -- Only two queues and two channels are allowed.
• Description -- Basic description of the dashboard.

Simple dashboard
In this kind of dashboard, you can add arbitrary monitors:

A web-based monitoring tool for IBM WebSphere MQ Page 13 of 20

developerWorks® ibm.com/developerWorks/

Simple Dashboard

Click Add/Remove Monitors to manage monitors in this dashboard.

Add/Remove Monitors in Simple Dashboard

• Available Monitors -- All available monitors of all connections.

• Selected Monitors -- Existing monitors in this dashboard..
• >> -- Add available monitor to dashboard.
• << -- Delete existing monitor.

A web-based monitoring tool for IBM WebSphere MQ Page 14 of 20

ibm.com/developerWorks/ developerWorks®

If the monitor is inactive, click Activate in the center or at top right corner of each monitor.

Activate monitor in dashboard

Monitor chart:

Monitor title

• Title text -- Monitor object.

• Tooltip -- When you hover over the title text, the Tooltip shows the connection name and
monitor name.
• Penultimate field -- Status of latest monitor data.
• Last field -- Stop and deactivate the monitor.

The dashboard supports two kinds of charts: Line Chart and Area Chart. The Area Chart is
preferred for monitoring measurements such as channelStatus and listenerStatus.

A web-based monitoring tool for IBM WebSphere MQ Page 15 of 20

developerWorks® ibm.com/developerWorks/

Area Chart

Line Chart

Detailed information

The table at the bottom displays the detailed information for the monitor, refreshed every five
minutes. Click on the scroll button on the right to view more information.

SenderReceiver dashboard
The SenderReceiver Dashboard monitors a topical messaging scenario, with messages being sent
from a transmit queue via sender-receiver channels, and going to the target queue, which normally
is a local queue. When you monitor a transmit queue, you may also want to know the status of the
sender/receiver channel and the target queue that will receive the messages. The SenderReceiver
Dashboard shows you what's going on behind the scenes:

A web-based monitoring tool for IBM WebSphere MQ Page 16 of 20

ibm.com/developerWorks/ developerWorks®

SenderReceiver Dashboard

Click Add/Remove Monitors to manage monitors in the SenderReceiver Dashboard:

Add/Remove Monitors in SenderReceiver Dashboard.

Select monitors from the dropdown list and add or remove them for the specific position in the
dashboard as indicated above. Otherwise the SenderReceiver Dashboard is the same as Simple
Dashboard.

A web-based monitoring tool for IBM WebSphere MQ Page 17 of 20

developerWorks® ibm.com/developerWorks/

Alerts
The Alert tab collects all Alert messages generated by the active monitors, based on the Alert
conditions defined during monitor creation:

Alert Tooltip

The Tooltip displays the total of alert messages. It updates every 50 seconds.

Alert Tab

The Alert message table is refreshed each time it is accessed:

• Connection -- Connection in which the monitor is created.

• Monitor -- Monitor that generates the alert message.
• Level -- Alert level: Warn or Error.
• Rule -- Monitor alert rule item. A rule may contain several items.
• Result -- Alert reason that means that the condition is met.
• Time -- Time the alert message is generated.

Conclusion
This article showed you how to use a simple, downloadable, web-based monitoring tool for
WebSphere MQ to provide visualization and custom alert conditions for WebSphere MQ objects,
including channels, listeners, topics, queues, and queue managers.

Related topics IBM MQ Version 8.0 documentation IBM products: IBM MQ Forum:
WebSphere MQ IBM MQ and WebSphere MQ library

A web-based monitoring tool for IBM WebSphere MQ Page 18 of 20

ibm.com/developerWorks/ developerWorks®

Downloads
Description Name Size
WebSphere MQ Monitoring tool wmq-monitoring-0.2.2.zip 35.9MB

A web-based monitoring tool for IBM WebSphere MQ Page 19 of 20

developerWorks® ibm.com/developerWorks/

About the authors

QianLi Jin

QianLi Jin is a Senior Software Engineering Manager on the WebSphere MQ team

at the at the IBM China Development Lab in Beijing. He has worked on application
integration software development for years, and his areas of expertise include
application integration, connectivity solutions, and SOA. He has published one retail
book, one IBM Redbook, and several developerWorks articles. You can contact
QianLi at jinql@cn.ibm.com

ZiHan Tang

ZiHan Tang is a Software Engineer on the WebSphere MQ team at the IBM China
Development Lab in Beijing. Her technical expertise includes Web UI development
and testing. You can contact ZiHan at zhtang@cn.ibm.com.

Bin Zhang

Bin Zhang is a Software Engineer of the WebSphere MQ team at the IBM China
Development Lab in Beijing. Hia technical expertise includes Java EE development,
WebSphere MQ monitoring, and MQTT. You can contact Bin at zhbinbj@cn.ibm.com.

© Copyright IBM Corporation 2013, 2016

(www.ibm.com/legal/copytrade.shtml)
Trademarks
(www.ibm.com/developerworks/ibm/trademarks/)

A web-based monitoring tool for IBM WebSphere MQ Page 20 of 20