Monitoring IBM MQ
After you install the Instana agent, IBM MQ sensor is installed automatically. You can view metrics that are related to IBM MQ in the Instana UI after you configure IBM MQ sensor as outlined in the Configuring section.
- Supported information
- Common scenarios
- High availability (HA) scenarios
- Important IBM MQ monitoring concepts
- Configuring
- Viewing metrics
- Health signatures
- Troubleshooting IBM MQ sensor
Supported information
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:
-
Privileged users by platform for local binding
Platform Privileged users Windows - SYSTEM
- Members of the mqm group
- Members of the Administrators groupLinux - Members of the mqm group
-
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.
The IBM MQ versions supported on Instana are listed in the following table:
Sensor | Support policy | Latest version | Last supported version |
---|---|---|---|
IBM MQ | 45 days | 9.3 | 9.3 |
Supported client-side tracing
Instana supports client-side tracing for Java.
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 server-side tracing, you must install and enable IBM MQ Tracing first. For detailed steps, see IBM MQ Tracing. For IBM i servers, see IBM MQ Tracing on IBM i.
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 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 privilege of the user account that is running the Instana host agent.
- If the user account is privileged, then IBM MQ sensor automatically monitors all IBM MQ Queue Manager instances through the local binding mode.
- If the user account is not privileged, then IBM MQ sensor monitors all IBM MQ Manager instances through the client binding mode. In such a condition, you need to configure some IBM 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 or physical 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.
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.
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 labelqmName
as a separated box. The nameqmName@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 theconfiguration.yaml
file to activate HA support, you must edit the deployment file and redeploy the Instana host agent. In other environments, settingsupport_ha
in theconfiguration.yaml
file activates the HA support without restarting an agent.
Replicated data queue manager (RDQM) support
You need to install the Instana host agent on each RDQM host. The host must be a virtual machine or physical machine of the Linux platform. Then, Instana automatically discovers and monitors the running and standby Queue Manager instances
through local monitoring. The Instana UI displays only 1 RDQM Queue Manager name with the aggregated data of 3 Queue Manager instances. You can view the information about HA Type
, HA Role
, HA Preferred Location
,
HA Floating IP address
, Active Node
, and Standby Nodes
values on the dashboard of the running Queue Manager in the Instana UI.
Multi-instance Queue Managers support
All the distributed platforms and Kubernetes environments are supported. For the distributed platform, you need to install the Instana host agent on each Queue Manager instance of the multi-instance host. For the Kubernetes environment, you
need to install the Instana host agent in the Kubernetes environment. Then, Instana automatically discovers and monitors Queue Managers that are in running
, standby
, and elsewhere
status through local
monitoring. The Instana UI displays only 1 multi-instance Queue Manager name with the aggregated data of the other Queue Manager instances. You can view the information about HA Type
, Active Node
, Standby Nodes
,
and Elsewhere Nodes
values on the dashboard of the running Queue Manager in the Instana UI.
Native HA Queue Manager support
You need to install the Instana host agent in the Kubernetes environment. Then, Instana automatically discovers and monitors Queue Managers that are in running
and replica
status through local monitoring. The Instana
UI display only 1 Native HA Queue Manager name with the aggregated data of the other Queue Manager instances. You can view the information about HA Type
, Active Node
, and Standby Nodes
on the dashboard
of the running Queue Manager in the Instana UI.
Single-instance queue manager in Red Hat OpenShift Container Platform support
You need to install the Instana host agent on the Kubernetes environment. Then, Instana automatically discovers and monitors the running queue manager instance through local monitoring. The Instana UI displays the information about HA Type
and Active Node
of this queue manager instance on the dashboard.
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.
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, the Instana agent user must be privileged, 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 theavailabilityZone
configuration property is not defined, Queue Manager is shown in theUndefined
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.
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 do not need to complete the configuration steps in this section. However, the Instana agent user must be privileged, 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) 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) 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)
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
queuesIncludeRegex
orqueuesExcludeRegex
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 astrue
orfalse
to indicate whether the IBM MQ HA Queue Managers are monitored as a whole or not. If the value istrue
, all the data of IBM MQ HA Queue Managers is aggregated and shown asqmName
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 isfalse
, all the IBM MQ HA Queue Managers are monitored separately and shown in the Instana UI asqmName@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 isfalse
. If this field is not set, its value is considered asfalse
. The value of this field is hot-loaded. No need to restart the agent after you change the value of this field. -
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 namesSYSTEM.ADMIN.PERFM.EVENT
,SYSTEM.ADMIN.CHANNEL.EVENT
, andSYSTEM.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
customEvents
is a list of custom event names that must be triggered. Remove the events that you don't need from the list. This field is optional. If this field is not defined, the current listed events are triggered. You must enable event queues in thecustomEventQueues
parameter for your required custom events. 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 -
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.
Support matrix of IBM MQ connection mode
See the following support matrix for IBM MQ connection mode:
Support matrix | Queue Manager in a virtual or physical machine | Queue Manager in a Kubernetes cluster | Queue Manager in a Docker container |
---|---|---|---|
Instana agent in a virtual or physical machine | Local monitoring and remote monitoring | Remote monitoring | Remote monitoring |
Instana agent in a Kubernetes cluster | Not supported | Local monitoring | Not supported |
Instana agent in a Docker container | Local monitoring and remote monitoring | Remote monitoring | Local monitoring |
Monitoring IBM MQ in a virtual or physical machine
When the Instana host agent and IBM MQ run in the same machine, two connection modes are supported: local binding mode and client binding mode.
Local monitoring with the local binding mode
The Instana host agent must be privileged, and then the IBM MQ sensor uses the local binding mode to retrieve data from IBM MQ.
By using the local binding mode, IBM MQ sensor can discover IBM MQ Queue Manager instances automatically and show all the data. You don't need to set anything in the Instana agent configuration file.
Local monitoring with the client binding mode
If the user account to run Instana agent 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.
-
Configure the
ibmmq
plugin 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
-
Configure other authorities based on your IBM MQ configurations. If the security of IBM MQ is enabled, you need to configure the user and password. If TLS of IBM MQ is enabled, you need to provide keystore-related information in the agent configuration file. See the following configuration example:
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, 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.
When the Instana host agent and IBM MQ run in different machines, only the client binding mode is supported.
Remote monitoring with the client binding mode
In this mode, IBM MQ sensor also 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 showed in the Instana UI.
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.
Client binding mode configurations for local monitoring in Kubernetes clusters
In this mode, when the Instana host agent and IBM MQ run in the same Kubernetes cluster, only the client binding mode is supported because the host agent and Queue Manager can not run in the same pod. You need to configure IBM MQ connection parameters in the agent configuration file as follows. Because the host and port can be automatically discovered, don't set them to avoid duplicate querying of all Queue Manager instances in the Kubernetes cluster.
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
For Instana host agent on Kubernetes cluster, if TLS is enabled for monitored Queue Manager instances on Kubernetes cluster, you also need to configure TLS in the agent configuration file. Follow the steps:
-
Create a secret with the user jks file as follows:
kubectl create secret generic keystore-secret-name --from-file=./<jks-file-name>.jks -n instana-agent-namespace
Replace <jks-file-name> with the user jks file that you use. For the certificate file, only the jks file is supported.
-
Add the secret
mountPath
into thevolumeMounts
andvolumes
sections, and then update the secretmountPath
to the keystore directory in the ibmmq section of the agent configuration file.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
Do not set the host and port in the agent configuration file, but grant authority to connect to Queue Manager in the Kubernetes cluster. The metrics are also showed in the Instana UI.
Monitoring IBM MQ in Docker
When the Instana host agent and IBM MQ run in different Docker containers in the same 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.
Local monitoring with client binding mode
The configuration steps are the same as in the Local monitoring with the client binding mode section. You don't need to configure the host and port in the agent configuration file. The metrics are also showed in the Instana UI.
Remote monitoring with client binding mode
The configuration steps are the same as in the Remote monitoring with the client binding mode section.
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:
-
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.
-
To collect the IBM MQ performance built-in events, such as Queue Depth High, Queue Full, and Queue Service Interval High, you must enable the queue manager performance events (
PERFMEV
) by running the followingRUNMQSC
command:alter qmgr PERFMEV(ENABLED) CHLEV(ENABLED)
To collect built-in events that are related to queue manager, such as 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, you need to enable the channel events (
CHLEV
) by running the followingRUNMQSC
command. For more information about controlling queue manager events, see Controlling queue manager events.alter qmgr AUTHOREV(ENABLED) INHIBTEV(ENABLED) LOCALEV(ENABLED) REMOTEEV(ENABLED) STRSTPEV(ENABLED)
To collect built-in events that are related to channel, such as 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, the channel-related events (
CHLEV
) need to be enabled by running the followingRUNMQSC
command. For more information about controlling channel events, Controlling channel and bridge events.alter qmgr CHLEV(ENABLED) BRIDGEEV(ENABLED) SSLEV(ENABLED) CHADEV(ENABLED)
For more information about the
alter qmgr
command, see IBM MQ documents. -
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:
-
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).
-
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.
-
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:
-
In the sidebar of the Instana UI, select Infrastructure.
-
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 theavailabilityZone
configuration property is not defined, Queue Manager is shown in theUndefined
zone.
-
After you click the host or Queue Manager instance from the Infrastructure map, you need to click Open Dashboard to see the metrics data.
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:
Problems with the local binding mode
For the Queue Managers that are running, after you make the user privileged, make sure that the security settings work. You must either refresh security by running the following IBM MQ runmqsc command or restart Queue manager to make authority that you granted take effective.
REFRESH SECURITY