APM - 9.5 - APM For IBM WebSphere MQ Guide

for IBM WebSphere MQ Guide
Release 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 techpubs@ca.com.
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


<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
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
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


Execution Group Section .......................................................................................................................................... 125
Node Statistics Section ............................................................................................................................................. 126
Delay Times Section ................................................................................................................................................. 126
Monitoring Level Settings Section ............................................................................................................................ 127
<brokername>.messageflow.statistics.............................................................................................................. 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
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


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


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 ManagersThe 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 ClustersThe 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

This chapter contains the prerequisites that must be satisfied before you begin the
installation of the CA APM for IBM WebSphere MQ.
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.


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


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

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.
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


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


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.

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


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


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

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


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


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
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
dhbcore.jar
ConfigManagerProxy.jar
j2ee.jar
connector.jar
Configure the MQMonitor to monitor WebSphere Message Brokers


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 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.
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.


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.
MBMonitor_7.properties File (see page 123).


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


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


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


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


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.
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.


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 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)


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.


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.


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 channels 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 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


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 Whats Interesting column.


Chapter 5: Additional Information

You can perform additional tasks such as configuring SSL, upgrading CA APM for IBM
WebSphere MQ, and creating JMS queues.
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


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


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


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


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


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


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 certificateeither self-signed certificate using IKEYMAN tool or any
personal certificateand 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


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:
QM1@hostname.ssl=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:
QM1@hostname.channel.ssl.cipherspec= 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


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


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.
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.


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


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


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


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.
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.


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


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 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.


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


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 Manager1@hostname.host=Queue Manager1@hostname
Queue Manager1@hostname.port=3002
Queue Manager1@hostname.channelname=SYSTEM.AUTO.SVRCONN
Queue Manager2@hostname.channelname=SYSTEM.DEF.SVRCONN
Queue Manager1@hostname.character.set=819
Queue Manager2@hostname.character.set=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 Manager1@hostname.channelname=
Queue Manager2@hostname.channelname=
Queue Manager1@hostname.character.set=
Queue Manager2@hostname.character.set=
Installation and Configuration in an EM Clustered Environment


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 Whats Interesting column.
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)


5. Configure MQ applications for SOA Dependency Map (see page 58).
6. Configure WebSphere MQ for Trace. (see page 37)


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.
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


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


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


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


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


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


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


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


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.


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

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.
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:
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


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:


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.


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:
ChannelsLinks 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 InitiatorProvides 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.
PageSetsData 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.
LogsRecords 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 PropertiesData on how administrators have configured each
Queue Manager. Some properties have both a string and a numeric value.


Dead Letter QueueConfiguration Properties and Status data/metrics about the
dead letter queue, which is a repository for undeliverable messages.
Transmission QueueConfiguration 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 CheckInformation about the connection status of the Queue Manager.
QueuesConfiguration Properties and Status data/metrics for each of the queues
that is configured by the administrators on the Queue Manager.
StatusData 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 PropertiesIdentification and configuration information about this
message broker.
Component RunstateWhether the message broker is running or not running.
Number of Subcomponentsthe number of Execution Groups under this
broker.
Shared ObjectWhether the message broker is a shared object ("TRUE") or a
non-shared object ("FALSE").
UUIDUniversally Unique Identifier for the Broker.
Execution GroupsSets 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 StatisticsDivided into Client Statistics, Neighbor Statistics, and Wide
Statistics.
Message FlowsDivided into several subcategories.


Broker Queue Manager metricsDetailed 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.


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 = greensuccessful
1 = redunsuccessful


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 = greenNo channels are in doubt
1 = redAt least one channel is in
doubt.
Aggregated Page Set Status (z/OS
only)

Indicates the aggregated status of
the page sets.
0 = greenall page sets are running
1 = redone 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 = greenrunning
1 = redunknown
Maximum Queue Depth Reached Indicates whether the maximum
queue depth has been reached for
any of the queues under this node.
0 = greenmaximum not reached
1 = redmaximum reached

Queue Aggregated Metrics

Get Enabled Indicates whether the get operations
are allowed for the queues or not.
0 = greenget operations are
allowed (messages can be read) for
all queues under this node
1 = redget 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 = greenmaximum not reached
1 = redmaximum reached


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 = greenput operations are
allowed (messages can be put on a
queue) for all queues under this
node
1 = redput 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


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

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.
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:

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 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 ConnectionsIncludes blame metrics for Average Response Time, Errors
Per Interval, and Stall Count.
MQ ServerIncludes 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 OperationsIncludes blame metrics for Average Response Time, Errors
Per Interval, and Stall Count.
Get/Receive OperationsIncludes 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.


The graphs in the dashboard display the following blame metrics for the MQ Client
Connections, MQ Client Operations, and MQ Server components:
MQ Client ConnectionsIncludes 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 OperationsIncludes blame metrics for Errors Per Interval, Slowest
(Average Response Time), Stall Count, Responses Per Interval for Put/Send and
Get/Receive operations.
MQ ServerDisplays 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


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.
The WebSphere Message Broker dashboards show the performance of the Message
Broker and its Message Queue.


