IBM MQ

Supported Versions

Confirmed support for metrics and configuration data for version 8.0.0 or newer.

Configuration

Instana supports monitoring of both remote and local IBM MQ instances. In order to be able to collect data Instana agent requires following fields to be configured in the agent configuration file <agent_install_dir>/etc/instana/configuration.yaml:

Local

Note:

  1. Instana agent automatically discovers local IBM MQ instance, therefore you do not need to set the host and port. For an Instana agent on OCP, only the local Queue Manager can be monitored. For a host agent on an Operating System, both local and remote Queue Manager can be monitored together. Please note that local monitored Queue Manager instances will be shown as one layer in the separated host or OCP node in Infrastructure Map.
com.instana.plugin.ibmmq:
   enabled: true
   poll_rate: 5
   queueManagers:
      COM-INSTANA-QM01:    # Your Queue Manager name here
         channel: 'SYSTEM.ADMIN.SVRCONN' # Server connection channel
         username: 'mqmuser' # User ID to connect to MQ (optional)
         password: 'mqmuser' # User password to connect to MQ (optional)
         queuesRegex: '.*' # Optional regex for filtering queues
         availabilityZone: 'IBM MQ Custom Zone' # Optional, cluster name will be used by default 
         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: 5 # Metrics poll rate in seconds (optional)
      STAN-QM02:   # Your Queue Manager name here
         channel: 'SYSTEM.ADMIN.SVRCONN' # Server connection channel
         username: 'mqmuser' # User ID to connect to MQ (optional)
         password: 'mqmuser' # User password to connect to MQ (optional)
         queuesRegex: '.*' # Optional regex for filtering queues
         availabilityZone: 'IBM MQ Custom Zone' # Optional, cluster name will be used by default 
         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: 5 # Metrics poll rate in seconds (optional)
  1. For Instana agent on OCP, when monitored Queue managers on OCP with TLS enabled, create a secret with user jks file (example command below), add secret mountPath in volumeMounts and volumes section, and finally update the secret mountPath to keystore directory in ibmmq section part in configuration.yaml file.

Example:

kubectl create secret generic keystore-secret-name --from-file=./jks-file-name.jks -n instana-agent-namespace
volumeMounts:
  - name: mq-key-jks-name
    subPath: jks-file-name.jks
    mountPath: /opt/instana/agent/etc/jks-file-name.jks 
volumes:
  - name: mq-key-jks-name
    secret:
      secretName: keystore-secret-name

Remote

com.instana.plugin.ibmmq:
  enabled: true
  poll_rate: 5
  queueManagers:
    COM-INSTANA-QM03:    # Your Queue Manager name here
      host: '103.116.4.197'
      port: '1414'
      channel: 'SYSTEM.ADMIN.SVRCONN' # Remote administration channel
      username: 'mqmuser' # User ID to connect to MQ (optional)
      password: 'mqmuser' # User password to connect to MQ (optional)
      queuesRegex: '.*' # Optional regex for filtering queues
      availabilityZone: 'IBM MQ Custom Zone' # Optional, cluster name will be used by default 
      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: 5 # Metrics poll rate in seconds (optional)
    STAN-QM04:    # Your Queue Manager name here
      host: '103.116.4.198'
      port: '1415'
      channel: 'SYSTEM.ADMIN.SVRCONN' # Remote administration channel
      username: 'mqmuser' # User ID to connect to MQ (optional)
      password: 'mqmuser' # User password to connect to MQ (optional)
      queuesRegex: '.*' # Optional regex for filtering queues
      availabilityZone: 'IBM MQ Custom Zone' # Optional, cluster name will be used by default 
      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: 5 # Metrics poll rate in seconds (optional)

Remote monitored Queue Manager instances are shown on the Infrastructure Map as separate boxes in an availability zone, grouped by the availabilityZone configuration property or IBM MQ cluster name if present. If a Queue Manager is not running in cluster mode and the availabilityZone configuration property is not defined, Queue Manager will be shown in the Undefined zone.

IBM MQ Cluster - Metrics collection

Configuration data

  • Name
  • Started At
  • Alternated At

Performance metrics

  • Messages In
  • Messages Out

Queue Managers

