Monitoring IBM MQ

Supported information

Common scenarios

IBM MQ sensor can work in a Kubernetes cluster, Docker, virtual machine, and bare metal in hybrid environments. It can also monitor both local and remote Queue Manager in current complex environments. See the following common scenarios for reference:

• If the Instana host agent and IBM MQ run in the same virtual machine, then this local monitoring supports both the local binding mode and the client binding mode to connect to the Queue Manager. Monitoring IBM MQ Queue Manager instances through the local or client binding modes depend on the presence of the user account into the mqm group of IBM MQ to run the Instana host agent:

• If the user account is added in the mqm group, then IBM MQ sensor automatically monitors all IBM MQ Queue Manager instances through the local binding mode.

• If the user account is not in the mqm group, then IBM MQ sensor monitors all IBM MQ Manager instances through the client binding mode. In such a condition, you need to configure some MQ connection parameters in the agent configuration file <agent_install_dir>/etc/instana/configuration.yaml.

For more information about MQ connection parameters, see the Instana agent in a virtual machine section.

• If the Instana host agent and IBM MQ run in the same Kubernetes cluster or in the same Docker environment, this kind of local monitoring can support only the client binding mode to connect to Queue Manager. To use the client binding mode to monitor IBM MQ Queue Manager instances, you need to configure some IBM MQ connection parameters in the agent configuration file. For more information, see the Instana agent in a Kubernetes cluster and Instana agent in a Docker container sections.
• If the Instana host agent and IBM MQ run in different environments, this kind of remote monitoring can support only the client binding mode to connect to Queue Manager. To use the client binding mode to monitor IBM MQ Queue Manager instances, you need to configure some IBM MQ connection parameters in the agent configuration file. For more information, see the Remote monitoring with the client binding mode section.

High availability (HA) scenarios

If you want to monitor IBM MQ HA queue managers, install the Instana host agent on each monitored queue manager instance locally and set the support_ha parameter to true in the <agent_install_dir>/etc/instana/configuration.yaml file. The IBM MQ HA queue manager support is not enabled by default to ensure consistency with a normal queue manager. For more information, see the Configuring section. Enabling the HA support for the queue manager activates monitoring of the following IBM MQ HA environment: multi-instance queue managers, RDQM, native HA, and single instances in Red Hat OpenShift Container Platform.

When the monitoring of HA queue managers is supported, the infrastructure link between the Instana IBM MQ sensor and IBM MQ Tracing in call details continues to work after you configure tracing. For more information, see Troubleshooting.{: note} After you enable the HA support, you can get the following features:

• Monitor the HA queue managers as one queue manager with a unified view of continuous historical data that is obtained by aggregating data from all the HA queue manager instances.
• Identify the specific HA node on which the current queue manager is running.
• Trigger event by default when the HA queue manager switches over.

Note: After you enable the IBM MQ HA queue manager, you can see the following changes in the Instana UI:

• Before IBM MQ HA queue manager monitoring is supported, all instances of HA queue managers are monitored and shown separately with the label qmName@host in the Instana UI. Each instance is shown as a layer of the host where it is running. After IBM MQ HA queue manager monitoring is supported, all instances of HA queue managers are monitored as a unified queue manager, and their data is aggregated. In this case, all instances of HA queue managers are monitored and displayed as one queue manager with the label qmNameas a separated box. The name qmName@host1-host2-host3 is displayed in summary information on the IBM MQ Queue Manager instance dashboard in the Instana UI.
• The correlation with the host where the queue manager instance is running is removed due to the aggregation of 3 HA queue managers. So the original filters that are related with the queue manager host no longer work. A new filter like entity.ibmmq.qm.activeNode:* can to be used for searching the HA queue manager.
• You need to set the availability zone in the ibmmq plug-in section in the agent configuration.yaml file instead of the host section because the queue manager correlation with the original single host is removed. If the zone is set in the host part, the queue manager is displayed in an undefined zone after the HA support is enabled. You need to reset the availability zone in the ibmmq plug-in section.
• In the Red Hat OpenShift Container Platform environment, if you want to manually set support_ha in the configuration.yaml file to activate HA support, you must edit the deployment file and redeploy the Instana host agent. In other environments, setting support_ha in the configuration.yaml file activates the HA support without restarting an agent.