WebSphere Message Broker Overview Dashboard
The WebSphere Message Broker Overview dashboard has 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
GreenNo threshold has been reached.
YellowCaution threshold has been reached.
RedDanger threshold has been reached.
Component: Timeouts
Component: Backouts
Component: Messages Dropped


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
MQMonitor agent lost its connection with any one of the monitored queue
managers.
Component: Queue Managers Status
Any one of the monitored Queue Managers is not running.
Component: Queues Full
Any one of the monitored Queues is full (no more messages can be put on the
queue).
Component: Channels Indoubt
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


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
Alert: MQ Qmgrs Status
Type: Simple
Thresholds:
Danger Threshold: 0
Alert: MQ Queues Full Status
Type: Simple
Thresholds:
Danger Threshold: 0
Alert: MQ Channels Indoubt Status
Type: Simple
Thresholds:
Danger Threshold: 0
Alert: Messages Dropped Total
Type: Simple
Thresholds:
Danger Threshold: 1


Alert: Timeouts Total
Type: Simple
Thresholds:
Danger Threshold: 1
Alert: MQ Agent-MQ Connection Status
Type: Simple
Thresholds:
Danger Threshold: 0
Alert: MQ Overall Status
Type: Summary
Thresholds:
None.


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.
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



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


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.
Example: keystore.path=C:\\MQMonitor\\key\\keystore.jks
keystore.password


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


Specifies the queue that is used among all MQ agents for discovering Queue
Managers.
Default: CA_WILY_AUTODISCOVERY
Example: handshake.queue=CA_WILY_AUTODISCOVERY


Appendix B: MQMonitor.properties File

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)



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
Example: QM1@<hostname>.channelname=SYSTEM.AUTO.SVRCONN


<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


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.
keystore.path
Specifies the location of the keystore containing certificates for authentication of
the MQMonitor agent. If you require client authentication, set this property.
Example: keystore.path=C:\\MQMonitor\\key\\keyststore.jks
keystore.password
Specifies the keystore password.
Default: <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


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


<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


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


To see which metrics belong to each value set, see Queue Manager metrics (see
page 153).
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.


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.
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.
Default: true


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
Specifies the unique identification of the agent. This property is mandatory.
Limits: 1 to 999999999
Default: None
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
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


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
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


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
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.
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


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.
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.
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.
Default: true
Example: QM1@<hostname>.queue.filter.exclude.dynamic=true
Filters Section


<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.
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>
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>
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>


Appendix C: MBMonitor.properties File

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)
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


configuration.manager.port
Specifies the CMP Queue Manager port.
Default: null
Example: configuration.manager.port=2414

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.
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


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


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
Example: static.delaytime=1800
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


<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

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


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:
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:
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.


keystore.path
Specifies the keystore path of the SSL key repository that is used for both CMP and
escaped.
keystore.password
Specifies the keystore password of the SSL key repository that is used for both CMP
and JMS SSL connections.
Default: <password>


Appendix D: MBMonitor_7.properties File

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)
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



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

Use this section to monitor the Queue Manager for each broker.
Default: all
Example: mq.broker.list=BROKER1,BROKER2
Statistics Section


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.

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


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
Example: static.delaytime=1800


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
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.


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
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
escaped.


keystore.path
Specifies the keystore path of the SSL key repository that is used for both CMP and
escaped.
keystore.password
Specifies the keystore password of the SSL key repository that is used for both CMP
and JMS SSL connections.
Default: <password>


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.
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 valuea 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 Counta numeric value, expressed as the number of incidents over the last
interval.


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:
MMinimum
Contains the minimum metrics.
RRecommended
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.
FFull
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.
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.


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


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
Status metrics
Aggregated Queue Manager Metrics
For each Queue Manager beneath a host name, the Investigator displays the following
aggregated status metrics:

Aggregated
Channel Indoubt
Status
Mapped Value Indicates whether any of the channels on the Queue Managers are currently
0 = None of the channels are in doubt.
1 = At least one channel is in doubt.
Maximum Queue
Depth Reached
the Queues in this cluster.
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.



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:
Status metrics
Aggregated status for all cluster queues, as described in the following table:

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_INHIBITEDGet operations are inhibited.
0 = MQQA_GET_ALLOWEDGet 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_INHIBITEDPut operations are inhibited.
0 = MQQA_PUT_ALLOWEDPut 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
the cluster queues on this Queue Manager. One of:

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.


