MQ Queue Info
Introduction Copied
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.
View Copied
The MQ Queue Details Plugin produces a single view as follows:
Table Legend
| Name | Description |
|---|---|
| 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 |
Prerequisites Copied
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 Windows, the 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 MQ_LIBRARY_FILE environment variable, for example to libmqic\_r.so instead of libmqic.so.
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 LD_LIBRARY_PATH or LIBPATH 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
Plugin Configuration Copied
mq-qinfo queueManagerName data: mqServer: queueName: data: hideUnavailable: stagnantMessageAge:
The following parameters can be configured for this plugin:
queueManagerName Copied
The name of the queue managed to connect to
Mandatory: Yes
mqServer Copied
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.
Mandatory: No
Note
MQ QInfo does not accept single quotes in the MQ Server address.
queueName Copied
The name of the queue which is to be monitored.
Mandatory: Yes
hideUnavailable Copied
Whether fields whose value cannot be retrieved should be displayed or not. If it is not defined it defaults to false.
Mandatory: No
Default: false
stagnantMessageAge Copied
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.
Mandatory: No
Default: -1
statsCalcTimeOut Copied
The number of seconds to calculate message statistics, such as the stagnant message count, the average message age and the oldest message age.
Mandatory: No
Default: 30
SSL Connections Copied
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.
Security Exit Copied
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 Copied
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.
Mandatory: No
connection > securityExitConfig > remoteUserIdentifier Copied
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.
Mandatory: No
connection > securityExitConfig > remotePassword Copied
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. Choose the appropriate field when specifying the password:
stdAES— use this to input your plaintext password. If you selectstdAES, you can define your password directly in the sampler and store it in standard AES encryption hash in the Gateway.var— use this to pass the password as a variable. The variable is defined in Managed entity > Advanced > Var. This is useful for situations where you have multiple samplers that use the same credentials.extPwd— use this for passwords provided by an external provider. For more information, see Securing your Gateway with an external password provider in Secure Passwords. Mandatory: No
Security Connection Authentication Copied
connection > securityConnectionAuthenticationConfig > username Copied
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.
This setting only works if the mqServer setting is configured.
Mandatory: No
connection > securityConnectionAuthenticationConfig > password Copied
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.
Choose the appropriate field when specifying the password:
stdAES— use this to input your plaintext password. If you selectstdAES, you can define your password directly in the sampler and store it in standard AES encryption hash in the Gateway.var— use this to pass the password as a variable. The variable is defined in Managed entity > Advanced > Var. This is useful for situations where you have multiple samplers that use the same credentials.extPwd— use this for passwords provided by an external provider. For more information, see Securing your Gateway with an external password provider in Secure Passwords.0
This setting only works if the mqServer setting is configured.
Mandatory: No
MQ Connection Backoff Copied
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.