MQ Channel

Introduction Copied

The MQ Channel plugin is part of a suite of plugins 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 plugin 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.

MQ Architecture Copied

mq_channel_image2

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 plugin connects as a client to the configured queue manager, and obtains monitoring data by issuing status query commands using the command server.

View Copied

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 plugin. For a more in-depth discussion of columns, please see the columns configuration section.

Headline Legend

Name Description
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 plugin is connecting to.
connectionStatus The current connection status (UP or DOWN).
samplingStatus The current status of the plugin.

Table Legend

Name Description
name Name of the channel being monitored.
type Type of channel, one of Sender, Receiver, Server, Server Connection, Client Connection, ClusterSender, Cluster Receiver, Requester.
protocol The transmission protocol used by the channel. One of Local, LU 6.2, TCP, NetBIOS, SPX, DECnet, UDP.
status

Status of the connection/channel:

  • For specific connections (only shown when Summary and Detail view is activated), values can be one of Initializing, Binding, Starting, Running, Paused, Stopping, Retrying, Stopped, Requesting.

  • For summary rows of the channel, status depends on the status of the connections within that channel.
    • There are no channel instances: Status shown as Inactive.
    • There is a single channel connection: Status shown as the actual status of the connection.
    • There are 2 or more connections, all with the same status: Status shown as the actual status of the connections.
    • There are 2 or more connections, with mixed statuses: Status shown as Mixed.
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 yyyy‑mm‑dd.
alterationTime Time the channel definition was last altered, in the form hh.mm.ss.
alterationDateTime A concatenation of the alterationDate and alterationTime columns showing when the channel definition was last altered, in the form yyyy‑mm‑dd hh.mm.ss.
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 Current, Saved, Short.
startDate Date the channel was started, in the form yyyy‑mm‑dd.
startTime Time the channel was started, in the form hh.mm.dd.
startDateTime A concatenation of the startDate and startTime columns showing when the channel was started, in the form yyyy‑mm‑dd hh.mm.ss.
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 yyyy‑mm‑dd.
lastMsgTime Time the last message was sent, in the form hh.mm.dd.
lastMsgDateTime A concatenation of the lastMsgDate and lastMsgTime columns showing when the last message was sent, in the form yyyy‑mm‑dd hh.mm.ss.
mcaName Name of the Message Channel Agent (MCA).
mcaUserId The user id used by the MCA.
mcaStatus MCA status, either Stopped or Running.
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 Yes or No.
sslCipherSpec SSL cipher specification for the channel.
sslClientAuth Whether SSL client authentication (a certificate) is required to connect. Values are Required or Optional.
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.

Prerequisites Copied

Before running the MQ Channel plugin, you must first install the IBM WebSphere MQ Client version 9.x software on the machine on which the Netprobe will run. 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 mqic.dll 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 PATH environment 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 Netprobe.

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 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:

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.

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 runmqsc:

Note

If you are using a very short sample interval for your plugin, it is advised to increase the rate of data collection in MQ from medium to high.

Plugin Configuration Copied

The following parameters can be configured for this plugin:

Connection Details Copied

The connection section describes how the MQ Channel plugin will connect to the MQ server. There are two ways to configure a connection:

  1. Configure an inline connection using the MQSERVER variable.
  2. 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:

  1. Using the file specified in the mqChannelTable setting.
  2. Using the file specified by the MQCHLLIB and MQCHLTAB environment variables. In this case, variables configured in the managed entity section will be used in preference to those configured in the Netprobe start script.
  3. Using the connection details specified in the mqServer setting.
  4. Using the connection details specified in the MQSERVER environment 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.

connection Copied

This section contains the connection details used by the MQ Channel plugin to connect to the MQ server. If not specified, the plugin will fall back to using the environment variables MQCHLLIB and MQCHLTAB, or if not specified then MQSERVER instead.

These environment variables may be specified either in the managed entity configuration, or in the Netprobe start script.

Mandatory: No

connection > mqServer Copied

The MQ server setting informs the plugin how to connect to the MQ server. It consists of a channel name, transport type and hostname/port - e.g. CHAN/TCP/testhost(1414)

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.

Mandatory: No

connection > mqChannelTable Copied

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 plugin 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 the MQCHLLIB and MQCHLTAB environment variables (if set). It will be also used in preference to the mqServer setting or the MQSERVER environment variable.

Please see the IBM documentation for further details on the MQCHLLIB and MQCHLTAB environment variables.

Mandatory: No

connection > ssl Copied

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 plugins 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 plugin will connect successfully.

Mandatory: No

connection > ssl > keyRepository Copied

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 MQSSLKEYR environment variable.