Level
Description
Cluster Queue
Type
Mapped
Value
M One of:
1 = MQCQT_LOCAL_Qlocal
2 = MQCQT_ALIAS_Qalias
3 = MQCQT_REMOTE_Qremote
4 = MQCQT_Q_MGR_ALIASQueue 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.
Max Message
Length
Number R Maximum message length.
Persistence Mapped
Value
F Default persistence of messages on the queue. One of:
1= MQPER_PERSISTENTThe message survives system failures
and Queue Manager restarts.
0= MQPER_NOT_PERSISTENTThe 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.
QMID String F Queue Manager name
Queue Depth
High Events
Mapped
Value
F Enables Queue Depth High events.
0 = MQEVR_DISABLEDEvent reporting disabled.
1 = MQEVR_ENABLEDEvent reporting enabled.


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:
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_LOCALLocal 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.

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.


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
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.
Day (sec)
Number M Running maximum oldest message age over the
last day.
Hour (sec)
Number
Dynamic
M Running maximum oldest message age over the
last hour.


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_MGRCollect monitoring data
according to the setting of the QueueMonitoring
Queue Manager attribute. This is the default value.
0 = MQMON_OFFOnline monitoring data
collection is turned off for this queue.
17 = MQMON_LOWIf 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_MEDIUMIf the value of the
is turned on, with a moderate rate of data
collection for this queue.
65 = MQMON_HIGHIf the value of the
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:



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:

Aggregated
Channel
Indoubt Status
Mapped Value Indicates whether any of the channels on the Queue Managers are currently
0 = none of the channels are in doubt.
1 = at least one channel is in doubt.
Aggregated
Channel
Instance Counts
Number
Dynamic
Aggregated count of all the channel instances on the Queue Manager.

The same set of Configuration properties can appear under the Cluster-Receiver
Channel node and the Cluster-Sender Channel node.

Level
Description
CLWL Channel
Priority
Number R Cluster workload channel priority.
CLWL Channel
Rank
Number R Cluster workload channel rank.


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_CLUSRCVRCluster receiver channel
9 = MQCHT_CLUSSDRCluster 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.

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.


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_STOPPEDMessage channel agent stopped.
3 = MQMCAS_RUNNINGMessage 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_INACTIVEChannel is not active.
1 = MQCHS_BINDINGChannel is negotiating with the partner.
2 = MQCHS_STARTINGChannel is waiting to become active.
3 = MQCHS_RUNNINGChannel is transferring or waiting for
messages.
4 = MQCHS_STOPPINGChannel is in process of stopping.
5 = MQCHS_RETRYINGChannel is reattempting to establish
connection.
6 = MQCHS_STOPPEDChannel is stopped.
7 = MQCHS_REQUESTINGRequester channel is requesting
connection
8 = MQCHS_PAUSEDChannel is paused.
13 = MQCHS_INITIALIZINGChannel 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_REQUESTEDUser stop request has
not been received.
1 = MQCHSR_STOP_REQUESTEDUser stop request has been
received.



The Configuration Properties node displays properties for the Queue Manager.

Level
Description
Auto CLUSSDR
Monitoring
Mapped Value F Setting for online monitoring for automatically defined
cluster-sender channels. One of:
-3 = MQMON_Q_MGRCollection of online monitoring
data is inherited from the setting of the Queue Manager's
ChannelMonitoring parameter.
0 = MQMON_OFFMonitoring for the channel is switched
off.
17 = MQMON_LOWSpecifies 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_MEDIUMSpecifies a moderate rate of data
collection with limited impact on system performance
unless ChannelMonitoring for the Queue Manager is
MQMON_NONE.
65 = MQMON_HIGHSpecifies 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_MGRCollection of statistics data is
inherited from the setting of the Queue Manager's
ChannelStatistics parameter.
0 = MQMON_OFFStatistics data collection for the channel
is switched off.
17 = MQMON_LOWSpecifies a low rate of data collection
with a minimal impact on system performance.
33 = MQMON_MEDIUMSpecifies a moderate rate of data
collection.
65 = MQMON_HIGHSpecifies a high rate of data
collection.
This metric is valid only on AIX, HP-UX, Linux, Solaris, and
Windows.


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_LOCALDo not use remote queues.
1 = MQCLWL_USEQ_ANYUse 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 = NormalA normal Queue Manager.
1 = RepositoryA 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
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.


Level
Description
Platform Mapped Value R Platform on which the Queue Manager resides. One of:
1 = MQPL_ZOSz/OS
3 = MQPL_AIXAIX (same value as MQPL_UNIX).
3= MQPL_UNIXUNIX systems.
4 = MQPL_OS400i5/OS.
12 = MQPL_VMSHP OpenVMS.
11 = MQPL_WINDOWS_NTWindows.
13 = MQPL_NSKCompaq NonStop Kernel.
QMID String F Unique identifier of the Queue Manager.
Queue Manager
Name
Repository Name
List
String F Name of the list of clusters for which the Queue Manager is
providing a repository service.

Status Metrics

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 UnknownChannel Initiator
stopped/unknown.
1 = MQSVC_STATUS_STARTINGChannel Initiator starting up.
2 = MQSVC_STATUS_RUNNINGChannel Initiator running.
3 = MQSVC_STATUS_STOPPINGChannel Initiator shutting
down.
4 = MQSVC_STATUS_RETRYINGChannel Initiator retrying.
Cluster Queue
Manager Suspend
Mapped
Value
Dynamic
M Indicates whether the Queue Manager is suspended. One of:
0 = Nonot suspended.
1 = Yessuspended.


