The MQ Channel 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 Channel plug-in monitors all configured channels 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 channel going down, or if an unknown process connects on a channel.
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 Channel 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 Channel produces a single dataview displaying
the configured channels for the queue manager it is
connected to, and the selected attributes for each
view. By default, these attributes include those
produced by a
DISPLAY CHSTATUS command. An
example of this is shown below.
The legends below list all columns which can be configured for this 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 channel being monitored.|
|type||Type of channel, one of
|protocol||The transmission protocol used by the
channel. One of
Status of the connection/channel:
|description||A user-configured description of the channel.|
|connectionName||Connection name. E.g. For a TCP connection, this would be the host and port of the remote queue manager.|
|remoteQManager||Name of the remote queue manager.|
|transmitQName||Name of the transmission queue, for a sender channel.|
|maxMsgLength||Maximum message length which can be sent over this channel, displayed in KB.|
|alterationDate||Date the channel definition was last
altered, in the form
|alterationTime||Time the channel definition was last
altered, in the form
|alterationDateTime||A concatenation of the
|buffersRecv||Number of messages buffers received over the channel.|
|buffersSent||Number of message buffers sent over the channel.|
|bytesRecv||Message data in bytes sent over the channel.|
|bytesSent||Message data in bytes received over the channel.|
|instanceType||The channel instance type, one of
|startDate||Date the channel was started, in the form
|startTime||Time the channel was started, in the form
|startDateTime||A concatenation of the
|heartbeatInterval||The channel heartbeat interval in seconds.|
|currentLuwid||Current "logical unit of work" identifier, for an in-doubt batch of messages.|
|currentSeqNo||Sequence number of the last message, for an in-doubt batch of messages.|
|lastLuwid||The "logical unit of work" identifier for the last committed batch of messages.|
|lastSeqNo||The sequence number of the last message in the last committed batch of messages.|
|lastMsgDate||Date the last message was sent, in the form
|lastMsgTime||Time the last message was sent, in the form
|lastMsgDateTime||A concatenation of the
|mcaName||Name of the Message Channel Agent (MCA).|
|mcaUserId||The user id used by the MCA.|
|mcaStatus||MCA status, either
|mcaJobName||Name of the MCA job.|
|messageCount||Number of messages sent or received.|
|remoteApp||Remote application name for a server-connection channel, or the remote queue manager / group otherwise.|
|retriesLeft||Number of short retries left (for reconnections).|
|stopRequested||Whether a stop request has been registered
for this channel. Values are
|sslCipherSpec||SSL cipher specification for the channel.|
|sslClientAuth||Whether SSL client authentication (a
certificate) is required to connect. Values are
|sslPeerName||Filter to use on the Distinguished Name of the SSL certificate of the peer connecting via the channel.|
|securityExit||Name of the security exit.|
|securityUserData||User data passed to the security exit when initiated.|
Before running the MQ Channel 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.
+get+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 channel to be monitored as below. The table in the column setting section describes which columns are of which type.
- Inquire Channel Status columns require no extra permissions.
- Inquire Channel columns require
+dsppermissions on each channel.
It is also advisable to enable channel monitoring to
gather extra status data, either for the queue manager
as a whole or individual channels which are being
monitored. This can either be done using WebSphere MQ
Explorer, or by issuing the following commands in
alterqmgr monchl(medium)to enable monitoring for all channels on the queue manager with
alterchannel(channelName)chltype(channelType)monchl(medium)to enable monitoring for a specific channel.
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 Channel 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 Channel 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 Channel 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 Channel 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
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.
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.
By default, MQ Channel will monitor all channels on the configured queue manager. The channels section allows users to configure only the channels they are interested in for monitoring.
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 channels section specifies the channels that will be monitored by the plug-in. By default, if no channels are specified then all channels on the queue manager will be monitored.
channels > channel
Specifies a channel (or channels for a generic name) for the MQ Channel plug-in to monitor. If no channels are specified all channels on the queue manager will be monitored.
channels > channel > matches
This setting specifies the exact name of a channel to monitor.
channels > channel > startsWith
This setting specifies a prefix of a channel name. All channels on the queue manager starting with the prefix will be monitored.
The startsWith setting uses the generic queue
names feature of the command server. For example,
if you entered the value
SYSTEM then the monitored
channels would be the same as the channels returned
when you issue the command
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 Channel will display columns
including the data you would see when executing the
DISPLAYCHSTATUS command in the
runmqsc MQ utility, along with
some additional metrics (see below
for more details). 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 configuration.
The columns section specifies the columns which
will be produced by the MQ Channel plug-in. Columns
appear in the order in which they are configured.
The name column is always present as the first
column. If no columns are specified, then a default
set of columns displaying most of the output from
DISPLAYCHSTATUS command is used.
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 they have been configured. If a column has already been added, then a duplicate entry will be ignored.
Column data for MQ Channel comes from executing inquire channel and inquire channel status commands using the command server on the MQ queue manager. Columns which obtain data from a channel status command may appear blank unless channel monitoring is enabled - see the prerequisites section for details on how to do this.
The following table shows which command is run to obtain data for each column. The default columns (which are displayed if no other columns are configured) are also displayed.
|Column||Default||Inq. Channel||Inq. Channel Status|
Further descriptions of these attributes can be found at the following IBM documentation pages:
The display format setting controls whether details rows are displayed in the dataview output. Details rows are shown as an indented set of (sub-)rows under a (summary) channel row. These sub-rows show statistics for each individual connection using a channel. The sub rows are identified by the MCA Job Name. The summary rows show totalled statistics for the whole channel.
Possible values for this setting are:
|SummaryOnly||Only the summary rows are displayed, showing the totalled statistics for that whole channel.|
|SummaryAndDetails||The summary rows are displayed along with the detail rows. Each detail row shows statistics for a single connection using that channel.|
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 Channel plug-in, in order to diagnose the problem.
The debug section contains debugging settings for the MQ Channel 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 > 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.
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 Channel. This example assumes that connection details for the MQ server are configured as environment variables. As no channels and columns have been specified, all channels on the queue manager will be monitored for the default set of statistics.
<sampler name="minChannelExample"> <plugin> <mq-channel> <queueManager> <data>QM.test.sim</data> </queueManager> <connection> <mqServer> <data>CH.TEST/TCP/itrs-mq6(1416)</data> </mqServer> </connection> </mq-channel> </plugin> </sampler>
SSL connection using MQSERVER setting
The following example shows how to configure MQ Channel 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
channels, selecting all channels starting
RECV, and the specific channel
<sampler name="channelMQServerWithSSL"> <plugin> <mq-channel> <queueManager> <data>QM.test.sim</data> </queueManager> <connection> <mqServer> <data>CH.TEST/TCP/itrs-mq6(1416)</data> </mqServer> <ssl> <keyRepository> <data>C:\Program Files\IBM\WebSphere MQ\ssl\key</data> </keyRepository> <cipherSpec><data>TRIPLE_DES_SHA_US</data></cipherSpec> </ssl> </connection> <channels> <channel> <startsWith><data>SEND</data></startsWith> </channel> <channel> <startsWith><data>RECV</data></startsWith> </channel> <channel> <matches><data>CH.TEST</data></matches> </channel> </channels> </Mmq-channel> </plugin> </sampler>
Channel table file connection
This example shows how to configure MQ Channel to use a channel table file. This file should define a client-connection which MQ Channel will use to connect to the queue manager. If this channel also has SSL settings configured, then you will need to specify the location of the key repository in order to successfully authenticate. Additionally, any security exit configuration in the sampler will be ignored.
The example also shows the use of the columns setting to select a set of columns for display, and also a debug setting which produces output of the MQ API calls being made.
<sampler name="channelTableFile"> <plugin> <mq-channel> <queueManager> <data>QM.test.sim</data> </queueManager> <connection> <mqChannelTable> <data>C:\Program Files\IBM\WebSphere MQ\AMQCLCHL.TAB</data> </mqChannelTable> </connection> <columns> <column>protocol</column> <column>type</column> <column>status</column> <column>mcaStatus</column> <column>mcaJobName</column> <column>remoteApp</column> <column>sslCipherSpec</column> <column>sslClientAuth</column> <column>securityExit</column> <column>securityUserData</column> </columns> <debug> <output> <mqApi>true</mqApi> </output> </debug> </mq-channel> </plugin> </sampler>