MQ Queue Plug-In
The MQ Queue plug-in is part of a suite of plug-ins designed to monitor an IBM WebSphere MQ server. MQ is a middleware product which allows independent client programs to communicate by passing messages to each other via a Message Queue. These queues provided added benefits by adding reliability of communications, and storing and persisting messages allowing client programs to operate asynchronously.
The MQ Queue plug-in monitors all configured queues for a particular Queue Manager (an MQ system service which holds a set of queues). Using the Geneos framework administrators can set alerts for events such as a queue approaching its maximum number of messages, or to ensure that the expected number of producers and consumers are connected to the queue. Additionally, database logging of monitored metrics allows these figured to be used later in calculating trends and aid in capacity planning.
Websphere MQ servers are based around queues of messages, each Message containing some arbitrary application data. Messages are contained within Queues, which are in turn managed by a Queue Manager. An MQ server may contain several queue managers.
Client applications communicate with each other by sending messages via a queue. To do so they connect to a queue manager - typically using TCP/IP - and send or receive messages accordingly.
Communication between components are handled using pre-configured links called Channels. Channels are mono-directional, so a full-duplex link between two components requires two channels.
A queue manager also has an associated Command Server, which allows a remote client to execute commands. The MQ Queue plug-in connects as a client to the configured queue manager, and obtains monitoring data by issuing status query commands using the command server.
MQ Queue produces a single dataview displaying the
configured queues for the queue manager it is
connected to, and the selected attributes for each
view. By default these attributes are the same as
those reported by a
QSTATUS command. An example of this is
The legends below list all columns which can be configured for the plug-in. For a more in-depth discussion of columns, please see the columns configuration section.
|mqServer||Displays the connection details used to connect to the MQ server.|
|mqChannelTable||Displays the MQ channel table file used to connect to the MQ server.|
|queueManager||The name of the queue manager the plug-in is connecting to.|
|connectionStatus||The current connection status (
|samplingStatus||The current status of the plug-in.|
|name||Name of the queue being monitored.|
|queueType||Type of queue, one of
|queueDefinition||Indicates how the queue was defined, one of
|description||A user-configured description of the queue.|
|maxQueueDepth||Maximum queue depth (number of messages).|
|currentQueueDepth||Current number of messages on the queue.|
|percentQueueDepth||Current queue depth as a percentage of the maximum.|
|maxQueueCapacity||Maximum queue capacity shows the maximum
amount of data a queue can contain, calculated
|creationDate||Date the queue was created, in the form
|creationTime||Time the queue was created, in the form
|creationDateTime||A concatenation of the
|alterationDate||Date the queue definition was last altered,
in the form
|alterationTime||Time the queue definition was last altered,
in the form
|alterationDateTime||A concatenation of the
|remoteQueueManager||Name of the remote queue manager hosting the remote queue.|
|remoteQueue||The local queue name on the remote queue manager, for a remote queue.|
|transmitQueueName||Name of the transmission queue, for a remote queue.|
|inhibitPut||Whether put operations are allowed for the
queue - values are
|inhibitGet||Whether get operations are allowed for the
queue - values are
|defaultPersistence||The default message persistence for this
queue - values are
|msgEnqCount||Number of enqueued messages put on the queue but not committed, at the time of a queue statistics reset.|
|msgDeqCount||Number of dequeued messages got from the queue but not committed, at the time of a queue statistics reset.|
|highQueueDepth||Maximum number of messages on a queue, at the time of a queue statistics reset.|
|timeSinceReset||Time in seconds since the queue statistics were last reset.|
|oldestMsgAge||Age of the oldest message on the queue in seconds.|
|openInputCount||Number of input processes which are using the queue (an input process GETs messages from the queue).|
|openOutputCount||Number of output processes which are using the queue (an output process PUTs messages on the queue).|
|lastGetDate||Date a message was last taken from the
queue, in the form
|lastGetTime||Time a message was last taken from the
queue, in the form
|lastGetDateTime||A concatenation of the
|lastPutDate||Date a message was last put on the queue,
in the form
|lastPutTime||Time a message was last put on the queue,
in the form
|lastPutDateTime||A concatenation of the
|queueTimeIndicator||Indicator of the amount of time a message stayed on the queue. Two comma-separated values are displayed, showing the message time in microseconds averaged over a short and longer periods of time.|
|stagnantMsgCount||Number of stagnant messages on the queue. A message is considered stagnant if it is older than a user-defined time period.|
|averageMsgAge||The average message age (in seconds) of all messages on the queue at the time of sampling.|
|newestMsgAge||The age of the newest message on the queue in seconds.|
|processName||Name of the process servicing the queue.|
|clusterName||Name of the cluster to which the queue belongs.|
|triggerData||Additional data appended to the trigger message when a trigger event occurs.|
|triggerControl||Controls whether trigger messages are
created to start an application to service the
queue. Values are
|triggerDepth||The number of messages of priority
|triggerMessagePriority||Message priority threshold for trigger message creation. Values are positive integers, with 0 being the lowest priority.|
|triggerType||Controls the conditions under which a
trigger message is created. Values are
|defaultBind||The default binding used when a client
connects to a queue, and the queue is part of a
cluster. Values are On
|usage||Indicates the queue usage, either
Before running the MQ Queue plug-in, you must first install the IBM WebSphere MQ Client v7.1 (or greater) software on the machine which the Netprobe will run on. This client comes as part of the MQ software bundle and must be installed correctly - simply copying across the DLLs or shared object files will typically result in a 2012 (MQ environment) error.
On Netprobe. This is usually
done by ensuring that the directory in which this
library resides is configured on the
variable available to the Netprobe.
On Solaris/Linux, the libmqic.so
library needs to be available to the Netprobe. This is
usually done by ensuring that the directory in which
this library resides is configured on the
LD_LIBRARY_PATH environment variable available to the
On AIX, the libmqic.a library needs
to be available to the Netprobe. This is usually done
by ensuring that the directory in which this library
resides is configured on the
environment variable available to the Netprobe.
In order to gather status commands, the MQ command server must be running. Additionally, the Netprobe user must be granted the following permissions to operate, if it is not a member of the mqm administration group:
+connect+dsppermissions on the Queue Manager object
+put+inqpermissions on the
SYSTEM.ADMIN.COMMAND.QUEUE. If using the send queue parameter, these permissions should be set on the named queue alias instead.
+dsppermissions on the
SYSTEM.DEFAULT.MODEL.QUEUE. If using the receive queue parameter, the permissions
+get +dsp+put+inqshould be set on the named queue instead.
In addition certain columns will need additional permissions to be granted on each queue to be monitored as below. The table in the column setting section describes which columns are of which type.
- Inquire Queue Status columns require no extra permissions.
- Inquire Queue columns require
+dsppermissions on each queue.
- Reset Queue Statistics columns require
+dsp+chgpermissions on each queue.
- Browse Queue columns require
+browsepermissions on each queue.
It is also advisable to enable queue monitoring to
gather status data, either for the queue manager as a
whole or the individual queues which will be monitored.
This can either be done from the WebSphere MQ Explorer,
or by issuing the following commands in
alterqmgr monq(medium)to enable monitoring for all queues on the queue manager with
alterqlocal(queueName)monq(medium)to enable monitoring for a specific queue.
Note: If you are using a very short sample interval for your plug-in, it is advised to increase the rate of data collection in MQ from medium to high.
The following parameters can be configured for this plug-in:
The connection section describes how the MQ Queue plug-in will connect to the MQ server. There are two ways to configure a connection:
- Configure an inline connection using the MQSERVER variable.
- Configure a connection using a channel table.
If multiple different configuration settings and environment variables exist, MQ Queue will choose a configuration using the following order:
- Using the file specified in the mqChannelTable setting.
- Using the file specified by the
MQCHLTABenvironment variables. In this case, variables configured in the managed entity section will be used in preference to those configured in the Netprobe start script.
- Using the connection details specified in the mqServer setting.
- Using the connection details specified in the
MQSERVERenvironment variable. In this case if the variable is configured in the managed entity section it will be used in preference to a value configured in the Netprobe start script.
If no connection details are supplied, an error message will be produced in the Netprobe log and in the samplingStatus headline of the sampler dataview.
This section contains the connection details
used by the MQ Queue plug-in to connect to the MQ
server. If not specified, the plug-in will fall
back to using the environment variables
MQCHLTAB, or if not specified
These environment variables may be specified either in the managed entity configuration, or in the Netprobe start script.
connection > mqServer
The MQ server setting informs the plug-in how to
connect to the MQ server. It consists of a channel
name, transport type and hostname/port - e.g.
If set this setting overrides the value of the
MQSERVER environment variable.
If the mqChannelTable setting
has been configured it will be used in preference
to this setting.
Please see the IBM documentation for further details on the MQSERVER environment variable.
connection > mqChannelTable
The MQ channel table setting allows you to specify the location of a channel table file. This file is created when you define a client-connection channel on your queue manager. MQ clients (including the MQ Queue plug-in in Netprobe) can use the channels within the file to connect to an MQ server.
To configure this setting specify the full path
to the channel table. This will then be used over
MQCHLTAB environment variables
(if set). It will be also used in preference to the
mqServer setting or the
Please see the IBM documentation for further details on the MQCHLLIB and MQCHLTAB environment variables.
connection > ssl
This sub-section contains details relating to SSL-secured connections to an MQ server.
Note: If using SSL connections, it is recommended that all MQ plug-ins running on that Netprobe use the same connection details. The reason for this is that the MQ API only supports a single SSL connection instance per process, and so if using multiple different SSL configurations only the first plug-in will connect successfully.
connection > ssl > keyRepository
This setting configures the location of the SSL key repository, which is used when establishing an SSL connection to an MQ server. The key repository contains SSL certificates, and should be created and managed using the IBM key manager utility.
To use this setting specify the full path of the
key repository file. It is recommended to exclude
the file extension (.kdb) for this value, so that
it matches the syntax of the
The value of this setting is only required when using SSL connections. These can be specified in two ways:
- By configuring the mqServer setting (or
MQSERVERenvironment variable) and also configuring the cipherSpec setting.
- By using a channel table (mqChannelTable setting
MQCHLTABenvironment variables) which specify an SSL connection.
If specified, this setting will override the
value in the
MQSSLKEYR environment variable.
For more details on this variable, please consult
this IBM documentation page.
connection > ssl > cipherSpec
This setting is used when the connection is
configured using the mqServer setting or
MQSERVER environment variable.
If configured, this setting specifies the SSL
encryption which will be used to secure the
connection, subject to SSL certificate checks.
The value of this setting can either be typed in directly, or selected from the following list of options:
For more information on cipher specs with MQ, please consult this IBM documentation article.
connection > mqSender
This setting allows the user to specify the name
of the queue to send commands on, for execution by
the command server. If not specified, the plug-in
will send requests for monitoring data (commands)
using the default name
In practise this setting need not be defined unless the MQ server has been configured with a non-default command queue name.
connection > mqReceiver
This setting allows the user to specify the name
of a (permanent) queue to receive command results
(monitoring data) from, following execution by the
command server. If not specified the plug-in will
use the default behaviour of the IBM MQAI library,
which is to create a new dynamic queue for the
reply (based on the
which is automatically deleted after use.
Users may wish to configure this setting if they are having problems with command results being placed on the dead letter queue. These "dead" messages contain stale monitoring data and so are safe to delete, but their creation can be avoided by use of a permanent reply queue. Use of a permanent reply queue can avoid also the (small) cost of creation/deletion of a dynamic reply queue.
When using a permanent queue only a single queue
per MQ server instance is required (although you
may use additional queues as required). The
Netprobe user will require a minimum of
+get+dsp +put+inq permissions on the queue
to operate correctly. The queue can safely be
shared by multiple MQ plug-in instances (either
running on the same or different Netprobes) as each
MQ plug-in will obtain its own monitoring data from
the queue using a correlation id. The depth of the
permanent queue should remain at (or close to) 0.
Any messages on the queue older than a few minutes
may be safely deleted.
connection > securityExitConfig > securityExit
This setting allows the user to specify a client side security exit to use when authenticating with the MQ server. See the IBM documentation for the SecurityExit field on the MQCD structure for more information.
Note: This configuration will only work with MQServer. If a channel table is used in the configuration then the settings here will be ignored.
connection > securityExitConfig > remoteUserIdentifier
This setting allows the user to specify the Remote User Identifier that will be sent to the client side security exit and the server when authenticating. Only the first 12 characters will be used, see the IBM documentation for the RemoteUserIdentifier field on the MQCD structure for more information.
connection > securityExitConfig > remotePassword
This setting allows the user to specify the Remote Password that will be sent to the client side security exit and the server when authenticating. Only the first 12 characters will be used, see the IBM documentation for the RemotePassword field on the MQCD structure for more information.
connection > securityConnectionAuthenticationConfig > username
This setting allows the user to specify a username in order to connect to the MQ server which supports Security Connection Authentication. The username provided does not need to be part of the mqm group. But keep in mind that the user running the Netprobe should have been given the default MQ user permissions. This includes having the user added to the mqm group, authorised to connect to the Queue manager, channel, and queue. As the netprobe user would be the one used for MQ authorisation checks. But if ADOPTCTX attribute is set to YES then the Connection Authentication username provided would be used instead throughout the connection. See the IBM documentation on MQCSP password protection and on Connection Authentication: Configuration for more information.
Note: The Security Connection Authentication is applicable only to IBM MQ Version 8.0. If the version is lower than 8.0 then this configuration will have no bearing.
connection > securityConnectionAuthenticationConfig > password
This setting allows the user to specify the password for the given username that will connect to the MQ server which supports Security Connection Authentication. See the IBM documentation on MQCSP password protection and on Connection Authentication: Configuration for more information.
By default MQ Queue will monitor all queues on the configured queue manager. The queues section allows users to configure a set of queues they are interested in, thereby filtering the results returned and also reducing the processing that the plug-in must perform.
This setting specifies the name of the queue manager the plug-in is to connect to. If a channel table is used, then this name should match the one specified for the connection.
The queues section specifies the queues that will be monitored by the plug-in. By default, if no queues are specified then the plug-in will monitor all queues on the queue manager.
queues > queue
Specifies a queue (or queues for a generic name) for the MQ Queue plug-in to monitor. If no queues are specified all queues on the queue manager will be monitored.
queues > queue > matches
This setting specifies an exact queue name. If this queue is found on the queue manager, it will then be monitored.
queues > queue > startsWith
This setting specifies a prefix for a queue name. All queues on the queue manager starting with the specified value will be monitored.
The startsWith setting uses the generic queue
names feature of the command server. For example,
if you entered
AMQ then the queues monitored
by MQ Queue would be the same as those returned
when you issue the command
DISPLAY QSTATUS(AMQ*) using
runmqsc MQ utility. You may
also add the trailing * in the setting value if you
wish to match the standard MQ syntax.
By default, MQ Queue will display columns showing
the same data as you would see when executing the
DISPLAYQSTATUS command in the
runmqsc MQ utility. The columns
section allows users to configure a set of columns
that they wish to see, and ignore data which is not
relevant for their particular monitoring
The columns section specifies the columns which
will be produced by the MQ Queue plug-in. Columns
appear in the order in which they are configured.
The (queue) name column is always present as the
first column. If no columns are specified, then
columns showing data from the
DISPLAY QSTATUS command
will be displayed by default.
columns > column
The column setting configures a single column which will be displayed in the resulting dataview. For a description of what each column shows, please see the view section table legend.
Columns will be added to the dataview in the order in which they are configured. If a column has already been added, then a duplicate entry will be ignored. Columns may also be ignored if the disableQueueResetAttributes or disableQueueBrowseAttributes settings have been enabled.
Column data comes from various MQ attributes obtained by executing commands. These commands will only be run if the column that requires this data has been configured. The commands which may be run include:
- Inquire queue - obtains queue configuration values
- Inquire queue status - obtains information about the current status of the queue.
- Reset queue statistics - resets queue statistics, giving count values since the last reset.
- Browse queue messages - browses messages on a queue to calculate statistics.
If using columns taking data from queue status attributes, you should enable queue monitoring as described in the prerequisites section of this document otherwise no values will be returned.
Note: Resetting queue statistics affects all applications using reset statistics on that queue. In particular, monitoring the same queue from two different instances of MQ Queue (perhaps running on different gateways) will produce unexpected results since the values returned will not be over the sample interval, but from the last reset time.
The following table shows which command is run to obtain data for each column. Some columns can obtain the same data from multiple commands - in this case MQ Queue will choose which command to run, in order to minimise the total number of commands run.
|Column||Queue||Queue Status||Reset Queue||Browse|
Further descriptions of the attributes used can be found at the following IBM documentation pages:
A "reset queue statistics" command is issued for each monitored queue if any of the following columns has been configured:
If this setting is enabled (set to true) then the MQ Queue plug-in will not issue a "reset queue statistics" command. Also if any of the above columns have been configured, they will not be displayed (since they will not be populated with data).
In order to calculate message statistics such as the average message age, it is necessary to browse (the headers of) all messages in a queue. Queue browsing occurs if any of the following columns have been configured:
For queues with a large number of messages this can be a time consuming process. If this setting is enabled (set to true) then the MQ Queue plug-in will not browse queue messages. Also if any of the above columns have been configured, they will not be displayed (since they will not be populated with data).
This setting sets a threshold (in seconds) over which a message will be considered stagnant, and will then be counted in the stagnantMsgCount column. For example if the value of this setting is 60, then any messages on the queue over a minute old will be considered stagnant.
A value of 0 disables this threshold, meaning no messages are considered stagnant (and so the stagnantMsgCount column will always show 0). Since 0 is the default value for this setting, the user should always configure this setting if they intend to use the stagnantMsgCount column.
The debug section contains settings used for debugging purposes. You may be asked to configure these by ITRS support if you are having issues with the MQ Queue plug-in, in order to diagnose the problem.
The debug section contains debugging settings for the MQ Queue plug-in. Typically users should not need to configure any setting in this section.
debug > sampleTimeout
The sample timeout controls the number of seconds MQ Queue will spend during a sample, before it gives up and displays any data obtained so far. This setting typically only comes into effect if the MQ server is slow to respond to queries, which may happen during times of heavy load.
debug > disableBrowseTimeAdjust
When using columns that obtain data by browsing the messages on a queue, the message headers give the time the message was placed on the queue in server time. Calculations for the newest or average message age then compare this time against the local time of the Netprobe machine, introducing a possible source of error if the times are not synced between machines.
To compensate for this, the MQ Queue plug-in also requests the oldest message age using the queue statistics command. This value is then compared with the oldest message age computed using the local time, and any offset is used to adjust the resulting values accordingly.
This adjustment can be disabled by configuring this setting to true.
debug > browseWarnThreshold
The browse warn threshold is used to warn when a message browsing operation may take a long time due to a large number of messages on the queue. Enable this setting to adjust how many messages must be present on a queue before a warning is produced. A value of 0 disables all warnings.
debug > output
The debug output settings enable additional output which is sent to the Netprobe log file.
debug > output > setup
If enabled, this Boolean setting produces output regarding the results of the sampler setup parsing.
debug > output > mqApi
If enabled, this Boolean setting produces output regarding the results of all MQ API calls made by the plug-in.
debug > output > connection
If enabled, this Boolean setting produces output regarding connection attempts, successes and failures to aid in debugging connection issues.
debug > output > commands
If enabled, this Boolean setting produces output regarding commands being executed by the plug-in.
debug > output > results
If enabled, this Boolean setting produces output regarding the results processing of a successful command execution.
MQ Connection Backoff
This section describes the mechanism to prevent MQ connections after a certain number of consecutive failures.
By default, MQ plugins will continually attempt connections to the MQ server, even after connections have continually failed. To prevent this, connectionFailureThreshold and connectionFailureStopTime can be configured to manage MQ connection backoff. These configurations are located under the Probe configuration's advanced tab (refer to Gateway2 Reference Guide). Setting these configurations will put into place a mechanism which will prevent MQ connections from being attempted after a given number of failures.
The connectionFailureThreshold is the maximum number of failures that can be allowed before initiating an MQ connection backoff. Once a backoff has been started, the netprobe will try to reconnect only after the indicated connectionFailureStopTime in seconds has been reached. If reconnection is successful, MQ connections will work normally. If reconnection is unsuccessful, backoff for the indicated time in connectionFailureStopTime will be once again put into effect.
These configurations are shared across several MQ plugins using the same connection in the same probe. This means that the count for consecutive failures will be counted against each unique MQ connection and not in each sampler.
This example shows the bare minimum configuration for MQ Queue. This example assumes that the connection details are configured as environment variables. As no queues and columns have been specified, all queues on the queue manager will be monitored for their status statistics.
<sampler name="minimal"> <plugin> <mq-queue> <queueManager><data>QMname</data></queueManager> </mq-queue> </plugin> </sampler>
SSL connection using MQSERVER setting
The following example shows how to configure MQ Queue to connect using an SSL connection in conjunction with the MQSERVER variable. This is done by specifying an SSL cipher for encryption, and the location of the SSL certificate key repository.
The example also shows a configuration for queues,
selecting all queues starting
TRD.PRD1 and the specific queue
<sampler name="sslMQSERVER"> <plugin> <mq-queue> <connection> <mqServer><data>CHAN/TCP/host(port)</data></mqServer> <ssl> <keyRepository><data>/var/mqm/ssl/key</data></keyRepository> <cipherSpec><data>TRIPLE_DES_SHA_US</data></cipherSpec> </ssl> </connection> <queueManager><data>QMname</data></queueManager> <queues> <queue> <matches><data>SYSTEM.DEAD.LETTER.QUEUE</data></matches> </queue> <queue> <startsWith><data>TRD.PRD1</data></startsWith> </queue> </queues> </mq-queue> </plugin> </sampler>
Channel table file connection
This example shows how to configure MQ Queue to use a channel table to connect to the MQ server. If the channel table configuration requires SSL, then you will also need to configure the location of the key repository. Additionally, any security exit configuration in the sampler will be ignored.
This example also shows the use of the columns setting to select a set of columns for display.
<sampler name="channelTableFile"> <plugin> <mq-queue> <connection> <mqChannelTable><data>/var/mqm/AMQCLCHL.TAB</data></mqChannelTable> </connection> <queueManager><data>QMname</data></queueManager> <columns> <column>queueType</column> <column>queueDefinition</column> <column>maxQueueDepth</column> <column>currentQueueDepth</column> <column>percentQueueDepth</column> <column>openInputCount</column> <column>openOutputCount</column> <column>remoteQueueManager</column> <column>remoteQueue</column> <column>transmitQueueName</column> </columns> </mq-queue> </plugin> </sampler>