Level
Description
Command Server
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_RUNNINGRunning.
0 = UnknownUnknown.
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.


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
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:

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:
Status

Level
Description
Cluster Name String F Name of the cluster.


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_Qlocal
2 = MQCQT_ALIAS_Qalias
3 = MQCQT_REMOTE_Qremote
4 = MQCQT_Q_MGR_ALIASQueue 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.
1 = MQQA_GET_INHIBITEDGet 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_PERSISTENTThe message survives system
failures and Queue Manager restarts.
0 = MQPER_NOT_PERSISTENTThe 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.
QMID String F Queue Manager name
Queue Depth High
Events
Mapped
Value
F Enables Queue Depth High events.


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:
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_LOCALLocal 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

Status
To see data for the Oldest Message Age and Queue Time metrics, enable Queue
Monitoring in WebSphere MQ.

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.
Dynamic
M Number of messages currently on the queue on this Queue
Manager.
Current Queue Depth
Percentage (% Queue
Full)
Number
Dynamic


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
last day.
Dequeue Count Per
Hour
last hour.
Dequeue Count Per
Minute
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
last day.
Enqueue Count Per
Hour
last hour.
Enqueue Count Per
Minute
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.
Dynamic
M The number of handles that are currently open for input for
the queue on this Queue Manager.


Level
Description
Dynamic
M The number of handles that are currently open for output
for the queue on this Queue Manager.
Queue Monitoring Mapped
Value
-3 = MQMON_Q_MGRCollect monitoring data according
to the setting of the QueueMonitoring Queue Manager
attribute. This is the default value.
0 = MQMON_OFFOnline monitoring data collection is
turned off for this queue.
17 = MQMON_LOWIf 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.
MQMON_NONE, online monitoring data collection is turned
on, with a moderate rate of data collection for this queue.
65 = MQMON_HIGHIf 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.
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.
Uncommitted
Messages
Number M Number of uncommitted messages.

