A web-based monitoring tool for IBM WebSphere MQ


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


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


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.


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

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.


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.


To customize settings, unpack the WAR file, find the 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 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.

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

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:

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


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.

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:

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:

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.

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:

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:

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.

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.

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:

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.


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.


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.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=A web-based monitoring tool for IBM WebSphere MQ