Configuring IBM MQ monitoring

Edit online

Instana supports monitoring of both remote and local IBM MQ queue manager instances. The configuration varies depending on the connection mode that the sensor uses.

Local binding mode

Edit online

In local binding mode (the sensor connects directly to the queue manager), no configuration is required if the Instana agent user is privileged. For more information about privileged users for local binding, see Supported operating systems.

In the local binding mode, the IBM MQ sensor supports fully automatic discovery and monitoring.

Client binding mode

Edit online

In client binding mode (the sensor connects remotely to the queue manager), you need to configure the following fields in the agent configuration file <agent_install_dir>/etc/instana/configuration.yaml as shown in the following example to enable monitoring.

In the client binding mode, the IBM MQ sensor supports only partial automatic discovery.

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.
  enableStatisticsQueueMetrics: false # true or false. The default value 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).
  aggregateChannelInstances: false # true or false. The default value is false.
  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)
      queuesInclude: '' # Comma-separated patterns with wildcard support to include queues(e.g: AMQ*,TEST*); up to 10 queues will be processed. (Optional)
      channelsIncludeRegex: '.*' # Regex for filtering inclusive channels. An example for multiple conditions: (^CHA\..*)|(^ECHO\..*)|(^SYSTEM\.DEAD\..*) (Optional)
      channelsExcludeRegex: '' # Regex for filtering exclusive channels. An example for multiple conditions: (^CHA\..*)|(^ECHO\..*)|(^SYSTEM\.DEAD\..*) (Optional)
      topicsIncludeRegex: '.*' # Regex for filtering inclusive topics. An example for multiple conditions: (^TOPIC\..*)|(^ECHO\..*)|(^SYSTEM\.DEAD\..*) (Optional)
      topicsExcludeRegex: '' # Regex for filtering exclusive topics. An example for multiple conditions: (^TOPIC\..*)|(^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)
      customEvents: 'Alias Base Queue Type Error, Bridge Stopped, Channel Auto-definition Error, Channel Blocked, Channel Conversion Error, Channel Not Activated, Channel Not Available, Channel SSL Error, Channel SSL Warning, Channel Stopped, Channel Stopped By User, Default Transmission Queue Type Error, Default Transmission Queue Usage Error, Get Inhibited, Not Authorized, Put Inhibited, Queue Depth High, Queue Full, Queue Manager Not Active, Queue Service Interval High, Queue Type Error, Remote Queue Name Error, Transmission Queue Type Error, Transmission Queue Usage Error, Unknown Alias Base Queue, Unknown Default Transmission Queue, Unknown Object Name, Unknown Remote Queue Manager, Unknown Transmission Queue' # Filter custom events to trigger. 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)
      queuesInclude: '' # Comma-separated patterns with wildcard support to include queues(e.g: AMQ*,TEST*); up to 10 queues will be processed. (Optional)
      channelsIncludeRegex: '.*' # Regex for filtering inclusive channels. An example for multiple conditions: (^CHA\..*)|(^ECHO\..*)|(^SYSTEM\.DEAD\..*) (Optional)
      channelsExcludeRegex: '' # Regex for filtering exclusive channels. An example for multiple conditions: (^CHA\..*)|(^ECHO\..*)|(^SYSTEM\.DEAD\..*) (Optional)
      topicsIncludeRegex: '.*' # Regex for filtering inclusive topics. An example for multiple conditions: (^TOPIC\..*)|(^ECHO\..*)|(^SYSTEM\.DEAD\..*) (Optional)
      topicsExcludeRegex: '' # Regex for filtering exclusive topics. An example for multiple conditions: (^TOPIC\..*)|(^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)
      customEvents: 'Alias Base Queue Type Error, Bridge Stopped, Channel Auto-definition Error, Channel Blocked, Channel Conversion Error, Channel Not Activated, Channel Not Available, Channel SSL Error, Channel SSL Warning, Channel Stopped, Channel Stopped By User, Default Transmission Queue Type Error, Default Transmission Queue Usage Error, Get Inhibited, Not Authorized, Put Inhibited, Queue Depth High, Queue Full, Queue Manager Not Active, Queue Service Interval High, Queue Type Error, Remote Queue Name Error, Transmission Queue Type Error, Transmission Queue Usage Error, Unknown Alias Base Queue, Unknown Default Transmission Queue, Unknown Object Name, Unknown Remote Queue Manager, Unknown Transmission Queue' # Filter custom events to trigger. 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)

For more information about the configuration parameters, see Configuration parameters.

Configuring sensor custom extension (public preview)

Edit online

You can collect custom metrics from beyond the standard metrics through the PCF (Programmable Command Format) commands. Configure the metrics that you want to collect, and the sensor automatically generates and runs the appropriate PCF commands. All metrics are exported in the Prometheus format.

