IBM MQ monitoring

Learn how to use Dynatrace extensions to collect IBM MQ metrics.

IBM MQ ActiveGate extension

Requirements

  • Dynatrace 1.212+
  • ActiveGate 1.212+
    • Important note: Each queue manager connection will run a separate JVM. Take memory consumption into consideration.
  • IBM MQ 9.x+ for Windows/Linux/AIX/MQ Appliance/Z systems.
  • A server-connection channel on the queue manager for communication with the plugin.
  • Connectivity from the ActiveGate to the host and port on which the queue manager runs.
  • No longer required to install an IBM MQ Client
  • Java Runtime Environment of at least version 8 installed on ActiveGate (JRE 11+ recommended). We recommend not using the JRE that comes in the ActiveGate install directory.
  • If using SSL: Two key repositories must exist: a JKS truststore on the ActiveGate where the MQ extension is installed, and your CMS repository on the MQ Server. Each repository must have each other's public key certificate. The certificate label of the MQ Server must be ibmwebspheremq<queue_manager> (all in lowercase). The certificate label on the client side on the ActiveGate must be ibmwebspheremq<username> (all in lowercase). The username is the user under which the Dynatrace Remote Plugin process runs.

IBM MQ Configuration

IBM MQ connectivity to ActiveGate

For the IBM MQ plugin extension to work, it must connect to the MQ server passing a user and password. The user/password pair from the Dynatrace web UI is passed in an MQCSP structure block. However, depending how the MQ server is configured, it may ignore the MQCSP block. Instead, MQ server will authenticate the passed UserID, which is the user running the Remote Plugin Module process. If this is the case, that user must exist on the MQ server and must have the proper permissions to access channels and queues.

You are also able to connect without a user or password, but your Queue Manager must allow this and channels must be configured properly (IDPWOS, IDPWLDAP, etc.) Please review the CHLAUTH and CONNAUTH objects and the ADOPTCTX parameters on the MQ server.

Permissions

For distributed platforms:
IBM MQ permissions: LUW

For z/OS:
IBM MQ permissions: z/OS

Note: Providing DISPLAY permissions to ** will satisfy most objects. However, you may specify each object manually. Other permissions may be required.

Extension installation and configuration

  1. In the Software Intelligence Hub, find and select IBM MQ - ActiveGate.
  2. Select Download to get the extension ZIP file. Don't rename the file.
  3. Unzip the ZIP file to the plugin_deployment directory of your ActiveGate host.
  4. Restart the Dynatrace Remote Plugin Module service.
  5. In the Dynatrace menu, go to Settings > Monitored technologies > Custom extensions and select Upload Extension.
  6. Upload the ZIP file.
  7. Enter the following endpoint information for connecting to IBM MQ:
    • Endpoint name: Any label to identify this connection. It is only for identification purposes.
    • User: User to authenticate against MQ Server. If blank, make sure the queue manager and the server-connection channel are configured to allow this.
    • Password: The password for the user.
    • Comma-separated Queue Manager hosts with ports: This is a connection name list, so you can enter more than one host and IP address (with ports) for one queue manager only. Example: 192.168.55.180(1414), 192.168.55.181(1414), 192.168.55.182:1415, 192.168.55.183:1414
    • Server-connection channel: Channel for the extension to communicate with the queue manager.
    • Single Queue Manager: Name of queue manager to collect data from. Only one queue manager per end-point. You may add other end-points to other queue managers.
    • Channels: Wildcards (*) and exclusions (-) are allowed. For example, abc* will get all channels that start with abc, and abc*, -mq.chan* will get all channels that start with abc and exclude those that start with mq.chan. Only explicitly defined channels are collected.
    • Comma-separated queues: List of queues to collect data for separated by commas. Wildcards (*) and exclusions (-) are allowed. For example, abc* will get all queues that start with abc, and abc*, -amq* will get all queues that start with abc and exclude those that start with amq.
    • Listeners: List of listeners to collect data, separated by commas.
    • Use SSL: Check to validate SSL configuration upon connecting and use SSL.
    • SSL key repository: If using SSL, you must provide the path on the ActiveGate where the SSL JKS key repository is located.
      Two key repositories must exist, one on the ActiveGate where the MQ Client resides and the other on the MQ Server where the queue manager resides. Each repository must have the other's public key certificate. The certificate label of the MQ Server must be ibmwebspheremq<queue_manager> (all in lowercase). The certificate label of the MQ Client on the ActiveGate must be ibmwebspheremq<username> (all in lowercase). The username is the user that runs the Remote Plugin process.
    • SSL keystore password: The password to the JKS truststore.
    • Cipher spec: Cipher specification of encryption used in the channel communication. Must match the Cipher specification of the Server-Connection channel configuration.
    • Exclude SYSTEM: Select this if you want to automatically exclude all queues and channels that start with SYSTEM.
    • Run Reset Statistics: This will issue the RESET_STATS command to queues in order to collect Enqueue/Dequeue count metrics. This requires CHG permissions on queues.
    • Alert on DLQ messages: This will get the queue depth of the dead letter queue and automatically trigger an alert if it has any messages. If not selected, you can set your own alert and threshold in Settings > Anomaly detection > Custom events for alerting.
    • Alert on Retry channel status: This will automatically trigger an alert if any channel is in Retry state, which can be a serious condition.
    • Model queue: If not set, it will use the SYSTEM default model queue for command requests and responses.
    • Reply queue: If setting a model queue, it assumes a custom reply queue.
    • Retrieve topology for improved transaction tracing: This enables a flag to use the Dynatrace Configuration API to feed the MQ topology for local, alias, remote, and cluster queues. This way, application transaction tracing has improved visibility to MQ calls.
    • Cluster environment or tenant: Your current cluster environment or tenant URL.
    • API Token: A Dynatrace API token with Write configuration and Accept problem and event feed, metrics and topology permissions.
    • Name of group: If the device is part of a cluster, enter the name here to group the devices in the Dynatrace web UI. This will group your devices in the Technology overview.
    • Path to Java: Location of JRE's Java executable. We recommend using a different JRE than the one provided with ActiveGate. You can install a separate JRE (version 8+) on your ActiveGate.
    • ActiveGate: Choose the ActiveGate where the extension resides; it will poll MQ Server every minute.

