Powerpack for Websphere MQ v8 1userguide
Post on 12-Apr-2015
302 Views
Preview:
DESCRIPTION
Transcript
Date: 04-2009
Version 8.1
CA Wily Introscope®
PowerPack for IBM® WebSphere® MQ Connectors and Messaging System
User Guide
6000 Shoreline Court, Suite 300 South San Francisco, CA 94080
Copyright © 2009, CA. All rights reserved.
Wily Technology, the Wily Technology Logo, Introscope, and All Systems Green are registered trademarks of CA.
Blame, Blame Game, ChangeDetector, Get Wily, Introscope BRT Adapter, Introscope ChangeDetector, Introscope Environment Performance Agent, Introscope ErrorDetector, Introscope LeakHunter, Introscope PowerPack, Introscope SNMP Adapter, Introscope SQL Agent, Introscope Transaction Tracer, SmartStor, Web Services Manager, Whole Application, Wily Customer Experience Manager, Wily Manager for CA SiteMinder, and Wily Portal Manager are trademarks of CA. Java is a trademark of Sun Microsystems in the U.S. and other countries. All other names are the property of their respective holders.
For help with Introscope or any other product from CA Wily Technology, contact Wily Technical Support at 1-888-GET-WILY ext. 1 or support@wilytech.com.
If you are the registered support contact for your company, you can access the support Web site directly at www.ca.com/wily/support.
We value your feedback
Please take this short online survey to help us improve the information we provide you. Link to the survey at: http://tinyurl.com/6j6ugb
If you have other comments or suggestions about Wily documentation, please send us an email at wily-techpubs@ca.com.
US Toll Free 888 GET WILY ext. 1 US +1 630 505 6966 Fax +1 650 534 9340 Europe +44 (0)870 351 6752 Asia-Pacific +81 3 6868 2300 Japan Toll Free 0120 974 580 Latin America +55 11 5503 6167
www.ca.com/apm
Contents iii
CONTENTS
Table of Contents
Chapter 1 PowerPack for IBM WebSphere MQ . . . . . . . . . . . 1
About PowerPack for MQ. . . . . . . . . . . . . . . . . 2Components . . . . . . . . . . . . . . . . . . . . . 3What’s new in PowerPack for MQ . . . . . . . . . . . . . . 4
Chapter 2 Installing and Configuring the PowerPack for MQ . . . . . . 9
Preparing to install PowerPack for MQ . . . . . . . . . . . . 10
Check system and version requirements . . . . . . . . . . 10
Identify installation machines and directories . . . . . . . . 10
Check server connection and access. . . . . . . . . . . . 10
Download the PowerPack for MQ . . . . . . . . . . . . . 11
Install PowerPack for MQ with minimum configuration . . . . . . 12
Install and configure the MQMonitor agent . . . . . . . . . . 15
Extract the MQMonitor agent files . . . . . . . . . . . . 15
Check the Java environment requirement . . . . . . . . . . 16
Obtain third-party libraries . . . . . . . . . . . . . . . 17
Configure the MQMonitor agent for third-party libraries . . . . . 19Configure the MQMonitor agent properties . . . . . . . . . 20
Security settings for CMP, JMS, PCF connections . . . . . . . 32Run the MQMonitor agent . . . . . . . . . . . . . . . 43
Configure WebSphere MQ for MQ Trace . . . . . . . . . . . 43
Upgrade the MQMonitor agent . . . . . . . . . . . . . . 44
(Optional) Install MQMonitor agent as a Windows Service . . . . . 46
Install and configure MQ Java Connectors . . . . . . . . . . 47
Extract the MQ Java Connectors files . . . . . . . . . . . 47
Configure MQ Java Connectors . . . . . . . . . . . . . 49
Configure ErrorDetector . . . . . . . . . . . . . . . . 53
Configure JCA Connection Pool . . . . . . . . . . . . . 55
Install Management Modules and extensions . . . . . . . . . 56
iv Contents
PowerPack for WebSphere MQ Connectors and Messaging System
Additional Information . . . . . . . . . . . . . . . . . 57
Configure SSL . . . . . . . . . . . . . . . . . . . 58
Configure WebSphere MB . . . . . . . . . . . . . . . 64
Configure WebSphere MQ to publish events . . . . . . . . . 65
Turn on Queue Monitoring . . . . . . . . . . . . . . . 66
Chapter 3 Viewing Data Using PowerPack for MQ . . . . . . . . . . 67
View data . . . . . . . . . . . . . . . . . . . . . . 67
Console dashboards . . . . . . . . . . . . . . . . . . 67
MQ dashboards in the Console. . . . . . . . . . . . . . 67
Investigator dashboards . . . . . . . . . . . . . . . . 68
Understanding the metrics tree . . . . . . . . . . . . . 68
Investigator Dashboards and data displays . . . . . . . . . 74
Aggregated metrics . . . . . . . . . . . . . . . . . 76
MQ Events. . . . . . . . . . . . . . . . . . . . . 79
Using dashboards in troubleshooting . . . . . . . . . . . . 81
Troubleshooting Queue Manager clusters and Queue Managers . . 81
Troubleshooting Message Brokers . . . . . . . . . . . . 84
Chapter 4 Transaction Tracing . . . . . . . . . . . . . . . . . . 85
Cross-Process Transaction Tracing . . . . . . . . . . . . . 86
Transaction Trace Viewer . . . . . . . . . . . . . . . . 86
Configure the WebSphere MQ System for trace . . . . . . . . 87
Set the Activity recording property . . . . . . . . . . . . 88
Configure SYSTEM.ADMIN.ACTIVITY.QUEUE . . . . . . . . . 90
Set the handshake queue . . . . . . . . . . . . . . . 90
Set the MCA User ID . . . . . . . . . . . . . . . . . 91
Verify the transaction trace configuration. . . . . . . . . . . 91
WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard . . . . . . . . . . . . . . 92
Configure EM for trace . . . . . . . . . . . . . . . . . 96
Interpret trace information. . . . . . . . . . . . . . . . 97
Identify a slow transaction . . . . . . . . . . . . . . . . 102
Enable or disable MQ Traces . . . . . . . . . . . . . . . 104
Filter queues for transaction trace . . . . . . . . . . . . . 105
Trace data properties . . . . . . . . . . . . . . . . . 106
Contents v
User Guide
Appendix A Dashboards . . . . . . . . . . . . . . . . . . . . 109
Management Modules . . . . . . . . . . . . . . . . . 109
WebSphere MQ Client and Server dashboards . . . . . . . . . 109
WebSphere MQ Client And Server Overview dashboard . . . . . 110
WebSphere MQ Client And Server Overview - Details dashboard . . 112
WebSphere MQ - Client Connections dashboard. . . . . . . . 115WebSphere MQ - Client Operations dashboard . . . . . . . . 116WebSphere MQ - Server dashboard . . . . . . . . . . . . 117
WebSphere Message Broker dashboards . . . . . . . . . . . 118
WebSphere Message Broker Overview dashboard . . . . . . . 118
Other Message Broker dashboards . . . . . . . . . . . . 120
Message Broker alerts . . . . . . . . . . . . . . . . 121
Appendix B Metrics reference . . . . . . . . . . . . . . . . . . 123
General metric characteristics. . . . . . . . . . . . . . . 123
Metric display sets . . . . . . . . . . . . . . . . . . 124
Queue Manager Cluster metrics . . . . . . . . . . . . . . 125
Aggregate clusters status metrics . . . . . . . . . . . . 125
Top level repository trees . . . . . . . . . . . . . . . 126
Workload Balance metrics . . . . . . . . . . . . . . . 139
Queue Manager metrics . . . . . . . . . . . . . . . . . 146
Top level Queue Manager aggregated metrics . . . . . . . . 147
Channel metrics . . . . . . . . . . . . . . . . . . . 148
Configuration Properties metrics . . . . . . . . . . . . . 153
Dead Letter Queue metrics . . . . . . . . . . . . . . . 162
Last Check metrics . . . . . . . . . . . . . . . . . . 163
Queue metrics . . . . . . . . . . . . . . . . . . . 164
Channel Initiator metrics. . . . . . . . . . . . . . . . 172Log metrics . . . . . . . . . . . . . . . . . . . . 174Usage metrics . . . . . . . . . . . . . . . . . . . 177
Queue Manager Status metrics . . . . . . . . . . . . . 180Message Broker metrics . . . . . . . . . . . . . . . . . 181
Configuration Manager aggregate totals . . . . . . . . . . 182
Broker properties and aggregate totals. . . . . . . . . . . 183
Execution Groups metrics . . . . . . . . . . . . . . . 184
MQ Java Connector metrics . . . . . . . . . . . . . . . 196
Operational groups. . . . . . . . . . . . . . . . . . 196
vi Contents
PowerPack for WebSphere MQ Connectors and Messaging System
Backend metrics . . . . . . . . . . . . . . . . . . 197
Instance Counts metrics . . . . . . . . . . . . . . . . 198
JCA node metrics . . . . . . . . . . . . . . . . . . 198
WebSphereMQ node metrics . . . . . . . . . . . . . . 199
ErrorDetector metrics . . . . . . . . . . . . . . . . . 204
Appendix C JCA/JMS Operational Groups . . . . . . . . . . . . . 207JCA Operational Groups . . . . . . . . . . . . . . . . 207
JCA Queue Manager Operations . . . . . . . . . . . . . 208
JCA Queue Operational Groups . . . . . . . . . . . . . 210
JMS Operational Groups . . . . . . . . . . . . . . . . 210
JMS Queue Manager Operational Groups . . . . . . . . . . 211
JMS Queue/Topic Operational Groups . . . . . . . . . . . 213
Appendix D Performance and Sizing . . . . . . . . . . . . . . . 215
MQMonitor agent background . . . . . . . . . . . . . . . 215
WebSphere MQ Sizing . . . . . . . . . . . . . . . . . 216
Sizing your MQMonitor agent . . . . . . . . . . . . . . 218
Sample MQMonitor agent sizing table . . . . . . . . . . . 219WebSphere MB Sizing . . . . . . . . . . . . . . . . . 221
Sizing your MQMonitor agent for WebSphere MB . . . . . . . 222
Sample MQMonitor agent sizing table for WebSphere MB . . . . 222
Appendix E Frequently Asked Questions . . . . . . . . . . . . . 225Alerts and dashboards . . . . . . . . . . . . . . . . 225
Installation . . . . . . . . . . . . . . . . . . . . 226
Metrics . . . . . . . . . . . . . . . . . . . . . . 226
Queues . . . . . . . . . . . . . . . . . . . . . . 227
Transaction Tracing . . . . . . . . . . . . . . . . . 227
Appendix F Troubleshooting . . . . . . . . . . . . . . . . . . 231
Appendix G Support for IPv6 Environment . . . . . . . . . . . . . 237Connect to the Introscope EM in an IPv6 environment . . . . . 237
Support for WebSphere MQ and WebSphere MB in an IPv6 environment . . . . . . . . . . . . . . . . 238
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Index . . . . . . . . . . . . . . . . . . . . . . . . . . 241
PowerPack for IBM WebSphere MQ 1
CHAPTER 1
PowerPack for IBM WebSphere MQ
The PowerPack for IBM® WebSphere® MQ Connectors and Messaging System
allows administrators to monitor the health and performance of IBM®
WebSphere® Message Queue (WebSphere MQ) and IBM® WebSphere® Message Broker (WebSphere MB).
This chapter contains the following topics:
About PowerPack for MQ . . . . . . . . . . . . . . . . . 2
Components . . . . . . . . . . . . . . . . . . . . . 3
What’s new in PowerPack for MQ . . . . . . . . . . . . . . . 4
2 PowerPack for IBM WebSphere MQ
PowerPack for IBM WebSphere MQ Connectors and Messaging System
About PowerPack for MQ
An extension of Introscope, Wily’s flagship web application management solution, the PowerPack for IBM WebSphere MQ Connectors and Messaging System (PowerPack for MQ) lets you monitor the performance of WebSphere MQ and WebSphere MB. By using the metrics provided by PowerPack for MQ, you can monitor the health and availability of WebSphere MQ-connected web applications and quickly isolate the source of WebSphere MQ-related and WebSphere MB-related performance problems.
The PowerPack for MQ lets you:
Monitor the performance of the WebSphere MQ infrastructure
Monitor the performance of WebSphere MB
Monitor the performance of WebSphere MQ Java Connectors
Correlate WebSphere MQ-to-application activity
Verify the use of WebSphere MQ capacity and use of MB capacity by web applications
Verify if WebSphere MQ and WebSphere MB meet the Service Level Agreements of web applications
The PowerPack for MQ provides Management Modules with pre-configured dashboards and performance-triggered alerts to monitor critical messages and queues for WebSphere MQ, and also monitor the health and availability of various WebSphere MB components.
The PowerPack for MQ helps ensure high availability of all WebSphere MQ-connected Java web applications.
3
User Guide
Components
The PowerPack for MQ consists of three components:
MQMonitor agent
The MQMonitor agent reports data on the performance of WebSphere MQ resources, such as queues and channels, to Introscope, which in turn displays the data as metrics under the following nodes in the Introscope Workstation Investigator metrics tree:
Queue Managers—The Queue Managers directory lists metric data for Queues, Channels, Logs (z/OS only), Usage (z/OS only), Channel Initiators (z/OS only), and Queue Manager objects.
Queue Manager Clusters—The Introscope Workstation Investigator displays Cluster Queue Managers along with their associated queues and channels so that you can easily monitor cluster performance. Multi-instanced cluster queues appear under the Workload Balance directory.
The MQMonitor agent monitors WebSphere MB and reports data on the performance of the WebSphere MB components to Introscope, where the data can be viewed as metrics in the Introscope Investigator tree under the WebSphere Message Broker node.
MQ Java Connectors Monitor
The MQ Java Connectors Monitor monitors the WebSphere MQ classes (both Connector and JMS) used for communicating with WebSphere MQ from a web application deployed on an application server. The web applications can use either JMS or Connector classes (or a combination of both) to communicate with WebSphere MQ. The data is displayed as metrics in the Introscope Investigator tree under the WebSphereMQ node.
Management Modules and Enterprise Manager (EM) extensions
The Management Modules contain pre-configured dashboards and alerts that Introscope uses to display WebSphere MQ and WebSphere MB metrics in graphical form. This component also includes dashboards for the Investigator as well as Javascript calculators and EM extensions which aggregate metric data for display in the Introscope Investigator. You can configure the dashboards and alerts to proactively alert operations and application-support personnel and WebSphere MQ administrators of potential WebSphere MQ and WebSphere MB issues before they become application performance bottlenecks.
4 PowerPack for IBM WebSphere MQ
PowerPack for IBM WebSphere MQ Connectors and Messaging System
What’s new in PowerPack for MQ
PowerPack for MQ has the following features.
Monitor WebSphere MQ over secured channels
If channel security is enabled over Secure Sockets Layer (SSL), then you can monitor WebSphere MQ over secured channels. For information on SSL, see Configure SSL on page 58.
Cross-process transaction trace from applications to WebSphere MQ
This feature enables Introscope to provide transaction trace views of transactions starting from the servlet upto the Queue Managers. The cross-process transaction tracing extends the monitoring capability of PowerPack for MQ and lets you determine the components of WebSphere MQ that are causing performance bottlenecks.
Cross-process transaction tracing helps you do the following:
Acquire and analyze WebSphere MQ performance information and identify performance problems caused by WebSphere MQ.
Identify whether WebSphere MQ is responsible for an application slowdown.
Extend the monitoring capability of PowerPack for MQ to determine which component of WebSphere MQ is causing the performance bottleneck.
Enable Introscope to provide transaction trace views of transactions starting from servlet all the way into the Queue Managers.
Identify the time taken by the message to pass through various queues and channels of a transaction (application to destination queue).
Correlate the trace data obtained from WebSphere MQ components with the trace data from the Introscope-enabled WebSphere MQ client application that has posted the WebSphere MQ message.
Provide a full transaction trace view when WebSphere MQ is used in the request-response mode.
PowerPack for MQ includes the WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard that you can use to check whether your WebSphere MQ infrastructure is properly configured for MQ Trace. You can also use the mqConfigurationSetup tool to automate the configuration of cross-process transaction tracing.
For more information, see Cross-Process Transaction Tracing on page 86.
5
User Guide
Filter dynamic queues in WebSphere MQ
When an application program issues an MQOPEN call to open a model queue, the Queue Manager dynamically creates an instance of a local queue with the same attributes as the model queue. Depending on the value of the Definitiontype field of the model queue, the Queue Manager creates either a temporary or permanent dynamic queue.
If the dynamic queues show up as regular queues during PowerPack for MQ monitoring inquiries, this may cause too many metrics to be displayed. Hence an option is provided to either enable or disable the display of dynamic queues in the Investigator tree.
If dynamic queues are filtered from being monitored, the response time improves.
Set the following property in MQMonitor.properties file to enable filtering so that dynamic queues are not monitored: <Queue Manager>@<hostname>.queue.filter.exclude.dynamic=true
In case of MQ Java connectors, the dynamic queues are always displayed under the Dynamic Queues node.
If the delay time of the MQMonitor agent is very high compared to the duration of the existence of the temporary dynamic queues in the Queue Manager, and if you enable filtering so that dynamic queues are not monitored, then:
Most of the metrics for the temporary dynamic queues may not appear in the Investigator tree.
A few metrics such as Current Queue Depth may display incorrect data.
Management Modules—New WebSphere MQ Client and Server dashboards
PowerPack for MQ includes the new WebSphere MQ Client and Server dashboards that show the real-time performance and health of WebSphere MQ system. The WebSphere MQ Client and Server dashboards are a set of five dashboards that you can use to correlate the activity of the WebSphere MQ Client Connections using the MQ Java Connector operations on the WebSphere MQ system, with the actual activities on the WebSphere MQ system. You can obtain metrics about the number of put, get, send, and receive operations, the response times, and queue depth information.
For more information, see WebSphere MQ Client and Server dashboards on page 109.
6 PowerPack for IBM WebSphere MQ
PowerPack for IBM WebSphere MQ Connectors and Messaging System
Support WebSphere MQ v7.0 and WebSphere MB v6.1
PowerPack for MQ provides additional support for WebSphere MQ v7.0 and WebSphere MB v6.1. All features in the PowerPack for MQ are compatible with WebSphere MQ v7.0 and WebSphere MB v6.1.
Support non-English character sets in WebSphere MQ
PowerPack for MQ can monitor both the English and non-English versions of WebSphere MQ objects. To do this, set the following property in the MQMonitor.properties file:
<Queue_Manager>@<hostname>.character.set = <Relevant IBM non-English CCSID>
where <Queue_Manager> is the Queue Manager name, <hostname> is the host name of the system where WebSphere MQ is installed, and CCSID is the supported IBM ID for that specific non-English language. CCSID is an abbreviation used by IBM to mean "Coded Character Set Identifier". It is a 16-bit number that represents a specific encoding of a specific code page.
For example, if WebSphere MQ is installed on a Korean operating system, the IBM CCSID for Korean language needs to be placed in the character.set property.
» Note PowerPack for MQ does not monitor non-English versions of WebSphere MB.
The following scenario illustrates how the MQMonitor agent monitors WebSphere MQ running on a non-English operation system:
Suppose WebSphere MQ is running on a non-English operating system (say,
Korean). When you create objects using the IBM® MQ Explorer (MQ Explorer), you must mention details such as Queue Manager name and Channel name in English and not in any non-English language. You must ensure that the schema is also in English. However, the properties for these objects may be in the non-English language. In such a scenario:
The MQMonitor agent of the PowerPack for MQ running on an English OS connects to a non-English (Korean) MQ system. Connection is possible because details such as the Queue Manager Name, Channel name, and so on, are displayed in English and have provided the Korean CCSID.
Introscope Enterprise Manager and Workstation are residing on an English OS host. Here, the top level names such as the Queue Manager name, channel name, and so on, are displayed in English and the Investigator metric values for these objects are also in English because the PowerPack for MQ returns IBM constants instead of the values on the WebSphere MQ system that are in the local language.
7
User Guide
» Important If the host name of the system is in a non-English language, then you must use the IP Address of the non-English machine for configuring the Queue Managers in the MQMonitor.properties file, instead of the host name.
Easier configuration of the MQMonitor agent
The property names of a few properties have been changed in the MQMonitor agent. If you are using the older version of the MBMonitor.properties file, you need to upgrade the old property file to the new one by replacing the old property name with the new property name. You can use the same value for the properties.
To relate the old properties to the new properties, see the following table:
Old property name New property name
CMP_MACHINE configuration.manager.host
CMP_QUEUE_MANAGER configuration.manager.queue.manager
CMP_PORT configuration.manager.port
MQ_Broker_List mq.broker.list
Statistics_Broker_List statistics.broker.list
JMS_MACHINE jms.broker.host
JMS_QUEUE_MANAGER jms.broker.queue.manager
JMS_PORT jms.broker.port
<BROKER>.EXEGRP <BROKER>.executiongroup
Node_Type_List node.type.list
Static_Delay_time static.delay.time
8 PowerPack for IBM WebSphere MQ
PowerPack for IBM WebSphere MQ Connectors and Messaging System
Installing and Configuring the PowerPack for MQ 9
CHAPTER 2
Installing and Configuring the PowerPack for MQ
This chapter contains instructions for installing and configuring the various components of PowerPack for MQ.
This chapter contains the following topics:
Preparing to install PowerPack for MQ . . . . . . . . . . . . 10
Install PowerPack for MQ with minimum configuration . . . . . . . 12
Install and configure the MQMonitor agent . . . . . . . . . . . 15
Configure WebSphere MQ for MQ Trace . . . . . . . . . . . . 43
Upgrade the MQMonitor agent . . . . . . . . . . . . . . . 44
(Optional) Install MQMonitor agent as a Windows Service . . . . . . 46
Install and configure MQ Java Connectors . . . . . . . . . . . 47
Install Management Modules and extensions . . . . . . . . . . 56
Additional Information . . . . . . . . . . . . . . . . . 57
10 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Preparing to install PowerPack for MQFollow the steps below to prepare for installation.
Check system and version requirements, below.
Identify installation machines and directories, below.
Check server connection and access, below.
Download the PowerPack for MQ on page 11.
Check system and version requirements
Ensure that your environment includes the following products and components:
IBM WebSphere MQ v6.x or v7.0
IBM WebSphere MB v6.0 or v6.1
Wily Introscope Workstation v8.0.3
Wily Introscope Enterprise Manager v8.0.3
Wily Introscope Agent v8.0.3
Identify installation machines and directories
To correctly install the software, you must identify the host name and directory path names of installed software:
Introscope Agent installation directory
Usually this is <appserver>/wily, where <appserver> is the home directory of your application server software.
<Introscope Home> directory on the machine hosting the Introscope Enterprise Manager.
Check server connection and access
To ensure proper server connection, check if you have the following:
A WebSphere MQ command server defined and running on the Queue Manager.
A Server Connection channel defined on the Queue Manager.
» Note Contact your WebSphere MQ specialist for details about configuring the Queue Manager machine.
The MQMonitor agent has TCP/HOST network access through firewalls.
Preparing to install PowerPack for MQ 11
User Guide
Download the PowerPack for MQ
Use the link to the CA Wily Software Download Site provided in the software delivery email. The following table lists the file names of the software archive for the Windows, UNIX, and z/OS platforms:
Platform Archive file names
UNIX PowerPackForWebSphereMQv8.1Unix.tar
Windows PowerPackForWebSphereMQv8.1Windows.zip
z/OS PowerPackForWebSphereMQv8.1Zos.tar
Windows and UNIX
The archive extraction steps for Windows and UNIX are the same; only the extension of the archives is different.
Type of file Windows OS file extensions
Equivalent UNIX file extensions
archive .zip .tar
executable .bat .sh
For example:
To download the PowerPack for MQ for Windows:
1 Download the PowerPack for MQ software archive PowerPackForWebSphereMQv8.1Windows.zip.
2 Open and uncompress the archive. The archive has the following files:
PowerPackForWebSphereMQv8.1Agent.windows.zip
PowerPackForWebSphereMQv8.1EM.windows.zip
PowerPackForWebSphereMQv8.1MQMonitor.windows.zip
To download the PowerPack for MQ for z/OS:
1 Download the PowerPack for MQ software archive -PowerPackForWebSphereMQv8.1Zos.tar.
2 Open and uncompress the archive. The archive has the following files:
PowerPackForWebSphereMQv8.1Agent.zos.tar
PowerPackForWebSphereMQv8.1EM.zos.tar
12 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Install PowerPack for MQ with minimum configuration
This section describes how you can quickly install PowerPack for MQ with minimum configuration.
Scenario 1:
An Introscope-enabled Java Application running on Solaris and is communicating to WebSphere MQ at the backend. The application drops a message to a queue of queue manager running under host “host_AIX” and a particular port. The message is routed to a mainframe queue manager running on another port under host “host_MF”. A CICS application picks up the message from the mainframe Queue manager, processes it, and puts it back on a queue of queue manager from where the application picks up the message.
To install and configure the PowerPack for MQ, perform the following steps:
1 Check the following:
The MQ Command Server is up and running for both the Queue Managers.
The version of the Introscope EM, Workstation, and Agent is at least v8.0.3.
The JAR files as mentioned Obtain third-party libraries on page 17.
2 Unzip PowerPackForWebSphereMQv8.1MQMonitor.windows.zip to a local directory.
3 Place all the third-party downloaded jar under MQMonitor\lib directory and accordingly configure the startMQMonitor.bat file.
4 Edit MQMonitor\properties\MQMonitor.properties and add the following lines:
mq.monitor.list=first,secondfirst.host=host_AIXsecond.host=host_MFfirst.port=4444second.port=5555
5 Execute mqConfigurationSetup.bat from the MQMonitor\tools directory and check changehistory.txt and console output to check for changes or errors. If you face any connection problems with the CA_WILY_HANDSHAKE queue, check if you have configured the handshake properly; if handshake is configured properly, then you can ignore the error messages.
6 Restart all the active channels of the monitored queue managers or if possible restart the Queue Manager.
7 Execute startMQMonitor.bat. You can ignore any warning messages.
Install PowerPack for MQ with minimum configuration 13
User Guide
8 Unzip PowerPackForWebSphereMQv8.1Agent.unix.tar to the \wily directory of Introscope-enabled Java application.
9 Add PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl to the IntroscopeAgent.profile file.
10 Restart the Application Server.
11 Unzip PowerPackForWebSphereMQv8.1EM.windows.zip to the EM root installation directory.
12 Restart the EM.
To verify the installation, see the WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard.
Scenario 2:
Monitoring a configuration manager that manages a few brokers. Also checking the health of the message brokers.
To install and configure the PowerPack for MQ, perform the following steps:
1 Unzip PowerPackForWebSphereMQv8.1MQMonitor.windows.zip to a local directory.
2 Place all the third-party downloaded JAR files under MQMonitor\lib directory, and accordingly configure startMQMonitor.bat file.
3 Edit MQMonitor\properties\MBMonitor.properties and set the values for the add the following properties:
jms.broker.host jms.broker.queue.managerjms.broker.port
4 Execute the MQMonitor\properties\MBMonitorJMSQueues.mqsc file on your JMS Queue Manager using the following command:
runmqsc <QMGR name>\MQMonitor\properties\MBMonitorJMSQueues.mqsc
5 Create an ACL entry on the Configuration manager using the following command: mqsicreateaclentry <ConfMgrName> -u <UserName> -m <machineName>/<DomainName> -x V –p
6 Enable statistics for Message flows on the Execution Groups on the broker named foo_broker:
mqsichangeflowstats foo_broker -s -e <ExecutionGroupName> -j -c active -o xml -n basic
7 Enable Publish/Subscribe statistics for the brokers using the command:
mqsichangeproperties foo_broker -e <ExecutionGroupName> -o DynamicSubscriptionEngine -n statsInterval -v 30000
14 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
8 Execute startMQMonitor.bat and run it for about 10 minutes.
To verify your installation, check the following:
All Message Broker related metrics are reported under the WebSphere MessageBroker node.
You can see Message Flow statistics metrics for each message flow of an execution group.
You can see Broker Statistics metrics under an execution group.
Install and configure the MQMonitor agent 15
User Guide
Install and configure the MQMonitor agentThe MQMonitor agent provides information related to WebSphere MQ resources such as Queue Managers, Queues, and Channels, as well as WebSphere MB resources such as Brokers and Message Flows. This capability lets you monitor various dynamic WebSphere MQ or WebSphere MB properties to trigger alerts, view utilization measurements of components, and view resource properties.
» Note The MQMonitor agent is supported only on Windows or UNIX for monitoring instances of WebSphere MQ. This version does not support MQMonitor agent running on z/OS.
To install and configure the MQMonitor agent:
1 Extract the MQMonitor agent files on page 15.
2 Check the Java environment requirement on page 16.
3 Obtain third-party libraries on page 17.
4 Configure the MQMonitor agent for third-party libraries on page 19.
5 Configure the MQMonitor agent properties on page 20.
6 Run the MQMonitor agent on page 43.
The following sections describe these steps in detail.
Extract the MQMonitor agent files
Extract the contents of the MQMonitor agent archive to any directory. Depending on the platform, the archive is named: PowerPackForWebSphereMQv8.1MQMonitor.windows.zip on Windows or PowerPackForWebSphereMQv8.1MQMonitor.unix.tar on UNIX.
» Note You can extract the MQMonitor agent files to any directory.
The contents of the archive are extracted into a single MQMonitor directory. The MQMonitor directory has the following structure:
/lib
Agent.jar
encryptpwd.jar
jline-0.9.9.jar
/tools
mqConfigurationSetup.bat (Windows) or mqConfigurationSetup.sh (UNIX)
16 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
/ext
extension.jar
Supportability-Agent.jar
/properties
MBMonitorJMSQueues.mqsc
IntroscopeAgent.profile
MBMonitor.properties
MBMonitor.properties.template
MQMonitor.properties
MQMonitor.properties.template
installMQMonitor.txt
MQMonitor.jar
mqPwdEncryptor.bat (Windows) or mqPwdEncryptor.sh (UNIX)
startMQMonitor.bat (Windows) or startMQMonitor.sh (UNIX) and stopMQMonitor.sh (UNIX)
The MQMonitor directory also contains files related to installing MQMonitor agent as a Windows Service. For information on installing MQMonitor agent as a Windows Service, see (Optional) Install MQMonitor agent as a Windows Service on page 46.
Check the Java environment requirement
PowerPack for MQ can report specific WebSphere MQ Events in the Investigator tree. For information on MQ Events, see Configure WebSphere MQ to publish events on page 65.
To display MQ Events information, you must do one of the following:
Install the International Version of Java Runtime Environment (JRE) 1.4 (or above), and use it to run the MQMonitor agent.
If the non-International Version of Java Runtime Environment (JRE) 1.4 (or above) is used to run the MQMonitor agent, then:
Obtain the charsets.jar file from the International Version of JRE 1.4 (or above).
Add the location of charsets.jar file to your system classpath.
» Note If you do not set the appropriate charsets.jar file in your Java Runtime Environment, then the MQMonitor agent does not report MQ Events.
Install and configure the MQMonitor agent 17
User Guide
» Important If you monitor Queue Managers over SSL, then do not use the JRE shipped with WebSphere MQ v6.0.0.0.0. Instead, use the Sun JRE v1.4 or later, or the latest WebSphere MQ JRE.
Obtain third-party libraries
To run the MQMonitor agent, you must obtain third-party JAR files and configure the MQMonitor agent.
PCF JAR file
As of 1 January, 2009, the com.ibm.mq.pcf-6.1.jar file can be downloaded from http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg24000668&loc=en_US&cs=utf-8&lang=en, subject to the accompanying license terms. Unzip the contents of the ms0b.zip archive to any directory of the machine where the MQMonitor agent is installed.
ConfigManagerProxy.jar
If IBM Message Brokers v6.0 or v6.1 is installed on the machine where the MQMonitor agent is installed, you can obtain the ConfigManagerProxy.jar file from the following directory of the IBM Message Broker installation:
For IBM Message Brokers v6.0, go to: <IBM Message Brokers v6.0 Installation Directory>\6.0\classes
For IBM Message Brokers v6.1, go to: <IBM Message Brokers v6.1 Installation Directory>\6.1\classes
j2ee.jar
If IBM Message Broker Toolkit v6.0 or v6.1 is installed on the machine where the MQMonitor agent is installed, you can obtain the j2ee.jar file from the following directory of the IBM Message Broker Toolkit installation:
For IBM Message Broker Toolkit v6.0, go to: <IBM Message Brokers Toolkit v6.0 Installation Directory>\6.0\runtimes\base_v6_stub\lib
For IBM Message Broker Toolkit v6.1, go to: <IBM Message Brokers Toolkit v6.1 Installation Directory>\6.1\runtimes\wsdk\j2ee14
Alternatively, the j2ee.jar file can be found in the /lib directory of the J2EE 1.4 SDK installation. As of 1 January, 2009, J2EE 1.4 SDK can be downloaded from http://java.sun.com/j2ee/1.4/download.html, subject to the accompanying license terms.
18 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Additional JAR files
For WebSphere MQ v6.x, copy the following JAR files from <IBM WebSphere MQ installation directory>\Java\lib to the .\MQMonitor\lib directory:
com.ibm.mq.jar
com.ibm.mqjms.jar
connector.jar
dhbcore.jar
For WebSphere MQ v7.0, copy the following JAR files from <IBM WebSphere MQ installation directory>\Java\lib to the .\MQMonitor\lib directory:
com.ibm.mq.jar
com.ibm.mqjms.jar
connector.jar
dhbcore.jar
com.ibm.mq.commonservices.jar
com.ibm.mq.headers.jar
com.ibm.mq.jmqi.jar
» Note If you are monitoring the Queue Managers of both WebSphere MQ v6.x and WebSphere MQ v7.0, then use the WebSphere MQ v7.0 library files.
Alternatively, to obtain the above files, you can install the MQ client software.
As of 1 January, 2009, the WebSphere MQ v6.0 client was available for download at https://www14.software.ibm.com/webapp/iwm/web/reg/pick.do?source=wsmqc60&lang=en_US, subject to the accompanying license terms.
» Note Install the WebSphere MQ client on the same machine as the MQMonitor agent.
As of 1 January, 2009, the WebSphere MQ v7.0 client was available for download at http://www-01.ibm.com/support/docview.wss?rs=171&uid=swg24019253&loc=en_US&cs=utf-8&lang=en, subject to the accompanying license terms.
Install and configure the MQMonitor agent 19
User Guide
Configure the MQMonitor agent for third-party libraries
To run the MQMonitor agent, you must edit the start script with the location of third-party JAR files on the MQMonitor agent host. For the location of the JAR files, see Obtain third-party libraries on page 17.
To monitor WebSphere MQ v6.0:
Edit the start script, startMQMonitor.bat (Windows) or startMQMonitor.sh (UNIX) to modify the classpath with the actual path of the following files:
com.ibm.mq.jar
connector.jar
PCF JAR file (see PCF JAR file on page 17)
To monitor WebSphere MQ v7.0:
Edit the start script, startMQMonitor.bat (Windows) or startMQMonitor.sh (UNIX) to modify the classpath with the actual path of the following files:
com.ibm.mq.jar
connector.jar
com.ibm.mq.commonservices.jar
com.ibm.mq.headers.jar
com.ibm.mq.jmqi.jar
PCF JAR file (see PCF JAR file on page 17)
com.ibm.mq.pcf.jar obtained from the WebSphere MQ v7.0 installation path <WebSphere MQ 7.0 home>/java/lib.
» Note To monitor the WebSphere MQ v7.0 Queue Managers, you need the above two PCF JAR files. You must provide the path to these two JAR files in the MQMonitor agent start script.
To monitor WebSphere MB:
Edit the start script, startMQMonitor.bat (Windows) or startMQMonitor.sh (UNIX) to modify the classpath with the actual path of the following files:
com.ibm.mq.jar
com.ibm.mqjms.jar
PCF JAR file (see PCF JAR file on page 17)
dhbcore.jar
ConfigManagerProxy.jar
j2ee.jar
connector.jar
20 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Configure the MQMonitor agent properties
You can configure the MQMonitor agent by editing the following files:
MQMonitor.properties
MBMonitor.properties
IntroscopeAgent.profile
MQMonitor.properties file
Locate the MQMonitor.properties file in the \MQMonitor\properties directory, and open the file in a text editor.
The MQMonitor.properties file has the following sections:
Specific MQ Data Section on page 21.
MQ Events Section on page 23.
Special Settings Section on page 25.
Advanced Settings Section on page 26.
MQ Trace related properties Section on page 27.
Filters Section on page 30.
The properties file includes brief descriptions of each of the above sections. For detailed descriptions of the above properties, see the following topics.
Install and configure the MQMonitor agent 21
User Guide
Specific MQ Data Section
In this section, you list the WebSphere MQ configuration instances to monitor WebSphere MQ Queue Managers.
» Important A single Queue Manager instance should be monitored by only one MQMonitor agent.
For each configuration instance, you specify a host name and port. You can also specify channel names, character set, polling delay times, and SSL-related properties.
» Note In references to network resources, DNS names cannot contain underscore characters.
Property Description Value
mq.monitor.list Indicates the comma-separated list of all the WebSphere MQ Queue Manager instances to be monitored.
The ideal format is to list the Queue Manager instances as follows:
<Queue Manager>@<hostname>
Be sure to use the same Queue Manager instance for the rest of the settings in this section.
You can refer to hosts by IP addresses or DNS names.
Example:
If the Queue Manager instance is QM1, then set the property as:
mq.monitor.list=QM1@<hostname>, QM1@<hostname>
Default: none
<Queue Manager>@<Host>.host Indicates the IP address or DNS name (hostname) of the Queue Manager listed in mq.monitor.list
Example:
If the Queue Manager instance is QM1, then set the property as:
QM1@<hostname>.host=localhost
Default: none
<Queue Manager>@<Host>.port Indicates the port numbers of the Queue Manager instances you listed in mq.monitor.list
Example:
QM1@<hostname>.port=5001
Default: 1414
22 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
<Queue Manager>@<Host>.channelname
Indicates the Server Connection Channel used to connect to Queue Manager instance being monitored.
Example:
QM1@<hostname>.channelname=SYSTEM.AUTO.SVRCONN
Default: SYSTEM.AUTO.SVRCONNSYSTEM.DEF.SVRCONN (used if the default channel fails)
<Queue Manager>@<Host>.character.set
Indicates the character set ID used by the Queue Manager.
Example:
QM1@<hostname>.character.set=819
For more information on the <Queue Manager>@<Host>.character.set property, see Support non-English character sets in WebSphere MQ on page 6.
Default: 819
<Queue Manager>@<Host>.delaytime
Indicates the delay time (in seconds) between each query for WebSphere MQ data.
Example:
QM1@<hostname>.delaytime=60
Default: 600 seconds (10 minutes)
<Queue Manager>@<Host>.report.static.freq
Indicates the frequency of metric collection for static metrics.
It is used as the denominator of a fraction, 1/n, where n is the number set for the property.
Example:
QM1@<hostname>.report.static.freq=20
Default: 20
The MQMonitor agent reports the results of only 1 out of every 20 queries.
<Queue Manager>@<Host>.ssl Indicates whether SSL is enabled or disabled for communicating with the Queue Manager instance.
Example:
To enable SSL for communication with Queue Manager instance QM1, set:
QM1@<hostname>.ssl=enable
enable or disable
Default: disable
<Queue Manager>@<Host>.channel.ssl.cipherspec
Indicates the CipherSpec used to communicate with the specific Queue Manager instance over SSL.
This value is used by the MQMonitor agent only when the SSL property is enabled.
Example:
QM1@<hostname>.channel.ssl.cipherspec=NULL_MD5
Default: none
Property Description Value
Install and configure the MQMonitor agent 23
User Guide
For information on encrypting the keystore password, see Run mqPwdEncryptor.bat file on page 60.
» Note Using special characters ":" or "=" in the <Host> of the Queue Manager Instances specified in the mq.monitor.list causes the MQMonitor agent to exit.
For example, QM1@2002:9b23:2d7b:0:20f:1fff:fe7e:59c4 is invalid. The MQMonitor agent exits with the following error message:
Failed to load properties file (MQMonitor.properties). Please make sure that there are no special characters like ":" or "=" in the mq.monitor.list property.
MQ Events Section
Use this section to configure MQMonitor agent to receive WebSphere MQ Event messages. Specify the queue names that receive the MQ Event messages on the WebSphere MQ Queue Manager.
truststore.path Indicates the location of a truststore containing certificates for authentication of the WebSphere MQ Queue Manager (WebSphere MQ server).
Provide either an absolute path or a path relative to the properties directory of the MQMonitor agent.
On Windows, backslashes must be escaped.
Example:
truststore.path=C:\\MQMonitor\\key\\truststore.jks
<path name>
keystore.path Indicates the location of the keystore containing certificates for authentication of the MQMonitor agent.
Set this property if you require client authentication.
Example:
keystore.path=C:\\MQMonitor\\key\\keystore.jks
<path name>
keystore.password Indicates the keystore password.
Example:
keystore.password=<password>
<password>
Property Description Value
24 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
MQ Events include the following:
Event type Events of this type
Queue manager events AuthorityInhibitLocalRemoteStartStop
Channel and bridge events ChannelSSLChannel auto-definition
Performance events Queue depthQueue service interval
» Note This release does not support z/OS-only WebSphere MQ Events.
Enabling MQ Events
To enable WebSphere MQ Events, you must configure WebSphere MQ and the MQMonitor.properties file.
To enable Introscope to display MQ Events:
For each Queue Manager for which you want to view WebSphere MQ Events in Introscope, edit the MQMonitor.properties file and specify the following settings:
Property Description Value
<Queue Manager>@<Host>.performance.event.queue
Indicates the queue name of the Performance Event Queue of a given Queue Manager.
SYSTEM.ADMIN.PERFM.EVENT
<Queue Manager>@<Host>.qmgr.event.queue
Indicates the queue name of the Queue Manager Event Queue of a given Queue Manager.
SYSTEM.ADMIN.QMGR.EVENT
Install and configure the MQMonitor agent 25
User Guide
To configure PowerPack for MQ to view WebSphere MQ Events, see Configure WebSphere MQ to publish events on page 65.
To view MQ Events in the Investigator, see MQ Events on page 79.
Special Settings Section
Use this section to set the limit on the number of metrics to be displayed in the Investigator tree. You can set the display level for the following components of WebSphere MQ:
Queue Managers
Queues
Channels
Channel Initiators (z/OS only)
Page Sets (z/OS only)
Logs (z/OS only)
For each component, the possible values are:
Never—Metrics for the component are neither queried for, nor displayed.
Minimum—a limited set of metrics.
Recommended—a larger set of metrics.
Full—all metrics for this component.
To see which metrics belong to each value set, see Queue Manager metrics on page 146.
<Queue Manager>@<Host>.channel.event.queue
Indicates the queue name of the Channel Event Queue of a given Queue Manager.
SYSTEM.ADMIN.CHANNEL.EVENT
<Queue Manager>@<Host>.event.destructive.get
Indicates whether the event messages are removed from the Event queues after the MQMonitor agent reads them.
Example:
To remove the event messages from the Event queues, set the property as follows:
<Queue Manager>@<hostname>.event.destructive.get=true
true or false
Default:
false
Property Description Value
26 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
To set the display level for a component:
Add a line to the section that corresponds to the component, referring to the component using its name and host name, and then specify the display level.
WebSphere MQ component
Property name
Queue Manager <Queue Manager>@<Host>.monitor.manager
Queue <Queue Manager>@<Host>.monitor.queue
Channel <Queue Manager>@<Host>.monitor.channel
Channel Initiator <Queue Manager>@<Host>.monitor.channelinitiator
Page Sets <Queue Manager>@<Host>.monitor.pagesets
Logs <Queue Manager>@<Host>.monitor.log
For example, to set the display level to Full for queues that belong to Queue Manager QM1, set the property:
QM1@<hostname>.monitor.queue=full
For more details, see the comments in the properties file.
Advanced Settings Section
In this section, you can redefine the recommended metric set.
The default display settings for MQMonitor agent metrics—Minimum, Recommended, and Full—are listed in the tables in Queue Manager metrics on page 146.
The MQMonitor.properties file also lists the members of the Minimum, Recommended, and Full sets for each component.
WebSphere MQ component Property name
Queue Managers recommended.metrics.manager
Queues recommended.metrics.queue
Channels recommended.metrics.channel
Channel Initiator (z/OS only) recommended.metrics.channelinitiator
Page Sets (z/OS only) recommended.metrics.pagesets
Logs (z/OS only) recommended.metrics.log
» Note By defining the recommended set, you have both the minimum set and the metrics that are included in the recommended set.
Install and configure the MQMonitor agent 27
User Guide
To redefine the Recommended display set of metrics:
List the metrics using component names and metric names, following the examples given in the properties file. Separate individual metrics with commas.
For example:
recommended.metrics.queue: Queue Name, Queue Type, Cluster Queue Type
In this example, the recommended list has been redefined with only three members; but you get both minimum set of metrics and the three metrics defined in the recommended list.
MQ Trace related properties Section
The MQ Trace-related properties section lets you configure MQ Trace for cross-process transactions. This section has the following properties:
Property Description Value
trace.dlq.activity.enabled Set the value to true to enable the MQMonitor agent to read trace data from Dead Letter Queue.
Setting the value to false ensures that the MQMonitor agent does not search the Dead Letter Queue for MQ Trace data.
Example:
To enable the MQMonitor agent to read the Dead Letter Queue, set:
trace.dlq.activity.enabled=true
true or false
Default: true
trace.polling.enabled Indicates whether polling is enabled for the MQMonitor agent to read the final destination queue for MQ Trace data.
Example:
To enable polling, set:
trace.polling.enabled=true
true or false
Default: true
28 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
trace.polling.interval Indicates the time period or interval after which the MQMonitor agent checks the final destination queue to see if the message is consumed or not.
Min: 200 milliseconds
Max: 600000 milliseconds (600 seconds/10 minutes)
Default: 1000 milliseconds (1 second).
trace.polling.retry.count Indicates the number of times the MQMonitor agent tries to check the final destination queue for a particular message.
Example:
trace.polling.retry.count=3
Min: 1
Max: 100
Default: 3
trace.dlq.flag.time Indicates the static time that needs to be added to the MQ Trace when messages reach the Dead Letter Queue.
Example:
trace.dlq.flag.time=30
Min: 1 second
Max: 1800 seconds (30 minutes)
Default: 1800 seconds (30 minutes)
handshake.mqagent.id Mandatory. Is the unique identification of the MQMonitor agent for handshaking.
Example:
handshake.mqagent.id=1
Range: 1 to 999999999
handshake.qm.host Indicates the IP address (or DNS name) of the common Queue Manager for handshaking.
Example:
handshake.qm.host=localhost
Default: localhost
handshake.qm.port Indicates the port of the common Queue Manager for handshaking.
Example:
handshake.qm.port=123
Default: 1414
Property Description Value
Install and configure the MQMonitor agent 29
User Guide
For information on cross-process transaction tracing and polling, see Cross-Process Transaction Tracing on page 86.
handshake.qm.channelname Indicates the channel name of the common Queue Manager for handshaking.
Example:
handshake.qm.channelname=SYSTEM.AUTO.SVRCONN
Default: SYSTEM.AUTO.SVRCONN or SYSTEM.DEF.SVRCONN (used if the default channel fails)
handshake.qm.character.set Sets the CCSID character set of the common Queue Manager for handshaking.
Example:
handshake.qm.character.set=819
Default: 819
handshake.qm.ssl Turns the SSL property on or off when the common Queue Manager for handshaking is SSL-enabled.
Example:
To turn off the SSL property of the Queue Manager, set:
handshake.qm.ssl=disable
enable or disable
Default: disable
handshake.qm.channel.ssl.cipherspec Indicates the SSL CipherSpec of the common Queue Manager for handshaking.
Example:
handshake.qm.channel.ssl.cipherspec=NULL_MD5
Default: none
handshake.queue Indicates the queue of the common Queue Manager used for handshaking.
Example:
handshake.queue=CA_WILY_HANDSHAKE
Default: CA_WILY_HANDSHAKE
Property Description Value
» Important The handshake.mqagent.id value in the MQMonitor.properties file must be unique across all MQMonitor agents.
30 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Filters Section
Settings in the filters section offer another layer of metric filtering. For example, you can exclude all system queue metrics in favor of user-defined queue metrics. The tables below explain each setting.
» Important If the trace.dlq.activity.enabled property is set to false, then the activity reports can accummulate in the Dead Letter
Queue. To prevent the activity reports from accummulating in the
Dead Letter Queue, see Set the MCA User ID on page 91.
Property Description Value
<Queue Manager>@<Host>
.filter.exclude.static
Excludes or includes static metrics while monitoring a given Queue Manager.
Set the value to true to exclude static metrics and report only dynamic metrics in the Investigator tree.
Set the value to false to include static metrics, and report both static and dynamic metrics in the Investigator tree.
Example:
To report both static and dynamic metrics of Queue Manager QM1, set the property:
QM1@<hostname>.filter.exclude.static=false
true or false
Default: false
<Queue Manager>@<Host>. queue.filter.exclude.system
Excludes or includes system queues while monitoring the queues of a given Queue Manager.
Set the value to true to exclude system queues in the Investigator tree.
Set the value to false to include system queues in the Investigator tree.
Note: Does not filter the Dead Letter Queue.
Example:
QM1@<hostname>.queue.filter.exclude.system=true
true or false
Default:true
<Queue Manager>@<Host>.queue.filter.exclude.dynamic
Excludes or includes dynamic queues while monitoring the queues of a given Queue Manager.
Set the value to true to exclude dynamic queues in the Investigator tree.
Set the value to false to include dynamic queues in the Investigator tree.
Example:
QM1@<hostname>.queue.filter.exclude.dynamic=true
true or false
Default:true
Install and configure the MQMonitor agent 31
User Guide
The settings in the rows below allow you to exclude metrics based on regular expression parameters.
<Queue Manager>@<Host>. queue.filter.includeonly.regex
While monitoring queues of a given Queue Manager, the Queue Manager displays only those queues with names that match the regular expression.
Example:
QM1@<hostname>.queue.filter.includeonly.regex=.*
Default:.*
(no filtering)
<Queue Manager>@<Host>. channel.filter.includeonly.regex
All channels are included by default unless a list is specified with a regular expression.
Example:
To show only those channels that start with test:
QM1@<hostname>.channel.filter.includeonly.regex=test.*
Default:.*
(no filtering)
<Queue Manager>@<Host>. pagesets.filter.includeonly.regex
Filters page sets in the z/OS Queue Manager by the Page Set ID, and displays them in this form:
Usage|Page Sets|PageSet<PageSet_ID>
Example:
To filter page sets, specify the Page Set ID in the regular expression:
QM1@<hostname>.pagesets.filter.includeonly.regex=.*<PageSet_ID>
Default:.*
(no filtering)
<Queue Manager>@<Host>. log.filter.includeonly.regex
Filters logs in the z/OS Queue Manager, and displays them in this form:
Logs|Log Copy Records|Log<Log Copy Record No>
Example:
To filter the logs, specify the Log Copy Record number in the regular expression:
QM1@<hostname>.log.filter.includeonly.regex=*<Log Copy Record No>
Default:.*
(no filtering)
Property Description Value
32 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Security settings for CMP, JMS, PCF connections
The following sections describe the minimum security settings needed for the MQMonitor agent for CMP, JMS, and PCF connections.
To set the minimum security needed for CMP Connection for the MQMonitor agent:
Apply the allmqi permission on the Queue Manager of the Configuration Manager as follows:
setmqaut -m <QMGR> -t qmgr -p <user>@<domain> +allmqi
» Note The allmqi permissions sets the inq, set, connect, altusr, setid, setall permissions on the CMP Queue Manager:
Apply the put permission on the SYSTEM.BROKER.CONFIG.QUEUE queue of the CMP Queue Manager as follows:
setmqaut -m <QMGR> -t q -n SYSTEM.BROKER.CONFIG.QUEUE -p <user>@<domain> +put
Apply the get permission on the SYSTEM.BROKER.CONFIG.REPLY queue of the CMP Queue Manager as follows:
setmqaut -m <QMGR> -t q -n SYSTEM.BROKER.CONFIG.REPLY -p <user>@<domain> +get
Create an ACL entry on Configuration manager by using following command.
mqsicreateaclentry <ConfMgrName> -u <UserName> -m <machineName>/<DomainName> -x V -p
In the following example, we allow user_x on machine_y to connect to the configuration manager ConfigMgr.
mqsicreateaclentry ConfigMgr -u user_x –m machine_y -x V -p
Command component Explanation
-x V Gives view authority over Configuration manager to user.
-p Adds access to the Configuration Manager Proxy, also known as “all resources” access control entry.
IBM also requires that your remote user ID be a member of mqm and mqbrkrs security groups in the Configuration Manager machine.
» Note After applying the above security settings, either restart the Queue Manager or do a "refresh security" using the runmqsc command and then restart the Configuration Manager.
Install and configure the MQMonitor agent 33
User Guide
To set the minimum security needed for JMS Connection for the MQMonitor agent:
Apply allmqi permission on the JMS Queue Manager.
Apply allmqi permission to all JMS pub sub queues (#10) defined in the JMS Queue Manager.
» Note After applying the above security settings, either restart the Queue Manager or do a "refresh security" using the runmqsc command.
You do not need any security settings for PCF inquiry from the MQMonitor agent as it connects to the Queue Manager with MQADMIN as user. If the connecting Queue Manager deploys any security exits, then the MQMonitor agent fails to connect to the Queue Manager.
If the server connection channel is SSL-enabled, then the MQMonitor agent must be configured for SSL parameters. The MCA user ID must not be set or it should be with a user ID that is a part of the mqm group in WebSphere MQ machine.
MBMonitor.properties file
You can configure the PowerPack for MQ to monitor message brokers managed by one configuration manager, and also obtain the broker and message flow statistics for the message brokers.
Locate the MBMonitor.properties file in the \MQMonitor\properties directory, and open the file in a text editor.
The MBMonitor.properties file has the following sections:
CMP Connection Section (mandatory) on page 34.
MQ Connection Section (optional) on page 34.
Statistics Section on page 35.
Broker (JMS) Connection Section on page 35.
Execution Group Section on page 36.
Node Statistics Section on page 37.
Delay Times Section on page 37.
Monitoring Level Settings Section on page 37.
Advanced Settings Section on page 39.
SSL Configuration Section on page 39.
34 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
CMP Connection Section (mandatory)
The CMP (Configuration Manager Proxy) machine hosts the broker’s configuration manager. After the CMP connection is established, the Investigator tree displays all Brokers, Execution Groups, and Message Flows under the configuration
manager tree. These properties are mandatory if you want to monitor brokers.
Property Description Value
configuration.manager.host
Indicates the CMP machine name or IP address.
Example:
configuration.manager.host=localhost
Default: null
configuration.manager.queue.manager
Indicates the CMP Queue Manager name.
Example:
configuration.manager.queue.manager=WBRK6_DEFAULT_QUEUE_MANAGER
Default: null
configuration.manager.port
Indicates the CMP Queue Manager port.
Example:
configuration.manager.port=2414
Default: null
» Note To turn off MB monitoring, leave the settings in the CMP Connection section empty.
MQ Connection Section (optional)
In a broker domain, the configuration manager and all brokers are associated with WebSphere MQ Queue Managers. As part of Message Broker monitoring, you can monitor the Queue Manager for each broker and configuration manager. This causes the Queue Manager to appear in the Introscope tree twice:
Under the Queue Managers node, as part of WebSphere MQ monitoring
Under the <Broker> that is associated with the Queue Manager
This section has the following property:
Property Description Value
mq.broker.list Is the list of brokers for which you would like to see the associated WebSphere MQ objects.
Example:
mq.broker.list=BROKER1,BROKER2
all, none, <broker list>
Default: all
Install and configure the MQMonitor agent 35
User Guide
The table below lists the different ways you can configure this section.
Value Example Result
all mq.broker.list=all Queue Manager metrics for each broker appears under the broker in the MessageBroker node.
Listing some of the brokers
mq.broker.list=BROKER1,BROKER2
Queue Manager metrics for the listed brokers appear under those brokers in the MessageBroker node.
none mq.broker.list=none No Queue Manager metrics appear under the MessageBroker node.
Statistics Section
In this section, you set the statistics.broker.list property. List the broker names separated by commas. For each of the brokers you list, Introscope displays the Broker statistics and Message Flow statistics.
For example:
statistics.broker.list=BROKER1,BROKER2
By default, the statistics.broker.list property is set to all.
Broker (JMS) Connection Section
In this section, specify the connection properties for the JMS connection.
» Note If the Configuration Manager shares a Queue Manager with a broker, then you do not have to edit this section.
Specify the following connection properties:
Property Description Default
jms.broker.host Indicates the JMS machine name or IP address
null
jms.broker.queue.manager Indicates the JMS Queue Manager name
null
jms.broker.port Indicates the JMS Queue Manager port
null
36 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
When you subscribe to only one Broker using JMS, you should get statistics for all brokers in the collective. This does not work if the configuration of the broker domain is not set up correctly. You may encounter a problem where statistics are reported only for the broker that was specified to be connected to for the subscription. This issue can occur due to improper communication within the collective. You can verify the issue by connecting to a different broker in the collective and see if statistics are reported for this broker. If you see statistics for the other broker, then the problem is not with the collection of the statistics but with the intercommunication between the brokers in the collective.
To address this issue, ensure that the deployment of the pub/sub topology was successful.
To redeploy the topology, issue the following IBM command:
mqsideploy -i <machine> -p <port> -q <queue manager> -l –m
where machine, port and Queue Manager are those of the configuration manager.
For more details, see the IBM documentation. You may have to contact IBM if the problem persists.
Execution Group Section
In this section, list the Execution Groups for which statistics need to be collected. Separate the execution groups by commas in the <broker name>.executiongroup property.
Property Description Value
<broker name>.executiongroup
Indicates the Execution Groups on the broker for which statistics are reported.
Example:
If the broker name is broker1, then se the property as:
broker1.executiongroup=ExecutionGroup1,ExecutionGroup2
all, list of execution groups
» Note Any broker you list in this section must also be listed in the statistics.broker.list in the previous section.
» Note If the statistics.broker.list set to all, then the MQMonitor agent reports all Execution Groups and ignore this section.
Install and configure the MQMonitor agent 37
User Guide
Node Statistics Section
Each message flow has several nodes. To view the statistics for the user-specified node types in the Investigator, set the node.type.list property. Separate the node type names with commas. For example:
node.type.list= JniNode,MQOutputNode
The MBMonitor.properties file contains a list of possible node types.
You can also specify the value as all to show statistics for all nodes in the message flow.
node.type.list=all
By default, the MQMonitor agent reports statistics for the JniNode.
Delay Times Section
In this section, specify a time interval between CMP queries by editing the static.delay.time setting.
See the information for the Delay Times Section in the MBMonitor.properties file for:
minimum and maximum allowable settings
default/recommended setting
examples
Monitoring Level Settings Section
This section lets you control the number of metrics reported by the PowerPack for MQ reports for Message Broker Monitoring. You can specify different monitoring levels for metrics of Message Flow Statistics and Broker Statistics.
You can set the monitoring level for both the statistics to the following values:
Never—No metrics for Message Flow Statistics and Broker statistics are requested from Message Broker.
Minimum—Only few metrics which mainly participate in Typeviews or metrics essential to triage WebSphere MB problems are reported to Introscope.
Recommended—All metrics from minimum level plus few extra metrics are reported to Introscope.
Full—All possible metrics are reported to Introscope.
38 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
» Note By default, the monitoring level is set to Recommended. The metric set for minimum and full monitoring levels are pre-defined, and you cannot change them. The metrics in the Recommended monitoring level can be configured by by specifying a metric list in the recommended.metrics.messageflow.statistics and recommended.metrics.broker.statistics properties of the MBMonitor.properties file.
You can use the <broker name>.messageflow.statistics property to specify the monitoring level for message flow statistics.
For example, for brokers, BROKER1 and BROKER2:
BROKER1.messageflow.statistics = full
BROKER2.messageflow.statistics = minimum
You can use the <broker name>.broker.statistics property to specify the monitoring level for broker statistics that are reported for a broker.
BROKER1.broker.statistics = recommended
BROKER2.broker.statistics = never
If statistics.broker.list property is set to a list of brokers, then all the brokers in the list can set the monitoring level to a value other than the default level.
» Note We recommend setting the monitoring level to the default value.
For example,
statistics.broker.list = BROKER1,BROKER2
BROKER1.broker.statistics = recommended
BROKER2.broker.statistics = never
BROKER1.messageflow.statistics = full
BROKER2.messageflow.statistics = minimum
» Note If you use a broker name that is not included in the statistics.broker.list property, then the broker name is ignored.
Install and configure the MQMonitor agent 39
User Guide
Advanced Settings Section
You can use redefine the recommended monitoring level for the Message Flow
and Broker Statistics using the properties in this section.
Property Description Default
recommended.metrics.messageflow.statistics
Comma-separated list of metrics for Message Flow Statistics, at the recommended monitoring level.
Example:
recommended.metrics.messageflow.statistics=MQ Errors Total, CPU Processing Time
null
recommended.metrics.broker.statistics
Comma-separated list of metrics for Broker Statistics at the recommended monitoring level.
Example:
recommended.metrics.broker.statistics=Bytes Dropped Total, Bytes Queued Total
null
By setting the above two properties, you can only redefine the metric list for the recommended level, and not for other levels of monitoring. The metrics that appear in the Investigator tree are the set of metrics at the minimum level and the redefined metrics at the recommended level. Unlike properties in the Monitoring Level Settings, these properties cannot be set for each broker.
SSL Configuration Section
The MBMonitor agent establishes two types of connections—CMP and JMS. You must set the properties for both the connections to enable SSL connection for CMP and JMS.
Property Description Value
cmp.ssl Indicates whether the SSL connection for CMP is enabled or not.
Example:
To enable the SSL connection for CMP, set the property as:
cmp.ssl=enable
enable or disable
Default: disable
jms.ssl Indicates whether the SSL connection for the JMS broker is enabled or not.
Example:
To enable the SSL connection for the JMS broker, set the property as:
jms.ssl=enable
enable or disable
Default: disable
40 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
» Note Run mqPwdEncryptor.bat only if client authentication is required. The values that you provide for keystore.path and keystore.passsword in the mqPwdEncryptor.bat file for the SSL key repository, get automatically populated in the corresponding properties of the MBMonitor.properties file. For information on the mqPwdEncryptor.bat file, see Run mqPwdEncryptor.bat file on page 60.
This completes your editing of the MBMonitor.properties file.
cmp.connection.ssl.cipherspec
Indicates the CipherSpec for the CMP SSL connection.
Example:
To specify the CipherSpec for the CMP Queue Manager, set the property as:
jms.connection.ssl.cipherspec=NULL_MD5
SYSYTEM.BRK.CONFIG (for CMP)SYSTEM.DEF.SVRCONN (for JMS)
truststore.path Indicates the truststore path of the SSL key repository, used for both CMP and JMS SSL connections.
Provide either an absolute path or a path relative to the properties directory of the MQMonitor agent.
On Windows, backslashes must be escaped.
Example:
truststore.path=C:\\MQMonitor\\key\\truststore.jks
<path name>
keystore.path Indicates the keystore path of the SSL key repository, used for both CMP and JMS SSL connections.
Provide either an absolute path or a path relative to the properties directory of the MQMonitor agent.
On Windows, backslashes must be escaped.
Example:
keystore.path=C:\\MQMonitor\\key\\keyststore.jks
<path name>
keystore.password Indicates the keystore password of the SSL key repository, used for both CMP and JMS SSL connections.
Provide either an absolute path or a path relative to the properties directory of the MQMonitor agent.
On Windows, backslashes must be escaped.
Example:
keystore.password=<password>
<password>
Property Description Value
Install and configure the MQMonitor agent 41
User Guide
To obtain Message Broker metrics, you must create JMS queues, as described in the following section.
To create JMS queues that use the JMS (Java Messenging Service) protocol:
1 Identify the Queue Manager where you have to define JMS queues.
If the Configuration Manager shares its Queue Manager with one of its brokers, this will be the Configuration Manager’s Queue Manager.
If a Queue Manager is not shared between the Configuration Manager and its broker, you can create the JMS queue on any of the brokers in a publish/subscribe collective.
2 Find the file MBMonitorJMSQueues.mqsc in the \MQMonitor\properties directory where you uncompressed the MQMonitor agent archive. The file (viewable in a text editor) contains a series of MQSC commands.
3 Issue the following command on your Message Broker host. This runs all the commands in the MBMonitorJMSQueues.mqsc file.
runmqsc queueMgr_name < MBMonitorJMSQueues.mqsc
where queueMgr_name is the name of the Queue Manager you identified in an earlier step.
IntroscopeAgent.profile file
Specify the connection properties for the Introscope Enterprise Manager (EM) to which you want to send the metrics reported by the MQMonitor agent. You can also specify the properties required for metric aging in the IntroscopeAgent.profile file.
To specify the EM:
1 Open the IntroscopeAgent.profile from the MQMonitor\properties directory.
2 Find the section Enterprise Manager Locations and Names.
3 Specify the following connection properties:
Property Description Default
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT
Indicates the EM host name or IP address.
localhost
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT
Indicates the EM port. 5001
4 Save and close the file.
42 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
To add properties for Metric Aging:
1 Open the IntroscopeAgent.profile file and set the values of the properties as shown in the following table:
Property Description Default
introscope.agent.metricAging.turnOn Enables or disables the MQMonitor agent’s metric aging.
true
introscope.agent.metricAging.heartbeatInterval
Sets the time interval when metrics are checked for removal (in seconds).
12600
introscope.agent.metricAging.dataChunk Sets the number of metrics that are checked during each interval. If the value is 500, then each of the 500 metrics is checked to see if it is a candidate for removal.
500
introscope.agent.metricAging.numberTimeslices
Sets the number of intervals to check for the metric without any new data before making it a candidate for removal.
100
introscope.agent.metricAging.metricExclude.ignore.0
Lists the metrics that must not be removed. Add the metric name or metric filter to the list.
Example:
To prevent Local_Queue Metrics from graying out, set the property as follows: introscope.agent.metricAging.metricExclude.ignore.0= *Local_Queue*
Threads*
Ensure that you set the proper value for the properties in the IntroscopeAgent.profile file. The heartbeatInterval depends upon the maximum polling interval specified using the delaytime property in the MQMonitor.properties file and the static.delaytime property in the MBMonitor.properties file. We recommend that you set it to at least 4 times the maximum default interval. In case of aggregated metrics, the aggregated metrics gray out if all the linked metrics gray out. For example, if the aggregated metric AG1 consists of agent metrics a1, a2, and a3, and data is available for a1 only, then AG1 does not gray out.
Configure WebSphere MQ for MQ Trace 43
User Guide
» Note The MQMonitor agent must push any metric data (if available) related to WebSphere MQ or WebSphere MB within the time specified in the heartbeatInterval property. So, the delay time must always be less than the heartbeatInterval. The default value for introscope.agent.metricAging.heartbeatInterval property is 12600 seconds. You can set the property to its default value or higher. If you set the property to a value lesser than 12600 seconds, then the system uses the default value only.
2 Save and close the file.
This completes the configuration tasks for the MQMonitor agent.
» Note For more information on the metric aging properties, see the Introscope Java Agent guide.
Run the MQMonitor agent
To start the MQMonitor agent on Windows or UNIX:
1 Make sure your JAVA_HOME variable is set in system properties.
2 In the \MQMonitor directory, execute the startMQMonitor.bat (Windows) or startMQMonitor.sh (UNIX) file.
The WebSphere MQ and/or WebSphere MB tree appears in the Introscope Workstation tree under the node WebSphere MQ and Message Broker Agent. For information on reading and understanding these metrics, see chapter 3, Viewing Data Using PowerPack for MQ on page 67.
To stop the MQMonitor agent on Windows or UNIX:
In Windows, close the command prompt window from where you executed the startMQMonitor.bat file. In UNIX, execute the stopMQMonitor.sh file from the \MQMonitor directory.
When you stop the MQMonitor agent, all the MQMonitor agent processes also stop.
Configure WebSphere MQ for MQ TraceAfter you install and configure the MQMonitor agent, you can use PowerPack for MQ to perform cross-process transaction tracing to obtain and analyze WebSphere MQ performance information. For information about how to configure WebSphere MQ to perform cross-process transaction tracing, see Configure the WebSphere MQ System for trace on page 87.
44 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Upgrade the MQMonitor agentThe following two sections describe how you can upgrade the earlier versions of the MQMonitor agent.
To upgrade the EPAMQMonitor agent in PowerPack for MQ v4.1.x:
1 Copy the EPAMQMonitor.properties file of PowerPack for MQ v4.1.x to the MQMonitor\properties directory of PowerPack for MQ v8.x.
2 Start the MQMonitor agent.
This converts and upgrades the PowerPack for MQ v4.1.x properties file to PowerPack for MQ v8.x properties file. The PowerPack for MQ v4.1.x properties file is backed up under the MQMonitor\properties\backup directory.
To upgrade the EM component for PowerPack for MQ v4.1.x:
1 Back up the following files from the <Introscope Home>/config/modules directory to any other location:
PPWebsphereMQ_MQSeries_ManagementModule.jar
PPWebsphereMQ_JavaConnectors_ManagementModule.jar
PPWebsphereMQ_EpaMQMonitor_ManagementModule.jar
2 Install the current version of PowerPack for MQ EM component.
To upgrade the EPAMQMonitor agent in PowerPack for MQ v5.x:
1 Copy the MQMonitor.properties and MBMonitor.properties files of PowerPack for MQ v5.x to the MQMonitor\properties directory of PowerPack for MQ v8.x.
2 Start the MQMonitor agent.
This converts and upgrades the PowerPack for MQ v5.x properties file to PowerPack for MQ version v8.x properties file. The PowerPack for MQ v5.x properties file is backed up under the MQMonitor\properties\backup directory.
To upgrade the EM component for PowerPack for MQ v5.x:
1 Back up the following files from the <Introscope Home>/config/modules directory to any other location:
WMBManagementModule.jar
WMQJavaConnectorsManagementModule.jar
WMQManagementModule.jar
WMQ_MB_JavaConnectorManagementModule.jar
2 Install the current version of PowerPack for MQ EM component.
» Note If the <Host> of the Queue Manager instances specified in the mq.monitor.list has special characters like ":" or "=", then it is replaced with "_" for all the instances.
If the <Host> was QM1@2002:9b23:2d7b:0:20f:1fff:fe7e:59c4 before the upgrade, then, after the upgrade, it would change to: QM1@2002_9b23_2d7b_0_20f_1fff_fe7e_59c4
Upgrade the MQMonitor agent 45
User Guide
46 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
(Optional) Install MQMonitor agent as a Windows Service
To run the MQMonitor agent on a Windows machine as a Windows Service, go to the MQMonitor\Window Service directory. The directory structure is as follows:
Directory Files
\Windows Service RegisterMQService.batDeregisterMQService.bat
\Windows Service\jsw-3.2.3\bin InstallTestWrapper-NT.batPauseTestWrapper-NT.batResumeTestWrapper-NT.batStartTestWrapper-NT.batStopTestWrapper-NT.batTestWrapper.batTestWrapperNoWrapper.batUninstallTestWrapper-NT.batwrapper.exe
\Windows Service\jsw-3.2.3\conf wrapper.conf
\Windows Service\jsw-3.2.3\legal\jsw-3.2.3
license.txt
\Windows Service\jsw-3.2.3\lib wrapper.dllwrapper-3.2.3.jarwrappertest-3.2.3.jar
To register the MQMonitor agent as a Windows Service:
1 Edit the wrapper.conf file to suit any local requirements, such as the <Path for JAVA>.
2 Run the RegisterMQService.bat file.
The MQMonitor agent is now registered as a Windows Service.
To monitor WebSphere MB when MQMonitor agent is registered as a Windows Service:
1 Open the Windows Service properties of the MQMonitor agent.
2 In the Log on tab, change the Log on as credentials to that of an authorized user of WebSphere MB.
3 Apply the changes and start the service.
The MQMonitor agent is now configured to monitor all WebSphere MB instances.
Install and configure MQ Java Connectors 47
User Guide
To run the MQMonitor agent as a Windows Service:
1 Click Start > Run.
The Run dialog box appears.
2 Type Services.msc in the Open text box and click OK.
A list of all Windows services appears.
3 Right-click MQ Monitor and click Start.
The MQMonitor agent starts reporting metrics for the configured WebSphere MQ and WebSphere MB instances.
To deregister the MQMonitor agent as a Windows Service:
Double-click the DeregisterMQService.bat file.
Install and configure MQ Java ConnectorsMQ Java Connectors monitor various Connector, JMS classes, and methods that communicate with WebSphere MQ.
To install and configure MQ Java Connectors:
1 Extract the MQ Java Connectors files on page 47.
2 Configure MQ Java Connectors on page 49.
3 Configure ErrorDetector on page 53.
4 Configure JCA Connection Pool on page 55.
The following sections describe these steps in detail.
Extract the MQ Java Connectors files
The names of the MQ Java Connectors archive files differ based on the platform. The archive file names for the Windows, UNIX, and z/OS platforms are listed in the following table:
Operating system Archive file name
Windows PowerPackForWebSphereMQv8.1Agent.windows.zip
UNIX PowerPackForWebSphereMQv8.1Agent.unix.tar
z/OS PowerPackForWebSphereMQv8.1Agent.zos.tar
48 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Based on the platform, extract the appropriate MQ Java Connectors archive to the /wily directory on your application server. The contents of the archive are as follows:
/ext
MQNameFormatter.jar
InstallAgent.txt
MQAppSupport.jar
PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbd
PowerPackForWebSphereMQ_v8.1_ErrorDetector.pbd
PowerPackForWebSphereMQ_JavaConnectors_old.pbd
PowerPackForWebSphereMQ_v8.1_InstanceCounts.pbd
PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl
MQAgent.properties
(Optional) Configure application server when Java 2 security is enabled
If Java 2 security is enabled on the application server, then you need to update the server.policy and java.policy files.
For example, to configure WebSphere Application Server v6.x, edit the server.policy and java.policy files as follows:
Add the following lines in the server.policy file located at <WebSphere home>\profiles\<profile name>\properties:
// WebSphere optional runtime classesgrant codeBase "file:${was.install.root}/-" {permission java.lang.RuntimePermission
"accessDeclaredMembers", "read";permission java.lang.RuntimePermission "getClassLoader",
"read";permission java.lang.RuntimePermission "modifyThread", "read";permission java.lang.RuntimePermission "modifyThreadGroup",
"read";permission java.lang.reflect.ReflectPermission"suppressAccessChecks", "read";permission java.util.PropertyPermission"java.security.policy", "read";};
Install and configure MQ Java Connectors 49
User Guide
Add the following lines in the java.policy file located at <WebSphere home>\java\jre\lib\security):
grant {permission java.io.FilePermission "C:/IBM/WebSphere/wily/
MQAgent.properties", "read";};
Configure MQ Java Connectors
The following instructions cover the Windows, UNIX, and z/OS platforms.
1 Configure the Introscope agent on the application server.
» Note The Introscope agent is a part of the Introscope product and must be obtained from the Introscope software download site.
2 Extract the MQ Java Connectors archive to the /wily directory of the Introscope agent.
3 In the /wily directory of the Introscope agent:
a Open the IntroscopeAgent.profile file in a text editor.
b Find the introscope.autoprobe.directivesFile property and add the PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl file to the list of files in that property.
PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl lists the PBD files to be enabled.
c Edit the PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl file to enable any PBD files. For information on enabling PBD files, see To enable or disable PBD files: on page 54.
» Important Do not remove any ProbeBuilder list files (.pbl) existing in the property.
» Note The PowerPackForWebSphereMQ_v8.1_InstanceCounts.pbd file provides the number of instances of MQ Java Connector classes. PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbd adds support for PowerPack for MQ v8.x metrics and PowerPackForWebSphereMQ_JavaConnectors_old.pbd adds support for PowerPack for MQ v4.1.x metrics. You must note that the PowerPackForWebSphereMQ_JavaConnectors_old.pbd file is specific to PowerPack for MQ v4.1.x, and you cannot enable both the PBD files at the same time as the tree structure in the Investigator varies from PowerPack for MQ v4.1.x to v8.x.
4 Save the IntroscopeAgent.profile file.
5 Restart the application server.
50 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Sharing the wily folder across multiple MQ Java Connector agents
If you want to use the same \wily folder across multiple MQ Java Connector agents, then make multiple copies of the MQAgent.properties file with names for the agents, and pass the -Dcom.wily.mqpp.mqagentProfile=<path to the wily folder>\MQAgent.properties along with other JVM arguments at the Java command for running the agents.
Example:
For Java versions 1.5 and above:
–javaagent:<path to the wily folder>\Agent.jar -Dcom.wily.introscope.agentProfile=<path to the wily folder>\IntroscopeAgent.profile -Dcom.wily.mqpp.mqagentProfile=<path to the wily folder>\MQAgent1.properties
For versions prior to Java 1.5:
-Xbootclasspath/p:<path to the wily folder>\connectors\AutoProbeConnector.jar;<path to the wily folder>\Agent.jar -Dcom.wily.mqpp.mqagentProfile=<path to the wily folder>\MQAgent1.properties -Dcom.ibm.websphere.classloader.plugin=com.wily.introscope.api.websphere.WASAutoProbe -Dcom.wily.introscope.agentProfile=<path to the wily folder>\IntroscopeAgent.profile
MQAgent.properties file
The MQAgent.properties file lets you configure handshake between the MQ Java Connector agents and the MQMonitor agents for cross-process transactions.
Install and configure MQ Java Connectors 51
User Guide
The following table describes the properties of the MQAgent.properties file:
Property Description Value
mqmonitor.mqagent.id.list Lists the value of the handshake.mqagent.id property of all the MQMonitor agents that are involved in a cross-process transactions trace.
Separate the names by comma.
Set this property to prevent unnecessary overload on WebSphere MQ, if cross-process transaction is enabled.
Example:
mqmonitor.mqagent.id.list=1, 2
Default: none
If this value is null, then the handshaking process to check the availability of running MQMonitor agents does not occur, and the WebSphere MQ transaction trace is set to on.
handshake.mqagent.id Mandatory. Is the unique identification of the agent.
Set this property to prevent unnecessary overload on WebSphere MQ if mqmonitor.mqagent.id.list is not blank.
Example:
handshake.mqagent.id=1
Range: 1 to 999999999
Default: none
If the value is null, then the handshake process does not start.
handshake.qm.host Indicates the IP address (or DNS name) of the common Queue Manager.
Example:
handshake.qm.host=localhost
Default: localhost
handshake.qm.port Indicates the port of the common Queue Manager.
Example:
handshake.qm.port=123
Default: 1414
handshake.qm.channelname Indicates the channel name of the common Queue Manager to be used for connections.
Example:
handshake.qm.channelname=SYSTEM.AUTO.SVRCONN
Default: SYSTEM.AUTO.SVRCONN
SYSTEM.DEF.SVRCONN (used if the default channel fails)
handshake.qm.character.set
Sets the CCSID character set of the common Queue Manager.
Example:
handshake.qm.character.set=819
Default: 819
52 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
handshake.qm.ssl Turns the SSL property on or off when the common Queue Manager is SSL-enabled.
Example:
To turn off the SSL property of the Queue Manager, set:
handshake.qm.ssl=disable
enable or disable
Default: disable
handshake.qm.channel.ssl.cipherspec
Indicates the SSL CipherSpec of the common Queue Manager.
XXXXX_XXXXX
Default: none
handshake.queue Indicates the queue used for handshaking among all WebSphere MQ agents.
Default: CA_WILY_HANDSHAKE
truststore.path Indicates the location of a truststore containing certificates for authentication of WebSphere MQ server.
Provide either an absolute path or a path relative to the properties directory of MQMonitor agent.
On Windows, backslashes must be escaped.
Example:
truststore.path=C:\\MQMonitor\\key\\truststore.jks
<path name>
keystore.path Optional. Is the location of the keystore.
Set this property if you require client authentication.
Provide either an absolute path or a path relative to the properties directory of MQMonitor agent.
On Windows, backslashes must be escaped.
Example:
keystore.path=C:\\MQMonitor\\key\\keystore.jks
<path name>
Property Description Value
Install and configure MQ Java Connectors 53
User Guide
» Important The handshake.mqagent.id value in the MQAgent.properties file must be unique across all MQ Java Connectors. The handshake properties must be the same in both the MQAgent.properties and MQMonitor.properties files of all agents in PowerPack for MQ.
Configure ErrorDetector
You can use Introscope’s ErrorDetector feature to read WebSphere MQ errors in the Introscope Investigator.
keystore.password Optional. Is the keystore password.
Example:
keystore.password=<password>
<password>
mqtracing.exclude.queues.regex
Optional. Indicates one or more queues of a particular Queue Manager that are filtered from transaction tracing.
Note: This property filters the first queue where WebSphere MQ Put or JMS Send operations occur along with the subsequent correlated traces. This also filters the traces for the WebSphere MQ Get or JMS Receive operations.
Example:
To filter all the queues containing the word "SYSTEM" of the Queue Manager QM1 from transaction tracing, set the property:
QM1.mqtracing.exclude.queues.regex=.*SYSTEM.*
To filter all the queues of the Queue Manager QM1 from transaction tracing, set the property:
QM1.mqtracing.exclude.queues.regex=.*
To filter all the queues except queues TRACE.QUEUE1 and TRACE.QUEUE2 of the Queue Manager QM1 from transaction tracing, set the property:
QM1.mqtracing.exclude.queues.regex=(?!((.*TRACE.QUEUE1.*)|(.*TRACE.QUEUE2.*))).*
Default: none (no filtering)
Property Description Value
54 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
ErrorDetector allows application support personnel to detect and diagnose errors that prevent you from completing web transactions. Enabling the ErrorDetector allows Introscope to show application errors on the Application Server that uses WebSphere MQ as the message queueing middleware.
To enable ErrorDetector, you must configure the Introscope Enterprise Manager host and the application server where MQ Java Connectors is installed.
On the Introscope EM host, the ErrorDetector depends on a JAR file, com.wily.introscope.errordetector_8.0.0.jar, that is part of the Introscope ErrorDetector software.
To enable ErrorDetector on the Introscope EM:
1 Extract the com.wily.introscope.errordetector_8.0.0.jar file from the ErrorDetector package and copy it to the <Introscope Home>/product/enterprisemanager/plugins directory.
2 Restart the EM.
To enable or disable PBD files:
1 Open the file PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl in a text editor.
2 Comment or uncomment one or more PBD files.
For example:
######################## Directives Files# ================# One directives file name per line. Relative names# are resolved against the location of this file.
PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbdPowerPackForWebSphereMQ_v8.1_ErrorDetector.pbd#PowerPackForWebSphereMQ_v8.1_InstanceCounts.pbd#PowerPackForWebSphereMQ_JavaConnectors_old.pbd
Install and configure MQ Java Connectors 55
User Guide
Configure JCA Connection Pool
The MQ Java Connectors files include the MQAppSupport.jar file, that enables WebSphere Application Server to report WebSphere MQ Connection Pool metrics.
» Note Applicable only for the WebSphere Application Server.
To install and configure the JCA Connection Pool in the WebSphere Application Server:
1 Check that the MQAppSupport.jar file has been extracted to the /wily directory of the application server host.
2 In WebSphere, create and configure a new service that reports connection pool metrics:
a Open the WebSphere Admin Console.
» Note These steps are based on WebSphere v6.1. For other versions of WebSphere, the steps may be slightly different.
b In the left pane, expand the Servers node.
c Under the Servers node, select Application Servers.
d In the right pane, select the server where you are creating a service.
e In the Admin Console menu, select Administration > Custom Services.
f Create a new service.
g Ensure Enable service at server startup is checked.
h Enter the following information under General Properties.
classname:
com.wily.powerpack.websphereMQ.agent.JCAConnectionPool.IntroscopeMQCustomService
DisplayName: Enter any string. Introscope uses this value for the label of the service.
ClassPath: Enter the full file system path to the MQAppSupport.jar file in the /wily directory of the application server host. For example:
C:\Program Files\WebSphere\AppServer\Wily\MQAppSupport.jar
i Click OK.
56 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
3 Enable PMI settings in the WebSphere Administrative Console:
a In the left pane, under Monitoring and Tuning, select Performance Monitoring Infrastructure (PMI).
b In the right pane, click on the server for which you are configuring the PMI.
c Click the Configuration tab.
d Check the Enable Performance Monitoring Infrastructure (PMI) box.
e Under Currently monitored statistic set, select Custom.
f Under Custom, click JCA Connection Pools.
g In the right pane, select the following attributes to be monitored:
PercentUsed
WaitTime (in WebSphere Application Server v5.1.1, this attribute is called AvgWaitTime)
PoolSize
WaitingThreadCount (in WebSphere Application Server v5.1.1, this attribute is called ConcurrentWaiters)
PercentMaxed
You can view the selected metrics in Introscope. See JCA node metrics on page 198.
h With the attributes selected, click Enable.
i Click OK.
4 Restart the WebSphere Application Server.
Install Management Modules and extensionsThe Management Modules contain pre-configured extensions for the Introscope Investigator and Console:
Dashboards, alerts, and other graphical displays to show WebSphere MQ and WebSphere MB metrics in graphical form in the Introscope Console and Investigator tools.
Calculators and Enterprise Manager (EM) extensions that aggregate metric data from more than one WebSphere MQ or WebSphere MB component.
» Note These instructions cover the Windows, UNIX, and z/OS platforms.
Additional Information 57
User Guide
To install the Management Modules:
1 Extract the Management Module archive to your Introscope EM home directory.
2 Copy the following Management Module JAR files to the <Introscope Home>/config/modules directory in the Introscope Enterprise Manager’s installation directory.
MQPowerPackHealth.jar
WebSphere_MQ_Client_And_Server.jar
WMBManagementModule.jar
3 Restart the Introscope Enterprise Manager.
For information on the Management Modules, see Management Modules on page 109.
Additional InformationThis section provides additional information such as upgrading PowerPack for MQ, configuring SSL, configuring WebSphere MB, and creating JMS queues. This section includes the following topics:
Configure SSL on page 58.
Configure WebSphere MB on page 64.
Configure WebSphere MQ to publish events on page 65.
Turn on Queue Monitoring on page 66.
58 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Configure SSL
Before you begin the SSL configuration, you must note the following:
The Server mentioned in this procedure is the IBM MQ Queue Manager and the Client is PowerPack for MQ.
The procedure assumes the usage of IBM Key Management Utility (IKEYMAN) tool for setting up the SSL repositories and creation or addition of certificates. See Generate Personal Certificates on page 63 for more information on Certificates.
The SSL Key repository is termed as keystore and truststore on the Client depending on its usage.
How to set up Client-Server communication over SSL
The process for setting up client-server communication over SSL is as follows:
Set up SSL key repository and create self-signed certificate on the Server.
Set up truststore on the Client and add the Server’s self-signed certificate to it.
Set up keystore on the Client (if client authentication is needed by the Server) and create self-signed certificate for the Client. The Client requires the keystore password during SSL communication with the Server.
Extract the Client’s certificate and add it to the Server’s SSL Key Repository.
Select an SSL CipherSpec for the Server Connection Channel on the Server.
Configure the Client using the SSL related properties in the MQMonitor.properties or MBMonitor.properties files.
Start the Client.
This initiates communication with Server CipherSpec. The Server and Client start exchanging information on the Server Connection channel over SSL.
To establish the SSL communication between the client and server, you must configure both the client and the server. The following sections describe the procedures for configuring the client and server.
Configure the Server
To configure the server, perform the following steps:
Set up SSL key repository with the Key database type as “CMS”.
For example:
On Windows, the Queue Managers SSL key repository is located at <WebSphere MQ home>\qmgrs\<Queue Manager Name>\ssl and the SSL key repository name is key.kdb.
Additional Information 59
User Guide
Generate the certificate. You can either generate a self-signed certificate using the IKEYMAN tool or any personal certificate, and add it to the SSL key repository. See Generate Personal Certificates on page 63 for more information on Certificates.
Add the Client certificate (if client authentication is needed] to the server’s SSL key repository.
» Note Client Certificate is got from the 2nd step in the Configuring the Client > Setup keystore section.
Set the SSL CipherSpec on the server connection channel. Be sure to note this value as you must provide this information in the MQMonitor.properties and MBMonitor.properties files.
Configure the Client
To configure the client, perform the following steps:
Step 1 Set up truststore.
Step 2 Set up keystore.
Step 3 Run mqPwdEncryptor.bat file.
Step 4 Configure the MQMonitor.properties file.
Step 5 Configure the MBMonitor.properties file.
Set up truststore
1 Set up truststore with the key database type as “JKS”.
For example:
You can name the truststore as truststore with the extension .jks.
2 Add the Server certificate to the truststore. Server Certificate is got from the 2nd step in the Configuring the Server section.
Set up keystore
This section is needed only when the Server asks for Client Authentication.
1 Set up keystore with the Key database type as JKS. Make a note of the password needed to open the keystore.
For example, you can name the keystore as keystore with the extension .jks.
2 Generate the certificate - either self-signed certificate using IKEYMAN tool or any personal certificate and add it to the keystore. See Generate Personal Certificates on page 63 for more information on Certificates.
60 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Run mqPwdEncryptor.bat file
Run the mqPwdEncryptor.bat file if client authentication is required by the server. The purpose of this command line utility is to set keystore location and keystore password for the Client (PowerPack for MQ) to communicate over SSL. Perform the following steps:
1 Double-click mqPwdEncryptor.bat.
The utility opens and prompts you for the keystore location.
2 Enter the path for the keystore in the command line.
» Note The utility provides a maximum of three attempts to enter the correct path, and then quits.
3 Enter the keystore password.
The utility prompts for the properties file (either MQMonitor.properties or MBMonitor.properties) where the keystore location and password should be updated.
4 Enter the absolute path for the properties file (either MQMonitor.properties or MBMonitor.properties) that you want to update, and press Enter.
The utility encrypts the keystore password and adds it to the properties file provided in the previous step.
When you run the MQMonitor agent, the encrypted password is decrypted and used by the MQMonitor agent.
» Important Always try to make use of the same truststore and keystore references for a given MQMonitor agent. In other words, if you configure both the MQMonitor.properties and MBMonitor.properties files, then the references to truststore and keystore should be the same.
Configure the MQMonitor.properties file
The MQMonitor agent uses SYSTEM.AUTO.SVRCONN as the default server connection channel to connect to the WebSphere MQ Queue Manager. If the connection is unsuccessful using the SYSTEM.AUTO.SVRCONN channel, then the MQMonitor agent uses SYSTEM.DEF.SVRCONN as the alternative channel.
For enabling SSL, you must edit the following property:
<Queue Manager>@<Host>.ssl
If a Queue Manager is SSL-enabled, then indicate the same by enabling the property. For example, QM1@hostname.ssl=enable
Additional Information 61
User Guide
By default, the following property is disabled:
<Queue Manager>@<Host>.channel.ssl.cipherspec
The MQMonitor agent verifies this value if the SSL property is enabled for the monitored Queue Manager. This value is the CipherSpec with which the server connection channel on the particular Queue Manager has been configured.
For example:
QM1@hostname.channel.ssl.cipherspec= NULL_MD5 where NULL_MD5 is the name of the CipherSpec that is used and QM1 is the Queue Manager.
Certificates of all the Queue Managers needs to be placed in the truststore. Edit the truststore.path property to point the MQMonitor agent to the truststore location :
» Note On UNIX, use the forward slash in the path as separator. You can use the same on Windows also. However, if the backward slash is used on Windows, then it should be escaped.
For example,
truststore.path = C:\\MQMonitor\\keys\\truststore.jks is correct.
truststore.path = C:/MQMonitor/keys/truststore.jks is correct.
keystore.path and keystore.password
The personal certificate of client is placed in keystore. We need to provide keystore location and also its password in MQMonitor.properties file as follows:
For example:
keystore.path = C:/MQMonitor/keys/keystore.jks
keystore.password = <encrypted password>
» Note You need not edit these properties directly in the MQMonitor.properties file. Instead, you must run the mqPwdEncryptor.bat file. The mqPwdEncryptor.bat utility updates the keystore.path property with the path (with the forward slash as separator) provided by you.
62 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Configure the MBMonitor.properties file
The MBMonitor establishes two types of connections—CMP and JMS.
The default system server connection channel used by the MQMonitor agent to establish connection with Configuration Manager’s Queue Manager is SYSYTEM.BRK.CONFIG (CMP). For the JMS Broker’s Queue Manager, the default system server connection channel is SYSTEM.DEF.SVRCONN (JMS).
» Note In MBMonitor.properties file, you must mention the configuration manager’s Queue Manager and the JMS broker’s Queue Manager information to establish the CMP or JMS connections.
You must set the following properties for both the connections to enable SSL connection for CMP and JMS.
cmp.ssl = enable
jms.ssl = enable
By default, both the properties are disabled.
cmp.connection.ssl.cipherspec
MQMonitor agent verifies this value if the SSL property is enabled for the Configuration Manager’s Queue Manager. This value is the CipherSpec with which the server connection channel on the particular the Configuration Manager’s Queue Manager has been configured.
For example,
cmp.connection.ssl.cipherspec= NULL_MD5 where NULL_MD5 is the CipherSpec that is used.
jms.connection.ssl.cipherspec
The MQMonitor agent verifies this value when the SSL property is enabled for the JMS Broker’s Queue Manager. This value is the CipherSpec with which the sever connection channel on the particular the JMS Broker’s Queue Manager has been configured.
For example,
jms.connection.ssl.cipherspec= NULL_MD5 where NULL_MD5 is the CipherSpec that is used.
truststore.path
Additional Information 63
User Guide
You must place the certificates of the Configuration Manager’s Queue Manager and JMS Broker’s Queue Manager in the truststore. Edit the following property to point MQMonitor agent to truststore location :
» Note On UNIX, use the forward slash in the path as separator. You can use the same on Windows also. However, if the backward slash is used on Windows, then it should be escaped.
For example:
truststore.path = C:\\MQMonitor\\keys\\truststore.jks is correct
truststore.path = C:/MQMonitor/keys/truststore.jks is correct
keystore.path and keystore.password
The personal certificate of client is placed in keystore. You must provide the keystore location and also its password in the MBMonitor.properties file as follows:
For example:
keystore.path = C:/MQMonitor/keys/keystore.jks
keystore.password = < Encrypted password>
» Note You need not edit these properties directly in the MBMonitor.properties file. Instead, you must run the mqPwdEncryptor.bat file. The mqPwdEncryptor.bat utility updates the keystore.path with the user provided location having forward slash as the separator.
This completes your editing of the MBMonitor.properties file.
Generate Personal Certificates
For generating self-signed certificates and extracting it, WebSphere MQ client installation is a prerequisite.
You can obtain the personal certificates for Queue Manager in the following ways:
Create self-signed certificates.
Have an in-house certification authority.
Request a certificate from a certification authority.
64 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Configure WebSphere MB
To configure WebSphere MB:
Use the Message Broker Command Console on the Windows platform
Use the command line on the UNIX platform.
To run the MQMonitor agent for monitoring WebSphere MB, the user must be part of mqm and mqbrkrs. Else, the MQMonitor agent throws an error such as the following:
[FATAL][com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] Configuration Manager broken connection!
12/11/07 03:01:33 PM GMT+05:30 [FATAL][com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain]
Start the Configuration Manager and run the MQMonitor agent again.
If you want to see the Queue Managers used by the Configuration Manager and it’s Brokers under the WebSphere Message Broker node, configure the corresponding Queue Manager details in the MQMonitor.properties file.
Step 1 Enable MessageFlow accounting statistics for message flow performance metrics by executing an MQSI command on the Message Broker host. See the WebSphere MB documentation for the syntax of this command.
Examples:
To enable statistics for Message flows on the AirlineExecutionGroup on a broker named foo_broker:
mqsichangeflowstats foo_broker -s -e AirlineExecutionGroup -j -c active -o xml -n basic
To verify the statistics settings created by the above command:
mqsireportflowstats foo_broker -s -e AirlineExecutionGroup -j
» Note The above commands use the Windows syntax. For information on the z/OS syntax, see the IBM documentation.
Step 2 Enable Publish/subscribe statistics reports for broker performance metrics.
Publish/subscribe statistics provide information about the performance of brokers, and the throughput between the broker and clients that are connected to the broker.
mqsichangeproperties foo_broker -e AirlineExecutionGroup -o DynamicSubscriptionEngine -n statsInterval -v 30000
Additional Information 65
User Guide
To verify the statistics settings created by the above command:
mqsireportproperties foo_broker -e default -o AirlineExecutionGroup –n statsInterval
For information on how to perform these steps, see the WebSphere MB documentation.
Configure WebSphere MQ to publish events
To view MQ Events in Introscope, perform the following steps:
Step 1 Edit the MQMonitor.properties file to identify the queues whose events you want to monitor. For more information on the MQ Events, see the MQ Events Section on page 23.
Step 2 Using MQ Explorer commands:
a For Queue Manager events:
From the Queue Manager properties dialog, choose the events pane. You can enable monitoring of Authority, Inhibit, Local, Remote, Start, and Stop from here.
b For Channel Events:
From the Queue Manager properties dialog, choose the events pane. You can enable monitoring of Channel, SSL, and Channel auto-definition from here.
c For Performance Events:
From the Queue Manager properties dialog, choose the events pane. You must first enable monitoring of Performance from here.
From the queue properties dialog, choose the events pane. You can enable queue depth events and service interval events from here.
You can also use MQSC commands. See the IBM WebSphere MQ documentation for assistance.
» Note If more than one application is monitoring the MQ Event Queues, then MQMonitor agent throws “MQ return code 2042 (Object In Use) error message.” To avoid this, go to the queue properties—if default properties are used, then the queues are SYSTEM.ADMIN.PERFM.EVENT, SYSTEM.ADMIN.QMGR.EVENT, and SYSTEM.ADMIN.CHANNEL.EVENT—click the Extended tab, and set the Shareability property set to Shareable and the Default Input Open Option property to Input shared.
After setting the options, start the MQMonitor agent.
66 Installing and Configuring the PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Turn on Queue Monitoring
You must turn on Queue Monitoring for each individual queue in MQ Explorer to see the following Oldest Message Age and Queue Time metrics:
Oldest Message Age (sec), Oldest Message Age Per Hour (sec), Oldest Message Age Per 6 Hours (sec), Oldest Message Age Per Day (sec).
Last Get Date, Last Put Date, Last Put Time, Last Get Time, Queue Time (Long Term Avg.), Queue Time (Short Term Avg.).
To turn on queue monitoring for individual queues:
1 Go to Queue Properties > Statistics Page.
2 Set Queue Monitoring to High, Medium, or Low.
3 Set Queue Statistics to On or Queue Manager.
You can also use the MQSC commands to turn on Queue Monitoring. For more information, see the IBM WebSphere MQ documentation.
Viewing Data Using PowerPack for MQ 67
CHAPTER 3
Viewing Data Using PowerPack for MQ
PowerPack for MQ reports data to the Introscope Enterprise Manager (EM). This chapter describes how you can view Introscope data using PowerPack for MQ.
This chapter contains the following topics:
View data . . . . . . . . . . . . . . . . . . . . . 67
Console dashboards . . . . . . . . . . . . . . . . . . 67
Investigator dashboards. . . . . . . . . . . . . . . . . 68
View dataTo view the data sent to the EM, you use these Introscope Workstation GUI tools:
Console Dashboards
Investigator Dashboards
Console dashboardsPowerPack for MQ provide the Management Modules that consist of several pre-configured dashboards for the Introscope Console.
MQ dashboards in the Console
You can view the following WebSphere MQ and WebSphere Message Broker dashboards in the Console:
WebSphere MQ Client and Server dashboards
WebSphere MQ Client And Server Overview
WebSphere MQ Client And Server Overview - Details
WebSphere MQ - Client Connections
WebSphere MQ - Client Operations
WebSphere MQ - Server
68 Viewing Data Using PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
WebSphere Message Broker dashboards
WebSphere Message Broker - Backouts Total
WebSphere Message Broker - Channels
WebSphere Message Broker - Errors Total
WebSphere Message Broker - Messages Dropped Total
WebSphere Message Broker - Overview
WebSphere Message Broker - Queue Managers
WebSphere Message Broker - Queues
WebSphere Message Broker - Timeouts Total
To use the Console dashboards:
1 Launch Introscope Enterprise Manager.
2 Launch the Introscope Workstation to connect to the Introscope Enterprise Manager, and log into the Console.
3 Using the dropdown menu, select one of the dashboards.
Investigator dashboardsPowerPack for MQ provides pre-configured graphical dashboards and data displays to give users visibility into the most important metrics provided by WebSphere MQ and WebSphere MB. These displays aggregate, correlate, and display important metrics so that you can see at a glance how the system is functioning and where problems are occurring.
To view dashboards and data displays:
1 Launch Introscope Enterprise Manager.
2 Launch the Introscope Workstation to connect to the Introscope Enterprise Manager, and log into the Investigator.
In the Investigator, the metric data is organized in the following ways:
the metrics tree
dashboards and graphical displays
Understanding the metrics tree
The PowerPack for MQ displays two main types of data from WebSphere MQ or WebSphere MB:
Data from MQMonitor agent and MBMonitor agent.
Data from the MQ Java Connectors.
Investigator dashboards 69
User Guide
MQMonitor agent and MBMonitor agent metrics
To find data from the MQMonitor agent and MBMonitor agent:
Select *SuperDomain* > <hostname> > WebSphere MQ and Message Broker > WebSphere MQ and Message Broker Agent (*SuperDomain*) node:
The following illustration shows data from the MQMonitor agent in four places in the Investigator metrics tree:
Basic information about the WebSphere MQ agent and the Message Broker agent, under WebSphere MQ and Message Broker Agent (*SuperDomain*).
Queue Manager Cluster metrics, under Queue Manager Clusters.
Queue Manager metrics, under Queue Managers.
Message Broker metrics, under WebSphere Message Broker.
70 Viewing Data Using PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
hleveltre
Investigator dashboards 71
User Guide
The following sections of this chapter provide a summary of the contents of the Investigator metrics tree. Appendix A provides detailed explanations of each metric.
Host information
At the top level of the MQ metrics tree, you can view information about the host where MQMonitor agent is running.
Metric name Description
EM Host Name of the machine that hosts the Introscope Enterprise Manager.
Java Version Version of Java being run by the MQMonitor agent.
Launch Time Time and date when MQMonitor agent was last launched.
Virtual Machine Vendor of the JVM (Java Virtual Machine) running MQMonitor agent.
GC Heap “Garbage collection” heap—the amount of free memory available to the MQMonitor agent.
Bytes In Use Size of the in-use memory heap on the MQMonitor agent.
Bytes Total Total size of the memory heap on the MQMonitor agent.
Host Machine which hosts the MQMonitor agent.
IP Address MQMonitor agent’s IP address.
Operating System MQMonitor agent’s operating system.
Wall Clock Time Local time of the MQMonitor agent.
Queue Manager Cluster metrics
Under the Queue Manager Clusters node, you can view metrics and status information for cluster Queue Managers.
For more information on Queue Manager Cluster metrics, see Queue Manager Cluster metrics on page 125.
Queue Manager metrics
Under the Queue Managers node, you can view metrics for each Queue Manager under six different nodes:
Channels—Links between two Queue Managers (a message channel), or between a Queue Manager and a client application (an MQI channel). Channel objects have attributes that define how message channels behave.
Under the Channels node, you can view Configuration Properties and Status metrics for each of the channels running under the Queue Manager.
72 Viewing Data Using PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Channel Initiator—Provides and manages resources that enable WebSphere MQ distributed queuing. WebSphere MQ uses Message Channel Agents (MCAs) to send messages from one Queue Manager to another.
PageSets—Data sets that are specially formatted to be used by WebSphere MQ. Page sets are used to store most messages and object definitions. WebSphere MQ page sets can be up to 64 GB in size. Each page set is identified by a page set identifier (PSID). Each Queue Manager must have its own page sets.
Logs—Records all significant events that occur in WebSphere MQ. The log contains the information about Persistent messages, WebSphere MQ objects such as queues, and the WebSphere MQ Queue Manager.
Configuration Properties—Data on how administrators have configured each Queue Manager. Some properties have both a string and a numeric value.
Dead Letter Queue—Configuration Properties and Status data/metrics about MQ Queue Manager’s dead letter queue, which is a repository for undeliverable messages.
Last Check—Information about the connection status of the Queue Manager.
Queues—Configuration Properties and Status data/metrics for each of the queues configured by the administrators on the Queue Manager.
Status—Data and metrics on the status of the Queue Manager. Some properties have both a string and numeric value.
For more information about Queue Manager metrics, see Queue Manager metrics on page 146.
Message Broker metrics
You can see three kinds of data and metrics for each message broker which the administrator has configured:
Broker Properties—Identification and configuration information about this message broker.
Component Runstate—Whether the message broker is running or not running.
Number of Subcomponents—the number of Execution Groups under this broker.
Shared Object—Whether the message broker is a shared object (“TRUE”) or a non-shared object (“FALSE”).
UUID—Universally Unique Identifier for the Broker.
Execution Groups—Sets of processes within a broker in which message flows run. For each execution group, you can see metrics arranged in several subgroups:
Investigator dashboards 73
User Guide
Status and configuration information.
Broker Statistics—Divided into Client Statistics, Neighbor Statistics, and Wide Statistics.
Message Flows—Divided into several subcategories.
Broker Queue Manager metrics—Detailed information about the status and configuration metrics for the broker Queue Manager, divided into:
Channels
Configuration Properties
Dead Letter Queue
Queues
Status
For more information on Message Broker metrics, see Message Broker metrics on page 181.
MQ Java Connector metrics
MQ Java Connector metrics allow you to monitor the performance of your application server.
To obtain data from MQ Java Connectors:
1 Expand the SuperDomain node and look under the <hostname><WebSphere><WebSphereAgent>(*SuperDomain*) node.
2 Look under certain nodes in the tree, as shown in the following illustration:
74 Viewing Data Using PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
For more information on MQ Java Connector metrics, see MQ Java Connector metrics on page 196.
Investigator Dashboards and data displays
To show dashboards and graphical displays of metric data:
Click on any node higher than an individual metric.
Investigator dashboards 75
User Guide
Almost all of these nodes have associated Investigator dashboards which display an aggregate view of the metrics under that node, and the Overview tab usually contains “traffic light” indicators. The design of each dashboard, the data it aggregates, and the thresholds which trigger changes in traffic lights depends on the node you select.
In the example above, the Queue Managers node is selected.
Things to notice:
Traffic lights
Traffic light widgets provide an overview of critical performance metrics. Each of the traffic lights corresponds to aggregated metrics viewable in the metrics tree under the node selected.
» Tip In most cases, double-clicking the traffic light displays the metric data underlying that traffic light.
Data table
A table beneath the traffic lights gives more information; in this example, it lists each of the Queue Managers associated with the selected node, allowing a user to quickly see that the first Queue Manager listed has reached its maximum queue depth.
In this example, the table columns reflect the same information shown in the traffic lights. In other cases, table columns provide additional information.
76 Viewing Data Using PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Remember that the Investigator dashboards display aggregated or calculated metrics, not atomic data which comes directly from WebSphere MQ. These tables display data that has been aggregated or calculated.
Colors
The colors reflect threshold settings.
red—a danger threshold has been reached for at least one of the objects monitored under this object.
yellow—a caution threshold has been reached for at least one of the objects monitored under this object.
green—no thresholds have been reached for any of the objects monitored under this object.
white—no data has been received for any of the objects monitored under this object.
Tabs
Each dashboard has an Overview tab, and additional tabs with more data. The names and contents of these tabs depends on the node.
Each dashboard element is pre-configured, and you can use them without performing additional configuration.
Aggregated metrics
The tables in this section list the aggregated metrics and traffic lights which you see in the PowerPack for MQ dashboards, with details about each.
Investigator dashboards 77
User Guide
Queue Manager Cluster and Queue Manager metrics
Aggregated metric name Description Value
Aggregated Agent-MQ Connection Status
Indicates the aggregated connection status of PowerPack for MQ with all the Queue Managers.
0 = green—successful
1 = red—unsuccessful
Aggregated Channel Indoubt Status
Indicates whether any of the channels on the Queue Managers are currently in doubt.
Note: Applies only to sending channels
0 = green—No channels are in doubt
1 = red—At least one channel is in doubt.
Aggregated Page Set Status (z/OS only)
Indicates the aggregated status of the page sets.
0 = green—all page sets are running
1 = red—one or more page sets have stopped
Aggregated Queue Manager Status
Indicates the aggregated status of the Queue Managers. One of:
0 or green = all the Queue Managers are running
1 or red = one or more Queue Managers have stopped
0 = green—running
1 = red—unknown
Maximum Queue Depth Reached Indicates whether the maximum queue depth has been reached for any of the queues under this node.
0 = green—maximum not reached
1 = red—maximum reached
Queue aggregated metrics
Aggregated metric name Description Value
Get Enabled Indicates whether the get operations are allowed for the queues or not.
0 = green—get operations are allowed (messages can be read) for all queues under this node
1 = red—get operations are inhibited (messages cannot be read) for at least one of the queues under this node
Maximum Queue Depth Reached Indicates whether the maximum queue depth has been reached for any of the queues under this node.
0 = green—maximum not reached
1 = red—maximum reached
78 Viewing Data Using PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Message Broker aggregated metrics
The following illustration shows the WebSphere Message Broker node:
Maximum Queue Depth (% Queue Full)
Indicates the greatest recorded queue depth for any of the queues under this node (measured in percent of fullness).
Green = maximum queue depth is <70% for all queues under this node
Yellow = maximum queue depth is >70% but <90% for all queues under this node
Red = maximum queue depth is >90% for all queues under this node
Put Enabled Indicates whether put operations are allowed for the queues or not.
0 = green—put operations are allowed (messages can be put on a queue) for all queues under this node
1 = red—put operations are inhibited (messages cannot be put on a queue) for at least one queue under this node
Investigator dashboards 79
User Guide
The table below describes aggregated metrics for the Message Broker Configuration Manager:
Aggregated metric name
Description
Backouts Total Total number of backouts reported under this node.
Errors Total Total number of errors reported by the objects under this node. Errors are aggregated from message flow statistics.
Messages Dropped Total
Total number of dropped messages under this node.
Timeouts Total Total number of timeouts reported under this node.
MQ Events
To view MQ Events in the Introscope Investigator workstation:
1 Select *SuperDomain* > <hostname> > WebSphere MQ and Message Broker > WebSphere MQ and Message Broker Agent (*SuperDomain*) node.
2 Look in the right pane in the What’s Interesting column:
80 Viewing Data Using PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Using dashboards in troubleshooting 81
User Guide
Using dashboards in troubleshootingThe aggregate metrics calculated by PowerPack for MQ dashboards allow users to spot trouble and quickly identify its source. This section guides you in using the MQ dashboards for troubleshooting.
Troubleshooting Queue Manager clusters and Queue Managers
This section gives you advice for troubleshooting the first two high-level nodes in the MQ metrics tree:
Queue Manager Clusters
Queue Managers
Queue depth
Very often the first sign of a problem with a queue is progressive increasing queue depth. Abnormal increases in queue depths might be common during scheduled batch processes, but unexpected increases should be cause for investigation.
When you see an unexpected increase in queue depth:
1 Check whether the application can access the queues.
2 Check the Connection metrics to see if there are any exceptions raised when the application attempts to connect to the queue.
3 Check whether the application is able to read and deliver messages to the queues.
a Although the message depth could indicate that the messages are being put on the queue, they could still be unavailable to be read by the application if they are uncommitted, so check metrics on commits/backouts.
b Check gets/puts for any abnormalities.
c Check queue residency times (Avg/Max) for abnormalities.
4 Check performance metrics relating to message processing to/through the queues.
5 Check the message size (Avg/Max) for any abnormalities.
6 Check the status of the dead letter queues. A large number of messages in the dead letter queue could adversely impact application performance.
Channels
1 Check the state of the channel—whether it is running, stopped, in doubt, retry, or any other state.
2 Check whether the channel is moving messages fast enough.
82 Viewing Data Using PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
a Investigate throughput by comparing:
Buffers Sent vs. Buffers Received.
Bytes Sent vs. Bytes Received, or Messages Sent vs. Messages Received.
b Check the status of the MCAs (Message Channel Agents) that link to the channel.
c Check the status of the transmission queues (a channel is always linked to a transmission queue). If a receiver channel is down, the sender channel might do certain number of re-tries to move the messages in which case the messages do not appear in a Dead Letter Queue immediately.
Example
In this illustration, the user has selected the Queues node on the default Queue Manager.
Red traffic lights indicate the maximum queue depth has been reached on at least one of the queues.
Using dashboards in troubleshooting 83
User Guide
1 Click the Message Throughput tab, which lists all the queues under the Queues node. One of the queues, SOCCER_SUBSCRIPTION, is highlighted, as shown in the illustration below.
2 Double-click the red-highlighted cell. The display changes to a display of graphs highlighting the most important metrics for that queue. The following illustration shows the Current Queue Depth as 300:
84 Viewing Data Using PowerPack for MQ
PowerPack for WebSphere MQ Connectors and Messaging System
Troubleshooting Message Brokers
The most important Message Broker metrics to monitor are under the Message Flows > Node Statistics node:
Compute Node metrics
Metrics on Input and Output Nodes
Database nodes, particularly with respect to:
Response Time
Amount of data retrieved from database
The Node Statistics appear under the Message Flows node of the Message Broker tree, as shown here:
Transaction Tracing 85
CHAPTER 4
Transaction Tracing
The PowerPack for MQ introduces support for WebSphere MQ message tracking by extending the core Transaction Trace feature of Introscope. This chapter describes cross-process transaction tracing, how you can configure the WebSphere MQ system for trace, and how you can interpret the trace data.
This chapter contains the following topics:
Cross-Process Transaction Tracing . . . . . . . . . . . . . 86
Transaction Trace Viewer . . . . . . . . . . . . . . . . 86
Configure the WebSphere MQ System for trace . . . . . . . . . 87
Verify the transaction trace configuration . . . . . . . . . . . 91
WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard92
Enable or disable MQ Traces . . . . . . . . . . . . . . . 104
Configure EM for trace . . . . . . . . . . . . . . . . . 96
Interpret trace information . . . . . . . . . . . . . . . . 97
Enable or disable MQ Traces . . . . . . . . . . . . . . . 104
Filter queues for transaction trace . . . . . . . . . . . . . 105
Trace data properties . . . . . . . . . . . . . . . . . 106
86 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
Cross-Process Transaction TracingIn Introscope, cross-process transaction tracing is Transaction Tracer’s capability to trace transactions for instance servlets to EJBs, across JVM and CLR boundaries for specific versions of WebSphere and WebLogic application servers.
In PowerPack for MQ, cross-process transaction tracing is expanded to WebSphere MQ. This capability includes transactions crossing from various applications servers to WebSphere MQ backends. The cross-process transaction tracing extends the monitoring capability of PowerPack for MQ and lets you determine which component of WebSphere MQ is causing performance bottlenecks.
PowerPack for MQ obtains MQ traces using the Activity Recording feature of WebSphere MQ. In special cases (when the message goes to a local queue), the MQ trace is obtained by polling, on the MQMonitor agent. The MQ trace-related polling properties are described in MQ Trace related properties Section on page 27.
Transaction Trace ViewerThe following sections describe how you can use the Transaction Trace viewer.
To start a Transaction Trace session:
1 Select Workstation > New Transaction Trace Session.
The New Transaction Trace Session window opens.
2 In the Trace transactions section of the window, specify the threshold execution time. Select milliseconds or seconds from the drop-down list.
» Note Sub-second thresholds can have a negative impact on performance.
To stop a Transaction Trace session:
Click Stop, or select Trace > Stop Tracing Session.
To restart a Transaction Trace session:
Click Restart, or select Trace > Restart Tracing Session.
Restarting the Transaction Trace session resets the timeout to the user-defined time period and continues to trace transactions in the targeted agents using the same threshold criteria. You can restart a Transaction Trace session:
after a session has timed out.
to restart a session that you have stopped.
to restart a session that is in progress.
Configure the WebSphere MQ System for trace 87
User Guide
Configure the WebSphere MQ System for traceYou can use the mqConfigurationSetup tool to configure the WebSphere MQ system for trace. You can also configure the WebSphere MQ system for trace manually.
mqConfigurationSetup tool
You can use the mqConfigurationSetup tool to automate the configuration for cross-process transaction tracing. The tool contains a batch file named mqConfigurationSetup.bat and is available in the /tools directory of the MQMonitor agent. On UNIX, the tool contains the mqConfigurationSetup.sh file, and is available in the /tools directory of the MQMonitor agent.
» Note Before you run the tool, ensure that the MQMonitor.properties file is configured appropriately, as the tool uses the mq.monitor.list property value to obtain the monitored Queue Managers.
The configuration tool updates the following properties on all the monitored Queue Managers and queues:
Sets the Activity recording property to Queue for each Queue Manager.
Creates the SYSTEM.ADMIN.ACTIVITY.QUEUE, Dead Letter Queue(DLQ), and Handshake queue, if any of these queues does not exist in the Queue Manager.
Configures the SYSTEM.ADMIN.ACTIVITY.QUEUE, Dead Letter Queue, and Handshake queue as follows:
Sets the Max queue depth property to the maximum permitted value (999999999).
Sets the Put messages and Get messages properties to Allowed.
Sets the Shareability property to Shareable.
Sets the Default Input Open Option property to Input Shared.
The tool finally generates a report containing information about all the properties that were modified in the Queue Managers and Qqeues. The tool saves the report to a file called changehistory.txt in the /tools directory of the MQMonitor agent. The tool appends all configuration changes to the same file, so that you can see
To apply the changes, restart all active channels on the monitored Queue Managers. Alternatively, except for z/OS, we recommend that you also restart all the monitored Queue Managers.For z/OS, restart CHINIT only as restarting the Queue Manager, may change the value of the Activity Recording property of some Queue Managers to “Message” instead of “Queue”.
all the changes made to the WebSphere MQ objects.
» Important
» Important
88 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
To configure the mqConfigurationSetup tool:
1 Configure the MQMonitor.properties to monitor Queue Managers. See Configure the MQMonitor agent properties on page 20.
2 Edit the mqConfigurationSetup.bat file for the following settings.
Set the JAVA_HOME variable to a valid JRE.
Set the MQ_JAR variable to the location of com.ibm.mq.jar file.
Set the PCF_JAR variable to the location of com.ibm.mq.pcf-6.1.jar file.
Set the J2EE_JAR variable to the location of j2ee.jar file.
3 Run the mqConfigurationSetup.bat file. The command is as follows:
mqConfigurationSetup.bat [-i on/off] [-p ../properties/]
» Note Set the parameter -i for interactive or non-interactive mode. The default value of the parameter is on. If you set the parameter to on, then the tool prompts you for confirmation before changing the properties of the WebSphere MQ objects. If you set the parameter to off, then the tool changes all the properties without prompting you for confirmation.
» Note Set the parameter -p to indicate the location of the MQMonitor.properties file. The default value of this parameter is ../properties/.
Configure WebSphere MQ for trace manually
To manually configure the WebSphere MQ system for trace, perform the following steps:
Configure the Queue Managers as follows:
Set the Activity recording property on page 88.
Configure SYSTEM.ADMIN.ACTIVITY.QUEUE on page 90.
Set the Max queue depth property to the maximum permitted value (999999999).
Set the Put messages and Get messages properties to Allowed.
Set the Shareability property to Shareable.
Set the Default Input Open Option property to Input Shared.
Set the handshake queue on page 90.
Set the Activity recording property
For all the Queue Managers in WebSphere MQ that are monitored by the MQMonitor agent, set the value of the Activity recording property to Queue. This enables the Queue Managers to generate activity reports. All the activity reports are generated in SYSTEM.ADMIN.ACTIVITY.QUEUE of the same Queue Manager.
Configure the WebSphere MQ System for trace 89
User Guide
The following illustration shows how you can set the Activity recording property to Queue for the SOURCE Queue Manager in the MQ Explorer:
You can use the MQSC commands to set and display the Activity recording property.
To set the Activity recording property, enter the command:
runmqsc <Queue Manager Name>
To view the value of the Activity recording property, enter the command:
display QMGR ACTIVREC
The Activity recording property values appear in the command prompt window under the following two columns:
QMNAME(SOURCE) ACTIVREC(MSG)
To set the ACTIVEREC property value to QUEUE, enter the command:
alter QMGR ACTIVREC(QUEUE)
To verify the Activity recording property, enter the command:
display QMGR ACTIVREC
The Activity recording property values appear in the command prompt window under the following two columns:
QMNAME(SOURCE) ACTIVREC(QUEUE)
For more details, see the IBM documentation.
» Important Restart the Queue Manager MCA’s after configuring the SYSTEM.ADMIN.ACTIVITY.QUEUE.
90 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
Configure SYSTEM.ADMIN.ACTIVITY.QUEUE
To configure SYSTEM.ADMIN.ACTIVITY.QUEUE:
1 Open SYSTEM.ADMIN.ACTIVITY.QUEUE in the MQ Explorer.
2 Right-click SYSTEM.ADMIN.ACTIVITY.QUEUE and click Properties.
The SYSTEM.ADMIN.ACTIVITY.QUEUE properties window opens.
3 Select Extended and set the Max queue depth property to 999999999. Set Shareability as Shareable. Set the Default Input Open Option property to Input Shared.
4 Select General, and set the Put messages and Get messages properties to Allowed.
MQSC commands
You can use the MQSC commands to configure SYSTEM.ADMIN.ACTIVITY.QUEUE.
To define SYSTEM.ADMIN.ACTIVITY.QUEUE (if not already defined), enter the command:
define QLOCAL(SYSTEM.ADMIN.ACTIVITY.QUEUE) USAGE (normal) DESCR('For Introscope Use')
To configure the SYSTEM.ADMIN.ACTIVITY.QUEUE, enter the command:
alter QLOCAL (SYSTEM.ADMIN.ACTIVITY.QUEUE) PUT (enabled) GET (enabled) DEFPSIST (no) SHARE DEFSOPT (SHARED) MAXDEPTH (999999999)
To verify the SYSTEM.ADMIN.ACTIVITY.QUEUE, enter the command:
display QLOCAL(SYSTEM.ADMIN.ACTIVITY.QUEUE)
Set the handshake queue
Handshake refers to the communication between the MQMonitor agents and MQ Java Connector agents. You can perform handshake by creating a queue (called handshake queue) on an existing Queue Manager or a new Queue Manager, that is accessible from all application servers and MQMonitor agents.
To define a local queue, say CA_WILY_HANDSHAKE, enter the MQSC command:
define QLOCAL(CA_WILY_HANDSHAKE) USAGE(NORMAL) PUT(ENABLED) GET(ENABLED) DEFPSIST(NO) SHARE DEFSOPT (SHARED) DESCR('For Introscope Use')
The above command defines the CA_WILY_HANDSHAKE queue with the put and get properties enabled, not persistent, and shareable.
Verify the transaction trace configuration 91
User Guide
To verify the queue, enter the command:
display QLOCAL(CA_WILY_HANDSHAKE)
Set the MCA User ID
To ensure that the trace data does not reach the Dead Letter Queue, and for transaction trace to occur, you can set the MCA user ID as described below.
» Note This is applicable for WebSphere MQ infrastructure that consists of Queue Managers of various WebSphere MQ platforms, to obtain MQ trace for Queue Managers of different types.
The Java application may use WebSphere MQ, JMS, or MQ Java Connectors to interact with the WebSphere MQ infrastructure. Depending on the setting of the Java application, you can use the following approaches to set the MCA user ID:
If the Java application sets the user ID of the WebSphere MQ message, then perform the following steps to add a user:
a Identify the user that is being set by the Java application on the MQMessage.
b Create the user on all WebSphere MQ machines.
c Add the user to the group created by WebSphere MQ installation on all platforms.
d Restart the channels.
If the Java application does not set the user ID of the MQ Message, then perform the following steps to add a common user:
a Create a common user for all WebSphere MQ machines.
b Add the common user to the group created by WebSphere MQ installation on all platforms.
c Set the common user in the Server-connection channel’s attribute MCA user ID using the WebSphere MQ Explorer on all Server-connection channels on all Queue Managers. The corresponding MQSC command is:
alter channel (<channel name>) CHLTYPE (SVRCONN) MCAUSER(<common user>)
d Restart the channels.
Verify the transaction trace configurationTo check if you have configured the transaction trace properly, check the following:
The handshake and trace-related properties are configured on both the MQAgent.properties and MQMonitor.properties files.
92 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
The handshake queue is available.
All the MQMonitor agents are running.
All the MQMonitor agents are connected to the Queue Managers.
The SYSTEM.ADMIN.ACTIVITY.QUEUE is available, and enabled for put and get operations.
You can check the status of MQ Trace by checking the values of the mqmonitor.mqagent.id.list and handshake.mqagent.id properties in the MQAgent.properties file as shown in the following table:
Value of mqmonitor.mqagent.id.list
Value of handshake.mqagent.id
MQ Trace configuration
null null or any value always on
any value null always off
any valid value any valid value conditional on
WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard
The WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard helps you check whether your WebSphere MQ infrastructure is properly configured for MQ Trace. The dashboard has traffic lights that show the status of SYSTEM.ADMIN.ACTIVITY.QUEUE, Agent-MQ Connection Status, Handshake status, Activity recording status, and Dead Letter Queue.
WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard 93
User Guide
Here’s an illustration of the dashboard:
94 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
The SYSTEM.ADMIN.ACTIVITY.QUEUE has traffic lights for the following elements:
Get/Put Messages
Queue Full
Shareability
The following table lists the threshold values for
Element Threshold
Get/Put messages Green - Indicates that all the SYSTEM.ADMIN.ACTIVITY.QUEUE of the monitored Queue Managers are receiving and sending messages.Red - Indicates that one or more SYSTEM.ADMIN.ACTIVITY.QUEUE of the monitored Queue Managers cannot send or receive messages.
Queue Full Green - Indicates that the % Queue Full value of the monitored Queue Managers is less than 50%.
Yellow - Indicates that the % Queue Full value of the monitored Queue Managers is greater than 50% and less than 75%.Red - Indicates that the % Queue Full value is greater than 75%.
Shareability Green - Indicates that the Shareability property of SYSTEM.ADMIN.ACTIVITY.QUEUE is set to Shareable.Red - Indicates that the Shareability property of SYSTEM.ADMIN.ACTIVITY.QUEUE is not set to Shareable.
the above elements:
The Dead Letter Queue has traffic lights for the following elements:
Get/Put Messages
Queue Full
Shareability
WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard 95
User Guide
The following table lists the threshold values for
Element Threshold
Get/Put messages Green - Indicates that all the Dead Letter Queues of the monitored Queue Managers are configured for sending and/or receiving messages from applications.Yellow - Indicates that one or more Dead Letter Queue of the monitored Queue Managers are not configured for sending and/or receive messages from applications.
Queue Full Green - Indicates that the % Queue Full value of the monitored Queue Managers is less than 50%.
Yellow - Indicates that the % Queue Full value of the monitored Queue Managers is greater than 50%.
Shareability Green - Indicates that the Shareability property of Dead Letter Queue is set to Shareable.Yellow - Indicates that the Shareability property of Dead Letter Queue is not set to Shareable.
the above elements:
Apart from the traffic light indicators for SYSTEM.ADMIN.ACTIVITY.QUEUE and Dead Letter Queue, the dashboard includes traffic lights for the following:
Element Threshold
Agent-MQ connection Status
Green - Indicates that the MQMonitor agent is able to successfully connect to all the monitored Queue Managers.
Red - Indicates that the MQMonitor agent cannot connect to one or more Queue Managers.
Handshake Status Green - Indicates that the handshake between the MQMonitor agents and MQ Java Connector agents is successful.
Red - Indicates that the handshake between the MQMonitor agents and MQ Java Connector agents is not successful.
Activity Recording status
Green - Indicates that the Activity recording property for all the monitored Queue Managers is set to Queue.
Red - Indicates that the Activity recording property for one or more monitored Queue Managers is set to a value other than Queue.
Based on the threshold values of all the elements, the dashboard shows the overall status of your PowerPack for MQ installation in the central traffic light indicator.
96 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
The overall status traffic light appears as green if the traffic lights of all of the elements are green. However, if one of the traffic lights in the SYSTEM.ADMIN.ACTIVITY.QUEUE, or Agent-MQ Connection Status, Handshake Status, or Activity Recording status is red, the overall status traffic light turns red.
Configure EM for traceTo configure the Introscope Enterprise Manager (EM) for trace:
1 Edit the IntroscopeEnterpriseManager.properties file located in the <Introscope Home>/config directory to add the following two lines:
introscope.workstation.transactiontracer.showTotalDuration=trueintroscope.workstation.transactiontracer.showTotalDuration.sumAl
lTraceComponents=true
2 Restart the EM.
An additional column called Total Duration (ms) appears in the Transaction Trace Viewer. The Total Duration (in milliseconds) of a trace is the wall clock time from the start to the very end of all trace components.
Interpret trace information 97
User Guide
Interpret trace information
Scenario 1 - Single Hop in the WebSphere MQ infrastructure
Message has been put by the Java application to a Remote Queue HOP1.REMOTE of Queue Manager HOP1 located at host localhost. The message hops to another queue HOP2.LOCAL of Queue Manager HOP2 at host localhost.
The following illustration shows the complete trace of this message transaction when the transaction trace session is turned on:
98 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
The interpretation of this trace is as follows:
The Total Transaction takes 14011 ms. The Total trace contains three components.
The first trace component is the MQ Java Connector trace. If you zoom the trace, the trace appears as follows:
The MQ Java Connector generates a Queue Put operation of 91 ms.
The message has been put to HOP1.REMOTE queue of Queue Manager HOP1.
Interpret trace information 99
User Guide
The second trace component is the trace coming from the MQMonitor agent for the first Queue Manager HOP1.
The message is read using the MQ get operation (MQ Operation: GET).
The message stayed at the Transmission Queue (MQ Queue Type: TRANSMISSION) named HOP1.TRANS (MQ Queue Name: HOP1.TRANS) for 11330 ms (MQ Queue Residency Time: 11330 ms).
The message is supposed to go to the Queue Manager HOP2 (MQ Target Queue Manager: HOP2) through the sender (MQ Channel Type: SENDER) channel named HOP1.SNDR (MQ Channel Name: HOP1.SNDR).
100 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
The third trace component is the trace coming from the MQMonitor agent for the second Queue Manager HOP2.
The message is received by a receiver (MQ Channel Type: RECEIVER) channel named HOP1.SNDR (MQ Channel Name: HOP1.SNDR) and put (MQ Operation: Put) to a local queue (MQ Queue Type: LOCAL) named HOP2.LOCAL (MQ Queue Name: HOP2.LOCAL).
The message is found to be at HOP2.LOCAL for 2580 ms (MQ Queue Residency Time (~): 2580 ms) and also the message is not consumed (MQ Message Status: Message is not consumed) by the any other Application.
The message has not expired (MQ Message Expiry Time: Never expires) after 2580 ms.
» Note In the above case, when the message is put by the Java application to a local queue of a Queue Manager, the values of MQ Queue Residency Time and MQ Message Status at the local queue depends on the value of trace.polling.interval and trace.polling.retry.count properties.
Interpret trace information 101
User Guide
Scenario 2- No Hop inside the WebSphere MQ infrastructure
Message has been put by the Java application to a Local Queue Queue1 of Queue Manager QMGR1 located at host1.
The following illustration shows the complete trace of this message transaction when the transaction trace session is turned on:
The interpretation of the above trace is as follows:
The upper trace comes from the MQ Java Connector agent that captures the Put call of the Java application; the selected trace is the trace that comes from the MQMonitor agent.
The total duration of the transaction is 3077 ms (Total Duration (ms) column of the table).
The time taken by the MQ Java Connector agent is 484 ms (Duration (ms) column of the table).
The time taken by the message inside the MQ environment is 2677 ms (Duration (ms) column of the table).
The Java application puts (MQ Operation: PUT) the message to a local queue (MQ Queue Type: LOCAL) named Queue1 (MQ Queue Name: Queue1) through a Server Connection Channel to MQ (MQ Channel Type: SERVER-CONNECTION).
The message is found to be at Queue1 for 2677 ms (MQ Queue Residency Time (~): 2677 ms) and also the message is not consumed (MQ Message Status: Message is not consumed) by any other application.
The message has not expired (MQ Message Expiry Time: Never expires)
102 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
after 2677 ms.
» Note In the above case, when the message is put by the Java application to a local queue of a Queue Manager, the values of MQ Queue Residency Time and MQ Message Status at the local queue depends on the value of the trace.polling.interval and trace.polling.retry.count properties.
Identify a slow transactionYou can identify a slow transaction by performing the following steps:
1 Start a Transaction Trace session.
The trace appears in the Transaction Trace viewer.
2 Sort the trace in the descending order of Total Duration (ms) column.
3 Select the first trace in the list.
The first trace indicates the slowest running transaction among all the transactions.
Identify a slow transaction 103
User Guide
4 Select View > Correlated Events to get all the correlated events for the selected trace, as shown in the illustration below.
104 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
5 Select any trace to see the complete trace information.
Enable or disable MQ TracesYou can enable or disable MQ Trace by setting the handshake properties in the MQAgent.properties file.
To disable MQ Traces:
1 Set mqmonitor.mqagent.id.list to any valid value and handshake.mqagent.id to null value.
2 Restart the application server.
When you run the transaction trace, MQ Trace data does not appear on the Transaction Trace Viewer.
To enable MQ Traces without handshake:
Set mqmonitor.mqagent.id.list to null value.
Filter queues for transaction trace 105
User Guide
When you run the transaction trace, you can view MQ Trace data even when the MQMonitor agents are not running. However, you must note that the trace may be incomplete when the MQMonitor agent is unable to connect to any of the monitored Queue Managers.
» Note You need not restart the application server.
To enable MQ Traces with handshake (recommended):
Set mqmonitor.mqagent.id.list to the handshake.mqagent.id value of all MQMonitor agents.
The MQ Trace is generated when all MQMonitor agents are running and connected to their Queue Managers. This method provides you the complete trace and prevents any unnecessary overload on the MQMonitor agent.
You must restart the application server if you change the value of handshake.mqagent.id.
Filter queues for transaction traceYou can use the mqtracing.exclude.queues.regex property in the MQAgent.properties file to filter one or more queues of a particular Queue Manager from transaction tracing.
» Note This property filters the first queue where WebSphere MQ Put or JMS Send operations occur along with the subsequent correlated traces. This also filters the traces for the WebSphere MQ Get or JMS Receive operations.
Example:
To filter all the queues containing the word "SYSTEM" of the Queue Manager QM1 from transaction tracing, set the property:
QM1.mqtracing.exclude.queues.regex=.*SYSTEM.*
To filter all the queues of the Queue Manager QM1 from transaction tracing, set the property:
QM1.mqtracing.exclude.queues.regex=.*
To filter all the queues except queues TRACE.QUEUE1 and TRACE.QUEUE2 of the Queue Manager QM1 from transaction tracing, set the property:
QM1.mqtracing.exclude.queues.regex=(?!((.*TRACE.QUEUE1.*)|(.*TRACE.QUEUE2.*))).*
106 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
Trace data propertiesThe trace data properties vary based on the MQ operations. Channels perform different MQ operations (Get or Put) when they receive or send messages.
The following table describes the trace data:
Key Description Value MQ Operation
<Message ID> Actual message ID of the message.
IScopeMQID Put, Get
<Correlation ID> Actual correlation ID of the message.
This trace data does not appear if the correlation ID is same as message ID or if the correlation ID is null.
IScopeMQID Put, Get
MQ Channel Name Name of the channel on which the WebSphere MQ operations are performed.
<Channel Name> Put, Get
MQ Channel Type Type of the channel on which the WebSphere MQ operations are performed.
Any one of the possible values:
SENDERRECEIVERREQUESTERSERVER CONNECTIONCLUSTER SENDERCLUSTER RECEIVER
Put, Get
MQ Queue Name Queue Name <Queue Name> Put, Get
MQ Queue Type Queue Type Any one of the possible values:
LOCALLOCAL (DLQ)TRANSMISSIONREMOTE
Put, Get
MQ Queue Residency Time
Actual time (in milliseconds) the message stayed in the queue before moving it to the next Queue Manager.
Time in milliseconds (ms) Get
Trace data properties 107
User Guide
MQ Queue Residency Time (~)
Approximate time (in milliseconds) the message stayed in the queue before moving it to the next Queue Manager.
Note: This value is populated when the message is put to a local queue by polling. See Cross-Process Transaction Tracing on page 86.
Approximate time in milliseconds (ms).
or
Systems time may not be in synchronization if the MQMonitor agent and the WebSphere MQ Queue Managers are out of sync.
Put operation to a local queue
MQ Source Queue Manager
Previous Queue Manager Name from where the message has reached the current queue.
<Queue Manager Name> Put operation for one or more WebSphere MQ Hops.
MQ Target Queue Manager
Target Queue Manager Name to where the message must go on the next hop.
<Queue Manager Name> Put operation to a remote queue for one or more WebSphere MQ Hops.
MQ Target Queue Target Queue where the message must go on the next hop.
<Queue Name> Put operation to a remote queue for one or more WebSphere MQ Hops.
MQ Message Status Determines the status of the message in the destination queue.
If trace.polling.enabled=true, then any one of the following values:
Message is consumed or expiredMessage is not consumedMessage is consumed
Put operation to a local queue.
Key Description Value MQ Operation
108 Transaction Tracing
PowerPack for WebSphere MQ Connectors and Messaging System
Management Modules 109
User Guide
5Dashboards
This chapter lists each of the dashboards, their elements, and other information that you can view using the Introscope Console. These dashboards and related elements are part of the Management Module component of PowerPack for MQ. See Install Management Modules and extensions on page 56 for installing Management Modules.
This chapter contains the following topics:
Management Modules . . . . . . . . . . . . . . . . . 109
WebSphere MQ Client and Server dashboards . . . . . . . . . . 109
WebSphere Message Broker dashboards . . . . . . . . . . . 118
For general information on how to view dashboards in the Console, see Console dashboards on page 67.
Management ModulesPowerPack for MQ includes the following management modules:
WebSphere MQ Client and Server dashboards
WebSphere Message Broker dashboards
WebSphere MQ Client and Server dashboardsThe WebSphere MQ Client and Server dashboards show the real-time performance and health of WebSphere MQ system. This management module consists of five dashboards that help you diagnose the performance issues of WebSphere MQ. You can easily navigate through the various dashboards and troubleshoot the issues by correlating the activities in the application to WebSphere MQ operations to actual WebSphere MQ objects.
The WebSphere MQ Client and Server dashboards consists of the following:
WebSphere MQ Client And Server Overview dashboard on page 110.
WebSphere MQ Client And Server Overview - Details dashboard on page 112.
WebSphere MQ - Client Connections dashboard on page 115.
WebSphere MQ - Client Operations dashboard on page 116.
WebSphere MQ - Server dashboard on page 117.
110 Dashboards
PowerPack for WebSphere MQ Connectors and Messaging System
WebSphere MQ Client And Server Overview dashboard
The WebSphere MQ Client And Server Overview dashboard shows the overall health of the Queue Managers, Queues, and Channels. It contains three components—MQ Client Connections, MQ Client Operations, and MQ Server. Each component has traffic lights that show the overall health of that component. For example, the MQ Client Connections component has two traffic lights—Connect and Rollbacks. Clicking the Connect or Rollbacks traffic lights shows the details for the MQ Client Connections component in the WebSphere MQ - Client Connections dashboard.
From the Overview tab, you can double-click any of the component dashboards, and view their details. Also, each traffic light has a link to the dashboard associated with the details of that specific component.
The following tables explain the thresholds and traffic lights in each of the three components of the dashboard.
WebSphere MQ Client and Server dashboards 111
User Guide
MQ Client Connections
MQ Client Operations
Element Description Threshold
Connect Indicates the status of the Average Response Time(ms) for the Connect operations.
Green - Indicates that the applications are able to connect to the WebSphere MQ infrastructure properly without much delay.
Yellow - Indicates that caution threshold has been reached; the applications are taking considerable duration to connect to the WebSphere MQ infrastructure and that there can be some problem in the system.
Red - Indicates that danger threshold has been reached; the applications are taking longer time to connect to the WebSphere MQ infrastructure and that there are some bottlenecks or problems in the system.
Rollbacks Indicates the status of the Responses Per Interval for the Rollback operations.
Green - Indicates that no threshold has been reached.
Yellow - Indicates that caution threshold has been reached.
Red - Indicates that danger threshold has been reached.
Element Description Threshold
Put/Send Indicates the status of the Average Response Time (ms) for the Put/Send operations.
Green - Indicates that the Put or Send operations are completing in time meaning that the communication between the application and the WebSphere MQ Queue Manager or queues is good and that there is no problem in the Put/Send operations.
Yellow/Red- Indicates that the Put or Send operations are taking longer time to complete meaning that there can be problems in the WebSphere MQ infrastructure such as a channel that is busy or is in doubt; it can also mean that there is some problem on the network between the application and the WebSphere MQ infrastructure.
Yellow indicates that the caution threshold has been reached.
Red indicates that the danger threshold has been reached.
Get/Receive Indicates the status of the Average Response Time (ms) status for the Get/Receive operations.
Green - Indicates that the Get or Receive operations are completing in time meaning that the communication between the application and the WebSphere MQ Queue Managers or queues is good and that there is no problem in the Get/Receive operations.
Yellow/Red - Indicates that the Get or Receive operations are taking longer times to complete meaning that there can be problems in the WebSphere MQ infrastructure such as a channel that is busy or is in doubt; it can also mean that there is some problem on the network between the application and the WebSphere MQ infrastructure.
Yellow indicates that the caution threshold has been reached.
Red indicates that the danger threshold has been reached.
112 Dashboards
PowerPack for WebSphere MQ Connectors and Messaging System
MQ Server
WebSphere MQ Client And Server Overview - Details dashboard
The WebSphere MQ Client And Server Overview - Details dashboard contains detailed metrics corresponding to the three components of the WebSphere MQ Client And Server Overview dashboard. Each component section is divided into smaller sections detailing specific and important operations.
The graphs in the dashboard display the following blame metrics for the MQ Client Connections, MQ Client Operations, and MQ Server components:
MQ Client Connections—Includes blame metrics for Average Response Time, Concurrent Invocations, Errors Per Interval, Responses Per Interval, and Stall Count for the Connect, Disconnect, Commit, and Rollback operations. It also includes the Waiting Thread Count, Percent Maxed, and Connection Pool status for the Connection Pool.
MQ Client Operations—Includes blame metrics for Errors Per Interval, Slowest (Average Response Time), Stall Count, Responses Per Interval for Put/Send and Get/Receive operations.
MQ Server—Displays Queue Manager Status (aggregated count), Queue Depth status, and Channel Indoubt Status. Also includes metrics for Connection Counts, Enqueue/Dequeue Count, Current Queue Depth (%), and Messages Per Channel.
Element Description Threshold
Queue Managers Status
Indicates the status of the Queue Manager Aggregated of the MQ Server.
Green - Indicates that all Queue Managers are in the running state.
Red - Indicates that at least one of the Queue Managers is not running.
Queue Depth Indicates the Current Queue Depth (%) of the MQ Server.
Green - Indicates that all queues are being processed by the corresponding applications appropriately, so the messages are being addressed properly.
Yellow/Red - Indicates that the rate of the incoming messages for at least one queue is more than the rate of outgoing messages meaning that the messages are not being addressed properly by the concerned application listening to this queue and so the queue is reaching its full capacity.
Yellow indicates that the caution threshold has been reached.
Red indicates that the danger threshold has been reached.
Channel Status
Indicates the Channels Indoubt status of the MQ Server.
Green - Indicates that none of the channels are in doubt.
Red - Indicates that at least one channel is in doubt, indicating that there is some problem with that channel.
WebSphere MQ Client and Server dashboards 113
User Guide
From the WebSphere MQ Client And Server Overview - Details dashboard, you can click the Overview tab to navigate to the WebSphere MQ Client And Server Overview dashboard.
114 Dashboards
PowerPack for WebSphere MQ Connectors and Messaging System
Interpret the dashboard traffic lights
When a traffic light is green, it indicates that the corresponding operation for that component is working fine or is at an appropriate threshold level. When any alert turns to red, it indicates that there is a problem with that component or operation. Clicking that alert takes you to that dashboard with more details of that component, where you can investigate the specific operation causing the problem. Similarly, the WebSphere MQ Overview Details dashboard contains more information regarding all of the three components so that you can correlate all the operations causing the alerts, in a single dashboard.
For example, when the Put/Send alert turns red in the WebSphere MQ Client And Server Overview dashboard, then clicking that alert takes you to the WebSphere MQ - Client Operations dashboard that has details for the Put/Send operations. The WebSphere MQ Client And Server Overview - Details dashboard also shows high level details of all components so that you can triage the problem quickly. In this example, the Put/Send operations may have a problem because of the corresponding Queue may be full or that the channel is in doubt, all of which can be easily seen in the WebSphere MQ - Server component of the WebSphere MQ Client And Server Overview - Details dashboard. You can click any of the traffic lights or graphs to see the blame metrics underlying that status.
WebSphere MQ Client and Server dashboards 115
User Guide
WebSphere MQ - Client Connections dashboard
The WebSphere MQ - Client Connections dashboard shows detailed metrics for MQ Client connections. The dashboard displays Average Respnse Time (ms), Errors (Errors Per Interval), Stalls (Stall Count) as traffic lights for the Connect, Commit, Disconnect, and Rollback operations. The graphs show the top ten metrics of Concurrent Invocations and Responses Per Interval for the Connect, Disconnect, Commit, and Rollback operations. The dashboard also displays Waiting Thread Count, Percent Maxed, and Pool status metrics for the Connection Pool.
From the WebSphere MQ - Client Connections dashboard, you can navigate to the WebSphere MQ Client And Server Overview and WebSphere MQ Client And Server Overview - Details dashboards.
116 Dashboards
PowerPack for WebSphere MQ Connectors and Messaging System
WebSphere MQ - Client Operations dashboard
The WebSphere MQ - Client Operations dashboard shows detailed metrics for WebSphere MQ operations. The dashboard shows four blame metrics for the Put/Get operations of the Connector component and Get/Send operations of the JMS component. For each of the Put/Get, Send/Receive operations, you can see the top ten metrics for Responses Per Interval, Errors Per Interval, Stalls, and Average Response Times (Slowest Gets, Slowest Puts, Slowest Sends, Slowest Receives).
From the WebSphere MQ - Client Operations dashboard, you can navigate to the WebSphere MQ Client And Server Overview and WebSphere MQ Client And Server Overview - Details dashboards.
WebSphere MQ Client and Server dashboards 117
User Guide
WebSphere MQ - Server dashboard
The WebSphere MQ - Server dashboard shows detailed metrics for WebSphere MQ Server. The dashboard displays traffic lights for Queue Manager Status, Page Set Status (z/OS), Queue Depth for Queues, and Channel Indoubt Status for Channels. The graphs show the top 10 metrics for Connection Counts, Dead Letter, Enqueue/Dequeue Counts, Channel Instance Counts, Messages per Channel, and so on.
118 Dashboards
PowerPack for WebSphere MQ Connectors and Messaging System
WebSphere Message Broker dashboardsThe WebSphere Message Broker dashboards show the performance of the Message Broker and its Message Queue.
WebSphere Message Broker Overview dashboard
The WebSphere Message Broker Overview dashboard has both:
traffic lights to show high-level alerts for both WebSphere MQ and WebSphere MB.
bar charts to show the Message Flows with the highest elapsed times and CPU times.
WebSphere Message Broker dashboards 119
User Guide
Elements
The WebSphere Message Broker Overview dashboard displays the following traffic lights.
In the
Component Red light threshold
Overall This traffic light reflects the worst status of the other components. If any one of the child traffic lights are yellow, the Overall traffic light is yellow, else, if any
one of the child traffic lights is red, the Overall traffic light is red.
Note: Red has a higher precedence over yellow.
Errors For each of these traffic lights :Green - No threshold has been reachedYellow - Caution threshold has been reachedRed - Danger threshold has been reached
Timeouts
Backouts
Messages Dropped
Message Broker section:
In the MQ section:
Component Red light threshold
Overall If any of the four child traffic lights pointing to this Overall traffic light are red, then this Overall traffic light is red.
Agent-MQ Connection Status
MQMonitor agent lost its connection with any one of the monitored queue managers.
Queue Managers Status
Any one of the monitored Queue Managers is not running.
Queues Full Any one of the monitored Queues is full (no more messages can be put on the queue).
Channels Indoubt Any one of the monitored channels is in doubt.
Compare the traffic lights with the high-level tree displayed in the Introscope Workstation:
120 Dashboards
PowerPack for WebSphere MQ Connectors and Messaging System
Double-clicking on any of the traffic lights leads to another Console dashboard with more information about the health of the component you selected. For example, double-clicking Errors leads to the WebSphere Message Broker Errors Total dashboard:
Other Message Broker dashboardsWebSphere Message Broker - Backouts Total
WebSphere Message Broker - Timeouts Total
WebSphere Message Broker - Messages Dropped Total
WebSphere Message Broker - Queue Managers
WebSphere Message Broker - Channels
WebSphere Message Broker - Queues
WebSphere Message Broker dashboards 121
User Guide
Message Broker alerts
Message Broker dashboards display an alert with a threshold of 1. For example, if any of the monitored components show a single backout, the Backouts Total
traffic light turns red.
Alert Type Thresholds
Backouts Total Simple Danger Threshold: 1 Caution Threshold: 0
Errors Total Simple Danger Threshold: 1 Caution Threshold: 0
MQ Qmgrs Status Simple Danger Threshold: 0 Caution Threshold: 0
MQ Queues Full Status Simple Danger Threshold: 0 Caution Threshold: 0
MQ Channels Indoubt Status Simple Danger Threshold: 0 Caution Threshold: 0
Messages Dropped Total Simple Danger Threshold: 1 Caution Threshold: 0
Timeouts Total Simple Danger Threshold: 1 Caution Threshold: 0
MQ Agent-MQ Connection Status
Simple Danger Threshold: 0
Caution Threshold: 0
MQ Overall Status Summary
122 Dashboards
PowerPack for WebSphere MQ Connectors and Messaging System
Metrics reference 123
APPENDIX A
Metrics reference
This appendix describes the Introscope metrics that you can view using PowerPackNameShort.
This appendix contains the following topics:
General metric characteristics . . . . . . . . . . . . . . . 123
Queue Manager Cluster metrics . . . . . . . . . . . . . . 125
Queue Manager metrics . . . . . . . . . . . . . . . . . 146
Message Broker metrics . . . . . . . . . . . . . . . . . 181
MQ Java Connector metrics . . . . . . . . . . . . . . . 196
» Note Time measurements appearing in Introscope are in milliseconds (thousandths of a second). When WebSphere MQ provides metrics in microseconds, Introscope converts these to milliseconds.
General metric characteristicsEach metric is expressed as one of four types:
String
Number
Mapped value—a numeric expression of a metric that is also expressed as a string. See the table below for an example:
Metric name
String Mapped Value
Channel Type
Domain|Hostname|...|...|Queue Managers|Queue manager hostname|Queue Manager name|Channels|SYSTEM.DEF.SVRCONN|Configuration Properties:Channel Type = MQCHT_SVRCONN
7
The tables in this appendix give numeric equivalents for all mapped values.
Interval Count—a numeric value, expressed as number of incidents over the last interval.
124 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Metric display sets
The PowerPackNameShort uses a configuration setting for each group of MQMonitor agent metrics, assigning it to one of these sets:
M = Minimum
R = Recommended
F = Full
Each metric is set to membership in one of these sets, which determine whether or not the Investigator displays the metric for each WebSphere MQ component. The Recommended set contains all the metrics in the Minimum set plus additional metrics, and the Full metrics set contains all the metrics.
You can redefine the Recommended metrics set by editing the Advanced Settings section of the MQMonitor.properties file. See the Advanced Settings Section on page 26 for WebSphere MQ and WebSphere MB components.
The default display settings for each MQMonitor agent metric are documented in the Monitoring Level column in the tables in this section. For example, in the Channels Configuration Properties metrics on page 149, the first metric, Channel Disposition, has a default membership in the Full set.
To change the metric set for a given metric, see Special Settings Section on page 25.
Queue Manager Cluster metrics 125
User Guide
Queue Manager Cluster metricsIn the Queue Manager Clusters node, the Investigator displays cluster queues, cluster receiver channels and cluster sender channels with their associated Queue Managers and arranges them by whether they are full or partial repositories. Each cluster Queue Manager under a cluster tree reports additional cluster related attributes and metric data of child objects compared to the normal tree objects.
Cluster workload balance metrics show work distributed over multiple instances of same-named queues. The Investigator displays workload balance metrics on this cluster queue.
Aggregate clusters status metrics
At the top of the Queue Manager Clusters tree, the Investigator displays aggregated status metrics over all clusters, as shown in the illustration above.
Metric name Type Description
Aggregated Channel Indoubt Status
Mapped Value Indicates whether any of the channels on the clustered queues are currently in doubt. Applies only to sending channels. Possible values:
0 = No channel is in doubt.
1 = At least one channel is in doubt.
Aggregated Queue Manager Status
Mapped Value Indicates the aggregated status of the clustered Queue Managers. One of:
0 or green = all the Queue Managers are running
1 or red = one or more Queue Managers have stopped
126 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Top level repository trees
For each of the Queue Manager Clusters, the Investigator displays:
Aggregate properties for all Queue Manager and queues in the cluster
Metrics arranged according to three nodes:
Full Repositories
Partial Repositories
Workload Balance
For each of the two repository nodes, the Investigator displays the followed by the host name:
Queue Manager names
For each Queue Manager:
Metrics for clustered Queue Managers arranged according to:
- Cluster Queues
- Cluster-Receiver Channels
- Cluster-Sender Channels
Configuration Properties
Status metrics
The following sections describe each of these metrics.
Maximum Queue Depth Reached
Mapped Value Indicates whether the maximum queue depth has been reached for any of the clustered queues.
0 = no queue has reached the maximum queue depth
1 = one or more queues have reached the maximum queue depth
Aggregated Agent-MQ Connection Status
Mapped Value Indicates the aggregated connection status of PowerPackNameShort with all the Queue Managers.
0 or green = successful
1 or red = unsuccessful
Channel Instance Count
Mapped Value Aggregation of number of various channel instance that are currently connected to a Queue Manager.
Metric name Type Description
Queue Manager Cluster metrics 127
User Guide
Aggregated Queue Manager metrics
For each Queue Manager beneath a host name, the Investigator displays three aggregated status metrics:
Metric name Type Description
Aggregated Channel Indoubt Status
Mapped Value Indicates whether any of the channels on the Queue Managers are currently in doubt. Applies only to sending channels. Possible values:
0 = None of the channels are in doubt.
1 = At least one channel is in doubt.
Maximum Queue Depth Reached
Mapped Value Indicates whether the maximum queue depth has been reached for any of the Queues in this cluster.
0 = no queue has reached the maximum queue depth
1 = one or more queues have reached the maximum queue depth
Queue Manager Status
Mapped Value Indicates whether any of the Queue Managers in this cluster are running or stopped.
0 = running
1 = stopped
Aggregated Agent-MQ Connection Status
Mapped Value Indicates the aggregated connection status of PowerPackNameShort with all the Queue Managers.
0 or green = successful
1 or red = unsuccessful
Cluster queue metrics
Under the Cluster Queues node, the Investigator displays:
Aggregated status metrics for all clustered queues on this Queue Manager
Each clustered queue on this Queue Manager, and for each one:
Configuration Properties
Status metrics
Aggregated status for all cluster queues, as described in this table:
Metric name Type Description
Aggregated Get Messages Value
Mapped Value Indicates whether get operations have been inhibited for any of the cluster queues on this Queue Manager. One of:
1 = MQQA_GET_INHIBITED—Get operations are inhibited.
0 = MQQA_GET_ALLOWED—Get operations are allowed.
Aggregated Put Messages Value
Mapped Value Indicates whether put operations have been inhibited for any of the cluster queues on this Queue Manager. One of:
1 = MQQA_PUT_INHIBITED—Put operations are inhibited.
0 = MQQA_PUT_ALLOWED—Put operations are allowed.
128 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Configuration Properties
For each cluster queue on this Queue Manager, the Investigator displays the following configuration properties:
Maximum Queue Depth (% Queue Full)
Number Percentage of fullness of the queue depth of all of the cluster queues on this Queue Manager.
Maximum Queue Depth Reached
Mapped Value Indicates whether the maximum queue depth has been reached for any of the cluster queues on this Queue Manager. One of:
0 = no queue has reached the maximum queue depth
1 = one or more queues have reached the maximum queue depth
Metric name Type Description
Metric name Type Monitoring Level
Description
Base Queue String M Queue name to which the alias resolves.
Cluster Name String F Name of the cluster.
Cluster Queue Manager
String R Name of the Queue Manager managing this queue.
Cluster Queue Type
Mapped Value
M One of:
1 = MQCQT_LOCAL_Q—local
2 = MQCQT_ALIAS_Q—alias
3 = MQCQT_REMOTE_Q—remote
4 = MQCQT_Q_MGR_ALIAS—Queue Manager alias
Default Bind Type
Mapped Value
F Default binding. One of:
0 = MQBND_BIND_ON_OPEN – binding fixed by MQOPEN call.
1 = MQBND_BIND_NOT_FIXED – binding not fixed by MQOPEN call.
Default Priority Number F Default priority.
Description String R Description or label for this Queue Manager.
Get Messages Mapped Value
M Get operations allowed or inhibited.
0 = MQQA_GET_ALLOWED—Get operations are allowed.
1 = MQQA_GET_INHIBITED—Get operations are inhibited.
Max Message Length
Number R Maximum message length.
Queue Manager Cluster metrics 129
User Guide
Persistence Mapped Value
F Default persistence of messages on the queue. One of:
1= MQPER_PERSISTENT—The message survives system failures and Queue Manager restarts.
0= MQPER_NOT_PERSISTENT—The message does not normally survive system failures or Queue Manager restarts.
Both persistent and nonpersistent messages can exist on the same queue.
Put Messages Mapped Value
M Put operations allowed or inhibited.
0 = MQQA_PUT_ALLOWED—Put operations are allowed.
1 = MQQA_PUT_INHIBITED—Put operations are inhibited.
QMID String F Queue Manager name
Queue Depth High Events
Mapped Value
F Enables Queue Depth High events.
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
Queue Depth High Limit
Number F High limit for queue depth
Queue Depth Low Events
Mapped Value
F Enables Queue Depth Low events. One of:
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
Queue Depth Low Limit
Number F Low limit for queue depth
Queue Name String R Queue name.
Queue Type Mapped Value
M Queue Type.
1 = MQQT_LOCAL—Local queue.
2 = MQQT_MODEL Model queue definition.
3 = MQQT_ALIAS Alias queue definition.
6 = MQQT_REMOTE Local definition of a remote queue.
7 = MQQT_CLUSTER Cluster queue definition.
Remote Queue String M Name of the remote queue as known locally on the remote Queue Manager.
Remote Queue Manager
String M Name of the remote Queue Manager.
130 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Status metrics
For each cluster queue on this Queue Manager, the Investigator displays the following status metrics.
In order to see data for Oldest Message and Queue Time metrics, Queue Monitoring must be enabled in WebSphere MQ. See Turn on Queue Monitoring on page 66.
Metric name Type Monitoring Level
Description
Alteration Date String
Dynamic
M Date when properties were last altered.
Alteration Time String
Dynamic
M Time when properties were last altered.
Current Queue Depth Number
Dynamic
M Number of messages currently on the queue.
Current Queue Depth Percentage (% Queue Full)
Number
Dynamic
M Percentage of fullness of the queue.
Dequeue Count Interval Count R Number of messages removed from the queue.
Dequeue Count Per 6 Hours
Number R Running count of the number of message dequeues in the last six hours.
Dequeue Count Per Day
Number R Running count of the number of message dequeues in the last day.
Dequeue Count Per Hour
Number R Running count of the number of message dequeues in the last hour.
Dequeue Count Per Minute
Number R Running count of the number of message dequeues in the last minute.
Enqueue Count Interval Count R Number of messages added to the queue, including messages that have been put to the queue, but have not yet been committed.
Enqueue Count Per 6 Hours
Number R Running count of the number of message enqueues in the last six hours.
Enqueue Count Per Day
Number R Running count of the number of message enqueues in the last day.
Enqueue Count Per Hour
Number R Running count of the number of message enqueues in the last hour.
Enqueue Count Per Minute
Number R Running count of the number of message enqueues in the last minute.
Last Get Date String M Date of last Get command.
Last Get Time String M Time of last Get command.
Queue Manager Cluster metrics 131
User Guide
Last Put Date String M Date of last Put command.
Last Put Time String M Time of last Put command.
Oldest Message Age (sec)
Number M Age of the oldest message on the queue, in seconds.
Oldest Message Age Per 6 Hours (sec)
Number M Running maximum oldest message age over the last six hours.
Oldest Message Age Per Day (sec)
Number M Running maximum oldest message age over the last day.
Oldest Message Age Per Hour (sec)
Number
Dynamic
M Running maximum oldest message age over the last hour.
Open Input Count Number
Dynamic
M The number of handles that are currently open for input for the queue.
Open Output Count Number
Dynamic
M The number of handles that are currently open for output for the queue.
Queue Monitoring Mapped Value
Dynamic
F Queue monitoring level. Possible values:
-3 = MQMON_Q_MGR—Collect monitoring data according to the setting of the QueueMonitoring Queue Manager attribute. This is the default value.
0 = MQMON_OFF—Online monitoring data collection is turned off for this queue.
17 = MQMON_LOW—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a low rate of data collection for this queue.
33 = MQMON_MEDIUM—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a moderate rate of data collection for this queue.
65 = MQMON_HIGH—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a high rate of data collection for this queue.
Queue Time (Long Term Avg.)
Number
Dynamic
M Average time, in milliseconds, that a message spent on the queue, based on activity over a longer period.
Compare with Queue Time (Short Term Avg.)
Metric name Type Monitoring Level
Description
132 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Cluster-Receiver Channel and Cluster-Sender Channel metrics
MQMonitor reports metrics for Cluster-Receiver and Cluster-Sender Channels on separate nodes of the Investigator tree. For each channel, Investigator displays:
Aggregated status metric
Configuration properties
Status metrics
On the Cluster-Receiver Channel node of the tree, the Investigator displays configuration properties and status for each channel.
In the illustration above, notice:
These channels all reside in the Queue Manager named NEWYORK on host host1.
One Cluster-Receiver channel, TO.NEWYORK, with two Queue Managers, NEWYORK and QM_MEDFORD.
The NEWYORK node contains the channel definition metrics. The
Queue Time (Short Term Avg.)
Number
Dynamic
M Average time, in milliseconds, that a message spent on the queue, based on activity over a shorter period.
Compare with Queue Time (Long Term Avg.)
Uncommitted Messages
Number
Dynamic
M Number of uncommitted messages.
Metric name Type Monitoring Level
Description
Queue Manager Cluster metrics 133
User Guide
QM_MEDFORD node contains information about an instance of this channel, which is connected to the Queue Manager named QM_MEDFORD.
Two Cluster-Sender channels, TO.LONDON and TO.MEDFORD, each with a NEWYORK node which has the channel definition metrics for each channel. Additionally, each has a channel instance open to their respective remote Queue Managers:
The channel T0.LONDON has channel instance metrics under QM_LONDON.
The channel T0.MEDFORD has channel instance metrics under QM_MEDFORD.
Channel definitions have the same Queue Manager name as the cluster Queue Manager, whereas the instances have nodes named after the Remote Queue Manager with which they communicate. These channels may be missing some of the following metrics because they are not applicable to that type of channel.
Aggregated status metric
For each channel, the Investigator displays a single status metric:
Metric name Type Description
Aggregated Channel Indoubt Status
Mapped Value Indicates whether any of the channels on the Queue Managers are currently in doubt. Applies only to sending channels. Possible values:
0 = none of the channels are in doubt.
1 = at least one channel is in doubt.
Aggregated Channel Instance Counts
Number
Dynamic
Aggregated count of all the channel instances on the Queue Manager.
The Configuration Properties and Status metrics for each Channel definition and Channel instance are listed in the following sections.
Configuration properties
The same set of Configuration properties can appear under the Cluster-Receiver
Channel node and the Cluster-Sender Channel node.
Metric name Type Monitoring Level
Description
CLWL Channel Priority
Number R Cluster workload channel priority.
CLWL Channel Rank
Number R Cluster workload channel rank.
134 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Status metrics
The same set of status metrics can appear under the Cluster-Receiver Channel
node and the Cluster-Sender Channel node.
CLWL Channel Weight
Number R Cluster workload channel weight.
Channel Name String F Name of the channel definition to be changed, created, tested, reset or deleted. The maximum length of the string is MQ_CHANNEL_NAME_LENGTH.
This parameter is required on all types of channel; on a CLUSSDR it can be different from on the other channel types.
Channel Type Mapped Value
R Specifies the channel type, one of the following:
8 = MQCHT_CLUSRCVR—Cluster receiver channel
9 = MQCHT_CLUSSDR—Cluster sender channel
Cluster Name String F Name of the cluster to which the queue belongs.
Cluster Namelist String F Identifies a namelist object that contains the names of clusters to which this queue belongs.
Queue Manager Name
String R Name of the Queue Manager.
Remote Queue Manager
String R The remote Queue Manager this channel connects to.
Transmission Queue Name
String F Name of the transmission queue.
Metric name Type Monitoring Level
Description
Metric name Type Monitoring Level
Description
Batches Number M Number of completed batches.
Buffers Received Number M Number of buffers received.
Buffers Sent Number M Number of buffers sent.
Bytes Received Number M Number of bytes received.
Bytes Sent Number M Number of bytes sent.
Current Messages Number M Number of messages in the current batch.
Indoubt Status Mapped Value
M Indicates whether the channel is currently in doubt. Possible values:
0 = MQCHIDS_NOT_INDOUBT— Channel is not in doubt.
1 = MQCHIDS_INDOUBT— Channel is in doubt.
Long Retries Left Number M Number of long retry attempts remaining.
Queue Manager Cluster metrics 135
User Guide
MCA Status Mapped Value
M MCA (message channel agent) status. One of:
0 = MQMCAS_STOPPED—Message channel agent stopped.
3 = MQMCAS_RUNNING—Message channel agent running.
Channel Instance Counts
Mapped Value
Dynamic
M Number of instances of channels present currently.
Messages Number M Number of messages.
Overall Channel Status
Mapped Value
M Status of the channel. One of:
0 = MQCHS_INACTIVE—Channel is not active.
1 = MQCHS_BINDING—Channel is negotiating with the partner.
2 = MQCHS_STARTING—Channel is waiting to become active.
3 = MQCHS_RUNNING—Channel is transferring or waiting for messages.
4 = MQCHS_STOPPING—Channel is in process of stopping.
5 = MQCHS_RETRYING—Channel is reattempting to establish connection.
6 = MQCHS_STOPPED—Channel is stopped.
7 = MQCHS_REQUESTING—Requester channel is requesting connection
8 = MQCHS_PAUSED—Channel is paused.
13 = MQCHS_INITIALIZING—Channel is initializing.
Short Retries Left Number M Number of short retry attempts remaining.
Stop Requested Mapped Value
M Whether a stop has been requested. One of:
0 = MQCHSR_STOP_NOT_REQUESTED—User stop request has not been received.
1 = MQCHSR_STOP_REQUESTED—User stop request has been received.
Metric name Type Monitoring Level
Description
136 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Configuration Properties
The Configuration Properties node displays properties for the Queue Manager.
Metric name Type Monitoring Level
Description
Auto CLUSSDR Monitoring
Mapped Value F Setting for online monitoring for automatically defined cluster-sender channels. One of:
-3 = MQMON_Q_MGR—Collection of online monitoring data is inherited from the setting of the Queue Manager's ChannelMonitoring parameter.
0 = MQMON_OFF—Monitoring for the channel is switched off.
17 = MQMON_LOW—Specifies a low rate of data collection with a minimal impact on system performance unless ChannelMonitoring for the Queue Manager is MQMON_NONE. The data collected is not likely to be the most current.
33 = MQMON_MEDIUM—Specifies a moderate rate of data collection with limited impact on system performance unless ChannelMonitoring for the Queue Manager is MQMON_NONE.
65 = MQMON_HIGH—Specifies a high rate of data collection with a likely impact on system performance unless ChannelMonitoring for the Queue Manager is MQMON_NONE. The data collected is the most current available.
Auto CLUSSDR Statistics
Mapped Value F Indicates whether statistics data is to be collected for auto-defined cluster-sender channels (parameter identifier: MQIA_STATISTICS_AUTO_CLUSSDR). One of:
-3 = QMON_Q_MGR—Collection of statistics data is inherited from the setting of the Queue Manager's ChannelStatistics parameter.
0 = MQMON_OFF—Statistics data collection for the channel is switched off.
17 = MQMON_LOW—Specifies a low rate of data collection with a minimal impact on system performance.
33 = MQMON_MEDIUM—Specifies a moderate rate of data collection.
65 = MQMON_HIGH—Specifies a high rate of data collection.
This metric is valid only on AIX, HP-UX, Linux, Solaris, and Windows.
CLWL Channel Priority
Number R Cluster workload channel priority.
Queue Manager Cluster metrics 137
User Guide
CLWL Channel Rank
Number R Cluster workload channel rank.
CLWL Channel Weight
Number R Cluster workload channel weight.
CLWL Use Queue
Mapped Value F Specifies whether a Cluster Queue Manager is to use remote puts to other queues defined in other Queue Managers within the cluster during workload management. One of:
0 = MQCLWL_USEQ_LOCAL—Do not use remote queues.
1 = MQCLWL_USEQ_ANY—Use remote queues.
Channel Auto Definition Exit
String F Channel auto-definition exit name. This exit is invoked when an inbound request for an undefined channel is received, if:
1. The channel is a cluster-sender, or
2. Channel auto-definition is enabled.
This exit is also invoked when a cluster-receiver channel is started.
Channel Name String R The name of the channel used to establish communication with this cluster.
Cluster Name String R Name of the Cluster this Queue Manager is a member of.
Cluster Queue Manager Type
Mapped Value R The type of Queue Manager for this cluster. One of:
0 = Normal—A normal Queue Manager.
1 = Repository—A repository Queue Manager.
Dead Letter Queue
String F Name of the local queue that is to be used for undelivered messages.
Description String R Description of the Queue Manager.
Max Handles Number R Maximum number of handles that are currently open for input for the queue.
Max Message Length
Number R Maximum message length.
Max Priority Number F Maximum message priority supported by the Queue Manager.
Maximum Outbound Cluster Channels
Number R Maximum number of active outbound cluster channels.
Metric name Type Monitoring Level
Description
138 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Status metrics
Metrics under the Status node show Queue Manager status.
Platform Mapped Value R Platform on which the Queue Manager resides. One of:
1 = MQPL_ZOS—z/OS
3 = MQPL_AIX—AIX (same value as MQPL_UNIX).
3= MQPL_UNIX—UNIX systems.
4 = MQPL_OS400—i5/OS.
12 = MQPL_VMS—HP OpenVMS.
11 = MQPL_WINDOWS_NT—Windows.
13 = MQPL_NSK—Compaq NonStop Kernel.
QMID String F Unique identifier of the Queue Manager.
Queue Manager Name
String R Name of the Queue Manager.
Repository Name List
String F Name of the list of clusters for which the Queue Manager is providing a repository service.
Metric name Type Monitoring Level
Description
Metric name Type Monitoring Level
Description
Alteration Date String M Date when properties were last altered.
Alteration Time String M Time when properties were last altered.
Channel Initiator Status (not available on z/OS)
Mapped Value
M 0 = MQSVC_STATUS_STOPPED or Unknown—Channel Initiator stopped/unknown.
1 = MQSVC_STATUS_STARTING—Channel Initiator starting up.
2 = MQSVC_STATUS_RUNNING—Channel Initiator running.
3 = MQSVC_STATUS_STOPPING—Channel Initiator shutting down.
4 = MQSVC_STATUS_RETRYING—Channel Initiator retrying.
Cluster Queue Manager Suspend
Mapped Value
Dynamic
M Indicates whether the Queue Manager is suspended. One of:
0 = No—not suspended.
1 = Yes—suspended.
Command Server Status (not available on z/OS)
Mapped Value
M One of:
2 = MQQMSTA_RUNNING
0 = Unknown
Queue Manager Cluster metrics 139
User Guide
Workload Balance metrics
Workload Balance metrics provide information on queues which have multiple instances within a cluster, residing on more than one Queue Manager.
The Workload Balance tree is organized according to this hierarchy:
Workload BalanceMulti-instance Queue AAggregated metrics across the Queue Managers on this hosthost
Queue Manager 01Configuration PropertiesStatus
Queue Manager 02Multi-instance Queue BAggregated metrics across the Queue Managers on this hosthost
Queue Manager 03
Connection Count (not available on z/OS)
Mapped Value
M Current number of connections to the Queue Manager.
Current Log Extent Name (not available on z/OS)
String F The name of the log extent that was being written to at the time of the Inquire command. If the Queue Manager is using circular logging, this is blank.
Log Path (not available on z/OS)
String F The location of the recovery log extents.
Media Recovery Log Extent Name (not available on z/OS)
String F Name of the oldest log extent required by the Queue Manager to perform media recovery. This is available only on Queue Managers using linear logging. If the Queue Manager is using circular logging, this is blank.
Queue Manager Status
Mapped Value
Dynamic
M One of:
2 = MQQMSTA_RUNNING—Running.
0 = Unknown—Unknown.
Restart Recovery Log Extent Name (not available on z/OS)
String F Name of the oldest log extent required by the Queue Manager to perform restart recovery. This is available only on Queue Managers using linear logging. If the Queue Manager is using circular logging, this is blank.
140 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Aggregated metrics for multi-instance cluster queues
For multi-instance cluster queues, the Investigator displays these aggregated
metrics:
Metric name Type Description
Average Queue Depth
Number Average queue depth for all the Queue Manager instances that manage this cluster queue.
Total Queue Depth
Number Total queue depth for this cluster queue across all Queue Managers that manage it.
The illustration below shows a queue INVENTQ which has instances on two Queue Managers, NEWYORK and LONDON, at the same host.
Queue metrics
For each of the Queue Managers on which an instance of the queue resides, the Investigator displays:
Configuration Properties
Status
Configuration Properties
Metric name Type Monitoring Level
Description
Base Queue String M Queue name to which the alias resolves.
Cluster Name String F Name of the cluster.
Cluster Queue Manager
String R Name of the Queue Manager managing this queue.
Queue Manager Cluster metrics 141
User Guide
Cluster Queue Type Mapped Value
M One of:
1 = MQCQT_LOCAL_Q—local
2 = MQCQT_ALIAS_Q—alias
3 = MQCQT_REMOTE_Q—remote
4 = MQCQT_Q_MGR_ALIAS—Queue Manager alias
Default Bind Type Mapped Value
F Default binding. One of:
0 = MQBND_BIND_ON_OPEN – binding fixed by MQOPEN call.
1 = MQBND_BIND_NOT_FIXED – binding not fixed by MQOPEN call.
Default Priority Number F Default priority.
Description String R Description or label for this Queue Manager.
Get Messages Mapped Value
M Get operations allowed or inhibited.
0 = MQQA_GET_ALLOWED—Get operations are allowed.
1 = MQQA_GET_INHIBITED—Get operations are not allowed.
Max Message Length
Number R Maximum message length.
Persistence Mapped Value
F Default persistence of messages on the queue. One of:
1 = MQPER_PERSISTENT—The message survives system failures and Queue Manager restarts.
0 = MQPER_NOT_PERSISTENT—The message does not normally survive system failures or Queue Manager restarts.
Both persistent and nonpersistent messages can exist on the same queue.
Put Messages Mapped Value
M Put operations allowed or inhibited.
0 = MQQA_PUT_ALLOWED—Put operations are allowed.
1 = MQQA_PUT_INHIBITED—Put operations are inhibited.
QMID String F Queue Manager name
Queue Depth High Events
Mapped Value
F Enables Queue Depth High events.
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
Queue Depth High Limit
Number F High limit for queue depth
142 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Status
In order to see data for Oldest Message and Queue Time metrics, Queue Monitoring must be enabled in WebSphere MQ. See Turn on Queue Monitoring on page 66.
Queue Depth Low Events
Mapped Value
F Enables Queue Depth Low events. One of:
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
Queue Depth Low Limit
Number F Low limit for queue depth
Queue Name String R Queue name.
Queue Type Mapped Value
M Queue type. One of:
1 = MQQT_LOCAL—Local queue.
2 = MQQT_MODEL Model queue definition.
3 = MQQT_ALIAS Alias queue definition.
6 = MQQT_REMOTE Local definition of a remote queue.
7 = MQQT_CLUSTER Cluster queue definition.
Remote Queue String M Name of the remote queue as known locally on the remote Queue Manager.
Remote Queue Manager
String M Name of the remote Queue Manager.
Metric name Type Monitoring Level
Description
Alteration Date String M Date when the properties for this Queue Manager were last altered.
Alteration Time String M Time when the properties for this Queue Manager were last altered.
Current Queue Depth Number
Dynamic
M Number of messages currently on the queue on this Queue Manager.
Current Queue Depth Percentage (% Queue Full)
Number
Dynamic
M Percentage of fullness of the queue.
Dequeue Count Interval Count
R Number of messages removed from the queue.
Dequeue Count Per 6 Hours
Number R Running count of the number of message dequeues in the last six hours.
Dequeue Count Per Day
Number R Running count of the number of message dequeues in the last day.
Queue Manager Cluster metrics 143
User Guide
Dequeue Count Per Hour
Number R Running count of the number of message dequeues in the last hour.
Dequeue Count Per Minute
Number R Running count of the number of message dequeues in the last minute.
Enqueue Count Interval Count
R Number of messages added to the queue, including messages that have been put to the queue, but have not yet been committed.
Enqueue Count Per 6 Hours
Number R Running count of the number of message enqueues in the last six hours.
Enqueue Count Per Day
Number R Running count of the number of message enqueues in the last day.
Enqueue Count Per Hour
Number R Running count of the number of message enqueues in the last hour.
Enqueue Count Per Minute
Number R Running count of the number of message enqueues in the last minute.
Last Get Date String M Date of last Get command.
Last Get Time String M Time of last Get command.
Last Put Date String M Date of last Put command.
Last Put Time String M Time of last Put command.
Oldest Message Age (sec)
Number
Dynamic
M Age of the oldest message on the queue, in seconds.
Oldest Message Age Per 6 Hours (sec)
Number M Running maximum oldest message age over the last six hours.
Oldest Message Age Per Day (sec)
Number
Dynamic
M Running maximum oldest message age over the last day.
Oldest Message Age Per Hour (sec)
Number
Dynamic
M Running maximum oldest message age over the last hour.
Open Input Count Number
Dynamic
M The number of handles that are currently open for input for the queue on this Queue Manager.
Open Output Count Number
Dynamic
M The number of handles that are currently open for output for the queue on this Queue Manager.
Metric name Type Monitoring Level
Description
144 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Percent Queue Depth Variation
The % Queue Depth Variation metric shows the deviation of the Queue Depth from a calculated average. The calculation of the variation is based on 2 numbers:
curreqdepth—Current Queue Depth for a specific Queue Manager.
aveqdepth—Average Queue Depth across all Queue Managers on which the cluster queue resides.
The metric is calculated using this formula:
Queue Monitoring Mapped Value
F Queue monitoring level. Possible values:
-3 = MQMON_Q_MGR—Collect monitoring data according to the setting of the QueueMonitoring Queue Manager attribute. This is the default value.
0 = MQMON_OFF—Online monitoring data collection is turned off for this queue.
17 = MQMON_LOW—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a low rate of data collection for this queue.
33 = MQMON_MEDIUM—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a moderate rate of data collection for this queue.
65 = MQMON_HIGH—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a high rate of data collection for this queue.
% Queue Depth Variation
Number M Shows the deviation of the Queue Depth from a calculated average. See Percent Queue Depth Variation on page 144.
Queue Time (Long Term Avg.)
Number M Average time, in milliseconds, that a message spent on the queue, based on activity over a longer period.
Compare with Queue Time (Short Term Avg.)
Queue Time (Short Term Avg.)
Number M Average time, in milliseconds, that a message spent on the queue, based on activity over a shorter period.
Compare with Queue Time (Long Term Avg.)
Uncommitted Messages
Number M Number of uncommitted messages.
Metric name Type Monitoring Level
Description
Queue Manager Cluster metrics 145
User Guide
% Variation = ((curreqdepth - aveqdepth) / aveqdepth) * 100
Note that when the current queue depth is below average, the Queue Depth Variance is a negative number.
For example: a multi-instance cluster queue runs on three Queue Managers— QM1, QM2 and QM3—with the following current queue depths:
QM1 = 100
QM2 = 140
QM3 = 0
The average queue depth for all three Queue Managers would be calculated:
((100 + 140 + 0) / 3)= 80
% Queue Depth Variance for QM1:
((100 – 80) / 80) * 100 = 25
% Queue Depth Variance for QM2:
((140 – 80) / 80) * 100 = 75
% Queue Depth Variance for QM3:
((0 – 80) / 80) * 100 = -100
So QM1 deviation is only 25% from the average, while QM3 is -100% (negative 100 percent), correctly indicating a problem with QM3.
146 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Queue Manager metricsThe Investigator displays Queue Manager metrics in a tree with these nodes:
The tree has the following high-level structure:
Queue ManagersAggregated status metrics across all hostsHost name
Aggregated status metrics for all Queue Managers on the hostQueue Manager name
Aggregate status metrics for the Queue ManagerChannel Initiator (z/OS only)ChannelsConfiguration PropertiesDead Letter QueueLast CheckLogs (z/OS only)QueuesStatusUsage (z/OS only)
» Note The Investigator displays aggregated status metrics across hosts, all Queue Managers, and for all queues on a Queue Manager.
Queue Manager metrics 147
User Guide
Top level Queue Manager aggregated metrics
Aggregated status metrics across all hosts
The Investigator displays the following aggregated status metrics for all hosts
reporting WebSphere MQ metrics:
Metric name Type Description
Aggregated Agent-MQ Connection Status
Mapped Value Indicates the aggregated connection status of PowerPackNameShort with all the Queue Managers.
0 or green = successful
1 or red = unsuccessful
Aggregated Page Set Status (z/OS only)
Mapped Value Indicates the aggregated status of the page sets. One of:
0 or green = all the page sets are running
1 or red = one or more page sets have stopped
Aggregated Queue Manager Status
Mapped Value Indicates the aggregated status of the Queue Managers. One of:
0 or green = all the Queue Managers are running
1 or red = one or more Queue Managers have stopped
Maximum Queue Depth Reached
Mapped Value Indicates whether the maximum queue depth has been reached for any of the queues on this Queue Manager.
0 = no queue has reached the maximum queue depth
1 = one or more queues have reached the maximum queue depth.
Aggregated status metrics for all Queue Managers on a host
The Investigator displays the following aggregated status metrics for all the
Queue Managers on a host:
Metric name Type Description
Aggregated Agent-MQ Connection Status
Mapped Value Indicates the aggregated connection status of PowerPackNameShort with all the Queue Managers.
0 or green = successful
1 or red = unsuccessful
Aggregated Page Set Status (z/OS only)
Mapped Value Indicates the aggregated status of the page sets. One of:
0 or green = all the page sets are running
1 or red = one or more page sets have stopped
148 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Aggregated status metrics for each Queue Manager
The Investigator displays the following aggregated status metrics for all the
queues managed by each Queue Manager:
Metric name Type Description
Aggregated Agent-MQ Connection Status
Mapped Value Indicates the aggregated connection status of PowerPackNameShort with all the Queue Managers.
0 or green = successful
1 or red = unsuccessful
Maximum Queue Depth Reached
Mapped Value Indicates whether the maximum queue depth has been reached for any of the queues.
0 = no queue has reached the maximum queue depth
1 = one or more queues have reached the maximum queue depth
Aggregated Page Set Status (z/OS only)
Mapped Value Indicates the aggregated status of the page sets. One of:
0 or green = all the page sets are running
1 or red = one or more page sets have stopped
Queue Manager Status Mapped Value Indicates whether any of the Queue Managers is running or stopped.
0 = running
1 = stopped
Channel metrics
For each of the channels configured by an administrator on a Queue Manager, the metrics are divided into two groups:
Configuration Properties
Status
Aggregated Queue Manager Status
Mapped Value Indicates the aggregated status of the Queue Managers. One of:
0 or green = all the Queue Managers are running
1 or red = one or more Queue Managers have stopped
Maximum Queue Depth Reached
Mapped Value Indicates whether the maximum queue depth has been reached for any of the queues on the Queue Manager.
0 =no queue has reached the maximum queue depth
1 = one or more queues have reached the maximum queue depth
Metric name Type Description
Queue Manager metrics 149
User Guide
Configuration Properties metrics
Metric name Type Monitoring Level
Description
Channel Disposition
Mapped Value F Specifies how channels are resolved.
4 = MQCHLD_PRIVATEA receiving channel is private if it was started in response to an inbound transmission directed to the Queue Manager.A sending channel is private if its transmission queue has a disposition other than MQQSGD_SHARED.
2 = MQCHLD_SHAREDA receiving channel is shared if it was started in response to an inbound transmission directed to the queue-sharing group.A sending channel is shared if its transmission queue has a disposition of MQQSGD_SHARED.
Channel Name String R Name of the channel.
Channel Type Mapped Value R Specifies the channel type, one of the following:
1 = MQCHT_SENDER—Sender channel
2 = MQCHT_SERVER—Server channel
3 = MQCHT_RECEIVER—Receiver channel
4 = MQCHT_REQUESTER—Requester channel
5 = MQCHT_ALL—All the channel types are selected.
6 = MQCHT_CLNTCONN—Client connection channel
7 = MQCHT_SVRCONN—Server connection channel
8 = MQCHT_CLUSRCVR—Cluster receiver channel
9 = MQCHT_CLUSSDR—Cluster sender channel
Cluster Name String
Dynamic
F Name of the cluster to which the channel belongs.
Cluster Namelist String
Dynamic
F Identifies a namelist object that contains the names of clusters to which this channel belongs.
Connection Name
String R Internet address of a live connection; if not live, the contents of the ConnectionName field in the channel definition.
Heartbeat Interval
Number F The time, in seconds, between heartbeat flows passed from the sending MCA when there are no messages on the transmission queue.
Keep Alive Interval
Number F Keep alive interval (in seconds).
150 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Max Message Length
Number R Maximum permitted message length.
Non Persistent Message Speed
Mapped Value F Speed of nonpersistent messages. One of:
1 = MQNPMS_NORMAL—Normal speed.
2 = MQNPMS_FAST—Fast speed.
Queue Manager Name
String R Name of the Queue Manager.
Remote Queue Manager
String R Name of the remote Queue Manager.
SSL Certificate User ID (z/OS only)
String F User ID associated with the remote SSL certificate.
Transmission Queue Name
String F Name of the Transmission Queue.
SSL Client Authentication
Integer R Indicates whether the SSL server requires the SSL client to send its digital certificate for authentication. The value can be :
MQSCA_REQUIRED - Client authentication required MQSCA_OPTIONAL - Client authentication is optional
SSL Cipher Spec String R The CipherSpec for the channel to use. SSLCIPH parameter is mandatory if you want your channel to use SSL.
SSL Peer Name String R The Distinguished Name patterns that WebSphere MQ uses to decide the entities from which messages are accepted. The SSLPEER pattern filters the Distinguished Names of the entities.
SSL Short Peer Name
String F The Distinguished Name (DN) of the remote certificate
SSL Certificate Issuer Name
String R Represents the full Distinguished Name (DN) of the remote certificate issuer. The ″issuer″ is the Certification Authority (CA) that issued the certificate.
SSL Crypto Hardware
String F Sets a Queue Manager attribute, SSLCryptoHardware, which holds the name of the parameter string required to configure the cryptographic hardware present on the system. This parameter applies only to Windows and UNIX Queue Managers.
Metric name Type Monitoring Level
Description
Queue Manager metrics 151
User Guide
Status metrics
SSL Key Repository
String R Sets a Queue Manager attribute, SSLKeyRepository, which holds the name of the SSL key repository.
SSL Reset Count Long Counter R Sets a numeric Queue Manager attribute called SSLKeyResetCount, the total number of unencrypted bytes that are sent and received within an SSL conversation before the secret key is renegotiated. The number of bytes includes control information sent by the message channel agent.
Metric name Type Monitoring Level
Description
Batch Size Number M Maximum number of messages sent within a batch.
Batches Number
Dynamic
M Number of completed batches.
Buffers Received Number
Dynamic
M Number of buffers received.
Buffers Sent Number
Dynamic
M Number of buffers sent.
Bytes Received Number
Dynamic
M Number of bytes received.
Bytes Sent Number
Dynamic
M Number of bytes sent.
Channel Instance Counts
Mapped Value
Dynamic
M Number of instances of channels present currently.
Current Logical Unit Work ID
String F Logical unit-of-work identifier for current batch of messages.
Current Messages Number
Dynamic
M Number of messages in the current batch.
Current Sequence Number
Number F Sequence number of current message sent or received.
Indoubt Status Mapped Value
Dynamic
M Indicates whether the channel is currently in doubt. Applies only to a sending channel. Possible values:
0 = MQCHIDS_NOT_INDOUBT—Channel is not in doubt.
1 = MQCHIDS_INDOUBT—Channel is in doubt.
Metric name Type Monitoring Level
Description
152 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Last Logical Unit Work ID
String F Logical unit-of-work identifier for last batch of messages.
Last Message Date String
Dynamic
M Date on which the last message was sent.
Last Message Time String
Dynamic
M Time at which the last message was sent.
Last Sequence Number
Number F Sequence number of last message sent or received.
Long Retries Left Number M Number of long retry attempts remaining.
MCA Status Mapped Value
Dynamic
M MCA (message channel agent) status. One of:
0 = MQMCAS_STOPPED—Message channel agent stopped.
3 = MQMCAS_RUNNING—Message channel agent running.
Messages Number
Dynamic
M Number of messages.
Overall Channel Status
Mapped Value
Dynamic
M Status of the channel. One of:
0 = MQCHS_INACTIVE—Channel is not active.
1 = MQCHS_BINDING—Channel is negotiating with the partner.
2 = MQCHS_STARTING—Channel is waiting to become active.
3 = MQCHS_RUNNING—Channel is transferring or waiting for messages.
4 = MQCHS_STOPPING—Channel is in process of stopping.
5 = MQCHS_RETRYING—Channel is reattempting to establish connection.
6 = MQCHS_STOPPED—Channel is stopped.
7 = MQCHS_REQUESTING—Requester channel is requesting connection
8 = MQCHS_PAUSED—Channel is paused.
13 = MQCHS_INITIALIZING—Channel is initializing.
Short Retries Left Number M Number of short retry attempts remaining.
Metric name Type Monitoring Level
Description
Queue Manager metrics 153
User Guide
Configuration Properties metrics
Stop Requested Mapped Value M Whether a stop has been requested. One of:
0 = MQCHSR_STOP_NOT_REQUESTED—User stop request has not been received.
1 = MQCHSR_STOP_REQUESTED—User stop request has been received.
SSL Key Resets Long Counter
Dynamic
R Displays the number of SSL key resets successfully performed for this channel instance. The count of SSL key resets is reset when the channel instance is ended
SSL Key Reset Date String
Dynamic
R Displays the date when the last SSL secret key reset was successfully issued for this channel instance. The date of the last SSL secret key reset is reset when the channel instance is ended.
SSL Key Reset Time String
Dynamic
R Displays the time when the last SSL secret key reset was successfully issued for this channel instance. The time of the last SSL secret key reset is reset when the channel instance is ended.
Metric name Type Monitoring level
Description
Activity Recording Mapped Value
Dynamic
M Indicates whether activity reports can be generated. One of:
0 = MQRECORDING_DISABLED—Activity reports cannot be generated.
1 = MQRECORDING_Q—Activity reports can be generated and sent to SYSTEM.ADMIN.ACTIVITY.QUEUE.
2 = MQRECORDING_MSG—Activity reports can be generated and sent to the destination specified by the originator of the message causing the report.
Adopt New MCA Check (z/OS only)
Mapped Value F Identifies the MCA Check setting. One of:
0 = MQADOPT_CHECK_NONE—Do not check any elements.
1 = MQADOPT_CHECK_ALL—Check the Queue Manager name and network address. If possible, perform this check to protect your channels from being shut down, inadvertently or maliciously. This is the default value.
2 = MQADOPT_CHECK_Q_MGR_NAME—Check the Queue Manager name.
4 = QADOPT_CHECK_NET_ADDR—Check the network address.
Metric name Type Monitoring Level
Description
154 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Adopt New MCA Type (z/OS only)
Mapped Value F Whether an orphaned instance of an MCA should
be restarted automatically when a new inbound
channel request matching the AdoptNewMCACheck
parameter is detected. One of:
0 = MQADOPT_TYPE_NO: Do not adopt orphaned
channel instances.
1 = MQADOPT_TYPE_ALL: Adopt all channel types.
This is the Queue Manager’s initial default value.
Authority Events Mapped Value F Indicates Authorization Event enabled.
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
Auto Definition Events Generated
Mapped Value F Indicates Auto Definition Event enabled.
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
Bridge Events (z/OS only)
Mapped Value F Controls whether IMS Bridge events are generated. One of:
0 = MQEVR_DISABLED: Event reporting disabled. This is the default value
1 = MQEVR_ENABLED: Event reporting enabled.
Channel Auto Definition Exit
String F Channel automatic definition exit name.
Channel Initiator Adapters (z/OS only)
Number R Number of adapter subtasks to use for processing WebSphere MQ calls.
Channel Initiator Trace Auto Start (z/OS only)
Mapped Value R Whether the channel initiator trace should start automatically.One of:
0 = MQTRAXSTR_NO: Channel initiator trace is not to start automatically. This is the Queue Manager’s initial default value.
1 = MQTRAXSTR_YES: Channel initiator trace is to start automatically.
Channel Initiator Trace Table Size (z/OS only)
Number F Size, in megabytes, of the channel initiator’s trace data space.
Channels Using LU62 (z/OS only)
Number R The maximum number of channels that can be current, or clients that can be connected, that use the LU 6.2 transmission protocol.
Channels Using TCP (z/OS only)
Number R The maximum number of channels that can be current, or clients that can be connected, that use the TCP/IP transmission protocol.
Coded Character Set ID
Number F Coded character set identifier.
Metric name Type Monitoring level
Description
Queue Manager metrics 155
User Guide
Command Events (z/OS only)
Mapped Value F Controls whether command events are generated. One of:
0 = MQEVR_DISABLED: Event reporting disabled.
1 = MQEVR_ENABLED: Event reporting enabled.
3 = MQEVR_NO_DISPLAY: Event reporting enabled for all successful commands except Inquire commands.
Command Input Queue
String F Command input queue name.
Command Level Mapped Value R Command level supported by the Queue Manager. The Command Level refers to the system of control commands supported by WebSphere MQ. Possible values:
100 = MQCMDL_LEVEL_1
101 = MQCMDL_LEVEL_101
110 = MQCMDL_LEVEL_110
200 = MQCMDL_LEVEL_200
201 = MQCMDL_LEVEL_201
210 = MQCMDL_LEVEL_210
220 = MQCMDL_LEVEL_220
221 = MQCMDL_LEVEL_221
320 = MQCMDL_LEVEL_320
420 = MQCMDL_LEVEL_420
500 = MQCMDL_LEVEL_500—System for MQSeries v5.0
510 = MQCMDL_LEVEL_510—System for MQSeries v.5 release 1
520 = MQCMDL_LEVEL_520—System for MQSeries v.5 release 2
530 = MQCMDL_LEVEL_530—System for WebSphere MQ v.5 release 3
531 = MQCMDL_LEVEL_531
600 = MQCMDL_LEVEL_600—System for WebSphere MQ v6
700 = MQCMDL_LEVEL_700—System for WebSphere MQ v7
Configuration Events (z/OS only)
Mapped Value F Controls whether configuration events are generated.
0 = MQEVR_DISABLED: Event reporting disabled.
1 = MQEVR_ENABLED: Event reporting enabled.
Dead Letter Queue String F Indicates the Dead Letter Queue of the Queue Manager.
Metric name Type Monitoring level
Description
156 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Default Transmission Queue
String R Indicates the default transmission queue of the Queue Manager
Description String R Description of the Queue Manager.
Distribution Lists Mapped Value F Indicates Distribution List enabled.
0 = MQDL_NOT_SUPPORTED—Distribution lists not supported.
1 = MQDL_SUPPORTED—Distribution lists supported.
DNS Group Name (z/OS only)
String F The name of the group that the TCP listener handling inbound transmissions for the queue-sharing group should join when using Workload Manager for Dynamic Domain Name Services support (DDNS).
Expiry Interval (z/OS only)
Number F Frequency with which the Queue Manager scans the queues looking for expired messages.
Metric name Type Monitoring level
Description
Queue Manager metrics 157
User Guide
IGQ Authority Check Type (z/OS only)
Mapped Value F Type of authority checking and, therefore, the user IDs to be used by the IGQ agent (IGQA). This establishes the authority to put messages to a destination queue. Acceptable values:
1 = MQIGQPA_DEFAULT: Default user identifier is used. The user identifier used for authorization is the value of the UserIdentifier field in the separate MQMD that is associated with the message when the message is on the shared transmission queue. This is the user identifier of the program that placed the message on the shared transmission queue, and is usually the same as the user identifier under which the remote Queue Manager is running. If the RESLEVEL profile indicates that more than one user identifier is to be checked, the user identifier of the local IGQ agent (IGQUserId) is also checked.
2 = MQIGQPA_CONTEXT: Context user identifier is used. The user identifier used for authorization is the value of the UserIdentifier field in the separate MQMD that is associated with the message when the message is on the shared transmission queue. This is the user identifier of the program that placed the message on the shared transmission queue, and is usually the same as the user identifier under which the remote Queue Manager is running. If the RESLEVEL profile indicates that more than one user identifier is to be checked, the user identifier of the local IGQ agent (IGQUserId) and the value of the UserIdentifier field in the embedded MQMD are also checked. The latter user identifier is usually the user identifier of the application that originated the message.
3 = MQIGQPA_ONLY_IGQ: Only the IGQ user identifier is used. The user identifier used for authorization is the user identifier of the local IGQ agent (IGQUserId). If the RESLEVEL profile indicates that more than one user identifier is to be checked, this user identifier is used for all checks.
4 = MQIGQPA_ALTERNATE_OR_IGQ: Alternate user identifier or IGQ-agent user identifier is used. The user identifier used for authorization is the user identifier of the local IGQ agent (IGQUserId). If the RESLEVEL profile indicates that more than one user identifier is to be checked, the value of the UserIdentifier field in the embedded MQMD is also checked. This user identifier is usually the user identifier of the application that originated the message.
Metric name Type Monitoring level
Description
158 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
IGQ User ID (z/OS only)
String F User identifier used by the intra-group queuing agent.
Inhibit Events Mapped Value F Indicates Inhibit Event enabled.
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
Intra-Group Queuing (z/OS only)
Mapped Value R Specifies whether intra-group queuing is used. Acceptable values:
0 = MQIGQ_DISABLED: Intra-group queuing disabled.
1 = MQIGQ_ENABLED: Intra-group queuing enabled.
Listener Timer (z/OS only)
Number F The time interval, in seconds, between attempts by WebSphere MQ to restart the listener after an APPC or TCP/IP failure.
Local Events Mapped Value F Indicates Local Error Event enabled.
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
LU Group Name (z/OS only)
String F The generic LU name to be used by the LU 6.2 listener that handles inbound transmissions for the queue-sharing group.
LU Name (z/OS only) String F The name of the LU to use for outbound LU 6.2 transmissions.
LU62 Member Name Suffix (z/OS only)
String F Member Name Suffix. The suffix of the APPCPM member of SYS1.PARMLIB. This suffix nominates the LUADD for this channel initiator.
Max Handles Number R Specifies the maximum number of handles that any one job can have open at the same time.
Max Message Length Number R Maximum permitted message length.
Max Priority Number F Maximum priority supported.
Maximum Channels (z/OS only)
Number R Maximum number of channels that can be current.
Maximum Outbound Port (z/OS only)
Number F Maximum value in the range for the binding of outgoing channels.
Metric name Type Monitoring level
Description
Queue Manager metrics 159
User Guide
Maximum Uncommitted Messages
Number R Maximum number of uncommitted messages within a unit of work. Calculated as:
The number of messages that can be retrieved + The number of messages that can be put on a queue + Any trigger messages generated within this unit of work under any one syncpoint.
This limit does not apply to messages that are retrieved or put outside syncpoint.
Minimum Outbound Port (z/OS only)
Number F Minimum value in the range for the binding of outgoing channels.
Minimum Receive Timeout (z/OS only)
Number R The minimum length of time that a TCP/IP channel waits to receive data, including heartbeats, from its partner before returning to the inactive state.
Performance Events Mapped Value R Whether or not Performance Events are enabled.
0 = MQEVR_DISABLED—Event reporting disabled. No queue reached maximum queue depth.
1 = MQEVR_ENABLED—Event reporting enabled.
2 = MQEVR_EXCEPTION—Performance event exception.
Platform Mapped Value R Platform on which the Queue Manager resides. One of:
1 = MQPL_ZOS—z/OS
3 = MQPL_AIX—AIX (same value as MQPL_UNIX).
3= MQPL_UNIX—UNIX systems.
4 = MQPL_OS400—i5/OS.
12 = MQPL_VMS—HP OpenVMS.
11 = MQPL_WINDOWS_NT—Windows.
13 = MQPL_NSK—Compaq NonStop Kernel.
QMID String F Unique Queue Manager Identifier.
Queue Manager Name
String R Name of the Queue Manager.
Queue-Sharing Group Name (z/OS only)
String R Name of the queue sharing group
Receive Timeout (z/OS only)
Number R How long a TCP/IP channel waits to receive data from its partner.
Metric name Type Monitoring level
Description
160 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Receive Timeout Type (z/OS only)
Mapped Value R The qualifier to apply to ReceiveTimeoutType to calculate how long a TCP/IP channel waits to receive data, including heartbeats, from its partner before returning to the inactive state.
0 = MQRCVTIME_MULTIPLY: The ReceiveTimeout value is a multiplier to be applied to the negotiated value of HeartbeatInterval to determine how long a channel waits. This is the Queue Manager’s initial default value.
1 = MQRCVTIME_ADD: ReceiveTimeout is a value, in seconds, to be added to the negotiated value of HeartbeatInterval to determine how long a channel waits.
2 = MQRCVTIME_EQUAL: ReceiveTimeout is a value, in seconds, representing how long a channel waits.
Receiver Server-Connection Channels Auto-Defined
Mapped Value F Indicates CHAD enabled.
0 = MQCHAD_DISABLED—Event reporting disabled.
1 = MQCHAD_ENABLED—Event reporting enabled.
Remote Events Mapped Value F Indicates Remote Error Event enabled.
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
Repository Name String F The name of a cluster for which this Queue Manager is to provide a repository service.
Repository Name List String F The name of a list of clusters for which this Queue Manager is to provide a repository service.
Shared Queue Manager Name (z/OS only)
Mapped Value R Shared-queue Queue Manager name. When a Queue Manager makes an MQOPEN call for a shared queue and the Queue Manager that is specified in the ObjectQmgrName parameter of the MQOPEN call is in the same queue-sharing group as the processing Queue Manager, the SQQMNAME attribute specifies whether the ObjectQmgrName is used or whether the processing Queue Manager opens the shared queue directly. Acceptable values:
0 = MQSQQM_USE: ObjectQmgrName is used and the appropriate transmission queue is opened.
1 = MQSQQM_IGNORE: The processing Queue Manager opens the shared queue directly. This can reduce the traffic in your Queue Manager network.
Metric name Type Monitoring level
Description
Queue Manager metrics 161
User Guide
SSL Event Mapped Value R Indicates whether or not SSL Events are enabled.
1 = MQEVR_ENABLED
0 = MQEVR_DISABLED
SSL Key Repository String R Sets a Queue Manager attribute, SSLKeyRepository, which holds the name of the SSL key repository.
SSL CRL Name List String F Sets a Queue Manager attribute that holds the namelist of authentication information objects.
SSL Crypto Hardware String F Sets a Queue Manager attribute, SSLCryptoHardware, which holds the name of the parameter string required to configure the cryptographic hardware present on the system. This parameter applies only to Windows and UNIX Queue Managers.
SSL Reset Count Long Counter R Sets a numeric Queue Manager attribute called
SSLKeyResetCount, the total number of unencrypted bytes that are sent and received within an SSL conversation before the secret key is renegotiated. The number of bytes includes control information sent by the message channel agent.
SSL FIPS Required Integer F The value can be:
0 = MQSSL_FIPS_NO - Any supported CipherSpec can be used.
1 = MQSSL_FIPS_YES - Only FIPS-certified cryptographic algorithms must be used.
SSL Task (z/OS only) Number F Number of server subtasks to use for processing SSL calls.
Start And Stop Events
Mapped Value R Indicates whether or not Start and Stop Events are enabled.
1 = MQEVR_ENABLED
0 = MQEVR_DISABLED
Sync Point Mapped Value F Indicates whether Syncpoint is available.
0 = MQSP_NOT_AVAILABLE—Units of work and syncpointing not available.
1 = MQSP_AVAILABLE—Units of work and syncpointing available.
Metric name Type Monitoring level
Description
162 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Dead Letter Queue metrics
The Dead Letter Queue node can contain all the metrics that appear under a regular queue. See the lists under Queue metrics on page 164.
TCP Keep Alive (z/OS only)
Mapped Value F Indicates whether the TCP KEEPALIVE facility is to be used to check whether the other end of a connection is still available. One of:
0 = MQTCPKEEP_NO—The TCP KEEPALIVE Facility is not to be used. This is the Queue Manager’s initial default value.
1 = MQTCPKEEP_YES—The TCP KEEPALIVE Facility is to be used as specified in the TCP profile configuration data set. The interval is specified in the KeepAliveInterval channel attribute
TCP Name (z/OS only)
String F Name of the TCP/IP system that you are using.
TCP Stack Type (z/OS only)
Mapped Value F Indicates whether the channel initiator may use only the TCP/IP address space specified in TCPName, or may optionally bind to any selected TCP/IP address. Acceptable values:
0 = MQTCPSTACK_SINGLE—The channel initiator may only use the TCP/IP address space specified in TCPName. This is the Queue Manager’s initial default value.
1 = MQTCPSTACK_MULTIPLE—The channel initiator may use any TCP/IP address space available to it. It defaults to the one specified in TCPName if no other is specified for a channel or listener.
Trigger Interval Number F Trigger interval, expressed in milliseconds, for use only with queues where TriggerType has a value of MQTT_FIRST.
Workload Manager Register Status (z/OS only)
Mapped Value F Indicates whether the TCP listener that handles inbound transmissions for the queue-sharing group should register with Workload Manager (WLM) for DDNS.
0 = MQDNSWLM_NO—The listener is not to register with WLM. This is the Queue Manager’s initial default value.
1 = MQDNSWLM_YES—The listener should register with WLM.
Metric name Type Monitoring level
Description
Queue Manager metrics 163
User Guide
Last Check metrics
The Last Check metrics contain information about the last time the Queue
Manager was queried.
Metric name Type Monitoring Level
Description
Description String M Queue Manager description.
Queue Manager Name String M Queue Manager name.
Agent-MQ Connection Status
String M Indicates whether or not PowerPackNameShort can successfully connect to the Queue Managers.
0 or green = successful
1 or red = unsuccessful
Timestamp String M Indicates the system timestamp of Agent-MQ Connection Status.
164 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Queue metrics
Configuration Properties metrics
Metric name Type Monitoring Level
Description
Back Out Requeue Queue
String F Name of the queue used for re-queueing messages that were backed out.
Back Out Threshold
Number R The number of times a message can be backed out before it is transferred to the backout queue specified in MQCA_BACKOUT_REQ_Q_NAME.
Base Queue String M Queue name to which the alias resolves.
Cluster Name String F Name of the cluster to which the queue belongs.
Cluster Namelist String F Identifies a namelist object that contains the names of clusters to which this queue belongs.
Coupling Facility Name (z/OS only)
String F The name of the coupling facility where messages on the queue are stored.
Creation Date String F Queue creation date.
Creation Time String F Queue creation time.
Default Bind Type Mapped Value F Describes binding mechanism. One of:
0 = MQBND_BIND_ON_OPEN—Binding fixed by MQOPEN call.
1 = MQBND_BIND_NOT_FIXED—Binding not fixed by MQOPEN call.
Default Priority Number F Default priorities for messages on the queue. Can be any number from 0 to MQIA_MAX_PRIORITY.
Definition Type Mapped Value R Queue definition type.
1 = MQQDT_PREDEFINED—Predefined permanent queue.
2 = MQQDT_PERMANENT_DYNAMIC—Dynamically defined permanent queue.
3 = MQQDT_TEMPORARY_DYNAMIC—Dynamically defined temporary queue.
4 = MQQDT_SHARED_DYNAMIC
Description String R Description of the queue.
Distribution Lists Mapped Value F 0 = MQDL_NOT_SUPPORTED—Distribution lists not supported.
1 = MQDL_SUPPORTED—Distribution lists supported.
Queue Manager metrics 165
User Guide
Get Messages Mapped Value M Get operations allowed or inhibited.
0 = MQQA_GET_ALLOWED—Get operations are allowed.
1 = MQQA_GET_INHIBITED—Get operations are inhibited.
Harden Get Backout
Mapped Value F Indicates whether backout count is tracked.
0 = MQQA_BACKOUT_NOT_HARDENED—Backout count may not be remembered.
1 = MQQA_BACKOUT_HARDENED—Backout count remembered.
Index Type (z/OS only)
Mapped Value F Specifies the type of index maintained by the Queue Manager to expedite MQGET operations on the queue.
The value can be:
0 = MQIT_NONE—No index.
1 = MQIT_MSG_ID—The queue is indexed using message identifiers.
2 = MQIT_CORREL_ID—The queue is indexed using correlation identifiers.
3 = MQIT_MSG_TOKEN—The queue is indexed using message tokens.
4 = MQIT_GROUP_ID—The queue is indexed using group identifiers.
Initiation Queue String F Name of the initiation queue.
Max Message Length
Number R Maximum message length.
Max Queue Depth Number
Dynamic
M Maximum number of messages allowed on queue.
Message Delivery Sequence
Mapped Value F Message delivery sequence.
0 = MQMDS_PRIORITY—if priority is relevant
1 = MQMDS_FIFO—first-in, first-out
Persistence Mapped Value F Default persistence of messages on the queue. One of:
1 = MQPER_PERSISTENT—The message survives system failures and Queue Manager restarts.
0 = MQPER_NOT_PERSISTENT—The message does not normally survive system failures or Queue Manager restarts.
Both persistent and nonpersistent messages can exist on the same queue.
Process Name String F Name of the process.
Metric name Type Monitoring Level
Description
166 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Put Messages Mapped Value M Put operations allowed or inhibited.
0 = MQQA_PUT_ALLOWED—Put operations are allowed.
1 = MQQA_PUT_INHIBITED—Put operations are inhibited.
QSG Disposition (z/OS only)
Mapped Value
Dynamic
F Specifies the disposition of the process definition. One of:
-1 (minus 1) = MQQSGD_ALL—The object is defined as MQQSGD_Q_MGR or MQQSGD_COPY. If there is a shared Queue Manager environment, and the command is being executed on the Queue Manager where it was issued, this option also displays information for objects defined with MQQSGD_GROUP. If MQQSGD_LIVE is specified or defaulted, or if MQQSGD_ALL is specified in a shared Queue Manager environment, the command might give duplicated names (with different dispositions).
0 = MQQSGD_Q_MGR—The object has queue-manager disposition: the object definition is known only to the local Queue Manager; the definition is not known to other Queue Managers in the queue-sharing group.
1 = MQQSGD_COPY—The object is a local copy of a master object definition that exists in the shared repository. Each Queue Manager in the queue-sharing group can have its own copy of the object.
2 = MQQSGD_SHARED—The object has shared disposition. This means that there exists in the shared repository a single instance of the object that is known to all Queue Managers in the queue-sharing group. When a Queue Manager in the group accesses the object, it accesses the single shared instance of the object.
3 = MQQSGD_GROUP—The object definition resides in the shared repository. The object was defined using a command that had the parameter MQQSGD_GROUP.
4 = MQQSGD_PRIVATE—Clear the private queue named in QName. The queue is private if it was created using a command with the attributes MQQSGD_PRIVATE or MQQSGD_Q_MGR. This is the default value.
6 = MQQSGD_LIVE—The object is defined as MQQSGD_Q_MGR or MQQSGD_COPY. This is the default value if the parameter is not specified.
Metric name Type Monitoring Level
Description
Queue Manager metrics 167
User Guide
Queue Default Input Open Option
Mapped Value F Default input open option for defining whether queues can be shared. One of:
2 = MQOO_INPUT_SHARED - Open queue to get messages with shared access.
4 = MQOO_INPUT_EXCLUSIVE - Open queue to get messages with exclusive access.
Queue Depth High Events
Mapped Value F Enables Queue Depth High events.
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
Queue Depth High Limit
Number F Threshold against which the queue depth is compared to generate a Queue Depth High event, expressed as a percentage of the maximum queue depth.
Queue Depth Low Events
Mapped Value F Enables Queue Depth Low events. One of:
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
Queue Depth Low Limit
Number F Threshold against which the queue depth is compared to generate a Queue Depth Low event, expressed as a percentage of the maximum queue depth.
Queue Full Events Generated
Mapped Value F Enables Queue Full events. One of:
0 = MQEVR_DISABLED—Event reporting disabled.
1 = MQEVR_ENABLED—Event reporting enabled.
Queue Name String R Name of the queue.
Queue Service Interval
Number F Target queue service interval.
The service interval used for comparison to generate Queue Service Interval
High and Queue Service Interval OK events.
Queue Service Interval Events
Mapped Value F Indicates whether queue service interval events are enabled.
0 = MQQSIE_NONE—No queue service interval events enabled.
1 = MQQSIE_HIGH—Queue Service Interval High events enabled.
2 = MQQSIE_OK—Queue Service Interval OK events enabled.
Queue Type Mapped Value M Queue Type.
1 = MQQT_LOCAL—local queue.
2 = MQQT_MODEL—model queue definition
3 = MQQT_ALIAS—alias queue definition
7 = MQQT_CLUSTER—cluster queue definition
6 = MQQT_REMOTE—local definition of a remote queue.
Metric name Type Monitoring Level
Description
168 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Remote Queue String M Name of the remote queue as known locally on the remote Queue Manager.
Remote Queue Manager
String M Name of the remote Queue Manager.
Retention Interval Number F Period of time (in hours, beginning from creation time of the queue) to retain the queue, after which the queue is eligible for deletion.
Scope Mapped Value F Scope of the queue definition.
1 = MQSCO_Q_MGR—Queue-manager scope.
2 = MQSCO_CELL—Cell scope.
Shareability Mapped Value F Indicates whether queue can be shared or is opened for exclusive use.
0 = MQQA_NOT_SHAREABLE—Queue is not shareable.
1 = MQQA_SHAREABLE—Queue is shareable.
Storage Class Name (z/OS only)
String F Name of the storage class.
Transmission Queue
String R Transmission queue name.
Trigger Control Mapped Value F Trigger control.
0 = MQTC_OFF
1 = MQTC_ON
Trigger Data String F Data or message which the Queue Manager inserts into a trigger message when a message arriving on this queue causes a trigger message to be written to the initiation queue.
Trigger Depth Number F Number of messages of a certain priority (TriggerMsgPriority) or greater which must be on the queue before a trigger message can be written. Must be 1 or greater.
Trigger Message Priority
Number F Trigger threshold based on message priority.
Metric name Type Monitoring Level
Description
Queue Manager metrics 169
User Guide
Status metrics
In order to see data for Oldest Message and Queue Time metrics, Queue Monitoring must be enabled in WebSphere MQ. See Turn on Queue Monitoring on page 66.
Trigger Type Mapped Value F Trigger type.
0 = MQTT_NONE—No trigger messages.
1 = MQTT_FIRST—Trigger message when queue depth goes from 0 to 1.
2 = MQTT_EVERY—Trigger message for every message.
3 = MQTT_DEPTH—Trigger message when depth threshold exceeded.
Usage Mapped Value M 0 = MQUS_NORMAL—Normal usage.
1 = MQUS_TRANSMISSION—Transmission queue.
Metric name Type Monitoring Level
Description
Metric name Type Monitoring Level
Description
Alteration Date String
Dynamic
M Date when properties were last altered.
Alteration Time String
Dynamic
M Time when properties were last altered.
Current Queue Depth Number
Dynamic
M Number of messages on queue.
Current Queue Depth Percentage (% Queue Full)
Number
Dynamic
M Percentage of fullness of the queue.
Dequeue Count Interval Count
Dynamic
R Number of messages removed from the queue.
Dequeue Count Per 6 Hours
Number
Dynamic
R Running count of the number of message dequeues in the last six hours.
Dequeue Count Per Day
Number
Dynamic
R Running count of the number of message dequeues in the last day.
Dequeue Count Per Hour
Number
Dynamic
R Running count of the number of message dequeues in the last hour.
Dequeue Count Per Minute
Number
Dynamic
R Running count of the number of message dequeues in the last minute.
170 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Enqueue Count Interval Count
Dynamic
R Number of messages added to the queue, including messages that have been put to the queue, but have not yet been committed.
Enqueue Count Per 6 Hours
Number
Dynamic
R Running count of the number of message enqueues in the last six hours.
Enqueue Count Per Day
Number
Dynamic
R Running count of the number of message enqueues in the last day.
Enqueue Count Per Hour
Number
Dynamic
R Running count of the number of message enqueues in the last hour.
Enqueue Count Per Minute
Number
Dynamic
R Running count of the number of message enqueues in the last minute.
Last Get Date String
Dynamic
M Date of last Get command.
Last Get Time String
Dynamic
M Time of last Get command.
Last Put Date String
Dynamic
M Date of last Put command.
Last Put Time String
Dynamic
M Time of last Put command.
Media Recovery Log Extent Name
String
Dynamic
F Name of the earliest log extent required to perform media recovery.
Oldest Message Age (sec)
Number
Dynamic
M Age of the oldest message on the queue, in seconds.
Oldest Message Age Per 6 Hours (sec)
Number
Dynamic
M Running maximum oldest message age over the last six hours.
Oldest Message Age Per Day (sec)
Number
Dynamic
M Running maximum oldest message age over the last day.
Oldest Message Age Per Hour (sec)
Number
Dynamic
M Running maximum oldest message age over the last hour.
Open Input Count Number
Dynamic
M Number of handles that are currently valid for removing messages from the queue.
Open Output Count Number
Dynamic
M Number of handles that are currently valid for adding messages to the queue
Metric name Type Monitoring Level
Description
Queue Manager metrics 171
User Guide
Queue Monitoring Mapped Value
Dynamic
F Queue monitoring level. Possible values:
-3 = MQMON_Q_MGR—Collect monitoring data according to the setting of the QueueMonitoring Queue Manager attribute. This is the default value.
0 = MQMON_OFF—Online monitoring data collection is turned off for this queue.
17 = MQMON_LOW—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a low rate of data collection for this queue.
33 = MQMON_MEDIUM—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a moderate rate of data collection for this queue.
65 = MQMON_HIGH—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a high rate of data collection for this queue.
Queue Time (Long Term Avg.)
Number M Average time, in milliseconds, that a message spent on the queue, based on activity over a longer period.
Compare with Queue Time (Short Term Avg.)
Queue Time (Short Term Avg.)
Number M Average time, in milliseconds, that a message spent on the queue, based on activity over a shorter period.
Compare with Queue Time (Long Term Avg.)
Uncommitted Messages
Number
Dynamic
M Number of uncommitted messages.
Metric name Type Monitoring Level
Description
172 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Channel Initiator metrics
Channel Initiator metrics are reported for Queue Managers running on z/OS hosts only.
Configuration settings
Metric name Type Monitoring Level
Description
Active Adapters Requested
Number R The requested number of adapter subtasks.
Active Channel Connections Requested
Number R The requested number of active channel connections.
Active Dispatchers Requested
Number R The requested number of dispatchers.
Active SSL Tasks Requested
Number R The requested number of SSL server subtasks.
Channel Connections Requested
Number R The requested number of channel connections.
Current LU6.2 Channels
Number R The number of current LU 6.2 channel connections.
Current TCP/IP Channels
Number R The number of current TCP/IP channel connections.
TCP System Name String F TCP system name.
Status metrics
Metric name Type Monitoring Level
Description
Active Adapters Number
Dynamic
R The number of active adapter subtasks.
Active Channel Connections
Number
Dynamic
M The number of active channel connections.
Active Channels Paused
Number
Dynamic
R The number of active channel connections that have paused, waiting to become active, because the limit for active channels has been reached.
Active Channels Retrying
Number
Dynamic
R The number of active channel connections that are attempting to reconnect following a temporary error.
Queue Manager metrics 173
User Guide
Active Channels Started
Number
Dynamic
R The number of active channel connections that have started.
Active Channels Stopped
Number
Dynamic
M The number of active channel connections that have stopped, requiring manual intervention.
Active Dispatchers Number
Dynamic
R The number of active dispatchers.
Active SSL Tasks Number
Dynamic
R The number of active SSL server subtasks.
Channel Initiator Status
Mapped Value
Dynamic
M Status of the channel initiator. One of:
0 = MQSVC_STATUS_STOPPED or Unknown—stopped/unknown.
1 = MQSVC_STATUS_STARTING—starting.
2 = MQSVC_STATUS_RUNNING—running.
3 = MQSVC_STATUS_STOPPING—stopping.
4 = MQSVC_STATUS_RETRYING—retrying.
Current Channel Connections
Number
Dynamic
M The number of current channel connections.
Metric name Type Monitoring Level
Description
174 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Log metrics
Log metrics are reported for Queue Managers running on z/OS hosts only.
For each of the logs configured by an administrator on a Queue Manager, the metrics are divided into three groups—Configuration Properties, Log Copy Records, Status. The following illustration shows the Log metrics:
Configuration Properties metrics
Metric name Type Monitoring Level
Description
Archive Status Mapped Value R Specifies whether archiving is on or off. One of:
0 = No—no archiving.
1 = Yes—archiving is on.
Deallocation Interval
Number R Specifies the length of time, in minutes, that an allocated archive read tape unit is allowed to remain unused before it is deallocated.
The value can be in the range zero through 1440. If it is zero, the tape unit is deallocated immediately. If it is 1440, the tape unit is never deallocated.
Queue Manager metrics 175
User Guide
Dual Archive Logging
Mapped Value R Specifies whether dual archive logging is being used. One of:
0 = No—no dual archive archiving.
1 = Yes—dual archive logging is on.
Dual BSDS Logging Mapped Value R Specifies whether dual BSDS is being used. One of:
0 = No—no dual BSDS.
1 = Yes—dual BSDS is on.
Dual Logging Mapped Value R Specifies whether dual logging is being used. One of:
0 = No—no dual logging.
1 = Yes—dual logging is on.
Input Buffer Size Number R Specifies the size of input buffer storage for active and archive log data sets.
Log Suspend Status Mapped Value R Specifies whether logging is suspended. One of:
0 = No—log is not suspended.
1 = Yes—log has been suspended.
Maximum Archive Log
Number R Specifies the maximum number of archive log volumes that can be recorded in the BSDS.
Maximum Tape Units
Number R Specifies the maximum number of dedicated tape units that can be allocated to read archive log tape volumes.
Output Buffer Count
Number R Specifies the number of output buffers to be filled before they are written to the active log data sets.
Output Buffer Size Number R Size of output buffer storage for active and archive log data sets.
Parameter Type Mapped Value R Specifies how the parameters are to be reset. One of:
10 = MQSYSP_TYPE_INITIAL—The initial settings of the log parameters.
11 = MQSYSP_TYPE_SET—The settings of the log parameters if they have been altered since
their initial setting.
12 = MQSYSP_TYPE_LOG_COPY—Information relating to the active log copy.
13 = MQSYSP_TYPE_LOG_STATUS—Information relating to the status of the logs.
Queue Manager Start Date
String R The date on which the Queue Manager was started, in the form yyyy-mm-dd.
Queue Manager Start Time
String R The time that the Queue Manager was started, in the form hh.mm.ss.
Metric name Type Monitoring Level
Description
176 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Log Copy Records
Metric name Type Monitoring Level
Description
Log Copy Number Number
Dynamic
M Copy number
Parameter Type Mapped Value M Specifies the type of archive information being returned.
Percent of Log Data Set Used
Number
Dynamic
M The percentage of the active log data set that has been used.
Status metrics
Metric name Type Monitoring Level
Description
Full Active Log Data Sets
Number
Dynamic
M The total number of full active log data sets that have not yet been archived.
Total Logs Number
Dynamic
M Total number of active log data sets.
Queue Manager metrics 177
User Guide
Usage metrics
Under the Usage node, you can see two sub-nodes:
Buffer Pools
For each of the buffer pools configured by an administrator on a Queue Manager, the metrics are divided into two groups:
Configuration Properties
Status
Page Sets
For each of the page sets configured by an administrator on a Queue Manager, the metrics are divided as follows:
one aggregated metric for all page set instances
Configuration Properties
Status
The following illustration shows the Usage node, containing Buffer Pools and Page Sets:
178 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Aggregated status metric
Metric name Type Description
Aggregated Page Set Status Mapped Value Indicates the aggregated status of the page sets. One of:
0 or green = all the page sets are running
1 or red = one or more page sets have stopped
s
Configuration Properties metrics
Metric name Type Monitoring level
Description
Buffer Pool ID Number R Buffer pool identifier.
Page Set Expand Count
Number R The number of times the page set has been dynamically expanded since restart.
Page Set Expand Type
Mapped Value R How the Queue Manager expands a page set when it becomes nearly full, and further pages are required within it. One of:
1 = MQUSAGE_EXPAND_USER—The secondary extent size that was specified when the page set was defined is used. If no secondary extent size was specified, or it was specified as zero, then no dynamic page set expansion can take place. At restart, if a previously used page set has been replaced with a data set that is smaller, it is expanded until it reaches the size of the previously used data set. Only one extent is required to reach this size.
2 = MQUSAGE_EXPAND_SYSTEM—A secondary extent size that is approximately 10 per cent of the current size of the page set.
3 = MQUSAGE_EXPAND_NONE—No further page set expansion is to take place.
Page Set ID Number R Page set identifier; a two digit number from 00 to 99.
Queue Manager Name
String R The name of the Queue Manager that generates responses.
Usage Type Mapped Value R The type of information to be returned. One of:
MQIACF_USAGE_PAGESET—Return page set and buffer pool information.
MQIACF_USAGE_DATA_SET—Return data set information for log data sets.
MQIACF_USAGE_ALL—Return page set and data set information.
Queue Manager metrics 179
User Guide
Status metrics
Metric name Type Monitoring Level
Description
Page Set Status Mapped Value
Dynamic
M Current status of the page set. One of:
0 = MQUSAGE_PS_AVAILABLE—The page set is available.
1 = MQUSAGE_PS_DEFINED—The page set has been defined but has never been used.
2 = MQUSAGE_PS_OFFLINE—The page set is currently not accessible by the Queue Manager, for example because the page set has not been defined to the Queue Manager.
3 = MQUSAGE_PS_NOT_DEFINED—The command was issued for a specific page set that is not defined to the Queue Manager.
Pages Holding Non Persistent Data
Number
Dynamic
M The number of pages holding non-persistent message data.
Pages Holding Persistent Data
Number
Dynamic
M The number of pages used to store object definitions and persistent message data.
Total Pages Number
Dynamic
M The total number of 4KB pages in the page set.
Unused Pages Number
Dynamic
M The number of pages that are not used and hence available.
180 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Queue Manager Status metrics
Metric name Type Monitoring Level
Description
Active Channels (z/OS only)
Number
Dynamic
M Number of active channels.
Alteration Date String
Dynamic
M Date when properties were last altered.
Alteration Time String
Dynamic
M Time when properties were last altered.
Channel Initiator Dispatchers (z/OS only)
Number
Dynamic
M Number of dispatchers.
Channel Initiator Status (not available on z/OS)
Mapped Value
Dynamic
M 0 = MQSVC_STATUS_STOPPED or unknown—Channel Initiator stopped/unknown.
1 = MQSVC_STATUS_STARTING—Channel Initiator starting up.
2 = MQSVC_STATUS_RUNNING—Channel Initiator running.
3 = MQSVC_STATUS_STOPPING—Channel Initiator shutting down.
4 = MQSVC_STATUS_RETRYING—Channel Initiator retrying.
Command Server Status (not available on z/OS)
Mapped Value
Dynamic
M One of:
2 = MQQMSTA_RUNNING—RUNNING.
0 = Unknown—UNKNOWN.
Connection Count (not available on z/OS)
Mapped Value
Dynamic
M Current number of connections to the Queue Manager.
Current Log Extent Name (not available on z/OS)
String
Dynamic
F The name of the log extent that was being written to at the time of the Inquire command. If the Queue Manager is using circular logging, this is blank.
Log Path (not available on z/OS)
String
Dynamic
F The location of the recovery log extents.
Media Recovery Log Extent Name (not available on z/OS)
String
Dynamic
F Name of the oldest log extent required by the Queue Manager to perform media recovery. This is available only on Queue Managers using linear logging. If the Queue Manager is using circular logging, this is blank.
Message Broker metrics 181
User Guide
Message Broker metricsThe Investigator displays Message Broker metrics in a tree with these nodes:
Queue Manager Status
Mapped Value
Dynamic
M The current status of the Queue Manager. One of:
0 = Unknown
2 = MQQMSTA_RUNNING
Restart Recovery Log Extent Name (not available on z/OS)
String
Dynamic
F Name of the oldest log extent required by the Queue Manager to perform restart recovery. This is available only on Queue Managers using linear logging. If the Queue Manager is using circular logging, this is blank.
182 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
For each Message Broker that you configure to send metrics to Introscope, you can view the following:
Broker properties
Metrics for each execution group
Metrics for the Queue Manager belonging to the Message Broker
The following sections describe each of the metrics you can find under these nodes.
» Note The intervals used by the Message Broker metrics can vary.
Aggregate metrics and “traffic lights” are based on calculations done by the Introscope Enterprise Manager, which uses a default interval. This is almost always 15 seconds.
Message Flow metrics are based on reports from WebSphere Message Broker and use Message Broker’s default interval, which is always 20 seconds.
Metrics returned by the CMP (Configuration Manager Proxy) are based on the results of queries that are sent at a frequency which the administrator defines using the Static Delay Time setting in the MBMonitor.properties file. See CMP Connection Section (mandatory) on page 34.
Configuration Manager aggregate totals
Under the Configuration Manager node, the Investigator displays the aggregated Message Flow statistics and Broker Statistics, aggregated to the level of the Configuration Manager, as described in the following table.
Metric name Type Description
Backouts Total Number Aggregate total of messages backed out across all brokers under this Configuration Manager.
Errors Total Number Aggregate total of errors reported on this Configuration Manager.
Messages Dropped Total Number Aggregate total of dropped messages across all brokers under this Configuration Manager.
Timeouts Total Number Aggregate total of timeouts across all brokers under this Configuration Manager.
Message Broker metrics 183
User Guide
Broker properties and aggregate totals
Under the Configuration Manager metrics, the Investigator displays a node for the broker. This node displays broker properties and aggregate metrics for all Execution Groups managed by the broker.
The totals are calculated and have a 15 second interval, and everything else comes from CMP basic topology.
Metric name Type Description
Backouts Total Number Aggregate total of messages backed out for all Execution Groups configured on this broker.
Component Runstate String Whether the broker is RUNNING or STOPPED.
Errors Total Number Aggregate total of errors across all Execution Groups configured on this broker.
Messages Dropped Total
Number Aggregate total of dropped messages across all Execution Groups configured on this broker.
Number of Subcomponents
Number Number of subcomponents of this Broker.
Shared Object String TRUE—Broker is shared.FALSE—Broker is not shared.
Timeouts Total Number Number of timeouts.
UUID String Unique identifier for this Broker.
184 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Execution Groups metrics
Execution Groups are logical groupings of message flows within a broker.
The four metrics shown under the Execution Groups node are aggregated across all Execution Groups on the broker
Metric name Type Description
Backouts Total Number Aggregate total of messages backed out across all Execution Groups under this node.
Errors Total Number Aggregate total of errors reported across all Execution Groups under this node.
Messages Dropped Total Number Aggregate total of dropped messages across all Execution Groups under this node.
Timeouts Total Number Aggregate total of timeouts across all Execution Groups across all Execution Groups under this node.
.
Each Execution Group contains one or more Message Flows. Above the Message Flows node are several metrics which report:
Execution Group properties
Broker Statistics for the broker which the Execution Group resides on
Aggregate metrics for the Message Flows under that Execution Group
Message Broker metrics 185
User Guide
Execution Group properties and aggregate metrics
The calculated metrics roll up data from the message flows in that execution group.
Metric name Type Description
Architecture String This identifies the processor architecture of the Execution Group. Following values are reported to Introscope for different architecture execution groups:
32-bit for 32-bit architecture64-bit for 64-bit architecturedefault for default architecture
Backouts Total Number Aggregate total of messages backed out across all Message Flows in this Execution Group.
Component Runstate String Indicates whether the Execution Group is RUNNING or STOPPED.
Errors Total Number Aggregate total of errors reported across all Message Flows in this Execution Group.
Messages Dropped Total Number Aggregate total of dropped messages across all message flows configured under this Execution Group. Calculated by adding the following Client Statistics:
Disconnected Messages Dropped TotalMessages Dropped Total
Number of Subcomponents
Number Number of message flows and message sets under this Execution Group.
Shared Object String TRUE—Execution Group is shared.FALSE—Execution Group is not shared.
Timeouts Total Number Aggregate total of timeouts across all Message Flows in this Execution Group.
UUID String Unique identifier for the Execution Group
Broker statistics
Some Execution Groups publish Broker Statistics, also known as publish/subscribe statistics. They provide information about the performance of brokers and the throughput between clients that are connected to the broker.
As shown in the illustration below, the Broker Statistics node contains 3 summary nodes:
Client statistics—message throughput between the broker and clients that are connected to the broker.
Neighbor statistics—message throughput between the broker and any other brokers with which it has been configured as a neighbor to share publications and subscriptions.
186 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Wide Statistics—subscriber, client and neighbor counts for the broker.
Client and Neighbor Statistics report the metrics in the table below. The Wide Statistics node reports only summary counts which are self-explanatory.
» Note Totals are reported from the time the broker was started, not from an interval, and are cumulative.
Client and Neighbor statistics
Client Statistics report on message throughput between clients connected to the broker. Neighbor Statistics report on message throughput between brokers which
have been configured as neighbors.
Metric name Type Monitoring Level
Description
Bytes Dropped Total Number F The number of bytes that have been dropped due to queue overflow, where the client or neighboring broker was not subsequently disconnected from the broker.
Message Broker metrics 187
User Guide
Wide Statistics
Metric name Type Monitoring Level
Description
Client Count Total Number M The total number of clients that are connected to the broker.
Neighbor Count Total Number M The total number of neighbor brokers that are connected to the broker.
Subscription Count Total
Number M The number of subscriptions held by the broker.
Statistics generated by Publication Node
In general, each node provides one statistics element. However, the Publication node is split into five types of nodes and appears five times in the statistics.
Bytes Queued Total Number F The number of bytes of data that are currently queued by the broker for delivery to clients/neighboring brokers.
Bytes Received Total Number R The total number of bytes that have been received by the broker from its clients/neighboring brokers.
Bytes Sent Total Number R The total number of bytes that the broker has delivered to its clients/neighboring brokers.
Bytes Sent Without Being Queued Total
Number F The total number of bytes of data that were sent immediately to clients/neighboring brokers, without being queued internally by the broker.
Disconnected Bytes Dropped Total
Number F The number of bytes that have been dropped due to queue overflow, where the client/neighboring broker was subsequently disconnected from the broker.
Disconnected Messages Dropped Total
Number M The number of messages that have been dropped due to queue overflow, where the client/neighboring broker was subsequently disconnected from the broker.
Messages Dropped Total
Number M The number of messages that have been dropped due to queue overflow, where the client/neighboring broker was not subsequently disconnected from the broker.
Messages Received Total
Number M The total number of messages that have been received by the broker from its clients/neighboring brokers.
Messages Sent Total Number M The total number of messages that the broker has delivered to its clients/neighboring brokers.
188 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
For example, when you subscribe to the Surfwatch MessageFlow in the PagerExecutionGroup in the IBM Pager sample, you can see statistics reported for a single publication under five different nodes:
<NodeStatistics Label="Publish Reports.ComIbmMQOutput" Type="MQOutputNode" ...
<NodeStatistics Label="Publish Reports.ComIbmMQeOutput" Type="MQeOutputNode" ...
<NodeStatistics Label="Publish Reports.ComIbmPSService" Type="PSServiceNode" ...
<NodeStatistics Label="Publish Reports.ComIbmSCADAOutput" Type="SCADAOutputNode"
<NodeStatistics Label="Publish Reports.Response" Type="MQOutputNode" ...
Message Flow statistics
A Message Flow contains two or more Message Nodes.
Each of the Message Flows under an Execution Group reports the following statistics:
Message Flow properties and aggregate metrics covering all Message Nodes under the Message Flow
Errors—Error statistics for the Message Flow
Message Flow Invocations—Total number of invocations during the interval being monitored.
Message Statistics—Statistics regarding count and size of messages during the interval being monitored.
Node Statistics (if the Message Flow has been configured to report them)—Statistics for each of the Message Nodes
Performance—Performance statistics for the Message Flow
Data collection rules
Accounting and statistics data is collected only for message flows that start with an MQInput, HTTPInput, or user-defined input node.
Data collection follows these rules:
If you start data collection for a message flow that starts with one of these nodes, the data is collected for all built-in and user-defined nodes, including those in subflows.
If the message flow starts with another input node (for example, a Real-timeInput node), no data is collected (and no errors are reported).
Message Broker metrics 189
User Guide
Intervals
Message flow metrics use a 20-second interval, except for calculated aggregates, which run on the Enterprise Manager and use a 15-second interval.
Aggregate metrics across all Message Flows
At the top of the Message Flows tree, you can see aggregate metrics for all Message Flows.
Metric name Type Monitoring Level
Description
Backouts Total Number M Total number of backouts occurring across all Message Flows
Errors Total Number M Total number of errors occurring across all Message Flows, calculated by adding:
MQ Errors TotalMessages With Errors Total Processing Errors Total
Timeouts Total Number M Total number of timeouts occurring across all Message Flows
Properties and aggregate metrics for each Message Flow
Under each individual Message Flow, you can see several metrics mixed together:
Message Flow properties (for example, Message Flow State)
Aggregate metrics for all nodes under the Message Flow
190 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Metric name Type Description
Backouts Total Number Total number of backouts across all nodes under this Message Flow.
CPU Time Total Number Total CPU time (milliseconds) spent processing input messages by all nodes under this Message Flow.
Database Time Stamp String The time this Message Flow was updated in the Message Broker database.
Deployed String TRUE—Message Flow has been deployed to the broker.FALSE—Message Flow has not been deployed to the broker.
Elapsed Time Total Number Time spent waiting for messages, aggregated for all nodes under this Message Flow.
Errors Total Number Total number of errors, aggregated for all nodes under this Message Flow.
Invocations Total Number Total number of Message Flow invocations.
Message Count Total Number Total number of messages processed by this node.
Message Flow Coordinated Transactions Allowed
Number Whether coordinated transactions are allowed for this Message Flow. One of:
TRUE—Coordinated transactions are allowed.FALSE—Coordinated transactions are not allowed.
Message Flow Deploy Time
String Date and time this Message flow was deployed.
Message Flow State String Whether the message flow is:RUNNINGSTOPPED
Message Flow UUID String Unique identifier for this Message Flow.
Message Flow User Trace
String Defines the type of user trace configured for this message flow. One of:
debug— Defines debug user trace.none—States that user trace is not running.normal—Defines normal user trace.unknown—Defines an unknown user trace setting.
Name String Name of the Message Flow.
Statistics Reported String Whether statistics are being reported for this Message Flow. One of:
TRUE—Statistics are reported for this Message Flow.FALSE—Statistics are not reported for this Message Flow.
Timeouts Total Number Number of timeouts that occurred on this Message Flow while processing a message, aggregated for all nodes under this Message Flow.
Message Broker metrics 191
User Guide
Errors
Metric name Type Monitoring Level
Description
MQErrors Total Number M Number of MQGET errors (MQInput node) or Web services errors (HTTPInput node) during the most recent 20-second interval.
Messages With Errors Total
Number M Number of messages that contain errors during the most recent 20-second interval.
Processing Errors Total Number M Number of errors processing a message during the most recent 20-second interval.
Thread Count In Pool Total Number R Number of threads in pool.
Thread Maximum Reached Total
Number M Number of times the maximum number of threads was reached during the most recent 20-second interval.
Timeouts Total Number M Number of timeouts processing a message (AggregateReply node only) during the most recent 20-second interval.
Message Flow Invocations
Metric name Type In Description
Message Flow Backouts Total
Number M Number of transaction backouts aggregated from all nodes of this message flow during the most recent 20-second interval.
Message Flow Commits Total
Number M Number of transaction commits aggregated from all nodes of this message flow during the most recent 20-second interval.
Message Flow Invocations Total
Number M Total number of invocations, that is, sum of Message Flow Backouts Total and Message Flow Commits Total.
Total Broker Threads for Message Flow
Number The number of additional threads that the broker can use to service the message flow.
192 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Message Statistics
Metric name Type Monitoring Level
Description
Message Count Total Number M Total number of messages processed during the most recent 20-second interval.
Message Size Average Number M Average size of input messages (bytes) during the most recent 20-second interval.
Message Size Maximum Number M Maximum input message size (bytes) during the most recent 20-second interval.
Message Size Minimum Number M Minimum message input size (bytes) during the most recent 20-second interval.
Message Size Total Number M Total size of input messages (bytes) during the most recent 20-second interval.
Node Statistics
Message Flow node statistics are crucial in identifying Message Flow performance problems. The following metrics are reported for each node if Message Flow statistics are configured for the Execution Group.
» Note Time measurements are in milliseconds.
Metric name Type Monitoring Level
Description
CPU Processing Time Number M Total CPU time, in milliseconds, this node has spent processing input messages during the most recent 20-second interval.
CPU Processing Time Average
Number M Average CPU time, in milliseconds, this node takes to process an input message during the most recent 20-second interval.
Message Broker metrics 193
User Guide
Performance
Elapsed Time Number M Total elapsed time, in milliseconds, the node has spent waiting for input messages during the most recent 20-second interval.
Elapsed Time Average Number M Average elapsed time, in milliseconds, the node has spent waiting for input messages during the most recent 20-second interval.
Node Invocation Total Number M Total number of messages processed by this node during the most recent 20-second interval.
Node Type String R Type of the node being monitored. This should correspond to the node name, e.g. MQInputNode.
Number of Input Terminals Number F Each message flow node has a fixed number of input and output points or terminals which serve as entrances to or exits from a node. These metrics measure the total number of input and output terminals for the node.
Number of Output Terminals
Number F
Metric name Type Monitoring Level
Description
CPU Time Number R Total CPU time spent processing input messages.
CPU Time Average Number F Average CPU time spent processing input messages (in milliseconds)
CPU Time Maximum Number M Maximum CPU time spent processing an input message (in milliseconds)
CPU Time Minimum Number M Minimum CPU time spent processing an input message (in milliseconds)
CPU Time Waiting For Input Average
Number M Average CPU time spent waiting for input messages (in milliseconds)
CPU Time Waiting For Input Total
Number M Total CPU time spent waiting for input messages (in milliseconds)
Elapsed Time Average Number R Average elapsed time spent processing input messages (in milliseconds)
Elapsed Time Maximum Number M Maximum elapsed time spent processing an input message (in milliseconds)
Elapsed Time Minimum Number F Minimum elapsed time spent processing an input message (in milliseconds)
Elapsed Time Number M Total elapsed time spent processing input messages (in milliseconds)
194 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Broker Queue Manager metrics
Beneath the Execution Groups node in the Message Broker metrics tree is a node for the Message Broker’s Queue Manager.
Elapsed Time Waiting For Input Average
Number F Average elapsed time spent waiting for input messages (in milliseconds)
Elapsed Time Waiting For Input Total
Number F Total elapsed time spent waiting for input messages (in milliseconds)
Message Broker metrics 195
User Guide
The Investigator displays the same set of metrics for this Queue Manager as detailed in the section on Queue Manager metrics on page 146.
Configuration Manager’s Queue Manager metrics
Metrics for the Configuration Manager’s Queue Manager appear under a Configuration Manager|Dedicated Queue Manager node in the MB metrics tree.
The Investigator displays the same set of metrics for this Queue Manager as detailed in Queue Manager metrics on page 146.
Display of shared and non-shared Queue Managers
The Message Broker topology enables the user to use the same Queue Manager for the Configuration Manager and its default Broker. In this case, the Queue Manager is shared by the Configuration Manager and one (and only one) Broker, the PowerPackNameShort Agent reports this Queue Manager and its related metrics under the Broker in the Introscope Investigator tree.
In cases where the Configuration Manager has its own non shared Queue Manager, the Queue Manager appears right under the Configuration Manager|Dedicated Queue Manager node, which is on the same level where brokers appear.
196 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
MQ Java Connector metricsWebSphere MQ classes for Java (also referred to as WebSphere MQ base Java) allow a Java application to:
Connect to WebSphere MQ as a WebSphere MQ client
Connect directly to a WebSphere MQ server
WebSphere MQ classes for Java Message Service (also referred to as WebSphere MQ JMS) is a set of Java classes that implement Sun’s Java Message Service (JMS) interfaces to enable JMS programs to access WebSphere MQ systems.
To find data from MQ Java Connectors:
1 Expand the SuperDomain node and look under the <hostname> > WebSphere > WebSphereAgent (*SuperDomain*) node.
2 Look under certain nodes in the tree, as shown in the following illustration:
Operational groups
MQ returns metrics from MQ Java base classes using operational groups. Appendix B, JCA/JMS Operational Groups beginning on page 207, lists the member of each operational group and the MQ Java base class they use.
MQ Java Connector metrics 197
User Guide
Backend metrics
Introscope reports metrics for backend systems, including databases, a mail server, a transaction processing system (such as CICS or Tuxedo) or, in this case, WebSphere MQ. You can use these metrics to monitor the performance of any running application using MQ.
The following illustration shows how WebSphere MQ appears under the Investigator’s Backends node.
In the above illustration, Investigator displays two WebSphere MQ servers. The MQ instance on host2 is expanded to show:
Aggregate metrics
Connector node, with the following for each Queue Manager on the Connector:
Operations
Queues
JMS node:
Operations
Queues
Topics
198 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Instance Counts metrics
The Investigator displays instance counts for the WebSphere MQ base classes
under the Instance Counts node. To enable Instance counts, uncomment PowerPackForWebSphereMQ_v8.1_InstanceCounts.pbd file in the PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl file.
Only one metric, Approximate Instance Count, is reported for each instance:
Metric Description
Approximate Instance Count
The number of times the WebSphere MQ system called the class corresponding to the instance during the most recently completed interval.
You can use instance count metrics to monitor the number of times the object of the particular class was created.
JCA node metrics
Under the JCA node, the Investigator displays metrics for each of the connection pools you configured a service for (see Configure MQ Java Connectors on page 49).
MQ Java Connector metrics 199
User Guide
» Note Two of the metrics displayed for connection pools are labeled differently depending on whether you are monitoring WebSphere Application Server
(WAS) v5.1 or v6.0.
Metric Description
PercentMaxed Average percent of the time that all connections are in use.
PercentUsed The percentage of the connection pool that is currently in use.
PoolSize The size of the connection pool to the data source.
AvgWaitTime (WAS v5.1)
WaitTime (WAS v6.0/v6.1)
The average waiting time in milliseconds until a connection is granted.
ConcurrentWaiters (WAS v5.1)
WaitingThreadCount (WAS v6.0/v6.1)
The number of threads that are currently waiting for a connection.
» Note JCA Connection Pool metrics are only visible for WebSphere v5.1, v6.x, and later.
WebSphereMQ node metrics
Under the WebSphereMQ node, you can see most of the metrics you can use to monitor the performance of your WebSphere MQ Java Connectors.
» Note These aggregated metrics are not visible unless and until the corresponding Operations are invoked.
» Note The Average Response Time (ms) for Commit and Rollback Operations are aggregated together.
The top level of the tree shows aggregated metrics rolling up Average Response Time for all of the Connectors and JMS operations in the tree below.
200 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
Th
Metric Description
Average Response Time (ms) The weighted average response times for all operational groups of this name on nodes lower in the tree
e metrics are organized by operation name, but they are all the same metric:
The tree is organized by this hierarchy:
Top level node (Connector/JMS)Aggregate response time metrics, organized by Operational Group namehost name
Queue Manager NameOperations
Operational GroupAggregate metrics for the operational groupIndividual operation name
Metrics for the individual operationQueues
Individual queue nameOperational group
Aggregate metrics for the operational groupIndividual operation name
Metrics for the individual operationTopics (JMS only)
Individual topic nameOperational group
Aggregate metrics for the operational groupIndividual operation name
Metrics for the individual operation
Operational groups
The Investigator displays metrics on operations (such as connect, get, rollback, etc.) under the following Operation Groups:
Connect
Disconnect
Send
Receive
Commit
Rollback
Close
MQ Java Connector metrics 201
User Guide
Operational Group metrics
The tree displays the following metrics for each operation group:
Aggregate metrics for all the operations in that group
Metrics for each individual operation
For each Aggregate Operation, the Investigator displays five aggregated metrics
at the operational group level:
Metric Description
Average Response Time (ms)
The weighted average response time, in milliseconds, for all operations under this node, during the most recent interval.
Concurrent Invocations The total number of requests for all operations under this node that were completed, during the most recent interval.
Errors Per Interval The total number of errors for all operations under this node that occurred, during the most recent interval.
Responses Per Interval Total responses per interval of all operations under this node, during the most recent interval.
Stall Count The total number of stalled transactions for all operations under this node, during the most recent interval.
» Note Introscope uses a default 15-second interval, not the 20-second interval which WebSphere MQ uses to report its internal metrics. Whenever you see the metrics in the table above in the Java Connectors tree, the interval is always the default Introscope interval.
202 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
asdf
The following illustrations show how metrics for operational groups are displayed throughout the WebSphereMQ node.
MQ Java Connector metrics 203
User Guide
Aggregate and individual metrics
Aggregate metrics are calculated using metrics of the same name on nodes lower in a hierarchy. For example, expanding the Connect operation group displays:
Aggregate metrics for all the operations in the group
Nodes for each individual operation in that group
This pattern, in which aggregate metrics roll up the metrics from the nodes under them, is repeated throughout the tree.
The illustration below shows the relation of the aggregate metrics to the nodes whose metrics are rolled up in the aggregate metrics:
204 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
ErrorDetector metrics
The PowerPackForWebSphereMQ_v8.1_ErrorDetector.pbd file (see Configure ErrorDetector on page 53) generates Errors Per Interval metrics that appear under several operational group nodes, as shown in the following illustration:
The Errors view, available when a resource or component is selected in the Investigator tree, lists errors and error details for the selected item.
The top half of the Errors view lists the time, description, and type of each error. The lower half of the view shows detailed information for each component involved in the error selected.
MQ Java Connector metrics 205
User Guide
The following illustration shows this view.
206 Metrics reference
PowerPack for WebSphere MQ Connectors and Messaging System
JCA/JMS Operational Groups 207
APPENDIX B
JCA/JMS Operational Groups
This appendix lists the operation names for each Operational Group.
This appendix contains the following topics:
JCA Queue Manager Operations . . . . . . . . . . . . . . 208
JCA Queue Operational Groups . . . . . . . . . . . . . . 210
JMS Queue Manager Operational Groups . . . . . . . . . . . 211
JMS Queue/Topic Operational Groups . . . . . . . . . . . . 213
JCA Operational Groups
This section describes the following JCA Operational Groups:
JCA Queue Manager Operations
JCA Queue Operational Groups
208 JCA/JMS Operational Groups
PowerPack for WebSphere MQ Connectors and Messaging System
JCA Queue Manager Operations
Disconnect Operational Group
Operation name Description
Manager Disconnect Monitors the Queue Manager disconnect functions in the com.ibm.mq.jar file.
Unregister Monitors the Queue Manager unregister functions in the com.ibm.mq.jar file.
Cleanup Monitors the cleanup functions called on the Queue Manager object in the com.ibm.mq.jar file.
Destroy Monitors the destroy functions called on the Queue Manager object in the com.ibm.mq.jar file.
Session Disconnect Monitors all the session disconnection operations on the Queue Manager object in the com.ibm.mq.jar file.
Connect Operational Group
Operation name Description
Begin Monitors the Queue Manager begin() operation in the com.ibm.mq.jar file.
Access Process Monitors the Queue Manager process access operation in the com.ibm.mq.jar file.
Get Connection Monitors the Queue Manager connection get operations in the com.ibm.mq.jar file.
Session Connect Monitors the Queue Manager session connect operations, such as MQCONN, MQCONNX in the com.ibm.mq.jar file.
XA Session Start Monitors the Queue Manager session start operations in the com.ibm.mq.jar file.
XA Session Prepare Monitors the Queue Manager XA enabled prepare session operations in the com.ibm.mq.jar file.
Queue Process Get Type Monitors the Application Type operations in the com.ibm.mq.jar file.
209
User Guide
Commit Operational Group
Operation name Description
Manager Commit Monitors the Queue Manager commit operations in com.ibm.mq.jar.
Session Commit Monitors the Queue Manager session client commit operations in com.ibm.mq.jar.
XA Session Commit Monitors the Queue Manager XA enabled session client commit operations in com.ibm.mq.jar.
Put Operational Group
Operation name Description
Manager Put Monitors the Queue Manager put operations in com.ibm.mq.jar.
Distribution List Put Monitors the Queue Manager distribution list put operations in com.ibm.mq.jar.
Get Operational Group
Operation name Description
Access Queue Monitors the Queue Manager queue access operations in com.ibm.mq.jar.
Distribution List Get Monitors the Queue Manager distribution list get operations in com.ibm.mq.jar.
Get Count Monitors the Queue Manager getcount() operation
Open Operational Group
Operation name Description
Session Open Monitors the session client open operations in the com.ibm.mq.jar file.
XA Session Open Monitors the XA enabled session client open operations in the com.ibm.mq.jar file.
210 JCA/JMS Operational Groups
PowerPack for WebSphere MQ Connectors and Messaging System
Close Operational Group
Operation name Description
Session Close Monitors the session client close operations in the com.ibm.mq.jar file.
XA Session Close Monitors the XA enabled session client open operations the in com.ibm.mq.jar file.
Process Close Monitors the mqprocess object operations in the com.ibm.mq.jar file.
Rollback Operational Group
Operation name Description
Session Rollback Monitors the session client rollback operations in the com.ibm.mq.jar file.
XA Session Rollback Monitors the XA enabled session client rollback operations in the com.ibm.mq.jar file.
XA Session Recover Monitors the session client recover operations in the com.ibm.mq.jar file.
JCA Queue Operational Groups
Put operational group
Operation Names Description
Queue Put Monitors the queue put operations in the com.ibm.mq.jar file.
Get operational group
Operation Names Description
Queue Get Monitors the queue get operations in the com.ibm.mq.jar file.
JMS Operational Groups
This section describes the following JMS Operational Groups:
JMS Queue Manager Operational Groups
JMS Queue/Topic Operational Groups
211
User Guide
JMS Queue Manager Operational Groups
Receive Operational Group
Operation name Description
Create Receiver Monitors the JMS create receiver operations in the com.ibm.mqjms.jar file.
Create Subscriber Monitors the JMS create subscriber operations in the com.ibm.mqjms.jar file.
Create Browser Monitors the JMS create browser operations in the com.ibm.mqjms.jar file.
Create Consumer Monitors the JMS create consumer operations in the com.ibm.mqjms.jar file.
Get Topic Monitors the JMS get topic operations in the com.ibm.mqjms.jar file.
Async Receive Monitors the JMS Async receive operations in the com.ibm.mqjms.jar file.
Receive No Wait Monitors the JMS receive no wait operations in the com.ibm.mqjms.jar file.
Consumer Receive Monitors the JMS consumer receive operations in the com.ibm.mqjms.jar file.
Send Operational Group
Operation name Description
Create Sender Monitors the JMS sender creation operations in the com.ibm.mqjms.jar file.
Create Producer Monitors the JMS producer creation operations in the com.ibm.mqjms.jar file.
Create Destination Monitors the JMS destination creation operations in the com.ibm.mqjms.jar file.
Create Message Monitors the JMS message creation operations in the com.ibm.mqjms.jar file.
Process Message Monitors the JMS message process operations in the com.ibm.mqjms.jar file.
212 JCA/JMS Operational Groups
PowerPack for WebSphere MQ Connectors and Messaging System
Connect Operational Group
Operation name Description
Create Queue Monitors the JMS queue creation operations in the com.ibm.mqjms.jar file.
Create Publisher Monitors the JMS create publisher operations in the com.ibm.mqjms.jar file.
Create Topic Monitors the JMS Topic creation operations in the com.ibm.mqjms.jar file.
Get Server Session Pool Monitors the JMS session pool operations in the com.ibm.mqjms.jar file.
Disconnect Operational Group
Operation name Description
Unsubscribe Monitors the JMS unsubscribe operations in the com.ibm.mqjms.jar file.
Close Connect Monitors the JMS connection close operations in the com.ibm.mqjms.jar file.
Close Operational Group
Operation name Description
Session Close Monitors the JMS session close operations in the com.ibm.mqjms.jar file.
Commit Operational Group
Operation name Description
Session Commit Monitors the JMS session commit operations in the com.ibm.mqjms.jar file.
Rollback Operational Group
Operation name Description
Session Recover Monitors the JMS session recover operations in the com.ibm.mqjms.jar file.
Session Rollback Monitors the JMS connection close operations in the com.ibm.mqjms.jar file.
213
User Guide
JMS Queue/Topic Operational Groups
Send Operational Group
Operation name Description
Publish Monitors the JMS Queue/Topic publish operations in the com.ibm.mqjms.jar file.
Producer Send Monitors the JMS Queue/Topic send operations in the com.ibm.mqjms.jar file.
Process Message Monitors the JMS agent thread process message operations in the com.ibm.mqjms.jar file.
Receive Operational Group
Operation name Description
Get Topic Monitors the JMS Topic get operations in the com.ibm.mqjms.jar file.
Async Receive Monitors the JMS Queue/Topic async receive operations in the com.ibm.mqjms.jar file.
Receive No Wait Monitors the JMS Queue/Topic receive no wait operations in the com.ibm.mqjms.jar file.
Consumer Receive Monitors the JMS Queue/Topic consumer receive operations in the com.ibm.mqjms.jar file.
Connect Operational Group
Operation name Description
Get Server Session Pool Monitors the JMS session pool get operations in the com.ibm.mqjms.jar file.
Disconnect Operational Group
Operation name Description
Close Connection Monitors the JMS Queue/Topic connection close operations in the com.ibm.mqjms.jar file.
214 JCA/JMS Operational Groups
PowerPack for WebSphere MQ Connectors and Messaging System
Performance and Sizing 215
APPENDIX C
Performance and Sizing
This appendix contains instructions, best practices, and tips for optimizing the sizing and performance of your PowerPack for MQ deployment and environment.
» Important The configurations listed in this appendix are only examples and do not indicate the recommended WebSphere MQ or WebSphere MB configurations.
This appendix contains the following topics:
MQMonitor agent background . . . . . . . . . . . . . . . 215
WebSphere MQ Sizing . . . . . . . . . . . . . . . . . 216
WebSphere MB Sizing . . . . . . . . . . . . . . . . . 221
MQMonitor agent backgroundIn an Introscope deployment, the agent collects application and environmental metrics, and relays them to the Enterprise Manager. As an Introscope Agent, the MQMonitor agent collects WebSphere MQ and WebSphere MB-specific metrics to monitor the performance of WebSphere MQ and WebSphere MB to quickly isolate the source of WebSphere MQ-related and WebSphere MB-related performance problems.
The factors that would affect the performance and overhead of MQMonitor agent are:
The number of Queue Managers monitored and the number of WebSphere MQ objects (queues, channels, and so on) in each monitored Queue Manager for WebSphere MQ.
The number of message brokers monitored and the number of execution groups and message flows in each monitored message broker for WebSphere MB.
The number of WebSphere MQ clusters and the size of each cluster.
The metric display and control level (minimum, recommended, full) for a component.
216 Performance and Sizing
PowerPack for WebSphere MQ Connectors and Messaging System
The Java Heap size of the MQMonitor agent.
%CPU utilization of the MQMonitor agent.
State of the Transaction Tracer (whether switched on or switched off).
Hardware configuration of the machines involved.
WebSphere MQ SizingTo perform sizing on WebSphere MQ, you must perform sizing on the EM and the MQMonitor agent.
Sizing your EM
The number of metrics contributed by the PowerPack for MQ agent determines the sizing consideration of your EM. The metric count depends on the number of Queue Manager objects that you plan to monitor. To find out the number of metrics that are reported to your EM, calculate the Maximum Metric Count per Queue Manager for different levels of monitoring. The Maximum Metric Count is the maximum number of metrics that are reported including aggregated metrics. The formulas for calculating the Maximum Metric Count for distributed and z/OS systems at the full, recommended, and minimum monitoring levels are as follows:
Distributed systems:
At the full monitoring level:
Maximum Metric Count = (Q * 76) + (C * 48) + 69
At the recommended level:
Maximum Metric Count = (Q * 30) + (C * 39) + 38
At the minimum level:
Maximum Metric Count = (Q * 21) + (C * 28) + 18
where:
Q is the number of Queues for a Queue Manager
C is the number of Channels for a Queue Manager
z/OS systems:
At the full monitoring level:
Maximum Metric Count = (Q * 97) + (C * 48) + (CI * 18) + (L * 19) + ((PS * 15) + 1) + 91
WebSphere MQ Sizing 217
User Guide
At the recommended level:
Maximum Metric Count = (Q * 30) + (C * 36) + (CI * 17) + (L * 19) + ((PS * 15) + 1) + 45
At the minimum level:
Maximum Metric Count = (Q * 15) + (C * 20) + (CI * 4) + (L * 4) + ((PS * 6) + 1) + 18
where:
Q is the number of Queues for a Queue Manager
C is the number of Channels for a Queue Manager
CI is the number of Channel Initiators for a Queue Manager
L is the number of Logs for a Queue Manager
PS is the number of Page Sets for a Queue Manager
» Note The number of metrics equal to the Maximum Metric Count is added to your EM’s metric count. To find out the existing metric count, go to Custom Metric Host > Custom Metric Agent > Enterprise Manager > Connections > Number of Metrics in the Investigator tree. You can then see the Introscope EM sizing guide to size your EM.
» Note If you do not see all the metrics that should be reported by the MQMonitor agent, then you must check if the metrics are being clamped by the EM. To do this, login to the Investigator tree and observe the following metric:
If the Is Clamped metric displays the value 1, then the agent metrics are being clamped by the EM, so you need to increase the limit of metrics that the agent can report. To do this, set the introscope.enterprisemanager.agent.metrics.limit to a desired value and restart the EM.
Alternatively, you can change the monitoring level for the WebSphere MQ objects from Full to Recommended or Recommended to Minimum.
SuperDomain > Custom Metric Agent (Virtual) > Custom Metric Agent (Virtual) (*SuperDomain*) > Agents > <Agent Machine Name> > <Agent Name> > <Agent Process> > Is Clamped
218 Performance and Sizing
PowerPack for WebSphere MQ Connectors and Messaging System
Sizing your MQMonitor agent
The following sections describe the settings and capacity limits that you need to set up, maintain, and configure PowerPack for MQ environment for monitoring WebSphere MQ. The monitoring level defined at the MQMonitor agent determines the number of metrics reported by the PowerPack for MQ to the EM.
» Note The information below is only a guideline for the sizing of your configuration. The sizing information can vary depending on the hardware configuration of your EM, the MQMonitor agent, and the WebSphere MQ machines.
WebSphere MQ Sizing 219
User Guide
Sample MQMonitor agent sizing table
The MQMonitor agent sizing table is as follows:
Configuration: Single Queue Manager with Multiple Queues
Configuration: Multiple Queue Managers with Multiple Queues
Monitoring Level
Delaytime, Static frequency
Heap Size (minimum to maximum)
Number of queues
Number of metrics
Minimum 300, 2 256 to 512 5800 122000
600, 2 256 to 512 6000 126200
Recommended 300, 2 256 to 512 4200 126300
600, 2 256 to 512 4500 135300
Full 300, 2 256 to 512 1700 129500
600, 2 256 to 512 1800 137100
Monitoring Level
Delaytime, Static frequency
Heap Size (minimum to maximum)
Number of Queue Managers / Number of queues per Queue Manager
Number of metrics
Minimum 300, 2 256 to 512 Queue Managers: 5
Queues per Queue Manager: 1100
116800
600, 2 256 to 512 Queue Managers: 5
Queues per Queue Manager: 1200
127300
Recommended 300, 2 256 to 512 Queue Managers: 5
Queues per Queue Manager: 800
121600
600, 2 256 to 512 Queue Managers: 5
Queues per Queue Manager: 800
121600
Full 300, 2 256 to 512 Queue Managers: 5
Queues per Queue Manager: 300
116570
600, 2 256 to 512 Queue Managers: 5
Queues per Queue Manager: 300
116570
220 Performance and Sizing
PowerPack for WebSphere MQ Connectors and Messaging System
Environment Details
Enterprise Manager:
System Requirement Details
Operating system Microsoft Windows Server 2003 Enterprise Edition
System Model Dell Inc., PowerEdge 6950
Processor Dual Core AMD Opteron™ Processor 8220,MMX,3D Now(8CPUs), ~2.8HZ
Memory 16GB
Total Free Space 210GB
MQMonitor agent:
System Requirement Details
Operating system Microsoft Windows Server 2003 Enterprise Edition
System Model Dell Inc., PowerEdge GX620
Processor Intel Pentium® 4 CPU 3.00 GHz, ~3.0 GHz
Memory 2GB
Total Free Space 17GB
4-512MB
System Requirement Details
Operating system Microsoft Windows Server 2003 Enterprise Edition
System Model Dell Inc., PowerEdge 745
Processor Intel Pentium® D CPU 3.00 GHz, ~3.0 GHz
Memory 2GB
Total Free Space 16GB
MQ Machine:
With the above WebSphere MQ configuration and the number of metrics generated by the MQMonitor agent, the EM processing cycle increases. The overload on the MQMonitor agent is, however, minimal, so you must ensure that you size your EM appropriately for sizing PowerPack for MQ for WebSphere MQ objects. See the Introscope Sizing Guide to size your EM appropriately.
» Note If you plan to use the same agent for monitoring WebSphere MQ and WebSphere MB, or if you plan to use the same MQMonitor agent for transaction tracing, then the number of supported objects would reduce.
WebSphere MB Sizing 221
User Guide
WebSphere MB SizingTo perform sizing on WebSphere MB, you must perform sizing on the EM and the MQMonitor agent for WebSphere MB.
Sizing your EM
The number of metrics contributed by the PowerPack for MQ agent determines the sizing consideration of your EM. The metric count depends on the number of WebSphere MB objects that you plan to monitor. To find out the number of metrics that are reported to your EM, calculate the Maximum Metric Count for different levels of monitoring.
The formulas for calculating the Maximum Metric Count at the full, recommended, and minimum monitoring levels are as follows:
At full monitoring level:
Maximum Metric Count = 4 + (4 + 5 * B) + (4 + 29 * EG * B) + (3 + 36 * MF * EG * B) + (7 * N)
At the recommended level:
Maximum Metric Count = 4 + (4 + 5 * B) + (4 + 21 * EG * B) + (3 + 32 * MF * EG * B) + (7 * N)
At the minimum level:
Maximum Metric Count = 4 + (4 + 5 * B) + (4 + 17 * EG * B) + (3 + 29 * MF * EG * B) + (7 * N)
» Note This is the maximum number of metrics that are reported when all the aggregated and normal metrics are reported.
where:
B is the number of brokers
EG is the number of execution groups
MF is the number of message flows
N is the number of nodes per message flow
» Note The number of metrics equal to the Maximum Metric Count is added to your EM’s metric count. To find out the existing metric count, go to Custom Metric Host > Custom Metric Agent > Enterprise Manager > Connections > Number of Metrics in the Investigator tree. You can then see the Introscope EM sizing guide to size your EM.
222 Performance and Sizing
PowerPack for WebSphere MQ Connectors and Messaging System
Sizing your MQMonitor agent for WebSphere MB
The following sections describe the settings and capacity limits that you need to set up, maintain, and configure your PowerPack for MQ environment for monitoring WebSphere MB.
» Note The information below is only a guideline for the sizing of your configuration. The sizing information can vary depending on the hardware configuration of your EM, MQMonitor agent, and WebSphere MB machines.
Sample MQMonitor agent sizing table for WebSphere MB
The MQMonitor agent sizing table for WebSphere MB is as follows:
Configuration: Single Broker Multiple Execution Groups and Multiple Message flows
Monitoring Level Number of execution groups per broker
Total number of message flows
Number of nodes per message flow
Number of metrics reported
Minimum 25 150 51 8700
Recommended 25 150 51 10400
Full 25 150 51 13600
Minimum 15 90 51 5800
Recommended 15 90 51 6900
Full 15 90 51 9400
Minimum 5 30 51 1800
Recommended 5 30 51 2300
Full 5 30 51 2900
WebSphere MB Sizing 223
User Guide
Configuration: Multiple brokers (total number of brokers used is 3) multiple execution groups and multiple message flows in each broker.
Environment Details
Enterprise Manager
System Requirement Details
Operating system Microsoft Windows Server 2003 Enterprise Edition
System Model Dell Inc., PowerEdge 6950
Processor Dual Core AMD Opteron™ Processor 8220, MMX, 3D Now(8CPUs), ~2.8HZ
Memory 16GB
Total Free Space 210GB
:
MQMonitor agent:
System Requirement
Details
Operating system Microsoft Windows Server 2003 Enterprise Edition
System Model Dell Inc., Optiplex GX620
Processor Intel Pentium® 4 CPU 3.00 GHz, ~3.0 GHz
Memory 2GB
Total Free Space 17GB
4-512MB
Monitoring Level Number of execution groups per broker
Total number of message flows
Number of nodes per message flow
Number of metrics reported
Minimum 10 130 51 8100
Recommended 10 130 51 9700
Full 10 130 51 12600
System Requirement
Details
Operating system Microsoft Windows Server 2003 Enterprise Edition
System Model Dell Inc., Optiplex 745
Processor Intel Pentium® D CPU 3.00 GHz, ~3.0 GHz
Memory 2GB
Total Free Space 16GB
224 Performance and Sizing
PowerPack for WebSphere MQ Connectors and Messaging System
MB Machine:
With the above WebSphere MB configuration, the overload on the MQMonitor machine is minimal (only 2%) and the number of metrics reported to EM is comparatively lesser than the number of metrics reported when you monitor large WebSphere MQ configurations. So, depending on your WebSphere MB machine configuration, the MQMonitor agent can be utilized better.
Also, if you plan to use the same agent for monitoring WebSphere MQ and WebSphere MB, or if you plan to use the same MQMonitor agent for transaction tracing, then the number of supported objects would reduce.
» Important We recommend that you do not perform Management Module hot deployments on production collectors or MOMs, as it locks the system and also prevents the metric data from being reported.
Frequently Asked Questions 225
APPENDIX D
Frequently Asked Questions
This appendix includes frequently asked questions about installation, metrics, transaction tracing, alerts, and dashboards in PowerPack for MQ.
This appendix includes the following topics:
Alerts and dashboards . . . . . . . . . . . . . . . . . 225
Installation . . . . . . . . . . . . . . . . . . . . . 226
Metrics . . . . . . . . . . . . . . . . . . . . . . 226
Queues . . . . . . . . . . . . . . . . . . . . . . 227
Transaction Tracing . . . . . . . . . . . . . . . . . . 227
Alerts and dashboards
What is the purpose of the WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard?
The WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard helps you check if your MQ infrastructure is configured properly for the cross-process transaction trace to work.
I do not see any color for the Connection Pool alert in the WebSphere MQ Client And Server Overview – Details and WebSphere MQ – Client Connection dashboards. Why is this so?
Connection pool alerts are applicable only for the WebSphere application server. If your Java application server is WebSphere and you have enabled PMI metrics reporting, then you would see this alert reporting data from the WebSphere PMI connection pool data.
How do I triage the WebSphere MQ infrastructure problems?
To troubleshoot WebSphere MQ infrastructure issues:
a Log in to the Introscope Console Workstation.
b Open the WebSphere MQ Client And Server - Overview dashboard.
226 Frequently Asked Questions
PowerPack for WebSphere MQ Connectors and Messaging System
c Observe the traffic lights to determine the health of your MQ Client connections, MQ Client operations, and MQ Server.
d Double-click the traffic light that reports a warning and go to the details page.
On the Details page, view the MQ connections, MQ operations, and MQ Server information, to determine and analyze the problem in your MQ infrastructure.
Installation
On UNIX or Linux, do I need to install PowerPack for MQ using the “root” account?
No, you do not need the root account to install PowerPack for MQ on UNIX or Linux platforms. For details, see Security settings for CMP, JMS, PCF connections on page 32.
Which version of connector JAR file does the PowerPack for MQ support? How can I know the version of connector jar file used by my application?
PowerPack for MQ v8.x supports the v6.x and v7.x connector JAR files only.
To determine the version of Connector JAR files, locate the com.ibm.mq.jar file, open the JAR file, and see the version of the connector in the manifest.mf file.
When Java 2 security is enabled on my application server and I deploy PowerPack for MQ, I see security exception being reported in the application server log. What do I do?
You must ensure that you provide adequate permission on the application server to prevent any security exceptions. For configuring PowerPack for MQ to enable Java 2 security, see (Optional) Configure application server when Java 2 security is enabled on page 48.
Metrics
At what intervals are the message broker metrics updated?
Configuration manager metrics are updated as per the delay time property in the MBMonitor.properties file.
Message flow statistics are updated every 20 seconds, and are reported accordingly.
Broker statistics are updated depending on the mqsichangeproperties command issue on the Message Broker.
How do I interpret Enqueue Count and Dequeue Count metrics? How is this related to the Queue Depth metric?
227
User Guide
The Enqueue Depth metric gives the number of messages that were added to a queue since the last polling cycle of the MQMonitor agent. This includes uncommitted messages.
The Dequeue Count metric gives the number of messages that were removed from the queue since the last polling cycle of the MQMonitor agent.
The Current Queue Depth can be confirmed as follows:
Current Queue Depth = [Queue Depth at the previous polling cycle] + [Enqueue Count] – [Dequeue Count]
What is the difference between Message metrics and Current Messages metrics for Channels?
The Message metrics indicate the number of messages that have been sent or received (or, for server-connection channels, the number of MQI calls handled) since the channel was started. This is applicable to Sender, Receiver, Cluster-sender, Cluster-receiver, Server, Requester, Server-connection channel types
The Current Messages metric indicates the number of messages sent/received in the current batch. This is not applicable to Server Connection channels but applicable to all other channel types.
Queues
PowerPack for MQ provides the “includeonly” regular expression for monitoring queues. How can I exclude queues from monitoring?
You can use the regular expression with the “includeonly” property to exclude the monitoring of relevant queues.
If you want to filter out all queues starting queue1 and queue2 of the WebSphere MQ instance named QM1, then you can use the following regular expression:
QM1.queue.filter.includeonly.regex=(?!((queue1.*)|(queue2.*))).*
Transaction Tracing
I am using the cross-process transaction trace feature. However, I do not see MQ traces. Why is this so?
Open the WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard. Check if any of the traffic lights is red and view the details for that traffic light. If all the traffic lights are green or yellow, and if you still don't see MQ Trace data, then ensure that you restart all the active channels of the monitored Queue Managers. If the problem persists, check the log files and Introscope version.
228 Frequently Asked Questions
PowerPack for WebSphere MQ Connectors and Messaging System
If my business transaction passes through any WebSphere MQ v5.3 Queue Managers, can I view the transaction traces from WebSphere MQ version v5.3 Queue Managers?
No, you cannot view transaction traces from WebSphere MQ v5.3 Queue Managers. Cross-process transaction tracing is supported for WebSphere MQ v6.x and v7.x only.
After setting the Activity Reporting property to “Queue”, why should I restart the active channels of the monitored Queue Managers or the Queue Managers?
Restarting the Queue Manager also restarts the MCA’s. This ensures that the trace data generated by WebSphere MQ goes to SYSTEM.ADMIN.ACTIVITY.QUEUE.
Why is the Average Response Time of the Queue Put operation under the WebSphereMQ node greater than that of the Backend node?
The time difference is due to the additional processing logic (involving the tracers) for the Queue Put operation performed under the WebphereMQ node. When cross-process transaction tracing is turned off, the Average Response Time of the Queue Put operation under the WebSphereMQ node and Backend node remains the same.
How do I interpret the Total Duration column in the Transaction Trace Viewer window?
The Total Duration column indicates the total duration taken by your MQ transaction. For example, if your application puts a message into a queue and read the response from the reply to queue; traces will be generated for the Java component and MQ components. Suppose your application puts a message at 12:05:01 and the last MQ trace appears in the Transaction Trace Viewer window at 12:06:01, then your total transaction time is 60 seconds or 1 min. This is reflected in the Transaction Trace Viewer window for each trace in the transaction.
What properties do I need to configure in my EM to see the Total Duration column?
To configure EM to view the Total Duration column, add the following properties in the <Introscope Home>\config\IntroscopeEnterpriseManager.properties file:
introscope.workstation.transactiontracer.showTotalDuration=true
introscope.workstation.transactiontracer.showTotalDuration.sumAllTraceComponents=true
229
User Guide
I set the Activity Recording option to “Queue” on a z/OS Queue Manager, but restarting the Queue Manager changes it back to “Message”. Why does this happen; how does this affect transaction tracing?
On z/OS, a Queue Manager on startup refers to the config setup in the start-up job. If the config has the Activity Recording set to “Message”, such as,
ROUTEREC( MSG ) ACTIVREC( MSG ) + then the Activity Recording for that Queue Manager is always set to “Message” after the Queue Manager is restarted. Because of this, transaction tracing does not occur for that Queue Manager, that is, traces for remote queues do not appear for that Queue Manager.
I see lot of Backends data in the transaction trace viewer. I am not interested in this information. How can I disable the Backends information?
To disable the Backends data from appearing in the transaction trace viewer and the Investigator tree, open the PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbd file in the \wily directory and comment all the directives containing Backends|WebSphereMQ on {hostname}.
230 Frequently Asked Questions
PowerPack for WebSphere MQ Connectors and Messaging System
Troubleshooting 231
APPENDIX E
Troubleshooting
This appendix provides solutions for troubleshooting issues that you may encounter in PowerPack for MQ. The following table lists the errors, the probable causes of the errors, and the troubleshooting steps:
Errors in Log/Console Cause of the error Troubleshooting steps
[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.TracerDriverThread] MQMonitor: For configuration instance <QueueManager name>@localhost and the drivers(manager,manager) an error occured in sending query to MQ. The target MQ (localhost:19100) may be down. Reason code 2035 MQRC_NOT_AUTHORIZED
The user running the MQMonitor agent does not have adequate permissions to run the MQMonitor agent and connect to the Queue Manager.
Do one of the following:If the server connection channel used by the MQMonitor agent is CLIENT.WILY and the MCA user ID is set to user Wily, then the user “Wily” must be made member of mqm group, so that the MQMonitor agent can connect to the Queue Manager without any problem.Leave the MCA user ID blank so that the user ID is set to a default value of MQADMIN by the the PCF APIs, and hence becomes part of the mqm group.
[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.TracerDriverThread] MQMonitor: For configuration instance <QueueManager name>@<hostname> and the drivers(queue,queue,queue,queue,queue,queue) an error occured in sending query to MQ. The target MQ (localhost:3414) may be down. Reason code 2397 MQRC_JSSE_ERROR
Indicates that the truststore or keystore paths or passwords provided in the MQMonitor.properties file are incorrect. Can also indicate a problem with creating or exchanging the certificates between the WebSphere MQ server and client (MQMonitor agent) such as Certificate expiry.
In the IntroscopeAgent.profile file under MQMonitor properties directory, remove the comment ‘#’ for the following line: #log4j.logger.com.wily.powerpack.websphereMQ.agent.MQMonitor.TracerDriverThread=DEBUG
This displays the SSL handshake debug statements which will have details such as truststore path, keystorepath certificates used and their expiry dates. This information is useful to get to root of the JSSE Error.
232 Troubleshooting
PowerPack for WebSphere MQ Connectors and Messaging System
[ERROR]
TraceManager.startUp ClassNotFoundException: Activity report parsing classes are not available. Make sure to have PCF JAR file from latest MS0B support pack.
Incorrect version of PCF JAR file was used.
Ensure that you use the com.ibm.mq.pcf-6.1.jar file in the ms0b.zip file. For more information, see Obtain third-party libraries on page 17.
[ERROR]sun.io.MalformedInputException at sun.io.ByteToCharUTF8.convert(ByteToCharUTF8.java(Compiled Code))
Locale specific environment variable contains suffix ".UTF-8"
Perform the following steps on all UNIX-flavored operating systems:
1 Check for locale-specific environment variables such as LANG, LC_ALL. You can retrieve these details by running the "locale" command.
2 Remove the suffix .UTF-8 from the locale-specific environment variables, if this suffix exists.
3 For example, change LANG=en_US.UTF-8 to LANG=en_US
4 Start the MQMonitor agent.
[DEBUG] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] User <userName> is not authorized to connect to queue manager <ConfigMgrQmgr> (MQ reason code 2035 while trying to connect)
The MQMonitor agent user is not authorized to connect to the Configuration Manager’s Queue Manager.
Perform the following steps:
1 Apply the allmqi permission on Queue Manager of Configuration Manager using the following command: setmqaut -m <CMPQMName> -
t qmgr -p <userName@DomainName> +allmqi
2 Apply the put permission on the SYSTEM.BROKER.CONFIG.QUEUE queue of the same Queue Manager using the following command: setmqaut -m <CMPQMName>-n
SYSTEM.BROKER.CONFIG.QUEUE -t queue - p <userName@DomainName> +put
Errors in Log/Console Cause of the error Troubleshooting steps
233
User Guide
[DEBUG] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] ConfigManagerProxy information was not received from the Configuration Manager. Either the Configuration Manager is not available or the user 'userName\MachineName' does not have authority to view the object. (UUID='', required attribute='name')
[FATAL] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] Configuration Manager is not initialized.
Either the Configuration Manager is not available or the user 'hostname\username' does not have authority to view the object. (UUID='', required attribute='name').
Perform the following steps:
1 Check the MBMonitor.properties file. Also, check the CMP credentials.
2 Include the user of the MQMonitor agent into the ACL entry of the Configuration manager. To include the user into ACL entry, use following command and restart the Configuration manager and the MQMonitor agent.mqsicreateaclentry
<ConfigurationManagerName> -u <user> -m <machine> -x F –p
[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.BrokerStatistics] MQJMS1111: JMS1.1 The required Queues/Publish Subscribe services are not set up {0}
JMS Broker Queue Manager does not have the prerequisite queues for Pub/Sub.
Create all prerequisite JMS queue on JMS Broker Queue Manager using the MBMonitorJMSQueues.mqsc script and restart the MQMonitor agent.
runmqsc <QMName> <MBMonitorJMSQueues.mqsc
Errors in Log/Console Cause of the error Troubleshooting steps
234 Troubleshooting
PowerPack for WebSphere MQ Connectors and Messaging System
[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeMsgflowStatistics] MQJMS2013: invalid security authentication supplied for MQQueueManager.
JMS Broker Queue manager does not have suitable user permission.
Perform the following steps:
Stop the MQMonitor agent and modify the privileges of Queue Manager of JMS Broker using the following commands:
1 Apply the allmqi permission on Queue Manager as follows: setmqaut -m <JMSQMName> -t
qmgr -p <userName@DomainName> +allmqi
2 Apply the allmqi permission on all JMS queues (all JMS queue name starts with SYSTEM.JMS.*) setmqaut -m <JMSQMName> -n
<NameOfJMSQueue> -t queue -p <userName@DomainName> +allmqi
3 If MQMonitor user is not domain user, then create the same user in the MQ server and give privileges to this user. In this case, give the name of user without specifying domain name with user name. setmqaut -m <JMSQMName> -t
qmgr -p <userName> +allmqi
After changing privileges on the Queue Manager, refresh the security or restart the Queue Manager. Also, restart the MQMonitor agent.
[FATAL] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] Configuration Manager is not initialized.
[FATAL] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] Start the Configuration Manager and run MB Agent again.
Configuration Manager is not available.
Stop the MQMonitor agent and turn on Configuration Manager using following command:
mqsistart <ConfigurationManagerName>
Errors in Log/Console Cause of the error Troubleshooting steps
235
User Guide
[INFO] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeMsgflowStatistics] No Execution groups to monitor.
[INFO] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.BrokerStatistics] No Execution groups to monitor.
[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.ExecutionGroupTracer] Statistics for all Execution groups are missing. MB Agent probably lost connection.
[INFO] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.ExecutionGroupTracer] MB Agent restart will be preformed now.
In the MBMonitor.properties file, the statistics.broker.list property has been set to a broker but, at the same time no execution groups have been specified for monitoring on that broker using the <BROKER>.executiongroup property.
Check the values of the statistics.broker.list and <BROKER1>.executiongroup properties. If statistics.broker.list is set to any value other than all, then for the same broker name , <BROKER1>.executiongroup must have some value.
For example:
statistics.broker.list=amqbroker_ca amqbroker_ca.executiongroup=amqbroker_ca_exegrp
where amqbroker_ca is a name of broker that user wants to monitor and amqbroker_ca_exegrp is the execution group defined in it.
Errors in Log/Console Cause of the error Troubleshooting steps
236 Troubleshooting
PowerPack for WebSphere MQ Connectors and Messaging System
[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.ExecutionGroupTracer] Statistics for all Execution groups are missing. MB Agent probably lost connection.
[INFO] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.ExecutionGroupTracer] MB Agent restart will be performed now.
Message Flow statistics and Broker statistics are not enabled for the execution groups on WebSphere MB.
Check if Message flow statistics and Broker Statistics are turned on using IBM commands. See the Configure WebSphere MB Section of this user documentation for more information on how to enable Message Flow statistics and Broker Statistics.
[WARN]
[Manager.Agent] The Agent WebSphere MQ and Message Broker Agent is reporting too many metrics (current=50000, max=50000). New metrics will not be accepted
The metrics reported by the MQMonitor agent are clamped by the EM as it is sending more than 50000 metrics. Because of this, no new metrics will be reported by the EM.
Do one of the following:Open the IntroscopeEnterpriseManager.properties file and increase the limit for the number of metrics that an agent can report. You can set this by editing the property:introscope.enterprisemana
ger.agent.metrics.limit=50000
Restart the EM.Lower the monitoring level of the WebSphere MQ objects such as Queue Managers, Queues, Channels, and z/OS specific components such as Channel Initiators, PageSets, and Logs. For example, to lower the monitoring level for queues to the Minimum level, set the property as:<QueueManager
name>@localhost.monitor.queue=minimum
Restart the MQMonitor agent.
Errors in Log/Console Cause of the error Troubleshooting steps
Support for IPv6 Environment 237
APPENDIX F
Support for IPv6 Environment
This appendix describes how you can configure the MQMonitor agent and the MQ Java Connectors to connect to the Introscope EM in an IPv6 environment. The appendix also describes how you can add support for WebSphere MQ and WebSphere MB in the IPv6 environment.
Connect to the Introscope EM in an IPv6 environment
You can connect to the Introscope EM in an IPv6 environment by configuring the MQMonitor agent and the MQ Java Connectors.
MQMonitor agent
In a pure IPv6 Java environment, you must configure the MQMonitor agent with the java.net.preferIPv6Addresses property to display IPv6 addresses for the MQMonitor agent in the Investigator tree.
To configure the MQMonitor agent:
Set the property -Djava.net.preferIPv6Addresses=true in the MQMonitor startup script as shown below:
On Windows, update the startMQMonitor.bat file as:
%JAVA_HOME%\bin\java -Xms4m -Xmx512m -cp %CLASSPATH% -Dcom.wily.introscope.agentProfile=.\properties\IntroscopeAgent.profile -DProperties=.\properties\ com.wily.powerpack.websphereMQ.agent.MQMonitor.MQMonitor -Djava.net.preferIPv6Addresses=true
On UNIX, update the startMQMonitor.sh with the same argument specified above.
The Investigator will then display the full IPv6 IP address under *SuperDomain* > <hostname> > WebSphere MQ and Message Broker > WebSphere MQ and Message Broker Agent > Host:IP Address.
238 Support for IPv6 Environment
Local Product
» Note If the IPv6 address is not mentioned in the hosts file of the machine on which the MQMonitor agent is running, it displays 0:0:0:0:0:0:0:1.
MQ Java Connectors
To configure the MQ Java Connectors:
Follow the steps described in the Introscope 8.0.3.0 Release Notes to enable IPV6 addresses for the MQ Java Connectors.
Support for WebSphere MQ and WebSphere MB in an IPv6 environment
If WebSphere MQ and WebSphere MB are in an IPv6 environment, the relevant IPv6 addresses can be provided in the MQMonitor.properties and MBMonitor.properties files. For example, to monitor a Queue Manager QMGR1 that is configured on an IPv6 machine, add the following lines to your MQMonitor.properties file:
mq.monitor.list=QMGR1
QMGR1.host=2002:9b23:2d7b:0:20f:1fff:fe7e:59c4
» Note The following configuration does not work:
mq.monitor.list=QMGR1@2002:9b23:2d7b:0:20f:1fff:fe7e:59c4
Glossary 239
GLOSSARY
Glossary
backout
When errors occur in a Message Broker Message Flow, a message rolls back and is backed out onto the input queue. Each of these events is called a backout.
coordinated transaction
Message flows execute within a globally coordinated transaction. In coordinated transaction mode, either all or none of the changes associated with one message are accepted.
coupling facility
On z/OS, a special logical partition that provides high-speed caching, list processing, and locking functions.
cross-process transaction
A cross-process trasaction is a transaction that spans all Java and non-Java processes
in doubt
A message queue channel is said to be in doubt when the sending Message Channel Agent is waiting for an acknowledgement of receipt for a batch of messages. It is not in doubt at all other times, including the period during which messages are being sent but before an acknowledgment has been requested.
Java trace
A Java trace is a trace generated by the MQ Java Connector agent.
handshake
The communication between the MQMonitor agents and MQ Java Connector agents is called a handshake. You can perform handshake by creating a queue (called handshake queue) on an existing Queue Manager or a new Queue Manager, that is accessible from all application servers and MQMonitor agents.
240 Glossary
CA Wily Introscope PowerPack for WebSphere MQ Connectors and Messaging System
message channel agent (MCA)
A program that transmits prepared messages from a transmission queue to a communication link, or from a communication link to a destination queue.
MQ Trace
An MQ trace is a trace generated by the MQMonitor agent.
queue depth
The number of messages on a queue. Maximum queue depth is defined for each queue and is measured as a percentage. When a queue reaches this maximum, no more messages can be put on it, leading to performance problems. Therefore, increases in queue depth are an indication of possible performance problems.
retry, long/short
WebSphere administrators can specify the maximum number of times a channel tries to allocate a session to its partner; this can be stated using two variables, a long retry count (LONGRTY) and a short retry count (SHORTRTY). If the initial allocation attempt fails, the short retry count number is decremented and the channel retries the remaining number of times. If it still fails, it retries a long-retry-count number of times with an interval of long retry interval between each try. If it is still unsuccessful, the channel closes down.
timeout
A delay in sending a message into a message flow after it has been received.
Index 241
INDEX
Index
Aagent directory 10aggregated metrics 125, 127, 147, 148, 182,
183, 184, 185, 189application server host 10
BBroker Statistics 35
Cchannels 71, 81CMP (Configuration Management Proxy) 34Compute Node 84configuration
delay times 37IntroscopeAgent.profile 41JCA Connection Pool 55MBMonitor.properties 33MQ Events 23MQMonitor.properties 20WebSphere MB 64
configuring MQMonitor agent 20Console 67
Ddashboard colors 76dashboards 68, 81
MessageBroker 118Overview dashboard 207, 210, 215
Dead Letter Queue 72, 162
EEnterprise Manager (EM)
host 71ErrorDetector 54Execution Group 72, 184, 185
Ffiltering metrics 30
Iinstallation
download software 11extract MQMonitor agent files 15Management Modules 56MQ Java Connectors 47MQMonitor agent 15
IntroscopeAgent.profile 41
Llast check 72, 163
MManagement Modules 56, 67, 109Message Broker 181message throughput 83metric data types 123metrics
aggregated 76Channel Initiator 169log metrics 174Message Broker 72, 181
Broker Queue Manager 194Broker statistics
Client and Neighbor statistics 186Wide Statistics 187
Configuration Manager 182Message Flow 188
Queue Manager 71, 146channels 148Configuration properties 153host status 147queues 164
242 Index
CA Wily Introscope PowerPack for WebSphere MQ Connectors and Messaging System
status 147Queue Manager Cluster 125
configuration properties 136workload balance 139
Queue Manager Cluster-Receiver Channel 132
Queue Manager Cluster-Sender Channel 132metrics sets 25, 124MQ Events 79
NNode Statistics 37
PPercent Queue Depth Variation 144PMI settings 56
QQueue Manager 73
metrics 146
Rrecommended metrics set 26
Sstarting the MQMonitor agent 43stopping the MQMonitor agent 43
Ttraffic lights 75troubleshooting 81
WWebSphere MB 64WebSphere Message Broker node 64
top related