Important IBM MQ monitoring concepts

The following concepts are used in the Configuring section. Ensure that you fully understand these concepts and their differences before you start the configuration.

Configuring

Instana supports monitoring of both remote and local IBM MQ Queue Manager instances.

• By using the local binding mode, IBM MQ sensor can do fully automatic discovery and monitoring. So you don't need to do the configuration steps in this section. However, you need to add the Instana agent user to the mqm group of IBM MQ, and then all the IBM MQ data can be monitored.

• By using the client binding mode, IBM MQ sensor can do only partially automatic discovery. You need to configure the following fields in the agent configuration file <agent_install_dir>/etc/instana/configuration.yaml:

com.instana.plugin.ibmmq:
  enabled: true
  poll_rate: 60 # The default is 60 seconds. The minimum value is 30 seconds.
  support_ha: false # true or false. The default value is false. If the value is true, the HA Queue manger instances will be shown as 1 aggregated Queue manager.
  queueManagers:
    QMGR01:    # 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>.
      host: '127.0.0.1' # Queue Manager host, required for remote monitoring. Remove it for local monitoring or when Instana agent is on Kubernetes cluster. (Optional)
      port: '1414' # Remote administration channel port, required for remote monitoring. Remove it for local monitoring or when Instana agent is on Kubernetes cluster. (Optional)
      channel: 'SYSTEM.ADMIN.SVRCONN' # Server connection channel
      username: 'mqmuser' # User ID to connect to MQ. (Required only when user ID and password checking is enabled. Optional)
      password: 'mqmuser' # User password to connect to MQ. (Required only when user ID and password checking is enabled. Optional)
      queuesIncludeRegex: '.*' # Regex for filtering inclusive queues. An example for multiple conditions: (^AMQ\..*)|(^ECHO\..*)|(^SYSTEM\.DEAD\..*) (Optional)
      queuesExcludeRegex: '' # Regex for filtering exclusive queues. An example for multiple conditions: (^AMQ\..*)|(^ECHO\..*)|(^SYSTEM\.DEAD\..*) (Optional)
      customEventQueues: 'SYSTEM.ADMIN.PERFM.EVENT, SYSTEM.ADMIN.CHANNEL.EVENT, SYSTEM.ADMIN.QMGR.EVENT' # User defined queue names to read performance/channel/qmgr events. Separated by comma. (Optional)
      availabilityZone: 'IBM MQ Custom Zone' # Cluster name will be used by default. (Optional)
      keystore: '/tmp/application.jks' # Keystore path for TLS connection. (Required only when TLS is enabled)
      keystorePassword: 'password' # Keystore password for TLS connection. (Required only when TLS is enabled)
      cipherSuite: 'TLS_RSA_WITH_AES_256_CBC_SHA256' # TLS cipher suite for TLS connection. (Required only when TLS is enabled)
      poll_rate: 60 # Metrics poll rate in seconds. The minimum value is 30 seconds. (Optional)
    QMGR02:    # 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>.
      host: '127.0.0.1' # Queue Manager host, required for remote monitoring. Remove it for local monitoring or when Instana agent is on Kubernetes cluster. (Optional)
      port: '1415' # Remote administration channel port, required for remote monitoring. Remove it for local monitoring or when Instana agent is on Kubernetes cluster. (Optional)
      channel: 'SYSTEM.ADMIN.SVRCONN'  # Server connection channel
      username: 'mqmuser' # User ID to connect to MQ. (Required only when user ID and password checking is enabled)
      password: 'mqmuser' # User password to connect to MQ. (Required only when user ID and password checking is enabled)
      queuesIncludeRegex: '.*' # Regex for filtering inclusive queues. An example for multiple conditions: (^AMQ\..*)|(^ECHO\..*)|(^SYSTEM\.DEAD\..*) (Optional)
      queuesExcludeRegex: '' # Regex for filtering exclusive queues. An example for multiple conditions: (^AMQ\..*)|(^ECHO\..*)|(^SYSTEM\.DEAD\..*) (Optional)
      customEventQueues: 'SYSTEM.ADMIN.PERFM.EVENT, SYSTEM.ADMIN.CHANNEL.EVENT, SYSTEM.ADMIN.QMGR.EVENT' # User defined queue names to read performance/channel/qmgr events. Separated by comma. (Optional)
      availabilityZone: 'IBM MQ Custom Zone' # Cluster name will be used by default. (Optional)
      keystore: '/tmp/application.jks' # Keystore path for TLS connection. (Required only when TLS is enabled)
      keystorePassword: 'password' # Keystore password for TLS connection. (Required only when TLS is enabled)
      cipherSuite: 'TLS_RSA_WITH_AES_256_CBC_SHA256' # TLS cipher suite for TLS connection. (Required only when TLS is enabled)
      poll_rate: 60 # Metrics poll rate in seconds. The minimum value is 30 seconds. (Optional)