Metric Description Granularity
Name The queue manager name and it is collected from MQCA_Q_MGR_NAME. 10 minutes
Status The current execution status of the queue manager and it is collected from MQIACF_Q_MGR_STATUS. 10 minutes
Version The version of IBM MQ code and it is collected from MQCA_VERSION. 10 minutes
Platform The platform on which the queue manager resides and it is collected from MQIA_PLATFORM. 10 minutes
Started At The data and time when the queue manage was started and it is collected from MQCACF_Q_MGR_START_DATE and MQCACF_Q_MGR_START_TIME. 10 minutes
Alternated At The alternation date and time and it is collected from MQCA_ALTERATION_DATE and MQCA_ALTERATION_TIME. 10 minutes
Max Handles The maximum number of handles MQIA_MAX_HANDLES. 10 minutes
Connections The number of connections and it is collected from MQIACF_CONNECTION_COUNT. 10 minutes

IBM MQ Queue Manager - Metrics collection

For the sensor to be able to collect Queue and Channel metrics, it is necessary to enable monitoring and statistics on Queue Manager level or on the level of Queue and Channel. QueueStatistics(MQIA_STATISTICS_Q) needs to be set to ON(MQMON_ON) and QueueMonitoring(MQIA_MONITORING_Q) needs to be set to at least Medium(MQMON_MEDIUM) level. ChannelStatistics(MQIA_STATISTICS_CHANNEL) and ChannelMonitoring(MQIA_MONITORING_CHANNEL) both needs to be set to at least Medium(MQMON_MEDIUM) level.

Configuration data

  • Name
  • Version
  • Status
  • Started At
  • Alternated At
  • Platform
  • Location
  • Description
  • Command Level
  • Repo
  • Max Handles

Performance metrics

Metric Description Granularity
Connections The number of connections and it is collected from MQIACF_CONNECTION_COUNT. 5 seconds
Messages In The number of messages enqueued and it is aggregated from all queues. 5 seconds
Messages Out The number of messages dequeued and it is aggregated from all queues. 5 seconds
Uncommitted Messages The number of uncommited messages and it is aggregated from all queues. 5 seconds

Topics

Metric Description Granularity
Name The topic name and it is collected from MQCA_TOPIC_NAME. 10 minutes
Queue Manager The name of queue manager topic belongs to. 10 minutes
Cluster The name of the cluster topic belongs to. 10 minutes
Type Whether this object is a local or cluster topic and it is collected from MQIA_TOPIC_TYPE. 10 minutes
Alternated At The alternation date and time and it is collected from MQCA_ALTERATION_DATE and MQCA_ALTERATION_TIME. 10 minutes
Messages Count The number of messages put to this topic and it is collected from MQIACF_MESSAGE_COUNT. 10 minutes
Publish Count The number of applications currently publishing to the topic and it is collected from MQIA_PUB_COUNT. 10 minutes
Subscription Count The number of subscribers from this topic and it is collected from MQIA_SUB_COUNT. 10 minutes

Listeners

Metric Description Granularity
Name The name of the listener and it is collected from MQCACH_LISTENER_NAME. 10 minutes
Status The listener status and it is collected from MQIACH_LISTENER_STATUS. 10 minutes
Port The port number and it is collected from MQIACH_PORT. 10 minutes
IP Address The IP Address of the listener and it is collected from MQCACH_IP_ADDRESS. 10 minutes
Started At The date and time when listener was started and it is collected from MQCACH_LISTENER_START_DATE and MQCACH_LISTENER_START_TIME. 10 minutes
QM Name The Queue Manager containing this listener. 10 minutes

Queues Usage

Metric Description Granularity
Name The queue name and it is collected from MQCA_Q_NAME. 10 minutes
Application The open application type and it is collected from MQCACF_APPL_TAG. 10 minutes
Channel The channel name and it is collected from MQCACH_CHANNEL_NAME. 10 minutes
Connection The Connection name and it is collected from MQCACH_CONNECTION_NAME. 10 minutes
Handle State The state of the handle and it is collected from MQIACF_HANDLE_STATE. 10 minutes
User The open application user name and it is collected from MQCACF_USER_IDENTIFIER. 10 minutes

Queues

Metric Description Granularity
Name The queue name and it is collected from MQCA_Q_NAME. 10 minutes
Type The queue type and it is collected from MQIA_Q_TYPE. 10 minutes
Usage The queue usage and it is collected from MQIA_USAGE. 10 minutes
Monitoring The online monitoring data collection and it is collected from MQIA_MONITORING_Q. 10 minutes

