Configuring IBM MQ monitoring in virtual or physical machines

Configure the IBM MQ sensor based on the deployment of the Instana agent and the queue manager in your environment.

Deployment-based configuration scenarios

When the Instana host agent and IBM MQ run in the same machine, the following connection modes are supported: local binding mode and client binding mode. When the Instana host agent and IBM MQ run in different machines, only the client binding mode is supported.

The following table displays the configurations for different agent-queue manager deployment scenarios:

Agent-queue manager deployment User type Monitoring method Configuration requirement
Both in the same virtual or physical machine Privileged user Local monitoring with local binding mode No configuration required (Automatic monitoring)
Both in the same virtual or physical machine Nonprivileged user Local monitoring with client binding mode Manual configuration required in configuration.yaml
Both in the same Linux machine Nonprivileged and nonroot user Local monitoring with client binding mode Manual configuration required in configuration.yaml
In different environments (VM, Docker, or Kubernetes) Remote monitoring with client binding mode Manual configuration required in configuration.yaml

Configuring local monitoring with local binding mode

If the Instana agent user account is privileged, the IBM MQ sensor uses the local binding mode to retrieve data from IBM MQ.

By using the local binding mode, the IBM MQ sensor can discover IBM MQ queue manager instances automatically and show all the data. You don't need to configure the Instana agent configuration file.

Configuring local monitoring with client binding mode

If the Instana agent user account is not privileged, the IBM MQ sensor must use the client binding mode to retrieve data from IBM MQ. You must configure the IBM MQ connection parameters in the agent configuration file.

To configure the IBM MQ connection parameters, complete the following steps:

  1. Configure the ibmmq plug-in section in the agent configuration file as follows:

    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

  2. Configure other authorities based on your IBM MQ configurations. If the security of IBM MQ is enabled, configure the user and password. If TLS of IBM MQ is enabled, provide keystore-related information in the agent configuration file. See the following configuration example:

    Note:
    For keystore certificate file, only the jks file 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
      username: '<INSERT_USERNAME_HERE>' # User ID to connect to MQ (optional)
      password: '<INSERT_PASSWORD_HERE>' # User password to connect to MQ (optional)
      keystore: '<INSERT_KEYSTORE_PATH_HERE>' # Keystore path for TLS connection (required only when TLS is enabled for remote monitoring. Optional)
      keystorePassword: '<INSERT_KEYSTORE_PASSWORD_HERE>' # Keystore password for TLS connection (required only when TLS is enabled for remote monitoring. Optional)
      cipherSuite: '<INSERT_CIPHER_SUITE_HERE>' # TLS cipher suite for TLS connection (required only when TLS is enabled for remote monitoring. Optional)

    By using the client binding mode, the IBM MQ sensor can partially discover some configurations, such as host and port automatically in the local monitoring and show metrics in the Instana UI.

  3. For non-privileged and non-root users on Linux: Configure the enableStatisticsQueueMetrics flag in the agent configuration file to enable the IBM MQ sensor to retrieve queue statistics data. See Configuring queue statistics.

    For comprehensive information about running the Instana agent as a nonroot user on Linux, see Running the agent as a nonroot user.

Configuring queue statistics

To configure queue statistics, complete the following steps:

  1. Enable queue statistics: To enable the collection of performance metrics (such as message rates) for all queues, the mqm user must complete the following steps:

    1. Enable statistics at the queue manager level by running the following command. This command acts as a master switch for all queues with their STATQ attribute set to QMGR (the default value).

      ALTER QMGR STATQ(ON)

    2. b. Set the collection interval (mandatory) by running the following command. The STATINT value must match the agent poll_rate for real-time and accurate statistics. If STATINT is higher than the poll_rate, statistics are not real-time.

      ALTER QMGR STATINT(60)
      Important:
      The mqm user must grant all the required permissions. {: important)
  2. Configure the agent: Add the enableStatisticsQueueMetrics parameter in the agent configuration.yaml file (*instanaAgentDir*/etc/instana/configuration.yaml): 
    com.instana.plugin.ibmmq:
  enabled: true
  poll_rate: 60
  enableStatisticsQueueMetrics: false # Default is false. If false, uses RESET PCF command (requires mqm privileges). If true (Linux only), uses STATS mode from statistics queue (STATINT must match POLL_RATE for accuracy).

    After these configurations are set up, the Instana agent successfully collects queue statistics metrics by consuming messages from the statistics queue, without requiring root or mqm group access.

    When enableStatisticsQueueMetrics is set to true, the IBM MQ sensor enables STATS mode to collect queue throughput statistics. Ensure that the STATINT (statistics interval) is set to match the poll_rate value. When set to false (default), the sensor uses the RESET PCF command approach to collect statistics, which requires mqm privileges.

Configuring remote monitoring with client binding mode

In remote monitoring, the IBM MQ sensor uses the client binding mode to retrieve and show data from IBM MQ. You need to configure IBM MQ connection parameters in the agent configuration file. The configuration steps are the same as in the Local monitoring with the client binding mode section.

By using the client binding mode in the remote monitoring, you need to configure the host and port because IBM MQ sensor can't discover them in remote monitoring. The metrics are also shown in the Instana UI.