MQ Queue Info
GENEOS MQ Queue Info Plugin monitors a specific queue associated with a specified queue manager on an IBM WebSphere MQ installation. The installation may be on either the same machine as the Plugin or, on a different machine, that is accessible across a network.
The MQ Queue Details Plugin produces a single view as follows:
|Queue Name||The name of the queue|
|Queue Type||The type of the queue|
|Queue Class||The class (System or Custom) of the queue - defined in the plugin configuration|
|Stagnant Message Count||The number of stagnant messages on the queue. A stagnant message is defined in the plugin configuration|
|Average Message Age||The average age in HH:MM:SS format|
|Oldest Message Age||The oldest age in HH:MM:SS format|
|Newest Message Age||The newest age in HH:MM:SS format|
|Write Message Rate||Number of messages per second written to the queue|
|Read Message Rate||Number of messages per second read from the queue|
|Writer Count||The number of processes writing to the queue|
|Reader Count||The number of processes reading from the queue|
|Queue Depth||The number of messages currently on the queue|
|Maximum Queue Depth||The maximum number of messages the queue can hold|
|Used Capacity||Percentage of queue capacity that is currently in use|
|Megabyte Capacity||The capacity of the queue in megabytes|
|Date Created||The date and time at which the queue was created|
|Date Modified||The date and time at which the queue was modified|
|Default Bind||The binding to be used if the queue is opened|
|Put Enabled||If messages can be put onto this queue or not|
|Get Enabled||If messages can be retrieved off this queue or not|
|Trigger Type||Specifies the condition that initiates a trigger event|
|Trigger Priority||Specifies the minimum priority that a message must have before it can cause or be counted for, a trigger event|
|Trigger Depth||Specifies(when trigger type is MQTT_DEPTH) the number of messages that will initiate a trigger message to the initiation queue|
|Trigger Control||Specifies whether trigger messages are written to the initiation queue|
|Transmission Queue Name||Transmission queue name|
|Cluster Name||The name of the cluster to which this queue belongs|
|Remote Queue Manager Name||Name of remote queue as known locally on the remote queue manager|
|Default Message Persistance||The default message persistance|
|Trigger Data||The trigger data for the queue|
|Process Name||The process name for the queue|
Before running the MQ Queue Info plugin, 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 searches for the
mqic.dll client library file. On
Solaris/Linux, the libmqic.so client
library file must be available. If using a 64-bit
Netprobe the MQ client libraries must also be 64-bit.
Assuming these are installed, you may also be required
to set the
LD_LIBRARY_PATH environment variable to
point to the correct directory, e.g.
/opt/mqm/lib64. The name of the
library file (not path) can be changed if
required using the
variable, for example to
libmqic_r.so instead of
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 queue statistics, the Netprobe user must be granted the following permissions to operate, if it is not a member of the mqm administration group:
+connectpermissions on the Queue Manager object
+inqpermissions on the queue to be monitored
+browsepermissions on the queue to be monitored, if message statistics are required
mq-qinfo queueManagerName data: mqServer: queueName: data: hideUnavailable: stagnantMessageAge:
The following parameters can be configured for this plugin:
This is normally set by the admin as an environment variable and determines which channel to use to connect to queue managers on different machines. If the user specifies a different value then that value is used in preference to the environment variable. Thus queue managers on multiple machines can be connected to from different sampler instances. If it is not defined, the environment variable is used instead.
A message is defined as stagnant if is stays in the queue for longer that the value of this parameter.
When set to -1 no messages are considered stagnant.
The number of seconds to calculate message statistics, such as the stagnant message count, the average message age and the oldest message age.
SSL connections to an MQ server can be achieved by using an MQ channel table file, and associated SSL key database. The location of these files should be configured in the Netprobe environment, which are then used by the MQ client library to establish a connection.
The expected environment variables are:
- MQCHLLIB - absolute path to the directory containing the channel table file
- MQCHLTAB - name of the MQ channel table file (including the .TAB extension)
- MQSSLKEYR - absolute path to the SSL key database, but excluding the (.KDB extension)
When connecting via SSL, the MQSERVER setting should not be set, either in the plugin configuration or as an environment variable.
It is possible to configure MQ Queue Info to connect to the MQ Server using a specified client side security exit and passing the Remote User Identifier and Remote Password.
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.
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.
Security Connection Authentication
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.
Note: This setting only works if the mqServer setting is configured.
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.
Note: This setting only works if the mqServer setting is configured.
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.