Channels

Metric Description Granularity
Name The channel name and it is collected from MQCACH_CHANNEL_NAME. 10 minutes
Status The channel status and it is collected from MQIACH_CHANNEL_STATUS. 10 minutes
In Doubt Whether the channel is currently in doubt and it is collected from MQIACH_INDOUBT_STATUS. 10 minutes
Substate The current action being performed by the channel and it is collected from MQIACH_CHANNEL_SUBSTATE. 10 minutes
Connection Name The connection name and it is collected from MQCACH_CONNECTION_NAME. 10 minutes
Active Conversations The number for server connection channel active conversations and it is collected from MQIACH_CURRENT_SHARING_CONVS. 10 minutes
Remote Queue Manager The name of the remote queue manager or queue sharing group and it is collected from MQCA_REMOTE_Q_MGR_NAME. 10 minutes
Last Message Date/Time The date and time when last message was sent or MQI call was handled and it is collected from MQCACH_LAST_MSG_DATE and MQCACH_LAST_MSG_TIME. 10 minutes
Start Date/Time The date and time when the channel was started and it is collected from MQCACH_CHANNEL_START_DATE and MQCACH_CHANNEL_START_TIME. 10 minutes

IBM MQ Queue - Metrics collection

Configuration data

  • Name
  • Type
  • Created At
  • Alternated At
  • Inhibit Put
  • Inhibit Get
  • Delivery Sequence
  • Default Binding
  • Usage
  • Monitoring

Performance metrics

Note: For Messages In, Messages Out in KPI value frame, they are summarized data by time selection.

Depth

Metric Description Granularity
Queue Depth The current queue depth and it is collected from MQIA_CURRENT_Q_DEPTH. 5 seconds
Max Queue Depth The maximum queue depth and it is collected from MQIA_MAX_Q_DEPTH. 5 seconds
Queue Full Percentage The percentage that the queue has reached its maximum depth. 5 seconds

Messages

Metric Description Granularity
Messages In The number of messages enqueued and it is collected from MQIA_MSG_ENQ_COUNT. 5 seconds
Messages Out The number of messages dequeued and it is collected from MQIA_MSG_DEQ_COUNT. 5 seconds
Uncommitted Messages The number of uncommited changes pending for the queue and it is collected from MQIACF_UNCOMMITTED_MSGS. 5 seconds

Message Time

Metric Description Granularity
Oldest Message The age of the oldest message and it is collected from MQIACF_OLDEST_MSG_AGE. 5 seconds
On Queue The indicator of the time that messages remain on the queue and it is collected from MQIACF_Q_TIME_INDICATOR. 5 seconds

Reset

Metric Description Granularity
Last Reset The time since statistics reset in seconds and it is collected from MQIA_TIME_SINCE_RESET. 5 seconds

Calls

Metric Description Granularity
Open Input Count The open input count and it is collected from MQIA_OPEN_INPUT_COUNT. 5 seconds
Open Output Count The open output count and it is collected from MQIA_OPEN_OUTPUT_COUNT. 5 seconds

Note: When data of Messages In and Message Out are retrieved, the QSTATS will be reset.

IBM MQ Queues Usage - Metrics collection

Configuration data

  • Name
  • Application
  • Channel
  • Connection
  • Input Type
  • Output
  • Inquire
  • Set
  • Browse
  • Last Message At
  • Handle State
  • User

Performance metrics

Metric Description Granularity
Open Inputs The open input count. 5 seconds
Open Outputs The open output count. 5 seconds

IBM MQ Channel - Metrics collection

Note: For Client Connection and Server Connection types of Channels, Messages Available and Sequence Number metrics are not available.

Configuration data

  • Name
  • Type
  • Status
  • In Doubt
  • Substate
  • Connection Name
  • Active Conversations
  • Remote Queue Manager
  • Start Date/Time

Performance metrics

Note: For Messages Sent, Messages Available, Buffers Sent, Buffers Received, Bytes Sent, BytesReceived in KPI value frame, they are summarized data by time selection.

Messages

