Geneos
Geneos
Recommended Reads

MQ Queue Info Plug-In

Introduction

GENEOS MQ Queue Info Plug-in 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 Plug-in or, on a different machine, that is accessible across a network.

View

The MQ Queue Details Plug-in produces a single view as follows:

mq_qinfo_image2

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 plug-in configuration
Stagnant Message Count The number of stagnant messages on the queue. A stagnant message is defined in the plug-in 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

Before running the MQ Queue Info 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 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:

  • +connect permissions on the Queue Manager object
  • +inq permissions on the queue to be monitored
  • +browse permissions on the queue to be monitored, if message statistics are required

Plug-in Configuration

mq-qinfo
        queueManagerName
                data:
        mqServer:
        queueName:
                data:
        hideUnavailable:
        stagnantMessageAge:

The following parameters can be configured for this plug-in:

queueManagerName

The name of the queue managed to connect to

Mandatory: Yes

mqServer

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

queueName

The name of the queue which is to be monitored.

Mandatory: Yes

hideUnavailable

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

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

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

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 plug-in configuration or as an environment variable.

Security Exit

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.

Mandatory: No

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.

Mandatory: No

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.

Mandatory: No

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.

Mandatory: No

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.

Mandatory: No

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.