You can set up the custom metrics configuration for local and remote monitoring of IBM MQ in the agent configuration file <agent_install_dir>/etc/instana/configuration.yaml as follows:

Local monitoring

Edit online
#IBM MQ
com.instana.plugin.ibmmq:
  enabled: true
  poll_rate: <>
  metrics:
    enabled: false  # Set to false to disable custom metrics collection (default: false for local)
    poll_rate: 60  # Global poll rate in seconds
    entities:
      <entityName1>:
        poll_rate: 30  # Poll rate in seconds for this entity (overrides global)
        metrics:
          - <metric1>
          - <metric2>
      <entityName2>:
        poll_rate: 60  # Poll rate in seconds for this entity
        metrics:
          - <metric1>
          - <metric2>
          - <metric3>
          - <metric4>
          - <metric5>

For more information, see Configuration parameters for custom metrics.

Remote monitoring

Edit online
#IBM MQ
com.instana.plugin.ibmmq:
  enabled: true
  poll_rate: <>
  queueManagers:
    <QUEUE_MANAGER_NAME>:
      host: '<MQ_HOST>'
      port: <MQ_PORT>
      channel: '<MQ_CHANNEL>'
      username: '<MQ_USERNAME>'
      password: '<MQ_PASSWORD>'
      availabilityZone: '<AVAILABILITY_ZONE>'
  metrics:
    enabled: false  # Set to true to enable custom metrics collection (default: false for remote)
    poll_rate: 60   # Global poll rate in seconds
    entities:
      <entityName1>:
        poll_rate: 30  # Poll rate in seconds for this entity (overrides global)
        metrics:
          - <metric1>
          - <metric2>
      <entityName2>:
        poll_rate: 60  # Poll rate in seconds for this entity
        metrics:
          - <metric1>
          - <metric2>
          - <metric3>
          - <metric4>
          - <metric5>

For more information, see Configuration parameters for custom metrics.

Custom metrics configuration example

Edit online

The following example shows the custom metrics configuration section for both local and remote monitoring of IBM MQ:

#IBM MQ
com.instana.plugin.ibmmq:
  metrics:
    enabled: true # enable/disable custom metrics collection, defaults to false when custom metrics section is configured
    poll_rate: 30 # Global poll rate in seconds
    entities:
      queue-manager: # entityName: IBM MQ resource type (queue-manager, queues, queue-usages, channels, subscriptions, topics, mqtt-channels)
        poll_rate: 60 # poll rate in seconds for this entity
        metrics: # List of IBM MQ PCF parameters to collect
          - 'MQIACF_CONNECTION_COUNT'
      subscriptions:
        poll_rate: 10
        metrics:
          - 'MQIACF_MESSAGE_COUNT'
      channels:
        poll_rate: 30
        metrics:
          - 'MQIACH_CHANNEL_STATUS'
      queue-usages:
        poll_rate: 30
        metrics:
          - 'MQIA_OPEN_INPUT_COUNT'
      queues:
        poll_rate: 30
        metrics:
          - 'MQIA_MAX_Q_DEPTH'
      topics:
        poll_rate: 10
        metrics:
          - 'MQIA_SUB_COUNT'
      mqtt-channels:
        poll_rate: 10
        metrics:
          - 'MQIACF_CONNECTION_COUNT'

Configuration parameters

Edit online

The following table lists the IBM MQ sensor configuration parameters:

Parameter Description Required Default value Remarks
enabled Enables or disables the IBM MQ sensor. Mandatory true Must be set to true to activate monitoring.
poll_rate Global metrics polling interval in seconds. Optional 60 Set globally or per queue manager. The minimum value is 30 seconds. See Configuring the polling rate.
support_ha Enables HA monitoring. If true, HA queue managers are shown as one. Optional false Hot-loaded; no agent restart needed. Aggregates HA queue managers in the Instana UI.
enableStatisticsQueueMetrics Enables statistics queue metrics collection. If false, the sensor uses RESET PCF command (requires mqm privileges). If true (Linux only), it uses STATS mode from statistics queue (STATINT must match poll_rate for accuracy). Optional (Linux only) false Hot-loaded; no agent restart needed.
aggregateChannelInstances Enables aggregation of channel instances. If true, channel instances are aggregated based on connection name. Optional false Hot-loaded; no agent restart needed. Aggregates channel instances in the Instana UI.
queueManagers Defines one or more queue manager instances. Mandatory — If duplicate names exist, different -<instance> to the queue manager name to distinguish them.
host Queue manager host IP for remote monitoring. Optional — Required for remote monitoring. Remove it for local monitoring or when Instana agent is on the Kubernetes cluster.
port Port for remote administration channel. Optional — Required for remote monitoring; remove for local monitoring or when Instana agent is on a Kubernetes cluster.
channel Server connection channel name. Mandatory — For example, SYSTEM.ADMIN.SVRCONN.
username User ID for IBM MQ connection. Optional — Required only if IBM MQ authentication is enabled.
password Password for IBM MQ connection. Optional — Required only if IBM MQ authentication is enabled.
queuesIncludeRegex Regex for filtering inclusive queues. Optional .* Takes precedence over queuesExcludeRegex if both are defined.
queuesExcludeRegex Regex for filtering exclusive queues. Optional '' Ignored if queuesIncludeRegex is defined.
queuesInclude Comma-separated patterns with wildcard support to include queues. Optional '' Use either queuesInclude or queuesIncludeRegex, not both. If both defined, queuesInclude takes precedence.
channelsIncludeRegex Regex for filtering inclusive channels. Optional .* Takes precedence over channelsExcludeRegex if both are defined.
channelsExcludeRegex Regex for filtering exclusive channels. Optional '' Ignored if channelsIncludeRegex is defined.
topicsIncludeRegex Regex for filtering inclusive topics. Optional .* Takes precedence over topicsExcludeRegex if both are defined.
topicsExcludeRegex Regex for filtering exclusive topics. Optional '' Ignored if channelsIncludeRegex is defined.
customEventQueues Comma-separated user-defined queue names to read performance, channel, or queue manager events. Optional SYSTEM.ADMIN.PERFM.EVENT, SYSTEM.ADMIN.CHANNEL.EVENT, SYSTEM.ADMIN.QMGR.EVENT Up to 3 queues can be defined.
customEvents Comma-separated list of custom events to trigger. Optional All listed events Requires corresponding queues to be enabled through customEventQueues. For details on the relation between the events and event queues, see Table 2.
availabilityZone Custom zone name. Optional Cluster name Useful for grouping queue managers in the Instana UI.
keystore Keystore path for TLS connection. Optional — Required only when TLS is enabled.
keystorePassword Keystore password for TLS connection. Optional — Required only when TLS is enabled.
cipherSuite TLS cipher suite for TLS connection. Optional — Required only when TLS is enabled.
poll_rate Polling interval for a specific queue manager. Optional 60 Overrides global poll_rate, if set.
Note: Notes: The channelsIncludeRegex or channelsExcludeRegex list is a regex expression to filter channels. If both lists are defined, the inclusive list takes precedence over the exclusive list. The topicsIncludeRegex or topicsExcludeRegex list is a regex expression to filter topics. If both lists are defined, the inclusive list takes precedence over the exclusive list. Setting the environment variable FORCE_CLIENT_BINDING to true forces the sensor to use client binding mode.

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

The following table shows the relationship between the events and event queues:

Event queues Events
SYSTEM.ADMIN.QMGR.EVENT Alias Base Queue Type Error, Default Transmission Queue Type Error, Default Transmission Queue Usage Error, Get Inhibited, Not Authorized, Put Inhibited, Queue Manager Not Active, Queue Type Error, Remote Queue Name Error, Transmission Queue Type Error, Transmission Queue Usage Error, Unknown Alias Base Queue, Unknown Default Transmission Queue, Unknown Object Name, Unknown Remote Queue Manager, and Unknown Transmission Queue
SYSTEM.ADMIN.PERFM.EVENT Queue Depth High, Queue Full, and Queue Service Interval High
SYSTEM.ADMIN.CHANNEL.EVENT Bridge Stopped, Channel Auto-definition Error, Channel Blocked, Channel Conversion Error, Channel Not Activated, Channel Not Available, Channel SSL Error, Channel SSL Warning, Channel Stopped, and Channel Stopped By User

Configuring the polling rate

Edit online

Note: Instana IBM MQ sensor 1.1.50 and later support configuring the polling rate to reduce data ingestion. This feature is supported on self-hosted Instana backend 311 and later.

You can configure how often Instana polls IBM MQ to collect data and metrics by using the poll_rate parameter in the agent configuration.yaml file as shown in the following example:

com.instana.plugin.ibmmq:
  poll_rate: 60

Configuration parameters for custom metrics

Edit online

The following table lists the configuration parameters for custom metrics collection:

Parameter Required or Optional Description
enabled Optional This flag enables or disables the custom metrics collection. By default, it is disabled (false).
poll_rate Optional The global poll rate (in seconds) for all the metric entities. If individual entities do not specify the poll rate, then global poll rate is taken.
entities Required The entities represents the metric groups. Multiple metric groups can be defined, and under each entity, the specific metrics to be collected and the tags to be associated with each metric can be specified.
entityName Required The entity type for IBM MQ resources. The metric prefix matches the provided entityName. Possible prefixes: queue-manager queues queue-usages channels subscriptions topics mqtt-channels
metrics Required List of IBM MQ PCF parameters to be collected, basically the performance metrics available through PCF commands must be specified here.
poll_rate Optional Custom poll rate (in seconds) for each entity; if not defined, the global poll rate is taken.