Metric Description Granularity
Sent/Received The number of messages sent or received, or number of MQI calls handled and it is collected from MQIACH_MSGS. 5 seconds
Available The number of messages available and it is collected from MQIACH_XMITQ_MSGS_AVAILABLE. 5 seconds

Sequence Number

Metric Description Granularity
Current The sequence number of last message in in-doubt batch and it is collected from MQIACH_CURRENT_SEQ_NUMBER. 5 seconds
Last The sequence number of last message in last committed batch and it is collected from MQIACH_LAST_SEQ_NUMBER. 5 seconds

Buffers

Metric Description Granularity
Sent The number of buffers sent and it is collected from MQIACH_BUFFERS_SENT. 5 seconds
Received The number of buffers received and it is collected from MQIACH_BUFFERS_RECEIVED. 5 seconds

Bytes

Metric Description Granularity
Sent The bytes sent and it is collected from MMQIACH_BYTES_SENT. 5 seconds
Received The bytes received and it is collected from MMQIACH_BYTES_RCVD. 5 seconds

IBM MQ Topic - Metrics collection

Configuration data

  • Name
  • Queue Manager
  • Cluster Name
  • Topic Type
  • Topic Alternated At

Performance metrics

Message

Metric Description Granularity
Count The number of messages put to the destination specified by this subscription and it is collected from MQIACF_MESSAGE_COUNT. 5 seconds

Publish

Metric Description Granularity
Count The number of applications currently publishing to the topic and it is collected from MQIA_PUB_COUNT. 5 seconds

Subscription

Metric Description Granularity
Count The number of subscribers for this topic string, including durable subscribers who are not currently connected and it is collected from MQIA_SUB_COUNT. 5 seconds

IBM MQ Listener - Metrics collection

Configuration data

  • Name
  • Status
  • Port
  • Started At
  • Listener IP Address

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.

Tracing

This page describes how to install and enable IBM MQ tracing on your IBM MQ hosts.

Install IBM MQ Tracing user exits

Platforms and prerequisites

The IBM MQ Tracing user exits support Linux x86_64 only, and will support more platforms in the future.

The IBM MQ Tracing user exits report tracing data to the host agent on the same host by default. You also can configure IBM MQ tracing to report data to a remote host agent.

Only IBM MQ messages that include an MQRFH2 header or message properties are supported.

IBM MQ Server and queue managers must be installed and configured before installing and configuring this component.

Downloading IBM MQ Tracing user exits

  1. Download the package from IBM Fix Central to your IBM MQ server host. The package includes the following three files.

    • mqtracingexit_r, the IBM MQ user exits, intercepting the IBM MQ API calls and invoking the wrapped go Jaeger client library to create spans.
    • tracelibrary.so, the wrapped go Jaeger client, provides functions to manage the lifecycle of spans and sends spans to the target tracing system.
    • mqtracingexit.conf, the configuration file to specify the log level and information about connecting to the host agent.
  2. Extract tar file into /var/mqm/exits64 directory on your IBM MQ server.

Configuring IBM MQ Tracing user exits

This section describes how to configure your IBM MQ to enable tracing, including two parts - Configuring user exits and Configuring IBM MQ tracing.

Configuring user exits

You need to edit mqs.ini or qm.ini file to configure user exits. The mqs.ini file contains information relevant to all the queue managers on a particular node. The mqs.ini file is located at /var/mqm on Linux platform. The qm.ini file contains information relevant to a specific queue manager. The qm.ini file is located at /var/mqm/qmgrs/<QMNAME> on Linux platform, where <QMNAME> is queue manager name.

Follow these steps to enable tracing for all the queue managers on a particular node:

  1. Backup /var/mqm/mqs.ini file.
  2. Edit /var/mqm/mqs.ini file.

    Add the following content to enable user exits for all queue managers on this node. When any queue manager starts, the attributes in this stanza are read, and then overridden by the user exits defined in qm.ini.

    ApiExitCommon:
      Sequence=100
      Function=EntryPoint
      Module=/var/mqm/exits64/mqtracingexit
      Name=TracingApiExit

Follow these steps to enable tracing for a particular queue manager or if you want to change user exits settings for a particular queue manager.

  1. Backup /var/mqm/qmgrs/<QMNAME>/qm.ini file.
  2. Edit /var/mqm/qmgrs/<QMNAME>/qm.ini.

    Add the following content:

    ApiExitLocal:
      Sequence=100
      Function=EntryPoint
      Module=/var/mqm/exits64/mqtracingexit
      Name=TracingApiExit

