Monitoring IBM MQ

Supported operating systems

• The supported operating systems of IBM MQ sensor are consistent with host agents requirements, which can be checked in the Supported operating systems section of the Windows, Unix, or Linux host agent:

  • Supported operating systems for Linux
  • Supported operating systems for Unix
  • Supported operating systems for Windows

• For the supported operating systems of IBM MQ Tracing, see Supported operating systems for IBM MQ Tracing.

Supported IBM MQ versions

• Instana IBM MQ sensor supports monitoring metrics and configuration data for IBM MQ 8.0.0 and later.

• Instana IBM MQ Tracing supports IBM MQ 9.0.0 and later.

Replicated data queue manager (RDQM) support

You need to install the Instana host agent on each Queue Manager instance of the RDQM host. Then, the running and standby Queue Manager instances are automatically discovered and monitored by local monitoring. The Instana UI displays only 1 RDQM name with the aggregated data of 3 Queue Manager instances. You can view the information about HA Type, Running Node, and Standby Nodes values on the dashboard of the running Queue Manager in the Instana UI.

Local binding mode and client binding mode

These 2 modes refer to the connection mode that IBM MQ sensor connects to Queue Manager.

• By using the local binding mode, IBM MQ sensor can do fully automatic discovery and monitoring. By using the client binding mode, IBM MQ sensor can do only partially automatic discovery. In addition, you need to provide some connection parameters.
• By using local binding mode, more monitoring metrics including metrics from local files can be provided. By using client binding mode, IBM MQ sensor can provide only metrics that are retrieved from IBM MQ PCF interface and IBM MQ queues.
• If you use the local binding mode, you need to only add the Instana agent user to the mqm group of IBM MQ, and then all the IBM MQ data can be monitored.
• For client binding mode, you need to configure Queue Manager name, channel name, and related authority to connect to Queue Manager as a client application.

Local monitoring and remote monitoring

These 2 monitoring methods show whether IBM MQ sensor is in the same environment as Queue Manager.

• If IBM MQ sensor and Queue Manager are in the same environment, this is called local monitoring. If they are not in the same environment, this is called remote monitoring.
• The locally monitored Queue Manager instance is shown as one layer in the separated host or Kubernetes cluster node in the Infrastructure Map page of the Instana UI.
• The remotely monitored Queue Manager instances are shown in the Infrastructure Map page as separate boxes in an availability zone, and these instances are grouped by the availabilityZone configuration property or IBM MQ cluster name if present. If a Queue Manager instance is not running in the cluster mode and the availabilityZone configuration property is not defined, Queue Manager is shown in the Undefined zone.
• By using the local monitoring, IBM MQ sensor can connect to Queue Manager by either the local binding mode or client binding mode.
• By using the remote monitoring, IBM MQ sensor can connect to Queue Manager only by the client binding mode.
• The collection of monitoring metrics is decided by the connection modes: local binding mode or client binding mode. The local binding mode can collect more metrics in local files.

Support matrix of IBM MQ connection mode

See the following support matrix for IBM MQ connection mode:

Monitoring IBM MQ in a virtual machine

When the Instana host agent and IBM MQ run in the same virtual machine, 2 connection modes are supported: local binding mode and client binding mode.

Monitoring IBM MQ in a Kubernetes cluster

When the instana host agent and IBM MQ run in the same Kubernetes cluster, only local monitoring with the client binding mode is supported.

com.instana.plugin.ibmmq:
  enabled: true
  poll_rate: 60
  queueManagers:
    QMGR03:    # Your Queue Manager name here. If there are queue managers with the same name, it is required to append '-<instance>' in the queue manager name to distinguish them. You can select any string for <instance>.
    channel: '<INSERT_CHANNEL_HERE>' # Remote administration channel

Monitoring IBM MQ in Docker

When the Instana host agent and IBM MQ run in different Docker containers in the same virtual machine, only local monitoring with the client binding mode is supported because Instana host agent and IBM MQ run in different Docker operating systems. In such scenario, you need to configure IBM MQ connection parameters in the agent configuration file. Because IBM MQ sensor discovers IBM MQ Queue Manager instances automatically, you don't need to set the host and port in the agent configuration file.

Extra IBM MQ configurations

Some MQ metrics require that the queue statistics data, Queue Manager performance or channel events from IBM MQ side are enabled. If you want to collect these metrics, you need to do the following actions:

1. To collect the queue metrics Last Put Time, Last Get Time, Oldest Message Time, and On Queue Message Time, enable the queue statistic by running the RUNMQSC command alter ql(QUEUE_NAME) MONQ(LOW) by the queue level or by running the command alter qmgr MONQ(LOW) by the Queue Manager level.

   For more information, see IBM MQ documents.

2. To collect the built-in events Bridge stopped, Channel conversion error, Channel SSL Error and Queue Service Interval High, the Queue Manager performance events (PERFMEV) and channel events (CHLEV) need to be enabled by running the following RUNMQSC command:

   alter qmgr PERFMEV(ENABLED) CHLEV(ENABLED)
   

   For more information, see IBM MQ documents.

3. To collect MQ queue statistics metrics as Persistent Put Bytes, Nonpersistent Put Bytes, Persistent Get Bytes, Nonpersistent Get Bytes, Expired Msg Count, Put Fail Count, Put1 Fail Count, Get Fail Count, the following steps are required from IBM MQ:

   1. If you want to get all the queues statistics data, you need to enable queues statistics data collection by Queue Manager level as follows:

   alter qmgr STATQ(ON)
   

   If you want to get only a specific queue statistics data, you need enable it by queue level with your specific Queue_Name as follows:

   alter qlocal(Queue_Name) STATQ(ON)
   

   You can also change the queue statistics interval by using the IBM MQ Queue Manager parameter STATINT, which is 1800 seconds by default. For example, run the command alter qmgr STATINT(900).

   2. To get statistics data from SYSTEM.ADMIN.STATISTICS.QUEUE, you need to grant the get authority to the Instana agent user because the statistics data is collected from this queue. For example, run the command setmqaut -m QmgrName -n SYSTEM.ADMIN.STATISTICS.QUEUE -t q -p user +get. For more information, see IBM MQ documents.

Configuring IBM MQ authority

You can use 2 modes to monitor IBM MQ: local binding mode and client binding mode.

• For the local binding mode, you need to add the Instana agent user to the mqm group, and then all the data can be showed in the Instana UI.

• For the client binding mode, IBM MQ sensor works as a client to connect to Queue Manager. Thus, it requires authority to connect to the server connection channel as a client. This is the same authority as the other applications when they connect to Queue Manager.

  For most IBM MQ data, only the read authority is needed, and the data needs the following authorities:

  • To get the queue reset statistics data, the read and change authorities are needed.
  • To get the statistics data from SYSTEM.ADMIN.STATISTICS.QUEUE, the get authority needs to be set because the statistics data is collected from this queue. For example, run the command setmqaut -m QmgrName -n SYSTEM.ADMIN.STATISTICS.QUEUE -t q -p user +get.
  • To get the IBM MQ event such as the Queue Manager performance events and channel events, the get authority is needed for the queues SYSTEM.ADMIN.PERFM.EVENT, SYSTEM.ADMIN.CHANNEL.EVENT, and SYSTEM.ADMIN.QMGR.EVENT.

Local monitoring with the local binding mode

After you add the Instana agent user to the mqm group, for the already running Queue Managers, ensure that the security settings are taken effective.

You need to either refresh security by running the following IBM MQ runmqsc command or restart Queue manager to make the mqm authority that you granted take effective.

REFRESH SECURITY

Local or remote monitoring with the client binding mode

For the client binding mode, IBM MQ sensor behaves as a client application to connect to Queue Manager. So the sensor requires the same authority as any other applications to connect to Queue Manager, such as MQ explore. When you find Queue Manager can not be connected with your configured parameters, you can try your connection parameters with MQ explore to connect to Queue Manager and check whether Queue Manager can be connected.

See the following issues for reference:

• Listener is not started.

  Solution: Start the listener. You can start listener by running the following IBM MQ runmqsc command:

  START LISTENER($Listener_Name)
  

• No authority is granted to connect to the server connection channel. For example, some system server connection channels like SYSTEM.AUTO.SVRCONN are blocked by default.

  Solution: Unblock the user for system server connection channel before the user is used, or define your own server connection channel for connection.

• Security is enabled or TLS is enabled, but the corresponding username and password or keystore parameters are not provided.

  Solution: Provide corresponding username and password or keystore parameters in the agent configuration file.

• The host and port are configured in the agent configuration file in the Kubernetes cluster. But when Queue Manager is restarted, the host IP is changed, which caused the problem that Queue Manager cannot be connected by IBM MQ sensor.

  Solution: Make the host and port information automatically discovered by deleting the host and port in the agent configuration file for the host agent in the Kubernetes cluster.