Notes:

• If two IBM MQ Queue Manager instances with the same name is configured, you need to append different -<instance> to the Queue Manager name to distinguish them in the same configuration file. You can select any string for <instance>.
• The customEventQueues is a list of user-defined queue names to read the performance, channel, and Queue Manager events. This field is optional. If this field is not defined, the default queue names SYSTEM.ADMIN.PERFM.EVENT, SYSTEM.ADMIN.CHANNEL.EVENT, and SYSTEM.ADMIN.QMGR.EVENT are used to read the performance, channel, and Queue Manager events. You can define 1 to 3 items so that the specified event queues are used to read events.
• The queuesIncludeRegex or queuesExcludeRegex list is a regex expression to filter queues. If both lists are defined, the exclusive list has the priority over the inclusive list.
• The support_ha field can be set as true or false to indicate whether the IBM MQ HA Queue Managers are monitored as a whole or not. If the value is true, all the data of IBM MQ HA Queue Managers is aggregated and shown as qmName in a separate box in the Instana UI as one Queue Manager, and the historical data is continuous even when the Queue Managers are in failover or switchover status. If the value is false, all the IBM MQ HA Queue Managers are monitored separately and shown in the Instana UI as qmName@host as normal Queue Managers, and thus the HA Queue Managers are shown as 2 or 3 Queue Managers as its instance number separately. The default value of this field is true. If this field is not set, its value is considered as true. The value of this field is hot-loaded. No need to restart the agent after you change the value of this field.

For more information about IBM MQ HA Queue Managers, see High availability (HA) scenarios.

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

Viewing metrics

After you complete the configuration steps in the Configuring section, you can view metrics that are related to IBM MQ in the Instana UI.

To view the metrics, complete the following steps:

1. In the sidebar of the Instana UI, select Infrastructure.
2. Click a specific monitored host.
   • 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.
   • Remotely monitored Queue Manager instances are shown in the Infrastructure Map page as separate boxes in an availability zone. 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 cluster mode and the availabilityZone configuration property is not defined, Queue Manager is shown in the Undefined zone.

Then, you can see a host dashboard with all the collected metrics and monitored processes.

For detailed metrics that IBM MQ sensor supports, see Viewing IBM MQ metrics.

Health signatures

For each sensor, there is a curated knowledgebase of health signatures that are evaluated continuously against the incoming metrics and are used to raise issues or incidents depending on user impact.

Built-in events trigger issues or incidents based on failing health signatures on entities, and custom events trigger issues or incidents based on the thresholds of an individual metric of any given entity.

For information about built-events for the IBM MQ sensor, see the Built-in events reference.

Troubleshooting IBM MQ sensor

Most problems that you might encounter are related to IBM MQ connection and authority. See the following problems:

REFRESH SECURITY

AMQ8077W: Entity 'user' has insufficient authority to access object
'SYSTEM.AUTH.DATA.QUEUE'.

EXPLANATION:
The specified entity is not authorized to access the required object. The
following requested permissions are unauthorized: chg
ACTION:
Ensure that the correct level of authority has been set for this entity against
the required object, or ensure that the entity is a member of a privileged
group.

Tracing

The configuration steps in the Configuring section are for monitoring and collecting IBM MQ metrics. You can continue to use IBM MQ Tracing on your IBM MQ hosts as you need.

To use IBM MQ Tracing, you must install and enable IBM MQ Tracing first. For detailed steps, see IBM MQ Tracing.