Where:

  • Sequence identifies the sequence of this exit in relation to other exits. An exit with a low sequence number is called before an exit with a higher sequence number.
  • Function identifies the name of the function entry point into the module containing the user exits code.
  • Module contains the user exits code. If this field contains the full path name of the module, it is used as is. If this field contains only the module name, the module is located using the ExitsDefaultPath attribute in the ExitPath in qm.ini.
  • Name is the descriptive name of the user exits.

See more information at Configuring API exits in IBM MQ document library.

You need to save changes to the configuration files and restart the queue managers afterwards to make the changes take effect.

Configuring IBM MQ Tracing
  1. Go to /var/mqm/exits64 directory.
  2. Edit mqtracingexit.conf file.

    # configuration for IBM MQ exit
    LOG_LEVEL="info" #Log level: info, warn, error, debug
    SPAN_FORMAT="instana"
    INSTANA_AGENT_HOST = "localhost" #(optional)
    INSTANA_AGENT_PROTO = "http" #(optional)
    HOST_ALIAS="<YOUR-HOST-NAME>" #(optional)

    Where:

    • LOG_LEVEL specifies the log level, which can be one of info, warn, error and debug, the log file is located at /var/mqm/trace directory on Linux platform.
    • SPAN_FORMAT specifies where the span data is sent to. Set this variable to instana. IBM MQ Tracing user exits send span data to the host agent endpoint http://localhost:42699 by default. Update the configuration items INSTANA_AGENT_HOST and INSTANA_AGENT_PROTO if you want to send the span data to a remote host agent using https protocol. You should have the same SPAN_FORMAT setting for all MQ hosts.
    • INSTANA_AGENT_HOST specifies the agent host where the Instana format span data is sent to, localhost is used by default. If you specify a remote agent host, you also need to add a line http.listen=* in <instana-agent-dir>/etc/instana/com.instana.agent.main.config.Agent.cfg for the remote host agent first as the host agent is not reachable from other hosts by default.
    • INSTANA_AGENT_PROTO specifies the connection type between IBM MQ tracing exits and the host agent, http and https are supported, http is used by default. If you want to change it to https, you need to follow Setup TLS Encryption for Agent Endpoint to secure the agent endpoint first.
    • HOST_ALIAS specifies a host alias for the span data collected by IBM MQ Tracing user exits, so we can link calls to IBM MQ to the infrastructure entity if the Queue Manager is also monitored by the IBM MQ sensor. The FQDN of MQ host is used by default. The host alias value should match with the MQ host specified in host agent configuration yaml. You only need to specify a host alias if the FQDN of MQ host is not used in IBM MQ sensor configuration when the host agent is not on the local MQ host. The IBM MQ sensor can discover the FQDN for the local Queue Managers.
  3. Save the file and restart queue managers.

Repeat these installation and configuration steps on other IBM MQ hosts that you want to enable tracing for.

You can view IBM MQ tracing data on Instana UI.

Upgrade IBM MQ Tracing user exits

  1. Back up /var/mqm/exits64/mqtracingexit.conf on your IBM MQ server.
  2. Extract the downloaded IBM MQ Tracing user exits tar file and replace the corresponding files in /var/mqm/exits64 directory.
  3. Restart the queue managers.

Unconfiguring IBM MQ Tracing user exits

  1. Remove the ApiExitCommon and ApiExitLocal stanzas that you configured in /var/mqm/mqs.ini file and /var/mqm/qmgrs/<QMNAME>/qm.ini file from the MQ hosts that you enabled tracing.
  2. Restart the queue managers.
  3. Repeat steps on other IBM MQ hosts.

Limitations

  • At the moment, the tracing data collected from IBM MQ Tracing user exits can only be correlated with the tracing data collected by IBM App Connect Enterprise(ACE) Tracing and the Instana Java Trace Sensor. Instana tracers for other runtimes (.Net, Node.js, Go, ...) do not yet instrument the respective MQ client libraries.

Troubleshooting IBM MQ tracing

The tracing log files are located at /var/mqm/trace on Linux platform. The file name is mqExit*.log.

You can set log level in mqtracingexit.conf as described in Configure IBM MQ tracing section.