The value of this setting is only required when using SSL connections. These can be specified in two ways:

  1. By configuring the mqServer setting (or MQSERVER environment variable) and also configuring the cipherSpec setting.
  2. By using a channel table (mqChannelTable setting or MQCHLLIB and MQCHLTAB environment 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.

Mandatory: No

connection > ssl > cipherSpec Copied

This setting is used when the connection is configured using the mqServer setting or the 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.

Mandatory: No

connection > mqSender Copied

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 plugin will send requests for monitoring data (commands) using the default name SYSTEM.ADMIN.COMMAND.QUEUE.

In practise this setting need not be defined unless the MQ server has been configured with a non-default command queue name.

Mandatory: No

Default: SYSTEM.ADMIN.COMMAND.QUEUE

connection > mqReceiver Copied

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 plugin will use the default behaviour of the IBM MQAI library, which is to create a new dynamic queue for the reply (based on the SYSTEM.DEFAULT.MODEL.QUEUE) 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 plugin instances (either running on the same or different Netprobes) as each MQ plugin 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.

Mandatory: No

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.

Note

This configuration will only work with MQServer. If a channel table is used in the configuration then the settings here will be ignored.

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.

{% snippets/netprobe/sampler-api-password-field %}}
Mandatory: No

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:

Channels Copied

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.

queueManager Copied

This setting specifies the name of the queue manager the plugin is to connect to. If a channel table is used, then this name should match the one specified for the connection.

Mandatory: Yes

channels Copied

The channels section specifies the channels that will be monitored by the plugin. By default, if no channels are specified then all channels on the queue manager will be monitored.

Mandatory: No

channels > channel Copied

Specifies a channel (or channels for a generic name) for the MQ Channel plugin to monitor. If no channels are specified all channels on the queue manager will be monitored.

Mandatory: No

channels > channel > matches Copied

This setting specifies the exact name of a channel to monitor.

Mandatory: No

channels > channel > startsWith Copied

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 DISPLAY CHSTATUS(SYSTEM\*) using the runmqsc MQ utility. You may also add the trailing \* in the setting value if you wish to match the standard MQ syntax.

Mandatory: No

Columns Copied

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.

columns Copied

The columns section specifies the columns which will be produced by the MQ Channel plugin. 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 the DISPLAYCHSTATUS command is used.

Mandatory: No

columns > column Copied

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.

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.

Further descriptions of these attributes can be found at the following IBM documentation pages:

Column Default Inq. Channel Inq. Channel Status
type X X X
protocol X X
status X X
description X X
connectionName X X X
remoteQManager X X
transmitQName X X X
maxMsgLength X X
alterationDate X
alterationTime X
alterationDateTime X
buffersRecv X
buffersSent X
bytesRecv X X
bytesSent X X
instanceType X
startDate X
startTime X
startDateTime X
heartbeatInterval X
currentLuwid X
currentSeqNo X
lastLuwid X
lastSeqNo X
lastMsgDate X
lastMsgTime X
lastMsgDateTime X
mcaName X
mcaUserId X X
mcaStatus X X
mcaJobName X
messageCount X X
remoteApp X
retriesLeft X
stopRequested X
sslCipherSpec X
sslClientAuth X
sslPeerName X
securityExit X
securityUserData X

Additional options Copied

displayFormat Copied

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:

Mandatory: No

Default: Summary Only

Setting Meaning
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.

Debug Copied

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 plugin, in order to diagnose the problem.

debug Copied

The debug section contains debugging settings for the MQ Channel plugin. Typically users should not need to configure any setting in this section.

Mandatory: No

debug > sampleTimeout Copied

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.

Mandatory: No

Default: Half the Netprobe heartbeat interval (approx 35 seconds), with a minimum of 20s.

debug > output Copied

The debug output settings enable additional output which is sent to the Netprobe log file.

Mandatory: No

debug > output > setup Copied

If enabled, this Boolean setting produces output regarding the results of the sampler setup parsing.

Mandatory: No

Default: false

debug > output > mqApi Copied

If enabled, this Boolean setting produces output regarding the results of all MQ API calls made by the plugin.

Mandatory: No

Default: false

debug > output > connection Copied

If enabled, this Boolean setting produces output regarding connection attempts, successes and failures to aid in debugging connection issues.

Mandatory: No

Default: false

debug > output > commands Copied

If enabled, this Boolean setting produces output regarding commands being executed by the plugin.

Mandatory: No

Default: false

debug > output > results Copied

If enabled, this Boolean setting produces output regarding the results processing of a successful command execution.

Mandatory: No

Default: false

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.

XML Examples Copied

Minimal setup Copied

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 Copied

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 SEND, RECV, and the specific channel named CH.TEST.

<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 Copied

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>
["Geneos"] ["Geneos > Netprobe"] ["Technical Reference"]

Was this topic helpful?