More information:



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:
curreqdepthCurrent Queue Depth for a specific Queue Manager.
aveqdepthAverage 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 QM3with 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
((140 80) / 80) * 100 = 75
((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.


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
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:

Aggregated Agent-MQ
Connection Status
Mapped Value Indicates the aggregated connection status of CA APM for IBM
WebSphere MQ with all the Queue Managers.
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:
Maximum Queue Depth
Reached
Mapped Value Indicates whether the maximum queue depth has been
reached for any of the queues on this Queue Manager.
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:

Aggregated Agent-MQ
Connection Status
(z/OS only)
Aggregated Queue Manager
Status
Mapped Value Indicates the aggregated status of the Queue Managers. One
of:
Maximum Queue Depth
Reached
reached for any of the queues on the Queue Manager.
0 =no queue has reached the maximum queue depth
depth



Aggregated Status Metrics for Each Queue Manager
The Investigator displays the following aggregated status metrics for all the queues
managed by each Queue Manager:

Aggregated Agent-MQ
Connection Status
Maximum Queue Depth
Reached
reached for any of the queues.
depth
(z/OS only)
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:
Status

Metric name Type Monitoring Level Description
Channel Name String R Name of the channel.


Channel Type Mapped Value R Specifies the channel type, one of the following:
1 = MQCHT_SENDERSender channel
2 = MQCHT_SERVERServer channel
3 = MQCHT_RECEIVERReceiver channel
4 = MQCHT_REQUESTERRequester channel
5 = MQCHT_ALLAll the channel types are selected.
6 = MQCHT_CLNTCONNClient connection channel
7 = MQCHT_SVRCONNServer connection channel
8 = MQCHT_CLUSRCVRCluster receiver channel
9 = MQCHT_CLUSSDRCluster 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_NORMALNormal speed.
2 = MQNPMS_FASTFast speed.
Queue Manager
Name
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


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

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.


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_INDOUBTChannel is not in
doubt.
1 = MQCHIDS_INDOUBTChannel 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_STOPPEDMessage channel agent
stopped.
3 = MQMCAS_RUNNINGMessage 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_INACTIVEChannel is not active.
1 = MQCHS_BINDINGChannel is negotiating with the
partner.
2 = MQCHS_STARTINGChannel is waiting to become
active.
3 = MQCHS_RUNNINGChannel is transferring or
waiting for messages.
4 = MQCHS_STOPPINGChannel is in process of
stopping.
5 = MQCHS_RETRYINGChannel is reattempting to
establish connection.
6 = MQCHS_STOPPEDChannel is stopped.
7 = MQCHS_REQUESTINGRequester channel is
requesting connection
8 = MQCHS_PAUSEDChannel is paused.
13 = MQCHS_INITIALIZINGChannel is initializing.


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

level
Description
Activity Recording Mapped Value
Dynamic
M Indicates whether activity reports can be generated.
One of:
0 = MQRECORDING_DISABLEDActivity reports
cannot be generated.
1 = MQRECORDING_QActivity reports can be
generated and sent to
SYSTEM.ADMIN.ACTIVITY.QUEUE.
2 = MQRECORDING_MSGActivity 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_NONEDo not check any
elements.
1 = MQADOPT_CHECK_ALLCheck 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_NAMECheck the
Queue Manager name.
4 = QADOPT_CHECK_NET_ADDRCheck the network
address.


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 Managers initial default value.
Authority Events Mapped Value F Indicates Authorization Event enabled.
Auto Definition Events
Generated
Mapped Value F Indicates Auto Definition Event 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 Managers 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 initiators 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.


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.
3 = MQEVR_NO_DISPLAY: Event reporting enabled for
all successful commands except Inquire commands.
Command Input
Queue
String F Command input queue name.


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
500 = MQCMDL_LEVEL_500System for MQSeries
v5.0
510 = MQCMDL_LEVEL_510System for MQSeries v.5
release 1
520 = MQCMDL_LEVEL_520System for MQSeries v.5
release 2
530 = MQCMDL_LEVEL_530System for WebSphere
MQ v.5 release 3
MQ v6
MQ v7
Configuration Events
(z/OS only)
Mapped Value F Controls whether configuration events are generated.
0 = MQEVR_DISABLED: Event reporting disabled.
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.


level
Description
Distribution Lists Mapped Value F Indicates Distribution List enabled.
0 = MQDL_NOT_SUPPORTEDDistribution lists not
supported.
1 = MQDL_SUPPORTEDDistribution 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,


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.
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.


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_DISABLEDEvent reporting disabled. No
queue reached maximum queue depth.
2 = MQEVR_EXCEPTIONPerformance event
exception.


level
Description
Platform Mapped Value R Platform on which the Queue Manager resides. One of:
1 = MQPL_ZOSz/OS
3 = MQPL_AIXAIX (same value as MQPL_UNIX).
3= MQPL_UNIXUNIX systems.
4 = MQPL_OS400i5/OS.
12 = MQPL_VMSHP OpenVMS.
11 = MQPL_WINDOWS_NTWindows.
13 = MQPL_NSKCompaq 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 Managers 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_DISABLEDEvent reporting disabled.
1 = MQCHAD_ENABLEDEvent reporting enabled.
Remote Events Mapped Value F Indicates Remote Error Event enabled.
Repository Name String F The name of a cluster for which this Queue Manager is
to provide a repository service.


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.


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_AVAILABLEUnits of work and
syncpointing not available.
1 = MQSP_AVAILABLEUnits 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_NOThe TCP KEEPALIVE Facility is
not to be used. This is the Queue Managers initial
default value.
1 = MQTCPKEEP_YESThe 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_SINGLEThe channel initiator may
only use the TCP/IP address space specified in
TCPName. This is the Queue Managers initial default
value.
1 = MQTCPSTACK_MULTIPLEThe 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.


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_NOThe listener is not to register
with WLM. This is the Queue Managers initial default
value.
1 = MQDNSWLM_YESThe 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.

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.
Timestamp String M Indicates the system timestamp of Agent-MQ
Connection Status.



Queue Metrics

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.
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_OPENBinding fixed by MQOPEN
call.
1 = MQBND_BIND_NOT_FIXEDBinding 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_PREDEFINEDPredefined permanent queue.
2 = MQQDT_PERMANENT_DYNAMICDynamically
defined permanent queue.
3 = MQQDT_TEMPORARY_DYNAMICDynamically
defined temporary queue.
4 = MQQDT_SHARED_DYNAMIC
Description String R Description of the queue.
Distribution Lists Mapped Value F 0 = MQDL_NOT_SUPPORTEDDistribution lists not
supported.
1 = MQDL_SUPPORTEDDistribution lists supported.


Level
Description
Get Messages Mapped Value M Get operations allowed or inhibited.
Harden Get
Backout
Mapped Value F Indicates whether backout count is tracked.
0 = MQQA_BACKOUT_NOT_HARDENEDBackout count
may not be remembered.
1 = MQQA_BACKOUT_HARDENEDBackout 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_NONENo index.
1 = MQIT_MSG_IDThe queue is indexed using message
identifiers.
2 = MQIT_CORREL_IDThe queue is indexed using
correlation identifiers.
3 = MQIT_MSG_TOKENThe queue is indexed using
message tokens.
4 = MQIT_GROUP_IDThe queue is indexed using group
identifiers.
Initiation Queue String F Name of the initiation queue.
Max 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_PRIORITYif priority is relevant
1 = MQMDS_FIFOfirst-in, first-out
Persistence Mapped Value F Default persistence of messages on the queue. One of:
1 = MQPER_PERSISTENTThe message survives system
failures and Queue Manager restarts.
0 = MQPER_NOT_PERSISTENTThe message does not
normally survive system failures or Queue Manager
restarts.
Both persistent and nonpersistent messages can exist on
the same queue.


Level
Description
Process Name String F Name of the process.
Put Messages Mapped Value M Put operations allowed or inhibited.
QSG Disposition
(z/OS only)
Mapped Value
Dynamic
F Specifies the disposition of the process definition. One of:
-1 (minus 1) = MQQSGD_ALLThe 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_MGRThe 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_COPYThe 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_SHAREDThe 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_GROUPThe object definition resides in
the shared repository. The object was defined using a
command that had the parameter MQQSGD_GROUP.
4 = MQQSGD_PRIVATEClear 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_LIVEThe object is defined as
MQQSGD_Q_MGR or MQQSGD_COPY. This is the default
value if the parameter is not specified.


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.
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:
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:
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_NONENo queue service interval events
enabled.
1 = MQQSIE_HIGHQueue Service Interval High events
enabled.
2 = MQQSIE_OKQueue Service Interval OK events
enabled.


Level
Description
Queue Type Mapped Value M Queue Type.
1 = MQQT_LOCALlocal queue.
2 = MQQT_MODELmodel queue definition
3 = MQQT_ALIASalias queue definition
7 = MQQT_CLUSTERcluster queue definition
6 = MQQT_REMOTElocal 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
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_MGRQueue-manager scope.
2 = MQSCO_CELLCell scope.
Shareability Mapped Value F Indicates whether queue can be shared or is opened for
exclusive use.
0 = MQQA_NOT_SHAREABLEQueue is not shareable.
1 = MQQA_SHAREABLEQueue 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.


Level
Description
Trigger Type Mapped Value F Trigger type.
0 = MQTT_NONENo trigger messages.
1 = MQTT_FIRSTTrigger message when queue depth
goes from 0 to 1.
2 = MQTT_EVERYTrigger message for every message.
3 = MQTT_DEPTHTrigger message when depth
threshold exceeded.
Usage Mapped Value M 0 = MQUS_NORMALNormal usage.
1 = MQUS_TRANSMISSIONTransmission queue.

Status Metrics
To see data for the Oldest Message Age and Queue Time metrics, Queue Monitoring
must be enabled in WebSphere MQ.

Level
Description
Dynamic
Dynamic
Dynamic
M Number of messages on queue.
Current Queue Depth
Percentage (% Queue
Full)
Number
Dynamic
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
Dequeue Count Per Day Number
Dynamic
in the last day.
Dequeue Count Per Hour Number
Dynamic
in the last hour.


Level
Description
Dequeue Count Per
Minute
Number
Dynamic
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
Enqueue Count Per Day Number
Dynamic
in the last day.
Enqueue Count Per Hour Number
Dynamic
in the last hour.
Enqueue Count Per
Minute
Number
Dynamic
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.
6 Hours (sec)
Number
Dynamic
M Running maximum oldest message age over the last
six hours.
Day (sec)
Number
Dynamic
day.
Hour (sec)
Number
Dynamic
hour.
Dynamic
M Number of handles that are currently valid for
removing messages from the queue.


Level
Description
Dynamic
M Number of handles that are currently valid for adding
messages to the queue
Queue Monitoring Mapped Value
Dynamic
-3 = MQMON_Q_MGRCollect monitoring data
according to the setting of the QueueMonitoring
Queue Manager attribute. This is the default value.
0 = MQMON_OFFOnline monitoring data
collection is turned off for this queue.
17 = MQMON_LOWIf the value of the
MQMON_NONE, online monitoring data collection is
turned on, with a low rate of data collection for this
queue.
turned on, with a moderate rate of data collection
for this queue.
65 = MQMON_HIGHIf the value of the
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.
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.
Uncommitted Messages Number
Dynamic
M Number of uncommitted messages.

More information:



Channel Initiator Metrics
Channel Initiator metrics are reported for Queue Managers running on z/OS hosts only.
Configuration Settings

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

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.


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
Unknownstopped/unknown.
1 = MQSVC_STATUS_STARTINGstarting.
2 = MQSVC_STATUS_RUNNINGrunning.
3 = MQSVC_STATUS_STOPPINGstopping.
4 = MQSVC_STATUS_RETRYINGretrying.
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:
Log Copy Records
Status



Level
Description
Archive Status Mapped Value R Specifies whether archiving is on or off. One of:
0 = Nono archiving.
1 = Yesarchiving 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 = Nono dual archive archiving.
1 = Yesdual archive logging is on.
Dual BSDS Logging Mapped Value R Specifies whether dual BSDS is being used. One of:
0 = Nono dual BSDS.
1 = Yesdual BSDS is on.
Dual Logging Mapped Value R Specifies whether dual logging is being used. One of:
0 = Nono dual logging.
1 = Yesdual 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 = Nolog is not suspended.
1 = Yeslog 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.


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_INITIALThe initial settings of the
log parameters.
11 = MQSYSP_TYPE_SETThe settings of the log
parameters if they have been altered since their initial
setting.
12 = MQSYSP_TYPE_LOG_COPYInformation relating
to the active log copy.
13 = MQSYSP_TYPE_LOG_STATUSInformation
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

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

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.



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:
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
Status
Aggregated Status Metric

Aggregated Page Set Status Mapped Value Indicates the aggregated status of the page sets. One of:


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.


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_USERThe 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_SYSTEMA secondary extent
size that is approximately 10 per cent of the current
size of the page set.
3 = MQUSAGE_EXPAND_NONENo 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_PAGESETReturn page set and
buffer pool information.
MQIACF_USAGE_DATA_SETReturn data set
information for log data sets.
MQIACF_USAGE_ALLReturn page set and data set
information.



Status Metrics

Level
Description
Page Set Status Mapped Value
Dynamic
M Current status of the page set. One of:
0 = MQUSAGE_PS_AVAILABLEThe page set is
available.
1 = MQUSAGE_PS_DEFINEDThe page set has been
defined but has never been used.
2 = MQUSAGE_PS_OFFLINEThe 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_DEFINEDThe 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

Level
Description
Active Channels(z/OS
only)
Number
Dynamic
M Number of active channels.
Dynamic
Dynamic


Level
Description
Channel Initiator
Dispatchers (z/OS
only)
Number
Dynamic
M Number of dispatchers.
Channel Initiator
on z/OS)
Mapped Value
Dynamic
M 0 = MQSVC_STATUS_STOPPED or unknownChannel
Initiator stopped/unknown.
1 = MQSVC_STATUS_STARTINGChannel Initiator
starting up.
2 = MQSVC_STATUS_RUNNINGChannel Initiator
running.
3 = MQSVC_STATUS_STOPPINGChannel Initiator
shutting down.
4 = MQSVC_STATUS_RETRYINGChannel Initiator
retrying.
Command Server
on z/OS)
Mapped Value
Dynamic
M One of:
2 = MQQMSTA_RUNNING
RUNNING.
0 = UnknownUNKNOWN.
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.



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.

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.



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.

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
TRUEBroker is shared.
FALSEBroker 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.

Backouts Total Number Aggregate total of messages backed out across all Execution
Groups under this node.


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.

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
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


Architecture String Identifies the processor architecture of the Execution Group. The
following values are reported to CA Introscope for different
architecture execution groups:
default for default architecture
Number of
Subcomponents
Number Number of message flows and message sets under this Execution
Group.
Shared Object String
TRUEExecution Group is shared.
FALSEExecution 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.


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.

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.



Wide Statistics

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" ...


Message Flow Statistics
A Message Flow contains two or more Message Nodes.
Each of the Message Flows under an Execution Group reports the following statistics:
Message Flow properties and aggregate metrics covering all Message Nodes under
the Message Flow
ErrorsError statistics for the Message Flow
Message Flow InvocationsTotal number of invocations during the interval being
monitored.
Message StatisticsStatistics 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
PerformancePerformance statistics for the Message Flow
Data Collection Rules
Accounting and statistics data is collected only for message flows that start with an
MQInput, HTTPInput, or user-defined input node.
Data collection follows these rules:
If you start data collection for a message flow that starts with one of these nodes,
the data is collected for all built-in and user-defined nodes, including those in
subflows.
If the message flow starts with another input node (for example, a Real-timeInput
node), no data is collected (and no errors are reported).
Intervals
Message flow metrics use a 20-second interval, except for calculated aggregates, which
run on the Enterprise Manager and use a 15-second interval.


Aggregate Metrics Across All Message Flows
At the top of the Message Flows tree, you can see aggregate metrics for all Message
Flows.

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


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
TRUEMessage Flow has been deployed to the broker.
FALSEMessage Flow has not been deployed to the broker.
Elapsed Time Total Number Time spent waiting for messages, aggregated for all nodes under this
Message Flow.


Errors Total Number Total number of errors, aggregated for all nodes under this Message
Flow.
Invocations Total Number Total number of Message Flow invocations.
Message Count Total Number Total number of messages processed by this node.
Message Flow
Coordinated
Transactions Allowed
Number Whether coordinated transactions are allowed for this Message
Flow. One of:
TRUECoordinated transactions are allowed.
FALSECoordinated 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:
debugDefines debug user trace.
noneStates that user trace is not running.
normalDefines normal user trace.
unknownDefines 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:
TRUEStatistics are reported for this Message Flow.
FALSEStatistics 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.



Errors

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
Processing Errors Total Number M Number of errors processing a message during
Thread Count In Pool Total Number R Number of threads in pool.
Thread Maximum Reached
Total
Number M Number of times the maximum number of
threads was reached during the most recent
20-second interval.
Timeouts Total Number M Number of timeouts processing a message
(AggregateReply node only) during the most
recent 20-second interval.

Message Flow Invocations

Metric name Type In Description
Message Flow Backouts
Total
Number M Number of transaction backouts aggregated
from all nodes of this message flow during the
most recent 20-second interval.
Message Flow Commits
Total
Number M Number of transaction commits aggregated
from all nodes of this message flow during the
Message Flow Invocations
Total
Number M Total number of invocations, that is, sum of
Message Flow Backouts Total and Message
Flow Commits Total.



Message Statistics

Level
Description
Message Count Total Number M Total number of messages processed during
Message Size Average Number M Average size of input messages (bytes) during
Message Size Maximum Number M Maximum input message size (bytes) during
Message Size Minimum Number M Minimum message input size (bytes) during
Message Size Total Number M Total size of input messages (bytes) during

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.

Level
Description
CPU Processing Time Number M Total CPU time, in milliseconds, this node has
spent processing input messages during the
CPU Processing Time Average Number M Average CPU time, in milliseconds, this node
takes to process an input message during the
Elapsed Time Number M Total elapsed time, in milliseconds, the node
has spent waiting for input messages during
Elapsed Time Average Number M Average elapsed time, in milliseconds, the
node has spent waiting for input messages
during the most recent 20-second interval.


Node Invocation Total Number M Total number of messages processed by this
node during the most recent 20-second
interval.
Node Type String R Type of the node being monitored. This
should correspond to the node name, e.g.
MQInputNode.
Number of Input Terminals Number F Each message flow node has a fixed number
of input and output points or terminals which
serve as entrances to or exits from a node.
These metrics measure the total number of
input and output terminals for the node.
Number of Output Terminals Number F

Performance

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
CPU Time Waiting For Input Total Number M Total CPU time spent waiting for input
Elapsed Time Average Number R Average elapsed time spent processing input
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
Elapsed Time Waiting For Input
Average
Number F Average elapsed time spent waiting for input


Level
Description
Elapsed Time Waiting For Input
Total
Number F Total elapsed time spent waiting for input

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.
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.
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.


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.


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.


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


Queues
Individual queue name
Operational group
Topics (JMS only)
Individual topic name
Operational group
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.


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.


Appendix F: JCA/JMS Operational Groups

This appendix lists the operation names for each Operational Group.
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 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
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.


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
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.


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


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.
This section describes the following JMS Operational Groups:
JMS Queue Manager Operational Groups
JMS Queue/Topic Operational Groups


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.


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.
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.


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 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
Operation name: Consumer Receive
Description:
Monitors the JMS Queue/Topic consumer receive operations in the
Operation name: Get Server Session Pool
Description:
Monitors the JMS session pool get operations in the com.ibm.mqjms.jar file.


Operation name: Close Connection
Description:
Monitors the JMS Queue/Topic connection close operations in the


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.
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


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:
At the minimum level:
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


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
132600
Recommended 300, 2 256 to 512 Queue Managers: 5
129000
Recommended 600, 2 256 to 512 Queue Managers: 5
129000
Full 300, 2 256 to 512 Queue Managers: 5
121600
Full 600, 2 256 to 512 Queue Managers: 5
115500

WebSphere MQ Sizing


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:
Details:
Details:
Dell Inc., PowerEdge GX620
Details:
Intel Pentium 4 CPU 3.00 GHz, ~3.0 GHz
WebSphere MQ Sizing


Details:
2 GB
Details:
17 GB
4-512 MB
WebSphere MQ computer:
Details:
Details:
Details:
Intel Pentium D CPU 3.00 GHz, ~3.0 GHz
Details:
2 GB
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


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:
+ (7 * N)
At the minimum level:
+ (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


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
execution groups
per broker
Total number of
message flows
Number of nodes
per message flow
Number of metrics
reported
Minimum 15 90 51 5800
Full 15 90 51 9400
execution groups
per broker
Total number of
message flows
Number of nodes
per message flow
Number of metrics
reported
Minimum 5 30 51 1800
Full 5 30 51 2900

WebSphere MB Sizing


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:

execution groups
per broker
Total number of
message flows
Number of nodes
per message flow
Number of metrics
reported
Minimum 10 130 51 8100
Full 10 130 51 12600

Environment Details
Enterprise Manager
Details:
Details:
Details:
Dual Core AMD Opteron Processor 8220, MMX, 3D Now(8CPUs), ~2.8 HZ
Details:
16 GB
Details:
210 GB
WebSphere MB Sizing


MQMonitor agent:
Details:
Details:
Dell Inc., Optiplex GX620
Details:
Intel Pentium 4 CPU 3.00 GHz, ~3.0 GHz
Details:
2 GB
Details:
17 GB
4-512 MB
WebSphere MB computer:
Details:
Details:
Dell Inc., Optiplex 745
WebSphere MB Sizing


Details:
Intel Pentium D CPU 3.00 GHz, ~3.0 GHz
Details:
2 GB
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.


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.
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


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 channelwhether 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


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


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


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


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


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>.


Appendix I: Troubleshooting

This appendix provides solutions for troubleshooting issues that you may encounter in
CA APM for IBM WebSphere MQ.
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.


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.


[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 Managers
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


[DEBUG]
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]
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:
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


[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:
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]
in] Configuration Manager is not initialized.
[FATAL]
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>


[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]
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.


[ERROR]
racer] Statistics for all Execution groups are missing. WebSphere MB agent probably
lost connection.
[INFO]
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:
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.


[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:
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.
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.


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 CCSIDs 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.


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.
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


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
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


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
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
24
Install MQMonitor agent 24
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


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
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

APM - 9.5 - APM For IBM WebSphere MQ Guide

Загружено:

Сведения о документе

Исходное описание:

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

APM - 9.5 - APM For IBM WebSphere MQ Guide

Загружено:

Авторское право:

Доступные форматы

for IBM WebSphere MQ Guide

Вам также может понравиться