APM_9.5--APM for IBM WebSphere MQ Guide

for IBM WebSphere MQ GuideRelease 9.5 CA Application Performance Management This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to as the “Documentation”) is for your informational purposes only and is subject to change or withdrawal by CA at any time. This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and CA. Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy. The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION “AS IS” WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. The use of any software product referenced in the Documentation is governed by the applicable license agreement and such license agreement is not modified in any way by the terms of this notice. The manufacturer of this Documentation is CA. Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors. Copyright © 2013 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies. CA Technologies Product References This document references the following CA Technologies products and features: ■ CA Application Performance Management (CA APM) ■ CA Application Performance Management ChangeDetector (CA APM ChangeDetector) ■ CA Application Performance Management ErrorDetector (CA APM ErrorDetector) ■ CA Application Performance Management for CA Database Performance (CA APM for CA Database Performance) ■ CA Application Performance Management for CA SiteMinder® (CA APM for CA SiteMinder®) ■ CA Application Performance Management for CA SiteMinder® Application Server Agents (CA APM for CA SiteMinder® ASA) ■ CA Application Performance Management for IBM CICS Transaction Gateway (CA APM for IBM CICS Transaction Gateway) ■ CA Application Performance Management for IBM WebSphere Application Server (CA APM for IBM WebSphere Application Server) ■ CA Application Performance Management for IBM WebSphere Distributed Environments (CA APM for IBM WebSphere Distributed Environments) ■ CA Application Performance Management for IBM WebSphere MQ (CA APM for IBM WebSphere MQ) ■ CA Application Performance Management for IBM WebSphere Portal (CA APM for IBM WebSphere Portal) ■ CA Application Performance Management for IBM WebSphere Process Server (CA APM for IBM WebSphere Process Server) ■ CA Application Performance Management for IBM z/OS® (CA APM for IBM z/OS®) ■ CA Application Performance Management for Microsoft SharePoint (CA APM for Microsoft SharePoint) ■ CA Application Performance Management for Oracle Databases (CA APM for Oracle Databases) ■ CA Application Performance Management for Oracle Service Bus (CA APM for Oracle Service Bus) ■ CA Application Performance Management for Oracle WebLogic Portal (CA APM for Oracle WebLogic Portal) ■ CA Application Performance Management for Oracle WebLogic Server (CA APM for Oracle WebLogic Server) ■ CA Application Performance Management for SOA (CA APM for SOA) ■ CA Application Performance Management for TIBCO BusinessWorks (CA APM for TIBCO BusinessWorks) ■ CA Application Performance Management for TIBCO Enterprise Message Service (CA APM for TIBCO Enterprise Message Service) ■ CA Application Performance Management for Web Servers (CA APM for Web Servers) ■ CA Application Performance Management for webMethods Broker (CA APM for webMethods Broker) ■ CA Application Performance Management for webMethods Integration Server (CA APM for webMethods Integration Server) ■ CA Application Performance Management Integration for CA CMDB (CA APM Integration for CA CMDB) ■ CA Application Performance Management Integration for CA NSM (CA APM Integration for CA NSM) ■ CA Application Performance Management LeakHunter (CA APM LeakHunter) ■ CA Application Performance Management Transaction Generator (CA APM TG) ■ CA Cross-Enterprise Application Performance Management ■ CA Customer Experience Manager (CA CEM) ■ CA Embedded Entitlements Manager (CA EEM) ■ CA eHealth® Performance Manager (CA eHealth) ■ CA Insight™ Database Performance Monitor for DB2 for z/OS® ■ CA Introscope® ■ CA SiteMinder® ■ CA Spectrum® Infrastructure Manager (CA Spectrum) ■ CA SYSVIEW® Performance Management (CA SYSVIEW) Contact CA Technologies Contact CA Support For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At http://ca.com/support, you can access the following resources: ■ Online and telephone contact information for technical assistance and customer services ■ Information about user communities and forums ■ Product and documentation downloads ■ CA Support policies and guidelines ■ Other helpful resources appropriate for your product Providing Feedback About Product Documentation If you have comments or questions about CA Technologies product documentation, you can send a message to [email protected]. To provide feedback about CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at http://ca.com/docs. Contents 7 Contents Chapter 1: IBM WebSphere MQ Monitoring 15 About the Extension for WebSphere MQ .................................................................................................................. 15 Extension for WebSphere MQ Components .............................................................................................................. 16 Chapter 2: Preparing to install 17 Verify System and Version Requirements .................................................................................................................. 17 Verify Server Connection and Access ......................................................................................................................... 17 Obtain Third-Party Libraries ....................................................................................................................................... 17 PCF JAR File ......................................................................................................................................................... 17 ConfigManagerProxy.jar ..................................................................................................................................... 18 j2ee.jar ................................................................................................................................................................ 18 Additional JAR Files ............................................................................................................................................. 18 Chapter 3: Installation 21 Install Enterprise Manager components on a new Enterprise Manager ................................................................... 21 Install Enterprise Manager components on an Existing Enterprise Manager ............................................................ 22 Install MQ Java Connector agent as a new installation .............................................................................................. 23 Install MQ Java Connector agent on an existing agent .............................................................................................. 24 Install MQMonitor agent ............................................................................................................................................ 24 Chapter 4: Configuration 27 Configure MQ Java Connector agent ......................................................................................................................... 27 Configure the MQMonitor to monitor WebSphere MQ Queue Managers ................................................................ 28 Configure the MQMonitor Agent for Third-Party Libraries ................................................................................ 28 Configure the MQMonitor Agent Properties ...................................................................................................... 30 Run the MQMonitor Agent ................................................................................................................................. 30 Configure the MQMonitor to monitor WebSphere Message Brokers ....................................................................... 30 Configure the MBMonitor.properties File for WebSphere MB 6.x ..................................................................... 31 Configure the MBMonitor_7.properties File for WebSphere MB 7.0 or 8.0 ...................................................... 31 Create JMS queues .............................................................................................................................................. 33 Set Security Requirements to Monitor an MQ object ................................................................................................ 34 Set Security Requirements for MB 6.x ....................................................................................................................... 35 Set Security Requirements to Monitor a Remote WebSphere MB 7.0 or 8.0 ............................................................ 36 Configure WebSphere MQ for Trace .......................................................................................................................... 37 Configure Tracing Automatically ......................................................................................................................... 37 8 for IBM WebSphere MQ Guide Configure Tracing Manually ................................................................................................................................ 39 Set the MCA User ID ............................................................................................................................................ 41 Configure handshake for Cross Process Transaction Tracing .............................................................................. 43 Configure WebSphere MQ to Publish Events ............................................................................................................. 44 Chapter 5: Additional Information 45 Turn On Queue Monitoring ........................................................................................................................................ 45 Configure Application Server When Java 2 Security is Enabled ................................................................................. 45 Share the wily Folder Across MQ Java Connector agents .......................................................................................... 46 Configure JCA Connection Pool .................................................................................................................................. 47 Configure SSL .............................................................................................................................................................. 48 How to Set Up Client-Server Communication Over SSL ...................................................................................... 49 Configure the Server ........................................................................................................................................... 49 Configure the Client ............................................................................................................................................ 50 Generate Personal Certificates ........................................................................................................................... 54 Configure CA APM ErrorDetector ............................................................................................................................... 54 Install the MQMonitor Agent as a Windows Service ................................................................................................. 56 Upgrade CA APM for IBM WebSphere MQ ................................................................................................................ 57 Configure MQ applications for SOA Dependency Map .............................................................................................. 58 Auto-discover Queue Managers ................................................................................................................................ 60 Set Auto Discovery Properties ............................................................................................................................ 60 View the Auto Discovered Queue Managers in the What's Interesting section ................................................. 63 Installation and Configuration in an EM Clustered Environment ............................................................................... 63 Chapter 6: Transaction Tracing 65 Cross-Process Transaction Tracing ............................................................................................................................. 65 Verify the Transaction Trace Configuration ............................................................................................................... 66 WebSphereMQ Cross Process Transaction Trace Health & Availability Dashboard .................................................. 66 Configure the Enterprise Manager for Trace ............................................................................................................. 69 Identifying a Slow Transaction ................................................................................................................................... 69 Transaction Trace with Trace Holding Duration Set to 0ms ................................................................................ 70 Transaction Trace with Holding Duration Set to a Value Other than 0ms .......................................................... 70 Enable or Disable MQ Traces ..................................................................................................................................... 71 Filter Queues for Transaction Trace ........................................................................................................................... 72 Trace Data Properties ................................................................................................................................................. 72 Chapter 7: Viewing Data Using the WebSphere MQ Extension 75 View Data ................................................................................................................................................................... 75 Console Dashboards ................................................................................................................................................... 75 MQ Dashboards in the Console .......................................................................................................................... 75 Contents 9 View Dashboards and Data ........................................................................................................................................ 76 Understanding the Metrics Tree ......................................................................................................................... 76 Show Investigator Dashboards and Data Displays .............................................................................................. 80 Aggregated Metrics ............................................................................................................................................. 81 WebSphereMQ Sample Report Templates ................................................................................................................ 84 Chapter 8: Dashboards 85 Management Modules ............................................................................................................................................... 85 WebSphere MQ Client and Server Dashboards ......................................................................................................... 85 WebSphere MQ Client and Server Overview Dashboard.................................................................................... 86 WebSphere MQ Client and Server Overview - Details Dashboard ..................................................................... 86 WebSphere MQ - Client Connections Dashboard ............................................................................................... 88 WebSphere MQ - Client Operations Dashboard ................................................................................................. 88 WebSphere MQ - Server Dashboard ................................................................................................................... 88 WebSphere Message Broker Dashboards .................................................................................................................. 88 WebSphere Message Broker Overview Dashboard ............................................................................................ 89 Other Message Broker Dashboards .................................................................................................................... 90 Message Broker Alerts ........................................................................................................................................ 91 Appendix A: MQAgent.properties File 93 mqmonitor.mqagent.id.list ........................................................................................................................................ 93 handshake.mqagent.id ............................................................................................................................................... 94 handshake.qm.host .................................................................................................................................................... 94 handshake.qm.port .................................................................................................................................................... 94 handshake.qm.channelname ..................................................................................................................................... 94 handshake.qm.character.set ...................................................................................................................................... 94 handshake.qm.ssl ....................................................................................................................................................... 95 handshake.qm.channel.ssl.cipherspec ....................................................................................................................... 95 handshake.queue ....................................................................................................................................................... 95 truststore.path ........................................................................................................................................................... 95 keystore.path ............................................................................................................................................................. 95 keystore.password ..................................................................................................................................................... 96 mqtracing.exclude.queues.regex ............................................................................................................................... 96 mq.autodiscovery.enabled ......................................................................................................................................... 96 mq.autodiscovery.queue ........................................................................................................................................... 97 Appendix B: MQMonitor.properties File 99 Specific MQ Data Section ........................................................................................................................................... 99 mq.monitor.list ................................................................................................................................................. 100 <Queue Manager>@<Host>.host ..................................................................................................................... 100 10 for IBM WebSphere MQ Guide <Queue Manager>@<Host>.port ..................................................................................................................... 100 <Queue Manager>@<Host>.channelname ...................................................................................................... 100 <Queue Manager>@<Host>.character.set ....................................................................................................... 101 <Queue Manager>@<Host>.delaytime ............................................................................................................ 101 <Queue Manager>@<Host>.report.static.freq ................................................................................................. 101 <Queue Manager>@<Host>.ssl ........................................................................................................................ 101 <Queue Manager>@<Host>.channel.ssl.cipherspec ........................................................................................ 102 truststore.path .................................................................................................................................................. 102 keystore.path .................................................................................................................................................... 102 keystore.password ............................................................................................................................................ 102 MQ Events Section ................................................................................................................................................... 102 <Queue Manager>@<Host>.qmgr.event.queue .............................................................................................. 103 <Queue Manager>@<Host>.event.destructive.get .......................................................................................... 103 <Queue Manager>@<Host>.performance.event.queue .................................................................................. 104 <Queue Manager>@<Host>.channel.event.queue .......................................................................................... 104 Special Settings Section ............................................................................................................................................ 105 Advanced Settings Section ....................................................................................................................................... 106 MQ Trace Related Properties Section ...................................................................................................................... 106 trace.dlq.activity.enabled ................................................................................................................................. 107 trace.polling.enabled ........................................................................................................................................ 107 trace.polling.interval ......................................................................................................................................... 108 trace.polling.retry.count ................................................................................................................................... 108 trace.dlq.flag.time ............................................................................................................................................. 108 handshake.mqagent.id ...................................................................................................................................... 108 handshake.qm.host ........................................................................................................................................... 109 handshake.qm.port ........................................................................................................................................... 109 handshake.qm.channelname ............................................................................................................................ 109 handshake.qm.character.set............................................................................................................................. 109 handshake.qm.ssl .............................................................................................................................................. 109 handshake.qm.channel.ssl.cipherspec .............................................................................................................. 110 handshake.queue .............................................................................................................................................. 110 trace.hold.maxduration .................................................................................................................................... 110 MQ Auto Discovery Related Properties Section ....................................................................................................... 110 mq.monitor.agent.id ......................................................................................................................................... 111 mq.autodiscovery.enabled ............................................................................................................................... 111 mq.autodiscovery.queue .................................................................................................................................. 111 mq.autodiscovery.properties.update ............................................................................................................... 111 Filters Section ........................................................................................................................................................... 111 <Queue Manager>@<Host>.filter.exclude.static ............................................................................................. 112 <Queue Manager>@<Host>.queue.filter.exclude.system ................................................................................ 112 <Queue Manager>@<Host>.queue.filter.exclude.dynamic ............................................................................. 112 <Queue Manager>@<Host>.queue.filter.includeonly.regex ............................................................................ 113 Contents 11 <Queue Manager>@<Host>.channel.filter.includeonly.regex ......................................................................... 113 <Queue Manager>@<Host>.pagesets.filter.includeonly.regex ........................................................................ 113 <Queue Manager>@<Host>.log.filter.includeonly.regex ................................................................................. 113 Appendix C: MBMonitor.properties File 115 CMP Connection Section .......................................................................................................................................... 115 configuration.manager.host ............................................................................................................................. 115 configuration.manager.queue.manager ........................................................................................................... 115 configuration.manager.port .............................................................................................................................. 116 MQ Connection Section ........................................................................................................................................... 116 Statistics Section ...................................................................................................................................................... 116 Broker (JMS) Connection Section ............................................................................................................................. 117 jms.broker.host ................................................................................................................................................. 117 jms.broker.queue.manager............................................................................................................................... 117 jms.broker.port ................................................................................................................................................. 117 Execution Group Section .......................................................................................................................................... 118 Node Statistics Section ............................................................................................................................................. 118 Delay Times Section ................................................................................................................................................. 118 Monitoring Level Settings Section ............................................................................................................................ 119 <brokername>.messageflow.statistics.............................................................................................................. 119 <brokername>.broker.statistics ........................................................................................................................ 120 Advanced Settings Section ....................................................................................................................................... 120 recommended.metrics.messageflow.statistics ................................................................................................. 120 recommended.metrics.broker.statistics ........................................................................................................... 120 SSL Configuration Section......................................................................................................................................... 121 cmp.ssl .............................................................................................................................................................. 121 jms.ssl ................................................................................................................................................................ 121 cmp.connection.ssl.cipherspec ......................................................................................................................... 121 jms.connection.ssl.cipherspec .......................................................................................................................... 121 truststore.path .................................................................................................................................................. 121 keystore.path .................................................................................................................................................... 122 keystore.password ............................................................................................................................................ 122 Appendix D: MBMonitor_7.properties File 123 CMP Connection Section .......................................................................................................................................... 123 mq.broker.monitor.list ...................................................................................................................................... 123 a.host ................................................................................................................................................................ 123 a.queue.manager .............................................................................................................................................. 124 a.port ................................................................................................................................................................. 124 MQ Connection Section ........................................................................................................................................... 124 Statistics Section ...................................................................................................................................................... 125 12 for IBM WebSphere MQ Guide Execution Group Section .......................................................................................................................................... 125 Node Statistics Section ............................................................................................................................................. 126 Delay Times Section ................................................................................................................................................. 126 Monitoring Level Settings Section ............................................................................................................................ 127 <brokername>.messageflow.statistics.............................................................................................................. 127 Advanced Settings Section ....................................................................................................................................... 127 recommended.metrics.messageflow.statistics ................................................................................................. 128 SSL Configuration Section......................................................................................................................................... 128 .ssl ..................................................................................................................................................................... 128 broker.connection.ssl.cipherspec ..................................................................................................................... 128 jms.connection.ssl.cipherspec .......................................................................................................................... 128 truststore.path .................................................................................................................................................. 128 keystore.path .................................................................................................................................................... 129 keystore.password ............................................................................................................................................ 129 Appendix E: Metrics Reference 131 General Metric Characteristics ................................................................................................................................. 131 Metric Display Sets ............................................................................................................................................ 132 Queue Manager Cluster Metrics .............................................................................................................................. 132 Aggregate Clusters Status Metrics .................................................................................................................... 133 Top Level Repository Trees ............................................................................................................................... 133 Workload Balance Metrics ................................................................................................................................ 147 Queue Manager Metrics .......................................................................................................................................... 153 Top Level Queue Manager Aggregated Metrics ............................................................................................... 153 Channel Metrics ................................................................................................................................................ 155 Configuration Properties Metrics ...................................................................................................................... 159 Transmission Queue Metrics ............................................................................................................................ 169 Last Check Metrics ............................................................................................................................................ 169 Queue Metrics................................................................................................................................................... 170 Channel Initiator Metrics .................................................................................................................................. 178 Log Metrics ........................................................................................................................................................ 179 Usage Metrics ................................................................................................................................................... 182 Queue Manager Status Metrics ........................................................................................................................ 184 Message Broker Metrics........................................................................................................................................... 186 Configuration Manager Aggregate Totals ......................................................................................................... 186 Broker Properties and Aggregate Totals ........................................................................................................... 187 Execution Groups Metrics ................................................................................................................................. 187 Find MQ Java Connector Metrics ............................................................................................................................. 199 Operational Groups ........................................................................................................................................... 199 Backend Metrics ................................................................................................................................................ 199 Instance Counts Metrics .................................................................................................................................... 200 Contents 13 JCA Node Metrics .............................................................................................................................................. 200 WebSphereMQ Node Metrics ........................................................................................................................... 201 ErrorDetector Metrics ....................................................................................................................................... 203 Appendix F: JCA/JMS Operational Groups 205 JCA Operational Groups ........................................................................................................................................... 205 JCA Queue Manager Operations ....................................................................................................................... 206 JCA Queue Operational Groups ........................................................................................................................ 209 JMS Operational Groups .......................................................................................................................................... 209 JMS Queue Manager Operational Groups ........................................................................................................ 210 JMS Queue/Topic Operational Groups ............................................................................................................. 213 Appendix G: Performance and Sizing 215 MQMonitor Agent Background ................................................................................................................................ 215 WebSphere MQ Sizing .............................................................................................................................................. 215 Sizing Your Enterprise Manager ........................................................................................................................ 216 Sizing Your MQMonitor Agent .......................................................................................................................... 216 Sample MQMonitor Agent Sizing Table ............................................................................................................ 216 WebSphere MB Sizing .............................................................................................................................................. 220 Sizing Your MQMonitor Agent for WebSphere MB .......................................................................................... 221 Sample MQMonitor Agent Sizing Table for WebSphere MB ............................................................................ 221 Appendix H: Frequently Asked Questions 225 Alerts and Dashboards ............................................................................................................................................. 225 Unexpected Increase in Queue Depth ..................................................................................................................... 226 Installation ................................................................................................................................................................ 227 Metrics ..................................................................................................................................................................... 228 Queues ..................................................................................................................................................................... 229 Transaction Tracing .................................................................................................................................................. 230 Appendix I: Troubleshooting 233 Errors and Troubleshooting Steps ............................................................................................................................ 233 Appendix J: Support for IPv6 Environment 243 Connect to the Enterprise Manager in an IPv6 Environment .................................................................................. 243 Configure the MQMonitor Agent ...................................................................................................................... 243 MQ Java Connectors ......................................................................................................................................... 244 Support for WebSphere MQ and WebSphere MB in an IPv6 Environment ............................................................. 244 14 for IBM WebSphere MQ Guide Index 245 Chapter 1: IBM WebSphere MQ Monitoring 15 Chapter 1: IBM WebSphere MQ Monitoring The extension 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 section contains the following topics: About the Extension for WebSphere MQ (see page 15) Extension for WebSphere MQ Components (see page 16) About the Extension for WebSphere MQ An extension of CA Introscope®, the flagship web application management solution, CA APM for IBM WebSphere MQ lets you monitor the performance of WebSphere MQ and WebSphere MB. CA APM for IBM WebSphere MQ provides metrics that you can use to monitor the health and availability of WebSphere MQ-connected web applications. The metrics also help you quickly isolate the source of WebSphere MQ-related and WebSphere MB-related performance problems. CA APM for IBM WebSphere MQ lets you perform the following actions: ■ 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. CA APM for IBM WebSphere MQ provides Management Modules with preconfigured dashboards and performance-triggered alerts to monitor: ■ Critical messages and queues for WebSphere MQ ■ Health and availability of various WebSphere MB components CA APM for IBM WebSphere MQ ensures high availability of all WebSphere MQ-connected Java web applications. Extension for WebSphere MQ Components 16 for IBM WebSphere MQ Guide Extension for WebSphere MQ Components CA APM for IBM WebSphere MQ consists of the following components: ■ MQMonitor agent The MQMonitor agent reports data on the performance of WebSphere MQ resources, such as queues and channels to CA Introscope®. CA Introscope® then displays the data as metrics under the following nodes in the 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 Investigator displays Cluster Queue Managers with their associated queues and channels so that you can monitor cluster performance. Multi-instanced cluster queues appear under the Workload Balance directory. ■ MQ Java Connectors The MQ Java Connectors monitor the WebSphere MQ classes (both Connector and JMS) used for communicating with WebSphere MQ from a web application that is 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 Investigator tree under the WebSphereMQ node. ■ Management Modules and Enterprise Manager extensions The Management Modules contain preconfigured dashboards and alerts that CA Introscope® uses to display WebSphere MQ and WebSphere MB metrics in graphical form. The component also includes dashboards for the Investigator and JavaScript calculators and Enterprise Manager extensions which aggregate metric data for display in the Investigator. You can configure the dashboards and alerts to notify operations and application-support personnel and WebSphere MQ administrators. Such alerts can be used to address potential WebSphere MQ and WebSphere MB issues before they become application performance bottlenecks. Chapter 2: Preparing to install 17 Chapter 2: Preparing to install This chapter contains the prerequisites that must be satisfied before you begin the installation of the CA APM for IBM WebSphere MQ. This section contains the following topics: Verify System and Version Requirements (see page 17) Verify Server Connection and Access (see page 17) Obtain Third-Party Libraries (see page 17) Verify System and Version Requirements Ensure your version of CA APM for IBM WebSphere MQ is listed in the APM Compatibility Guide. Verify Server Connection and Access To ensure proper server connection, verify the following: ■ A WebSphere MQ command server that is defined and running on the Queue Manager. ■ A Server Connection channel that is defined on the Queue Manager. Note: Contact your WebSphere MQ specialist for details about configuring the Queue Manager. ■ Network access through firewalls, for the MQ Monitor Agent. Obtain Third-Party Libraries To run the MQMonitor agent, obtain third-party JAR files and configure the MQMonitor agent. PCF JAR File Download the PCF jar file from the www.ibm.com support and downloads section. Obtain Third-Party Libraries 18 for IBM WebSphere MQ Guide ConfigManagerProxy.jar The ConfigManagerProxy.jar is in the IBM Message Brokers directory that is installed on the computer that has the MQMonitor agent installation: The directory structure is as follows: ■ For IBM Message Brokers <Version_Number>: <IBM Message Brokers v<Version_Number> Installation Directory>/<Version_Number>/classes j2ee.jar Valid for IBM Message Broker Toolkit 6.x: After installing the IBM Message Broker Toolkit on the same computer as the MQMonitor agent, you can obtain the j2ee.jar file from the following directory of the IBM Message Broker Toolkit installation: ■ For IBM Message Broker Toolkit 6.0: <IBM Message Brokers Toolkit v6.0 Installation Directory>/runtimes/base_v6_stub/lib ■ For IBM Message Broker Toolkit 6.1: <IBM Message Brokers Toolkit v6.1 Installation Directory>/runtimes/wsdk/j2ee14 Alternatively, you can find the j2ee.jar file in the /lib directory of the J2EE SDK installation. You can also download J2EE SDK from http://www.oracle.com, subject to the accompanying license terms. Additional JAR Files The following files are required for WebSphere MQ 6.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 Obtain Third-Party Libraries Chapter 2: Preparing to install 19 The following files are required for WebSphere MQ 7.0 and 7.1: 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 6.x and 7.0 or 7.1, then use the WebSphere MQ 7.0 or 7.1 library files. Alternatively, to obtain the files install the MQ client software from www.ibm.com. Note: Install the WebSphere MQ client on the same computer as the MQMonitor agent. Chapter 3: Installation 21 Chapter 3: Installation You can install the Enterprise Manager components of the Java Connectors by using the Enterprise Manager installer. You can install the agent for Application Server by using the agent installer. You can install the Standalone MQMonitor agent by using the Standalone agent installer. Note: To view the MQ components in the SOA Dependency Map, install CA APM for SOA. This section contains the following topics: Install Enterprise Manager components on a new Enterprise Manager (see page 21) Install Enterprise Manager components on an Existing Enterprise Manager (see page 22) Install MQ Java Connector agent as a new installation (see page 23) Install MQ Java Connector agent on an existing agent (see page 24) Install MQMonitor agent (see page 24) Install Enterprise Manager components on a new Enterprise Manager You can install the Enterprise Manager components by using the Enterprise Manager installer. Follow these steps: 1. Run the Enterprise Manager installer. 2. In the Select Monitoring Options screen, select CA APM for IBM WebSphere MQ and IBM WebSphere Message Broker. 3. Verify that the following files are present: ■ In <EM_Home>/product/enterprisemanager/plugins: – com.wily.powerpack.wmq.ddtv.typeview.jar – com.wily.powerpack.wmq.em.extension.jar ■ In <EM_Home>/config/modules: – WebSphereMQ_Client_And_Server.jar – WebsphereMQ_CPT_Health_And_Availability.jar – WMBManagementModule.jar Install Enterprise Manager components on an Existing Enterprise Manager 22 for IBM WebSphere MQ Guide ■ In <EM_Home>/scripts: – Broker-Agent-MQConnectionStatus.js – Cluster-Agent-MQConnectionStatus.js – Clusters-ChannelInstanceCounts.js – Clusters-Channels.js – Clusters-QueueManager.js – Clusters-Queues.js – Clusters-SingleClusterAggregation.js – Clusters-TopLevelAggregation.js – MBMQ-ChannelIndoubtAggregation.js – MBMQ-ChannelInstanceCountsAggregation.js – MBMQ-PagesetStatusAggregation.js – MBMQ-QueueManagerAggregation.js – MBMQ-QueuesAggregation.js – MQ-ChannelIndoubtAggregation.js – MQ-ChannelInstancesCountsAggregation.js – MQ-ConnectionStatusAggregation.js – MQ-HostNameAggregation.js – MQ-PagesetStatusAggregation.js – MQ-QueueManagerAggregation.js – MQ-QueuesAggregation.js – MQ-TopLevelAggregation.js Enterprise Manager components have been installed on a new Enterprise Manager. Install Enterprise Manager components on an Existing Enterprise Manager If you are using the same Enterprise Manager for different agents, the Enterprise Manager components of all the extensions are already installed in the <EM_Home>/examples folder when you run the installer for the first time. You can install the enterprise manager components of the extension on an existing Enterprise Manager. Install MQ Java Connector agent as a new installation Chapter 3: Installation 23 Follow these steps: 1. Copy the contents of <EM_Home>/examples/MQMonitorForWebsphereMQ to the <EM_Home> installation directory. 2. Restart the Enterprise Manager. Enterprise Manager components have been installed on an existing Enterprise Manager. Install MQ Java Connector agent as a new installation The agent installer lets you install the MQ Java Connector Agent for Application Server. Follow these steps: 1. Run the agent installer specific to your application server. 2. Select CA APM for IBM WebSphere MQ and IBM WebSphere Message Broker during the installation. 3. Verify that the following files are present: ■ In <AppServer_Home>/wily/common: – MQAgent.properties – MQAppSupport.jar ■ In <AppServer_Home>/wily/core/config: – webspheremq.pbl – webspheremq.pbd – webspheremq_errors.pbd – webspheremq_instancecounts.pbd – webspheremq-extra.pbd ■ In <AppServer_Home>/wily/core/ext/: – MQNameFormatter.jar MQ Java Connector agent has been installed as a new installation. Install MQ Java Connector agent on an existing agent 24 for IBM WebSphere MQ Guide Install MQ Java Connector agent on an existing agent You can install MQ Java connector agent on an existing agent. Follow these steps: 1. Copy the webspheremq.pbl and its associated pbds from <AppServer_Home>/wily/examples/PowerpackforWebsphereMQ/config to the <AppServer_Home>/wily/core/config directory 2. Open the IntroscopeAgent.profile file that is located in the <AppServer_Home>/wily/core/config directory. 3. Go to the introscope.autoprobe.directivesFile property. 4. Add the webspheremq.pbl as follows: introscope.autoprobe.directivesFile=websphere-typical.pbl,hotdeploy,websphere mq.pbl 5. Open the webspheremq.pbl and uncomment any additional pbds that you require for further instrumentation. For example, webspheremq_errors.pbd. 6. Copy the MQNameFormatter.jar from <AppServer_Home>/wily/examples/PowerpackforWebsphereMQ/ext to <AppServer_Home>/wily/core/ext. 7. Restart the Application Server. MQ Java Connector agent has been installed on an existing agent. Install MQMonitor agent You can install the agent for MQMonitor by using the Standalone agent installer. Follow these steps: 1. Run the Standalone agent installer and select CA APM for IBM WebSphere MQ Connectors and Messaging Systems during the installation. 2. Specify <MQMonitor installation directory> as the installation directory. 3. Specify the Enterprise Manager host and port. All the agent files are copied to the <MQMonitor installation directory> directory. Install MQMonitor agent Chapter 3: Installation 25 4. Verify that the following files are present: ■ In <MQMonitor installation directory>/lib: – Agent.jar – jline-0.9.94.jar ■ In <MQMonitor installation directory>/tools: – mqConfigurationSetup.bat (Windows) or mqConfigurationSetup.sh (UNIX) ■ In <MQMonitor installation directory>/ext: – Supportability-Agent.jar ■ In <MQMonitor installation directory>/properties: – MBMonitorJMSQueues.mqsc – IntroscopeAgent.profile – MBMonitor.properties – MBMonitor.properties.template – MQMonitor.properties – MQMonitor.properties.template – MBMonitor_7.properties ■ In <MQMonitor installation directory>: – MQMonitor.jar – mqPwdEncryptor.bat (Windows) or mqPwdEncryptor.sh (UNIX) – startMQDiscovery.bat (Windows) or startMQDiscovery.sh (UNIX) – startMQMonitor.bat (Windows) or startMQMonitor.sh (UNIX) and stopMQMonitor.sh (UNIX) – WILYRACF.JCL MQMonitor agent has been installed. Chapter 4: Configuration 27 Chapter 4: Configuration This section contains the following topics: Configure MQ Java Connector agent (see page 27) Configure the MQMonitor to monitor WebSphere MQ Queue Managers (see page 28) Configure the MQMonitor to monitor WebSphere Message Brokers (see page 30) Set Security Requirements to Monitor an MQ object (see page 34) Set Security Requirements for MB 6.x (see page 35) Set Security Requirements to Monitor a Remote WebSphere MB 7.0 or 8.0 (see page 36) Configure WebSphere MQ for Trace (see page 37) Configure WebSphere MQ to Publish Events (see page 44) Configure MQ Java Connector agent MQ Java Connector monitors various Connectors, JMS classes, and methods that communicate with WebSphere MQ. Follow these steps: 1. If you have installed and enabled the extension, verify that the PBL file is added to the introscope.autoprobe.directivesFile property in the IntroscopeAgent.profile file that is located in the <AppServer_Home>/wily/core/config directory as follows: introscope.autoprobe.directivesFile=websphere-typical.pbl,hotdeploy,websphere mq.pbl Note: This example is in the case of a WebSphere Application Server where the WebSphere MQ pbl is appended to the websphere-typical.pbl. Configure the MQMonitor to monitor WebSphere MQ Queue Managers 28 for IBM WebSphere MQ Guide 2. Open the webspheremq.pbl and uncomment any additional pbds that you require for further instrumentation. For example, webspheremq_errors.pbd. 3. Specify the connection properties for the Enterprise Manager to which you want to send the metrics reported by the MQMonitor agent. Use the IntroscopeAgent.profile file to configure the following properties: introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT Specifies the Enterprise Manager host name or IP address. Default: localhost introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT Specifies the Enterprise Manager port. Default: 5001 MQ Java Connector agent has been configured. Note: For information about metric aging properties, see the CA APM Java Agent Implementation Guide. Configure the MQMonitor to monitor WebSphere MQ Queue Managers The MQMonitor agent provides information that is related to WebSphere MQ resources such as Queue Managers, Queues, and Channels, and 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. To configure the MQMonitor agent, perform the following steps: 1. Configure the MQMonitor agent for third-party libraries (see page 28). 2. Configure the MQMonitor agent properties (see page 30). 3. Run the MQMonitor agent (see page 30). Configure the MQMonitor Agent for Third-Party Libraries To run the MQMonitor agent, you edit the start script with the location of third-party JAR files (see page 17) on the MQMonitor agent host. Edit the start script, startMQMonitor.bat (Windows) or startMQMonitor.sh (UNIX), to modify the classpath with the actual path of the files. Configure the MQMonitor to monitor WebSphere MQ Queue Managers Chapter 4: Configuration 29 To monitor WebSphere MQ 6.0: ■ com.ibm.mq.jar ■ connector.jar ■ PCF JAR file (see page 17) To monitor WebSphere MQ 7.0: ■ 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 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 two PCF JAR files mentioned. Provide the path to these two JAR files in the MQMonitor agent start script. To monitor WebSphere MB 6.0 to 6.1 or MB 7.0: ■ com.ibm.mq.jar ■ com.ibm.mqjms.jar ■ PCF JAR file (see page 17) ■ dhbcore.jar ■ ConfigManagerProxy.jar ■ j2ee.jar ■ connector.jar Configure the MQMonitor to monitor WebSphere Message Brokers 30 for IBM WebSphere MQ Guide Configure the MQMonitor Agent Properties Locate the MQMonitor.properties file in the /MQMonitor/properties directory, and configure the properties to meet your requirements. Follow these steps: 1. List all the queue managers you want to monitor. mq.monitor.list=<QM1@hostname>,<QM2@hostname>,<QM3@hostname> 2. Provide the following information for all the queue managers listed: <QM1@host>.host <QM1@port>.port MQMonitor.properties file has been configured. Note: Depending on what you want to monitor, configure other properties in the MQMonitor.properties File (see page 99) files. For example, edit the MQMonitor.properties file to identify the queues whose MQ Events you want to monitor. Run the MQMonitor Agent To complete the configuration of the MQMonitor agent, run it. Follow these steps: 1. Verify that 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 tree, the WebSphere MB tree, or both appear in the Workstation tree under the node WebSphere MQ and Message Broker Agent. Configure the MQMonitor to monitor WebSphere Message Brokers Configure CA APM for IBM WebSphere MQ to monitor message brokers and to obtain the broker and message flow statistics for the message brokers. Configure the MQMonitor to monitor WebSphere Message Brokers Chapter 4: Configuration 31 Configure the MBMonitor.properties File for WebSphere MB 6.x You can configure the CA APM for IBM WebSphere MQ to monitor MB 6.x. Follow these steps: 1. Go to the /MQMonitor/properties directory and open the MBMonitor.properties file with a text editor. 2. Configure the following properties: configuration.manager.host Specifies the Configuration Manager Proxy (CMP) machine name or IP address. Example: configuration.manager.host=localhost configuration.manager.queue.manager Specifies the CMP Queue Manager name. Example: configuration.manager.queue.manager=WBRK6_DEFAULT_QUEUE_MANAGER configuration.manager.port Specifies the CMP Queue Manager port. Example: configuration.manager.port=2414 MBMonitor.properties file has been configured. Note: Depending on what you want to monitor, configure other properties in the MBMonitor.properties File (see page 115). Important! If you configure the MBMonitor.properties file for WebSphere MB 6.0 to 6.1, you cannot configure the CA APM for IBM WebSphere MQ to monitor message brokers for WebSphere MB 7.0 or MB 8.0. Enabling both configuration files causes WebSphere MB monitoring failure. Configure the MBMonitor_7.properties File for WebSphere MB 7.0 or 8.0 You can configure CA APM for IBM WebSphere MQ to monitor MB 7.0 and 8.0. Configure the MQMonitor to monitor WebSphere Message Brokers 32 for IBM WebSphere MQ Guide Follow these steps: 1. Go to the /MQMonitor/properties directory and open the MBMonitor_7.properties file with a text editor. 2. Provide a comma-separated list of unique identifiers for each broker you want to monitor. Set this property to start broker monitoring. For example: mq.broker.monitor.list=a,b 3. For each of the broker that is listed specify the following properties: ■ a.host Specifies the broker machine name or IP address ■ a.queue.manager Specifies the broker queue manager name. ■ a.port Specifies the broker queue manager port. MBMonitor_7.properties file has been configured. Note: Depending on what you want to monitor, configure other properties in the MBMonitor_7.properties File (see page 123). Configure the MQMonitor to monitor WebSphere Message Brokers Chapter 4: Configuration 33 Create JMS queues After configuring the MBMonitor.properties file or the MBMonitor_7.properties file, create JMS queues that use the JMS protocol. Follow these steps: 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 Queue Manager is the Queue Manager of the Configuration 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. The file contains a series of MQSC commands. 3. Execute the following command on your Message Broker host, where queueMgr_name is the name of the Queue Manager you identified in an earlier step. runmqsc queueMgr_name < MBMonitorJMSQueues.mqsc All the commands in the MBMonitorJMSQueues.mqsc file are executed. Set Security Requirements to Monitor an MQ object 34 for IBM WebSphere MQ Guide Set Security Requirements to Monitor an MQ object The following MQ permissions are required to monitor MQ objects from a remote computer. The user need not be part of the mqm group. Note: <QMGR>is the Queue Manager and mqgroup is the usergroup name. setmqaut -m <QMGR> -t qmgr -g mqgroup +connect +dsp +inq +crt setmqaut -m <QMGR> -n SYSTEM.DEFAULT.MODEL.QUEUE -t q -g mqgroup +get +browse +dsp setmqaut -m <QMGR> -n SYSTEM.ADMIN.COMMAND.QUEUE -t q -g mqgroup +get +browse +put +dsp +inq setmqaut -m <QMGR> -n SYSTEM.ADMIN.PERFM.EVENT -t q -g mqgroup +get +browse +dsp +inq setmqaut -m <QMGR> -n SYSTEM.ADMIN.QMGR.EVENT -t q -g mqgroup +get +browse +dsp +inq setmqaut -m <QMGR> -n SYSTEM.ADMIN.CHANNEL.EVENT -t q -g mqgroup +get +browse +dsp +inq setmqaut -m <QMGR> -n SYSTEM.ADMIN.ACTIVITY.QUEUE -t q -g mqgroup +get +inq +dsp setmqaut -m <QMGR> -n SYSTEM.DEAD.LETTER.QUEUE -t q -g mqgroup +get +inq +dsp +browse setmqaut -m <QMGR> -n '**' -t channel -g mqgroup +dsp setmqaut -m <QMGR> -n '**' -t q -g mqgroup +dsp setmqaut -m <QMGR> -n '**' -t namelist -g mqgroup +dsp setmqaut -m <QMGR> -n '**' -t clntconn -g mqgroup +dsp Set Security Requirements for MB 6.x Chapter 4: Configuration 35 Set Security Requirements for MB 6.x The following sections describe the minimum security settings that are needed for the MQMonitor agent for CMP, JMS, and PCF connections. To set the minimum security that is 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 permission 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: -x V Explanation: Gives view authority over Configuration Manager to the user. ■ Command component: -p Explanation: Adds access to the Configuration Manager Proxy, also known as "all resources" access control entry. Note: Either restart the Queue Manager or do a "refresh security" using the runmqsc command. Then restart the Configuration Manager after applying the security settings. To set the minimum security that is 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: Either restart the Queue Manager or do a "refresh security" using the runmqsc command after applying the security settings as explained in the preceding section. Set Security Requirements to Monitor a Remote WebSphere MB 7.0 or 8.0 36 for IBM WebSphere MQ Guide Set Security Requirements to Monitor a Remote WebSphere MB 7.0 or 8.0 If you configure your environment to report WebSphere MB 7.0 or 8.0, set the following minimum security requirements. Follow these steps: 1. Execute the following command on the queue manager of the broker. setmqaut -m <QMGR NAME> -t qmgr -p <userid> +all 2. Set allmqi permission for the following Queues that are part of the Broker Queue Manager: ■ SYSTEM.BROKER.ADMIN.QUEUE ■ SYSTEM.BROKER.ADMIN.REPLYTODM ■ SYSTEM.BROKER.ADMIN.STREAM ■ SYSTEM.BROKER.CONTROL.QUEUE ■ SYSTEM.BROKER.DEPLOY.REPLY ■ SYSTEM.BROKER.DEPLOY.QUEUE ■ SYSTEM.BROKER.DEPLOY.QUEUE ■ SYSTEM.BROKER.DEFAULT.STREAM ■ SYSTEM.ADMIN.COMMAND.QUEUE ■ SYSTEM.ADMIN.PERFM.EVENT ■ SYSTEM.ADMIN.QMGR.EVENT ■ SYSTEM.ADMIN.CHANNEL.EVENT ■ SYSTEM.ADMIN.ACTIVITY.QUEUE Use the following command: setmqaut -m <QMGR NAME> -n <QUEUE NAME> -p <userid> +allmqi 3. Set allmqi permission to the following JMS pub sub queues that are defined for the Broker Queue Manager during installation: ■ SYSTEM.JMS.ADMIN.QUEUE ■ SYSTEM.JMS.PS.STATUS.QUEUE ■ SYSTEM.JMS.REPORT.QUEUE ■ SYSTEM.JMS.MODEL.QUEUE ■ SYSTEM.JMS.ND.SUBSCRIBER.QUEUE ■ SYSTEM.JMS.ND.CC.SUBSCRIBER.QUEUE ■ SYSTEM.JMS.D.SUBSCRIBER.QUEUE Configure WebSphere MQ for Trace Chapter 4: Configuration 37 ■ SYSTEM.JMS.D.CC.SUBSCRIBER.QUEUE ■ SYSTEM.JMS.ND.SUBSCRIBER.WILY.MBMSGFLOW ■ SYSTEM.JMS.ND.SUBSCRIBER.WILY.MBBROKER Use the following command: runmqsc MB7QMGR < C:/MQMonitor/properties/MBMonitorJMSQueues.mqsc 4. Set allmqi permission to SYSTEM.BROKER.MB.TOPIC in the Broker Queue Manager using the following command: setmqaut -m <QUEUE MANAGER> -n SYSTEM.BROKER.MB.TOPIC -t top -p <userid> +allmqi 5. (optional) Restart the broker and queue manager. Configure WebSphere MQ for Trace You can use the mqConfigurationSetup tool to configure the WebSphere MQ system for trace. You can also configure the WebSphere MQ system for trace manually. Configure Tracing Automatically You can use the mqConfigurationSetup tool to automate the configuration for cross-process transaction tracing. The tool contains a batch file named mqConfigurationSetup.bat (Windows) or mqConfigurationSetup.sh (UNIX). The file is available in the /tools directory of the MQMonitor agent. Follow these steps: 1. Configure the MQMonitor.properties to monitor Queue Managers. 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. Configure WebSphere MQ for Trace 38 for IBM WebSphere MQ Guide 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 noninteractive 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/. 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 do 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 generates a report containing information about all the properties that were modified in the Queue Managers and queues. The tool saves the report to a file named changehistory.txt in the /tools directory of the MQMonitor agent. Important! To apply the changes, perform one of the following operations: Restart all active channels on the monitored Queue Managers Restart all the monitored Queue Managers. (except for z/OS) 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". More information: Configure the MQMonitor Agent Properties (see page 30) Configure WebSphere MQ for Trace Chapter 4: Configuration 39 Configure Tracing Manually You can manually configure the WebSphere MQ system for trace. Follow these steps: 1. Configure the Queue Managers as follows: a. Set the Activity recording property (see page 39). b. Configure SYSTEM.ADMIN.ACTIVITY.QUEUE (see page 40). 2. Set the handshake queue (see page 41). Set the Activity Recording Property For all the Queue Managers in WebSphere MQ that the MQMonitor agent monitors, set the value of the Activity recording property to Queue. This setting enables the Queue Managers to generate activity reports. All the activity reports are generated in SYSTEM.ADMIN.ACTIVITY.QUEUE of the same Queue Manager. 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 columns: ■ QMNAME(SOURCE) ■ ACTIVREC(MSG) To set the ACTIVREC property value to QUEUE, enter the command: alter QMGR ACTIVREC(QUEUE) Configure WebSphere MQ for Trace 40 for IBM WebSphere MQ Guide 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) Note: For more details about activity recording, see the IBM documentation. Important! Restart the Queue Manager MCAs after configuring the SYSTEM.ADMIN.ACTIVITY.QUEUE. Configure SYSTEM.ADMIN.ACTIVITY.QUEUE You can configure SYSTEM.ADMIN.ACTIVITY.QUEUE using the MQ Explorer. Follow these steps: 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. The SYSTEM.ADMIN.ACTIVITY.QUEUE has been configured. Alternatively, you can configure SYSTEM.ADMIN.ACTIVITY.QUEUE using the MQSC commands. Follow these steps: 1. To define SYSTEM.ADMIN.ACTIVITY.QUEUE (if not already defined), enter the following command: define QLOCAL(SYSTEM.ADMIN.ACTIVITY.QUEUE) USAGE (normal) DESCR('For Introscope Use') 2. To configure the SYSTEM.ADMIN.ACTIVITY.QUEUE, enter the following command: alter QLOCAL (SYSTEM.ADMIN.ACTIVITY.QUEUE) PUT (enabled) GET (enabled) DEFPSIST (no) SHARE DEFSOPT (SHARED) MAXDEPTH (999999999) 3. To verify the SYSTEM.ADMIN.ACTIVITY.QUEUE, enter the following command: display QLOCAL(SYSTEM.ADMIN.ACTIVITY.QUEUE) The SYSTEM.ADMIN.ACTIVITY.QUEUE has been configured. Configure WebSphere MQ for Trace Chapter 4: Configuration 41 Set the Handshake Queue Handshake refers to the communication between the MQMonitor agents and MQ Java Connector agents. You can perform the handshake by creating a queue (handshake queue) on an existing Queue Manager. You can also perform the handshake on a new Queue Manager that is accessible from all application servers and MQMonitor agents. To define a local queue, for example, 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 MQSC command defines the CA_WILY_HANDSHAKE queue with the put and get properties enabled, not persistent, and shareable. To verify the queue, enter the command: display QLOCAL(CA_WILY_HANDSHAKE) Set the MCA User ID MCA User ID indicates to the server who the client is connecting as (at program runtime). The clients connect to the server using sockets, which are listening for connections. When the connection is established, the server validates the authentication of the clients. If you do not specify the MCA User ID at connect time, the server uses the client user ID. By defining the MCA User ID in the channel definition you can override the privileges of the client user ID. To ensure that the trace data does not reach the Dead Letter Queue, and for the transaction trace to occur, set the MCA user ID. The following procedure describes how to set the MCA user ID. Note: The procedure is applicable for WebSphere MQ infrastructure that consists of Queue Managers of various WebSphere MQ platforms. The MQ traces for Queue Managers can be of different types. Configure WebSphere MQ for Trace 42 for IBM WebSphere MQ Guide 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, use one of the following procedures 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: 1. Identify the user that set by the Java application on the MQMessage. 2. Create the user on all WebSphere MQ machines. 3. Add the user to the group created by the WebSphere MQ installation on all platforms. 4. Restart the channels. If the Java application does not set the user ID of the WebSphere MQ Message, then perform the following steps to add a common user: 1. Create a common user for all WebSphere MQ machines. 2. Add the common user to the group created by the WebSphere MQ installation on all platforms. 3. 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>) 4. Restart the channels. Configure WebSphere MQ for Trace Chapter 4: Configuration 43 Configure handshake for Cross Process Transaction Tracing Configure the handshake feature for Cross Process Transaction Tracing. Handshake requires a common Queue Manager that is used for communication between the MQ Java agent and MQMonitor agent. 1. Configure the following properties in the MQAgent.properties file: ■ mq.crossprocesstracing.enabled = true ■ mqmonitor.mqagent.id.list = <MQMonitor handshake id> ■ handshake.mqagent.id = <unique id> ■ handshake.qm.host = <queue manager hostname> ■ handshake.qm.port = <port number> ■ handshake.queue= <queue name> 2. Configure the following handshake properties in the MQMonitor.properties file: ■ handshake.mqagent.id = <unique id> ■ handshake.qm.host = <queue manager hostname> ■ handshake.qm.port = <port no> ■ handshake.queue= <queue name> The properties have been configured for cross process transaction tracing. For more information about the properties, see the respective properties files. Note: The mqmonitor.mqagent.id.list and the handshake.mqagent.id in MQMonitor.properties file have the same ID. The values for handshake.qm.host, handshake.qm.port, and handshake.queue must be the same in all properties files because they refer to a common queue manager. Important! Cross Process Transaction Tracing can also be configured without Handshake. In the MQMonitor.properties file, disable the handshake properties. Also, set the following properties in the MQAgent.properties file: ■ mq.crossprocesstracing.enabled property must be true ■ mqmonitor.mqagent.id.list property must be blank Configure WebSphere MQ to Publish Events 44 for IBM WebSphere MQ Guide Configure WebSphere MQ to Publish Events You can configure WebSphere MQ to publish events that you can view in CA Introscope®. Follow these steps: 1. Edit the MQMonitor.properties file to identify the queues whose MQ Events you want to monitor. 2. You can configure the following events on the MQ Server: ■ For Queue Manager events, enable monitoring of Authority, Inhibit, Local, Remote, Start, and Stop. ■ For Channel Events, enable monitoring of Channel, SSL, and Channel auto-definition. ■ For Performance Events, enable monitoring of Performance.You can also enable queue depth events and service interval events in the Queue properties dialog. Note: If more than one application is monitoring the MQ Event Queues, then MQMonitor agent throws an error. To avoid this error, go to the queue properties if default properties are used. 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 to Shareable and the Default Input Open Option property to Input shared. 3. Start the MQMonitor agent. Note: You can also use MQSC commands to enable monitoring of the MQ events. For more information, see the IBM WebSphere MQ documentation. To view MQ Events in the Investigator, select *SuperDomain*,<hostname>, WebSphere MQ and Message Broker, WebSphere MQ and Message Broker Agent (*SuperDomain*) node. The MQ Events display in the What’s Interesting column. Chapter 5: Additional Information 45 Chapter 5: Additional Information You can perform additional tasks such as configuring SSL, upgrading CA APM for IBM WebSphere MQ, and creating JMS queues. This section contains the following topics: Turn On Queue Monitoring (see page 45) Configure Application Server When Java 2 Security is Enabled (see page 45) Share the wily Folder Across MQ Java Connector agents (see page 46) Configure JCA Connection Pool (see page 47) Configure SSL (see page 48) Configure CA APM ErrorDetector (see page 54) Install the MQMonitor Agent as a Windows Service (see page 56) Upgrade CA APM for IBM WebSphere MQ (see page 57) Configure MQ applications for SOA Dependency Map (see page 58) Auto-discover Queue Managers (see page 60) Installation and Configuration in an EM Clustered Environment (see page 63) Turn On Queue Monitoring 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.). Follow these steps: 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. Configure Application Server When Java 2 Security is Enabled When Java 2 security is enabled on an application server, for example, WebSphere Application Server, update the server.policy and java.policy files. Share the wily Folder Across MQ Java Connector agents 46 for IBM WebSphere MQ Guide Follow these steps: 1. Add the following lines in the server.policy file that is at <WebSphere home>/profiles/<profile name>/properties: // WebSphere optional runtime classes grant 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"; }; 2. Add the following lines in the java.policy file that is at <WebSphere home>/java/jre/lib/security: grant { permission java.io.FilePermission "C:/IBM/WebSphere/wily/MQAgent.properties", "read"; }; Share the wily Folder Across MQ Java Connector agents You can use the same /wily folder across multiple MQ Java Connector agents. Follow these steps: 1. Make multiple copies of the MQAgent.properties file with names for the agents. 2. Pass the -Dcom.wily.mqpp.mqagentProfile=<path to the wily folder>/MQAgent.properties with other JVM arguments at the Java command for running the agents. Example: For Java versions 1.5 to the current version –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 Configure JCA Connection Pool Chapter 5: Additional Information 47 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. Follow these steps:: 1. Verify that the MQAppSupport.jar file has been extracted to the /wily/common directory of the application server host. 2. In WebSphere, create and configure a service that reports connection pool metrics: a. Open the WebSphere Admin Console. 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 service. g. Verify that Enable service at server startup is selected. h. Specify the following information under General Properties: ClassName: Indicates the name of the class. Specify as com.wily.powerpack.websphereMQ.agent.JCAConnectionPool.Introscope MQCustomService. DisplayName: Specifies any string. CA Introscope® uses this value for the label of the service. ClassPath: Indicates the full file system path to the MQAppSupport.jar file in the /wily/common directory of the application server host. For example: C:/Program Files/WebSphere/AppServer/Wily/common/MQAppSupport.jar i. Click OK. 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 the server for which you are configuring the PMI. Configure SSL 48 for IBM WebSphere MQ Guide c. Click the Configuration tab. d. Select the Enable Performance Monitoring Infrastructure (PMI) check 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 ■ PoolSize. ■ WaitingThreadCount ■ PercentMaxed. You can view the selected metrics in CA Introscope®. See JCA node metrics. h. With the attributes selected, click Enable. i. Click OK. 4. Restart the WebSphere Application Server. Configure SSL Before you begin the SSL configuration, note the following: ■ The Server mentioned in this procedure is the IBM MQ Queue Manager and the Client is CA APM for IBM WebSphere 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. For more information about Certificates, see Generate Personal Certificates (see page 54). ■ The SSL Key repository is termed as keystore and truststore on the Client depending on its usage. Important! If you monitor Queue Managers over SSL, then do not use the JRE shipped with WebSphere MQ 6.0.0.0.0. Instead, use the Sun JRE v1.4 (at a minimum), or the latest WebSphere MQ JRE . Configure SSL Chapter 5: Additional Information 49 How to Set Up Client-Server Communication Over SSL Perform the following steps to set up client-server communication over SSL: 1. Set up SSL key repository and create self-signed certificate on the server. 2. Set up truststore on the client and add the self-signed certificate for the server to it. 3. Set up keystore on the client (if the server needs client authentication) and create self-signed certificate for the client. The client requires the keystore password during SSL communication with the server. 4. Extract the certificate for the client and add it to the SSL Key Repository for the server. 5. Select an SSL CipherSpec for the Server Connection Channel on the server. 6. Configure the client using the SSL-related properties in the MQMonitor.properties or MBMonitor.properties files. 7. Start the client. This process initiates communication with Server CipherSpec. The server and client start exchanging information about the Server Connection channel over SSL. To establish the SSL communication between the client and server, configure both the client and the server. More information: Configure the Server (see page 49) Configure the Client (see page 50) Configure the Server To configure the server, perform the following steps: 1. Set up the SSL key repository with the Key database type as "CMS". For example: On Windows, the Queue Managers SSL key repository is at <WebSphere MQ home>\qmgrs\<Queue Manager Name>\ssl and the SSL key repository name is key.kdb. Configure SSL 50 for IBM WebSphere MQ Guide 2. Generate personal certificates (see page 54). You can either generate a self-signed certificate using the IKEYMAN tool or any personal certificate, and add it to the SSL key repository. 3. Add the Client certificate (if client authentication is needed) to the server SSL key repository. Note: Client Certificate is obtained from Step 2. 4. Set the SSL CipherSpec on the server connection channel. Note this value because you provide this information in the MQMonitor.properties file. You also provide this information in the MBMonitor.properties file or MBMonitor_7.properties file depending on the version of the MB in your environment. The server has been configured. Configure the Client To configure the client, perform the following steps: 1. Set up truststore (see page 50). 2. Set up keystore (see page 51). 3. Run mqPwdEncryptor.bat file (see page 51). 4. Configure the MQMonitor.properties file (see page 52). 5. Configure the MBMonitor properties File (see page 53). Set Up Truststore Perform the following steps to set up truststore: 1. Set up truststore with the Key database type as "JKS". For example: trustore.jks 2. Add the Server certificate to the truststore. You get the Server Certificate from Step 2 in Configure the Server (see page 49). Configure SSL Chapter 5: Additional Information 51 Set Up Keystore This section is needed only when the Server asks for Client Authentication. Follow these steps: 1. Set up keystore with the Key database type as "JKS". Note the password needed to open the keystore. For example: keystore.jks 2. Generate the certificate—either self-signed certificate using IKEYMAN tool or any personal certificate—and add it to the keystore. Run mqPwdEncryptor.bat file Run the mqPwdEncryptor.bat file if the server requires client authentication. The purpose of this command-line utility is to set keystore location and keystore password for the Client (CA APM for IBM WebSphere MQ) to communicate over SSL. Follow these steps: 1. Double-click mqPwdEncryptor.bat. 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 where the keystore location and password must be updated. 4. Enter the absolute path for the properties file 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 MQMonitor agent decrypts and uses the encrypted password. Important! Always use the same truststore and keystore references for a given MQMonitor agent. The properties file can be that of MQMonitor or MBMonitor. Configure SSL 52 for IBM WebSphere MQ Guide 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. Follow these steps: 1. To enable SSL, edit the following property: <Queue Manager>@<Host>.ssl 2. If a Queue Manager is SSL-enabled, indicate the same by enabling the property. For example: [email protected]=enable 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 is configured. For example: [email protected]= NULL_MD5 NULL_MD5 is the name of the CipherSpec that is used and QM1 is the Queue Manager. 3. Place certificates of all the Queue Managers in the truststore. Edit the truststore.path property to point the MQMonitor agent to the truststore location: Note: On UNIX systems, use the forward slash in the path as the separator. You can use the forward slash on Windows also. However, if the backward slash is used on Windows, escape it. 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 the client is placed in keystore. 4. Provide the 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 do not edit these properties directly in the MQMonitor.properties file. Instead, run the mqPwdEncryptor.bat file. The mqPwdEncryptor.bat utility updates the keystore.path property with the path (with the forward slash as the separator) you provided. Configure SSL Chapter 5: Additional Information 53 Configure the MBMonitor properties File The MBMonitor establishes the following types of default system server connection channels: ■ CMP (SYSYTEM.BRK.CONFIG) for MQMonitor agent connection with the Queue Manager for the configuration manager ■ JMS (SYSTEM.DEF.SVRCONN) for MQMonitor agent connection with the Queue Manager for the JMS broker Note: For connecting to the WebSphere message brokers over SSL, we recommend that you use the latest IBM JRE provided with WebSphere MB. Configure this JRE in the MQMonitor startup script/batch file. Important! The MBMonitor properties file refers to the MBMonitor.properties file for MB 6.x and MBMonitor_7.properties file for MB 7.0 or 8.0. Follow these steps: 1. Perform one of the following steps to configure the ssl properties: ■ For MB 6.x in the MBMonitor.properties file: cmp.ssl=enable jms.ssl=enable ■ For MB 7.0 and 8.0 in the MBMonitor_7.properties file: a.ssl=enable Note: Set this property for each instance for which you want to have SSL enabled. Use the same instance name that is used in mq.broker.monitor.list property. 2. Perform one of the following steps to configure the value for CipherSpec: ■ For MB 6.x in the MBMonitor.properties file: cmp.connection.ssl.cipherspec=NULL_MD5 ■ For MB 7.0 and 8.0 in the MBMonitor_7.properties file: broker.connection.ssl.cipherspec=NULL_MD5 3. For MB 6.x, set the value for the CipherSpec for the JMS broker in the MBMonitor.properties file. The MQMonitor agent verifies this value when the SSL property is enabled for the Queue Manager of the JMS broker. For example: jms.connection.ssl.cipherspec=NULL_MD5 Configure CA APM ErrorDetector 54 for IBM WebSphere MQ Guide 4. Place the certificates of the Queue Managers for the configuration manager or the broker (for MB 7.0 or 8.0) and the JMS broker in the truststore. Edit the following property to point the MQMonitor agent to the truststore location: truststore.path Note: On UNIX, use the forward slash in the path as the separator. You can use the forward slash on Windows also. However, if the backward slash is used on Windows, then it must be escaped. For example: truststore.path=C:\\MQMonitor\\keys\\truststore.jks truststore.path=C:/MQMonitor/keys/truststore.jks 5. The personal certificate of the client is included in the keystore. Provide the keystore location and its password in the MBMonitor.properties or in the MBMonitor_7.properties file. Note: You do not need to edit the properties directly in the MBMonitor.properties file or MBMonitor_7.properties file. Instead, run the mqPwdEncryptor.bat file. For example: keystore.path=C:/MQMonitor/keys/keystore.jks keystore.password=<Encrypted password> The MBMonitor properties file has been configured 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. Configure CA APM ErrorDetector You can use CA APM ErrorDetector feature to read WebSphere MQ errors in the Investigator. CA APM ErrorDetector allows application support personnel to detect and diagnose errors that prevent you from completing web transactions. Enabling CA APM ErrorDetector allows CA Introscope® to show application errors on the application server that uses WebSphere MQ as the message queuing middleware. Configure CA APM ErrorDetector Chapter 5: Additional Information 55 Follow these steps: 1. Edit the webspheremq.pbl in the <AppServer_Home>/wily/core/config directory on the application server. 2. Uncomment webspheremq_errors.pbd. 3. Restart the application server. You get values for the Errors Per Interval metric for each JCA/JMS operation or method. Error text appears as a snapshot in the Errors tab on the right pane of the Investigator. Install the MQMonitor Agent as a Windows Service 56 for IBM WebSphere MQ Guide Install the MQMonitor Agent as a Windows Service To run the MQMonitor agent on Windows as a Windows Service, go to the MQMonitor\Window Service directory. The directory structure is as follows: ■ Directory: \Windows Service Files: ■ RegisterMQService.bat ■ DeregisterMQService.bat ■ Directory: \Windows Service\jsw-3.2.3\bin Files: ■ InstallTestWrapper-NT.bat ■ PauseTestWrapper-NT.bat ■ ResumeTestWrapper-NT.bat ■ StartTestWrapper-NT.bat ■ StopTestWrapper-NT.bat ■ TestWrapper.bat ■ TestWrapperNoWrapper.bat ■ UninstallTestWrapper-NT.bat ■ wrapper.exe ■ Directory: \Windows Service\jsw-3.2.3\conf Files: ■ wrapper.conf ■ Directory: \Windows Service\jsw-3.2.3\legal\jsw-3.2.3 Files: ■ license.txt ■ Directory: \Windows Service\jsw-3.2.3\lib Files: ■ wrapper.dll ■ wrapper-3.2.3.jar ■ wrappertest-3.2.3.jar You can register the MQMonitor agent as a Windows Service. Follow these steps: Upgrade CA APM for IBM WebSphere MQ Chapter 5: Additional Information 57 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. You can monitor WebSphere MB when MQMonitor agent is registered as a Windows Service. Follow these steps: 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. You can run the MQMonitor agent as a Windows Service. Follow these steps: 1. Click Start, Run. The Run dialog 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. Upgrade CA APM for IBM WebSphere MQ If you use the Enterprise Manager installer to upgrade CA APM for IBM WebSphere MQ from version 8.x to the current version, ensure that a continued functionality is maintained. Follow these steps: 1. Replace the file <EM_Home>/config/modules/WebspherMQ_CPT_Health_And_Availability.jar with WebsphereMQ_CPT_Health_And_Availability.jar from the <EM_Home>/examples/PowerPackForWebSphereMQ/config/modules directory. Configure MQ applications for SOA Dependency Map 58 for IBM WebSphere MQ Guide This step enables the Enterprise Manager. If you do not perform this step correctly, the Enterprise Manager does not start and an error message appears. 2. Remove the following files: ■ <EM_Home>/ext/MQJCAJMSAggregator.jar ■ <EM_Home>/ext/ddtv/DedicatedQueueManager-typeviews.xml ■ <EM_Home>/ext/ddtv/MBMQObjects-typeviews.xml ■ <EM_Home>/ext/ddtv/MessageBroker-typeviews.xml ■ <EM_Home>/ext/ddtv/MQJCAJMS-typeviews.xml ■ <EM_Home>/ext/ddtv/MQObjects-typeviews.xml 3. Copy the following files from the <EM_Home>/examples/PowerPackForWebSphereMQ/product/enterprisemanager/ plugins directory to: ■ <EM_Home>/product/enterprisemanager/plugins/com.wily.powerpack.wmq.d dtv.typeview.jar ■ <EM_Home>/product/enterprisemanager/plugins/com.wily.powerpack.wmq.e m.extension.jar Note: If you do not perform Steps 2 and 3, you duplicate tabs appear in the typeview and warnings appear in the Enterprise Manager Console. CA APM for IBM WebSphere MQ has been upgraded. Configure MQ applications for SOA Dependency Map The Service-Oriented Architecture (SOA) Dependency Map provides a graphical way for you to view and understand the interdependent agents, services, and operations in your SOA environment. The SOA Dependency Map displays real-time dependencies and metrics for your web services agents, services, and operations that are automatically generated from performance metrics and analysis of metrics, errors, and events. Standard MQ/JMS Calls are supported for the web services communication. When you monitor the WebSphere MQ components, you can view the MQ transport protocols that are used in web services in the SOA dependency map. Some of the transport protocols that you can view are: ■ SOAP over JMS transport protocol (JMS Provider: WebSphereMQ 6.0 and 7.0 API) ■ SOAP over MQ transport protocol (MQ Provider: WebSphereMQ 7.0 API). You can view dependencies for WebSphere MQ operations and process definitions by selecting the WebServices node in the Investigator tree and clicking the SOA Dependency Map tab. Configure MQ applications for SOA Dependency Map Chapter 5: Additional Information 59 You can also view WebSphere MQ queue managers as map nodes in the SOA dependency map when WebSphere MQ is involved in web service transactions. The node that you select determines the context that is displayed in the dependency map. When you click WebServices in the Investigator tree and select Services tab as the content type, the dependency map displays the MQ nodes as WebSphereMQ on <hostname>. When you click WebServices in the Investigator tree and select Operations tab as the content type, the dependency map displays the MQ node as <Queue Manager Name>. Important! You can view WebSphere MQ components in SOA Dependency Map in the integrated SOA environment only. You cannot view SOA Dependency Map in the standalone WebSphere MQ deployment. To view MQ components in SOA Dependency Map, configure the IntroscopeAgent.profile file and enable the relevant PBD file in the webspheremq.pbl file. Follow these steps: 1. In IntroscopeAgent.profile, set the following property to true: ■ com.wily.introscope.agent.mqheaderinsertion.enabled=true This property enables the client to insert the correlation identifier in the MQ/MQ JMS Message header. – Set the property to true to allow the client to use the MQ/MQJMS Message header. – Set the property to false if you want to prevent the client from inserting the correlation identifier in the MQ/MQJMS Message header. – By default, this property is set to true. Note: Set this property if your SOAP-based applications do not work properly due to unexpected header entries. ■ com.wily.introscope.agent.mqheaderread.enabled=true This property enables the client to read the correlation identifier in the MQ/MQ JMS Message header. – Set the property to true to allow the client to read the MQ/MQJMS Message header. – Set the property to false if you want to prevent the client from reading correlation identifier in the MQ/MQJMS Message header. – By default, this property is set to true. Note: Set this property if your SOAP-based applications do not work properly due to unexpected header entries. Auto-discover Queue Managers 60 for IBM WebSphere MQ Guide 2. Uncomment webspheremq-extra.pbd in webspheremq.pbl to enable support for the MQ components in SOA Dependency Map. 3. Restart the managed application. Note: For more information about navigating the dependency map, including showing and hiding dependency levels, see the CA APM for SOA Implementation Guide. Auto-discover Queue Managers Auto Discovery of Queue Managers facilitates ease of configuration and monitoring of Queue Managers on demand. The installation and configuration becomes simpler and enables application owners to manage WebSphere MQ requiring little or no manual intervention from MQ administrators. The Queue Managers are discovered only when they are accessed or are part of a message route. Follow these steps: 1. Open the MQAgent.properties file and set the handshake.qm.host, handshake.qm.port, handshake.qm.channel.name, and handshake.qm.character.set properties with appropriate values for all MQPP agents. See MQAgent.properties file for details. 2. Set Auto Discovery Properties (see page 60) in MQMonitor.properties file. 3. View the Auto Discovered Queue Managers in the What's Interesting section (see page 63). Set Auto Discovery Properties The MQMonitor.properties file lets you set auto discovery properties. Follow these steps: 1. Open the MQMonitor.properties file and set the handshake.qm.host, handshake.qm.port, handshake.qm.channel.name, and handshake.qm.character.set properties with appropriate values for all MQPP agents. 2. If you have more than one MQ Monitor agent, set the mq.monitor.agent.id property to indicate the appropriate identification number for the MQMonitor agent. 3. Verify that mq.autodiscovery.enabled property is set to true to enable Auto Discovery of Queue Managers. Auto-discover Queue Managers Chapter 5: Additional Information 61 4. Set the mq.autodiscovery.queue property to indicate the queue that is used among all MQ agents for discovering Queue Managers. 5. Set the mq.autodiscovery.properties.update property to indicate if MQMonitor.properties file must be updated automatically with the fully discovered Queue Managers. a. If the mq.autodiscovery.properties.update property is set to true, the following occurs: ■ All the MQMonitors monitor all the successfully discovered queue managers. For example, if MQMonitor MQ1 discovers queue manager QM1 and MQMonitor MQ2 discovers queue manager QM2, both MQ1 and MQ2 monitor QM1 and QM2. ■ All the MQMonitors monitor the maximum number of queue managers. ■ The MQMonitor.properties file is updated with only successfully discovered queue managers. ■ Partially discovered queue managers, if any, are not updated in the MQMonitor.properties file. We recommend that you set this property to false and run the MQDiscovery utility tool (see page 61). b. If the mq.autodiscovery.properties.update property is set to false, run the MQDiscovery utility tool (see page 61) to update the MQMonitor.properties file with successfully and partially discovered queue managers. 6. Save and close the MQMonitor.properties file. MQMonitor.properties file has been configured for auto discovery of queue managers. MQDiscovery Utility Tool You can use the MQDiscovery utility tool to add discovered Queue Managers to MQMonitor.properties and start the monitoring of these Queue Managers. The utility tool can be executed in interactive and non-interactive modes. You can execute the MQDiscovery utility tool and update MQMonitor.properties file. Follow these steps: 1. To update MQMonitor.properties file with successfully discovered Queue Managers from MQDiscovery.list, enter the following command in the command prompt and press the Enter key. For Windows: startMQDiscovery.bat For UNIX: startMQDiscovery.sh Auto-discover Queue Managers 62 for IBM WebSphere MQ Guide This command updates MQMonitor.properties file in the non-interactive mode. 2. To update MQMonitor.properties file with partially discovered Queue Managers from MQDiscovery.list, enter the following command in the command prompt and press the Enter key. For Windows: startMQDiscovery.bat –i For UNIX: startMQDiscovery.sh –i This command updates MQMonitor.properties file in the interactive mode and asks for channel name and character set for corresponding Queue Managers. Note: If channels other than default system channels are used to discover the queue managers, then the tool provides a channel list from which you can choose channels for monitoring. The channel list is saved in the mq.autodiscovery.channel.list property. The tool saves the report to a file named MQDiscoveryUtility.log in the /logs directory of the MQMonitor agent. The tool appends all the MQMonitor.properties changes to the same file in interactive and non-interactive mode. MQDiscovery.list file is accessed and the list of Queue Managers that are auto-discovered is added to MQDiscovery.list file. If the Queue Managers are discovered successfully, they are added in the following format: mq.monitor.list=Queue Manager1@hostname, Queue Manager2@hostname Queue [email protected]=Queue Manager1@hostname Queue [email protected]=Queue Manager2@hostname Queue [email protected]=3002 Queue [email protected]=4403 Queue [email protected]=SYSTEM.AUTO.SVRCONN Queue [email protected]=SYSTEM.DEF.SVRCONN Queue [email protected]=819 Queue [email protected]=819 If the Queue Managers are discovered partially, they are added in the following format: mq.monitor.list=Queue Manager1@hostname, Queue Manager2@hostname Queue [email protected]=Queue Manager1@hostname Queue [email protected]=Queue Manager2@hostname Queue [email protected]=3002 Queue [email protected]=4403 Queue [email protected]= Queue [email protected]= Queue [email protected]= Queue [email protected]= Installation and Configuration in an EM Clustered Environment Chapter 5: Additional Information 63 View the Auto Discovered Queue Managers in the What's Interesting section When the Queue Managers are discovered, they are reported as What's Interesting events. Follow these steps: 1. Click *Super Domain*, <Hostname>, WebSphere MQ and Message Broker, WebSphere MQ and Message Broker Agent (*Super Domain*) and see What's Interesting events in the Viewer pane. After a delay of 300 seconds, the Queue Managers appear under the node in the Investigator tree. 2. Click one of the following to view the Queue Managers that have been discovered automatically: ■ *Super Domain*, <Hostname>, WebSphere MQ and Message Broker, WebSphere MQ and Message Broker Agent (*Super Domain*), Queue Manager Clusters, CLUSTERS, Full Repositories or Partial Repositories, <Hostname> ■ *Super Domain*, <Hostname>, WebSphere MQ and Message Broker, WebSphere MQ and Message Broker Agent (*Super Domain*), Queue Managers, <Hostname> Queue Managers that have been discovered automatically are displayed in the right pane in the What’s Interesting column. Installation and Configuration in an EM Clustered Environment Clustered environment or clustering allows an Enterprise Manager to manage other Enterprise Managers, serving as a Manager of Managers (MOM). The managed Enterprise Managers are named Collectors. In a clustered environment, install and configure the extension on each Collector. To install and configure the extension, do the following steps: 1. Preparing to install (see page 17) 2. Installation (see page 21) Note: All Enterprise Manager extensions and calculators for Java Connectors and MQMonitor must be placed primarily on all the Collectors. Only the SOA Dependency Map extension must be placed on the Collectors and the MOM. The agents configured in the clustered environment must be connected to MOM using the properties in the IntroscopeAgent.profile file. 3. Configuration (see page 27) 4. Auto-discover Queue Managers (see page 60) Installation and Configuration in an EM Clustered Environment 64 for IBM WebSphere MQ Guide 5. Configure MQ applications for SOA Dependency Map (see page 58). 6. Configure WebSphere MQ for Trace. (see page 37) Chapter 6: Transaction Tracing 65 Chapter 6: Transaction Tracing CA APM for IBM WebSphere MQ introduces support for WebSphere MQ message tracking by extending the core Transaction Trace feature of CA Introscope®. You can use cross-process transaction tracing, configure the WebSphere MQ system for trace, and interpret the trace data. This section contains the following topics: Cross-Process Transaction Tracing (see page 65) Verify the Transaction Trace Configuration (see page 66) WebSphereMQ Cross Process Transaction Trace Health & Availability Dashboard (see page 66) Configure the Enterprise Manager for Trace (see page 69) Identifying a Slow Transaction (see page 69) Enable or Disable MQ Traces (see page 71) Filter Queues for Transaction Trace (see page 72) Trace Data Properties (see page 72) Cross-Process Transaction Tracing In CA APM for IBM WebSphere 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 CA APM for IBM WebSphere MQ and lets you determine which component of WebSphere MQ is causing performance bottlenecks. CA APM for IBM WebSphere 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. Verify the Transaction Trace Configuration 66 for IBM WebSphere MQ Guide Verify the Transaction Trace Configuration To verify that you have configured the transaction trace correctly, check the following: ■ The handshake and trace-related properties are configured on both the MQAgent.properties and MQMonitor.properties files. ■ 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 Chapter 6: Transaction Tracing 67 The SYSTEM.ADMIN.ACTIVITY.QUEUE has traffic lights for the following elements: ■ 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 percent. Yellow Indicates that the % Queue Full value of the monitored Queue Managers is greater than 50 percent and less than 75 percent. Red Indicates that the % Queue Full value is greater than 75 percent. ■ 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 Dead Letter Queue has traffic lights for the following elements: ■ 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 is not configured for sending and/or receiving messages from applications. WebSphereMQ Cross Process Transaction Trace Health & Availability Dashboard 68 for IBM WebSphere MQ Guide ■ Queue Full Green Indicates that the % Queue Full value of the monitored Queue Managers is less than 50 percent. Yellow Indicates that the % Queue Full value of the monitored Queue Managers is greater than 50 percent. ■ 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 dashboard also includes traffic lights for the following: ■ Agent-MQ connection Status Green Indicates that the MQMonitor agent is able to connect to all the monitored Queue Managers successfully. 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. Configure the Enterprise Manager for Trace Chapter 6: Transaction Tracing 69 ■ 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 CA APM for IBM WebSphere MQ installation in the central traffic light indicator. The overall status traffic light appears as green when the traffic lights of all of the elements are green. However, if a traffic light 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 the Enterprise Manager for Trace Follow these steps: 1. Edit the IntroscopeEnterpriseManager.properties file located in the <Introscope Home>/config directory to add the following two lines: introscope.workstation.transactiontracer.showTotalDuration=true introscope.workstation.transactiontracer.showTotalDuration.sumAllTraceCompone nts=true 2. Restart the Enterprise Manager. An additional column named Total Duration (in milliseconds) 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. Identifying a Slow Transaction You can identify a slow transaction trace by interpreting the Transaction Trace. Identifying a Slow Transaction 70 for IBM WebSphere MQ Guide Transaction Trace with Trace Holding Duration Set to 0ms When the trace.hold.maxduration property is set to 0 milliseconds in the MQMonitor.properties file, the traces do not appear in sequence in the Transaction Trace window. Follow these 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 column. 3. Select the first trace in the list. The first trace indicates the slowest running transaction among all the transactions. 4. Select View, Correlated Events to get all the correlated events for the selected trace. 5. Select any trace to see the complete trace information. Transaction Trace with Holding Duration Set to a Value Other than 0ms When the trace.hold.maxduration property is set to a value other than 0 millisecond in the MQMonitor.properties file, the following occurs: ■ Traces appear in a sequence in the Transaction Trace window. ■ The extension collects the activity reports and sends the consolidated component data for the traces to Enterprise Manager. ■ If all activity reports are received during the holding duration specified in the trace.hold.maxduration property, the extension sends the consolidated transaction component data containing the activity report traces to Enterprise Manager with time duration of the transaction. ■ If all the activity reports are not received during the holding duration, the extension sends the incomplete trace component data to Enterprise Manager with consolidated custom trace component. If a message is put to a local queue, that is, for zero hops, activity reports are not stored and custom trace is not consolidated. Consider a scenario where the Java application puts a message to a Remote Queue rq of Queue Manager CPTT1 at host local host. The message hops to a remote queue rq of Queue Manager CPTT2. From here, it hops to another remote queue rq of Queue Manager CPTT3 and finally hops to local queue lq of Queue Manager CPTT4. When you start the Transaction Trace, you can see three hops in the window; with the MQ Traces being displayed in sequence. Enable or Disable MQ Traces Chapter 6: Transaction Tracing 71 To identify a slow transaction, perform the following steps: 1. Start a Transaction Trace session. The trace appears in the Transaction Trace viewer. 2. Click the Summary View tab. 3. Click the Trace View tab. You see the MQ Traces that are specific to message flow until destination queue under one consolidated expandable and collapsible MQ Trace Segment. 4. Expand the trace to see the details. 5. Click the Tree View tab. Enable or Disable MQ Traces You can disable or enable 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. When you run the transaction trace, you can view MQ Trace data even when the MQMonitor agents are not running. However, the trace is 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, set mqmonitor.mqagent.id.list to the handshake.mqagent.id value of all MQMonitor agents. Note: We recommend that you enable MQ Traces with handshake. 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. Restart the application server if you change the value of handshake.mqagent.id. Filter Queues for Transaction Trace 72 for IBM WebSphere MQ Guide Filter Queues for Transaction Trace You 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 with the subsequent correlated traces. The property 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.*))).* Trace Data Properties The 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 Trace Data Properties Chapter 6: Transaction Tracing 73 Key Description Value MQ Operation MQ Channel Type Type of the channel on which the WebSphere MQ operations are performed. Any one of the possible values: SENDER RECEIVER REQUESTER SERVER CONNECTION CLUSTER SENDER CLUSTER RECEIVER Put, Get MQ Queue Name Queue Name <Queue Name> Put, Get MQ Queue Type Queue Type Any one of the possible values: LOCAL LOCAL (DLQ) TRANSMISSION REMOTE 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 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 (see page 65). 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. Trace Data Properties 74 for IBM WebSphere MQ Guide Key Description Value MQ Operation 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 expired Message is not consumed Message is consumed Put operation to a local queue. Chapter 7: Viewing Data Using the WebSphere MQ Extension 75 Chapter 7: Viewing Data Using the WebSphere MQ Extension CA APM for IBM WebSphere MQ reports data to the Enterprise Manager. You can view CA Introscope® data using CA APM for IBM WebSphere MQ. This section contains the following topics: View Data (see page 75) Console Dashboards (see page 75) View Dashboards and Data (see page 76) WebSphereMQ Sample Report Templates (see page 84) View Data To view the data sent to the Enterprise Manager, use the following Workstation GUI tools: ■ Console Dashboards (see page 75) ■ Investigator Dashboards (see page 76) Console Dashboards CA APM for IBM WebSphere MQ provide the Management Modules that consist of several preconfigured dashboards for the Workstation Console. MQ Dashboards in the Console You can view the WebSphere MQ and WebSphere Message Broker dashboards in the Console. Follow these steps: 1. Launch Enterprise Manager. 2. Launch the Workstation to connect to the Enterprise Manager, and log into the Console. 3. Using the drop-down list, select one of the dashboards. The dashboard is displayed. View Dashboards and Data 76 for IBM WebSphere MQ Guide View Dashboards and Data CA APM for IBM WebSphere MQ provides preconfigured 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. You can see at a glance how the system is functioning and where problems are occurring. Follow these steps: 1. Launch Enterprise Manager. 2. Launch the Workstation to connect to the Enterprise Manager, and log in to the Investigator. In the Investigator, the metric data is organized in the following ways: ■ The metrics tree. ■ Dashboards and graphical displays. More information: Understanding the Metrics Tree (see page 76) Show Investigator Dashboards and Data Displays (see page 80) Aggregated Metrics (see page 81) Understanding the Metrics Tree CA APM for IBM WebSphere MQ displays the following types of data: ■ Data from MQMonitor agent ■ Data from MBMonitor for WebSphere MB ■ Data from the MQ Java Connectors MQMonitor Agent and MBBroker Metrics You can find data from the MQMonitor agent and MBMonitor agent. Follow these steps: 1. Select *SuperDomain*, <hostname>, WebSphere MQ and Message Broker. 2. Select the Message Broker Agent (*SuperDomain*) node: View Dashboards and Data Chapter 7: Viewing Data Using the WebSphere MQ Extension 77 The data from the MQMonitor agent is displayed in the Investigator metrics tree as follows: ■ 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. Note: The data displayed in the Investigator depends on the WebSpehere MQ agent version. More information: General Metric Characteristics (see page 131) Host Information At the top level of the MQ metrics tree, you can view information about the host where the MQMonitor agent is running. Enterprise Manager Host Displays the name of the computer that hosts the Enterprise Manager. Java Version Displays the version of Java being run by the MQMonitor agent. Launch Time Displays the time and date when the MQMonitor agent was last launched. Virtual Machine Displays the vendor of the JVM running the MQMonitor agent. GC Heap Displays the amount of free memory available to the MQMonitor agent. Bytes In Use Displays the size of the in-use memory heap on the MQMonitor agent. Bytes Total Displays the total size of the memory heap on the MQMonitor agent. View Dashboards and Data 78 for IBM WebSphere MQ Guide Host Displays the computer which hosts the MQMonitor agent. IP Address Displays the IP address of the MQMonitor agent. Operating System Displays the Operating System of the MQMonitor agent. Wall Clock Time Displays the 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. More information: Queue Manager Cluster Metrics (see page 132) Queue Manager Metrics Under the Queue Managers node, you can view metrics for each Queue Manager under the following 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. ■ 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 for 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 has 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. View Dashboards and Data Chapter 7: Viewing Data Using the WebSphere MQ Extension 79 ■ Dead Letter Queue—Configuration Properties and Status data/metrics about the dead letter queue, which is a repository for undeliverable messages. ■ Transmission Queue—Configuration Properties and Status data/metrics about the transmission queue for the MQ Queue Manager, which is a local queue that is used to store messages before they are transmitted to the remote queue manager. ■ Last Check—Information about the connection status of the Queue Manager. ■ Queues—Configuration Properties and Status data/metrics for each of the queues that is 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. More information: Queue Manager Metrics (see page 153) 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: ■ Status and configuration information. ■ Broker Statistics—Divided into Client Statistics, Neighbor Statistics, and Wide Statistics. ■ Message Flows—Divided into several subcategories. View Dashboards and Data 80 for IBM WebSphere MQ Guide ■ Broker Queue Manager metrics—Detailed information about the status and configuration metrics for the broker Queue Manager, which is divided into: ■ Channels ■ Configuration Properties ■ Dead Letter Queue ■ Queues ■ Status ■ Transmission Queue More information: Message Broker Metrics (see page 186) Find MQ Java Connector Metrics MQ Java Connector metrics allow you to monitor the performance of your application server. To find the MQ Java Connector metrics, expand the SuperDomain node and look under the <hostname><WebSphere><WebSphereAgent>(*SuperDomain*) node. Show Investigator Dashboards and Data Displays You can show dashboards and graphical displays of metric data. Follow these steps: 1. Navigate the Investigator tree. 2. Click any node higher than an individual metric. Most of these nodes have associated Investigator dashboards which display an aggregate view of the metrics under that node. 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 depend on the node you select. Things to notice: Traffic lights Indicates an overview of critical performance metrics. Each of the traffic lights corresponds to aggregated metrics viewable in the metrics tree under the node selected. Note: In most cases, double-clicking the traffic light displays the metric data underlying that traffic light. View Dashboards and Data Chapter 7: Viewing Data Using the WebSphere MQ Extension 81 Data table Indicates more information than the traffic lights, typically. The tables display aggregated or calculated metrics. Color Indicates threshold settings. red Indicates danger threshold has been reached for at least one of the objects that are monitored under this object. yellow Indicates a caution threshold has been reached for at least one of the objects that are monitored under this object. green Indicates no thresholds have been reached for any of the objects that are monitored under this object. white Indicates no data has been received for any of the objects that are monitored under this object. Tabs Indicates the different dashboards available. Each dashboard has an Overview tab, and more tabs with more data. The names and contents of these tabs depends on the node. Each dashboard element is preconfigured, and you can use them without performing more configuration. Aggregated Metrics Aggregated metrics and traffic lights appear in the CA APM for IBM WebSphere MQ dashboards. Queue Manager Cluster and Queue Manager Metrics Aggregated metric name Description Value Aggregated Agent-MQ Connection Status Indicates the aggregated connection status of CA APM for IBM WebSphere MQ with all the Queue Managers. 0 = green—successful 1 = red—unsuccessful View Dashboards and Data 82 for IBM WebSphere MQ Guide Aggregated metric name Description Value 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 View Dashboards and Data Chapter 7: Viewing Data Using the WebSphere MQ Extension 83 Aggregated metric name Description Value 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 Message Broker Aggregated Metrics The following list contains aggregated metrics for the Message Broker Configuration Manager: ■ Aggregated metric name: Backouts Total Description: Total number of backouts reported under this node. ■ Aggregated metric name: Errors Total Description: Total number of errors reported by the objects under this node. Errors are aggregated from message flow statistics. ■ Aggregated metric name: Messages Dropped Total Description: Total number of dropped messages under this node. ■ Aggregated metric name: Timeouts Total Description: Total number of timeouts that are reported under this node. WebSphereMQ Sample Report Templates 84 for IBM WebSphere MQ Guide WebSphereMQ Sample Report Templates CA APM for IBM WebSphere MQ includes sample report templates that are based on the sample dashboards and Management Module that are included with the extension. The report templates are contained in the WebSphereMQ_Client_And_Server.jar file present in the <EM_Home>/config/modules. You can customize these sample report templates and can edit them to match corresponding business needs. Chapter 8: Dashboards 85 Chapter 8: Dashboards This chapter lists each of the dashboards, their elements, and other information that you can view using the Workstation Console. These dashboards and related elements are part of the Management Module component of CA APM for IBM WebSphere MQ. This section contains the following topics: Management Modules (see page 85) WebSphere MQ Client and Server Dashboards (see page 85) WebSphere Message Broker Dashboards (see page 88) Management Modules CA APM for IBM WebSphere MQ includes the following management modules: ■ WebSphere MQ Client and Server dashboards ■ WebSphere Message Broker dashboards More information: Console Dashboards (see page 75) WebSphere MQ Client and Server Dashboards The 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 navigate various dashboards and can troubleshoot issues by correlating the activities in the application to WebSphere MQ operations to actual WebSphere MQ objects. The WebSphere MQ Client and Server dashboards consist of the following dashboards: ■ WebSphere MQ Client And Server Overview dashboard (see page 86) ■ WebSphere MQ Client And Server Overview - Details dashboard (see page 86) ■ WebSphere MQ - Client Connections dashboard (see page 88) ■ WebSphere MQ - Client Operations dashboard (see page 88) ■ WebSphere MQ - Server dashboard (see page 88) WebSphere MQ Client and Server Dashboards 86 for IBM WebSphere MQ Guide WebSphere MQ Client and Server Overview Dashboard The WebSphere MQ Client And Server Overview dashboard shows the overall health of the WebSphere MQ--MQ Client Connections and MQ Server. Each component has alerts that show the overall health of that component. For example, the MQ Client Connections component has three alerts--Average Response Time, Errors Per Interval, and Stall Counts. Clicking the alerts shows the details for the MQ Client Connections component in the WebSphere MQ - Client Connections dashboard. The alerts in the dashboard display the following blame metrics for the MQ Client Connections and MQ Server components: ■ MQ Client Connections—Includes blame metrics for Average Response Time, Errors Per Interval, and Stall Count. ■ MQ Server—Includes Current Queue Depth (in percentage), Transmission Current Queue Depth, and Dead Letter Current Queue Depth for Queues. The dashboard displays the health of Cluster Work Load Management, Channel, Queue Manager, and the Rate of Queuing for Throughput. ■ Put/Send Operations—Includes blame metrics for Average Response Time, Errors Per Interval, and Stall Count. ■ Get/Receive Operations—Includes blame metrics for Average Response Time, Errors Per Interval, and Stall Count. From the Overview tab, you can double-click any of the component dashboards and can view their details. Also, each alert has a link to the dashboard associated with the details of that specific component. 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. WebSphere MQ Client and Server Dashboards Chapter 8: Dashboards 87 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. 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. Interpret the Dashboard Traffic Lights When a traffic light is green, it indicates that the corresponding operation for that component is working fine or that it 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. 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 have a problem because of the corresponding Queue is 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 Message Broker Dashboards 88 for IBM WebSphere MQ Guide WebSphere MQ - Client Connections Dashboard The WebSphere MQ - Client Connections dashboard shows detailed metrics for MQ Client connections. The dashboard displays Average Response 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. 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 Send/Receive 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 - 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. WebSphere Message Broker Dashboards The WebSphere Message Broker dashboards show the performance of the Message Broker and its Message Queue. WebSphere Message Broker Dashboards Chapter 8: Dashboards 89 WebSphere Message Broker Overview Dashboard The WebSphere Message Broker Overview dashboard has the following features: ■ 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. The WebSphere Message Broker Overview dashboard displays the following sections. ■ The Message Broker section has the following traffic lights: ■ Component: Overall Red light threshold: 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. Otherwise, if any one of the child traffic lights is red, the Overall traffic light is red. Red has a higher precedence over yellow. ■ Component: Errors Green—No threshold has been reached. Yellow—Caution threshold has been reached. Red—Danger threshold has been reached. ■ Component: Timeouts Green—No threshold has been reached. Yellow—Caution threshold has been reached. Red—Danger threshold has been reached. ■ Component: Backouts Green—No threshold has been reached. Yellow—Caution threshold has been reached. Red—Danger threshold has been reached. ■ Component: Messages Dropped Green—No threshold has been reached. Yellow—Caution threshold has been reached. Red—Danger threshold has been reached. WebSphere Message Broker Dashboards 90 for IBM WebSphere MQ Guide ■ The MQ section has the following traffic lights: ■ Component: Overall Red light threshold: If any of the four child traffic lights pointing to this Overall traffic light are red, then this Overall traffic light is red. ■ Component: Agent-MQ Connection Status Red light threshold: MQMonitor agent lost its connection with any one of the monitored queue managers. ■ Component: Queue Managers Status Red light threshold: Any one of the monitored Queue Managers is not running. ■ Component: Queues Full Red light threshold: Any one of the monitored Queues is full (no more messages can be put on the queue). ■ Component: Channels Indoubt Red light threshold: Any one of the monitored channels is in doubt. Compare the traffic lights with the high-level tree displayed in the Workstation. Double-clicking on any of the traffic lights leads to another Console dashboard with more information about the health of the component you selected. Other Message Broker Dashboards ■ WebSphere 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 Chapter 8: Dashboards 91 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: Backouts Total Type: Simple Thresholds: Danger Threshold: 1 Caution Threshold: 0 ■ Alert: Errors Total Type: Simple Thresholds: Danger Threshold: 1 Caution Threshold: 0 ■ Alert: MQ Qmgrs Status Type: Simple Thresholds: Danger Threshold: 0 Caution Threshold: 0 ■ Alert: MQ Queues Full Status Type: Simple Thresholds: Danger Threshold: 0 Caution Threshold: 0 ■ Alert: MQ Channels Indoubt Status Type: Simple Thresholds: Danger Threshold: 0 Caution Threshold: 0 ■ Alert: Messages Dropped Total Type: Simple Thresholds: Danger Threshold: 1 Caution Threshold: 0 WebSphere Message Broker Dashboards 92 for IBM WebSphere MQ Guide ■ Alert: Timeouts Total Type: Simple Thresholds: Danger Threshold: 1 Caution Threshold: 0 ■ Alert: MQ Agent-MQ Connection Status Type: Simple Thresholds: Danger Threshold: 0 Caution Threshold: 0 ■ Alert: MQ Overall Status Type: Summary Thresholds: None. Chapter 8: Dashboards 93 Appendix A: MQAgent.properties File The MQAgent.properties file lets you configure the handshake between the MQ Java Connector agents and the MQMonitor agents for cross-process transactions. Important! The handshake.mqagent.id value in the MQAgent.properties file must be unique across all MQ Java Connectors. The remaining handshake properties are the same for the MQAgent.properties and MQMonitor.properties files of all agents participating in CA APM for IBM WebSphere MQ. This section contains the following topics: mqmonitor.mqagent.id.list (see page 93) handshake.mqagent.id (see page 94) handshake.qm.host (see page 94) handshake.qm.port (see page 94) handshake.qm.channelname (see page 94) handshake.qm.character.set (see page 94) handshake.qm.ssl (see page 95) handshake.qm.channel.ssl.cipherspec (see page 95) handshake.queue (see page 95) truststore.path (see page 95) keystore.path (see page 95) keystore.password (see page 96) mqtracing.exclude.queues.regex (see page 96) mq.autodiscovery.enabled (see page 96) mq.autodiscovery.queue (see page 97) mqmonitor.mqagent.id.list Specifies the value of the handshake.mqagent.id property of all the MQMonitor agents that are involved in cross-process transaction trace. To enable MQ Traces without handshake, set mqmonitor.mqagent.id.list to null. Note: Separate the names by comma. Set this property to prevent unnecessary overload on WebSphere MQ, if cross-process transaction is enabled. Default: none Example: mqmonitor.mqagent.id.list=1, 2 handshake.mqagent.id 94 for IBM WebSphere MQ Guide handshake.mqagent.id Specifies the unique identification of the agent. If the value is null, then the handshake process does not start. Default: none Limits: 1 to 999999999 Example: handshake.mqagent.id=1 handshake.qm.host Specifies the IP address (or DNS name) of the common Queue Manager. Default: localhost Example: handshake.qm.host=localhost handshake.qm.port Specifies the port of the common Queue Manager. Default: 1414 Example: handshake.qm.port=123 handshake.qm.channelname Specifies the channel name of the common Queue Manager to be used for connections. Default: ■ SYSTEM.AUTO.SVRCONN ■ SYSTEM.DEF.SVRCONN (used if the default channel fails) Example: handshake.qm.channelname=SYSTEM.AUTO.SVRCONN handshake.qm.character.set Specifies the CCSID character set of the common Queue Manager. Default: 819 Example: handshake.qm.character.set=819 handshake.qm.ssl Chapter 8: Dashboards 95 handshake.qm.ssl Specifies if the SSL property is turned or off when the common Queue Manager is SSL-enabled. You can either enable or disable SSL. Default: disable Example: handshake.qm.ssl=disable handshake.qm.channel.ssl.cipherspec Specifies the SSL CipherSpec of the common Queue Manager. Default: None Limits: XXXXX_XXXXX handshake.queue Specifies the queue that is used for handshaking among all WebSphere MQ agents. Default: CA_WILY_HANDSHAKE truststore.path Specifies 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, escape the backslashes. Default: <path name> Example: truststore.path=C:\\MQMonitor\\key\\truststore.jks keystore.path Specifies 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, escape the backslashes. Setting this property is optional. Default: <path name> Example: keystore.path=C:\\MQMonitor\\key\\keystore.jks keystore.password 96 for IBM WebSphere MQ Guide keystore.password Specifies the keystore password. Setting this property is optional. Default: <password> Example: keystore.password=<password> mqtracing.exclude.queues.regex Specifies one or more queues of a particular Queue Manager that are filtered from transaction tracing. Setting this property is optional. Note: This property filters the first queue where WebSphere MQ Put or JMS Send operations occur with the subsequent correlated traces. The property also filters the traces for the WebSphere MQ Get or JMS Receive operations. Default: None Example: ■ To filter all the queues containing the word "SYSTEM" of the Queue Manager QM1 from transaction tracing, set the property as follows: QM1.mqtracing.exclude.queues.regex=.*SYSTEM.* ■ To filter all the queues of the Queue Manager QM1 from transaction tracing, set the property as follows: 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 as follows: QM1.mqtracing.exclude.queues.regex=(?!((.*TRACE.QUEUE1.*)|(.*TRACE.QUE UE2.*))).* mq.autodiscovery.enabled Specifies if auto-discovery of Queue Managers is enabled or not. Default: true Example: mq.autodiscovery.enabled=true mq.autodiscovery.queue Chapter 8: Dashboards 97 mq.autodiscovery.queue Specifies the queue that is used among all MQ agents for discovering Queue Managers. Default: CA_WILY_AUTODISCOVERY Example: handshake.queue=CA_WILY_AUTODISCOVERY Chapter 8: Dashboards 99 Appendix B: MQMonitor.properties File This section contains the following topics: Specific MQ Data Section (see page 99) MQ Events Section (see page 102) Special Settings Section (see page 105) Advanced Settings Section (see page 106) MQ Trace Related Properties Section (see page 106) MQ Auto Discovery Related Properties Section (see page 110) Filters Section (see page 111) Specific MQ Data Section Use this section to list the WebSphere MQ configuration instances to monitor WebSphere MQ Queue Managers. Important! A single Queue Manager instance must be monitored by only one MQMonitor agent. The DNS names cannot contain underscore characters. These are the MQ Monitor properties: mq.monitor.list (see page 100) <Queue Manager>@<Host>.host (see page 100) <Queue Manager>@<Host>.port (see page 100) <Queue Manager>@<Host>.channelname (see page 100) <Queue Manager>@<Host>.character.set (see page 101) <Queue Manager>@<Host>.delaytime (see page 101) <Queue Manager>@<Host>.report.static.freq (see page 101) <Queue Manager>@<Host>.ssl (see page 101) <Queue Manager>@<Host>.channel.ssl.cipherspec (see page 102) truststore.path (see page 102) keystore.path (see page 102) keystore.password (see page 102) Specific MQ Data Section 100 for IBM WebSphere MQ Guide mq.monitor.list Specifies the comma-separated list of all the WebSphere MQ Queue Manager instances to be monitored. Note: Ensure that the mq.monitor.list property does not contain ":" or "=". Default: None Example: If the Queue Manager instance is QM1, then set the property as: mq.monitor.list=QM1@<hostname>, QM1@<hostname> <Queue Manager>@<Host>.host Specifies the IP address or DNS name (hostname) of the Queue Manager that is listed in mq.monitor.list. Default: None Example: If the Queue Manager instance is QM1, then set the property as: QM1@<hostname>.host=localhost <Queue Manager>@<Host>.port Specifies the port numbers of the Queue Manager instances you listed in mq.monitor.list. Default: 1414 Example: QM1@<hostname>.port=5001 <Queue Manager>@<Host>.channelname Specifies the Server Connection Channel that is used to connect to the Queue Manager instance being monitored. Default: ■ SYSTEM.AUTO.SVRCONN ■ SYSTEM.DEF.SVRCONN (used if the default channel fails) Example: QM1@<hostname>.channelname=SYSTEM.AUTO.SVRCONN Specific MQ Data Section Chapter 8: Dashboards 101 <Queue Manager>@<Host>.character.set Specifies the character set ID that the Queue Manager uses. Default: 819 Example: QM1@<hostname>.character.set=819 <Queue Manager>@<Host>.delaytime Specifies the delay time (in seconds) between each query for WebSphere MQ data. Default: 600 seconds Example: QM1@<hostname>.delaytime=60 <Queue Manager>@<Host>.report.static.freq Specifies the frequency of metric collection for static metrics. This value is used as the denominator of a fraction, 1/n, where n is the number that is set for the property. Default: 20 Example: If QM1@<hostname>.report.static.freq=20, it means that the MQMonitor agent reports the results of only 1 out of every 20 queries. <Queue Manager>@<Host>.ssl Specifies whether SSL is enabled or disabled for communicating with the Queue Manager instance. Default: disable Example: To enable SSL for communication with Queue Manager instance QM1, set: QM1@<hostname>.ssl=enable MQ Events Section 102 for IBM WebSphere MQ Guide <Queue Manager>@<Host>.channel.ssl.cipherspec Specifies the CipherSpec used to communicate with the specific Queue Manager instance over SSL. MQMonitor agent uses this property value only when the SSL property is enabled. Default: None Example: QM1@<hostname>.channel.ssl.cipherspec=NULL_MD5 truststore.path Specifies 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, escape the backslashes. Default: <path name> Example: truststore.path=C:\\MQMonitor\\key\\truststore.jks keystore.path Specifies the location of the keystore containing certificates for authentication of the MQMonitor agent. If you require client authentication, set this property. Default: <path name> Example: keystore.path=C:\\MQMonitor\\key\\keyststore.jks keystore.password Specifies the keystore password. Default: <password> Example: keystore.password=<password> MQ Events Section Use this section to configure the MQMonitor agent to receive WebSphere MQ Event messages. Specify the queue names that receive the MQ Event messages on the WebSphere MQ Queue Manager. MQ Events Section Chapter 8: Dashboards 103 MQ Events include the following types: Queue manager events ■ Authority ■ Inhibit ■ Local ■ Remote ■ Start ■ Stop Channel and bridge events ■ Channel ■ SSL ■ Channel auto-definition Performance events ■ Queue depth ■ Queue service interval Note: MQMonitor agent does not support z/OS-only WebSphere MQ Events that are configuration events or command events. <Queue Manager>@<Host>.qmgr.event.queue Specifies the queue name of the Queue Manager Event Queue of a given Queue Manager. Default: SYSTEM.ADMIN.QMGR.EVENT <Queue Manager>@<Host>.event.destructive.get Specifies whether the event messages are removed from the Event queues after the MQMonitor agent reads them. Values: true or false Default: false Example: To remove the event messages from the Event queues, set the property as follows: <Queue Manager>@<hostname>.event.destructive.get=true MQ Events Section 104 for IBM WebSphere MQ Guide <Queue Manager>@<Host>.performance.event.queue Specifies the queue name of the Performance Event Queue of a given Queue Manager. Default: SYSTEM.ADMIN.PERFM.EVENT <Queue Manager>@<Host>.channel.event.queue Specifies the queue name of the Channel Event Queue of a given Queue Manager. Default: SYSTEM.ADMIN.CHANNEL.EVENT Special Settings Section Chapter 8: Dashboards 105 Special Settings Section Use this section to set the limit on the number of metrics to be displayed in the Investigator tree. You can specify the display level for the WebSphere MQ components using the following properties: ■ Queue Managers The property is <Queue Manager>@<Host>.monitor.manager ■ Queues The property is <Queue Manager>@<Host>.monitor.queue ■ Channels The property is <Queue Manager>@<Host>.monitor.channel ■ Channel Initiators (z/OS only) The property is <Queue Manager>@<Host>.monitor.channelinitiator ■ Page Sets (z/OS only) The property is <Queue Manager>@<Host>.monitor.pagesets ■ Logs (z/OS only) The property is <Queue Manager>@<Host>.monitor.log To set the display level for a component, refer to the component using its name and host name, and then specify the display level. For example, to set the display level to full for queues that belong to Queue Manager QM1, set the property as follows: QM1@<hostname>.monitor.queue=full For each component, the possible values are: Never Displays metrics for the component are never queried or displayed. Minimum Displays a limited set of metrics. Recommended Displays a larger set of metrics. Full Displays all metrics for this component. Advanced Settings Section 106 for IBM WebSphere MQ Guide To see which metrics belong to each value set, see Queue Manager metrics (see page 153). Advanced Settings Section Use this section to redefine the recommended metric set. By redefining the recommended set, you have both the minimum set and the metrics that are included in the recommended set. The display settings for MQMonitor agent metrics are listed in the tables in Queue Manager metrics. You can redefine the recommended metric set using the following properties: ■ Queue Managers The property is recommended.metrics.manager ■ Queues The property is recommended.metrics.queue ■ Channels The property is recommended.metrics.channel ■ Channel Initiators (z/OS only) The property is recommended.metrics.channelinitiator ■ Page Sets (z/OS only) The property is recommended.metrics.pagesets ■ Logs (z/OS only) The property is recommended.metrics.log To redefine the recommended metric set, list the metrics using component names and metric names. Separate individual metrics with commas. For example: recommended.metrics.queue: Queue Name, Queue Type, Cluster Queue Type In this example, the recommended list is redefined with only three members. However, you get both the minimum set of metrics and the three metrics defined in the recommended list. MQ Trace Related Properties Section Use this section for cross-process transaction tracing. MQ Trace Related Properties Section Chapter 8: Dashboards 107 These are the MQ Trace properties: trace.dlq.activity.enabled (see page 107) trace.polling.enabled (see page 107) trace.polling.interval (see page 108) trace.polling.retry.count (see page 108) trace.dlq.flag.time (see page 108) handshake.mqagent.id (see page 108) handshake.qm.host (see page 109) handshake.qm.port (see page 109) handshake.qm.channelname (see page 109) handshake.qm.character.set (see page 109) handshake.qm.ssl (see page 109) handshake.qm.channel.ssl.cipherspec (see page 110) handshake.queue (see page 110) trace.hold.maxduration (see page 110) More information: Cross-Process Transaction Tracing (see page 65) trace.dlq.activity.enabled Specifies if the MQMonitor agent is enabled or disabled to read trace data from Dead Letter Queue. Values: true or false Default: true Example: To enable the MQMonitor agent to read the Dead Letter Queue, set: trace.dlq.activity.enabled=true trace.polling.enabled Specifies if the MQMonitor agent searches the final destination queue to determine whether the message is consumed or not. Values: true or false Default: true MQ Trace Related Properties Section 108 for IBM WebSphere MQ Guide trace.polling.interval Specifies the time period after which the MQMonitor agent checks the final destination queue to see if the message is consumed or not. Options: ■ Minimum: 10 milliseconds ■ Maximum: 600000 milliseconds Default: 1000 milliseconds trace.polling.retry.count Specifies the number of times the MQMonitor agent checks the final destination queue for a particular message. Options: ■ Minimum: 1 ■ Maximum: 100 Default: 3 Example: trace.polling.retry.count=3 trace.dlq.flag.time Specifies the static time to be added to the MQ Trace when messages reach the Dead Letter Queue. Options: ■ Minimum: 1 second ■ Maximum: 1800 seconds Default: 30 seconds Example: trace.dlq.flag.time=30 handshake.mqagent.id Specifies the unique identification of the agent. This property is mandatory. Limits: 1 to 999999999 Default: None Example: handshake.mqagent.id=1 MQ Trace Related Properties Section Chapter 8: Dashboards 109 handshake.qm.host Specifies the IP address or DNS name of the common Queue Manager. Default: localhost Example: handshake.qm.host=localhost handshake.qm.port Specifies the port of the common Queue Manager. Default: 1414 Example: handshake.qm.port=123 handshake.qm.channelname Specifies the channel name of the common Queue Manager to be used for connections. Default: ■ SYSTEM.AUTO.SVRCONN ■ SYSTEM.DEF.SVRCONN (used if the default channel fails) Example: handshake.qm.channelname=SYSTEM.AUTO.SVRCONN handshake.qm.character.set Specifies the CCSID character set of the common Queue Manager for handshaking. Default: 819 Example: handshake.qm.character.set=819 handshake.qm.ssl Specifies if the SSL property is enabled or disabled when the common Queue Manager for handshaking is SSL-enabled. Values: enable, disable Default: disable Example: To turn off the SSL property of the Queue Manager, set: handshake.qm.ssl=disable MQ Auto Discovery Related Properties Section 110 for IBM WebSphere MQ Guide handshake.qm.channel.ssl.cipherspec Specifies the SSL CipherSpec of the common Queue Manager for handshaking. Default: None Example: handshake.qm.channel.ssl.cipherspec=NULL_MD5 handshake.queue Specifies the queue that is used for handshaking among all WebSphere MQ agents. Default: CA_WILY_HANDSHAKE. trace.hold.maxduration Specifies the time to hold and wait for all the traces to be received for the message flow. This value is the maximum time to hold the traces. CA APM for IBM WebSphere MQ sends the traces that are collected in the specified time, even if all the traces are not received in that interval. Note: If this property is set to 0, the MQ traces are not held and consolidated trace does not appear for the MQ trace segment. In this scenario, there is no sequencing of MQ traces. Options: ■ Minimum: 0 seconds ■ Maximum: 3600 seconds Default: 30 seconds Example: trace.hold.maxduration=60 MQ Auto Discovery Related Properties Section Use this section to enable auto-discovery of Queue Managers. These are the MQ Auto Discovery-related properties: mq.monitor.agent.id (see page 111) mq.autodiscovery.enabled (see page 111) mq.autodiscovery.queue (see page 111) mq.autodiscovery.properties.update (see page 111) More information: Auto-discover Queue Managers (see page 60) Filters Section Chapter 8: Dashboards 111 mq.monitor.agent.id Specifies the identification number for the MQMonitor agent Default: 101 Example: mq.monitor.agent.id=101 mq.autodiscovery.enabled Specifies if the auto discovery of Queue Managers is enabled or not. Restart the application restart to publish any change to this property. Value: true or false Default: true Example: mq.autodiscovery.enabled=true mq.autodiscovery.queue Specifies the queue that MQMonitor agent uses for auto discovery. This queue is the same queue that is specified in the MQAgent.properties file for the MQ Java Agent. Example: mq.autodiscovery.queue=CA_WILY_AUTODISCOVERY mq.autodiscovery.properties.update Specifies if MQMonitor.properties must be updated automatically with the auto discovered Queue Managers. Values: true or false Default: false Example: mq.autodiscovery.properties.update=false Filters Section Use this section for more metric filtering. For example, you can exclude all system queue metrics in favor of user-defined queue metrics. Filters Section 112 for IBM WebSphere MQ Guide These are the filters properties: <Queue Manager>@<Host>.filter.exclude.static (see page 112) <Queue Manager>@<Host>.queue.filter.exclude.system (see page 112) <Queue Manager>@<Host>.queue.filter.exclude.dynamic (see page 112) <Queue Manager>@<Host>.queue.filter.includeonly.regex (see page 113) <Queue Manager>@<Host>.channel.filter.includeonly.regex (see page 113) <Queue Manager>@<Host>.pagesets.filter.includeonly.regex (see page 113) <Queue Manager>@<Host>.log.filter.includeonly.regex (see page 113) <Queue Manager>@<Host>.filter.exclude.static Specifies if static metrics must be included or excluded while monitoring a given Queue Manager. Set the value to true to exclude static metrics and report only dynamic metrics in the Investigator tree. Values: true or false Default: false Example: To report both static and dynamic metrics of Queue Manager QM1, set the property: QM1@<hostname>.filter.exclude.static=false <Queue Manager>@<Host>.queue.filter.exclude.system Specifies if system queues must be included while monitoring the queues of a given Queue Manager. Set the value to true to exclude system queues in the Investigator tree. Does not filter the Dead Letter Queue. Values: true or false Default: true Example: QM1@<hostname>.queue.filter.exclude.system=true <Queue Manager>@<Host>.queue.filter.exclude.dynamic Specifies if dynamic queues must be included or excluded while monitoring the queues of a given Queue Manager. Set the value to true to exclude dynamic queues in the Investigator tree. Values: true or false Default: true Example: QM1@<hostname>.queue.filter.exclude.dynamic=true Filters Section Chapter 8: Dashboards 113 <Queue Manager>@<Host>.queue.filter.includeonly.regex Specifies the regular expression that the queue manager uses to filter the queues. Default: * (no filtering) Example: QM1@<hostname>.queue.filter.includeonly.regex=.* <Queue Manager>@<Host>.channel.filter.includeonly.regex Specifies the regular expression that the queue manager uses to filter the channels. Default: * (no filtering) Example: To show only those channels that start with test: QM1@<hostname>.channel.filter.includeonly.regex=test.* <Queue Manager>@<Host>.pagesets.filter.includeonly.regex Specifies the regular expression that the queue manager uses to filter the page sets by Page Set ID in z/OS and displays them as follows: Usage|Page Sets|PageSet<PageSet_ID> Default: * (no filtering) Example: To filter page sets, specify the Page Set ID in the regular expression: QM1@<hostname>.pagesets.filter.includeonly.regex=.*<PageSet_ID> <Queue Manager>@<Host>.log.filter.includeonly.regex Specifies the regular expression that the queue manager uses to filter the logs in z/OS and displays them as follows: Logs|Log Copy Records|Log<Log Copy Record No> Default: * (no filtering) 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> Chapter 8: Dashboards 115 Appendix C: MBMonitor.properties File This section contains the following topics: CMP Connection Section (see page 115) MQ Connection Section (see page 116) Statistics Section (see page 116) Broker (JMS) Connection Section (see page 117) Execution Group Section (see page 118) Node Statistics Section (see page 118) Delay Times Section (see page 118) Monitoring Level Settings Section (see page 119) Advanced Settings Section (see page 120) SSL Configuration Section (see page 121) CMP Connection Section Use this section to monitor brokers. After the CMP connection is established, the Investigator tree displays all Brokers, Execution Groups, and Message Flows under the configuration manager tree. To turn off WebSphere MB 6.x monitoring, leave the settings in the CMP Connection section empty. configuration.manager.host Specifies the Configuration Manager Proxy (CMP) machine name or IP address. Default: null Example: configuration.manager.host=localhost configuration.manager.queue.manager Specifies the CMP Queue Manager name. Default: null Example: configuration.manager.queue.manager=WBRK6_DEFAULT_QUEUE_MANAGER MQ Connection Section 116 for IBM WebSphere MQ Guide configuration.manager.port Specifies the CMP Queue Manager port. Default: null Example: configuration.manager.port=2414 MQ Connection Section Use this section to list the brokers for which the associated MQ objects must be displayed. As part of Message Broker monitoring, you can monitor the Queue Manager for each broker and configuration manager. This action causes the Queue Manager to appear in the CA Introscope® tree twice: ■ Under the Queue Managers node, as part of WebSphere MQ monitoring. ■ Under the <Broker> that is associated with the Queue Manager. Values: all, none, list of brokers Default: all Example: mq.broker.list=BROKER1,BROKER2 Statistics Section Use this section to list the brokers for which the Broker statistics and Message Flow statistics must be displayed. Values: all, none, list of brokers Default: all Example: statistics.broker.list=BROKER1,BROKER2 Important! Use the following command to trigger statistics reports for message flow statistics and broker statistics: mqsichangeflowstats <BROKER1> -s -e <ExecutionGroup> -j -c active -o xml -n basic Use the following command to enable Publish/Subscribe statistics for the brokers: mqsichangeproperties <BROKER1> -e <ExecutionGroupName> -o DynamicSubscriptionEngine -n statsInterval -v 30000 Broker (JMS) Connection Section Chapter 8: Dashboards 117 Broker (JMS) Connection Section Use this section to establish a JMS connection. This section is optional if the Configuration Manager shares a Queue Manager with a broker. SYSTEM.DEF.SVRCONN channel is used for the JMS connection. To configure any other channel for JMS connection, use the jms.broker.channel property as follows: jms.broker.channel = SYSTEM.TESTCHANNEL.SVRCONN Note: Verify that the deployment of the pub/sub topology was successful if there is a problem with the intercommunication between the brokers in the collective. To redeploy the topology, issue the following IBM command where machine, port, and Queue Manager are the values of the configuration manager: mqsideploy -i <machine> -p <port> -q <queue manager> -l –m These are the Borker (JMS) Connection properties: jms.broker.host (see page 117) jms.broker.queue.manager (see page 117) jms.broker.port (see page 117) jms.broker.host Specifies the JMS machine name or IP address. Default: Null jms.broker.queue.manager Specifies the JMS Queue Manager name Default: Null jms.broker.port Specifies the JMS Queue Manager port. Default: Null Execution Group Section 118 for IBM WebSphere MQ Guide Execution Group Section Use this section to list the Execution Groups for which statistics must be collected. Ignore this section if you do not want to report execution groups. Note: Any broker you list in this section must also be listed in the statistics.broker.list section. Values: all, list of execution groups Example: If the broker name is broker1, then set the property as follows: broker1.executiongroup=ExecutionGroup1,ExecutionGroup2 Node Statistics Section Use this section to view the statistics for the user-specified node types in the Investigator. Note: By default, the MQMonitor agent reports statistics for the JniNode. Example: ■ To display statistics for a list of nodes, node.type.list= JniNode,MQOutputNode ■ To display statistics for all the nodes, node.type.list=all Delay Times Section Use this section to specify the time interval between CMP queries by editing the static.delaytime setting. Options: ■ Minimum: 15 seconds ■ Maximum: 3600 seconds Default: 1800 seconds Example: static.delaytime=1800 Monitoring Level Settings Section Chapter 8: Dashboards 119 Monitoring Level Settings Section Use this section to 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 Displays no metrics. Minimum Displays only a few metrics essential to triage WebSphere MB problems. Recommended Displays all data from the minimum level, plus a few extra metrics. Full Displays all possible metrics. Note: By default, the monitoring level is set to recommended. The metric set for minimum and full monitoring levels are predefined, and you cannot change them. The metrics in the recommended monitoring level can be configured by specifying a metric list in the recommended.metrics.messageflow.statistics and recommended.metrics.broker.statistics properties of the MBMonitor.properties file. 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: The broker name is ignored if you use a broker name that is not included in the statistics.broker.list property. <brokername>.messageflow.statistics Specifies the monitoring level for Message Flow Statistics that are reported for a broker. Example: For brokers BROKER1 and BROKER2, BROKER1.messageflow.statistics=full BROKER2.messageflow.statistics=minimum Advanced Settings Section 120 for IBM WebSphere MQ Guide <brokername>.broker.statistics Specifies the monitoring level for Broker Statistics that are reported for a broker. Example: For brokers BROKER1 and BROKER2, BROKER1.broker.statistics=recommended BROKER2.broker.statistics=never Advanced Settings Section Use this section to redefine the recommended monitoring level for the Message Flow Statistics and Broker Statistics.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. Note: The properties in this section cannot be set for each broker. recommended.metrics.messageflow.statistics Specifies the list of metrics for Message Flow Statistics at the recommended monitoring level. Default: Null Example: recommended.metrics.messageflow.statistics=MQ Errors Total, CPU Processing Time recommended.metrics.broker.statistics Specifies the list of metrics for Broker Statistics at the recommended monitoring level. Default: Null Example: recommended.metrics.broker.statistics=Bytes Dropped Total, Bytes Queued Total SSL Configuration Section Chapter 8: Dashboards 121 SSL Configuration Section cmp.ssl Specifies whether the SSL connection for CMP is enabled or not. Default: disable Example: cmp.ssl=disable jms.ssl Specifies whether the SSL connection for the JMS broker is enabled or not. Default: disable Example: jms.ssl=disable cmp.connection.ssl.cipherspec Specifies the CipherSpec for the CMP SSL connection. Example: To specify the CipherSpec for the CMP Queue Manager, set the property as: cmp.connection.ssl.cipherspec=NULL_MD5 jms.connection.ssl.cipherspec Specifies the CipherSpec for the JMS connection. Example: To specify the CipherSpec for the CMP Queue Manager, set the property as: cmp.connection.ssl.cipherspec=NULL_MD5 truststore.path Specifies the truststore path of the SSL key repository that is 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. Default: <path name> Example: truststore.path=C:\\MQMonitor\\key\\truststore.jks SSL Configuration Section 122 for IBM WebSphere MQ Guide keystore.path Specifies the keystore path of the SSL key repository that is 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. Default: <path name> Example: keystore.path=C:\\MQMonitor\\key\\keystore.jks keystore.password Specifies the keystore password of the SSL key repository that is used for both CMP and JMS SSL connections. Default: <password> Example: keystore.password=<password> Chapter 8: Dashboards 123 Appendix D: MBMonitor_7.properties File This section contains the following topics: CMP Connection Section (see page 123) MQ Connection Section (see page 124) Statistics Section (see page 125) Execution Group Section (see page 125) Node Statistics Section (see page 126) Delay Times Section (see page 126) Monitoring Level Settings Section (see page 127) Advanced Settings Section (see page 127) SSL Configuration Section (see page 128) CMP Connection Section Use this section to monitor brokers. The Investigator tree displays execution groups and message flows under each broker node. To turn off WebSphere MB 7.0 or 8.0 monitoring, leave the settings in the CMP Connection section empty. mq.broker.monitor.list Specifies the brokers to monitor. Default: null Example: mq.broker.monitor.list= a,b a.host Specifies the broker machine name or IP address. Default: null Example: a.host=localhost MQ Connection Section 124 for IBM WebSphere MQ Guide a.queue.manager Specifies the broker queue manager name. Default: null Example: a.queue.manager=WBRK6_DEFAULT_QUEUE_MANAGER a.port Specifies the broker queue manager port. Default: null Example: a.port=2414 MQ Connection Section Use this section to monitor the Queue Manager for each broker. Values: all, none, list of brokers Default: all Example: mq.broker.list=BROKER1,BROKER2 Statistics Section Chapter 8: Dashboards 125 Statistics Section Use the section to list the brokers for which the Message Flow statistics must be displayed. Note: Use the following command to trigger statistics reports for message flow statistics and broker statistics: mqsichangeflowstats <BROKER1> -s -e <ExecutionGroup> -j -c active -o xml -n basic Set the a.messageflow.statistics property to one of the following values: Never Never reports message flow statistics for brokers. Minimum Reports the minimum number of message flow statistics for brokers. Recommended Reports the recommended number of message flow statistics for brokers. Full Never reports message flow statistics for brokers. Execution Group Section Use this section to list the Execution Groups for which statistics must be collected. Ignore this section if you do not want to report execution groups. Note: Any broker you list in this section must also be listed in the statistics.broker.list section. Values: all, list of execution groups Example: If the broker name is a, then set the property as follows: a.executiongroup=ExecutionGroup1,ExecutionGroup2 Node Statistics Section 126 for IBM WebSphere MQ Guide Node Statistics Section Use this section to view the statistics for the user-specified node types in the Investigator. Ignore this section if you do not want to report node statistics Note: By default, the MQMonitor agent reports statistics for the JniNode. Example: ■ To display statistics for a list of nodes, node.type.list= JniNode,MQOutputNode ■ To display statistics for all the nodes, node.type.list=all Delay Times Section Use this section to specify the time interval between CMP queries by editing the static.delaytime property. Options: ■ Minimum: 15 seconds ■ Maximum: 3600 seconds Default: 1800 seconds Example: static.delaytime=1800 Monitoring Level Settings Section Chapter 8: Dashboards 127 Monitoring Level Settings Section Use this section to specify different monitoring levels for metrics of Message Flow Statistics. You can set the monitoring level to the following values: Never Displays no metrics. Minimum Displays the minimum set of metrics required to monitor the status of message flows to create the built-in dashboards and type views. Recommended Displays the minimum set of metrics and a few more metrics required to monitor the message flows. Full Displays all the metrics for Message Flow Statistics. Note: By default, the monitoring level is set to recommended. The metric set for minimum and full monitoring levels are predefined, and you cannot change them. The metrics in the recommended monitoring level can be configured by specifying a metric list in the recommended.metrics.messageflow.statistics in the MBMonitor_7.properties file. <brokername>.messageflow.statistics Specifies the monitoring level for Message Flow Statistics that are reported for a broker. Note: Use the same broker name that you have mentioned in the 'mq.broker.monitor.list' property. Example: For a broker a, a.messageflow.statistics=full a.messageflow.statistics=minimum Advanced Settings Section Use this section to redefine the recommended monitoring level for the Message Flow Statistics.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. Ignore this section if you do not want to redefine the recommended monitoring level for the Message Flow Statistics. SSL Configuration Section 128 for IBM WebSphere MQ Guide recommended.metrics.messageflow.statistics Specifies the list of metrics for Message Flow Statistics at the recommended monitoring level. Default: Null Example: recommended.metrics.messageflow.statistics=MQ Errors Total, CPU Processing Time SSL Configuration Section Use this section to specify the SSL properties for Broker JMS Connection. Ignore this section if you do not want to configure Broker JMS Connection over SSL. .ssl Specifies whether the SSL connection for the queue manager of the broker is enabled or not. Default: disable Example: a.ssl=disable broker.connection.ssl.cipherspec Specifies the CipherSpec for the CMP connection. Example: broker.connection.ssl.cipherspec=NULL_MD5 jms.connection.ssl.cipherspec Specifies the CipherSpec for the JMS connection. Example: jms.connection.ssl.cipherspec=NULL_MD5 truststore.path Specifies the truststore path of the SSL key repository that is 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. Default: <path name> Example: truststore.path=C:\\MQMonitor\\key\\truststore.jks SSL Configuration Section Chapter 8: Dashboards 129 keystore.path Specifies the keystore path of the SSL key repository that is 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. Default: <path name> Example: keystore.path=C:\\MQMonitor\\key\\keystore.jks keystore.password Specifies the keystore password of the SSL key repository that is used for both CMP and JMS SSL connections. Default: <password> Example: keystore.password=<password> Chapter 8: Dashboards 131 Appendix E: Metrics Reference This appendix describes the CA Introscope® metrics that you can view using CA APM for IBM WebSphere MQ. Note: Time measurements appearing in CA Introscope® are in milliseconds (thousandths of a second). When WebSphere MQ provides metrics in microseconds, CA Introscope® converts this time measurement to milliseconds. This section contains the following topics: General Metric Characteristics (see page 131) Queue Manager Cluster Metrics (see page 132) Queue Manager Metrics (see page 153) Message Broker Metrics (see page 186) Find MQ Java Connector Metrics (see page 199) General Metric Characteristics Each 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. The following table shows an example: Metric name String Mapped Value Channel Type Domain|Hostname|...|...|Queue Managers|Queue manager hostname|Queue Manager name|Channels|SYSTEM.DEF.SVRCONN|Configuratio n 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 the number of incidents over the last interval. Queue Manager Cluster Metrics 132 for IBM WebSphere MQ Guide Metric Display Sets CA APM for IBM WebSphere MQ uses a configuration setting for each group of MQMonitor agent metrics, assigning it to one of the following sets: M—Minimum Contains the minimum metrics. R—Recommended Contains all the metrics in the Minimum set and some more metrics. You can redefine the Recommended metrics that are set by editing the Advanced Settings section of the MQMonitor.properties file. The Advanced Settings section lists the WebSphere MQ and WebSphere MB component members. F—Full Contains all the metrics. Each metric is set to membership in one of these sets, which determine whether the Investigator displays the metric for each WebSphere MQ component. To change the metric set for a given metric, see the Special Settings section of the MQMonitor.properties file. Queue Manager Cluster Metrics In 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 more cluster related attributes and metric data of child objects that are compared to the normal tree objects. Cluster workload balance metrics show work that is distributed over multiple instances of same-named queues. The Investigator displays workload balance metrics on this cluster queue. Queue Manager Cluster Metrics Chapter 8: Dashboards 133 Aggregate Clusters Status Metrics At the top of the Queue Manager Clusters tree, the Investigator displays aggregated status metrics over all clusters. 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 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 CA APM for IBM WebSphere MQ 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. 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 Queue Manager Cluster Metrics 134 for IBM WebSphere MQ Guide 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 Aggregated Queue Manager Metrics For each Queue Manager beneath a host name, the Investigator displays the following 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 CA APM for IBM WebSphere MQ with all the Queue Managers. 0 or green = successful 1 or red = unsuccessful Queue Manager Cluster Metrics Chapter 8: Dashboards 135 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 the following 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. 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 Configuration Properties For each cluster queue on this Queue Manager, the Investigator displays the following 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 136 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description 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. 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 Manager Cluster Metrics Chapter 8: Dashboards 137 Metric name Type Monitoring Level Description 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. Status Metrics For each cluster queue on this Queue Manager, the Investigator displays the following status metrics. To see data for the Oldest Message Age and Queue Time metrics, Queue Monitoring must be enabled in WebSphere MQ. 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. Queue Manager Cluster Metrics 138 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description 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. 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. Queue Manager Cluster Metrics Chapter 8: Dashboards 139 Metric name Type Monitoring Level Description 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.) 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. More information: Turn On Queue Monitoring (see page 45) Queue Manager Cluster Metrics 140 for IBM WebSphere MQ Guide 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. Channel definitions have the same Queue Manager name as the cluster Queue Manager, whereas the instances have nodes that are 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. 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. Queue Manager Cluster Metrics Chapter 8: Dashboards 141 Metric name Type Monitoring Level Description 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. Status Metrics The same set of status metrics can appear under the Cluster-Receiver Channel node and the Cluster-Sender Channel node. 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. Queue Manager Cluster Metrics 142 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description 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. 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. Queue Manager Cluster Metrics Chapter 8: Dashboards 143 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. Queue Manager Cluster Metrics 144 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description CLWL Channel Priority Number R Cluster workload channel priority. 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. These queues are 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. Queue Manager Cluster Metrics Chapter 8: Dashboards 145 Metric name Type Monitoring Level Description 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. Status Metrics 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. Queue Manager Cluster Metrics 146 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description Command Server Status (not available on z/OS) Mapped Value M One of: 2 = MQQMSTA_RUNNING 0 = Unknown 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. Metrics under the Status node show Queue Manager status. Queue Manager Cluster Metrics Chapter 8: Dashboards 147 Workload Balance Metrics Workload Balance metrics provide information about queues which have multiple instances within a cluster, residing on more than one Queue Manager. The Workload Balance tree is organized according to the following hierarchy: Workload Balance Multi-instance Queue A Aggregated metrics across the Queue Managers on this host host Queue Manager 01 Configuration Properties Status Queue Manager 02 Multi-instance Queue B Aggregated metrics across the Queue Managers on this host host Queue Manager 03 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. Queue Metrics For each of the Queue Managers on which an instance of the queue resides, the Investigator displays the following: ■ 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. Queue Manager Cluster Metrics 148 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description 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 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 Manager Cluster Metrics Chapter 8: Dashboards 149 Metric name Type Monitoring Level Description 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. 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. Status To see data for the Oldest Message Age and Queue Time metrics, enable Queue Monitoring in WebSphere MQ. 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. Queue Manager Cluster Metrics 150 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description 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. 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. Queue Manager Cluster Metrics Chapter 8: Dashboards 151 Metric name Type Monitoring Level Description Open Output Count Number Dynamic M The number of handles that are currently open for output for the queue on this Queue Manager. 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 (see page 152). 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. More information: Turn On Queue Monitoring (see page 45) Queue Manager Cluster Metrics 152 for IBM WebSphere MQ Guide Percent Queue Depth Variation The percentage Queue Depth Variation metric shows the deviation of the Queue Depth from a calculated average. The calculation of the variation is based on the following two 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: % Variation = ((curreqdepth - aveqdepth) / aveqdepth) * 100 When the current queue depth is lesser than the 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 percent from the average, while QM3 is -100 percent (negative 100 percent), correctly indicating a problem with QM3. Queue Manager Metrics Chapter 8: Dashboards 153 Queue Manager Metrics The Investigator displays Queue Manager metrics in a tree.The tree has the following high-level structure: Queue Managers Aggregated status metrics across all hosts Host name Aggregated status metrics for all Queue Managers on the host Queue Manager name Aggregate status metrics for the Queue Manager Channel Initiator (z/OS only) Channels Configuration Properties Dead Letter Queue Last Check Logs (z/OS only) Queues Status Transmission Queue Usage (z/OS only) Note: The Investigator displays aggregated status metrics across hosts, all Queue Managers, and for all queues on a Queue Manager. 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 CA APM for IBM WebSphere MQ 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 Queue Manager Metrics 154 for IBM WebSphere MQ Guide Metric name Type Description 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 CA APM for IBM WebSphere MQ 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 the Queue Manager. 0 =no queue has reached the maximum queue depth 1 = one or more queues have reached the maximum queue depth Queue Manager Metrics Chapter 8: Dashboards 155 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 CA APM for IBM WebSphere MQ 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 Configuration Properties Metric name Type Monitoring Level Description Channel Name String R Name of the channel. Queue Manager Metrics 156 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description 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. 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. 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. Note: This metric is available only for cluster-sender channel Queue Manager Metrics Chapter 8: Dashboards 157 Metric name Type Monitoring Level Description 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. Status Metrics 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. Note: This metric is available only for cluster channels. 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. Queue Manager Metrics 158 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description Current Messages Number Dynamic M Number of messages in the current batch. 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. 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. 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. Queue Manager Metrics Chapter 8: Dashboards 159 Metric name Type Monitoring Level Description 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. Configuration Properties Metrics 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. Queue Manager Metrics 160 for IBM WebSphere MQ Guide Metric name Type Monitoring level Description 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. Queue Manager Metrics Chapter 8: Dashboards 161 Metric name Type Monitoring level Description 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. 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. Queue Manager Metrics 162 for IBM WebSphere MQ Guide Metric name Type Monitoring level Description 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. Default Transmission Queue String R Indicates the default transmission queue of the Queue Manager Description String R Description of the Queue Manager. Queue Manager Metrics Chapter 8: Dashboards 163 Metric name Type Monitoring level Description 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. 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, Queue Manager Metrics 164 for IBM WebSphere MQ Guide Metric name Type Monitoring level Description IGQ Authority Check Type (z/OS only) (cont.) Mapped Value F 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. 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. Queue Manager Metrics Chapter 8: Dashboards 165 Metric name Type Monitoring level Description 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. 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. Queue Manager Metrics 166 for IBM WebSphere MQ Guide Metric name Type Monitoring level Description 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. 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. Queue Manager Metrics Chapter 8: Dashboards 167 Metric name Type Monitoring level Description 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. 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. Queue Manager Metrics 168 for IBM WebSphere MQ Guide Metric name Type Monitoring level Description 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. 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. Transmission Queue String F Indicates the Transmission Queue of the Queue Manager. Trigger Interval Number F Trigger interval, expressed in milliseconds, for use only with queues where TriggerType has a value of MQTT_FIRST. Queue Manager Metrics Chapter 8: Dashboards 169 Metric name Type Monitoring level Description 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. Transmission Queue Metrics The Transmission Queue node can contain all the metrics that appear under a regular queue. More information: Queue Metrics (see page 170) 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 CA APM for IBM WebSphere MQ 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. Queue Manager Metrics 170 for IBM WebSphere MQ Guide 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. Note: This metric is available only for alias queues. 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 Chapter 8: Dashboards 171 Metric name Type Monitoring Level Description 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. Queue Manager Metrics 172 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description Process Name String F Name of the process. 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. Queue Manager Metrics Chapter 8: Dashboards 173 Metric name Type Monitoring Level Description 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 Manager Metrics 174 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description 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. 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. 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. Queue Manager Metrics Chapter 8: Dashboards 175 Metric name Type Monitoring Level Description 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. Status Metrics To see data for the Oldest Message Age and Queue Time metrics, Queue Monitoring must be enabled in WebSphere MQ. 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. Rate of Queuing Number Dynamic M The rate of queuing is calculated using the ((Enqueue Count - Dequeue Count)/Enqueue Count) formula. 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. Queue Manager Metrics 176 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description Dequeue Count Per Minute Number Dynamic R Running count of the number of message dequeues in the last minute. 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. Queue Manager Metrics Chapter 8: Dashboards 177 Metric name Type Monitoring Level Description Open Output Count Number Dynamic M Number of handles that are currently valid for adding messages to 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 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. More information: Turn On Queue Monitoring (see page 45) Queue Manager Metrics 178 for IBM WebSphere MQ Guide 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 Chapter 8: Dashboards 179 Metric name Type Monitoring Level Description 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. 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 the following groups: ■ Configuration Properties ■ Log Copy Records ■ Status Queue Manager Metrics 180 for IBM WebSphere MQ Guide Configuration Properties 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. 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. Queue Manager Metrics Chapter 8: Dashboards 181 Metric name Type Monitoring Level Description 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. 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 182 for IBM WebSphere MQ 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 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 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. Queue Manager Metrics Chapter 8: Dashboards 183 Metric name Type Monitoring level Description 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 184 for IBM WebSphere MQ 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. 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. Queue Manager Metrics Chapter 8: Dashboards 185 Metric name Type Monitoring Level Description 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. 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. Message Broker Metrics 186 for IBM WebSphere MQ Guide Message Broker Metrics The Investigator displays Message Broker metrics in a tree with various nodes. For each Message Broker that you configure to send metrics to CA Introscope®, you can view the following: ■ Broker properties ■ Metrics for each execution group ■ Metrics for the Queue Manager belonging to the Message Broker – Aggregate metrics and "traffic lights" are based on calculations done by the Enterprise Manager, which uses a default interval. This value is almost always 15 seconds. – Message Flow metrics are based on reports from WebSphere Message Broker and use the default interval (20 seconds) of the Message Broker. – Metrics that are returned by the CMP (Configuration Manager Proxy) are based on the results of queries that are sent at a frequency. The administrator defines the frequency using the Static Delay Time setting in the MBMonitor.properties file. See CMP Connection Section (mandatory). Note: The intervals that are used by the Message Broker metrics can vary. 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. These metrics are described in the following table. Note: These metrics are reported only for WebSphere MB 6.0 through 6.1. 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 Chapter 8: Dashboards 187 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 that are managed by the broker. The totals are calculated and have a 15-second interval, and everything else comes from the CMP basic topology. Note: Valid for WebSphere MB 6.0 through 6.1. 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. Execution Groups Metrics Execution Groups are logical groupings of message flows within a broker. The metrics that are shown under the Execution Groups node are aggregated across all Execution Groups on the broker. Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. Metric name Type Description Backouts Total Number Aggregate total of messages backed out across all Execution Groups under this node. Message Broker Metrics 188 for IBM WebSphere MQ Guide 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 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 Identifies the processor architecture of the Execution Group. The following values are reported to CA Introscope® for different architecture execution groups: ■ 32-bit for 32-bit architecture ■ 64-bit for 64-bit architecture ■ default 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 Total ■ Messages Dropped Total Message Broker Metrics Chapter 8: Dashboards 189 Metric name Type Description Architecture String Identifies the processor architecture of the Execution Group. The following values are reported to CA Introscope® for different architecture execution groups: ■ 32-bit for 32-bit architecture ■ 64-bit for 64-bit architecture ■ default for default architecture 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. Note: These metrics are reported only for WebSphere MB 6.x. The Broker Statistics node contains the following summary nodes: Client statistics Displays message throughput between the broker and clients that are connected to the broker. Neighbor statistics Displays message throughput between the broker and any other brokers with which it has been configured as a neighbor to share publications and subscriptions. Wide Statistics Displays subscriber, client, and neighbor counts for the broker. Client and Neighbor Statistics report the metrics in the following table. 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. Message Broker Metrics 190 for IBM WebSphere MQ Guide Client and Neighbor Statistics Client Statistics report on message throughput between clients that are connected to the broker. Neighbor Statistics report on message throughput between brokers which have been configured as neighbors. Note: These metrics are reported only for WebSphere MB 6.x. 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. 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. Message Broker Metrics Chapter 8: Dashboards 191 Wide Statistics Note: These metrics are reported only for WebSphere MB 6.x. 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. 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" ... Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. Message Broker Metrics 192 for IBM WebSphere MQ Guide Message Flow Statistics A Message Flow contains two or more Message Nodes. Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. 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. Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. 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). 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. Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. Message Broker Metrics Chapter 8: Dashboards 193 Aggregate Metrics Across All Message Flows At the top of the Message Flows tree, you can see aggregate metrics for all Message Flows. Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. 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 Total ■ Messages 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 that are mixed: ■ Message Flow properties (for example, Message Flow State) ■ Aggregate metrics for all nodes under the Message Flow Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. 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. Message Broker Metrics 194 for IBM WebSphere MQ Guide Metric name Type Description 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: ■ RUNNING ■ STOPPED 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. Total Broker Threads for Message Flow Number The number of additional threads that the broker can use to service the message flow. Message Broker Metrics Chapter 8: Dashboards 195 Errors Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. 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 Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. 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. Message Broker Metrics 196 for IBM WebSphere MQ Guide Message Statistics Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. 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: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. 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. 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. Message Broker Metrics Chapter 8: Dashboards 197 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 Performance Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. 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) Elapsed Time Waiting For Input Average Number F Average elapsed time spent waiting for input messages (in milliseconds) Message Broker Metrics 198 for IBM WebSphere MQ Guide Metric name Type Monitoring Level Description Elapsed Time Waiting For Input Total Number F Total elapsed time spent waiting for input messages (in milliseconds) Broker Queue Manager Metrics Beneath the Execution Groups node in the Message Broker metrics tree is a node for the Queue Manager of the Message Broker. Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. The Investigator displays the same set of metrics for this Queue Manager as detailed in the section on Queue Manager metrics (see page 153). Configuration Manager Queue Manager Metrics Metrics for the Queue Manager of the Configuration Manager appear under a Configuration Manager|Dedicated Queue Manager node in the WebSphere MB metrics tree. Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. The Investigator displays the same set of metrics for this Queue Manager as detailed in Queue Manager metrics (see page 153). Display of Shared and Nonshared Queue Managers The Message Broker topology lets the user use the same Queue Manager for the Configuration Manager and its default Broker. The Configuration Manager and only one Broker share the Queue Manager. The agent reports this Queue Manager and its related metrics under the Broker in the Investigator tree. In cases where the Configuration Manager has its own nonshared Queue Manager, the Queue Manager appears beneath the Configuration Manager|Dedicated Queue Manager node. This level is on the same level in which brokers appear. Note: These metrics are reported for WebSphere MB 6.x and WebSphere MB 7.0. Find MQ Java Connector Metrics Chapter 8: Dashboards 199 Find MQ Java Connector Metrics WebSphere 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) are a set of Java classes that implement JMS interfaces to enable JMS programs to access WebSphere MQ systems. To find nodes relevant to MQ Java Connectors, expand the SuperDomain node and look under the <hostname>, WebSphere, WebSphereAgent (*SuperDomain*) node. Operational Groups MQ returns metrics from MQ Java base classes using operational groups. More information: JCA/JMS Operational Groups (see page 205) Backend Metrics CA 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. Find MQ Java Connector Metrics 200 for IBM WebSphere MQ Guide The following metrics display for the WebSphere MQ server: ■ Aggregate metrics ■ Queue Manager with the following nodes: – Aggregate metrics – Connector node: ■ Operations ■ Queues – JMS node: ■ Operations ■ Queues Instance Counts Metrics The Investigator displays instance counts for the WebSphere MQ base classes under the Instance Counts node. To enable Instance counts, uncomment webspheremq_instancecounts.pbd in the webspheremq.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 named 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). Note: Metrics that are 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. Find MQ Java Connector Metrics Chapter 8: Dashboards 201 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 higher. WebSphereMQ Node Metrics Under the WebSphereMQ node, you see most of the metrics you can use to monitor the performance of your WebSphere MQ Java Connectors. Note: These aggregated metrics are visible only when the corresponding Operations are invoked. Note: The Average Response Time (ms) for Commit and Rollback Operations are aggregated together. Metric Description Average Response Time (ms) The weighted average response times for all operational groups of this name on nodes lower in the tree The metrics are organized by operation name, but they are all the same metric. The tree hierarchy is as follows: Top level node (Connector/JMS) Aggregate response time metrics, organized by Operational Group name host name Queue Manager Name Operations Operational Group Aggregate metrics for the operational group Individual operation name Metrics for the individual operation Find MQ Java Connector Metrics 202 for IBM WebSphere MQ Guide Queues Individual queue name Operational group Aggregate metrics for the operational group Individual operation name Metrics for the individual operation Topics (JMS only) Individual topic name Operational group Aggregate metrics for the operational group Individual operation name Metrics for the individual operation Operational Groups The Investigator displays metrics on operations (such as connect, get, rollback) under the following Operation Groups: ■ Connect ■ Disconnect ■ Send ■ Receive ■ Commit ■ Rollback ■ Close 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. Find MQ Java Connector Metrics Chapter 8: Dashboards 203 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: CA 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 previous table in the Java Connectors tree, the interval is always the default CA Introscope® interval. 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. ErrorDetector Metrics The webspheremq_errors.pbd file (see Configure ErrorDetector) generates Errors Per Interval metrics that appear under several operational group nodes. 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 that is involved in the error selected. Chapter 8: Dashboards 205 Appendix F: JCA/JMS Operational Groups This appendix lists the operation names for each Operational Group. This section contains the following topics: JCA Operational Groups (see page 205) JMS Operational Groups (see page 209) JCA Operational Groups This section describes the following JCA Operational Groups: ■ JCA Queue Manager Operations ■ JCA Queue Operational Groups JCA Operational Groups 206 for IBM WebSphere MQ Guide JCA Queue Manager Operations Disconnect Operational Group ■ Operation name: Manager Disconnect Description: Monitors the Queue Manager disconnect functions in the com.ibm.mq.jar file. ■ Operation name: Unregister Description: Monitors the Queue Manager unregister functions in the com.ibm.mq.jar file. ■ Operation name: Cleanup Description: Monitors the cleanup functions that are called on the Queue Manager object in the com.ibm.mq.jar file. ■ Operation name: Destroy Description: Monitors the destroy functions that are called on the Queue Manager object in the com.ibm.mq.jar file. ■ Operation name: Session Disconnect Description: Monitors all the session disconnection operations on the Queue Manager object in the com.ibm.mq.jar file. Connect Operational Group ■ Operation name: Begin Description: Monitors the Queue Manager begin() operation in the com.ibm.mq.jar file. ■ Operation name: Access Process Description: Monitors the Queue Manager process access operation in the com.ibm.mq.jar file. ■ Operation name: Get Connection Description: Monitors the Queue Manager connection get operations in the com.ibm.mq.jar file. JCA Operational Groups Chapter 8: Dashboards 207 ■ Operation name: Session Connect Description: Monitors the Queue Manager session connect operations, such as MQCONN, MQCONNX in the com.ibm.mq.jar file. ■ Operation name: XA Session Start Description: Monitors the Queue Manager session start operations in the com.ibm.mq.jar file. ■ Operation name: XA Session Prepare Description: Monitors the Queue Manager XA enabled prepare session operations in the com.ibm.mq.jar file. ■ Operation name: Queue Process Get Type Description: Monitors the Application Type operations in the com.ibm.mq.jar file. Commit Operational Group ■ Operation name: Manager Commit Description: Monitors the Queue Manager commit operations in com.ibm.mq.jar. ■ Operation name: Session Commit Description: Monitors the Queue Manager session client commit operations in com.ibm.mq.jar. ■ Operation name: XA Session Commit Description: Monitors the Queue Manager XA enabled session client commit operations in com.ibm.mq.jar. Put Operational Group ■ Operation name: Manager Put Description: Monitors the Queue Manager put operations in com.ibm.mq.jar. ■ Operation name: Distribution List Put Description: Monitors the Queue Manager distribution list put operations in com.ibm.mq.jar. JCA Operational Groups 208 for IBM WebSphere MQ Guide Get Operational Group ■ Operation name: Access Queue Description: Monitors the Queue Manager queue access operations in com.ibm.mq.jar. ■ Operation name: Distribution List Get Description: Monitors the Queue Manager distribution list get operations in com.ibm.mq.jar. ■ Operation name: Get Count Description: Monitors the Queue Manager getcount() operation Open Operational Group ■ Operation name: Session Open Description: Monitors the session client open operations in the com.ibm.mq.jar file. ■ Operation name: XA Session Open Description: Monitors the XA enabled session client open operations in the com.ibm.mq.jar file. Close Operational Group ■ Operation name: Session Close Description: Monitors the session client close operations in the com.ibm.mq.jar file. ■ Operation name: XA Session Close Description: Monitors the XA enabled session client close operations in the com.ibm.mq.jar file. ■ Operation name: Process Close Description: Monitors the mqprocess object operations in the com.ibm.mq.jar file. JMS Operational Groups Chapter 8: Dashboards 209 Rollback Operational Group ■ Operation name: Session Rollback Description: Monitors the session client rollback operations in the com.ibm.mq.jar file. ■ Operation name: XA Session Rollback Description: Monitors the XA enabled session client rollback operations in the com.ibm.mq.jar file. ■ Operation name: XA Session Recover Description: Monitors the session client recover operations in the com.ibm.mq.jar file. JCA Queue Operational Groups Put Operational Group ■ Operation name: Queue Put Description: Monitors the queue put operations in the com.ibm.mq.jar file. Get Operational Group ■ Operation name: Queue Get Description: 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 JMS Operational Groups 210 for IBM WebSphere MQ Guide JMS Queue Manager Operational Groups Receive Operational Group ■ Operation name: Create Receiver Description: Monitors the JMS create receiver operations in the com.ibm.mqjms.jar file. ■ Operation name: Create Subscriber Description: Monitors the JMS create subscriber operations in the com.ibm.mqjms.jar file. ■ Operation name: Create Browser Description: Monitors the JMS create browser operations in the com.ibm.mqjms.jar file. ■ Operation name: Create Consumer Description: Monitors the JMS create consumer operations in the com.ibm.mqjms.jar file. ■ Operation name: Get Topic Description: Monitors the JMS get topic operations in the com.ibm.mqjms.jar file. ■ Operation name: Async Receive Description: Monitors the JMS Async receive operations in the com.ibm.mqjms.jar file. ■ Operation name: Receive No Wait Description: Monitors the JMS receive no wait operations in the com.ibm.mqjms.jar file. ■ Operation name: Consumer Receive Description: Monitors the JMS consumer receive operations in the com.ibm.mqjms.jar file. JMS Operational Groups Chapter 8: Dashboards 211 Send Operational Group ■ Operation name: Create Sender Description: Monitors the JMS sender creation operations in the com.ibm.mqjms.jar file. ■ Operation name: Create Producer Description: Monitors the JMS producer creation operations in the com.ibm.mqjms.jar file. ■ Operation name: Create Destination Description: Monitors the JMS destination creation operations in the com.ibm.mqjms.jar file. ■ Operation name: Create Message Description: Monitors the JMS message creation operations in the com.ibm.mqjms.jar file. ■ Operation name: Process Message Description: Monitors the JMS message process operations in the com.ibm.mqjms.jar file. Connect Operational Group ■ Operation name: Create Queue Description: Monitors the JMS queue creation operations in the com.ibm.mqjms.jar file. ■ Operation name: Create Publisher Description: Monitors the JMS create publisher operations in the com.ibm.mqjms.jar file. ■ Operation name: Create Topic Description: Monitors the JMS Topic creation operations in the com.ibm.mqjms.jar file. ■ Operation name: Get Server Session Pool Description: Monitors the JMS session pool operations in the com.ibm.mqjms.jar file. JMS Operational Groups 212 for IBM WebSphere MQ Guide Disconnect Operational Group ■ Operation name: Unsubscribe Description: Monitors the JMS unsubscribe operations in the com.ibm.mqjms.jar file. ■ Operation name: Close Connect Description: Monitors the JMS connection close operations in the com.ibm.mqjms.jar file. Close Operational Group ■ Operation name: Session Close Description: Monitors the JMS session close operations in the com.ibm.mqjms.jar file. Commit Operational Group ■ Operation name: Session Commit Description: Monitors the JMS session commit operations in the com.ibm.mqjms.jar file. Rollback Operational Group ■ Operation name: Session Recover Description: Monitors the JMS session recover operations in the com.ibm.mqjms.jar file. ■ Operation name: Session Rollback Description: Monitors the JMS connection close operations in the com.ibm.mqjms.jar file. JMS Operational Groups Chapter 8: Dashboards 213 JMS Queue/Topic Operational Groups Send Operational Group ■ Operation name: Publish Description: Monitors the JMS Queue/Topic publish operations in the com.ibm.mqjms.jar file. ■ Operation name: Producer Send Description: Monitors the JMS Queue/Topic send operations in the com.ibm.mqjms.jar file. ■ Operation name: Process Message Description: Monitors the JMS agent thread process message operations in the com.ibm.mqjms.jar file. Receive Operational Group ■ Operation name: Get Topic Description: Monitors the JMS Topic get operations in the com.ibm.mqjms.jar file. ■ Operation name: Async Receive Description: Monitors the JMS Queue/Topic async receive operations in the com.ibm.mqjms.jar file. ■ Operation name: Receive No Wait Description: Monitors the JMS Queue/Topic receive no wait operations in the com.ibm.mqjms.jar file. ■ Operation name: Consumer Receive Description: Monitors the JMS Queue/Topic consumer receive operations in the com.ibm.mqjms.jar file. Connect Operational Group ■ Operation name: Get Server Session Pool Description: Monitors the JMS session pool get operations in the com.ibm.mqjms.jar file. JMS Operational Groups 214 for IBM WebSphere MQ Guide Disconnect Operational Group ■ Operation name: Close Connection Description: Monitors the JMS Queue/Topic connection close operations in the com.ibm.mqjms.jar file. Chapter 8: Dashboards 215 Appendix G: Performance and Sizing This appendix contains instructions, best practices, tips for optimizing the sizing and performance of your CA APM for IBM WebSphere 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 section contains the following topics: MQMonitor Agent Background (see page 215) WebSphere MQ Sizing (see page 215) WebSphere MB Sizing (see page 220) MQMonitor Agent Background The following factors can affect the performance and overhead of MQMonitor agent: ■ The number of Queue Managers that are 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 that are 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. ■ The Java Heap size of the MQMonitor agent. ■ %CPU use of the MQMonitor agent. ■ State of the Transaction Tracer (whether switched on or switched off). ■ Hardware configuration of the machines involved. WebSphere MQ Sizing To perform sizing on WebSphere MQ, perform sizing on the Enterprise Manager and the MQMonitor agent. WebSphere MQ Sizing 216 for IBM WebSphere MQ Guide Sizing Your Enterprise Manager The number of metrics contributed by the CA APM for IBM WebSphere MQ agent determines the sizing consideration of your Enterprise Manager. 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 Enterprise Manager, 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. Formulas calculate the Maximum Metric Count for distributed (see page 216) systems at the full, recommended, and minimum monitoring levels. 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 Q is the number of Queues for a Queue Manager. C is the number of Channels for a Queue Manager. Sizing Your MQMonitor Agent Use settings and capacity limits to set up, maintain, and configure CA APM for IBM WebSphere MQ environment for monitoring WebSphere MQ. The monitoring level that is defined at the MQMonitor agent determines the number of metrics that are reported to the Enterprise Manager. Note: This information is only a guideline for the sizing of your configuration. The sizing information can vary depending on the hardware configuration of your Enterprise Manager, the MQMonitor agent, and the WebSphere MQ computers. Sample MQMonitor Agent Sizing Table The MQMonitor agent sizing table is as follows: WebSphere MQ Sizing Chapter 8: Dashboards 217 Configuration: Single Queue Manager 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 127700 600, 2 256 to 512 6000 132100 Recommended 300, 2 256 to 512 4200 143000 600, 2 256 to 512 4500 153000 Full 300, 2 256 to 512 1700 133000 600, 2 256 to 512 1800 137000 Configuration: Multiple Queue Managers with Multiple Queues 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 121600 Minimum 600, 2 256 to 512 Queue Managers: 5 Queues per Queue Manager: 1200 132600 Recommended 300, 2 256 to 512 Queue Managers: 5 Queues per Queue Manager: 800 129000 Recommended 600, 2 256 to 512 Queue Managers: 5 Queues per Queue Manager: 800 129000 Full 300, 2 256 to 512 Queue Managers: 5 Queues per Queue Manager: 300 121600 Full 600, 2 256 to 512 Queue Managers: 5 Queues per Queue Manager: 300 115500 WebSphere MQ Sizing 218 for IBM WebSphere MQ Guide Environment Details Enterprise Manager: ■ System Requirement: Operating system Details: Microsoft Windows Server 2003 Enterprise Edition ■ System Requirement: System Model Details: Dell Inc., PowerEdge 6950 ■ System Requirement: Processor Details: Dual Core AMD Opteron™ Processor 8220,MMX,3D Now(8CPUs), ~2.8HZ ■ System Requirement: Memory Details: 16 GB ■ System Requirement: Total Free Space Details: 210 GB MQMonitor agent: ■ System Requirement: Operating system Details: Microsoft Windows Server 2003 Enterprise Edition ■ System Requirement: System Model Details: Dell Inc., PowerEdge GX620 ■ System Requirement: Processor Details: Intel Pentium® 4 CPU 3.00 GHz, ~3.0 GHz WebSphere MQ Sizing Chapter 8: Dashboards 219 ■ System Requirement: Memory Details: 2 GB ■ System Requirement: Total Free Space Details: 17 GB 4-512 MB WebSphere MQ computer: ■ System Requirement: Operating system Details: Microsoft Windows Server 2003 Enterprise Edition ■ System Requirement: System Model Details: Dell Inc., PowerEdge 745 ■ System Requirement: Processor Details: Intel Pentium® D CPU 3.00 GHz, ~3.0 GHz ■ System Requirement: Memory Details: 2 GB ■ System Requirement: Total Free Space Details: 16 GB With this WebSphere MQ configuration and the number of metrics that are generated by the MQMonitor agent, the Enterprise Manager processing cycle increases. The overload on the MQMonitor agent is, however, minimal, verify that you size your Enterprise Manager appropriately for sizing CA APM for IBM WebSphere MQ objects. Note: For information about sizing your Enterprise Manager appropriately, see the CA APM Sizing and Performance Guide. 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 220 for IBM WebSphere MQ Guide WebSphere MB Sizing To perform sizing on WebSphere MB, perform sizing on the Enterprise Manager and the MQMonitor agent for WebSphere MB. The number of metrics contributed by the Enterprise Manager agent determines the sizing consideration of your Enterprise Manager. 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 Enterprise Manager, 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 the metric count of your Enterprise Manager. 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 CA APM Sizing and Performance Guide to size your Enterprise Manager. WebSphere MB Sizing Chapter 8: Dashboards 221 Sizing Your MQMonitor Agent for WebSphere MB Use settings and capacity limits to set up, maintain, and configure your Enterprise Manager environment for monitoring WebSphere MB. Note: This information is only a guideline for the sizing of your configuration. The sizing information can vary depending on the hardware configuration of your Enterprise Manager, 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 Monitoring Level Number of execution groups per broker Total number of message flows Number of nodes per message flow Number of metrics reported Minimum 15 90 51 5800 Recommended 15 90 51 6900 Full 15 90 51 9400 Monitoring Level Number of execution groups per broker Total number of message flows Number of nodes per message flow Number of metrics reported Minimum 5 30 51 1800 Recommended 5 30 51 2300 Full 5 30 51 2900 WebSphere MB Sizing 222 for IBM WebSphere MQ Guide Configuration: Multiple Brokers The following table shows the multiple brokers (total number of brokers that are used is three), multiple execution groups, and multiple message flows in each broker: 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 Environment Details Enterprise Manager ■ System Requirement: Operating system Details: Microsoft Windows Server 2003 Enterprise Edition ■ System Requirement: System Model Details: Dell Inc., PowerEdge 6950 ■ System Requirement: Processor Details: Dual Core AMD Opteron™ Processor 8220, MMX, 3D Now(8CPUs), ~2.8 HZ ■ System Requirement: Memory Details: 16 GB ■ System Requirement: Total Free Space Details: 210 GB WebSphere MB Sizing Chapter 8: Dashboards 223 MQMonitor agent: ■ System Requirement: Operating system Details: Microsoft Windows Server 2003 Enterprise Edition ■ System Requirement: System Model Details: Dell Inc., Optiplex GX620 ■ System Requirement: Processor Details: Intel Pentium® 4 CPU 3.00 GHz, ~3.0 GHz ■ System Requirement: Memory Details: 2 GB ■ System Requirement: Total Free Space Details: 17 GB 4-512 MB WebSphere MB computer: ■ System Requirement: Operating system Details: Microsoft Windows Server 2003 Enterprise Edition ■ System Requirement: System Model Details: Dell Inc., Optiplex 745 WebSphere MB Sizing 224 for IBM WebSphere MQ Guide ■ System Requirement: Processor Details: Intel Pentium® D CPU 3.00 GHz, ~3.0 GHz ■ System Requirement: Memory Details: 2 GB ■ System Requirement: Total Free Space Details: 16 GB With this WebSphere MB configuration, the overload on the MQMonitor computer is minimal (only 2 percent) and the number of metrics reported to Enterprise Manager is comparatively lesser than the number of metrics that are reported when you monitor large WebSphere MQ configurations. So, depending on your WebSphere MB computer configuration, the MQMonitor agent can be utilized better. 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. Chapter 8: Dashboards 225 Appendix H: Frequently Asked Questions This appendix includes frequently asked questions about installation, metrics, transaction tracing, alerts, and dashboards in CA APM for IBM WebSphere MQ. This section contains the following topics: Alerts and Dashboards (see page 225) Unexpected Increase in Queue Depth (see page 226) Installation (see page 227) Metrics (see page 228) Queues (see page 229) Transaction Tracing (see page 230) Alerts and Dashboards Symptom: 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 does the color not appear? Solution: Connection pool alerts are applicable only for the WebSphere Application Server. When your Java application server is WebSphere and you have enabled PMI metrics reporting, you see this alert reporting data from the WebSphere PMI connection pool data. Symptom: How do I triage the WebSphere MQ infrastructure problems? Solution: Follow these steps: 1. Log in to the Workstation. 2. Open the WebSphere MQ Client And Server - Overview dashboard. 3. Observe the traffic lights to determine the health of your MQ Client connections, MQ Client operations, and MQ Server. 4. Double-click the traffic light that reports a warning and go to the details page. 5. On the Details page, view the MQ connections, MQ operations, and MQ Server information, to determine and analyze the problem in your MQ infrastructure. Unexpected Increase in Queue Depth 226 for IBM WebSphere MQ Guide Unexpected Increase in Queue Depth Symptom: The queue is increasing in depth. What should I do? Solution: Frequently, the first sign of a problem with a queue is steadily increasing queue depth. Abnormal increases in queue depths can be common during scheduled batch processes, but unexpected increases are cause for investigation. 1. Verify that the application can access the queues. 2. Review the Connection metrics. See if there are any exceptions raised when the application attempts to connect to the queue. 3. Review whether the application is able to read and deliver messages to the queues. a. The message depth can indicate that the messages are being put on the queue. However, the messages can still be unavailable by the application when they are uncommitted, so review metrics on commits/backouts. b. Review gets/puts for any abnormalities. c. Review queue residency times (Avg/Max) for abnormalities. 4. Review performance metrics relating to message processing to/through the queues. 5. Review the message size (Avg/Max) for any abnormalities. 6. Review the status of the dead letter queues. Numerous messages in the dead letter queue can adversely affect application performance. 7. Check the state of the channel—whether it is running, stopped, in doubt, retry, or any other state. 8. Check whether the channel is moving messages fast enough. a. Investigate throughput by comparing: ■ Buffers Sent compared to Buffers Received. ■ Bytes Sent compared to Bytes Received, or Messages Sent compared to 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 try to move the messages, a few times. Such messages do not appear in a Dead Letter Queue immediately. Installation Chapter 8: Dashboards 227 Installation Symptom: On UNIX or Linux, do I install CA APM for IBM WebSphere MQ using the "root" account? Solution: You do not need the root account to install CA APM for IBM WebSphere MQ on UNIX or Linux platforms. Review the security settings for CMP, JMS, PCF connections. Symptom: How can I know the version of the connector JAR file that my application uses? Solution: 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. Symptom: When Java 2 security is enabled on my application server and I deploy CA APM for IBM WebSphere MQ, I see security exception being reported in the application server log. What do I do? Solution: Verify that you provide adequate permission on the application server to prevent any security exceptions. You can configure the extension for MQ to enable Java 2 security. For more information, see the section that describes how to configure the application server when Java 2 Security is enabled. Metrics 228 for IBM WebSphere MQ Guide Metrics Symptom: At what intervals are the message broker metrics updated? Solution: 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. Symptom: How do I interpret Enqueue Count and Dequeue Count metrics? How is this related to the Queue Depth metric? Solution: The Enqueue Depth metric gives the number of messages that are 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] Queues Chapter 8: Dashboards 229 Symptom: What is the difference between Message metrics and Current Messages metrics for Channels? Solution: 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 Symptom: CA APM for IBM WebSphere MQ provides the "includeonly" regular expression for monitoring queues. How can I exclude queues from monitoring? Solution: 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 230 for IBM WebSphere MQ Guide Transaction Tracing Symptom: I am using the cross-process transaction trace feature. However, I do not see MQ traces. Why is this so? Solution: 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 you still do not see MQ Trace data, then verify that you restart all the active channels of the monitored Queue Managers. If the problem persists, check the log files and CA Introscope® version. Symptom: If my business transaction passes through any WebSphere MQ 5.3 Queue Managers, can I view the transaction traces from WebSphere MQ version 5.3 Queue Managers? Solution: No, you cannot view transaction traces from WebSphere MQ 5.3 Queue Managers. Cross-process transaction tracing is supported for WebSphere MQ 6.x and 7.0 only. Symptom: After setting the Activity Reporting property to "Queue," why should I restart the active channels of the monitored Queue Managers or the Queue Managers? Solution: Restarting the Queue Manager also restarts the MCAs. This action ensures that the trace data generated by WebSphere MQ goes to SYSTEM.ADMIN.ACTIVITY.QUEUE. Symptom: Why is the Average Response Time of the Queue Put operation under the WebSphereMQ node greater than that of the Backend node? Solution: The time difference is due to the additional processing logic (involving the tracers) for the Queue Put operation that is performed under the WebphereMQ node. When the 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. Transaction Tracing Chapter 8: Dashboards 231 Symptom: 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 behavior happen; how does this affect transaction tracing? Solution: On z/OS, a Queue Manager on startup refers to the configuration setup in the start-up job. If the configuration has the Activity Recording set to "Message," such as the following: 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 setting, transaction tracing does not occur for that Queue Manager. Traces for remote queues do not appear for that Queue Manager. Symptom: I see lots of Backends data in the transaction trace viewer. I am not interested in this information. How can I disable the Backends information? Solution: To disable the Backends data from appearing in the transaction trace viewer and the Investigator tree: 1. Open the webspheremq.pbd file in the /wily directory. 2. Comment all the directives containing Backends|WebSphereMQ on <hostname>. Chapter 8: Dashboards 233 Appendix I: Troubleshooting This appendix provides solutions for troubleshooting issues that you may encounter in CA APM for IBM WebSphere MQ. This section contains the following topics: Errors and Troubleshooting Steps (see page 233) Errors and Troubleshooting Steps The following list describes errors, the probable causes of the errors, and the troubleshooting steps: [ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.TracerDriverThread] MQMonitor: For configuration instance <QueueManager name>@localhost and the drivers(manager, manager) an error occurred in sending a query to MQ. The target MQ (localhost:19100) is down. Reason code 2035 MQRC_NOT_AUTHORIZED Reason: The user running the MQMonitor agent does not have adequate permissions to run the MQMonitor agent and connect to the Queue Manager. Action: 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 a 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 PCF APIs, and hence becomes part of the mqm group. Errors and Troubleshooting Steps 234 for IBM WebSphere MQ Guide [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 occurred in sending query to MQ. The target MQ (localhost:3414) may be down. Reason code 2397 MQRC_JSSE_ERROR Reason: 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. Action: 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 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. [ERROR] TraceManager.startUp ClassNotFoundException: Activity report parsing classes are not available. Ensure to have PCF JAR file from latest MS0B support pack. Reason: Incorrect version of PCF JAR file was used. Action: Verify 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. Errors and Troubleshooting Steps Chapter 8: Dashboards 235 [ERROR]sun.io.MalformedInputException at sun.io.ByteToCharUTF8.convert(ByteToCharUTF8.java(Compiled Code)) Reason: Locale-specific environment variable contains suffix ".UTF-8" Action: 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.MBTreeConfigMa in] User <userName> is not authorized to connect to queue manager <ConfigMgrQmgr> (MQ reason code 2035 while trying to connect) Reason: The MQMonitor agent user is not authorized to connect to the Configuration Manager’s Queue Manager. Action: 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 and Troubleshooting Steps 236 for IBM WebSphere MQ Guide [DEBUG] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMa in] 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.MBTreeConfigMa in] Configuration Manager is not initialized. Reason: Either the Configuration Manager is not available or the user 'hostname\username' does not have authority to view the object. (UUID='', required attribute='name'). Action: 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} Reason: JMS Broker Queue Manager does not have the prerequisite queues for Pub/Sub. Action: 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 and Troubleshooting Steps Chapter 8: Dashboards 237 [ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeMsgflow Statistics] MQJMS2013: invalid security authentication supplied for MQQueueManager. Reason: JMS Broker Queue manager does not have suitable user permission. Action: Perform the following steps: 1. Stop the MQMonitor agent and modify the privileges of Queue Manager of JMS Broker using the following commands: 2. Apply the allmqi permission on Queue Manager as follows: setmqaut -m <JMSQMName> -t qmgr -p <userName@DomainName> +allmqi 3. 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 4. 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 the domain name with the 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.MBTreeConfigMa in] Configuration Manager is not initialized. [FATAL] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMa in] Start the Configuration Manager and run WebSphere MB agent again. Reason: Configuration Manager is not available. Action: Stop the MQMonitor agent and turn on Configuration Manager using following command: mqsistart <ConfigurationManagerName> Errors and Troubleshooting Steps 238 for IBM WebSphere MQ Guide [INFO] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeMsgflow Statistics] 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.ExecutionGroupT racer] Statistics for all Execution groups are missing. WebSphere MB agent probably lost connection. [INFO] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.ExecutionGroupT racer] WebSphere MB agent restart will be performed now. Reason: 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. Action: 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 and Troubleshooting Steps Chapter 8: Dashboards 239 [ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.ExecutionGroupT racer] Statistics for all Execution groups are missing. WebSphere MB agent probably lost connection. [INFO] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.ExecutionGroupT racer] WebSphere MB agent restart will be performed now. Reason: Message Flow statistics and Broker statistics are not enabled for the execution groups on WebSphere MB. Action: 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 about 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 Reason: The metrics reported by the MQMonitor agent are clamped by the Enterprise Manager as it is sending more than 50000 metrics. Because of this, no new metrics will be reported by the Enterprise Manager. Action: 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.enterprisemanager.agent.metrics.limit=50000 Restart the Enterprise Manager. ■ Lower the monitoring level of the WebSphere MQ objects such as Queue Managers, Queues, Channels. 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 and Troubleshooting Steps 240 for IBM WebSphere MQ Guide [VERBOSE] [IntroscopeAgent.Agent] java.lang.ClassNotFoundException: com.wily.introscope.agent.extensions.trace.MapEnablingTracer Reason: webspheremq-extra.pbd is enabled or uncommented in webspheremq.pbl but SOA Performance Manager is not installed. Action: Do one of the following: ■ If you want to view MQ nodes in SOA Dependency Map, install SOA Performance Manager. For more information about viewing MQ nodes in SOA Dependency Map, see the sections on configuring applications for the SOA dependency map, and Websphere MQ in the SOA dependency map. ■ If you do not want to view MQ nodes in SOA Dependency Map, comment webspheremq-extra.pbd in webspheremq.pbl to disable the PBD and restart Enterprise Manager for the change to take effect. [ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.TracerDriverThread] MQMonitor: An error occurred sending or processing an MQ PCF command. java.io.UnsupportedEncodingException: IBM-932 (CCSID) Reason: JRE version being used does not support IBM-932 encoding. Action: Ensure that you use a JRE version that supports IBM-932 encoding. Errors and Troubleshooting Steps Chapter 8: Dashboards 241 [ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.TracerDriverThread] MQMonitor: For configuration instance QM1 and the drivers(namelist,cluster) an error occurred in sending query to MQ. The target MQ (10.131.172.101:8002) may be down. Reason code 2059 MQRC_Q_MGR_NOT_AVAILABLE Reason: You have provided incorrect or improper values for host, port, channelname, and CCSID for queue manager instances in MQMonitor.properties. Action: Provide correct or proper values for host, port, channelname, and CCSID for the queue manager instances in MQMonitor.properties. If you are using non-english character set, provide appropriate CCSID. Access <IBM WebSphereMQ Install Directory>/conv/table/ccsid.tbl and try out all the CCSID‘s listed in it under the appropriate language section. For example: If IBM WebSphere MQ is in Japanese language, go to the Japanese section in the ccsid.tbl file and try all CCSID's listed in this section. Chapter 8: Dashboards 243 Appendix J: Support for IPv6 Environment This appendix describes how you can configure the MQMonitor agent and the MQ Java Connectors to connect to the Enterprise Manager in an IPv6 environment. The appendix also describes how you can add support for WebSphere MQ and WebSphere MB in the IPv6 environment. This section contains the following topics: Connect to the Enterprise Manager in an IPv6 Environment (see page 243) Support for WebSphere MQ and WebSphere MB in an IPv6 Environment (see page 244) Connect to the Enterprise Manager in an IPv6 Environment You can connect to the Enterprise Manager in an IPv6 environment by configuring the MQMonitor agent and the MQ Java Connectors. Configure the MQMonitor Agent In a pure IPv6 Java environment, configure the MQMonitor agent with the java.net.preferIPv6Addresses property to display IPv6 addresses for the MQMonitor agent in the Investigator tree. Follow these steps: 1. Set the property -Djava.net.preferIPv6Addresses=true in the MQMonitor startup script: ■ On Windows, update the startMQMonitor.bat file as follows: %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 as for Windows. The Investigator displays the full IPv6 IP address under *SuperDomain* > <hostname> > WebSphere MQ and Message Broker > WebSphere MQ and Message Broker Agent > Host:IP Address. Note: If the IPv6 address is not mentioned in the host file of the computer on which the MQMonitor agent is running, it displays 0:0:0:0:0:0:0:1. Support for WebSphere MQ and WebSphere MB in an IPv6 Environment 244 for IBM WebSphere MQ Guide MQ Java Connectors To configure the MQ Java Connector, see the section on how to configure IPv6 in the CA APM Java Agent Implementation Guide. 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 computer, 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 Index 245 Index . .ssl • 128 < <brokername>.broker.statistics • 120 <brokername>.messageflow.statistics • 119, 127 <Queue Manager>@<Host>.channel.event.queue • 104 <Queue Manager>@<Host>.channel.filter.includeonly.rege x • 113 <Queue Manager>@<Host>.channel.ssl.cipherspec • 102 <Queue Manager>@<Host>.channelname • 100 <Queue Manager>@<Host>.character.set • 101 <Queue Manager>@<Host>.delaytime • 101 <Queue Manager>@<Host>.event.destructive.get • 103 <Queue Manager>@<Host>.filter.exclude.static • 112 <Queue Manager>@<Host>.host • 100 <Queue Manager>@<Host>.log.filter.includeonly.regex • 113 <Queue Manager>@<Host>.pagesets.filter.includeonly.reg ex • 113 <Queue Manager>@<Host>.performance.event.queue • 104 <Queue Manager>@<Host>.port • 100 <Queue Manager>@<Host>.qmgr.event.queue • 103 <Queue Manager>@<Host>.queue.filter.exclude.dynamic • 112 <Queue Manager>@<Host>.queue.filter.exclude.system • 112 <Queue Manager>@<Host>.queue.filter.includeonly.regex • 113 <Queue Manager>@<Host>.report.static.freq • 101 <Queue Manager>@<Host>.ssl • 101 A a.host • 123 a.port • 124 a.queue.manager • 124 About the Extension for WebSphere MQ • 15 Additional Information • 45 Additional JAR Files • 18 Advanced Settings Section • 106, 120, 127 Aggregate and Individual Metrics • 203 Aggregate Clusters Status Metrics • 133 Aggregate Metrics Across All Message Flows • 193 Aggregated Metrics • 81 Aggregated Metrics for Multi-Instance Cluster Queues • 147 Aggregated Queue Manager Metrics • 134 Aggregated Status Metric • 140, 182 Aggregated Status Metrics Across All Hosts • 153 Aggregated Status Metrics for All Queue Managers on a Host • 154 Aggregated Status Metrics for Each Queue Manager • 155 Alerts and Dashboards • 225 Auto-discover Queue Managers • 60 B Backend Metrics • 199 Broker (JMS) Connection Section • 117 Broker Properties and Aggregate Totals • 187 Broker Queue Manager Metrics • 198 Broker Statistics • 189 broker.connection.ssl.cipherspec • 128 C CA Technologies Product References • 3 Channel Initiator Metrics • 178 Channel Metrics • 155 Client and Neighbor Statistics • 190 Close Operational Group • 208, 212 Cluster Queue Metrics • 135 Cluster-Receiver Channel and Cluster-Sender Channel Metrics • 140 CMP Connection Section • 115, 123 cmp.connection.ssl.cipherspec • 121 246 for IBM WebSphere MQ Guide cmp.ssl • 121 Commit Operational Group • 207, 212 ConfigManagerProxy.jar • 18 Configuration • 27 Multiple Brokers • 222 Multiple Queue Managers with Multiple Queues • 217 Single Broker Multiple Execution Groups and Multiple Message Flows • 221 Single Queue Manager with Multiple Queues • 217 Configuration Manager Aggregate Totals • 186 Configuration Manager Queue Manager Metrics • 198 Configuration Properties • 135, 140, 143, 147, 155, 180 Configuration Properties Metrics • 159, 170, 182 Configuration Settings • 178 configuration.manager.host • 115 configuration.manager.port • 116 configuration.manager.queue.manager • 115 Configure Application Server When Java 2 Security is Enabled • 45 Configure CA APM ErrorDetector • 54 Configure handshake for Cross Process Transaction Tracing • 43 Configure JCA Connection Pool • 47 Configure MQ applications for SOA Dependency Map • 58 Configure MQ Java Connector agent • 27 Configure SSL • 48 Configure SYSTEM.ADMIN.ACTIVITY.QUEUE • 40 Configure the Client • 50 Configure the Enterprise Manager for Trace • 69 Configure the MBMonitor properties File • 53 Configure the MBMonitor.properties File for WebSphere MB 6.x • 31 Configure the MBMonitor_7.properties File for WebSphere MB 7.0 or 8.0 • 31 Configure the MQMonitor Agent • 243 Configure the MQMonitor Agent for Third-Party Libraries • 28 Configure the MQMonitor Agent Properties • 30 Configure the MQMonitor to monitor WebSphere Message Brokers • 30 Configure the MQMonitor to monitor WebSphere MQ Queue Managers • 28 Configure the MQMonitor.properties File • 52 Configure the Server • 49 Configure Tracing Automatically • 37 Configure Tracing Manually • 39 Configure WebSphere MQ for Trace • 37 Configure WebSphere MQ to Publish Events • 44 Connect Operational Group • 206, 211, 213 Connect to the Enterprise Manager in an IPv6 Environment • 243 Console Dashboards • 75 Contact CA Technologies • 5 Create JMS queues • 33 Cross-Process Transaction Tracing • 65 D Dashboards • 85 Data Collection Rules • 192 Delay Times Section • 118, 126 Disconnect Operational Group • 206, 212, 214 Display of Shared and Nonshared Queue Managers • 198 Distributed Systems • 216 E Enable or Disable MQ Traces • 71 Environment Details • 218, 222 ErrorDetector Metrics • 203 Errors • 195 Errors and Troubleshooting Steps • 233 Execution Group Properties and Aggregate Metrics • 188 Execution Group Section • 118, 125 Execution Groups Metrics • 187 Extension for WebSphere MQ Components • 16 F Filter Queues for Transaction Trace • 72 Filters Section • 111 Find MQ Java Connector Metrics • 80, 199 Frequently Asked Questions • 225 G General Metric Characteristics • 131 Generate Personal Certificates • 54 Get Operational Group • 208, 209 H handshake.mqagent.id • 94, 108 handshake.qm.channel.ssl.cipherspec • 95, 110 Index 247 handshake.qm.channelname • 94, 109 handshake.qm.character.set • 94, 109 handshake.qm.host • 94, 109 handshake.qm.port • 94, 109 handshake.qm.ssl • 95, 109 handshake.queue • 95, 110 Host Information • 77 How to Set Up Client-Server Communication Over SSL • 49 I IBM WebSphere MQ Monitoring • 15 Identifying a Slow Transaction • 69 Install Enterprise Manager components on a new Enterprise Manager • 21 Install Enterprise Manager components on an Existing Enterprise Manager • 22 Install MQ Java Connector agent as a new installation • 23 Install MQ Java Connector agent on an existing agent • 24 Install MQMonitor agent • 24 Install the MQMonitor Agent as a Windows Service • 56 Installation • 21, 227 Installation and Configuration in an EM Clustered Environment • 63 Instance Counts Metrics • 200 Interpret the Dashboard Traffic Lights • 87 Intervals • 192 J j2ee.jar • 18 JCA Node Metrics • 200 JCA Operational Groups • 205 JCA Queue Manager Operations • 206 JCA Queue Operational Groups • 209 JCA/JMS Operational Groups • 205 JMS Operational Groups • 209 JMS Queue Manager Operational Groups • 210 JMS Queue/Topic Operational Groups • 213 jms.broker.host • 117 jms.broker.port • 117 jms.broker.queue.manager • 117 jms.connection.ssl.cipherspec • 121, 128 jms.ssl • 121 K keystore.password • 96, 102, 122, 129 keystore.path • 95, 102, 122, 129 L Last Check Metrics • 169 Log Copy Records • 181 Log Metrics • 179 M Management Modules • 85 MBMonitor.properties File • 115 MBMonitor_7.properties File • 123 Message Broker Aggregated Metrics • 83 Message Broker Alerts • 91 Message Broker Metrics • 79, 186 Message Flow Invocations • 195 Message Flow Statistics • 192 Message Statistics • 196 Metric Display Sets • 132 Metrics • 228 Metrics Reference • 131 Monitoring Level Settings Section • 119, 127 MQ Auto Discovery Related Properties Section • 110 MQ Connection Section • 116, 124 MQ Dashboards in the Console • 75 MQ Events Section • 102 MQ Java Connectors • 244 MQ Trace Related Properties Section • 106 mq.autodiscovery.enabled • 96, 111 mq.autodiscovery.properties.update • 111 mq.autodiscovery.queue • 97, 111 mq.broker.monitor.list • 123 mq.monitor.agent.id • 111 mq.monitor.list • 100 MQAgent.properties File • 93 MQDiscovery Utility Tool • 61 MQMonitor Agent and MBBroker Metrics • 76 MQMonitor Agent Background • 215 mqmonitor.mqagent.id.list • 93 MQMonitor.properties File • 99 mqtracing.exclude.queues.regex • 96 N Node Statistics • 196 Node Statistics Section • 118, 126 248 for IBM WebSphere MQ Guide O Obtain Third-Party Libraries • 17 Open Operational Group • 208 Operational Group Metrics • 202 Operational Groups • 199, 202 Other Message Broker Dashboards • 90 P PCF JAR File • 17 Percent Queue Depth Variation • 152 Performance • 197 Performance and Sizing • 215 Preparing to install • 17 Properties and Aggregate Metrics for Each Message Flow • 193 Put Operational Group • 207, 209 Q Queue Aggregated Metrics • 82 Queue Manager Cluster and Queue Manager Metrics • 81 Queue Manager Cluster Metrics • 78, 132 Queue Manager Metrics • 78, 153 Queue Manager Status Metrics • 184 Queue Metrics • 147, 170 Queues • 229 R Receive Operational Group • 210, 213 recommended.metrics.broker.statistics • 120 recommended.metrics.messageflow.statistics • 120, 128 Rollback Operational Group • 209, 212 Run mqPwdEncryptor.bat file • 51 Run the MQMonitor Agent • 30 S Sample MQMonitor Agent Sizing Table • 216 Sample MQMonitor Agent Sizing Table for WebSphere MB • 221 Send Operational Group • 211, 213 Set Auto Discovery Properties • 60 Set Security Requirements for MB 6.x • 35 Set Security Requirements to Monitor a Remote WebSphere MB 7.0 or 8.0 • 36 Set Security Requirements to Monitor an MQ object • 34 Set the Activity Recording Property • 39 Set the Handshake Queue • 41 Set the MCA User ID • 41 Set Up Keystore • 51 Set Up Truststore • 50 Share the wily Folder Across MQ Java Connector agents • 46 Show Investigator Dashboards and Data Displays • 80 Sizing Your Enterprise Manager • 216 Sizing Your MQMonitor Agent • 216 Sizing Your MQMonitor Agent for WebSphere MB • 221 Special Settings Section • 105 Specific MQ Data Section • 99 SSL Configuration Section • 121, 128 Statistics Generated by Publication Node • 191 Statistics Section • 116, 125 Status • 149 Status Metrics • 137, 141, 145, 157, 175, 178, 181, 184 Support for IPv6 Environment • 243 Support for WebSphere MQ and WebSphere MB in an IPv6 Environment • 244 T Top Level Queue Manager Aggregated Metrics • 153 Top Level Repository Trees • 133 Trace Data Properties • 72 trace.dlq.activity.enabled • 107 trace.dlq.flag.time • 108 trace.hold.maxduration • 110 trace.polling.enabled • 107 trace.polling.interval • 108 trace.polling.retry.count • 108 Transaction Trace with Holding Duration Set to a Value Other than 0ms • 70 Transaction Trace with Trace Holding Duration Set to 0ms • 70 Transaction Tracing • 65, 230 Transmission Queue Metrics • 169 Troubleshooting • 233 truststore.path • 95, 102, 121, 128 Turn On Queue Monitoring • 45 U Understanding the Metrics Tree • 76 Unexpected Increase in Queue Depth • 226 Index 249 Upgrade CA APM for IBM WebSphere MQ • 57 Usage Metrics • 182 V Verify Server Connection and Access • 17 Verify System and Version Requirements • 17 Verify the Transaction Trace Configuration • 66 View Dashboards and Data • 76 View Data • 75 View the Auto Discovered Queue Managers in the What's Interesting section • 63 Viewing Data Using the WebSphere MQ Extension • 75 W WebSphere MB Sizing • 220 WebSphere Message Broker Dashboards • 88 WebSphere Message Broker Overview Dashboard • 89 WebSphere MQ - Client Connections Dashboard • 88 WebSphere MQ - Client Operations Dashboard • 88 WebSphere MQ - Server Dashboard • 88 WebSphere MQ Client and Server Dashboards • 85 WebSphere MQ Client and Server Overview - Details Dashboard • 86 WebSphere MQ Client and Server Overview Dashboard • 86 WebSphere MQ Sizing • 215 WebSphereMQ Cross Process Transaction Trace Health & Availability Dashboard • 66 WebSphereMQ Node Metrics • 201 WebSphereMQ Sample Report Templates • 84 Wide Statistics • 191 Workload Balance Metrics • 147