Extend the platform,
empower your team.
On this new version of this popular extension, collect performance metrics from your queue managers running locally on your OneAgent host or remotely from your ActiveGates. Capture metadata and new metrics on this version.
In order to retrieve the following metrics, queue monitoring must be enabled on queues. Any monitoring resolution will start collecting these statistics.
In order to retrieve the following metrics, statistics on queues are reset. To reset them, CHG permission must be granted to queues
OneAgent for Windows or Linux only.
OneAgent must be running and monitoring queue manager processes.
Dynatrace version 1.269+
IBM MQ 9.1+. IBM dropped support to 9.0.x in 2021.
IBM MQ Command server must be running on queue managers
MQ Libraries must be in PATH on Windows or LD_LIBRARY_PATH on Linux. User running extension must be able to find these libraries.
User running the OneAgent (dtuser by default) must also have read access to the queue manager directories /var/mqm/qmgrs/<queue_manager>
and read/write to log directories /var/mqm/log
so that it can bind properly.
Ensure MQ libraries are accessible by dtuser
or whichever user your OneAgent service is running under. Default location for these libraries is /opt/mqm/lib64
By default, IBM MQ installs an ldconfig file called /etc/ld.so.config.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. 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.so.config.d/.
Using ldconfig will allow the MQ libraries to be loaded by default. To do this you can do the following:
ibmmq_ext.conf
/opt/mqm/lib64
ldconfig
IBM MQ has several ways to authenticate client and local connections. This is determined by the administrator of your MQ environment according to their own security policies.
User authentication depends on Channel Authentication (CHLAUTH
) configuration. If disabled or ADOPTCTX
is disabled, IBM MQ will attempt to authenticate the user running the extension process, not the user passed in the endpoint configuration.
When ADOPTCTX
is enabled and CHLAUTH
is enabled, the user and password combination entered in the endpoint is passed in a MQCSP block that IBM MQ will attempt to authenticate.
Note:
Under Extensions
on the left menu, select IBM MQ
.
OneAgent deployment, also referred as "Local", can run on a specific host, host groups, hosts in a management zone or tagged hosts. ActiveGate deployment, also referred as "Remote", runs on ActiveGate groups. Groups can one or multiple ActiveGates for more reliability.
Log level: Enable DEBUG only when troubleshooting or support makes that recommendation.
Add a Queue Manager: Any queue managers matching its filter will use this configuration. You may create one separate configuration per queue manager on host, or one configuration for all queue managers on that host.
Queue manager filter: A name matching this filter will be matched against running processes on this host. If a name matches this filter, all settings on this configuration endpoint will apply to it.
Use credential vault: This will allow you to select a username/password credential stored on Dynatrace's Credential Vault. Using this feature will ignore any username/password entered manually and instead will only use the credential stored in the vault.
User: Optional but recommended to add a user. Otherwise, if left blank, IBM MQ will try to authenticate user running process, dtuser
by default.
Password: Password to user above.
Objects to monitor: Two methods of adding objects.
*, -SYSTEM.*, SYSTEM.CLUSTER*
would include all queues, then remove those that start with SYSTEM. then include those that start with SYSTEM.CLUSTER. Pay close attention to the order you enter your rules, whether in Wizard or Advanced mode.Send log event on Dead letter queue: Enable this if you would like any DLQ on any queue manager matching this configuration to trigger a log event indicating that the number of messages in DLQ exceeded threshold. You may create an alert based on that log event
Send log event on high queue depth from queue manager: Enable this if you would like any matching queue on any queue manager in this configuration to trigger a log event when its configured depth threshold is exceeded. This threshold is configured on IBM MQ.
Send log event on low queue depth from queue manager: Enable this if you would like any matching queue on any queue manager in this configuration to trigger a log event when its configured depth lower than threshold. This threshold is configured on IBM MQ.
Retrieve topology for improved transaction tracing: Enabling this setting will collect mappings for alias queues, remote queues, and cluster queues. This mapping is then sent to Dynatrace to complement mapping information for improved transaction tracing. You may only need to collect this once unless your mappings on IBM MQ change frequently. When enabled, enter a Dynatrace token to communicate with the API with these permission: Read settings
, Write settings
.
Rename Queue managers: Enabling this setting will allow you to add an alias to queue managers matching your queue manager filter (above). The real queue manager name will still be included in the name. This is only to differentiate queue managers with similar or same names on Dynatrace. This will not rename any queue manager on IBM MQ.
Inquire metrics in bulk: Enabling this setting will reduce the number of requests to IBM MQ and collect metrics for queues and channels in less requests thus reducing time and potential CPU overhead. However, this setting will require granting permissions to all queues and all channels, even SYSTEM objects too. This setting is not suitable for large environments with a large amount of queues or channels.
Lastly, select which feature sets (metric groups) you would like this configuration to collect. Selecting too few will not give you the proper visibility and you may miss out on important performance data, as well as key indicators that can be correlated between different objects.
Log level: Enable DEBUG only when troubleshooting or support makes that recommendation.
Add a Queue Manager: Click on this button for each queue manager you want to connect. Multiple queue managers per ActiveGate group is recommended.
Comma-separated hosts: Most queue managers run on a single host but there are times you have multi-instance queue managers that run across multiple hosts. Enter that single host and port here, or the comma-separated list of host and ports for that one queue manager.
Queue manager name: Enter the name of the single queue manager you are connecting to. This is required.
Server-connection channel: Any client application, such as this extension, that connects to IBM MQ must talk to the queue manager via a channel. Enter the name of that Server-connection channel here.
Use credential vault: This will allow you to select a username/password credential stored on Dynatrace's Credential Vault. Using this feature will ignore any username/password entered manually and instead will only use the credential stored in the vault.
Username: Optional but recommended to add a user. A user is always passed, but depending on the queue manager configuration on IBM MQ, it can be ignored or this user in this field can be authenticated. It is best to always enter a user.
Password: Password to user above.
Model queue: Optional. If not set, it will use the SYSTEM default model queue for command requests and responses.
Reply prefix: If you entered a model queue, you must enter a prefix for the reply queue.
Objects to monitor: Two methods of adding objects.
*, -SYSTEM.*, SYSTEM.CLUSTER*
would include all queues, then remove those that start with SYSTEM. then include those that start with SYSTEM.CLUSTER. Pay close attention to the order you enter your rules, whether in Wizard or Advanced mode.Send log event on Dead letter queue: Enable this if you would like any DLQ on any queue manager matching this configuration to trigger a log event indicating that the number of messages in DLQ exceeded threshold. You may create an alert based on that log event
Send log event on high queue depth from queue manager: Enable this if you would like any matching queue on any queue manager in this configuration to trigger a log event when its configured depth threshold is exceeded. This threshold is configured on IBM MQ.
Send log event on low queue depth from queue manager: Enable this if you would like any matching queue on any queue manager in this configuration to trigger a log event when its configured depth lower than threshold. This threshold is configured on IBM MQ.
Retrieve topology for improved transaction tracing: Enabling this setting will collect mappings for alias queues, remote queues, and cluster queues. This mapping is then sent to Dynatrace to complement mapping information for improved transaction tracing. You may only need to collect this once unless your mappings on IBM MQ change frequently. When enabled, enter a Dynatrace token to communicate with the API with these permission: Read settings
, Write settings
.
Rename Queue manager: Enabling this setting will allow you to add an alias to the queue manager defined above. The real queue manager name will still be included in the name. This is only to differentiate queue managers with similar or same names on Dynatrace. This will not rename any queue manager on IBM MQ.
The following is an approximation. Metrics change depending on type of objects. Some metrics are not available to all channels, some metrics are not available to all queues.
Assuming you get all metrics for all objects: ((10) + (Local queues * 16) + (Alias + Remote queues) * 2 + (Channels * 18) + (Listeners) + (Topics * 4)) * Queue managers * 525.6 = DDUs per year
For example:
1 Queue manager
400 Local queues
20 Alias and remote queues
50 Channels
1 Listener
50 Topics
( 10 + (400 * 16) + (20 * 2) + (50 * 18) + (1 * 1) + (50 * 4) ) * 1 * 525.6 =
(10 + 6400 + 40 + 900 + 1 + 200) * 525.6 = approximately 3.9M DDUs per year
Some metrics depend on the type of queues. Other metrics depend on your queue manager configuration and if your user has enough permissions to collect them.
Are you missing Enqueue and Dequeue? Make sure your user has CHG permission on queues to reset statistics on queues. Only then you can receive Enqueue and Dequeue metrics.
Are you missing Oldest message and Last get/put? Make sure Monitoring statistics is enabled on your queue manager for all queues.
Are you looking at Alias or Remote queues? Only Locally defined queues have status metrics. Alias and Remote only have Inhibit GET/PUT metrics.
Check the AMQERR01.LOG
on the queue manager itself. This log file will tell you what it tried to authenticate and what permissions you are missing.
If you are unable to connect to your queue manager, make sure that either the user running the extension process has permissions to the queue manager, or ADOPTCTX
and CHLAUTH
is enabled so that it can authenticate the user and password combination passed in the MQCSP
block.
This means that the IBM MQ libraries were not found in the unix PATH. Make sure you follow the ldconfig
step above under Local deployment
MQRC_HOST_NOT_AVAILABLE: Queue manager is not reachable from your ActiveGate. This usually means a firewall rule is missing. Because a queue manager can run on a custom port, you must make sure that host:port is reachable from the ActiveGate running the extension.
MQRC_NO_MSG_AVAILABLE: It took too long to get a response back from your queue manager and the response was blank. This can happen if the MAX LENGTH size of your reply queue is not enough to fit the response payload. You can try increasing that value. It may also be caused because of a timeout or the queue manager did not respond in time.
MQRC_CONNECTION_BROKEN: The connection to the queue manager is severed either due to a network interruption or the queue manager closed it. Make sure your network performance is optimal. Also, if you are using SSL, make sure that you are not using an older TLS cipher that requires manual reset of TLS keys such as TLS 1.2 AES-GCM ciphers. Switch to a TLS 1.3 Cipher that has automatic TLS keys reset.
Below is a complete list of the feature sets provided in this version. To ensure a good fit for your needs, individual feature sets can be activated and deactivated by your administrator during configuration.
Metric name | Metric key | Description | Unit |
---|---|---|---|
Oldest message | ibmmq.queue.oldest_message | Age in seconds of the oldest message on the queue. | Second |
Uncommitted messages | ibmmq.queue.uncommitted_messages | Number of handles opened by applications for output | Count |
Last GET | ibmmq.queue.last_get | Time at which the last message was successfully read from the queue. | MilliSecond |
Last PUT | ibmmq.queue.last_put | Time at which the last message was successfully put in queue. | MilliSecond |
Short time indicator | ibmmq.queue.time_indicator_short | Amount of time that a message spent on the queue over a short period. | MicroSecond |
Long time indicator | ibmmq.queue.time_indicator_long | Amount of time that a message spent on the queue over a long period. | MicroSecond |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Inhibit GET | ibmmq.queue.inhibit_get | Whether queue inhibits MQGET | Unspecified |
Inhibit PUT | ibmmq.queue.inhibit_put | Whether queue inhibits MQPUT | Unspecified |
Metric name | Metric key | Description | Unit |
---|---|---|---|
In-doubt | ibmmq.channel.in_doubt | Whether the channel is currently in doubt. 0 = No. 1 = Yes | Unspecified |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Enqueue count | ibmmq.queue.enqueue_cnt | Number of messages enqueued. This count includes messages that have been put to the queue, but have not yet been committed. Enqueue rate also comes with this metric. | Count |
Dequeue count | ibmmq.queue.dequeue_cnt | Number of messages dequeued. This count includes messages that have been successfully retrieved (with a nonbrowse MQGET) from the queue, even though the MQGET has not yet been committed. Dequeue rate also comes with this metric. | Count |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Open input handles | ibmmq.queue.open_input_handles | Number of handles opened by applications for input | Count |
Open output handles | ibmmq.queue.open_output_handles | Number of handles opened by applications for output | Count |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Publish count | ibmmq.topic.pub_cnt | The number of applications currently publishing to the topic. | Count |
Subcription count | ibmmq.topic.sub_cnt | The number of subscribers for this topic string, including durable subscribers who are not currently connected. | Count |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Depth | ibmmq.queue.depth | Number of messages in queue | Count |
Depth percentage | ibmmq.queue.depth_percent | Percentage of messages filling up queue | Percent |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Channel status | ibmmq.channel.status | Used to round up channel status counts for alerting and charting purposes | Unspecified |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Log utilization | ibmmq.queue_manager.log_utilization | Percentage estimate of how well the queue manager workload is contained within the primary log space | Percent |
Log in use | ibmmq.queue_manager.log_in_use | Percentage of the primary log space in use for restart recovery | Percent |
Log archive size | ibmmq.queue_manager.log_archive_size | Amount of space occupied, in megabytes, by log extents no longer required for restart or media recovery, but waiting to be archived. | MegaByte |
Log reuse size | ibmmq.queue_manager.log_reuse_size | Amount of space occupied, in megabytes, by log extents available to be reused. | MegaByte |
z/OS Total log data sets | ibmmq.queue_manager.total_log_data_sets | The total number of active log data sets. | Count |
z/OS Full log data sets | ibmmq.queue_manager.full_log_data_sets | The total number of full active log data sets that have not yet been archived. | Count |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Availability | ibmmq.queue_manager.availability | Percentage of time queue manager was reachable and available to this extension. While a queue manager sometimes may be up and running, availability is within the context of this extension. | Percent |
Uptime | ibmmq.queue_manager.uptime | Time in seconds since last time queue manager started | Second |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Long retries left | ibmmq.channel.long_retries_left | Number of long retry attempts remaining | Count |
Short retries left | ibmmq.channel.short_retries_left | Number of short retry attempts remaining | Count |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Messages | ibmmq.channel.messages | Number of messages sent or received, or number of MQI calls handled. | Count |
Batches | ibmmq.channel.batches | Number of completed batches | Count |
In-doubt messages | ibmmq.channel.current_messages | Number of messages in-doubt | Count |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Inhibit publish | ibmmq.topic.inhibit_pub | Whether publishes are not allowed | Unspecified |
Inhibit subscription | ibmmq.topic.inhibit_sub | Whether subscriptions are not allowed | Unspecified |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Connections | ibmmq.queue_manager.connections | Number of active connections to queue manager | Count |
Queues count | ibmmq.queue_manager.monitored_queues | Number of monitored queues | Count |
DLQ depth | ibmmq.queue_manager.dlq_depth | Number of messages in dead letter queue | Count |
Active channels | ibmmq.queue_manager.active_channels | Number of channels in an active current status | Count |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Channel instances | ibmmq.channel.instances | Number of instances of this channel. This metric is only available to server-connection channels. | Count |
Current shared conversations | ibmmq.channel.current_sharing_convs | Number of conversations currently active on this channel instance. This parameter is returned only for TCP/IP server-connection channels. | Count |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Total pages | ibmmq.queue_manager.usage.pageset.total_pages | The total number of 4 KB pages in the page set. Available only on z/OS IBM MQ | Count |
Expand count | ibmmq.queue_manager.usage.pageset.expand_cnt | The number of times the page set has been dynamically expanded since restart. Available only on z/OS IBM MQ | Count |
Unused pages | ibmmq.queue_manager.usage.pageset.unused_pages | The number of pages that are not used (that is, available page sets). Available only on z/OS IBM MQ | Count |
Persistent pages | ibmmq.queue_manager.usage.pageset.persistent_data_pages | The number of pages holding persistent data. Available only on z/OS IBM MQ | Count |
Non-persistent pages | ibmmq.queue_manager.usage.pageset.nonpersistent_data_pages | The number of pages holding nonpersistent data. Available only on z/OS IBM MQ | Count |
Free buffers | ibmmq.queue_manager.usage.buffer_pool.free_buffers | Number of free buffers in buffer pool. Available only on z/OS IBM MQ | Count |
Percent of free buffers | ibmmq.queue_manager.usage.buffer_pool.percent_free_buffers | Number of free buffers as a percentage of all buffers in the buffer pool. Available only on z/OS IBM MQ | Percent |
Total buffers | ibmmq.queue_manager.usage.buffer_pool.total_buffers | The number of buffers defined for specified buffer pool. Available only on z/OS IBM MQ | Count |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Bytes sent | ibmmq.channel.bytes_sent | Number of bytes sent | Byte |
Bytes received | ibmmq.channel.bytes_rcvd | Number of bytes received | Byte |
Buffers sent | ibmmq.channel.buffers_sent | Number of buffers sent. | Count |
Buffers received | ibmmq.channel.buffers_rcvd | Number of buffers received. | Count |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Last message sent | ibmmq.channel.last_msg | Time when last message was sent, or MQI call was handled | Second |
Network time short | ibmmq.channel.nettime_short | Amount of time, in microseconds, to send an end of batch request to the remote end of the channel and receive a response over a short period. | MicroSecond |
Network time long | ibmmq.channel.nettime_long | Amount of time, in microseconds, to send an end of batch request to the remote end of the channel and receive a response over a longer period. | MicroSecond |
XMIT queue time short | ibmmq.channel.xmitqtime_short | Time, in microseconds, that messages remained on the transmission queue before being retrieved over a short period. | MicroSecond |
XMIT queue time long | ibmmq.channel.xmitqtime_long | Time, in microseconds, that messages remained on the transmission queue before being retrieved over a longer period. | MicroSecond |
Metric name | Metric key | Description | Unit |
---|---|---|---|
Availability | ibmmq.listener.availability | Percentage this listener was running and available. | Percent |
Changes in this version:
This version takes filtering rules and evaluates them in sequential order. This allows you to enter more complex filtering rules based on results from the previous step.
For example:
will evaluate them in that specific order.
Same as:
*, -SYSTEM*, SYSTEM.CLUSTER*, -SYSTEM.CLUSTER.TRANSMIT.*
Make sure you review your rules when upgrading to this version to ensure they are ordered in the sequence you want to evaluate them
In case you need to change the order, there is no need to recreate rules. You can drag & drop them using your mouse over the dots next to each rule.
actual_qm_name
property is in all entities.Note: All patches are cumulative. For a list of fixes and enhancements, please look at Release notes in previous releases.
In this release: