IBM MQ monitoring

Deprecation notice

This extension documentation is now deprecated and will no longer be updated. We recommend using the new IBM MQ extension for improved functionality and support.

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

Starting with Dynatrace OneAgent and ActiveGate version 1.231, we are upgrading the Extension Framework (also referred to as the plugins framework) from Python 3.6 to Python 3.8.

  • Consequences: Some Dynatrace extensions running in your environment may stop working and require redeployment of a new version prepared for Python 3.8.
  • Symptoms:
    • No data is provided for affected metrics on dashboards, alerts, and custom device pages populated by the affected extension metrics.
    • Extension logs display errors. Most often this will manifest itself as Python ModuleNotFoundError in the PluginAgent log.
    • Sometimes the Python virtual machine crashes.
  • Impact: This issue affects only those extensions that use native libraries called from Python code distributed with the extension.

For remediation details, see Dynatrace Extensions.

Out of the box, Dynatrace OneAgent traces IBM MQ messages in your applications.

To retrieve IBM MQ metrics and automatically retrieve the queue topology, you can install an extension:

See below for details.

IBM MQ ActiveGate extension

Requirements

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.
  • 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 Command Server must be running to process PCF commands.

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

Providing READ permissions to ** will satisfy most objects. However, you still need to allow UPDATE permission on SYSTEM.COMMAND.** queues to process INQUIRE commands.

Extension installation and configuration

  1. In Dynatrace Hub, select IBM MQ.
  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.

    • On Linux (default location):

      /opt/dynatrace/remotepluginmodule/plugin_deployment

    • On Windows (default location):

      C:\Program Files\dynatrace\remotepluginmodule\plugin_deployment

  4. Go to Settings > Monitoring > Monitored technologies > Custom extensions and select Upload extension.
  5. Upload the ZIP file.
  6. 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.
    • Auto-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 > Metric events.
    • Auto-Alert on Retry channel status: This will automatically trigger an alert if any channel is in Retry state, which can be a serious condition.
    • Auto-Alert on high queue depth threshold configured on queue manager: This will automatically trigger an alert if the queue depth value is higher than that configured directly on queue manager (QDepthHighLimit)
    • Auto-Alert on low queue depth threshold configured on queue manager: This will automatically trigger an alert if the queue depth value is lower than that configured directly on queue manager (QDepthLowLimit)
    • Get Queue Sharing Group queues: This parameter is for z/OS queue managers only. On a Sysplex z/OS environment, this will retrieve metrics about queue sharing group (QSG) queues
    • 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, as well as IMS bridge and QSG 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 the following permissions:
      • APIv1:
        • Access problem and event feed, metrics, and topology
        • Read configuration
        • Write configuration
      • APIv2:

        To be able to use the API you need an access token with Read settings (settings.read) and Write settings (settings.write) scopes. To learn how to obtain it, see Create an access token.

    • 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

  • IBM MQ 9.x+ running on Windows/Linux

  • A user with proper permissions to objects must exist on the queue managers:

    IBM MQ permissions: LUW

  • Linux only: The user running the oneagentplugin process (dtuser by default) must also have access to the queue manager directories (/var/mqm/log, /var/mqm/qmgrs/<queue_manager>) so that it can bind properly.

  • Linux only: Unlike its counterpart ActiveGate extension, this OneAgent extension does not use a client TCP connection. Instead, it uses local IBM MQ libraries to bind to queue managers.

    • Local IBM MQ libraries must be in the LD_LIBRARY_PATH for dtuser or the user running the oneagentplugin process.
    • By default, IBM MQ installs an ldconfig file called /etc/ld.config.so.d/mqm.conf that adds /usr/lib64 to the LD_LIBRARY_PATH. Make sure IBM MQ library symbolic links to /opt/mqm/lib64 are found in that path. Because the extension uses local IBM MQ libraries to bind to queue managers (no TCP connection), dtuser must be able to find those MQ libraries in its path and load them. If there is no reference in /usr/lib64 to /opt/mqm/lib64 libraries, you may have to create your own .conf file and place it in /etc/ld.config.so.d/.

  • IBM MQ Command Server must be running to process PCF commands.

Installation and configuration

  1. In Dynatrace Hub, select IBM MQ.

  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.

    • On Linux (default location):

      /opt/dynatrace/oneagent/plugin_deployment

    • On Windows (default location):

      C:\Program Files\dynatrace\oneagent\plugin_deployment

  4. Go to Settings > Monitoring > Monitored technologies.

  5. Select the Custom extensions tab.

  6. Select Upload extension and upload the ZIP file.

  7. Configure the extension.

    Global configuration applies the same configuration to all hosts that are running the extension.

    1. Go to Settings > Monitoring > Monitored technologies.
    2. Select the Custom extensions tab.
    3. Select OneAgent IBM MQ.

    Typically, every host has different queue managers, so we recommend configuring the extension at the host level.

    1. Go to Hosts or Hosts Classic (latest Dynatrace) and select the host.
    2. On the host page, select More (…) > Settings.
    3. On the Host settings page, in the Monitored technologies table, expand OneAgent IBM MQ.
    • User: optional If a username is provided, it will send this user to queue managers for authentication. If this field is left blank, it will use the local user running the extension process (dtuser by default).
    • Password: If you entered a User, enter a password to authenticate.
    • Channels: Multiple queue managers can exist on the same host. List queue managers and channels for which to collect data, separated by commas, 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: Multiple queue managers can exist on the same host. List queue managers and queues for which to collect data, 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: Multiple queue managers can exist on the same host. List queue managers and listeners for which 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.
    • Auto-Alert on high queue depth threshold configured on queue manager: This will automatically trigger an alert if the queue depth value is higher than that configured directly on queue manager (QDepthHighLimit)
    • Auto-Alert on low queue depth threshold configured on queue manager: This will automatically trigger an alert if the queue depth value is lower than that configured directly on queue manager (QDepthLowLimit)
    • 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 the following permissions:
      • APIv1:
        • Access problem and event feed, metrics and topology
        • Read/Write configurations
      • APIv2:
        • Read/Write Settings

IBM MQ metrics

Queue Manager

  • Availability: Whether the queue manager is reachable. It reports availability as a percentage value. Depending on the MQ version and permissions, a PING command may be issued as well.
  • Connections: Current number of connections to the queue manager.
  • Active channels: Number of channels that are current and have a status. These are channels that have been started, or on which a client has connected, and that have not finished or disconnected normally.

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. This metric is only available to server-connection channels.
  • Channel instances: Number of instances this channel is using for connections. This metric is only available to server-connection channels.

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 %: Whether a listener channel reports as RUNNING status.