IBM MQ OneAgent extension

Requirements

  • Dynatrace 1.212+
  • IBM MQ 8.0+ running on Windows/Linux
  • User running the oneagentplugin process (dtuser by default) must exist on the queue managers and have proper permissions:
    IBM MQ permissions: LUW
  • User running the oneagentplugin process (dtuser by default) must also have permission rights to the queue manager directories (/var/mqm/log, /var/mqm/qmgrs/<queue_manager>) so that it can bind properly.

Installation and configuration

  1. In the Software Intelligence Hub, find and select IBM MQ - OneAgent.
  2. Select Download to get the extension ZIP file. Don't rename the file.
  3. Unzip the ZIP file to the oneagent/plugin_deployment directory.
  4. Restart the OneAgent service.
  5. In the Dynatrace menu, go to Settings > Monitored technologies.
  6. Select the Custom extensions tab.
  7. Select Upload extension and upload the ZIP file.
  8. Enter the following endpoint information for connecting to IBM MQ:
    • Channels: List of queue managers and channels to collect data for in the following format:
      QueueManager1: channel1, channel2, …
      QueueManager3: channel1, channel2, …
      Wildcards (*) and exclusions (-) are allowed. For example, abc* will get all channels that start with abc, and abc*, -mq.chan* will get all channels that start with abc and exclude those that start with mq.chan.
    • Comma-separated queues: List of queue managers and queues to collect data for separated by commas in the following format:
      QueueManager1: queue1, queue2…. Etc.
      QueueManager3: queue1, queue2…. Etc.
      Wildcards (*) and exclusions (-) are allowed. For example, abc* will get all queues that start with abc, and abc*, -amq* will get all queues that start with abc and exclude those that start with amq.
    • Listener channel: List of queue managers and listeners to collect data, separated by commas in the following format:
      QueueManager1: listener1
      QueueManager3: listener3
    • Exclude SYSTEM: Check this box if you want to automatically exclude all queues and channels that start with SYSTEM.
    • Run Reset Statistics: This will issue the RESET_STATS command to queues in order to collect Enqueue/Dequeue count metrics. This requires CHG permissions on queues.
    • Alert on DLQ: Checking this will auto create a Problem if it detects that the queue depth on the configured dead letter queue is > 0.
    • Alert on Retry channel state: This will auto create a problem if it detects a channel in the filter is in Retrying mode.
    • Retrieve topology for improved transaction tracing: This enables a flag to use the Dynatrace Configuration API to feed the MQ topology for local, alias, remote, and cluster queues. This way, application transaction tracing has improved visibility to MQ calls.
    • Cluster environment or tenant: Your current cluster environment or tenant URL.
    • API Token: A Dynatrace API token with Write configuration and Accept problem and event feed, metrics and topology permissions.

IBM MQ metrics

Queue Manager

  • Availability %
  • Connections
  • Active channels

Channel (split by channel)

  • State: Whether the channel is INACTIVE, RUNNING, STOPPED, RETRYING, STOPPING, STARTING, PAUSED, INITIATING states.
  • Messages: Number of messages sent and received, including MQI calls for all channel instances.
  • Bytes Sent/Received: Number of bytes sent and received for all channel instances.
  • Buffers Sent/Received: Number of buffers sent and received for all channel instances.
  • Last Message Date/Time: Time last message was sent.
  • Current Sharing Conversations: Number of conversations being shared for this channel.

Queues (split by queue)

  • Queue Depth: Current queue depth value.
  • Percent queue depth: Calculated using the Current Queue Depth over Max Queue Depth value.
  • Inhibit Get/Put: Property value denoting whether PUT and GET are allowed.
  • Open Input/Output Count: Open input and output handles (IPPROCS/OPPROCS).
  • Oldest Message Age: Time in seconds of oldest message.
  • Uncommitted Messages: Number of messages that have not been committed.
  • Enqueue/Dequeue Rate: Number of messages in queue that were PUT or RETRIEVED and not committed per second.
  • Time Indicator: Time messages stay in queue.
  • Last get/Last put: Time in milliseconds when MQGET and MQPUT commands were executed on this queue.

Listener (split by listener)

  • Availability %