powerpack for websphere mq v8 1userguide

Date: 04-2009

Version 8.1

CA Wily Introscope®

PowerPack for IBM® WebSphere® MQ Connectors and Messaging System

User Guide

6000 Shoreline Court, Suite 300 South San Francisco, CA 94080

Copyright © 2009, CA. All rights reserved.

Wily Technology, the Wily Technology Logo, Introscope, and All Systems Green are registered trademarks of CA.

Blame, Blame Game, ChangeDetector, Get Wily, Introscope BRT Adapter, Introscope ChangeDetector, Introscope Environment Performance Agent, Introscope ErrorDetector, Introscope LeakHunter, Introscope PowerPack, Introscope SNMP Adapter, Introscope SQL Agent, Introscope Transaction Tracer, SmartStor, Web Services Manager, Whole Application, Wily Customer Experience Manager, Wily Manager for CA SiteMinder, and Wily Portal Manager are trademarks of CA. Java is a trademark of Sun Microsystems in the U.S. and other countries. All other names are the property of their respective holders.

For help with Introscope or any other product from CA Wily Technology, contact Wily Technical Support at 1-888-GET-WILY ext. 1 or [email protected].

If you are the registered support contact for your company, you can access the support Web site directly at www.ca.com/wily/support.

We value your feedback

Please take this short online survey to help us improve the information we provide you. Link to the survey at: http://tinyurl.com/6j6ugb

If you have other comments or suggestions about Wily documentation, please send us an email at [email protected].

US Toll Free 888 GET WILY ext. 1 US +1 630 505 6966 Fax +1 650 534 9340 Europe +44 (0)870 351 6752 Asia-Pacific +81 3 6868 2300 Japan Toll Free 0120 974 580 Latin America +55 11 5503 6167

www.ca.com/apm

mailto:[email protected]

http://tinyurl.com/6j6ugb

http://www.ca.com/wily/support

mailto:[email protected]

http://www.ca.com/apm

Contents iii

CONTENTS

Table of Contents

Chapter 1 PowerPack for IBM WebSphere MQ . . . . . . . . . . . 1

About PowerPack for MQ. . . . . . . . . . . . . . . . . 2Components . . . . . . . . . . . . . . . . . . . . . 3What’s new in PowerPack for MQ . . . . . . . . . . . . . . 4

Chapter 2 Installing and Configuring the PowerPack for MQ . . . . . . 9

Preparing to install PowerPack for MQ . . . . . . . . . . . . 10

Check system and version requirements . . . . . . . . . . 10

Identify installation machines and directories . . . . . . . . 10

Check server connection and access. . . . . . . . . . . . 10

Download the PowerPack for MQ . . . . . . . . . . . . . 11

Install PowerPack for MQ with minimum configuration . . . . . . 12

Install and configure the MQMonitor agent . . . . . . . . . . 15

Extract the MQMonitor agent files . . . . . . . . . . . . 15

Check the Java environment requirement . . . . . . . . . . 16

Obtain third-party libraries . . . . . . . . . . . . . . . 17

Configure the MQMonitor agent for third-party libraries . . . . . 19Configure the MQMonitor agent properties . . . . . . . . . 20

Security settings for CMP, JMS, PCF connections . . . . . . . 32Run the MQMonitor agent . . . . . . . . . . . . . . . 43

Configure WebSphere MQ for MQ Trace . . . . . . . . . . . 43

Upgrade the MQMonitor agent . . . . . . . . . . . . . . 44

(Optional) Install MQMonitor agent as a Windows Service . . . . . 46

Install and configure MQ Java Connectors . . . . . . . . . . 47

Extract the MQ Java Connectors files . . . . . . . . . . . 47

Configure MQ Java Connectors . . . . . . . . . . . . . 49

Configure ErrorDetector . . . . . . . . . . . . . . . . 53

Configure JCA Connection Pool . . . . . . . . . . . . . 55

Install Management Modules and extensions . . . . . . . . . 56

iv Contents

PowerPack for WebSphere MQ Connectors and Messaging System

Additional Information . . . . . . . . . . . . . . . . . 57

Configure SSL . . . . . . . . . . . . . . . . . . . 58

Configure WebSphere MB . . . . . . . . . . . . . . . 64

Configure WebSphere MQ to publish events . . . . . . . . . 65

Turn on Queue Monitoring . . . . . . . . . . . . . . . 66

Chapter 3 Viewing Data Using PowerPack for MQ . . . . . . . . . . 67

View data . . . . . . . . . . . . . . . . . . . . . . 67

Console dashboards . . . . . . . . . . . . . . . . . . 67

MQ dashboards in the Console. . . . . . . . . . . . . . 67

Investigator dashboards . . . . . . . . . . . . . . . . 68

Understanding the metrics tree . . . . . . . . . . . . . 68

Investigator Dashboards and data displays . . . . . . . . . 74

Aggregated metrics . . . . . . . . . . . . . . . . . 76

MQ Events. . . . . . . . . . . . . . . . . . . . . 79

Using dashboards in troubleshooting . . . . . . . . . . . . 81

Troubleshooting Queue Manager clusters and Queue Managers . . 81

Troubleshooting Message Brokers . . . . . . . . . . . . 84

Chapter 4 Transaction Tracing . . . . . . . . . . . . . . . . . . 85

Cross-Process Transaction Tracing . . . . . . . . . . . . . 86

Transaction Trace Viewer . . . . . . . . . . . . . . . . 86

Configure the WebSphere MQ System for trace . . . . . . . . 87

Set the Activity recording property . . . . . . . . . . . . 88

Configure SYSTEM.ADMIN.ACTIVITY.QUEUE . . . . . . . . . 90

Set the handshake queue . . . . . . . . . . . . . . . 90

Set the MCA User ID . . . . . . . . . . . . . . . . . 91

Verify the transaction trace configuration. . . . . . . . . . . 91

WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard . . . . . . . . . . . . . . 92

Configure EM for trace . . . . . . . . . . . . . . . . . 96

Interpret trace information. . . . . . . . . . . . . . . . 97

Identify a slow transaction . . . . . . . . . . . . . . . . 102

Enable or disable MQ Traces . . . . . . . . . . . . . . . 104

Filter queues for transaction trace . . . . . . . . . . . . . 105

Trace data properties . . . . . . . . . . . . . . . . . 106

Contents v

User Guide

Appendix A Dashboards . . . . . . . . . . . . . . . . . . . . 109

Management Modules . . . . . . . . . . . . . . . . . 109

WebSphere MQ Client and Server dashboards . . . . . . . . . 109

WebSphere MQ Client And Server Overview dashboard . . . . . 110

WebSphere MQ Client And Server Overview - Details dashboard . . 112

WebSphere MQ - Client Connections dashboard. . . . . . . . 115WebSphere MQ - Client Operations dashboard . . . . . . . . 116WebSphere MQ - Server dashboard . . . . . . . . . . . . 117

WebSphere Message Broker dashboards . . . . . . . . . . . 118

WebSphere Message Broker Overview dashboard . . . . . . . 118

Other Message Broker dashboards . . . . . . . . . . . . 120

Message Broker alerts . . . . . . . . . . . . . . . . 121

Appendix B Metrics reference . . . . . . . . . . . . . . . . . . 123

General metric characteristics. . . . . . . . . . . . . . . 123

Metric display sets . . . . . . . . . . . . . . . . . . 124

Queue Manager Cluster metrics . . . . . . . . . . . . . . 125

Aggregate clusters status metrics . . . . . . . . . . . . 125

Top level repository trees . . . . . . . . . . . . . . . 126

Workload Balance metrics . . . . . . . . . . . . . . . 139

Queue Manager metrics . . . . . . . . . . . . . . . . . 146

Top level Queue Manager aggregated metrics . . . . . . . . 147

Channel metrics . . . . . . . . . . . . . . . . . . . 148

Configuration Properties metrics . . . . . . . . . . . . . 153

Dead Letter Queue metrics . . . . . . . . . . . . . . . 162

Last Check metrics . . . . . . . . . . . . . . . . . . 163

Queue metrics . . . . . . . . . . . . . . . . . . . 164

Channel Initiator metrics. . . . . . . . . . . . . . . . 172Log metrics . . . . . . . . . . . . . . . . . . . . 174Usage metrics . . . . . . . . . . . . . . . . . . . 177

Queue Manager Status metrics . . . . . . . . . . . . . 180Message Broker metrics . . . . . . . . . . . . . . . . . 181

Configuration Manager aggregate totals . . . . . . . . . . 182

Broker properties and aggregate totals. . . . . . . . . . . 183

Execution Groups metrics . . . . . . . . . . . . . . . 184

MQ Java Connector metrics . . . . . . . . . . . . . . . 196

Operational groups. . . . . . . . . . . . . . . . . . 196

vi Contents


Backend metrics . . . . . . . . . . . . . . . . . . 197

Instance Counts metrics . . . . . . . . . . . . . . . . 198

JCA node metrics . . . . . . . . . . . . . . . . . . 198

WebSphereMQ node metrics . . . . . . . . . . . . . . 199

ErrorDetector metrics . . . . . . . . . . . . . . . . . 204

Appendix C JCA/JMS Operational Groups . . . . . . . . . . . . . 207JCA Operational Groups . . . . . . . . . . . . . . . . 207

JCA Queue Manager Operations . . . . . . . . . . . . . 208

JCA Queue Operational Groups . . . . . . . . . . . . . 210

JMS Operational Groups . . . . . . . . . . . . . . . . 210

JMS Queue Manager Operational Groups . . . . . . . . . . 211

JMS Queue/Topic Operational Groups . . . . . . . . . . . 213

Appendix D Performance and Sizing . . . . . . . . . . . . . . . 215

MQMonitor agent background . . . . . . . . . . . . . . . 215

WebSphere MQ Sizing . . . . . . . . . . . . . . . . . 216

Sizing your MQMonitor agent . . . . . . . . . . . . . . 218

Sample MQMonitor agent sizing table . . . . . . . . . . . 219WebSphere MB Sizing . . . . . . . . . . . . . . . . . 221

Sizing your MQMonitor agent for WebSphere MB . . . . . . . 222

Sample MQMonitor agent sizing table for WebSphere MB . . . . 222

Appendix E Frequently Asked Questions . . . . . . . . . . . . . 225Alerts and dashboards . . . . . . . . . . . . . . . . 225

Installation . . . . . . . . . . . . . . . . . . . . 226

Metrics . . . . . . . . . . . . . . . . . . . . . . 226

Queues . . . . . . . . . . . . . . . . . . . . . . 227

Transaction Tracing . . . . . . . . . . . . . . . . . 227

Appendix F Troubleshooting . . . . . . . . . . . . . . . . . . 231

Appendix G Support for IPv6 Environment . . . . . . . . . . . . . 237Connect to the Introscope EM in an IPv6 environment . . . . . 237

Support for WebSphere MQ and WebSphere MB in an IPv6 environment . . . . . . . . . . . . . . . . 238

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Index . . . . . . . . . . . . . . . . . . . . . . . . . . 241

PowerPack for IBM WebSphere MQ 1

CHAPTER 1

PowerPack for IBM WebSphere MQ

The PowerPack for IBM® WebSphere® MQ Connectors and Messaging System

allows administrators to monitor the health and performance of IBM®

WebSphere® Message Queue (WebSphere MQ) and IBM® WebSphere® Message Broker (WebSphere MB).

This chapter contains the following topics:

About PowerPack for MQ . . . . . . . . . . . . . . . . . 2

Components . . . . . . . . . . . . . . . . . . . . . 3

What’s new in PowerPack for MQ . . . . . . . . . . . . . . . 4

2 PowerPack for IBM WebSphere MQ

PowerPack for IBM WebSphere MQ Connectors and Messaging System

About PowerPack for MQ

An extension of Introscope, Wily’s flagship web application management solution, the PowerPack for IBM WebSphere MQ Connectors and Messaging System (PowerPack for MQ) lets you monitor the performance of WebSphere MQ and WebSphere MB. By using the metrics provided by PowerPack for MQ, you can monitor the health and availability of WebSphere MQ-connected web applications and quickly isolate the source of WebSphere MQ-related and WebSphere MB-related performance problems.

The PowerPack for MQ lets you:

Monitor the performance of the WebSphere MQ infrastructure

Monitor the performance of WebSphere MB

Monitor the performance of WebSphere MQ Java Connectors

Correlate WebSphere MQ-to-application activity

Verify the use of WebSphere MQ capacity and use of MB capacity by web applications

Verify if WebSphere MQ and WebSphere MB meet the Service Level Agreements of web applications

The PowerPack for MQ provides Management Modules with pre-configured dashboards and performance-triggered alerts to monitor critical messages and queues for WebSphere MQ, and also monitor the health and availability of various WebSphere MB components.

The PowerPack for MQ helps ensure high availability of all WebSphere MQ-connected Java web applications.

3

User Guide

Components

The PowerPack for MQ consists of three components:

MQMonitor agent

The MQMonitor agent reports data on the performance of WebSphere MQ resources, such as queues and channels, to Introscope, which in turn displays the data as metrics under the following nodes in the Introscope Workstation Investigator metrics tree:

Queue Managers—The Queue Managers directory lists metric data for Queues, Channels, Logs (z/OS only), Usage (z/OS only), Channel Initiators (z/OS only), and Queue Manager objects.

Queue Manager Clusters—The Introscope Workstation Investigator displays Cluster Queue Managers along with their associated queues and channels so that you can easily monitor cluster performance. Multi-instanced cluster queues appear under the Workload Balance directory.

The MQMonitor agent monitors WebSphere MB and reports data on the performance of the WebSphere MB components to Introscope, where the data can be viewed as metrics in the Introscope Investigator tree under the WebSphere Message Broker node.

MQ Java Connectors Monitor

The MQ Java Connectors Monitor monitors the WebSphere MQ classes (both Connector and JMS) used for communicating with WebSphere MQ from a web application deployed on an application server. The web applications can use either JMS or Connector classes (or a combination of both) to communicate with WebSphere MQ. The data is displayed as metrics in the Introscope Investigator tree under the WebSphereMQ node.

Management Modules and Enterprise Manager (EM) extensions

The Management Modules contain pre-configured dashboards and alerts that Introscope uses to display WebSphere MQ and WebSphere MB metrics in graphical form. This component also includes dashboards for the Investigator as well as Javascript calculators and EM extensions which aggregate metric data for display in the Introscope Investigator. You can configure the dashboards and alerts to proactively alert operations and application-support personnel and WebSphere MQ administrators of potential WebSphere MQ and WebSphere MB issues before they become application performance bottlenecks.



What’s new in PowerPack for MQ

PowerPack for MQ has the following features.

Monitor WebSphere MQ over secured channels

If channel security is enabled over Secure Sockets Layer (SSL), then you can monitor WebSphere MQ over secured channels. For information on SSL, see Configure SSL on page 58.

Cross-process transaction trace from applications to WebSphere MQ

This feature enables Introscope to provide transaction trace views of transactions starting from the servlet upto the Queue Managers. The cross-process transaction tracing extends the monitoring capability of PowerPack for MQ and lets you determine the components of WebSphere MQ that are causing performance bottlenecks.

Cross-process transaction tracing helps you do the following:

Acquire and analyze WebSphere MQ performance information and identify performance problems caused by WebSphere MQ.

Identify whether WebSphere MQ is responsible for an application slowdown.

Extend the monitoring capability of PowerPack for MQ to determine which component of WebSphere MQ is causing the performance bottleneck.

Enable Introscope to provide transaction trace views of transactions starting from servlet all the way into the Queue Managers.

Identify the time taken by the message to pass through various queues and channels of a transaction (application to destination queue).

Correlate the trace data obtained from WebSphere MQ components with the trace data from the Introscope-enabled WebSphere MQ client application that has posted the WebSphere MQ message.

Provide a full transaction trace view when WebSphere MQ is used in the request-response mode.

PowerPack for MQ includes the WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard that you can use to check whether your WebSphere MQ infrastructure is properly configured for MQ Trace. You can also use the mqConfigurationSetup tool to automate the configuration of cross-process transaction tracing.

For more information, see Cross-Process Transaction Tracing on page 86.

5

User Guide

Filter dynamic queues in WebSphere MQ

When an application program issues an MQOPEN call to open a model queue, the Queue Manager dynamically creates an instance of a local queue with the same attributes as the model queue. Depending on the value of the Definitiontype field of the model queue, the Queue Manager creates either a temporary or permanent dynamic queue.

If the dynamic queues show up as regular queues during PowerPack for MQ monitoring inquiries, this may cause too many metrics to be displayed. Hence an option is provided to either enable or disable the display of dynamic queues in the Investigator tree.

If dynamic queues are filtered from being monitored, the response time improves.

Set the following property in MQMonitor.properties file to enable filtering so that dynamic queues are not monitored: <Queue Manager>@<hostname>.queue.filter.exclude.dynamic=true

In case of MQ Java connectors, the dynamic queues are always displayed under the Dynamic Queues node.

If the delay time of the MQMonitor agent is very high compared to the duration of the existence of the temporary dynamic queues in the Queue Manager, and if you enable filtering so that dynamic queues are not monitored, then:

Most of the metrics for the temporary dynamic queues may not appear in the Investigator tree.

A few metrics such as Current Queue Depth may display incorrect data.

Management Modules—New WebSphere MQ Client and Server dashboards

PowerPack for MQ includes the new WebSphere MQ Client and Server dashboards that show the real-time performance and health of WebSphere MQ system. The WebSphere MQ Client and Server dashboards are a set of five dashboards that you can use to correlate the activity of the WebSphere MQ Client Connections using the MQ Java Connector operations on the WebSphere MQ system, with the actual activities on the WebSphere MQ system. You can obtain metrics about the number of put, get, send, and receive operations, the response times, and queue depth information.

For more information, see WebSphere MQ Client and Server dashboards on page 109.



Support WebSphere MQ v7.0 and WebSphere MB v6.1

PowerPack for MQ provides additional support for WebSphere MQ v7.0 and WebSphere MB v6.1. All features in the PowerPack for MQ are compatible with WebSphere MQ v7.0 and WebSphere MB v6.1.

Support non-English character sets in WebSphere MQ

PowerPack for MQ can monitor both the English and non-English versions of WebSphere MQ objects. To do this, set the following property in the MQMonitor.properties file:

<Queue_Manager>@<hostname>.character.set = <Relevant IBM non-English CCSID>

where <Queue_Manager> is the Queue Manager name, <hostname> is the host name of the system where WebSphere MQ is installed, and CCSID is the supported IBM ID for that specific non-English language. CCSID is an abbreviation used by IBM to mean "Coded Character Set Identifier". It is a 16-bit number that represents a specific encoding of a specific code page.

For example, if WebSphere MQ is installed on a Korean operating system, the IBM CCSID for Korean language needs to be placed in the character.set property.

» Note PowerPack for MQ does not monitor non-English versions of WebSphere MB.

The following scenario illustrates how the MQMonitor agent monitors WebSphere MQ running on a non-English operation system:

Suppose WebSphere MQ is running on a non-English operating system (say,

Korean). When you create objects using the IBM® MQ Explorer (MQ Explorer), you must mention details such as Queue Manager name and Channel name in English and not in any non-English language. You must ensure that the schema is also in English. However, the properties for these objects may be in the non-English language. In such a scenario:

The MQMonitor agent of the PowerPack for MQ running on an English OS connects to a non-English (Korean) MQ system. Connection is possible because details such as the Queue Manager Name, Channel name, and so on, are displayed in English and have provided the Korean CCSID.

Introscope Enterprise Manager and Workstation are residing on an English OS host. Here, the top level names such as the Queue Manager name, channel name, and so on, are displayed in English and the Investigator metric values for these objects are also in English because the PowerPack for MQ returns IBM constants instead of the values on the WebSphere MQ system that are in the local language.

7

User Guide

» Important If the host name of the system is in a non-English language, then you must use the IP Address of the non-English machine for configuring the Queue Managers in the MQMonitor.properties file, instead of the host name.

Easier configuration of the MQMonitor agent

The property names of a few properties have been changed in the MQMonitor agent. If you are using the older version of the MBMonitor.properties file, you need to upgrade the old property file to the new one by replacing the old property name with the new property name. You can use the same value for the properties.

To relate the old properties to the new properties, see the following table:

Old property name New property name

CMP_MACHINE configuration.manager.host

CMP_QUEUE_MANAGER configuration.manager.queue.manager

CMP_PORT configuration.manager.port

MQ_Broker_List mq.broker.list

Statistics_Broker_List statistics.broker.list

JMS_MACHINE jms.broker.host

JMS_QUEUE_MANAGER jms.broker.queue.manager

JMS_PORT jms.broker.port

<BROKER>.EXEGRP <BROKER>.executiongroup

Node_Type_List node.type.list

Static_Delay_time static.delay.time

Installing and Configuring the PowerPack for MQ 9

CHAPTER 2

Installing and Configuring the PowerPack for MQ

This chapter contains instructions for installing and configuring the various components of PowerPack for MQ.


Preparing to install PowerPack for MQ . . . . . . . . . . . . 10

Install PowerPack for MQ with minimum configuration . . . . . . . 12

Install and configure the MQMonitor agent . . . . . . . . . . . 15

Configure WebSphere MQ for MQ Trace . . . . . . . . . . . . 43

Upgrade the MQMonitor agent . . . . . . . . . . . . . . . 44

(Optional) Install MQMonitor agent as a Windows Service . . . . . . 46

Install and configure MQ Java Connectors . . . . . . . . . . . 47

Install Management Modules and extensions . . . . . . . . . . 56

Additional Information . . . . . . . . . . . . . . . . . 57

10 Installing and Configuring the PowerPack for MQ


Preparing to install PowerPack for MQFollow the steps below to prepare for installation.

Check system and version requirements, below.

Identify installation machines and directories, below.

Check server connection and access, below.

Download the PowerPack for MQ on page 11.

Check system and version requirements

Ensure that your environment includes the following products and components:

IBM WebSphere MQ v6.x or v7.0

IBM WebSphere MB v6.0 or v6.1

Wily Introscope Workstation v8.0.3

Wily Introscope Enterprise Manager v8.0.3

Wily Introscope Agent v8.0.3

Identify installation machines and directories

To correctly install the software, you must identify the host name and directory path names of installed software:

Introscope Agent installation directory

Usually this is <appserver>/wily, where <appserver> is the home directory of your application server software.

<Introscope Home> directory on the machine hosting the Introscope Enterprise Manager.

Check server connection and access

To ensure proper server connection, check if you have the following:

A WebSphere MQ command server defined and running on the Queue Manager.

A Server Connection channel defined on the Queue Manager.

» Note Contact your WebSphere MQ specialist for details about configuring the Queue Manager machine.

The MQMonitor agent has TCP/HOST network access through firewalls.

Preparing to install PowerPack for MQ 11

User Guide

Download the PowerPack for MQ

Use the link to the CA Wily Software Download Site provided in the software delivery email. The following table lists the file names of the software archive for the Windows, UNIX, and z/OS platforms:

Platform Archive file names

UNIX PowerPackForWebSphereMQv8.1Unix.tar

Windows PowerPackForWebSphereMQv8.1Windows.zip

z/OS PowerPackForWebSphereMQv8.1Zos.tar

Windows and UNIX

The archive extraction steps for Windows and UNIX are the same; only the extension of the archives is different.

Type of file Windows OS file extensions

Equivalent UNIX file extensions

archive .zip .tar

executable .bat .sh

For example:

To download the PowerPack for MQ for Windows:

1 Download the PowerPack for MQ software archive PowerPackForWebSphereMQv8.1Windows.zip.

2 Open and uncompress the archive. The archive has the following files:

PowerPackForWebSphereMQv8.1Agent.windows.zip

PowerPackForWebSphereMQv8.1EM.windows.zip

PowerPackForWebSphereMQv8.1MQMonitor.windows.zip

To download the PowerPack for MQ for z/OS:

1 Download the PowerPack for MQ software archive -PowerPackForWebSphereMQv8.1Zos.tar.

2 Open and uncompress the archive. The archive has the following files:

PowerPackForWebSphereMQv8.1Agent.zos.tar

PowerPackForWebSphereMQv8.1EM.zos.tar



Install PowerPack for MQ with minimum configuration

This section describes how you can quickly install PowerPack for MQ with minimum configuration.

Scenario 1:

An Introscope-enabled Java Application running on Solaris and is communicating to WebSphere MQ at the backend. The application drops a message to a queue of queue manager running under host “host_AIX” and a particular port. The message is routed to a mainframe queue manager running on another port under host “host_MF”. A CICS application picks up the message from the mainframe Queue manager, processes it, and puts it back on a queue of queue manager from where the application picks up the message.

To install and configure the PowerPack for MQ, perform the following steps:

1 Check the following:

The MQ Command Server is up and running for both the Queue Managers.

The version of the Introscope EM, Workstation, and Agent is at least v8.0.3.

The JAR files as mentioned Obtain third-party libraries on page 17.

2 Unzip PowerPackForWebSphereMQv8.1MQMonitor.windows.zip to a local directory.

3 Place all the third-party downloaded jar under MQMonitor\lib directory and accordingly configure the startMQMonitor.bat file.

4 Edit MQMonitor\properties\MQMonitor.properties and add the following lines:

mq.monitor.list=first,secondfirst.host=host_AIXsecond.host=host_MFfirst.port=4444second.port=5555

5 Execute mqConfigurationSetup.bat from the MQMonitor\tools directory and check changehistory.txt and console output to check for changes or errors. If you face any connection problems with the CA_WILY_HANDSHAKE queue, check if you have configured the handshake properly; if handshake is configured properly, then you can ignore the error messages.

6 Restart all the active channels of the monitored queue managers or if possible restart the Queue Manager.

7 Execute startMQMonitor.bat. You can ignore any warning messages.

Install PowerPack for MQ with minimum configuration 13

User Guide

8 Unzip PowerPackForWebSphereMQv8.1Agent.unix.tar to the \wily directory of Introscope-enabled Java application.

9 Add PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl to the IntroscopeAgent.profile file.

10 Restart the Application Server.

11 Unzip PowerPackForWebSphereMQv8.1EM.windows.zip to the EM root installation directory.

12 Restart the EM.

To verify the installation, see the WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard.

Scenario 2:

Monitoring a configuration manager that manages a few brokers. Also checking the health of the message brokers.

To install and configure the PowerPack for MQ, perform the following steps:

1 Unzip PowerPackForWebSphereMQv8.1MQMonitor.windows.zip to a local directory.

2 Place all the third-party downloaded JAR files under MQMonitor\lib directory, and accordingly configure startMQMonitor.bat file.

3 Edit MQMonitor\properties\MBMonitor.properties and set the values for the add the following properties:

jms.broker.host jms.broker.queue.managerjms.broker.port

4 Execute the MQMonitor\properties\MBMonitorJMSQueues.mqsc file on your JMS Queue Manager using the following command:

runmqsc <QMGR name>\MQMonitor\properties\MBMonitorJMSQueues.mqsc

5 Create an ACL entry on the Configuration manager using the following command: mqsicreateaclentry <ConfMgrName> -u <UserName> -m <machineName>/<DomainName> -x V –p

6 Enable statistics for Message flows on the Execution Groups on the broker named foo_broker:

mqsichangeflowstats foo_broker -s -e <ExecutionGroupName> -j -c active -o xml -n basic

7 Enable Publish/Subscribe statistics for the brokers using the command:

mqsichangeproperties foo_broker -e <ExecutionGroupName> -o DynamicSubscriptionEngine -n statsInterval -v 30000



8 Execute startMQMonitor.bat and run it for about 10 minutes.

To verify your installation, check the following:

All Message Broker related metrics are reported under the WebSphere MessageBroker node.

You can see Message Flow statistics metrics for each message flow of an execution group.

You can see Broker Statistics metrics under an execution group.

Install and configure the MQMonitor agent 15

User Guide

Install and configure the MQMonitor agentThe MQMonitor agent provides information related to WebSphere MQ resources such as Queue Managers, Queues, and Channels, as well as WebSphere MB resources such as Brokers and Message Flows. This capability lets you monitor various dynamic WebSphere MQ or WebSphere MB properties to trigger alerts, view utilization measurements of components, and view resource properties.

» Note The MQMonitor agent is supported only on Windows or UNIX for monitoring instances of WebSphere MQ. This version does not support MQMonitor agent running on z/OS.

To install and configure the MQMonitor agent:

1 Extract the MQMonitor agent files on page 15.

2 Check the Java environment requirement on page 16.

3 Obtain third-party libraries on page 17.

4 Configure the MQMonitor agent for third-party libraries on page 19.

5 Configure the MQMonitor agent properties on page 20.

6 Run the MQMonitor agent on page 43.

The following sections describe these steps in detail.

Extract the MQMonitor agent files

Extract the contents of the MQMonitor agent archive to any directory. Depending on the platform, the archive is named: PowerPackForWebSphereMQv8.1MQMonitor.windows.zip on Windows or PowerPackForWebSphereMQv8.1MQMonitor.unix.tar on UNIX.

» Note You can extract the MQMonitor agent files to any directory.

The contents of the archive are extracted into a single MQMonitor directory. The MQMonitor directory has the following structure:

/lib

Agent.jar

encryptpwd.jar

jline-0.9.9.jar

/tools

mqConfigurationSetup.bat (Windows) or mqConfigurationSetup.sh (UNIX)



/ext

extension.jar

Supportability-Agent.jar

/properties

MBMonitorJMSQueues.mqsc

IntroscopeAgent.profile

MBMonitor.properties

MBMonitor.properties.template

MQMonitor.properties

MQMonitor.properties.template

installMQMonitor.txt

MQMonitor.jar

mqPwdEncryptor.bat (Windows) or mqPwdEncryptor.sh (UNIX)

startMQMonitor.bat (Windows) or startMQMonitor.sh (UNIX) and stopMQMonitor.sh (UNIX)

The MQMonitor directory also contains files related to installing MQMonitor agent as a Windows Service. For information on installing MQMonitor agent as a Windows Service, see (Optional) Install MQMonitor agent as a Windows Service on page 46.

Check the Java environment requirement

PowerPack for MQ can report specific WebSphere MQ Events in the Investigator tree. For information on MQ Events, see Configure WebSphere MQ to publish events on page 65.

To display MQ Events information, you must do one of the following:

Install the International Version of Java Runtime Environment (JRE) 1.4 (or above), and use it to run the MQMonitor agent.

If the non-International Version of Java Runtime Environment (JRE) 1.4 (or above) is used to run the MQMonitor agent, then:

Obtain the charsets.jar file from the International Version of JRE 1.4 (or above).

Add the location of charsets.jar file to your system classpath.

» Note If you do not set the appropriate charsets.jar file in your Java Runtime Environment, then the MQMonitor agent does not report MQ Events.


User Guide

» Important If you monitor Queue Managers over SSL, then do not use the JRE shipped with WebSphere MQ v6.0.0.0.0. Instead, use the Sun JRE v1.4 or later, or the latest WebSphere MQ JRE.

Obtain third-party libraries

To run the MQMonitor agent, you must obtain third-party JAR files and configure the MQMonitor agent.

PCF JAR file

As of 1 January, 2009, the com.ibm.mq.pcf-6.1.jar file can be downloaded from http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg24000668&loc=en_US&cs=utf-8&lang=en, subject to the accompanying license terms. Unzip the contents of the ms0b.zip archive to any directory of the machine where the MQMonitor agent is installed.

ConfigManagerProxy.jar

If IBM Message Brokers v6.0 or v6.1 is installed on the machine where the MQMonitor agent is installed, you can obtain the ConfigManagerProxy.jar file from the following directory of the IBM Message Broker installation:

For IBM Message Brokers v6.0, go to: <IBM Message Brokers v6.0 Installation Directory>\6.0\classes

For IBM Message Brokers v6.1, go to: <IBM Message Brokers v6.1 Installation Directory>\6.1\classes

j2ee.jar

If IBM Message Broker Toolkit v6.0 or v6.1 is installed on the machine where the MQMonitor agent is installed, you can obtain the j2ee.jar file from the following directory of the IBM Message Broker Toolkit installation:

For IBM Message Broker Toolkit v6.0, go to: <IBM Message Brokers Toolkit v6.0 Installation Directory>\6.0\runtimes\base_v6_stub\lib

For IBM Message Broker Toolkit v6.1, go to: <IBM Message Brokers Toolkit v6.1 Installation Directory>\6.1\runtimes\wsdk\j2ee14

Alternatively, the j2ee.jar file can be found in the /lib directory of the J2EE 1.4 SDK installation. As of 1 January, 2009, J2EE 1.4 SDK can be downloaded from http://java.sun.com/j2ee/1.4/download.html, subject to the accompanying license terms.

http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg24000668&loc=en_US&cs=utf-8&lang=en


http://java.sun.com/j2ee/1.4/download.html



Additional JAR files

For WebSphere MQ v6.x, copy the following JAR files from <IBM WebSphere MQ installation directory>\Java\lib to the .\MQMonitor\lib directory:

com.ibm.mq.jar

com.ibm.mqjms.jar

connector.jar

dhbcore.jar

For WebSphere MQ v7.0, copy the following JAR files from <IBM WebSphere MQ installation directory>\Java\lib to the .\MQMonitor\lib directory:

com.ibm.mq.jar

com.ibm.mqjms.jar

connector.jar

dhbcore.jar

com.ibm.mq.commonservices.jar

com.ibm.mq.headers.jar

com.ibm.mq.jmqi.jar

» Note If you are monitoring the Queue Managers of both WebSphere MQ v6.x and WebSphere MQ v7.0, then use the WebSphere MQ v7.0 library files.

Alternatively, to obtain the above files, you can install the MQ client software.

As of 1 January, 2009, the WebSphere MQ v6.0 client was available for download at https://www14.software.ibm.com/webapp/iwm/web/reg/pick.do?source=wsmqc60&lang=en_US, subject to the accompanying license terms.

» Note Install the WebSphere MQ client on the same machine as the MQMonitor agent.

As of 1 January, 2009, the WebSphere MQ v7.0 client was available for download at http://www-01.ibm.com/support/docview.wss?rs=171&uid=swg24019253&loc=en_US&cs=utf-8&lang=en, subject to the accompanying license terms.

https://www14.software.ibm.com/webapp/iwm/web/reg/pick.do?source=wsmqc60&lang=en_US

https://www14.software.ibm.com/webapp/iwm/web/reg/pick.do?source=wsmqc60&lang=en_US






User Guide

Configure the MQMonitor agent for third-party libraries

To run the MQMonitor agent, you must edit the start script with the location of third-party JAR files on the MQMonitor agent host. For the location of the JAR files, see Obtain third-party libraries on page 17.

To monitor WebSphere MQ v6.0:

Edit the start script, startMQMonitor.bat (Windows) or startMQMonitor.sh (UNIX) to modify the classpath with the actual path of the following files:

com.ibm.mq.jar

connector.jar

PCF JAR file (see PCF JAR file on page 17)

To monitor WebSphere MQ v7.0:


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 above two PCF JAR files. You must provide the path to these two JAR files in the MQMonitor agent start script.

To monitor WebSphere MB:


com.ibm.mq.jar

com.ibm.mqjms.jar


dhbcore.jar

ConfigManagerProxy.jar

j2ee.jar

connector.jar



Configure the MQMonitor agent properties

You can configure the MQMonitor agent by editing the following files:

MQMonitor.properties

MBMonitor.properties

IntroscopeAgent.profile

MQMonitor.properties file

Locate the MQMonitor.properties file in the \MQMonitor\properties directory, and open the file in a text editor.

The MQMonitor.properties file has the following sections:

Specific MQ Data Section on page 21.

MQ Events Section on page 23.

Special Settings Section on page 25.

Advanced Settings Section on page 26.

MQ Trace related properties Section on page 27.

Filters Section on page 30.

The properties file includes brief descriptions of each of the above sections. For detailed descriptions of the above properties, see the following topics.


User Guide

Specific MQ Data Section

In this section, you list the WebSphere MQ configuration instances to monitor WebSphere MQ Queue Managers.

» Important A single Queue Manager instance should be monitored by only one MQMonitor agent.

For each configuration instance, you specify a host name and port. You can also specify channel names, character set, polling delay times, and SSL-related properties.

» Note In references to network resources, DNS names cannot contain underscore characters.

Property Description Value

mq.monitor.list Indicates the comma-separated list of all the WebSphere MQ Queue Manager instances to be monitored.

The ideal format is to list the Queue Manager instances as follows:

<Queue Manager>@<hostname>

Be sure to use the same Queue Manager instance for the rest of the settings in this section.

You can refer to hosts by IP addresses or DNS names.

Example:

If the Queue Manager instance is QM1, then set the property as:

mq.monitor.list=QM1@<hostname>, QM1@<hostname>

Default: none

<Queue Manager>@<Host>.host Indicates the IP address or DNS name (hostname) of the Queue Manager listed in mq.monitor.list

Example:

If the Queue Manager instance is QM1, then set the property as:

QM1@<hostname>.host=localhost

Default: none

<Queue Manager>@<Host>.port Indicates the port numbers of the Queue Manager instances you listed in mq.monitor.list

Example:

QM1@<hostname>.port=5001

Default: 1414



<Queue Manager>@<Host>.channelname

Indicates the Server Connection Channel used to connect to Queue Manager instance being monitored.

Example:

QM1@<hostname>.channelname=SYSTEM.AUTO.SVRCONN

Default: SYSTEM.AUTO.SVRCONNSYSTEM.DEF.SVRCONN (used if the default channel fails)

<Queue Manager>@<Host>.character.set

Indicates the character set ID used by the Queue Manager.

Example:

QM1@<hostname>.character.set=819

For more information on the <Queue Manager>@<Host>.character.set property, see Support non-English character sets in WebSphere MQ on page 6.

Default: 819

<Queue Manager>@<Host>.delaytime

Indicates the delay time (in seconds) between each query for WebSphere MQ data.

Example:

QM1@<hostname>.delaytime=60

Default: 600 seconds (10 minutes)

<Queue Manager>@<Host>.report.static.freq

Indicates the frequency of metric collection for static metrics.

It is used as the denominator of a fraction, 1/n, where n is the number set for the property.

Example:

QM1@<hostname>.report.static.freq=20

Default: 20

The MQMonitor agent reports the results of only 1 out of every 20 queries.

<Queue Manager>@<Host>.ssl Indicates whether SSL is enabled or disabled for communicating with the Queue Manager instance.

Example:

To enable SSL for communication with Queue Manager instance QM1, set:

QM1@<hostname>.ssl=enable

enable or disable

Default: disable

<Queue Manager>@<Host>.channel.ssl.cipherspec

Indicates the CipherSpec used to communicate with the specific Queue Manager instance over SSL.

This value is used by the MQMonitor agent only when the SSL property is enabled.

Example:

QM1@<hostname>.channel.ssl.cipherspec=NULL_MD5

Default: none



User Guide

For information on encrypting the keystore password, see Run mqPwdEncryptor.bat file on page 60.

» Note Using special characters ":" or "=" in the <Host> of the Queue Manager Instances specified in the mq.monitor.list causes the MQMonitor agent to exit.

For example, QM1@2002:9b23:2d7b:0:20f:1fff:fe7e:59c4 is invalid. The MQMonitor agent exits with the following error message:

Failed to load properties file (MQMonitor.properties). Please make sure that there are no special characters like ":" or "=" in the mq.monitor.list property.

MQ Events Section

Use this section to configure MQMonitor agent to receive WebSphere MQ Event messages. Specify the queue names that receive the MQ Event messages on the WebSphere MQ Queue Manager.

truststore.path Indicates the location of a truststore containing certificates for authentication of the WebSphere MQ Queue Manager (WebSphere MQ server).

Provide either an absolute path or a path relative to the properties directory of the MQMonitor agent.

On Windows, backslashes must be escaped.

Example:

truststore.path=C:\\MQMonitor\\key\\truststore.jks

<path name>

keystore.path Indicates the location of the keystore containing certificates for authentication of the MQMonitor agent.

Set this property if you require client authentication.

Example:

keystore.path=C:\\MQMonitor\\key\\keystore.jks

<path name>

keystore.password Indicates the keystore password.

Example:

keystore.password=<password>

<password>




MQ Events include the following:

Event type Events of this type

Queue manager events AuthorityInhibitLocalRemoteStartStop

Channel and bridge events ChannelSSLChannel auto-definition

Performance events Queue depthQueue service interval

» Note This release does not support z/OS-only WebSphere MQ Events.

Enabling MQ Events

To enable WebSphere MQ Events, you must configure WebSphere MQ and the MQMonitor.properties file.

To enable Introscope to display MQ Events:

For each Queue Manager for which you want to view WebSphere MQ Events in Introscope, edit the MQMonitor.properties file and specify the following settings:


<Queue Manager>@<Host>.performance.event.queue

Indicates the queue name of the Performance Event Queue of a given Queue Manager.

SYSTEM.ADMIN.PERFM.EVENT

<Queue Manager>@<Host>.qmgr.event.queue

Indicates the queue name of the Queue Manager Event Queue of a given Queue Manager.

SYSTEM.ADMIN.QMGR.EVENT


User Guide

To configure PowerPack for MQ to view WebSphere MQ Events, see Configure WebSphere MQ to publish events on page 65.

To view MQ Events in the Investigator, see MQ Events on page 79.

Special Settings Section

Use this section to set the limit on the number of metrics to be displayed in the Investigator tree. You can set the display level for the following components of WebSphere MQ:

Queue Managers

Queues

Channels

Channel Initiators (z/OS only)

Page Sets (z/OS only)

Logs (z/OS only)

For each component, the possible values are:

Never—Metrics for the component are neither queried for, nor displayed.

Minimum—a limited set of metrics.

Recommended—a larger set of metrics.

Full—all metrics for this component.

To see which metrics belong to each value set, see Queue Manager metrics on page 146.

<Queue Manager>@<Host>.channel.event.queue

Indicates the queue name of the Channel Event Queue of a given Queue Manager.

SYSTEM.ADMIN.CHANNEL.EVENT

<Queue Manager>@<Host>.event.destructive.get

Indicates whether the event messages are removed from the Event queues after the MQMonitor agent reads them.

Example:

To remove the event messages from the Event queues, set the property as follows:

<Queue Manager>@<hostname>.event.destructive.get=true

true or false

Default:

false




To set the display level for a component:

Add a line to the section that corresponds to the component, referring to the component using its name and host name, and then specify the display level.

WebSphere MQ component

Property name

Queue Manager <Queue Manager>@<Host>.monitor.manager

Queue <Queue Manager>@<Host>.monitor.queue

Channel <Queue Manager>@<Host>.monitor.channel

Channel Initiator <Queue Manager>@<Host>.monitor.channelinitiator

Page Sets <Queue Manager>@<Host>.monitor.pagesets

Logs <Queue Manager>@<Host>.monitor.log

For example, to set the display level to Full for queues that belong to Queue Manager QM1, set the property:

QM1@<hostname>.monitor.queue=full

For more details, see the comments in the properties file.

Advanced Settings Section

In this section, you can redefine the recommended metric set.

The default display settings for MQMonitor agent metrics—Minimum, Recommended, and Full—are listed in the tables in Queue Manager metrics on page 146.

The MQMonitor.properties file also lists the members of the Minimum, Recommended, and Full sets for each component.

WebSphere MQ component Property name

Queue Managers recommended.metrics.manager

Queues recommended.metrics.queue

Channels recommended.metrics.channel

Channel Initiator (z/OS only) recommended.metrics.channelinitiator

Page Sets (z/OS only) recommended.metrics.pagesets

Logs (z/OS only) recommended.metrics.log

» Note By defining the recommended set, you have both the minimum set and the metrics that are included in the recommended set.


User Guide

To redefine the Recommended display set of metrics:

List the metrics using component names and metric names, following the examples given in the properties file. Separate individual metrics with commas.

For example:

recommended.metrics.queue: Queue Name, Queue Type, Cluster Queue Type

In this example, the recommended list has been redefined with only three members; but you get both minimum set of metrics and the three metrics defined in the recommended list.

MQ Trace related properties Section

The MQ Trace-related properties section lets you configure MQ Trace for cross-process transactions. This section has the following properties:


trace.dlq.activity.enabled Set the value to true to enable the MQMonitor agent to read trace data from Dead Letter Queue.

Setting the value to false ensures that the MQMonitor agent does not search the Dead Letter Queue for MQ Trace data.

Example:

To enable the MQMonitor agent to read the Dead Letter Queue, set:

trace.dlq.activity.enabled=true

true or false

Default: true

trace.polling.enabled Indicates whether polling is enabled for the MQMonitor agent to read the final destination queue for MQ Trace data.

Example:

To enable polling, set:

trace.polling.enabled=true

true or false

Default: true



trace.polling.interval Indicates the time period or interval after which the MQMonitor agent checks the final destination queue to see if the message is consumed or not.

Min: 200 milliseconds

Max: 600000 milliseconds (600 seconds/10 minutes)

Default: 1000 milliseconds (1 second).

trace.polling.retry.count Indicates the number of times the MQMonitor agent tries to check the final destination queue for a particular message.

Example:

trace.polling.retry.count=3

Min: 1

Max: 100

Default: 3

trace.dlq.flag.time Indicates the static time that needs to be added to the MQ Trace when messages reach the Dead Letter Queue.

Example:

trace.dlq.flag.time=30

Min: 1 second

Max: 1800 seconds (30 minutes)

Default: 1800 seconds (30 minutes)

handshake.mqagent.id Mandatory. Is the unique identification of the MQMonitor agent for handshaking.

Example:

handshake.mqagent.id=1

Range: 1 to 999999999

handshake.qm.host Indicates the IP address (or DNS name) of the common Queue Manager for handshaking.

Example:

handshake.qm.host=localhost

Default: localhost

handshake.qm.port Indicates the port of the common Queue Manager for handshaking.

Example:

handshake.qm.port=123

Default: 1414



User Guide

For information on cross-process transaction tracing and polling, see Cross-Process Transaction Tracing on page 86.

handshake.qm.channelname Indicates the channel name of the common Queue Manager for handshaking.

Example:

handshake.qm.channelname=SYSTEM.AUTO.SVRCONN

Default: SYSTEM.AUTO.SVRCONN or SYSTEM.DEF.SVRCONN (used if the default channel fails)

handshake.qm.character.set Sets the CCSID character set of the common Queue Manager for handshaking.

Example:

handshake.qm.character.set=819

Default: 819

handshake.qm.ssl Turns the SSL property on or off when the common Queue Manager for handshaking is SSL-enabled.

Example:

To turn off the SSL property of the Queue Manager, set:

handshake.qm.ssl=disable

enable or disable

Default: disable

handshake.qm.channel.ssl.cipherspec Indicates the SSL CipherSpec of the common Queue Manager for handshaking.

Example:

handshake.qm.channel.ssl.cipherspec=NULL_MD5

Default: none

handshake.queue Indicates the queue of the common Queue Manager used for handshaking.

Example:

handshake.queue=CA_WILY_HANDSHAKE

Default: CA_WILY_HANDSHAKE


» Important The handshake.mqagent.id value in the MQMonitor.properties file must be unique across all MQMonitor agents.



Filters Section

Settings in the filters section offer another layer of metric filtering. For example, you can exclude all system queue metrics in favor of user-defined queue metrics. The tables below explain each setting.

» Important If the trace.dlq.activity.enabled property is set to false, then the activity reports can accummulate in the Dead Letter

Queue. To prevent the activity reports from accummulating in the

Dead Letter Queue, see Set the MCA User ID on page 91.


<Queue Manager>@<Host>

.filter.exclude.static

Excludes or includes static metrics while monitoring a given Queue Manager.

Set the value to true to exclude static metrics and report only dynamic metrics in the Investigator tree.

Set the value to false to include static metrics, and report both static and dynamic metrics in the Investigator tree.

Example:

To report both static and dynamic metrics of Queue Manager QM1, set the property:

QM1@<hostname>.filter.exclude.static=false

true or false

Default: false

<Queue Manager>@<Host>. queue.filter.exclude.system

Excludes or includes system queues while monitoring the queues of a given Queue Manager.

Set the value to true to exclude system queues in the Investigator tree.

Set the value to false to include system queues in the Investigator tree.

Note: Does not filter the Dead Letter Queue.

Example:

QM1@<hostname>.queue.filter.exclude.system=true

true or false

Default:true

<Queue Manager>@<Host>.queue.filter.exclude.dynamic

Excludes or includes dynamic queues while monitoring the queues of a given Queue Manager.

Set the value to true to exclude dynamic queues in the Investigator tree.

Set the value to false to include dynamic queues in the Investigator tree.

Example:

QM1@<hostname>.queue.filter.exclude.dynamic=true

true or false

Default:true


User Guide

The settings in the rows below allow you to exclude metrics based on regular expression parameters.

<Queue Manager>@<Host>. queue.filter.includeonly.regex

While monitoring queues of a given Queue Manager, the Queue Manager displays only those queues with names that match the regular expression.

Example:

QM1@<hostname>.queue.filter.includeonly.regex=.*

Default:.*

(no filtering)

<Queue Manager>@<Host>. channel.filter.includeonly.regex

All channels are included by default unless a list is specified with a regular expression.

Example:

To show only those channels that start with test:

QM1@<hostname>.channel.filter.includeonly.regex=test.*

Default:.*

(no filtering)

<Queue Manager>@<Host>. pagesets.filter.includeonly.regex

Filters page sets in the z/OS Queue Manager by the Page Set ID, and displays them in this form:

Usage|Page Sets|PageSet<PageSet_ID>

Example:

To filter page sets, specify the Page Set ID in the regular expression:

QM1@<hostname>.pagesets.filter.includeonly.regex=.*<PageSet_ID>

Default:.*

(no filtering)

<Queue Manager>@<Host>. log.filter.includeonly.regex

Filters logs in the z/OS Queue Manager, and displays them in this form:

Logs|Log Copy Records|Log<Log Copy Record No>

Example:

To filter the logs, specify the Log Copy Record number in the regular expression:

QM1@<hostname>.log.filter.includeonly.regex=*<Log Copy Record No>

Default:.*

(no filtering)




Security settings for CMP, JMS, PCF connections

The following sections describe the minimum security settings needed for the MQMonitor agent for CMP, JMS, and PCF connections.

To set the minimum security needed for CMP Connection for the MQMonitor agent:

Apply the allmqi permission on the Queue Manager of the Configuration Manager as follows:

setmqaut -m <QMGR> -t qmgr -p <user>@<domain> +allmqi

» Note The allmqi permissions sets the inq, set, connect, altusr, setid, setall permissions on the CMP Queue Manager:

Apply the put permission on the SYSTEM.BROKER.CONFIG.QUEUE queue of the CMP Queue Manager as follows:

setmqaut -m <QMGR> -t q -n SYSTEM.BROKER.CONFIG.QUEUE -p <user>@<domain> +put

Apply the get permission on the SYSTEM.BROKER.CONFIG.REPLY queue of the CMP Queue Manager as follows:

setmqaut -m <QMGR> -t q -n SYSTEM.BROKER.CONFIG.REPLY -p <user>@<domain> +get

Create an ACL entry on Configuration manager by using following command.

mqsicreateaclentry <ConfMgrName> -u <UserName> -m <machineName>/<DomainName> -x V -p

In the following example, we allow user_x on machine_y to connect to the configuration manager ConfigMgr.

mqsicreateaclentry ConfigMgr -u user_x –m machine_y -x V -p

Command component Explanation

-x V Gives view authority over Configuration manager to user.

-p Adds access to the Configuration Manager Proxy, also known as “all resources” access control entry.

IBM also requires that your remote user ID be a member of mqm and mqbrkrs security groups in the Configuration Manager machine.

» Note After applying the above security settings, either restart the Queue Manager or do a "refresh security" using the runmqsc command and then restart the Configuration Manager.


User Guide

To set the minimum security needed for JMS Connection for the MQMonitor agent:

Apply allmqi permission on the JMS Queue Manager.

Apply allmqi permission to all JMS pub sub queues (#10) defined in the JMS Queue Manager.

» Note After applying the above security settings, either restart the Queue Manager or do a "refresh security" using the runmqsc command.

You do not need any security settings for PCF inquiry from the MQMonitor agent as it connects to the Queue Manager with MQADMIN as user. If the connecting Queue Manager deploys any security exits, then the MQMonitor agent fails to connect to the Queue Manager.

If the server connection channel is SSL-enabled, then the MQMonitor agent must be configured for SSL parameters. The MCA user ID must not be set or it should be with a user ID that is a part of the mqm group in WebSphere MQ machine.

MBMonitor.properties file

You can configure the PowerPack for MQ to monitor message brokers managed by one configuration manager, and also obtain the broker and message flow statistics for the message brokers.

Locate the MBMonitor.properties file in the \MQMonitor\properties directory, and open the file in a text editor.

The MBMonitor.properties file has the following sections:

CMP Connection Section (mandatory) on page 34.

MQ Connection Section (optional) on page 34.

Statistics Section on page 35.

Broker (JMS) Connection Section on page 35.

Execution Group Section on page 36.

Node Statistics Section on page 37.

Delay Times Section on page 37.

Monitoring Level Settings Section on page 37.

Advanced Settings Section on page 39.

SSL Configuration Section on page 39.



CMP Connection Section (mandatory)

The CMP (Configuration Manager Proxy) machine hosts the broker’s configuration manager. After the CMP connection is established, the Investigator tree displays all Brokers, Execution Groups, and Message Flows under the configuration

manager tree. These properties are mandatory if you want to monitor brokers.


configuration.manager.host

Indicates the CMP machine name or IP address.

Example:

configuration.manager.host=localhost

Default: null

configuration.manager.queue.manager

Indicates the CMP Queue Manager name.

Example:

configuration.manager.queue.manager=WBRK6_DEFAULT_QUEUE_MANAGER

Default: null

configuration.manager.port

Indicates the CMP Queue Manager port.

Example:

configuration.manager.port=2414

Default: null

» Note To turn off MB monitoring, leave the settings in the CMP Connection section empty.

MQ Connection Section (optional)

In a broker domain, the configuration manager and all brokers are associated with WebSphere MQ Queue Managers. As part of Message Broker monitoring, you can monitor the Queue Manager for each broker and configuration manager. This causes the Queue Manager to appear in the Introscope tree twice:

Under the Queue Managers node, as part of WebSphere MQ monitoring

Under the <Broker> that is associated with the Queue Manager

This section has the following property:


mq.broker.list Is the list of brokers for which you would like to see the associated WebSphere MQ objects.

Example:

mq.broker.list=BROKER1,BROKER2

all, none, <broker list>

Default: all


User Guide

The table below lists the different ways you can configure this section.

Value Example Result

all mq.broker.list=all Queue Manager metrics for each broker appears under the broker in the MessageBroker node.

Listing some of the brokers

mq.broker.list=BROKER1,BROKER2

Queue Manager metrics for the listed brokers appear under those brokers in the MessageBroker node.

none mq.broker.list=none No Queue Manager metrics appear under the MessageBroker node.

Statistics Section

In this section, you set the statistics.broker.list property. List the broker names separated by commas. For each of the brokers you list, Introscope displays the Broker statistics and Message Flow statistics.

For example:

statistics.broker.list=BROKER1,BROKER2

By default, the statistics.broker.list property is set to all.

Broker (JMS) Connection Section

In this section, specify the connection properties for the JMS connection.

» Note If the Configuration Manager shares a Queue Manager with a broker, then you do not have to edit this section.

Specify the following connection properties:

Property Description Default

jms.broker.host Indicates the JMS machine name or IP address

null

jms.broker.queue.manager Indicates the JMS Queue Manager name

null

jms.broker.port Indicates the JMS Queue Manager port

null



When you subscribe to only one Broker using JMS, you should get statistics for all brokers in the collective. This does not work if the configuration of the broker domain is not set up correctly. You may encounter a problem where statistics are reported only for the broker that was specified to be connected to for the subscription. This issue can occur due to improper communication within the collective. You can verify the issue by connecting to a different broker in the collective and see if statistics are reported for this broker. If you see statistics for the other broker, then the problem is not with the collection of the statistics but with the intercommunication between the brokers in the collective.

To address this issue, ensure that the deployment of the pub/sub topology was successful.

To redeploy the topology, issue the following IBM command:

mqsideploy -i <machine> -p <port> -q <queue manager> -l –m

where machine, port and Queue Manager are those of the configuration manager.

For more details, see the IBM documentation. You may have to contact IBM if the problem persists.

Execution Group Section

In this section, list the Execution Groups for which statistics need to be collected. Separate the execution groups by commas in the <broker name>.executiongroup property.


<broker name>.executiongroup

Indicates the Execution Groups on the broker for which statistics are reported.

Example:

If the broker name is broker1, then se the property as:

broker1.executiongroup=ExecutionGroup1,ExecutionGroup2

all, list of execution groups

» Note Any broker you list in this section must also be listed in the statistics.broker.list in the previous section.

» Note If the statistics.broker.list set to all, then the MQMonitor agent reports all Execution Groups and ignore this section.


User Guide

Node Statistics Section

Each message flow has several nodes. To view the statistics for the user-specified node types in the Investigator, set the node.type.list property. Separate the node type names with commas. For example:

node.type.list= JniNode,MQOutputNode

The MBMonitor.properties file contains a list of possible node types.

You can also specify the value as all to show statistics for all nodes in the message flow.

node.type.list=all

By default, the MQMonitor agent reports statistics for the JniNode.

Delay Times Section

In this section, specify a time interval between CMP queries by editing the static.delay.time setting.

See the information for the Delay Times Section in the MBMonitor.properties file for:

minimum and maximum allowable settings

default/recommended setting

examples

Monitoring Level Settings Section

This section lets you control the number of metrics reported by the PowerPack for MQ reports for Message Broker Monitoring. You can specify different monitoring levels for metrics of Message Flow Statistics and Broker Statistics.

You can set the monitoring level for both the statistics to the following values:

Never—No metrics for Message Flow Statistics and Broker statistics are requested from Message Broker.

Minimum—Only few metrics which mainly participate in Typeviews or metrics essential to triage WebSphere MB problems are reported to Introscope.

Recommended—All metrics from minimum level plus few extra metrics are reported to Introscope.

Full—All possible metrics are reported to Introscope.



» Note By default, the monitoring level is set to Recommended. The metric set for minimum and full monitoring levels are pre-defined, and you cannot change them. The metrics in the Recommended monitoring level can be configured by by specifying a metric list in the recommended.metrics.messageflow.statistics and recommended.metrics.broker.statistics properties of the MBMonitor.properties file.

You can use the <broker name>.messageflow.statistics property to specify the monitoring level for message flow statistics.

For example, for brokers, BROKER1 and BROKER2:

BROKER1.messageflow.statistics = full

BROKER2.messageflow.statistics = minimum

You can use the <broker name>.broker.statistics property to specify the monitoring level for broker statistics that are reported for a broker.

BROKER1.broker.statistics = recommended

BROKER2.broker.statistics = never

If statistics.broker.list property is set to a list of brokers, then all the brokers in the list can set the monitoring level to a value other than the default level.

» Note We recommend setting the monitoring level to the default value.

For example,

statistics.broker.list = BROKER1,BROKER2

BROKER1.broker.statistics = recommended

BROKER2.broker.statistics = never

BROKER1.messageflow.statistics = full

BROKER2.messageflow.statistics = minimum

» Note If you use a broker name that is not included in the statistics.broker.list property, then the broker name is ignored.


User Guide

Advanced Settings Section

You can use redefine the recommended monitoring level for the Message Flow

and Broker Statistics using the properties in this section.


recommended.metrics.messageflow.statistics

Comma-separated list of metrics for Message Flow Statistics, at the recommended monitoring level.

Example:

recommended.metrics.messageflow.statistics=MQ Errors Total, CPU Processing Time

null

recommended.metrics.broker.statistics

Comma-separated list of metrics for Broker Statistics at the recommended monitoring level.

Example:

recommended.metrics.broker.statistics=Bytes Dropped Total, Bytes Queued Total

null

By setting the above two properties, you can only redefine the metric list for the recommended level, and not for other levels of monitoring. The metrics that appear in the Investigator tree are the set of metrics at the minimum level and the redefined metrics at the recommended level. Unlike properties in the Monitoring Level Settings, these properties cannot be set for each broker.

SSL Configuration Section

The MBMonitor agent establishes two types of connections—CMP and JMS. You must set the properties for both the connections to enable SSL connection for CMP and JMS.


cmp.ssl Indicates whether the SSL connection for CMP is enabled or not.

Example:

To enable the SSL connection for CMP, set the property as:

cmp.ssl=enable

enable or disable

Default: disable

jms.ssl Indicates whether the SSL connection for the JMS broker is enabled or not.

Example:

To enable the SSL connection for the JMS broker, set the property as:

jms.ssl=enable

enable or disable

Default: disable



» Note Run mqPwdEncryptor.bat only if client authentication is required. The values that you provide for keystore.path and keystore.passsword in the mqPwdEncryptor.bat file for the SSL key repository, get automatically populated in the corresponding properties of the MBMonitor.properties file. For information on the mqPwdEncryptor.bat file, see Run mqPwdEncryptor.bat file on page 60.

This completes your editing of the MBMonitor.properties file.

cmp.connection.ssl.cipherspec

Indicates the CipherSpec for the CMP SSL connection.

Example:

To specify the CipherSpec for the CMP Queue Manager, set the property as:

jms.connection.ssl.cipherspec=NULL_MD5

SYSYTEM.BRK.CONFIG (for CMP)SYSTEM.DEF.SVRCONN (for JMS)

truststore.path Indicates the truststore path of the SSL key repository, used for both CMP and JMS SSL connections.



Example:


<path name>

keystore.path Indicates the keystore path of the SSL key repository, used for both CMP and JMS SSL connections.



Example:

keystore.path=C:\\MQMonitor\\key\\keyststore.jks

<path name>

keystore.password Indicates the keystore password of the SSL key repository, used for both CMP and JMS SSL connections.



Example:


<password>



User Guide

To obtain Message Broker metrics, you must create JMS queues, as described in the following section.

To create JMS queues that use the JMS (Java Messenging Service) protocol:

1 Identify the Queue Manager where you have to define JMS queues.

If the Configuration Manager shares its Queue Manager with one of its brokers, this will be the Configuration Manager’s Queue Manager.

If a Queue Manager is not shared between the Configuration Manager and its broker, you can create the JMS queue on any of the brokers in a publish/subscribe collective.

2 Find the file MBMonitorJMSQueues.mqsc in the \MQMonitor\properties directory where you uncompressed the MQMonitor agent archive. The file (viewable in a text editor) contains a series of MQSC commands.

3 Issue the following command on your Message Broker host. This runs all the commands in the MBMonitorJMSQueues.mqsc file.

runmqsc queueMgr_name < MBMonitorJMSQueues.mqsc

where queueMgr_name is the name of the Queue Manager you identified in an earlier step.

IntroscopeAgent.profile file

Specify the connection properties for the Introscope Enterprise Manager (EM) to which you want to send the metrics reported by the MQMonitor agent. You can also specify the properties required for metric aging in the IntroscopeAgent.profile file.

To specify the EM:

1 Open the IntroscopeAgent.profile from the MQMonitor\properties directory.

2 Find the section Enterprise Manager Locations and Names.

3 Specify the following connection properties:


introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT

Indicates the EM host name or IP address.

localhost

introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT

Indicates the EM port. 5001

4 Save and close the file.



To add properties for Metric Aging:

1 Open the IntroscopeAgent.profile file and set the values of the properties as shown in the following table:


introscope.agent.metricAging.turnOn Enables or disables the MQMonitor agent’s metric aging.

true

introscope.agent.metricAging.heartbeatInterval

Sets the time interval when metrics are checked for removal (in seconds).

12600

introscope.agent.metricAging.dataChunk Sets the number of metrics that are checked during each interval. If the value is 500, then each of the 500 metrics is checked to see if it is a candidate for removal.

500

introscope.agent.metricAging.numberTimeslices

Sets the number of intervals to check for the metric without any new data before making it a candidate for removal.

100

introscope.agent.metricAging.metricExclude.ignore.0

Lists the metrics that must not be removed. Add the metric name or metric filter to the list.

Example:

To prevent Local_Queue Metrics from graying out, set the property as follows: introscope.agent.metricAging.metricExclude.ignore.0= *Local_Queue*

Threads*

Ensure that you set the proper value for the properties in the IntroscopeAgent.profile file. The heartbeatInterval depends upon the maximum polling interval specified using the delaytime property in the MQMonitor.properties file and the static.delaytime property in the MBMonitor.properties file. We recommend that you set it to at least 4 times the maximum default interval. In case of aggregated metrics, the aggregated metrics gray out if all the linked metrics gray out. For example, if the aggregated metric AG1 consists of agent metrics a1, a2, and a3, and data is available for a1 only, then AG1 does not gray out.

Configure WebSphere MQ for MQ Trace 43

User Guide

» Note The MQMonitor agent must push any metric data (if available) related to WebSphere MQ or WebSphere MB within the time specified in the heartbeatInterval property. So, the delay time must always be less than the heartbeatInterval. The default value for introscope.agent.metricAging.heartbeatInterval property is 12600 seconds. You can set the property to its default value or higher. If you set the property to a value lesser than 12600 seconds, then the system uses the default value only.

2 Save and close the file.

This completes the configuration tasks for the MQMonitor agent.

» Note For more information on the metric aging properties, see the Introscope Java Agent guide.

Run the MQMonitor agent

To start the MQMonitor agent on Windows or UNIX:

1 Make sure your JAVA_HOME variable is set in system properties.

2 In the \MQMonitor directory, execute the startMQMonitor.bat (Windows) or startMQMonitor.sh (UNIX) file.

The WebSphere MQ and/or WebSphere MB tree appears in the Introscope Workstation tree under the node WebSphere MQ and Message Broker Agent. For information on reading and understanding these metrics, see chapter 3, Viewing Data Using PowerPack for MQ on page 67.

To stop the MQMonitor agent on Windows or UNIX:

In Windows, close the command prompt window from where you executed the startMQMonitor.bat file. In UNIX, execute the stopMQMonitor.sh file from the \MQMonitor directory.

When you stop the MQMonitor agent, all the MQMonitor agent processes also stop.

Configure WebSphere MQ for MQ TraceAfter you install and configure the MQMonitor agent, you can use PowerPack for MQ to perform cross-process transaction tracing to obtain and analyze WebSphere MQ performance information. For information about how to configure WebSphere MQ to perform cross-process transaction tracing, see Configure the WebSphere MQ System for trace on page 87.



Upgrade the MQMonitor agentThe following two sections describe how you can upgrade the earlier versions of the MQMonitor agent.

To upgrade the EPAMQMonitor agent in PowerPack for MQ v4.1.x:

1 Copy the EPAMQMonitor.properties file of PowerPack for MQ v4.1.x to the MQMonitor\properties directory of PowerPack for MQ v8.x.

2 Start the MQMonitor agent.

This converts and upgrades the PowerPack for MQ v4.1.x properties file to PowerPack for MQ v8.x properties file. The PowerPack for MQ v4.1.x properties file is backed up under the MQMonitor\properties\backup directory.

To upgrade the EM component for PowerPack for MQ v4.1.x:

1 Back up the following files from the <Introscope Home>/config/modules directory to any other location:

PPWebsphereMQ_MQSeries_ManagementModule.jar

PPWebsphereMQ_JavaConnectors_ManagementModule.jar

PPWebsphereMQ_EpaMQMonitor_ManagementModule.jar

2 Install the current version of PowerPack for MQ EM component.

To upgrade the EPAMQMonitor agent in PowerPack for MQ v5.x:

1 Copy the MQMonitor.properties and MBMonitor.properties files of PowerPack for MQ v5.x to the MQMonitor\properties directory of PowerPack for MQ v8.x.


This converts and upgrades the PowerPack for MQ v5.x properties file to PowerPack for MQ version v8.x properties file. The PowerPack for MQ v5.x properties file is backed up under the MQMonitor\properties\backup directory.

To upgrade the EM component for PowerPack for MQ v5.x:

1 Back up the following files from the <Introscope Home>/config/modules directory to any other location:

WMBManagementModule.jar

WMQJavaConnectorsManagementModule.jar

WMQManagementModule.jar

WMQ_MB_JavaConnectorManagementModule.jar

2 Install the current version of PowerPack for MQ EM component.

» Note If the <Host> of the Queue Manager instances specified in the mq.monitor.list has special characters like ":" or "=", then it is replaced with "_" for all the instances.

If the <Host> was QM1@2002:9b23:2d7b:0:20f:1fff:fe7e:59c4 before the upgrade, then, after the upgrade, it would change to: QM1@2002_9b23_2d7b_0_20f_1fff_fe7e_59c4

Upgrade the MQMonitor agent 45

User Guide



(Optional) Install MQMonitor agent as a Windows Service

To run the MQMonitor agent on a Windows machine as a Windows Service, go to the MQMonitor\Window Service directory. The directory structure is as follows:

Directory Files

\Windows Service RegisterMQService.batDeregisterMQService.bat

\Windows Service\jsw-3.2.3\bin InstallTestWrapper-NT.batPauseTestWrapper-NT.batResumeTestWrapper-NT.batStartTestWrapper-NT.batStopTestWrapper-NT.batTestWrapper.batTestWrapperNoWrapper.batUninstallTestWrapper-NT.batwrapper.exe

\Windows Service\jsw-3.2.3\conf wrapper.conf

\Windows Service\jsw-3.2.3\legal\jsw-3.2.3

license.txt

\Windows Service\jsw-3.2.3\lib wrapper.dllwrapper-3.2.3.jarwrappertest-3.2.3.jar

To register the MQMonitor agent as a Windows Service:

1 Edit the wrapper.conf file to suit any local requirements, such as the <Path for JAVA>.

2 Run the RegisterMQService.bat file.

The MQMonitor agent is now registered as a Windows Service.

To monitor WebSphere MB when MQMonitor agent is registered as a Windows Service:

1 Open the Windows Service properties of the MQMonitor agent.

2 In the Log on tab, change the Log on as credentials to that of an authorized user of WebSphere MB.

3 Apply the changes and start the service.

The MQMonitor agent is now configured to monitor all WebSphere MB instances.

Install and configure MQ Java Connectors 47

User Guide

To run the MQMonitor agent as a Windows Service:

1 Click Start > Run.

The Run dialog box appears.

2 Type Services.msc in the Open text box and click OK.

A list of all Windows services appears.

3 Right-click MQ Monitor and click Start.

The MQMonitor agent starts reporting metrics for the configured WebSphere MQ and WebSphere MB instances.

To deregister the MQMonitor agent as a Windows Service:

Double-click the DeregisterMQService.bat file.

Install and configure MQ Java ConnectorsMQ Java Connectors monitor various Connector, JMS classes, and methods that communicate with WebSphere MQ.

To install and configure MQ Java Connectors:

1 Extract the MQ Java Connectors files on page 47.

2 Configure MQ Java Connectors on page 49.

3 Configure ErrorDetector on page 53.

4 Configure JCA Connection Pool on page 55.

The following sections describe these steps in detail.

Extract the MQ Java Connectors files

The names of the MQ Java Connectors archive files differ based on the platform. The archive file names for the Windows, UNIX, and z/OS platforms are listed in the following table:

Operating system Archive file name

Windows PowerPackForWebSphereMQv8.1Agent.windows.zip

UNIX PowerPackForWebSphereMQv8.1Agent.unix.tar

z/OS PowerPackForWebSphereMQv8.1Agent.zos.tar



Based on the platform, extract the appropriate MQ Java Connectors archive to the /wily directory on your application server. The contents of the archive are as follows:

/ext

MQNameFormatter.jar

InstallAgent.txt

MQAppSupport.jar

PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbd

PowerPackForWebSphereMQ_v8.1_ErrorDetector.pbd

PowerPackForWebSphereMQ_JavaConnectors_old.pbd

PowerPackForWebSphereMQ_v8.1_InstanceCounts.pbd

PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl

MQAgent.properties

(Optional) Configure application server when Java 2 security is enabled

If Java 2 security is enabled on the application server, then you need to update the server.policy and java.policy files.

For example, to configure WebSphere Application Server v6.x, edit the server.policy and java.policy files as follows:

Add the following lines in the server.policy file located at <WebSphere home>\profiles\<profile name>\properties:

// WebSphere optional runtime classesgrant codeBase "file:${was.install.root}/-" {permission java.lang.RuntimePermission

"accessDeclaredMembers", "read";permission java.lang.RuntimePermission "getClassLoader",

"read";permission java.lang.RuntimePermission "modifyThread", "read";permission java.lang.RuntimePermission "modifyThreadGroup",

"read";permission java.lang.reflect.ReflectPermission"suppressAccessChecks", "read";permission java.util.PropertyPermission"java.security.policy", "read";};


User Guide

Add the following lines in the java.policy file located at <WebSphere home>\java\jre\lib\security):

grant {permission java.io.FilePermission "C:/IBM/WebSphere/wily/

MQAgent.properties", "read";};

Configure MQ Java Connectors

The following instructions cover the Windows, UNIX, and z/OS platforms.

1 Configure the Introscope agent on the application server.

» Note The Introscope agent is a part of the Introscope product and must be obtained from the Introscope software download site.

2 Extract the MQ Java Connectors archive to the /wily directory of the Introscope agent.

3 In the /wily directory of the Introscope agent:

a Open the IntroscopeAgent.profile file in a text editor.

b Find the introscope.autoprobe.directivesFile property and add the PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl file to the list of files in that property.

PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl lists the PBD files to be enabled.

c Edit the PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl file to enable any PBD files. For information on enabling PBD files, see To enable or disable PBD files: on page 54.

» Important Do not remove any ProbeBuilder list files (.pbl) existing in the property.

» Note The PowerPackForWebSphereMQ_v8.1_InstanceCounts.pbd file provides the number of instances of MQ Java Connector classes. PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbd adds support for PowerPack for MQ v8.x metrics and PowerPackForWebSphereMQ_JavaConnectors_old.pbd adds support for PowerPack for MQ v4.1.x metrics. You must note that the PowerPackForWebSphereMQ_JavaConnectors_old.pbd file is specific to PowerPack for MQ v4.1.x, and you cannot enable both the PBD files at the same time as the tree structure in the Investigator varies from PowerPack for MQ v4.1.x to v8.x.

4 Save the IntroscopeAgent.profile file.

5 Restart the application server.



Sharing the wily folder across multiple MQ Java Connector agents

If you want to use the same \wily folder across multiple MQ Java Connector agents, then make multiple copies of the MQAgent.properties file with names for the agents, and pass the -Dcom.wily.mqpp.mqagentProfile=<path to the wily folder>\MQAgent.properties along with other JVM arguments at the Java command for running the agents.

Example:

For Java versions 1.5 and above:

–javaagent:<path to the wily folder>\Agent.jar -Dcom.wily.introscope.agentProfile=<path to the wily folder>\IntroscopeAgent.profile -Dcom.wily.mqpp.mqagentProfile=<path to the wily folder>\MQAgent1.properties

For versions prior to Java 1.5:

-Xbootclasspath/p:<path to the wily folder>\connectors\AutoProbeConnector.jar;<path to the wily folder>\Agent.jar -Dcom.wily.mqpp.mqagentProfile=<path to the wily folder>\MQAgent1.properties -Dcom.ibm.websphere.classloader.plugin=com.wily.introscope.api.websphere.WASAutoProbe -Dcom.wily.introscope.agentProfile=<path to the wily folder>\IntroscopeAgent.profile

MQAgent.properties file

The MQAgent.properties file lets you configure handshake between the MQ Java Connector agents and the MQMonitor agents for cross-process transactions.


User Guide

The following table describes the properties of the MQAgent.properties file:


mqmonitor.mqagent.id.list Lists the value of the handshake.mqagent.id property of all the MQMonitor agents that are involved in a cross-process transactions trace.

Separate the names by comma.

Set this property to prevent unnecessary overload on WebSphere MQ, if cross-process transaction is enabled.

Example:

mqmonitor.mqagent.id.list=1, 2

Default: none

If this value is null, then the handshaking process to check the availability of running MQMonitor agents does not occur, and the WebSphere MQ transaction trace is set to on.

handshake.mqagent.id Mandatory. Is the unique identification of the agent.

Set this property to prevent unnecessary overload on WebSphere MQ if mqmonitor.mqagent.id.list is not blank.

Example:

handshake.mqagent.id=1

Range: 1 to 999999999

Default: none

If the value is null, then the handshake process does not start.

handshake.qm.host Indicates the IP address (or DNS name) of the common Queue Manager.

Example:

handshake.qm.host=localhost

Default: localhost

handshake.qm.port Indicates the port of the common Queue Manager.

Example:

handshake.qm.port=123

Default: 1414

handshake.qm.channelname Indicates the channel name of the common Queue Manager to be used for connections.

Example:

handshake.qm.channelname=SYSTEM.AUTO.SVRCONN

Default: SYSTEM.AUTO.SVRCONN

SYSTEM.DEF.SVRCONN (used if the default channel fails)

handshake.qm.character.set

Sets the CCSID character set of the common Queue Manager.

Example:

handshake.qm.character.set=819

Default: 819



handshake.qm.ssl Turns the SSL property on or off when the common Queue Manager is SSL-enabled.

Example:

To turn off the SSL property of the Queue Manager, set:

handshake.qm.ssl=disable

enable or disable

Default: disable

handshake.qm.channel.ssl.cipherspec

Indicates the SSL CipherSpec of the common Queue Manager.

XXXXX_XXXXX

Default: none

handshake.queue Indicates the queue used for handshaking among all WebSphere MQ agents.

Default: CA_WILY_HANDSHAKE

truststore.path Indicates the location of a truststore containing certificates for authentication of WebSphere MQ server.

Provide either an absolute path or a path relative to the properties directory of MQMonitor agent.


Example:


<path name>

keystore.path Optional. Is the location of the keystore.

Set this property if you require client authentication.

Provide either an absolute path or a path relative to the properties directory of MQMonitor agent.


Example:

keystore.path=C:\\MQMonitor\\key\\keystore.jks

<path name>



User Guide

» Important The handshake.mqagent.id value in the MQAgent.properties file must be unique across all MQ Java Connectors. The handshake properties must be the same in both the MQAgent.properties and MQMonitor.properties files of all agents in PowerPack for MQ.

Configure ErrorDetector

You can use Introscope’s ErrorDetector feature to read WebSphere MQ errors in the Introscope Investigator.

keystore.password Optional. Is the keystore password.

Example:


<password>

mqtracing.exclude.queues.regex

Optional. Indicates one or more queues of a particular Queue Manager that are filtered from transaction tracing.

Note: This property filters the first queue where WebSphere MQ Put or JMS Send operations occur along with the subsequent correlated traces. This also filters the traces for the WebSphere MQ Get or JMS Receive operations.

Example:

To filter all the queues containing the word "SYSTEM" of the Queue Manager QM1 from transaction tracing, set the property:

QM1.mqtracing.exclude.queues.regex=.*SYSTEM.*

To filter all the queues of the Queue Manager QM1 from transaction tracing, set the property:

QM1.mqtracing.exclude.queues.regex=.*

To filter all the queues except queues TRACE.QUEUE1 and TRACE.QUEUE2 of the Queue Manager QM1 from transaction tracing, set the property:

QM1.mqtracing.exclude.queues.regex=(?!((.*TRACE.QUEUE1.*)|(.*TRACE.QUEUE2.*))).*

Default: none (no filtering)




ErrorDetector allows application support personnel to detect and diagnose errors that prevent you from completing web transactions. Enabling the ErrorDetector allows Introscope to show application errors on the Application Server that uses WebSphere MQ as the message queueing middleware.

To enable ErrorDetector, you must configure the Introscope Enterprise Manager host and the application server where MQ Java Connectors is installed.

On the Introscope EM host, the ErrorDetector depends on a JAR file, com.wily.introscope.errordetector_8.0.0.jar, that is part of the Introscope ErrorDetector software.

To enable ErrorDetector on the Introscope EM:

1 Extract the com.wily.introscope.errordetector_8.0.0.jar file from the ErrorDetector package and copy it to the <Introscope Home>/product/enterprisemanager/plugins directory.

2 Restart the EM.

To enable or disable PBD files:

1 Open the file PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl in a text editor.

2 Comment or uncomment one or more PBD files.

For example:

######################## Directives Files# ================# One directives file name per line. Relative names# are resolved against the location of this file.

PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbdPowerPackForWebSphereMQ_v8.1_ErrorDetector.pbd#PowerPackForWebSphereMQ_v8.1_InstanceCounts.pbd#PowerPackForWebSphereMQ_JavaConnectors_old.pbd


User Guide

Configure JCA Connection Pool

The MQ Java Connectors files include the MQAppSupport.jar file, that enables WebSphere Application Server to report WebSphere MQ Connection Pool metrics.

» Note Applicable only for the WebSphere Application Server.

To install and configure the JCA Connection Pool in the WebSphere Application Server:

1 Check that the MQAppSupport.jar file has been extracted to the /wily directory of the application server host.

2 In WebSphere, create and configure a new service that reports connection pool metrics:

a Open the WebSphere Admin Console.

» Note These steps are based on WebSphere v6.1. For other versions of WebSphere, the steps may be slightly different.

b In the left pane, expand the Servers node.

c Under the Servers node, select Application Servers.

d In the right pane, select the server where you are creating a service.

e In the Admin Console menu, select Administration > Custom Services.

f Create a new service.

g Ensure Enable service at server startup is checked.

h Enter the following information under General Properties.

classname:

com.wily.powerpack.websphereMQ.agent.JCAConnectionPool.IntroscopeMQCustomService

DisplayName: Enter any string. Introscope uses this value for the label of the service.

ClassPath: Enter the full file system path to the MQAppSupport.jar file in the /wily directory of the application server host. For example:

C:\Program Files\WebSphere\AppServer\Wily\MQAppSupport.jar

i Click OK.



3 Enable PMI settings in the WebSphere Administrative Console:

a In the left pane, under Monitoring and Tuning, select Performance Monitoring Infrastructure (PMI).

b In the right pane, click on the server for which you are configuring the PMI.

c Click the Configuration tab.

d Check the Enable Performance Monitoring Infrastructure (PMI) box.

e Under Currently monitored statistic set, select Custom.

f Under Custom, click JCA Connection Pools.

g In the right pane, select the following attributes to be monitored:

PercentUsed

WaitTime (in WebSphere Application Server v5.1.1, this attribute is called AvgWaitTime)

PoolSize

WaitingThreadCount (in WebSphere Application Server v5.1.1, this attribute is called ConcurrentWaiters)

PercentMaxed

You can view the selected metrics in Introscope. See JCA node metrics on page 198.

h With the attributes selected, click Enable.

i Click OK.

4 Restart the WebSphere Application Server.

Install Management Modules and extensionsThe Management Modules contain pre-configured extensions for the Introscope Investigator and Console:

Dashboards, alerts, and other graphical displays to show WebSphere MQ and WebSphere MB metrics in graphical form in the Introscope Console and Investigator tools.

Calculators and Enterprise Manager (EM) extensions that aggregate metric data from more than one WebSphere MQ or WebSphere MB component.

» Note These instructions cover the Windows, UNIX, and z/OS platforms.

Additional Information 57

User Guide

To install the Management Modules:

1 Extract the Management Module archive to your Introscope EM home directory.

2 Copy the following Management Module JAR files to the <Introscope Home>/config/modules directory in the Introscope Enterprise Manager’s installation directory.

MQPowerPackHealth.jar

WebSphere_MQ_Client_And_Server.jar

WMBManagementModule.jar

3 Restart the Introscope Enterprise Manager.

For information on the Management Modules, see Management Modules on page 109.

Additional InformationThis section provides additional information such as upgrading PowerPack for MQ, configuring SSL, configuring WebSphere MB, and creating JMS queues. This section includes the following topics:

Configure SSL on page 58.

Configure WebSphere MB on page 64.

Configure WebSphere MQ to publish events on page 65.

Turn on Queue Monitoring on page 66.



Configure SSL

Before you begin the SSL configuration, you must note the following:

The Server mentioned in this procedure is the IBM MQ Queue Manager and the Client is PowerPack for MQ.

The procedure assumes the usage of IBM Key Management Utility (IKEYMAN) tool for setting up the SSL repositories and creation or addition of certificates. See Generate Personal Certificates on page 63 for more information on Certificates.

The SSL Key repository is termed as keystore and truststore on the Client depending on its usage.

How to set up Client-Server communication over SSL

The process for setting up client-server communication over SSL is as follows:

Set up SSL key repository and create self-signed certificate on the Server.

Set up truststore on the Client and add the Server’s self-signed certificate to it.

Set up keystore on the Client (if client authentication is needed by the Server) and create self-signed certificate for the Client. The Client requires the keystore password during SSL communication with the Server.

Extract the Client’s certificate and add it to the Server’s SSL Key Repository.

Select an SSL CipherSpec for the Server Connection Channel on the Server.

Configure the Client using the SSL related properties in the MQMonitor.properties or MBMonitor.properties files.

Start the Client.

This initiates communication with Server CipherSpec. The Server and Client start exchanging information on the Server Connection channel over SSL.

To establish the SSL communication between the client and server, you must configure both the client and the server. The following sections describe the procedures for configuring the client and server.

Configure the Server

To configure the server, perform the following steps:

Set up SSL key repository with the Key database type as “CMS”.

For example:

On Windows, the Queue Managers SSL key repository is located at <WebSphere MQ home>\qmgrs\<Queue Manager Name>\ssl and the SSL key repository name is key.kdb.


User Guide

Generate the certificate. You can either generate a self-signed certificate using the IKEYMAN tool or any personal certificate, and add it to the SSL key repository. See Generate Personal Certificates on page 63 for more information on Certificates.

Add the Client certificate (if client authentication is needed] to the server’s SSL key repository.

» Note Client Certificate is got from the 2nd step in the Configuring the Client > Setup keystore section.

Set the SSL CipherSpec on the server connection channel. Be sure to note this value as you must provide this information in the MQMonitor.properties and MBMonitor.properties files.

Configure the Client

To configure the client, perform the following steps:

Step 1 Set up truststore.

Step 2 Set up keystore.

Step 3 Run mqPwdEncryptor.bat file.

Step 4 Configure the MQMonitor.properties file.

Step 5 Configure the MBMonitor.properties file.

Set up truststore

1 Set up truststore with the key database type as “JKS”.

For example:

You can name the truststore as truststore with the extension .jks.

2 Add the Server certificate to the truststore. Server Certificate is got from the 2nd step in the Configuring the Server section.

Set up keystore

This section is needed only when the Server asks for Client Authentication.

1 Set up keystore with the Key database type as JKS. Make a note of the password needed to open the keystore.

For example, you can name the keystore as keystore with the extension .jks.

2 Generate the certificate - either self-signed certificate using IKEYMAN tool or any personal certificate and add it to the keystore. See Generate Personal Certificates on page 63 for more information on Certificates.



Run mqPwdEncryptor.bat file

Run the mqPwdEncryptor.bat file if client authentication is required by the server. The purpose of this command line utility is to set keystore location and keystore password for the Client (PowerPack for MQ) to communicate over SSL. Perform the following steps:

1 Double-click mqPwdEncryptor.bat.

The utility opens and prompts you for the keystore location.

2 Enter the path for the keystore in the command line.

» Note The utility provides a maximum of three attempts to enter the correct path, and then quits.

3 Enter the keystore password.

The utility prompts for the properties file (either MQMonitor.properties or MBMonitor.properties) where the keystore location and password should be updated.

4 Enter the absolute path for the properties file (either MQMonitor.properties or MBMonitor.properties) that you want to update, and press Enter.

The utility encrypts the keystore password and adds it to the properties file provided in the previous step.

When you run the MQMonitor agent, the encrypted password is decrypted and used by the MQMonitor agent.

» Important Always try to make use of the same truststore and keystore references for a given MQMonitor agent. In other words, if you configure both the MQMonitor.properties and MBMonitor.properties files, then the references to truststore and keystore should be the same.

Configure the MQMonitor.properties file

The MQMonitor agent uses SYSTEM.AUTO.SVRCONN as the default server connection channel to connect to the WebSphere MQ Queue Manager. If the connection is unsuccessful using the SYSTEM.AUTO.SVRCONN channel, then the MQMonitor agent uses SYSTEM.DEF.SVRCONN as the alternative channel.

For enabling SSL, you must edit the following property:

<Queue Manager>@<Host>.ssl

If a Queue Manager is SSL-enabled, then indicate the same by enabling the property. For example, [email protected]=enable


User Guide

By default, the following property is disabled:

<Queue Manager>@<Host>.channel.ssl.cipherspec

The MQMonitor agent verifies this value if the SSL property is enabled for the monitored Queue Manager. This value is the CipherSpec with which the server connection channel on the particular Queue Manager has been configured.

For example:

[email protected]= NULL_MD5 where NULL_MD5 is the name of the CipherSpec that is used and QM1 is the Queue Manager.

Certificates of all the Queue Managers needs to be placed in the truststore. Edit the truststore.path property to point the MQMonitor agent to the truststore location :

» Note On UNIX, use the forward slash in the path as separator. You can use the same on Windows also. However, if the backward slash is used on Windows, then it should be escaped.

For example,

truststore.path = C:\\MQMonitor\\keys\\truststore.jks is correct.

truststore.path = C:/MQMonitor/keys/truststore.jks is correct.

keystore.path and keystore.password

The personal certificate of client is placed in keystore. We need to provide keystore location and also its password in MQMonitor.properties file as follows:

For example:

keystore.path = C:/MQMonitor/keys/keystore.jks

keystore.password = <encrypted password>

» Note You need not edit these properties directly in the MQMonitor.properties file. Instead, you must run the mqPwdEncryptor.bat file. The mqPwdEncryptor.bat utility updates the keystore.path property with the path (with the forward slash as separator) provided by you.



Configure the MBMonitor.properties file

The MBMonitor establishes two types of connections—CMP and JMS.

The default system server connection channel used by the MQMonitor agent to establish connection with Configuration Manager’s Queue Manager is SYSYTEM.BRK.CONFIG (CMP). For the JMS Broker’s Queue Manager, the default system server connection channel is SYSTEM.DEF.SVRCONN (JMS).

» Note In MBMonitor.properties file, you must mention the configuration manager’s Queue Manager and the JMS broker’s Queue Manager information to establish the CMP or JMS connections.

You must set the following properties for both the connections to enable SSL connection for CMP and JMS.

cmp.ssl = enable

jms.ssl = enable

By default, both the properties are disabled.

cmp.connection.ssl.cipherspec

MQMonitor agent verifies this value if the SSL property is enabled for the Configuration Manager’s Queue Manager. This value is the CipherSpec with which the server connection channel on the particular the Configuration Manager’s Queue Manager has been configured.

For example,

cmp.connection.ssl.cipherspec= NULL_MD5 where NULL_MD5 is the CipherSpec that is used.

jms.connection.ssl.cipherspec

The MQMonitor agent verifies this value when the SSL property is enabled for the JMS Broker’s Queue Manager. This value is the CipherSpec with which the sever connection channel on the particular the JMS Broker’s Queue Manager has been configured.

For example,

jms.connection.ssl.cipherspec= NULL_MD5 where NULL_MD5 is the CipherSpec that is used.

truststore.path


User Guide

You must place the certificates of the Configuration Manager’s Queue Manager and JMS Broker’s Queue Manager in the truststore. Edit the following property to point MQMonitor agent to truststore location :

» Note On UNIX, use the forward slash in the path as separator. You can use the same on Windows also. However, if the backward slash is used on Windows, then it should be escaped.

For example:

truststore.path = C:\\MQMonitor\\keys\\truststore.jks is correct

truststore.path = C:/MQMonitor/keys/truststore.jks is correct

keystore.path and keystore.password

The personal certificate of client is placed in keystore. You must provide the keystore location and also its password in the MBMonitor.properties file as follows:

For example:

keystore.path = C:/MQMonitor/keys/keystore.jks

keystore.password = < Encrypted password>

» Note You need not edit these properties directly in the MBMonitor.properties file. Instead, you must run the mqPwdEncryptor.bat file. The mqPwdEncryptor.bat utility updates the keystore.path with the user provided location having forward slash as the separator.

This completes your editing of the MBMonitor.properties file.

Generate Personal Certificates

For generating self-signed certificates and extracting it, WebSphere MQ client installation is a prerequisite.

You can obtain the personal certificates for Queue Manager in the following ways:

Create self-signed certificates.

Have an in-house certification authority.

Request a certificate from a certification authority.



Configure WebSphere MB

To configure WebSphere MB:

Use the Message Broker Command Console on the Windows platform

Use the command line on the UNIX platform.

To run the MQMonitor agent for monitoring WebSphere MB, the user must be part of mqm and mqbrkrs. Else, the MQMonitor agent throws an error such as the following:

[FATAL][com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] Configuration Manager broken connection!

12/11/07 03:01:33 PM GMT+05:30 [FATAL][com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain]

Start the Configuration Manager and run the MQMonitor agent again.

If you want to see the Queue Managers used by the Configuration Manager and it’s Brokers under the WebSphere Message Broker node, configure the corresponding Queue Manager details in the MQMonitor.properties file.

Step 1 Enable MessageFlow accounting statistics for message flow performance metrics by executing an MQSI command on the Message Broker host. See the WebSphere MB documentation for the syntax of this command.

Examples:

To enable statistics for Message flows on the AirlineExecutionGroup on a broker named foo_broker:

mqsichangeflowstats foo_broker -s -e AirlineExecutionGroup -j -c active -o xml -n basic

To verify the statistics settings created by the above command:

mqsireportflowstats foo_broker -s -e AirlineExecutionGroup -j

» Note The above commands use the Windows syntax. For information on the z/OS syntax, see the IBM documentation.

Step 2 Enable Publish/subscribe statistics reports for broker performance metrics.

Publish/subscribe statistics provide information about the performance of brokers, and the throughput between the broker and clients that are connected to the broker.

mqsichangeproperties foo_broker -e AirlineExecutionGroup -o DynamicSubscriptionEngine -n statsInterval -v 30000


User Guide

To verify the statistics settings created by the above command:

mqsireportproperties foo_broker -e default -o AirlineExecutionGroup –n statsInterval

For information on how to perform these steps, see the WebSphere MB documentation.

Configure WebSphere MQ to publish events

To view MQ Events in Introscope, perform the following steps:

Step 1 Edit the MQMonitor.properties file to identify the queues whose events you want to monitor. For more information on the MQ Events, see the MQ Events Section on page 23.

Step 2 Using MQ Explorer commands:

a For Queue Manager events:

From the Queue Manager properties dialog, choose the events pane. You can enable monitoring of Authority, Inhibit, Local, Remote, Start, and Stop from here.

b For Channel Events:

From the Queue Manager properties dialog, choose the events pane. You can enable monitoring of Channel, SSL, and Channel auto-definition from here.

c For Performance Events:

From the Queue Manager properties dialog, choose the events pane. You must first enable monitoring of Performance from here.

From the queue properties dialog, choose the events pane. You can enable queue depth events and service interval events from here.

You can also use MQSC commands. See the IBM WebSphere MQ documentation for assistance.

» Note If more than one application is monitoring the MQ Event Queues, then MQMonitor agent throws “MQ return code 2042 (Object In Use) error message.” To avoid this, go to the queue properties—if default properties are used, then the queues are SYSTEM.ADMIN.PERFM.EVENT, SYSTEM.ADMIN.QMGR.EVENT, and SYSTEM.ADMIN.CHANNEL.EVENT—click the Extended tab, and set the Shareability property set to Shareable and the Default Input Open Option property to Input shared.

After setting the options, start the MQMonitor agent.



Turn on Queue Monitoring

You must turn on Queue Monitoring for each individual queue in MQ Explorer to see the following Oldest Message Age and Queue Time metrics:

Oldest Message Age (sec), Oldest Message Age Per Hour (sec), Oldest Message Age Per 6 Hours (sec), Oldest Message Age Per Day (sec).

Last Get Date, Last Put Date, Last Put Time, Last Get Time, Queue Time (Long Term Avg.), Queue Time (Short Term Avg.).

To turn on queue monitoring for individual queues:

1 Go to Queue Properties > Statistics Page.

2 Set Queue Monitoring to High, Medium, or Low.

3 Set Queue Statistics to On or Queue Manager.

You can also use the MQSC commands to turn on Queue Monitoring. For more information, see the IBM WebSphere MQ documentation.

Viewing Data Using PowerPack for MQ 67

CHAPTER 3

Viewing Data Using PowerPack for MQ

PowerPack for MQ reports data to the Introscope Enterprise Manager (EM). This chapter describes how you can view Introscope data using PowerPack for MQ.


View data . . . . . . . . . . . . . . . . . . . . . 67

Console dashboards . . . . . . . . . . . . . . . . . . 67

Investigator dashboards. . . . . . . . . . . . . . . . . 68

View dataTo view the data sent to the EM, you use these Introscope Workstation GUI tools:

Console Dashboards

Investigator Dashboards

Console dashboardsPowerPack for MQ provide the Management Modules that consist of several pre-configured dashboards for the Introscope Console.

MQ dashboards in the Console

You can view the following WebSphere MQ and WebSphere Message Broker dashboards in the Console:

WebSphere MQ Client and Server dashboards

WebSphere MQ Client And Server Overview

WebSphere MQ Client And Server Overview - Details

WebSphere MQ - Client Connections

WebSphere MQ - Client Operations

WebSphere MQ - Server

68 Viewing Data Using PowerPack for MQ


WebSphere Message Broker dashboards

WebSphere Message Broker - Backouts Total

WebSphere Message Broker - Channels

WebSphere Message Broker - Errors Total

WebSphere Message Broker - Messages Dropped Total

WebSphere Message Broker - Overview

WebSphere Message Broker - Queue Managers

WebSphere Message Broker - Queues

WebSphere Message Broker - Timeouts Total

To use the Console dashboards:

1 Launch Introscope Enterprise Manager.

2 Launch the Introscope Workstation to connect to the Introscope Enterprise Manager, and log into the Console.

3 Using the dropdown menu, select one of the dashboards.

Investigator dashboardsPowerPack for MQ provides pre-configured graphical dashboards and data displays to give users visibility into the most important metrics provided by WebSphere MQ and WebSphere MB. These displays aggregate, correlate, and display important metrics so that you can see at a glance how the system is functioning and where problems are occurring.

To view dashboards and data displays:

1 Launch Introscope Enterprise Manager.

2 Launch the Introscope Workstation to connect to the Introscope Enterprise Manager, and log into the Investigator.

In the Investigator, the metric data is organized in the following ways:

the metrics tree

dashboards and graphical displays

Understanding the metrics tree

The PowerPack for MQ displays two main types of data from WebSphere MQ or WebSphere MB:

Data from MQMonitor agent and MBMonitor agent.

Data from the MQ Java Connectors.

Investigator dashboards 69

User Guide

MQMonitor agent and MBMonitor agent metrics

To find data from the MQMonitor agent and MBMonitor agent:

Select *SuperDomain* > <hostname> > WebSphere MQ and Message Broker > WebSphere MQ and Message Broker Agent (*SuperDomain*) node:

The following illustration shows data from the MQMonitor agent in four places in the Investigator metrics tree:

Basic information about the WebSphere MQ agent and the Message Broker agent, under WebSphere MQ and Message Broker Agent (*SuperDomain*).

Queue Manager Cluster metrics, under Queue Manager Clusters.

Queue Manager metrics, under Queue Managers.

Message Broker metrics, under WebSphere Message Broker.



hleveltre


User Guide

The following sections of this chapter provide a summary of the contents of the Investigator metrics tree. Appendix A provides detailed explanations of each metric.

Host information

At the top level of the MQ metrics tree, you can view information about the host where MQMonitor agent is running.

Metric name Description

EM Host Name of the machine that hosts the Introscope Enterprise Manager.

Java Version Version of Java being run by the MQMonitor agent.

Launch Time Time and date when MQMonitor agent was last launched.

Virtual Machine Vendor of the JVM (Java Virtual Machine) running MQMonitor agent.

GC Heap “Garbage collection” heap—the amount of free memory available to the MQMonitor agent.

Bytes In Use Size of the in-use memory heap on the MQMonitor agent.

Bytes Total Total size of the memory heap on the MQMonitor agent.

Host Machine which hosts the MQMonitor agent.

IP Address MQMonitor agent’s IP address.

Operating System MQMonitor agent’s operating system.

Wall Clock Time Local time of the MQMonitor agent.

Queue Manager Cluster metrics

Under the Queue Manager Clusters node, you can view metrics and status information for cluster Queue Managers.

For more information on Queue Manager Cluster metrics, see Queue Manager Cluster metrics on page 125.

Queue Manager metrics

Under the Queue Managers node, you can view metrics for each Queue Manager under six different nodes:

Channels—Links between two Queue Managers (a message channel), or between a Queue Manager and a client application (an MQI channel). Channel objects have attributes that define how message channels behave.

Under the Channels node, you can view Configuration Properties and Status metrics for each of the channels running under the Queue Manager.



Channel Initiator—Provides and manages resources that enable WebSphere MQ distributed queuing. WebSphere MQ uses Message Channel Agents (MCAs) to send messages from one Queue Manager to another.

PageSets—Data sets that are specially formatted to be used by WebSphere MQ. Page sets are used to store most messages and object definitions. WebSphere MQ page sets can be up to 64 GB in size. Each page set is identified by a page set identifier (PSID). Each Queue Manager must have its own page sets.

Logs—Records all significant events that occur in WebSphere MQ. The log contains the information about Persistent messages, WebSphere MQ objects such as queues, and the WebSphere MQ Queue Manager.

Configuration Properties—Data on how administrators have configured each Queue Manager. Some properties have both a string and a numeric value.

Dead Letter Queue—Configuration Properties and Status data/metrics about MQ Queue Manager’s dead letter queue, which is a repository for undeliverable messages.

Last Check—Information about the connection status of the Queue Manager.

Queues—Configuration Properties and Status data/metrics for each of the queues configured by the administrators on the Queue Manager.

Status—Data and metrics on the status of the Queue Manager. Some properties have both a string and numeric value.

For more information about Queue Manager metrics, see Queue Manager metrics on page 146.

Message Broker metrics

You can see three kinds of data and metrics for each message broker which the administrator has configured:

Broker Properties—Identification and configuration information about this message broker.

Component Runstate—Whether the message broker is running or not running.

Number of Subcomponents—the number of Execution Groups under this broker.

Shared Object—Whether the message broker is a shared object (“TRUE”) or a non-shared object (“FALSE”).

UUID—Universally Unique Identifier for the Broker.

Execution Groups—Sets of processes within a broker in which message flows run. For each execution group, you can see metrics arranged in several subgroups:


User Guide

Status and configuration information.

Broker Statistics—Divided into Client Statistics, Neighbor Statistics, and Wide Statistics.

Message Flows—Divided into several subcategories.

Broker Queue Manager metrics—Detailed information about the status and configuration metrics for the broker Queue Manager, divided into:

Channels

Configuration Properties

Dead Letter Queue

Queues

Status

For more information on Message Broker metrics, see Message Broker metrics on page 181.

MQ Java Connector metrics

MQ Java Connector metrics allow you to monitor the performance of your application server.

To obtain data from MQ Java Connectors:

1 Expand the SuperDomain node and look under the <hostname><WebSphere><WebSphereAgent>(*SuperDomain*) node.

2 Look under certain nodes in the tree, as shown in the following illustration:



For more information on MQ Java Connector metrics, see MQ Java Connector metrics on page 196.

Investigator Dashboards and data displays

To show dashboards and graphical displays of metric data:

Click on any node higher than an individual metric.


User Guide

Almost all of these nodes have associated Investigator dashboards which display an aggregate view of the metrics under that node, and the Overview tab usually contains “traffic light” indicators. The design of each dashboard, the data it aggregates, and the thresholds which trigger changes in traffic lights depends on the node you select.

In the example above, the Queue Managers node is selected.

Things to notice:

Traffic lights

Traffic light widgets provide an overview of critical performance metrics. Each of the traffic lights corresponds to aggregated metrics viewable in the metrics tree under the node selected.

» Tip In most cases, double-clicking the traffic light displays the metric data underlying that traffic light.

Data table

A table beneath the traffic lights gives more information; in this example, it lists each of the Queue Managers associated with the selected node, allowing a user to quickly see that the first Queue Manager listed has reached its maximum queue depth.

In this example, the table columns reflect the same information shown in the traffic lights. In other cases, table columns provide additional information.



Remember that the Investigator dashboards display aggregated or calculated metrics, not atomic data which comes directly from WebSphere MQ. These tables display data that has been aggregated or calculated.

Colors

The colors reflect threshold settings.

red—a danger threshold has been reached for at least one of the objects monitored under this object.

yellow—a caution threshold has been reached for at least one of the objects monitored under this object.

green—no thresholds have been reached for any of the objects monitored under this object.

white—no data has been received for any of the objects monitored under this object.

Tabs

Each dashboard has an Overview tab, and additional tabs with more data. The names and contents of these tabs depends on the node.

Each dashboard element is pre-configured, and you can use them without performing additional configuration.

Aggregated metrics

The tables in this section list the aggregated metrics and traffic lights which you see in the PowerPack for MQ dashboards, with details about each.


User Guide

Queue Manager Cluster and Queue Manager metrics

Aggregated metric name Description Value

Aggregated Agent-MQ Connection Status

Indicates the aggregated connection status of PowerPack for MQ with all the Queue Managers.

0 = green—successful

1 = red—unsuccessful

Aggregated Channel Indoubt Status

Indicates whether any of the channels on the Queue Managers are currently in doubt.

Note: Applies only to sending channels

0 = green—No channels are in doubt

1 = red—At least one channel is in doubt.

Aggregated Page Set Status (z/OS only)

Indicates the aggregated status of the page sets.

0 = green—all page sets are running

1 = red—one or more page sets have stopped

Aggregated Queue Manager Status

Indicates the aggregated status of the Queue Managers. One of:

0 or green = all the Queue Managers are running

1 or red = one or more Queue Managers have stopped

0 = green—running

1 = red—unknown

Maximum Queue Depth Reached Indicates whether the maximum queue depth has been reached for any of the queues under this node.

0 = green—maximum not reached

1 = red—maximum reached

Queue aggregated metrics

Aggregated metric name Description Value

Get Enabled Indicates whether the get operations are allowed for the queues or not.

0 = green—get operations are allowed (messages can be read) for all queues under this node

1 = red—get operations are inhibited (messages cannot be read) for at least one of the queues under this node

Maximum Queue Depth Reached Indicates whether the maximum queue depth has been reached for any of the queues under this node.

0 = green—maximum not reached

1 = red—maximum reached



Message Broker aggregated metrics

The following illustration shows the WebSphere Message Broker node:

Maximum Queue Depth (% Queue Full)

Indicates the greatest recorded queue depth for any of the queues under this node (measured in percent of fullness).

Green = maximum queue depth is <70% for all queues under this node

Yellow = maximum queue depth is >70% but <90% for all queues under this node

Red = maximum queue depth is >90% for all queues under this node

Put Enabled Indicates whether put operations are allowed for the queues or not.

0 = green—put operations are allowed (messages can be put on a queue) for all queues under this node

1 = red—put operations are inhibited (messages cannot be put on a queue) for at least one queue under this node


User Guide

The table below describes aggregated metrics for the Message Broker Configuration Manager:

Aggregated metric name

Description

Backouts Total Total number of backouts reported under this node.

Errors Total Total number of errors reported by the objects under this node. Errors are aggregated from message flow statistics.

Messages Dropped Total

Total number of dropped messages under this node.

Timeouts Total Total number of timeouts reported under this node.

MQ Events

To view MQ Events in the Introscope Investigator workstation:

1 Select *SuperDomain* > <hostname> > WebSphere MQ and Message Broker > WebSphere MQ and Message Broker Agent (*SuperDomain*) node.

2 Look in the right pane in the What’s Interesting column:

Using dashboards in troubleshooting 81

User Guide

Using dashboards in troubleshootingThe aggregate metrics calculated by PowerPack for MQ dashboards allow users to spot trouble and quickly identify its source. This section guides you in using the MQ dashboards for troubleshooting.

Troubleshooting Queue Manager clusters and Queue Managers

This section gives you advice for troubleshooting the first two high-level nodes in the MQ metrics tree:

Queue Manager Clusters

Queue Managers

Queue depth

Very often the first sign of a problem with a queue is progressive increasing queue depth. Abnormal increases in queue depths might be common during scheduled batch processes, but unexpected increases should be cause for investigation.

When you see an unexpected increase in queue depth:

1 Check whether the application can access the queues.

2 Check the Connection metrics to see if there are any exceptions raised when the application attempts to connect to the queue.

3 Check whether the application is able to read and deliver messages to the queues.

a Although the message depth could indicate that the messages are being put on the queue, they could still be unavailable to be read by the application if they are uncommitted, so check metrics on commits/backouts.

b Check gets/puts for any abnormalities.

c Check queue residency times (Avg/Max) for abnormalities.

4 Check performance metrics relating to message processing to/through the queues.

5 Check the message size (Avg/Max) for any abnormalities.

6 Check the status of the dead letter queues. A large number of messages in the dead letter queue could adversely impact application performance.

Channels

1 Check the state of the channel—whether it is running, stopped, in doubt, retry, or any other state.

2 Check whether the channel is moving messages fast enough.



a Investigate throughput by comparing:

Buffers Sent vs. Buffers Received.

Bytes Sent vs. Bytes Received, or Messages Sent vs. Messages Received.

b Check the status of the MCAs (Message Channel Agents) that link to the channel.

c Check the status of the transmission queues (a channel is always linked to a transmission queue). If a receiver channel is down, the sender channel might do certain number of re-tries to move the messages in which case the messages do not appear in a Dead Letter Queue immediately.

Example

In this illustration, the user has selected the Queues node on the default Queue Manager.

Red traffic lights indicate the maximum queue depth has been reached on at least one of the queues.

Using dashboards in troubleshooting 83

User Guide

1 Click the Message Throughput tab, which lists all the queues under the Queues node. One of the queues, SOCCER_SUBSCRIPTION, is highlighted, as shown in the illustration below.

2 Double-click the red-highlighted cell. The display changes to a display of graphs highlighting the most important metrics for that queue. The following illustration shows the Current Queue Depth as 300:



Troubleshooting Message Brokers

The most important Message Broker metrics to monitor are under the Message Flows > Node Statistics node:

Compute Node metrics

Metrics on Input and Output Nodes

Database nodes, particularly with respect to:

Response Time

Amount of data retrieved from database

The Node Statistics appear under the Message Flows node of the Message Broker tree, as shown here:

Transaction Tracing 85

CHAPTER 4

Transaction Tracing

The PowerPack for MQ introduces support for WebSphere MQ message tracking by extending the core Transaction Trace feature of Introscope. This chapter describes cross-process transaction tracing, how you can configure the WebSphere MQ system for trace, and how you can interpret the trace data.


Cross-Process Transaction Tracing . . . . . . . . . . . . . 86

Transaction Trace Viewer . . . . . . . . . . . . . . . . 86

Configure the WebSphere MQ System for trace . . . . . . . . . 87

Verify the transaction trace configuration . . . . . . . . . . . 91

WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard92


Configure EM for trace . . . . . . . . . . . . . . . . . 96

Interpret trace information . . . . . . . . . . . . . . . . 97


Filter queues for transaction trace . . . . . . . . . . . . . 105

Trace data properties . . . . . . . . . . . . . . . . . 106

86 Transaction Tracing


Cross-Process Transaction TracingIn Introscope, cross-process transaction tracing is Transaction Tracer’s capability to trace transactions for instance servlets to EJBs, across JVM and CLR boundaries for specific versions of WebSphere and WebLogic application servers.

In PowerPack for MQ, cross-process transaction tracing is expanded to WebSphere MQ. This capability includes transactions crossing from various applications servers to WebSphere MQ backends. The cross-process transaction tracing extends the monitoring capability of PowerPack for MQ and lets you determine which component of WebSphere MQ is causing performance bottlenecks.

PowerPack for MQ obtains MQ traces using the Activity Recording feature of WebSphere MQ. In special cases (when the message goes to a local queue), the MQ trace is obtained by polling, on the MQMonitor agent. The MQ trace-related polling properties are described in MQ Trace related properties Section on page 27.

Transaction Trace ViewerThe following sections describe how you can use the Transaction Trace viewer.

To start a Transaction Trace session:

1 Select Workstation > New Transaction Trace Session.

The New Transaction Trace Session window opens.

2 In the Trace transactions section of the window, specify the threshold execution time. Select milliseconds or seconds from the drop-down list.

» Note Sub-second thresholds can have a negative impact on performance.

To stop a Transaction Trace session:

Click Stop, or select Trace > Stop Tracing Session.

To restart a Transaction Trace session:

Click Restart, or select Trace > Restart Tracing Session.

Restarting the Transaction Trace session resets the timeout to the user-defined time period and continues to trace transactions in the targeted agents using the same threshold criteria. You can restart a Transaction Trace session:

after a session has timed out.

to restart a session that you have stopped.

to restart a session that is in progress.

Configure the WebSphere MQ System for trace 87

User Guide

Configure the WebSphere MQ System for traceYou can use the mqConfigurationSetup tool to configure the WebSphere MQ system for trace. You can also configure the WebSphere MQ system for trace manually.

mqConfigurationSetup tool

You can use the mqConfigurationSetup tool to automate the configuration for cross-process transaction tracing. The tool contains a batch file named mqConfigurationSetup.bat and is available in the /tools directory of the MQMonitor agent. On UNIX, the tool contains the mqConfigurationSetup.sh file, and is available in the /tools directory of the MQMonitor agent.

» Note Before you run the tool, ensure that the MQMonitor.properties file is configured appropriately, as the tool uses the mq.monitor.list property value to obtain the monitored Queue Managers.

The configuration tool updates the following properties on all the monitored Queue Managers and queues:

Sets the Activity recording property to Queue for each Queue Manager.

Creates the SYSTEM.ADMIN.ACTIVITY.QUEUE, Dead Letter Queue(DLQ), and Handshake queue, if any of these queues does not exist in the Queue Manager.

Configures the SYSTEM.ADMIN.ACTIVITY.QUEUE, Dead Letter Queue, and Handshake queue as follows:

Sets the Max queue depth property to the maximum permitted value (999999999).

Sets the Put messages and Get messages properties to Allowed.

Sets the Shareability property to Shareable.

Sets the Default Input Open Option property to Input Shared.

The tool finally generates a report containing information about all the properties that were modified in the Queue Managers and Qqeues. The tool saves the report to a file called changehistory.txt in the /tools directory of the MQMonitor agent. The tool appends all configuration changes to the same file, so that you can see

To apply the changes, restart all active channels on the monitored Queue Managers. Alternatively, except for z/OS, we recommend that you also restart all the monitored Queue Managers.For z/OS, restart CHINIT only as restarting the Queue Manager, may change the value of the Activity Recording property of some Queue Managers to “Message” instead of “Queue”.

all the changes made to the WebSphere MQ objects.

» Important

» Important



To configure the mqConfigurationSetup tool:

1 Configure the MQMonitor.properties to monitor Queue Managers. See Configure the MQMonitor agent properties on page 20.

2 Edit the mqConfigurationSetup.bat file for the following settings.

Set the JAVA_HOME variable to a valid JRE.

Set the MQ_JAR variable to the location of com.ibm.mq.jar file.

Set the PCF_JAR variable to the location of com.ibm.mq.pcf-6.1.jar file.

Set the J2EE_JAR variable to the location of j2ee.jar file.

3 Run the mqConfigurationSetup.bat file. The command is as follows:

mqConfigurationSetup.bat [-i on/off] [-p ../properties/]

» Note Set the parameter -i for interactive or non-interactive mode. The default value of the parameter is on. If you set the parameter to on, then the tool prompts you for confirmation before changing the properties of the WebSphere MQ objects. If you set the parameter to off, then the tool changes all the properties without prompting you for confirmation.

» Note Set the parameter -p to indicate the location of the MQMonitor.properties file. The default value of this parameter is ../properties/.

Configure WebSphere MQ for trace manually

To manually configure the WebSphere MQ system for trace, perform the following steps:

Configure the Queue Managers as follows:

Set the Activity recording property on page 88.

Configure SYSTEM.ADMIN.ACTIVITY.QUEUE on page 90.

Set the Max queue depth property to the maximum permitted value (999999999).

Set the Put messages and Get messages properties to Allowed.

Set the Shareability property to Shareable.

Set the Default Input Open Option property to Input Shared.

Set the handshake queue on page 90.

Set the Activity recording property

For all the Queue Managers in WebSphere MQ that are monitored by the MQMonitor agent, set the value of the Activity recording property to Queue. This enables the Queue Managers to generate activity reports. All the activity reports are generated in SYSTEM.ADMIN.ACTIVITY.QUEUE of the same Queue Manager.

Configure the WebSphere MQ System for trace 89

User Guide

The following illustration shows how you can set the Activity recording property to Queue for the SOURCE Queue Manager in the MQ Explorer:

You can use the MQSC commands to set and display the Activity recording property.

To set the Activity recording property, enter the command:

runmqsc <Queue Manager Name>

To view the value of the Activity recording property, enter the command:

display QMGR ACTIVREC

The Activity recording property values appear in the command prompt window under the following two columns:

QMNAME(SOURCE) ACTIVREC(MSG)

To set the ACTIVEREC property value to QUEUE, enter the command:

alter QMGR ACTIVREC(QUEUE)

To verify the Activity recording property, enter the command:

display QMGR ACTIVREC

The Activity recording property values appear in the command prompt window under the following two columns:

QMNAME(SOURCE) ACTIVREC(QUEUE)

For more details, see the IBM documentation.

» Important Restart the Queue Manager MCA’s after configuring the SYSTEM.ADMIN.ACTIVITY.QUEUE.



Configure SYSTEM.ADMIN.ACTIVITY.QUEUE

To configure SYSTEM.ADMIN.ACTIVITY.QUEUE:

1 Open SYSTEM.ADMIN.ACTIVITY.QUEUE in the MQ Explorer.

2 Right-click SYSTEM.ADMIN.ACTIVITY.QUEUE and click Properties.

The SYSTEM.ADMIN.ACTIVITY.QUEUE properties window opens.

3 Select Extended and set the Max queue depth property to 999999999. Set Shareability as Shareable. Set the Default Input Open Option property to Input Shared.

4 Select General, and set the Put messages and Get messages properties to Allowed.

MQSC commands

You can use the MQSC commands to configure SYSTEM.ADMIN.ACTIVITY.QUEUE.

To define SYSTEM.ADMIN.ACTIVITY.QUEUE (if not already defined), enter the command:

define QLOCAL(SYSTEM.ADMIN.ACTIVITY.QUEUE) USAGE (normal) DESCR('For Introscope Use')

To configure the SYSTEM.ADMIN.ACTIVITY.QUEUE, enter the command:

alter QLOCAL (SYSTEM.ADMIN.ACTIVITY.QUEUE) PUT (enabled) GET (enabled) DEFPSIST (no) SHARE DEFSOPT (SHARED) MAXDEPTH (999999999)

To verify the SYSTEM.ADMIN.ACTIVITY.QUEUE, enter the command:

display QLOCAL(SYSTEM.ADMIN.ACTIVITY.QUEUE)

Set the handshake queue

Handshake refers to the communication between the MQMonitor agents and MQ Java Connector agents. You can perform handshake by creating a queue (called handshake queue) on an existing Queue Manager or a new Queue Manager, that is accessible from all application servers and MQMonitor agents.

To define a local queue, say CA_WILY_HANDSHAKE, enter the MQSC command:

define QLOCAL(CA_WILY_HANDSHAKE) USAGE(NORMAL) PUT(ENABLED) GET(ENABLED) DEFPSIST(NO) SHARE DEFSOPT (SHARED) DESCR('For Introscope Use')

The above command defines the CA_WILY_HANDSHAKE queue with the put and get properties enabled, not persistent, and shareable.

Verify the transaction trace configuration 91

User Guide

To verify the queue, enter the command:

display QLOCAL(CA_WILY_HANDSHAKE)

Set the MCA User ID

To ensure that the trace data does not reach the Dead Letter Queue, and for transaction trace to occur, you can set the MCA user ID as described below.

» Note This is applicable for WebSphere MQ infrastructure that consists of Queue Managers of various WebSphere MQ platforms, to obtain MQ trace for Queue Managers of different types.

The Java application may use WebSphere MQ, JMS, or MQ Java Connectors to interact with the WebSphere MQ infrastructure. Depending on the setting of the Java application, you can use the following approaches to set the MCA user ID:

If the Java application sets the user ID of the WebSphere MQ message, then perform the following steps to add a user:

a Identify the user that is being set by the Java application on the MQMessage.

b Create the user on all WebSphere MQ machines.

c Add the user to the group created by WebSphere MQ installation on all platforms.

d Restart the channels.

If the Java application does not set the user ID of the MQ Message, then perform the following steps to add a common user:

a Create a common user for all WebSphere MQ machines.

b Add the common user to the group created by WebSphere MQ installation on all platforms.

c Set the common user in the Server-connection channel’s attribute MCA user ID using the WebSphere MQ Explorer on all Server-connection channels on all Queue Managers. The corresponding MQSC command is:

alter channel (<channel name>) CHLTYPE (SVRCONN) MCAUSER(<common user>)

d Restart the channels.

Verify the transaction trace configurationTo check if you have configured the transaction trace properly, check the following:

The handshake and trace-related properties are configured on both the MQAgent.properties and MQMonitor.properties files.



The handshake queue is available.

All the MQMonitor agents are running.

All the MQMonitor agents are connected to the Queue Managers.

The SYSTEM.ADMIN.ACTIVITY.QUEUE is available, and enabled for put and get operations.

You can check the status of MQ Trace by checking the values of the mqmonitor.mqagent.id.list and handshake.mqagent.id properties in the MQAgent.properties file as shown in the following table:

Value of mqmonitor.mqagent.id.list

Value of handshake.mqagent.id

MQ Trace configuration

null null or any value always on

any value null always off

any valid value any valid value conditional on

WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard

The WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard helps you check whether your WebSphere MQ infrastructure is properly configured for MQ Trace. The dashboard has traffic lights that show the status of SYSTEM.ADMIN.ACTIVITY.QUEUE, Agent-MQ Connection Status, Handshake status, Activity recording status, and Dead Letter Queue.

WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard 93

User Guide

Here’s an illustration of the dashboard:



The SYSTEM.ADMIN.ACTIVITY.QUEUE has traffic lights for the following elements:

Get/Put Messages

Queue Full

Shareability

The following table lists the threshold values for

Element Threshold

Get/Put messages Green - Indicates that all the SYSTEM.ADMIN.ACTIVITY.QUEUE of the monitored Queue Managers are receiving and sending messages.Red - Indicates that one or more SYSTEM.ADMIN.ACTIVITY.QUEUE of the monitored Queue Managers cannot send or receive messages.

Queue Full Green - Indicates that the % Queue Full value of the monitored Queue Managers is less than 50%.

Yellow - Indicates that the % Queue Full value of the monitored Queue Managers is greater than 50% and less than 75%.Red - Indicates that the % Queue Full value is greater than 75%.

Shareability Green - Indicates that the Shareability property of SYSTEM.ADMIN.ACTIVITY.QUEUE is set to Shareable.Red - Indicates that the Shareability property of SYSTEM.ADMIN.ACTIVITY.QUEUE is not set to Shareable.

the above elements:

The Dead Letter Queue has traffic lights for the following elements:

Get/Put Messages

Queue Full

Shareability

WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard 95

User Guide

The following table lists the threshold values for

Element Threshold

Get/Put messages Green - Indicates that all the Dead Letter Queues of the monitored Queue Managers are configured for sending and/or receiving messages from applications.Yellow - Indicates that one or more Dead Letter Queue of the monitored Queue Managers are not configured for sending and/or receive messages from applications.

Queue Full Green - Indicates that the % Queue Full value of the monitored Queue Managers is less than 50%.

Yellow - Indicates that the % Queue Full value of the monitored Queue Managers is greater than 50%.

Shareability Green - Indicates that the Shareability property of Dead Letter Queue is set to Shareable.Yellow - Indicates that the Shareability property of Dead Letter Queue is not set to Shareable.

the above elements:

Apart from the traffic light indicators for SYSTEM.ADMIN.ACTIVITY.QUEUE and Dead Letter Queue, the dashboard includes traffic lights for the following:

Element Threshold

Agent-MQ connection Status

Green - Indicates that the MQMonitor agent is able to successfully connect to all the monitored Queue Managers.

Red - Indicates that the MQMonitor agent cannot connect to one or more Queue Managers.

Handshake Status Green - Indicates that the handshake between the MQMonitor agents and MQ Java Connector agents is successful.

Red - Indicates that the handshake between the MQMonitor agents and MQ Java Connector agents is not successful.

Activity Recording status

Green - Indicates that the Activity recording property for all the monitored Queue Managers is set to Queue.

Red - Indicates that the Activity recording property for one or more monitored Queue Managers is set to a value other than Queue.

Based on the threshold values of all the elements, the dashboard shows the overall status of your PowerPack for MQ installation in the central traffic light indicator.



The overall status traffic light appears as green if the traffic lights of all of the elements are green. However, if one of the traffic lights in the SYSTEM.ADMIN.ACTIVITY.QUEUE, or Agent-MQ Connection Status, Handshake Status, or Activity Recording status is red, the overall status traffic light turns red.

Configure EM for traceTo configure the Introscope Enterprise Manager (EM) for trace:

1 Edit the IntroscopeEnterpriseManager.properties file located in the <Introscope Home>/config directory to add the following two lines:

introscope.workstation.transactiontracer.showTotalDuration=trueintroscope.workstation.transactiontracer.showTotalDuration.sumAl

lTraceComponents=true

2 Restart the EM.

An additional column called Total Duration (ms) appears in the Transaction Trace Viewer. The Total Duration (in milliseconds) of a trace is the wall clock time from the start to the very end of all trace components.

Interpret trace information 97

User Guide

Interpret trace information

Scenario 1 - Single Hop in the WebSphere MQ infrastructure

Message has been put by the Java application to a Remote Queue HOP1.REMOTE of Queue Manager HOP1 located at host localhost. The message hops to another queue HOP2.LOCAL of Queue Manager HOP2 at host localhost.

The following illustration shows the complete trace of this message transaction when the transaction trace session is turned on:



The interpretation of this trace is as follows:

The Total Transaction takes 14011 ms. The Total trace contains three components.

The first trace component is the MQ Java Connector trace. If you zoom the trace, the trace appears as follows:

The MQ Java Connector generates a Queue Put operation of 91 ms.

The message has been put to HOP1.REMOTE queue of Queue Manager HOP1.


User Guide

The second trace component is the trace coming from the MQMonitor agent for the first Queue Manager HOP1.

The message is read using the MQ get operation (MQ Operation: GET).

The message stayed at the Transmission Queue (MQ Queue Type: TRANSMISSION) named HOP1.TRANS (MQ Queue Name: HOP1.TRANS) for 11330 ms (MQ Queue Residency Time: 11330 ms).

The message is supposed to go to the Queue Manager HOP2 (MQ Target Queue Manager: HOP2) through the sender (MQ Channel Type: SENDER) channel named HOP1.SNDR (MQ Channel Name: HOP1.SNDR).



The third trace component is the trace coming from the MQMonitor agent for the second Queue Manager HOP2.

The message is received by a receiver (MQ Channel Type: RECEIVER) channel named HOP1.SNDR (MQ Channel Name: HOP1.SNDR) and put (MQ Operation: Put) to a local queue (MQ Queue Type: LOCAL) named HOP2.LOCAL (MQ Queue Name: HOP2.LOCAL).

The message is found to be at HOP2.LOCAL for 2580 ms (MQ Queue Residency Time (~): 2580 ms) and also the message is not consumed (MQ Message Status: Message is not consumed) by the any other Application.

The message has not expired (MQ Message Expiry Time: Never expires) after 2580 ms.

» Note In the above case, when the message is put by the Java application to a local queue of a Queue Manager, the values of MQ Queue Residency Time and MQ Message Status at the local queue depends on the value of trace.polling.interval and trace.polling.retry.count properties.


User Guide

Scenario 2- No Hop inside the WebSphere MQ infrastructure

Message has been put by the Java application to a Local Queue Queue1 of Queue Manager QMGR1 located at host1.

The following illustration shows the complete trace of this message transaction when the transaction trace session is turned on:

The interpretation of the above trace is as follows:

The upper trace comes from the MQ Java Connector agent that captures the Put call of the Java application; the selected trace is the trace that comes from the MQMonitor agent.

The total duration of the transaction is 3077 ms (Total Duration (ms) column of the table).

The time taken by the MQ Java Connector agent is 484 ms (Duration (ms) column of the table).

The time taken by the message inside the MQ environment is 2677 ms (Duration (ms) column of the table).

The Java application puts (MQ Operation: PUT) the message to a local queue (MQ Queue Type: LOCAL) named Queue1 (MQ Queue Name: Queue1) through a Server Connection Channel to MQ (MQ Channel Type: SERVER-CONNECTION).

The message is found to be at Queue1 for 2677 ms (MQ Queue Residency Time (~): 2677 ms) and also the message is not consumed (MQ Message Status: Message is not consumed) by any other application.

The message has not expired (MQ Message Expiry Time: Never expires)



after 2677 ms.

» Note In the above case, when the message is put by the Java application to a local queue of a Queue Manager, the values of MQ Queue Residency Time and MQ Message Status at the local queue depends on the value of the trace.polling.interval and trace.polling.retry.count properties.

Identify a slow transactionYou can identify a slow transaction by performing the following steps:

1 Start a Transaction Trace session.

The trace appears in the Transaction Trace viewer.

2 Sort the trace in the descending order of Total Duration (ms) column.

3 Select the first trace in the list.

The first trace indicates the slowest running transaction among all the transactions.

Identify a slow transaction 103

User Guide

4 Select View > Correlated Events to get all the correlated events for the selected trace, as shown in the illustration below.



5 Select any trace to see the complete trace information.

Enable or disable MQ TracesYou can enable or disable MQ Trace by setting the handshake properties in the MQAgent.properties file.

To disable MQ Traces:

1 Set mqmonitor.mqagent.id.list to any valid value and handshake.mqagent.id to null value.

2 Restart the application server.

When you run the transaction trace, MQ Trace data does not appear on the Transaction Trace Viewer.

To enable MQ Traces without handshake:

Set mqmonitor.mqagent.id.list to null value.

Filter queues for transaction trace 105

User Guide

When you run the transaction trace, you can view MQ Trace data even when the MQMonitor agents are not running. However, you must note that the trace may be incomplete when the MQMonitor agent is unable to connect to any of the monitored Queue Managers.

» Note You need not restart the application server.

To enable MQ Traces with handshake (recommended):

Set mqmonitor.mqagent.id.list to the handshake.mqagent.id value of all MQMonitor agents.

The MQ Trace is generated when all MQMonitor agents are running and connected to their Queue Managers. This method provides you the complete trace and prevents any unnecessary overload on the MQMonitor agent.

You must restart the application server if you change the value of handshake.mqagent.id.

Filter queues for transaction traceYou can use the mqtracing.exclude.queues.regex property in the MQAgent.properties file to filter one or more queues of a particular Queue Manager from transaction tracing.

» Note This property filters the first queue where WebSphere MQ Put or JMS Send operations occur along with the subsequent correlated traces. This also filters the traces for the WebSphere MQ Get or JMS Receive operations.

Example:

To filter all the queues containing the word "SYSTEM" of the Queue Manager QM1 from transaction tracing, set the property:

QM1.mqtracing.exclude.queues.regex=.*SYSTEM.*

To filter all the queues of the Queue Manager QM1 from transaction tracing, set the property:

QM1.mqtracing.exclude.queues.regex=.*

To filter all the queues except queues TRACE.QUEUE1 and TRACE.QUEUE2 of the Queue Manager QM1 from transaction tracing, set the property:

QM1.mqtracing.exclude.queues.regex=(?!((.*TRACE.QUEUE1.*)|(.*TRACE.QUEUE2.*))).*



Trace data propertiesThe trace data properties vary based on the MQ operations. Channels perform different MQ operations (Get or Put) when they receive or send messages.

The following table describes the trace data:

Key Description Value MQ Operation

<Message ID> Actual message ID of the message.

IScopeMQID Put, Get

<Correlation ID> Actual correlation ID of the message.

This trace data does not appear if the correlation ID is same as message ID or if the correlation ID is null.

IScopeMQID Put, Get

MQ Channel Name Name of the channel on which the WebSphere MQ operations are performed.

<Channel Name> Put, Get

MQ Channel Type Type of the channel on which the WebSphere MQ operations are performed.

Any one of the possible values:

SENDERRECEIVERREQUESTERSERVER CONNECTIONCLUSTER SENDERCLUSTER RECEIVER

Put, Get

MQ Queue Name Queue Name <Queue Name> Put, Get

MQ Queue Type Queue Type Any one of the possible values:

LOCALLOCAL (DLQ)TRANSMISSIONREMOTE

Put, Get

MQ Queue Residency Time

Actual time (in milliseconds) the message stayed in the queue before moving it to the next Queue Manager.

Time in milliseconds (ms) Get

Trace data properties 107

User Guide

MQ Queue Residency Time (~)

Approximate time (in milliseconds) the message stayed in the queue before moving it to the next Queue Manager.

Note: This value is populated when the message is put to a local queue by polling. See Cross-Process Transaction Tracing on page 86.

Approximate time in milliseconds (ms).

or

Systems time may not be in synchronization if the MQMonitor agent and the WebSphere MQ Queue Managers are out of sync.

Put operation to a local queue

MQ Source Queue Manager

Previous Queue Manager Name from where the message has reached the current queue.

<Queue Manager Name> Put operation for one or more WebSphere MQ Hops.

MQ Target Queue Manager

Target Queue Manager Name to where the message must go on the next hop.

<Queue Manager Name> Put operation to a remote queue for one or more WebSphere MQ Hops.

MQ Target Queue Target Queue where the message must go on the next hop.

<Queue Name> Put operation to a remote queue for one or more WebSphere MQ Hops.

MQ Message Status Determines the status of the message in the destination queue.

If trace.polling.enabled=true, then any one of the following values:

Message is consumed or expiredMessage is not consumedMessage is consumed

Put operation to a local queue.

Key Description Value MQ Operation

Management Modules 109

User Guide

5Dashboards

This chapter lists each of the dashboards, their elements, and other information that you can view using the Introscope Console. These dashboards and related elements are part of the Management Module component of PowerPack for MQ. See Install Management Modules and extensions on page 56 for installing Management Modules.


Management Modules . . . . . . . . . . . . . . . . . 109

WebSphere MQ Client and Server dashboards . . . . . . . . . . 109

WebSphere Message Broker dashboards . . . . . . . . . . . 118

For general information on how to view dashboards in the Console, see Console dashboards on page 67.

Management ModulesPowerPack for MQ includes the following management modules:

WebSphere MQ Client and Server dashboards

WebSphere Message Broker dashboards

WebSphere MQ Client and Server dashboardsThe WebSphere MQ Client and Server dashboards show the real-time performance and health of WebSphere MQ system. This management module consists of five dashboards that help you diagnose the performance issues of WebSphere MQ. You can easily navigate through the various dashboards and troubleshoot the issues by correlating the activities in the application to WebSphere MQ operations to actual WebSphere MQ objects.

The WebSphere MQ Client and Server dashboards consists of the following:

WebSphere MQ Client And Server Overview dashboard on page 110.

WebSphere MQ Client And Server Overview - Details dashboard on page 112.

WebSphere MQ - Client Connections dashboard on page 115.

WebSphere MQ - Client Operations dashboard on page 116.

WebSphere MQ - Server dashboard on page 117.

110 Dashboards


WebSphere MQ Client And Server Overview dashboard

The WebSphere MQ Client And Server Overview dashboard shows the overall health of the Queue Managers, Queues, and Channels. It contains three components—MQ Client Connections, MQ Client Operations, and MQ Server. Each component has traffic lights that show the overall health of that component. For example, the MQ Client Connections component has two traffic lights—Connect and Rollbacks. Clicking the Connect or Rollbacks traffic lights shows the details for the MQ Client Connections component in the WebSphere MQ - Client Connections dashboard.

From the Overview tab, you can double-click any of the component dashboards, and view their details. Also, each traffic light has a link to the dashboard associated with the details of that specific component.

The following tables explain the thresholds and traffic lights in each of the three components of the dashboard.

WebSphere MQ Client and Server dashboards 111

User Guide

MQ Client Connections

MQ Client Operations

Element Description Threshold

Connect Indicates the status of the Average Response Time(ms) for the Connect operations.

Green - Indicates that the applications are able to connect to the WebSphere MQ infrastructure properly without much delay.

Yellow - Indicates that caution threshold has been reached; the applications are taking considerable duration to connect to the WebSphere MQ infrastructure and that there can be some problem in the system.

Red - Indicates that danger threshold has been reached; the applications are taking longer time to connect to the WebSphere MQ infrastructure and that there are some bottlenecks or problems in the system.

Rollbacks Indicates the status of the Responses Per Interval for the Rollback operations.

Green - Indicates that no threshold has been reached.

Yellow - Indicates that caution threshold has been reached.

Red - Indicates that danger threshold has been reached.


Put/Send Indicates the status of the Average Response Time (ms) for the Put/Send operations.

Green - Indicates that the Put or Send operations are completing in time meaning that the communication between the application and the WebSphere MQ Queue Manager or queues is good and that there is no problem in the Put/Send operations.

Yellow/Red- Indicates that the Put or Send operations are taking longer time to complete meaning that there can be problems in the WebSphere MQ infrastructure such as a channel that is busy or is in doubt; it can also mean that there is some problem on the network between the application and the WebSphere MQ infrastructure.

Yellow indicates that the caution threshold has been reached.

Red indicates that the danger threshold has been reached.

Get/Receive Indicates the status of the Average Response Time (ms) status for the Get/Receive operations.

Green - Indicates that the Get or Receive operations are completing in time meaning that the communication between the application and the WebSphere MQ Queue Managers or queues is good and that there is no problem in the Get/Receive operations.

Yellow/Red - Indicates that the Get or Receive operations are taking longer times to complete meaning that there can be problems in the WebSphere MQ infrastructure such as a channel that is busy or is in doubt; it can also mean that there is some problem on the network between the application and the WebSphere MQ infrastructure.



112 Dashboards


MQ Server

WebSphere MQ Client And Server Overview - Details dashboard

The WebSphere MQ Client And Server Overview - Details dashboard contains detailed metrics corresponding to the three components of the WebSphere MQ Client And Server Overview dashboard. Each component section is divided into smaller sections detailing specific and important operations.

The graphs in the dashboard display the following blame metrics for the MQ Client Connections, MQ Client Operations, and MQ Server components:

MQ Client Connections—Includes blame metrics for Average Response Time, Concurrent Invocations, Errors Per Interval, Responses Per Interval, and Stall Count for the Connect, Disconnect, Commit, and Rollback operations. It also includes the Waiting Thread Count, Percent Maxed, and Connection Pool status for the Connection Pool.

MQ Client Operations—Includes blame metrics for Errors Per Interval, Slowest (Average Response Time), Stall Count, Responses Per Interval for Put/Send and Get/Receive operations.

MQ Server—Displays Queue Manager Status (aggregated count), Queue Depth status, and Channel Indoubt Status. Also includes metrics for Connection Counts, Enqueue/Dequeue Count, Current Queue Depth (%), and Messages Per Channel.


Queue Managers Status

Indicates the status of the Queue Manager Aggregated of the MQ Server.

Green - Indicates that all Queue Managers are in the running state.

Red - Indicates that at least one of the Queue Managers is not running.

Queue Depth Indicates the Current Queue Depth (%) of the MQ Server.

Green - Indicates that all queues are being processed by the corresponding applications appropriately, so the messages are being addressed properly.

Yellow/Red - Indicates that the rate of the incoming messages for at least one queue is more than the rate of outgoing messages meaning that the messages are not being addressed properly by the concerned application listening to this queue and so the queue is reaching its full capacity.



Channel Status

Indicates the Channels Indoubt status of the MQ Server.

Green - Indicates that none of the channels are in doubt.

Red - Indicates that at least one channel is in doubt, indicating that there is some problem with that channel.


User Guide

From the WebSphere MQ Client And Server Overview - Details dashboard, you can click the Overview tab to navigate to the WebSphere MQ Client And Server Overview dashboard.

114 Dashboards


Interpret the dashboard traffic lights

When a traffic light is green, it indicates that the corresponding operation for that component is working fine or is at an appropriate threshold level. When any alert turns to red, it indicates that there is a problem with that component or operation. Clicking that alert takes you to that dashboard with more details of that component, where you can investigate the specific operation causing the problem. Similarly, the WebSphere MQ Overview Details dashboard contains more information regarding all of the three components so that you can correlate all the operations causing the alerts, in a single dashboard.

For example, when the Put/Send alert turns red in the WebSphere MQ Client And Server Overview dashboard, then clicking that alert takes you to the WebSphere MQ - Client Operations dashboard that has details for the Put/Send operations. The WebSphere MQ Client And Server Overview - Details dashboard also shows high level details of all components so that you can triage the problem quickly. In this example, the Put/Send operations may have a problem because of the corresponding Queue may be full or that the channel is in doubt, all of which can be easily seen in the WebSphere MQ - Server component of the WebSphere MQ Client And Server Overview - Details dashboard. You can click any of the traffic lights or graphs to see the blame metrics underlying that status.


User Guide

WebSphere MQ - Client Connections dashboard

The WebSphere MQ - Client Connections dashboard shows detailed metrics for MQ Client connections. The dashboard displays Average Respnse Time (ms), Errors (Errors Per Interval), Stalls (Stall Count) as traffic lights for the Connect, Commit, Disconnect, and Rollback operations. The graphs show the top ten metrics of Concurrent Invocations and Responses Per Interval for the Connect, Disconnect, Commit, and Rollback operations. The dashboard also displays Waiting Thread Count, Percent Maxed, and Pool status metrics for the Connection Pool.

From the WebSphere MQ - Client Connections dashboard, you can navigate to the WebSphere MQ Client And Server Overview and WebSphere MQ Client And Server Overview - Details dashboards.

116 Dashboards


WebSphere MQ - Client Operations dashboard

The WebSphere MQ - Client Operations dashboard shows detailed metrics for WebSphere MQ operations. The dashboard shows four blame metrics for the Put/Get operations of the Connector component and Get/Send operations of the JMS component. For each of the Put/Get, Send/Receive operations, you can see the top ten metrics for Responses Per Interval, Errors Per Interval, Stalls, and Average Response Times (Slowest Gets, Slowest Puts, Slowest Sends, Slowest Receives).

From the WebSphere MQ - Client Operations dashboard, you can navigate to the WebSphere MQ Client And Server Overview and WebSphere MQ Client And Server Overview - Details dashboards.


User Guide

WebSphere MQ - Server dashboard

The WebSphere MQ - Server dashboard shows detailed metrics for WebSphere MQ Server. The dashboard displays traffic lights for Queue Manager Status, Page Set Status (z/OS), Queue Depth for Queues, and Channel Indoubt Status for Channels. The graphs show the top 10 metrics for Connection Counts, Dead Letter, Enqueue/Dequeue Counts, Channel Instance Counts, Messages per Channel, and so on.

118 Dashboards


WebSphere Message Broker dashboardsThe WebSphere Message Broker dashboards show the performance of the Message Broker and its Message Queue.

WebSphere Message Broker Overview dashboard

The WebSphere Message Broker Overview dashboard has both:

traffic lights to show high-level alerts for both WebSphere MQ and WebSphere MB.

bar charts to show the Message Flows with the highest elapsed times and CPU times.

WebSphere Message Broker dashboards 119

User Guide

Elements

The WebSphere Message Broker Overview dashboard displays the following traffic lights.

In the

Component Red light threshold

Overall This traffic light reflects the worst status of the other components. If any one of the child traffic lights are yellow, the Overall traffic light is yellow, else, if any

one of the child traffic lights is red, the Overall traffic light is red.

Note: Red has a higher precedence over yellow.

Errors For each of these traffic lights :Green - No threshold has been reachedYellow - Caution threshold has been reachedRed - Danger threshold has been reached

Timeouts

Backouts

Messages Dropped

Message Broker section:

In the MQ section:

Component Red light threshold

Overall If any of the four child traffic lights pointing to this Overall traffic light are red, then this Overall traffic light is red.

Agent-MQ Connection Status

MQMonitor agent lost its connection with any one of the monitored queue managers.

Queue Managers Status

Any one of the monitored Queue Managers is not running.

Queues Full Any one of the monitored Queues is full (no more messages can be put on the queue).

Channels Indoubt Any one of the monitored channels is in doubt.

Compare the traffic lights with the high-level tree displayed in the Introscope Workstation:

120 Dashboards


Double-clicking on any of the traffic lights leads to another Console dashboard with more information about the health of the component you selected. For example, double-clicking Errors leads to the WebSphere Message Broker Errors Total dashboard:

Other Message Broker dashboardsWebSphere Message Broker - Backouts Total

WebSphere Message Broker - Timeouts Total

WebSphere Message Broker - Messages Dropped Total

WebSphere Message Broker - Queue Managers

WebSphere Message Broker - Channels

WebSphere Message Broker - Queues

WebSphere Message Broker dashboards 121

User Guide

Message Broker alerts

Message Broker dashboards display an alert with a threshold of 1. For example, if any of the monitored components show a single backout, the Backouts Total

traffic light turns red.

Alert Type Thresholds

Backouts Total Simple Danger Threshold: 1 Caution Threshold: 0

Errors Total Simple Danger Threshold: 1 Caution Threshold: 0

MQ Qmgrs Status Simple Danger Threshold: 0 Caution Threshold: 0

MQ Queues Full Status Simple Danger Threshold: 0 Caution Threshold: 0

MQ Channels Indoubt Status Simple Danger Threshold: 0 Caution Threshold: 0

Messages Dropped Total Simple Danger Threshold: 1 Caution Threshold: 0

Timeouts Total Simple Danger Threshold: 1 Caution Threshold: 0

MQ Agent-MQ Connection Status

Simple Danger Threshold: 0

Caution Threshold: 0

MQ Overall Status Summary

122 Dashboards


Metrics reference 123

APPENDIX A

Metrics reference

This appendix describes the Introscope metrics that you can view using PowerPackNameShort.

This appendix contains the following topics:

General metric characteristics . . . . . . . . . . . . . . . 123

Queue Manager Cluster metrics . . . . . . . . . . . . . . 125

Queue Manager metrics . . . . . . . . . . . . . . . . . 146

Message Broker metrics . . . . . . . . . . . . . . . . . 181

MQ Java Connector metrics . . . . . . . . . . . . . . . 196

» Note Time measurements appearing in Introscope are in milliseconds (thousandths of a second). When WebSphere MQ provides metrics in microseconds, Introscope converts these to milliseconds.

General metric characteristicsEach metric is expressed as one of four types:

String

Number

Mapped value—a numeric expression of a metric that is also expressed as a string. See the table below for an example:

Metric name

String Mapped Value

Channel Type

Domain|Hostname|...|...|Queue Managers|Queue manager hostname|Queue Manager name|Channels|SYSTEM.DEF.SVRCONN|Configuration Properties:Channel Type = MQCHT_SVRCONN

7

The tables in this appendix give numeric equivalents for all mapped values.

Interval Count—a numeric value, expressed as number of incidents over the last interval.

124 Metrics reference


Metric display sets

The PowerPackNameShort uses a configuration setting for each group of MQMonitor agent metrics, assigning it to one of these sets:

M = Minimum

R = Recommended

F = Full

Each metric is set to membership in one of these sets, which determine whether or not the Investigator displays the metric for each WebSphere MQ component. The Recommended set contains all the metrics in the Minimum set plus additional metrics, and the Full metrics set contains all the metrics.

You can redefine the Recommended metrics set by editing the Advanced Settings section of the MQMonitor.properties file. See the Advanced Settings Section on page 26 for WebSphere MQ and WebSphere MB components.

The default display settings for each MQMonitor agent metric are documented in the Monitoring Level column in the tables in this section. For example, in the Channels Configuration Properties metrics on page 149, the first metric, Channel Disposition, has a default membership in the Full set.

To change the metric set for a given metric, see Special Settings Section on page 25.

Queue Manager Cluster metrics 125

User Guide

Queue Manager Cluster metricsIn the Queue Manager Clusters node, the Investigator displays cluster queues, cluster receiver channels and cluster sender channels with their associated Queue Managers and arranges them by whether they are full or partial repositories. Each cluster Queue Manager under a cluster tree reports additional cluster related attributes and metric data of child objects compared to the normal tree objects.

Cluster workload balance metrics show work distributed over multiple instances of same-named queues. The Investigator displays workload balance metrics on this cluster queue.

Aggregate clusters status metrics

At the top of the Queue Manager Clusters tree, the Investigator displays aggregated status metrics over all clusters, as shown in the illustration above.

Metric name Type Description


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.


Mapped Value Indicates the aggregated status of the clustered Queue Managers. One of:





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

The following sections describe each of these metrics.

Maximum Queue Depth Reached

Mapped Value Indicates whether the maximum queue depth has been reached for any of the clustered queues.

0 = no queue has reached the maximum queue depth

1 = one or more queues have reached the maximum queue depth


Mapped Value Indicates the aggregated connection status of PowerPackNameShort with all the Queue Managers.

0 or green = successful

1 or red = unsuccessful

Channel Instance Count

Mapped Value Aggregation of number of various channel instance that are currently connected to a Queue Manager.



User Guide

Aggregated Queue Manager metrics

For each Queue Manager beneath a host name, the Investigator displays three aggregated status metrics:



Mapped Value Indicates whether any of the channels on the Queue Managers are currently in doubt. Applies only to sending channels. Possible values:

0 = None of the channels are in doubt.

1 = At least one channel is in doubt.


Mapped Value Indicates whether the maximum queue depth has been reached for any of 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





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 this 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_INHIBITED—Get operations are inhibited.

0 = MQQA_GET_ALLOWED—Get operations are allowed.

Aggregated Put Messages Value

Mapped Value Indicates whether put operations have been inhibited for any of the cluster queues on this Queue Manager. One of:

1 = MQQA_PUT_INHIBITED—Put operations are inhibited.

0 = MQQA_PUT_ALLOWED—Put operations are allowed.




For each cluster queue on this Queue Manager, the Investigator displays the following configuration properties:

Maximum Queue Depth (% Queue Full)

Number Percentage of fullness of the queue depth of all of the cluster queues on this Queue Manager.


Mapped Value Indicates whether the maximum queue depth has been reached for any of the cluster queues on this Queue Manager. One of:




Metric name Type Monitoring Level

Description

Base Queue String M Queue name to which the alias resolves.

Cluster Name String F Name of the cluster.

Cluster Queue Manager

String R Name of the Queue Manager managing this queue.

Cluster Queue Type

Mapped Value

M One of:

1 = MQCQT_LOCAL_Q—local

2 = MQCQT_ALIAS_Q—alias

3 = MQCQT_REMOTE_Q—remote

4 = MQCQT_Q_MGR_ALIAS—Queue Manager alias

Default Bind Type

Mapped Value

F Default binding. One of:

0 = MQBND_BIND_ON_OPEN – binding fixed by MQOPEN call.

1 = MQBND_BIND_NOT_FIXED – binding not fixed by MQOPEN call.

Default Priority Number F Default priority.

Description String R Description or label for this Queue Manager.

Get Messages Mapped Value

M Get operations allowed or inhibited.



Max Message Length

Number R Maximum message length.


User Guide

Persistence Mapped Value

F Default persistence of messages on the queue. One of:

1= MQPER_PERSISTENT—The message survives system failures and Queue Manager restarts.

0= MQPER_NOT_PERSISTENT—The message does not normally survive system failures or Queue Manager restarts.

Both persistent and nonpersistent messages can exist on the same queue.

Put Messages Mapped Value

M Put operations allowed or inhibited.



QMID String F Queue Manager name

Queue Depth High Events

Mapped Value

F Enables Queue Depth High events.

0 = MQEVR_DISABLED—Event reporting disabled.

1 = MQEVR_ENABLED—Event reporting enabled.

Queue Depth High Limit

Number F High limit for queue depth

Queue Depth Low Events

Mapped Value

F Enables Queue Depth Low events. One of:



Queue Depth Low Limit

Number F Low limit for queue depth

Queue Name String R Queue name.

Queue Type Mapped Value

M Queue Type.

1 = MQQT_LOCAL—Local queue.

2 = MQQT_MODEL Model queue definition.

3 = MQQT_ALIAS Alias queue definition.

6 = MQQT_REMOTE Local definition of a remote queue.

7 = MQQT_CLUSTER Cluster queue definition.

Remote Queue String M Name of the remote queue as known locally on the remote Queue Manager.

Remote Queue Manager

String M Name of the remote Queue Manager.



Status metrics

For each cluster queue on this Queue Manager, the Investigator displays the following status metrics.

In order to see data for Oldest Message and Queue Time metrics, Queue Monitoring must be enabled in WebSphere MQ. See Turn on Queue Monitoring on page 66.


Description

Alteration Date String

Dynamic

M Date when properties were last altered.

Alteration Time String

Dynamic

M Time when properties were last altered.

Current Queue Depth Number

Dynamic

M Number of messages currently on the queue.

Current Queue Depth Percentage (% Queue Full)

Number

Dynamic

M Percentage of fullness of the queue.

Dequeue Count Interval Count R Number of messages removed from the queue.

Dequeue Count Per 6 Hours

Number R Running count of the number of message dequeues in the last six hours.

Dequeue Count Per Day

Number R Running count of the number of message dequeues in the last day.

Dequeue Count Per Hour

Number R Running count of the number of message dequeues in the last hour.

Dequeue Count Per Minute

Number R Running count of the number of message dequeues in the last minute.

Enqueue Count Interval Count R Number of messages added to the queue, including messages that have been put to the queue, but have not yet been committed.

Enqueue Count Per 6 Hours

Number R Running count of the number of message enqueues in the last six hours.

Enqueue Count Per Day

Number R Running count of the number of message enqueues in the last day.

Enqueue Count Per Hour

Number R Running count of the number of message enqueues in the last hour.

Enqueue Count Per Minute

Number R Running count of the number of message enqueues in the last minute.

Last Get Date String M Date of last Get command.

Last Get Time String M Time of last Get command.


User Guide

Last Put Date String M Date of last Put command.

Last Put Time String M Time of last Put command.

Oldest Message Age (sec)

Number M Age of the oldest message on the queue, in seconds.

Oldest Message Age Per 6 Hours (sec)

Number M Running maximum oldest message age over the last six hours.

Oldest Message Age Per Day (sec)

Number M Running maximum oldest message age over the last day.

Oldest Message Age Per Hour (sec)

Number

Dynamic

M Running maximum oldest message age over the last hour.

Open Input Count Number

Dynamic

M The number of handles that are currently open for input for the queue.

Open Output Count Number

Dynamic

M The number of handles that are currently open for output for the queue.

Queue Monitoring Mapped Value

Dynamic

F Queue monitoring level. Possible values:

-3 = MQMON_Q_MGR—Collect monitoring data according to the setting of the QueueMonitoring Queue Manager attribute. This is the default value.

0 = MQMON_OFF—Online monitoring data collection is turned off for this queue.

17 = MQMON_LOW—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a low rate of data collection for this queue.

33 = MQMON_MEDIUM—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a moderate rate of data collection for this queue.

65 = MQMON_HIGH—If the value of the QueueMonitoring Queue Manager attribute is not MQMON_NONE, online monitoring data collection is turned on, with a high rate of data collection for this queue.

Queue Time (Long Term Avg.)

Number

Dynamic

M Average time, in milliseconds, that a message spent on the queue, based on activity over a longer period.

Compare with Queue Time (Short Term Avg.)


Description



Cluster-Receiver Channel and Cluster-Sender Channel metrics

MQMonitor reports metrics for Cluster-Receiver and Cluster-Sender Channels on separate nodes of the Investigator tree. For each channel, Investigator displays:

Aggregated status metric

Configuration properties

Status metrics

On the Cluster-Receiver Channel node of the tree, the Investigator displays configuration properties and status for each channel.

In the illustration above, notice:

These channels all reside in the Queue Manager named NEWYORK on host host1.

One Cluster-Receiver channel, TO.NEWYORK, with two Queue Managers, NEWYORK and QM_MEDFORD.

The NEWYORK node contains the channel definition metrics. The

Queue Time (Short Term Avg.)

Number

Dynamic

M Average time, in milliseconds, that a message spent on the queue, based on activity over a shorter period.

Compare with Queue Time (Long Term Avg.)

Uncommitted Messages

Number

Dynamic

M Number of uncommitted messages.


Description


User Guide

QM_MEDFORD node contains information about an instance of this channel, which is connected to the Queue Manager named QM_MEDFORD.

Two Cluster-Sender channels, TO.LONDON and TO.MEDFORD, each with a NEWYORK node which has the channel definition metrics for each channel. Additionally, each has a channel instance open to their respective remote Queue Managers:

The channel T0.LONDON has channel instance metrics under QM_LONDON.

The channel T0.MEDFORD has channel instance metrics under QM_MEDFORD.

Channel definitions have the same Queue Manager name as the cluster Queue Manager, whereas the instances have nodes named after the Remote Queue Manager with which they communicate. These channels may be missing some of the following metrics because they are not applicable to that type of channel.


For each channel, the Investigator displays a single status metric:



Mapped Value Indicates whether any of the channels on the Queue Managers are currently in doubt. Applies only to sending channels. Possible values:

0 = none of the channels are in doubt.

1 = at least one channel is in doubt.

Aggregated Channel Instance Counts

Number

Dynamic

Aggregated count of all the channel instances on the Queue Manager.

The Configuration Properties and Status metrics for each Channel definition and Channel instance are listed in the following sections.

Configuration properties

The same set of Configuration properties can appear under the Cluster-Receiver

Channel node and the Cluster-Sender Channel node.


Description

CLWL Channel Priority

Number R Cluster workload channel priority.

CLWL Channel Rank

Number R Cluster workload channel rank.



Status metrics

The same set of status metrics can appear under the Cluster-Receiver Channel

node and the Cluster-Sender Channel node.

CLWL Channel Weight

Number R Cluster workload channel weight.

Channel Name String F Name of the channel definition to be changed, created, tested, reset or deleted. The maximum length of the string is MQ_CHANNEL_NAME_LENGTH.

This parameter is required on all types of channel; on a CLUSSDR it can be different from on the other channel types.

Channel Type Mapped Value

R Specifies the channel type, one of the following:

8 = MQCHT_CLUSRCVR—Cluster receiver channel

9 = MQCHT_CLUSSDR—Cluster sender channel

Cluster Name String F Name of the cluster to which the queue belongs.

Cluster Namelist String F Identifies a namelist object that contains the names of clusters to which this queue belongs.

Queue Manager Name

String R Name of the Queue Manager.


String R The remote Queue Manager this channel connects to.

Transmission Queue Name

String F Name of the transmission queue.


Description


Description

Batches Number M Number of completed batches.

Buffers Received Number M Number of buffers received.

Buffers Sent Number M Number of buffers sent.

Bytes Received Number M Number of bytes received.

Bytes Sent Number M Number of bytes sent.

Current Messages Number M Number of messages in the current batch.

Indoubt Status Mapped Value

M Indicates whether the channel is currently in doubt. Possible values:

0 = MQCHIDS_NOT_INDOUBT— Channel is not in doubt.

1 = MQCHIDS_INDOUBT— Channel is in doubt.

Long Retries Left Number M Number of long retry attempts remaining.


User Guide

MCA Status Mapped Value

M MCA (message channel agent) status. One of:

0 = MQMCAS_STOPPED—Message channel agent stopped.

3 = MQMCAS_RUNNING—Message channel agent running.

Channel Instance Counts

Mapped Value

Dynamic

M Number of instances of channels present currently.

Messages Number M Number of messages.

Overall Channel Status

Mapped Value

M Status of the channel. One of:

0 = MQCHS_INACTIVE—Channel is not active.

1 = MQCHS_BINDING—Channel is negotiating with the partner.

2 = MQCHS_STARTING—Channel is waiting to become active.

3 = MQCHS_RUNNING—Channel is transferring or waiting for messages.

4 = MQCHS_STOPPING—Channel is in process of stopping.

5 = MQCHS_RETRYING—Channel is reattempting to establish connection.

6 = MQCHS_STOPPED—Channel is stopped.

7 = MQCHS_REQUESTING—Requester channel is requesting connection

8 = MQCHS_PAUSED—Channel is paused.

13 = MQCHS_INITIALIZING—Channel is initializing.

Short Retries Left Number M Number of short retry attempts remaining.

Stop Requested Mapped Value

M Whether a stop has been requested. One of:

0 = MQCHSR_STOP_NOT_REQUESTED—User stop request has not been received.

1 = MQCHSR_STOP_REQUESTED—User stop request has been received.


Description




The Configuration Properties node displays properties for the Queue Manager.


Description

Auto CLUSSDR Monitoring

Mapped Value F Setting for online monitoring for automatically defined cluster-sender channels. One of:

-3 = MQMON_Q_MGR—Collection of online monitoring data is inherited from the setting of the Queue Manager's ChannelMonitoring parameter.

0 = MQMON_OFF—Monitoring for the channel is switched off.

17 = MQMON_LOW—Specifies a low rate of data collection with a minimal impact on system performance unless ChannelMonitoring for the Queue Manager is MQMON_NONE. The data collected is not likely to be the most current.

33 = MQMON_MEDIUM—Specifies a moderate rate of data collection with limited impact on system performance unless ChannelMonitoring for the Queue Manager is MQMON_NONE.

65 = MQMON_HIGH—Specifies a high rate of data collection with a likely impact on system performance unless ChannelMonitoring for the Queue Manager is MQMON_NONE. The data collected is the most current available.

Auto CLUSSDR Statistics

Mapped Value F Indicates whether statistics data is to be collected for auto-defined cluster-sender channels (parameter identifier: MQIA_STATISTICS_AUTO_CLUSSDR). One of:

-3 = QMON_Q_MGR—Collection of statistics data is inherited from the setting of the Queue Manager's ChannelStatistics parameter.

0 = MQMON_OFF—Statistics data collection for the channel is switched off.

17 = MQMON_LOW—Specifies a low rate of data collection with a minimal impact on system performance.

33 = MQMON_MEDIUM—Specifies a moderate rate of data collection.

65 = MQMON_HIGH—Specifies a high rate of data collection.

This metric is valid only on AIX, HP-UX, Linux, Solaris, and Windows.

CLWL Channel Priority

Number R Cluster workload channel priority.


User Guide

CLWL Channel Rank

Number R Cluster workload channel rank.

CLWL Channel Weight

Number R Cluster workload channel weight.

CLWL Use Queue

Mapped Value F Specifies whether a Cluster Queue Manager is to use remote puts to other queues defined in other Queue Managers within the cluster during workload management. One of:

0 = MQCLWL_USEQ_LOCAL—Do not use remote queues.

1 = MQCLWL_USEQ_ANY—Use remote queues.

Channel Auto Definition Exit

String F Channel auto-definition exit name. This exit is invoked when an inbound request for an undefined channel is received, if:

1. The channel is a cluster-sender, or

2. Channel auto-definition is enabled.

This exit is also invoked when a cluster-receiver channel is started.

Channel Name String R The name of the channel used to establish communication with this cluster.

Cluster Name String R Name of the Cluster this Queue Manager is a member of.

Cluster Queue Manager Type

Mapped Value R The type of Queue Manager for this cluster. One of:

0 = Normal—A normal Queue Manager.

1 = Repository—A repository Queue Manager.

Dead Letter Queue

String F Name of the local queue that is to be used for undelivered messages.

Description String R Description of the Queue Manager.

Max Handles Number R Maximum number of handles that are currently open for input for the queue.

Max Message Length


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.


Description



Status metrics

Metrics under the Status node show Queue Manager status.

Platform Mapped Value R Platform on which the Queue Manager resides. One of:

1 = MQPL_ZOS—z/OS

3 = MQPL_AIX—AIX (same value as MQPL_UNIX).

3= MQPL_UNIX—UNIX systems.

4 = MQPL_OS400—i5/OS.

12 = MQPL_VMS—HP OpenVMS.

11 = MQPL_WINDOWS_NT—Windows.

13 = MQPL_NSK—Compaq NonStop Kernel.

QMID String F Unique identifier of the Queue Manager.

Queue Manager Name


Repository Name List

String F Name of the list of clusters for which the Queue Manager is providing a repository service.


Description


Description

Alteration Date String M Date when properties were last altered.

Alteration Time String M Time when properties were last altered.

Channel Initiator Status (not available on z/OS)

Mapped Value

M 0 = MQSVC_STATUS_STOPPED or Unknown—Channel Initiator stopped/unknown.

1 = MQSVC_STATUS_STARTING—Channel Initiator starting up.

2 = MQSVC_STATUS_RUNNING—Channel Initiator running.

3 = MQSVC_STATUS_STOPPING—Channel Initiator shutting down.

4 = MQSVC_STATUS_RETRYING—Channel Initiator retrying.

Cluster Queue Manager Suspend

Mapped Value

Dynamic

M Indicates whether the Queue Manager is suspended. One of:

0 = No—not suspended.

1 = Yes—suspended.

Command Server Status (not available on z/OS)

Mapped Value

M One of:

2 = MQQMSTA_RUNNING

0 = Unknown


User Guide

Workload Balance metrics

Workload Balance metrics provide information on queues which have multiple instances within a cluster, residing on more than one Queue Manager.

The Workload Balance tree is organized according to this hierarchy:

Workload BalanceMulti-instance Queue AAggregated metrics across the Queue Managers on this hosthost

Queue Manager 01Configuration PropertiesStatus

Queue Manager 02Multi-instance Queue BAggregated metrics across the Queue Managers on this hosthost

Queue Manager 03

Connection Count (not available on z/OS)

Mapped Value

M Current number of connections to the Queue Manager.

Current Log Extent Name (not available on z/OS)

String F The name of the log extent that was being written to at the time of the Inquire command. If the Queue Manager is using circular logging, this is blank.

Log Path (not available on z/OS)

String F The location of the recovery log extents.

Media Recovery Log Extent Name (not available on z/OS)

String F Name of the oldest log extent required by the Queue Manager to perform media recovery. This is available only on Queue Managers using linear logging. If the Queue Manager is using circular logging, this is blank.


Mapped Value

Dynamic

M One of:

2 = MQQMSTA_RUNNING—Running.

0 = Unknown—Unknown.

Restart Recovery Log Extent Name (not available on z/OS)

String F Name of the oldest log extent required by the Queue Manager to perform restart recovery. This is available only on Queue Managers using linear logging. If the Queue Manager is using circular logging, this is blank.



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.

The illustration below shows a queue INVENTQ which has instances on two Queue Managers, NEWYORK and LONDON, at the same host.

Queue metrics

For each of the Queue Managers on which an instance of the queue resides, the Investigator displays:


Status



Description


Cluster Name String F Name of the cluster.

Cluster Queue Manager

String R Name of the Queue Manager managing this queue.


User Guide

Cluster Queue Type Mapped Value

M One of:

1 = MQCQT_LOCAL_Q—local

2 = MQCQT_ALIAS_Q—alias

3 = MQCQT_REMOTE_Q—remote

4 = MQCQT_Q_MGR_ALIAS—Queue Manager alias

Default Bind Type Mapped Value

F Default binding. One of:

0 = MQBND_BIND_ON_OPEN – binding fixed by MQOPEN call.

1 = MQBND_BIND_NOT_FIXED – binding not fixed by MQOPEN call.

Default Priority Number F Default priority.

Description String R Description or label for this Queue Manager.

Get Messages Mapped Value

M Get operations allowed or inhibited.


1 = MQQA_GET_INHIBITED—Get operations are not allowed.

Max Message Length


Persistence Mapped Value

F Default persistence of messages on the queue. One of:

1 = MQPER_PERSISTENT—The message survives system failures and Queue Manager restarts.

0 = MQPER_NOT_PERSISTENT—The message does not normally survive system failures or Queue Manager restarts.


Put Messages Mapped Value

M Put operations allowed or inhibited.



QMID String F Queue Manager name


Mapped Value

F Enables Queue Depth High events.




Number F High limit for queue depth



Status



Mapped Value

F Enables Queue Depth Low events. One of:




Number F Low limit for queue depth

Queue Name String R Queue name.

Queue Type Mapped Value

M Queue type. One of:

1 = MQQT_LOCAL—Local queue.

2 = MQQT_MODEL Model queue definition.

3 = MQQT_ALIAS Alias queue definition.

6 = MQQT_REMOTE Local definition of a remote queue.

7 = MQQT_CLUSTER Cluster queue definition.





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.


Number

Dynamic


Dequeue Count Interval Count

R Number of messages removed from the queue.


Number R Running count of the number of message dequeues in the last six hours.


Number R Running count of the number of message dequeues in the last day.


User Guide


Number R Running count of the number of message dequeues in the last hour.


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.


Number R Running count of the number of message enqueues in the last six hours.


Number R Running count of the number of message enqueues in the last day.


Number R Running count of the number of message enqueues in the last hour.


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.


Number

Dynamic

M Age of the oldest message on the queue, in seconds.


Number M Running maximum oldest message age over the last six hours.


Number

Dynamic

M Running maximum oldest message age over the last day.


Number

Dynamic



Dynamic

M The number of handles that are currently open for input for the queue on this Queue Manager.


Dynamic

M The number of handles that are currently open for output for the queue on this Queue Manager.


Description



Percent Queue Depth Variation

The % Queue Depth Variation metric shows the deviation of the Queue Depth from a calculated average. The calculation of the variation is based on 2 numbers:

curreqdepth—Current Queue Depth for a specific Queue Manager.

aveqdepth—Average Queue Depth across all Queue Managers on which the cluster queue resides.

The metric is calculated using this formula:








% Queue Depth Variation

Number M Shows the deviation of the Queue Depth from a calculated average. See Percent Queue Depth Variation on page 144.


Number M Average time, in milliseconds, that a message spent on the queue, based on activity over a longer period.



Number M Average time, in milliseconds, that a message spent on the queue, based on activity over a shorter period.



Number M Number of uncommitted messages.


Description


User Guide

% Variation = ((curreqdepth - aveqdepth) / aveqdepth) * 100

Note that when the current queue depth is below average, the Queue Depth Variance is a negative number.

For example: a multi-instance cluster queue runs on three Queue Managers— QM1, QM2 and QM3—with the following current queue depths:

QM1 = 100

QM2 = 140

QM3 = 0

The average queue depth for all three Queue Managers would be calculated:

((100 + 140 + 0) / 3)= 80

% Queue Depth Variance for QM1:

((100 – 80) / 80) * 100 = 25


((140 – 80) / 80) * 100 = 75


((0 – 80) / 80) * 100 = -100

So QM1 deviation is only 25% from the average, while QM3 is -100% (negative 100 percent), correctly indicating a problem with QM3.



Queue Manager metricsThe Investigator displays Queue Manager metrics in a tree with these nodes:

The tree has the following high-level structure:

Queue ManagersAggregated status metrics across all hostsHost name

Aggregated status metrics for all Queue Managers on the hostQueue Manager name

Aggregate status metrics for the Queue ManagerChannel Initiator (z/OS only)ChannelsConfiguration PropertiesDead Letter QueueLast CheckLogs (z/OS only)QueuesStatusUsage (z/OS only)

» Note The Investigator displays aggregated status metrics across hosts, all Queue Managers, and for all queues on a Queue Manager.

Queue Manager metrics 147

User Guide

Top level Queue Manager aggregated metrics

Aggregated status metrics across all hosts

The Investigator displays the following aggregated status metrics for all hosts

reporting WebSphere MQ metrics:







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


Mapped Value Indicates the aggregated status of the Queue Managers. One of:




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 status metrics for each Queue Manager

The Investigator displays the following aggregated status metrics for all the

queues managed by each Queue Manager:







Mapped Value Indicates whether the maximum queue depth has been reached for any of the queues.







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


Mapped Value Indicates the aggregated status of the Queue Managers. One of:




Mapped Value Indicates whether the maximum queue depth has been reached for any of the queues on the Queue Manager.

0 =no queue has reached the maximum queue depth




User Guide

Configuration Properties metrics


Description

Channel Disposition

Mapped Value F Specifies how channels are resolved.

4 = MQCHLD_PRIVATEA receiving channel is private if it was started in response to an inbound transmission directed to the Queue Manager.A sending channel is private if its transmission queue has a disposition other than MQQSGD_SHARED.

2 = MQCHLD_SHAREDA receiving channel is shared if it was started in response to an inbound transmission directed to the queue-sharing group.A sending channel is shared if its transmission queue has a disposition of MQQSGD_SHARED.

Channel Name String R Name of the channel.

Channel Type Mapped Value R Specifies the channel type, one of the following:

1 = MQCHT_SENDER—Sender channel

2 = MQCHT_SERVER—Server channel

3 = MQCHT_RECEIVER—Receiver channel

4 = MQCHT_REQUESTER—Requester channel

5 = MQCHT_ALL—All the channel types are selected.

6 = MQCHT_CLNTCONN—Client connection channel

7 = MQCHT_SVRCONN—Server connection channel

8 = MQCHT_CLUSRCVR—Cluster receiver channel

9 = MQCHT_CLUSSDR—Cluster sender channel

Cluster Name String

Dynamic

F Name of the cluster to which the channel belongs.

Cluster Namelist String

Dynamic

F Identifies a namelist object that contains the names of clusters to which this channel belongs.

Connection Name

String R Internet address of a live connection; if not live, the contents of the ConnectionName field in the channel definition.

Heartbeat Interval

Number F The time, in seconds, between heartbeat flows passed from the sending MCA when there are no messages on the transmission queue.

Keep Alive Interval

Number F Keep alive interval (in seconds).



Max Message Length

Number R Maximum permitted message length.

Non Persistent Message Speed

Mapped Value F Speed of nonpersistent messages. One of:

1 = MQNPMS_NORMAL—Normal speed.

2 = MQNPMS_FAST—Fast speed.

Queue Manager Name



String R Name of the remote Queue Manager.

SSL Certificate User ID (z/OS only)

String F User ID associated with the remote SSL certificate.

Transmission Queue Name

String F Name of the Transmission Queue.

SSL Client Authentication

Integer R Indicates whether the SSL server requires the SSL client to send its digital certificate for authentication. The value can be :

MQSCA_REQUIRED - Client authentication required MQSCA_OPTIONAL - Client authentication is optional

SSL Cipher Spec String R The CipherSpec for the channel to use. SSLCIPH parameter is mandatory if you want your channel to use SSL.

SSL Peer Name String R The Distinguished Name patterns that WebSphere MQ uses to decide the entities from which messages are accepted. The SSLPEER pattern filters the Distinguished Names of the entities.

SSL Short Peer Name

String F The Distinguished Name (DN) of the remote certificate

SSL Certificate Issuer Name

String R Represents the full Distinguished Name (DN) of the remote certificate issuer. The ″issuer″ is the Certification Authority (CA) that issued the certificate.

SSL Crypto Hardware

String F Sets a Queue Manager attribute, SSLCryptoHardware, which holds the name of the parameter string required to configure the cryptographic hardware present on the system. This parameter applies only to Windows and UNIX Queue Managers.


Description


User Guide

Status metrics

SSL Key Repository

String R Sets a Queue Manager attribute, SSLKeyRepository, which holds the name of the SSL key repository.

SSL Reset Count Long Counter R Sets a numeric Queue Manager attribute called SSLKeyResetCount, the total number of unencrypted bytes that are sent and received within an SSL conversation before the secret key is renegotiated. The number of bytes includes control information sent by the message channel agent.


Description

Batch Size Number M Maximum number of messages sent within a batch.

Batches Number

Dynamic

M Number of completed batches.

Buffers Received Number

Dynamic

M Number of buffers received.

Buffers Sent Number

Dynamic

M Number of buffers sent.

Bytes Received Number

Dynamic

M Number of bytes received.

Bytes Sent Number

Dynamic

M Number of bytes sent.

Channel Instance Counts

Mapped Value

Dynamic

M Number of instances of channels present currently.

Current Logical Unit Work ID

String F Logical unit-of-work identifier for current batch of messages.

Current Messages Number

Dynamic

M Number of messages in the current batch.

Current Sequence Number

Number F Sequence number of current message sent or received.

Indoubt Status Mapped Value

Dynamic

M Indicates whether the channel is currently in doubt. Applies only to a sending channel. Possible values:

0 = MQCHIDS_NOT_INDOUBT—Channel is not in doubt.

1 = MQCHIDS_INDOUBT—Channel is in doubt.


Description



Last Logical Unit Work ID

String F Logical unit-of-work identifier for last batch of messages.

Last Message Date String

Dynamic

M Date on which the last message was sent.

Last Message Time String

Dynamic

M Time at which the last message was sent.

Last Sequence Number

Number F Sequence number of last message sent or received.

Long Retries Left Number M Number of long retry attempts remaining.

MCA Status Mapped Value

Dynamic

M MCA (message channel agent) status. One of:

0 = MQMCAS_STOPPED—Message channel agent stopped.

3 = MQMCAS_RUNNING—Message channel agent running.

Messages Number

Dynamic

M Number of messages.

Overall Channel Status

Mapped Value

Dynamic

M Status of the channel. One of:

0 = MQCHS_INACTIVE—Channel is not active.

1 = MQCHS_BINDING—Channel is negotiating with the partner.

2 = MQCHS_STARTING—Channel is waiting to become active.

3 = MQCHS_RUNNING—Channel is transferring or waiting for messages.

4 = MQCHS_STOPPING—Channel is in process of stopping.

5 = MQCHS_RETRYING—Channel is reattempting to establish connection.

6 = MQCHS_STOPPED—Channel is stopped.

7 = MQCHS_REQUESTING—Requester channel is requesting connection

8 = MQCHS_PAUSED—Channel is paused.

13 = MQCHS_INITIALIZING—Channel is initializing.

Short Retries Left Number M Number of short retry attempts remaining.


Description


User Guide


Stop Requested Mapped Value M Whether a stop has been requested. One of:

0 = MQCHSR_STOP_NOT_REQUESTED—User stop request has not been received.

1 = MQCHSR_STOP_REQUESTED—User stop request has been received.

SSL Key Resets Long Counter

Dynamic

R Displays the number of SSL key resets successfully performed for this channel instance. The count of SSL key resets is reset when the channel instance is ended

SSL Key Reset Date String

Dynamic

R Displays the date when the last SSL secret key reset was successfully issued for this channel instance. The date of the last SSL secret key reset is reset when the channel instance is ended.

SSL Key Reset Time String

Dynamic

R Displays the time when the last SSL secret key reset was successfully issued for this channel instance. The time of the last SSL secret key reset is reset when the channel instance is ended.

Metric name Type Monitoring level

Description

Activity Recording Mapped Value

Dynamic

M Indicates whether activity reports can be generated. One of:

0 = MQRECORDING_DISABLED—Activity reports cannot be generated.

1 = MQRECORDING_Q—Activity reports can be generated and sent to SYSTEM.ADMIN.ACTIVITY.QUEUE.

2 = MQRECORDING_MSG—Activity reports can be generated and sent to the destination specified by the originator of the message causing the report.

Adopt New MCA Check (z/OS only)

Mapped Value F Identifies the MCA Check setting. One of:

0 = MQADOPT_CHECK_NONE—Do not check any elements.

1 = MQADOPT_CHECK_ALL—Check the Queue Manager name and network address. If possible, perform this check to protect your channels from being shut down, inadvertently or maliciously. This is the default value.

2 = MQADOPT_CHECK_Q_MGR_NAME—Check the Queue Manager name.

4 = QADOPT_CHECK_NET_ADDR—Check the network address.


Description



Adopt New MCA Type (z/OS only)

Mapped Value F Whether an orphaned instance of an MCA should

be restarted automatically when a new inbound

channel request matching the AdoptNewMCACheck

parameter is detected. One of:

0 = MQADOPT_TYPE_NO: Do not adopt orphaned

channel instances.

1 = MQADOPT_TYPE_ALL: Adopt all channel types.

This is the Queue Manager’s initial default value.

Authority Events Mapped Value F Indicates Authorization Event enabled.



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 Manager’s initial default value.

1 = MQTRAXSTR_YES: Channel initiator trace is to start automatically.

Channel Initiator Trace Table Size (z/OS only)

Number F Size, in megabytes, of the channel initiator’s trace data space.

Channels Using LU62 (z/OS only)

Number R The maximum number of channels that can be current, or clients that can be connected, that use the LU 6.2 transmission protocol.

Channels Using TCP (z/OS only)

Number R The maximum number of channels that can be current, or clients that can be connected, that use the TCP/IP transmission protocol.

Coded Character Set ID

Number F Coded character set identifier.


Description


User Guide

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.

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_500—System for MQSeries v5.0

510 = MQCMDL_LEVEL_510—System for MQSeries v.5 release 1

520 = MQCMDL_LEVEL_520—System for MQSeries v.5 release 2

530 = MQCMDL_LEVEL_530—System for WebSphere MQ v.5 release 3


600 = MQCMDL_LEVEL_600—System for WebSphere MQ v6

700 = MQCMDL_LEVEL_700—System for WebSphere MQ v7

Configuration Events (z/OS only)

Mapped Value F Controls whether configuration events are generated.

0 = MQEVR_DISABLED: Event reporting disabled.


Dead Letter Queue String F Indicates the Dead Letter Queue of the Queue Manager.


Description



Default Transmission Queue

String R Indicates the default transmission queue of the Queue Manager

Description String R Description of the Queue Manager.

Distribution Lists Mapped Value F Indicates Distribution List enabled.

0 = MQDL_NOT_SUPPORTED—Distribution lists not supported.

1 = MQDL_SUPPORTED—Distribution lists supported.

DNS Group Name (z/OS only)

String F The name of the group that the TCP listener handling inbound transmissions for the queue-sharing group should join when using Workload Manager for Dynamic Domain Name Services support (DDNS).

Expiry Interval (z/OS only)

Number F Frequency with which the Queue Manager scans the queues looking for expired messages.


Description


User Guide

IGQ Authority Check Type (z/OS only)

Mapped Value F Type of authority checking and, therefore, the user IDs to be used by the IGQ agent (IGQA). This establishes the authority to put messages to a destination queue. Acceptable values:

1 = MQIGQPA_DEFAULT: Default user identifier is used. The user identifier used for authorization is the value of the UserIdentifier field in the separate MQMD that is associated with the message when the message is on the shared transmission queue. This is the user identifier of the program that placed the message on the shared transmission queue, and is usually the same as the user identifier under which the remote Queue Manager is running. If the RESLEVEL profile indicates that more than one user identifier is to be checked, the user identifier of the local IGQ agent (IGQUserId) is also checked.

2 = MQIGQPA_CONTEXT: Context user identifier is used. The user identifier used for authorization is the value of the UserIdentifier field in the separate MQMD that is associated with the message when the message is on the shared transmission queue. This is the user identifier of the program that placed the message on the shared transmission queue, and is usually the same as the user identifier under which the remote Queue Manager is running. If the RESLEVEL profile indicates that more than one user identifier is to be checked, the user identifier of the local IGQ agent (IGQUserId) and the value of the UserIdentifier field in the embedded MQMD are also checked. The latter user identifier is usually the user identifier of the application that originated the message.

3 = MQIGQPA_ONLY_IGQ: Only the IGQ user identifier is used. The user identifier used for authorization is the user identifier of the local IGQ agent (IGQUserId). If the RESLEVEL profile indicates that more than one user identifier is to be checked, this user identifier is used for all checks.

4 = MQIGQPA_ALTERNATE_OR_IGQ: Alternate user identifier or IGQ-agent user identifier is used. The user identifier used for authorization is the user identifier of the local IGQ agent (IGQUserId). If the RESLEVEL profile indicates that more than one user identifier is to be checked, the value of the UserIdentifier field in the embedded MQMD is also checked. This user identifier is usually the user identifier of the application that originated the message.


Description



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.



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.


Description


User Guide

Maximum Uncommitted Messages

Number R Maximum number of uncommitted messages within a unit of work. Calculated as:

The number of messages that can be retrieved + The number of messages that can be put on a queue + Any trigger messages generated within this unit of work under any one syncpoint.

This limit does not apply to messages that are retrieved or put outside syncpoint.

Minimum Outbound Port (z/OS only)

Number F Minimum value in the range for the binding of outgoing channels.

Minimum Receive Timeout (z/OS only)

Number R The minimum length of time that a TCP/IP channel waits to receive data, including heartbeats, from its partner before returning to the inactive state.

Performance Events Mapped Value R Whether or not Performance Events are enabled.

0 = MQEVR_DISABLED—Event reporting disabled. No queue reached maximum queue depth.


2 = MQEVR_EXCEPTION—Performance event exception.

Platform Mapped Value R Platform on which the Queue Manager resides. One of:

1 = MQPL_ZOS—z/OS

3 = MQPL_AIX—AIX (same value as MQPL_UNIX).

3= MQPL_UNIX—UNIX systems.

4 = MQPL_OS400—i5/OS.

12 = MQPL_VMS—HP OpenVMS.

11 = MQPL_WINDOWS_NT—Windows.

13 = MQPL_NSK—Compaq NonStop Kernel.

QMID String F Unique Queue Manager Identifier.

Queue Manager Name


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.


Description



Receive Timeout Type (z/OS only)

Mapped Value R The qualifier to apply to ReceiveTimeoutType to calculate how long a TCP/IP channel waits to receive data, including heartbeats, from its partner before returning to the inactive state.

0 = MQRCVTIME_MULTIPLY: The ReceiveTimeout value is a multiplier to be applied to the negotiated value of HeartbeatInterval to determine how long a channel waits. This is the Queue Manager’s initial default value.

1 = MQRCVTIME_ADD: ReceiveTimeout is a value, in seconds, to be added to the negotiated value of HeartbeatInterval to determine how long a channel waits.

2 = MQRCVTIME_EQUAL: ReceiveTimeout is a value, in seconds, representing how long a channel waits.

Receiver Server-Connection Channels Auto-Defined

Mapped Value F Indicates CHAD enabled.

0 = MQCHAD_DISABLED—Event reporting disabled.

1 = MQCHAD_ENABLED—Event reporting enabled.

Remote Events Mapped Value F Indicates Remote Error Event enabled.



Repository Name String F The name of a cluster for which this Queue Manager is to provide a repository service.

Repository Name List String F The name of a list of clusters for which this Queue Manager is to provide a repository service.

Shared Queue Manager Name (z/OS only)

Mapped Value R Shared-queue Queue Manager name. When a Queue Manager makes an MQOPEN call for a shared queue and the Queue Manager that is specified in the ObjectQmgrName parameter of the MQOPEN call is in the same queue-sharing group as the processing Queue Manager, the SQQMNAME attribute specifies whether the ObjectQmgrName is used or whether the processing Queue Manager opens the shared queue directly. Acceptable values:

0 = MQSQQM_USE: ObjectQmgrName is used and the appropriate transmission queue is opened.

1 = MQSQQM_IGNORE: The processing Queue Manager opens the shared queue directly. This can reduce the traffic in your Queue Manager network.


Description


User Guide

SSL Event Mapped Value R Indicates whether or not SSL Events are enabled.

1 = MQEVR_ENABLED

0 = MQEVR_DISABLED

SSL Key Repository String R Sets a Queue Manager attribute, SSLKeyRepository, which holds the name of the SSL key repository.

SSL CRL Name List String F Sets a Queue Manager attribute that holds the namelist of authentication information objects.

SSL Crypto Hardware String F Sets a Queue Manager attribute, SSLCryptoHardware, which holds the name of the parameter string required to configure the cryptographic hardware present on the system. This parameter applies only to Windows and UNIX Queue Managers.

SSL Reset Count Long Counter R Sets a numeric Queue Manager attribute called

SSLKeyResetCount, the total number of unencrypted bytes that are sent and received within an SSL conversation before the secret key is renegotiated. The number of bytes includes control information sent by the message channel agent.

SSL FIPS Required Integer F The value can be:

0 = MQSSL_FIPS_NO - Any supported CipherSpec can be used.

1 = MQSSL_FIPS_YES - Only FIPS-certified cryptographic algorithms must be used.

SSL Task (z/OS only) Number F Number of server subtasks to use for processing SSL calls.

Start And Stop Events

Mapped Value R Indicates whether or not Start and Stop Events are enabled.

1 = MQEVR_ENABLED

0 = MQEVR_DISABLED

Sync Point Mapped Value F Indicates whether Syncpoint is available.

0 = MQSP_NOT_AVAILABLE—Units of work and syncpointing not available.

1 = MQSP_AVAILABLE—Units of work and syncpointing available.


Description

/bin/edit/Ecosystem/SSLKeyResetCount?topicparent=Ecosystem.MQPPTNRSSLChannel(POC)



Dead Letter Queue metrics

The Dead Letter Queue node can contain all the metrics that appear under a regular queue. See the lists under Queue metrics on page 164.

TCP Keep Alive (z/OS only)

Mapped Value F Indicates whether the TCP KEEPALIVE facility is to be used to check whether the other end of a connection is still available. One of:

0 = MQTCPKEEP_NO—The TCP KEEPALIVE Facility is not to be used. This is the Queue Manager’s initial default value.

1 = MQTCPKEEP_YES—The TCP KEEPALIVE Facility is to be used as specified in the TCP profile configuration data set. The interval is specified in the KeepAliveInterval channel attribute

TCP Name (z/OS only)

String F Name of the TCP/IP system that you are using.

TCP Stack Type (z/OS only)

Mapped Value F Indicates whether the channel initiator may use only the TCP/IP address space specified in TCPName, or may optionally bind to any selected TCP/IP address. Acceptable values:

0 = MQTCPSTACK_SINGLE—The channel initiator may only use the TCP/IP address space specified in TCPName. This is the Queue Manager’s initial default value.

1 = MQTCPSTACK_MULTIPLE—The channel initiator may use any TCP/IP address space available to it. It defaults to the one specified in TCPName if no other is specified for a channel or listener.

Trigger Interval Number F Trigger interval, expressed in milliseconds, for use only with queues where TriggerType has a value of MQTT_FIRST.

Workload Manager Register Status (z/OS only)

Mapped Value F Indicates whether the TCP listener that handles inbound transmissions for the queue-sharing group should register with Workload Manager (WLM) for DDNS.

0 = MQDNSWLM_NO—The listener is not to register with WLM. This is the Queue Manager’s initial default value.

1 = MQDNSWLM_YES—The listener should register with WLM.


Description


User Guide

Last Check metrics

The Last Check metrics contain information about the last time the Queue

Manager was queried.


Description

Description String M Queue Manager description.

Queue Manager Name String M Queue Manager name.

Agent-MQ Connection Status

String M Indicates whether or not PowerPackNameShort can successfully connect to the Queue Managers.



Timestamp String M Indicates the system timestamp of Agent-MQ Connection Status.



Queue metrics



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.


Cluster Name String F Name of the cluster to which the queue belongs.

Cluster Namelist String F Identifies a namelist object that contains the names of clusters to which this queue belongs.

Coupling Facility Name (z/OS only)

String F The name of the coupling facility where messages on the queue are stored.

Creation Date String F Queue creation date.

Creation Time String F Queue creation time.

Default Bind Type Mapped Value F Describes binding mechanism. One of:

0 = MQBND_BIND_ON_OPEN—Binding fixed by MQOPEN call.

1 = MQBND_BIND_NOT_FIXED—Binding not fixed by MQOPEN call.

Default Priority Number F Default priorities for messages on the queue. Can be any number from 0 to MQIA_MAX_PRIORITY.

Definition Type Mapped Value R Queue definition type.

1 = MQQDT_PREDEFINED—Predefined permanent queue.

2 = MQQDT_PERMANENT_DYNAMIC—Dynamically defined permanent queue.

3 = MQQDT_TEMPORARY_DYNAMIC—Dynamically defined temporary queue.

4 = MQQDT_SHARED_DYNAMIC

Description String R Description of the queue.

Distribution Lists Mapped Value F 0 = MQDL_NOT_SUPPORTED—Distribution lists not supported.

1 = MQDL_SUPPORTED—Distribution lists supported.


User Guide

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_HARDENED—Backout count may not be remembered.

1 = MQQA_BACKOUT_HARDENED—Backout count remembered.

Index Type (z/OS only)

Mapped Value F Specifies the type of index maintained by the Queue Manager to expedite MQGET operations on the queue.

The value can be:

0 = MQIT_NONE—No index.

1 = MQIT_MSG_ID—The queue is indexed using message identifiers.

2 = MQIT_CORREL_ID—The queue is indexed using correlation identifiers.

3 = MQIT_MSG_TOKEN—The queue is indexed using message tokens.

4 = MQIT_GROUP_ID—The queue is indexed using group identifiers.

Initiation Queue String F Name of the initiation queue.

Max Message Length


Max Queue Depth Number

Dynamic

M Maximum number of messages allowed on queue.

Message Delivery Sequence

Mapped Value F Message delivery sequence.

0 = MQMDS_PRIORITY—if priority is relevant

1 = MQMDS_FIFO—first-in, first-out

Persistence Mapped Value F Default persistence of messages on the queue. One of:

1 = MQPER_PERSISTENT—The message survives system failures and Queue Manager restarts.

0 = MQPER_NOT_PERSISTENT—The message does not normally survive system failures or Queue Manager restarts.


Process Name String F Name of the process.


Description



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_ALL—The object is defined as MQQSGD_Q_MGR or MQQSGD_COPY. If there is a shared Queue Manager environment, and the command is being executed on the Queue Manager where it was issued, this option also displays information for objects defined with MQQSGD_GROUP. If MQQSGD_LIVE is specified or defaulted, or if MQQSGD_ALL is specified in a shared Queue Manager environment, the command might give duplicated names (with different dispositions).

0 = MQQSGD_Q_MGR—The object has queue-manager disposition: the object definition is known only to the local Queue Manager; the definition is not known to other Queue Managers in the queue-sharing group.

1 = MQQSGD_COPY—The object is a local copy of a master object definition that exists in the shared repository. Each Queue Manager in the queue-sharing group can have its own copy of the object.

2 = MQQSGD_SHARED—The object has shared disposition. This means that there exists in the shared repository a single instance of the object that is known to all Queue Managers in the queue-sharing group. When a Queue Manager in the group accesses the object, it accesses the single shared instance of the object.

3 = MQQSGD_GROUP—The object definition resides in the shared repository. The object was defined using a command that had the parameter MQQSGD_GROUP.

4 = MQQSGD_PRIVATE—Clear the private queue named in QName. The queue is private if it was created using a command with the attributes MQQSGD_PRIVATE or MQQSGD_Q_MGR. This is the default value.

6 = MQQSGD_LIVE—The object is defined as MQQSGD_Q_MGR or MQQSGD_COPY. This is the default value if the parameter is not specified.


Description


User Guide

Queue Default Input Open Option

Mapped Value F Default input open option for defining whether queues can be shared. One of:

2 = MQOO_INPUT_SHARED - Open queue to get messages with shared access.

4 = MQOO_INPUT_EXCLUSIVE - Open queue to get messages with exclusive access.


Mapped Value F Enables Queue Depth High events.




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.


Mapped Value F Enables Queue Depth Low events. One of:




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_NONE—No queue service interval events enabled.

1 = MQQSIE_HIGH—Queue Service Interval High events enabled.

2 = MQQSIE_OK—Queue Service Interval OK events enabled.

Queue Type Mapped Value M Queue Type.

1 = MQQT_LOCAL—local queue.

2 = MQQT_MODEL—model queue definition

3 = MQQT_ALIAS—alias queue definition

7 = MQQT_CLUSTER—cluster queue definition

6 = MQQT_REMOTE—local definition of a remote queue.


Description






Retention Interval Number F Period of time (in hours, beginning from creation time of the queue) to retain the queue, after which the queue is eligible for deletion.

Scope Mapped Value F Scope of the queue definition.

1 = MQSCO_Q_MGR—Queue-manager scope.

2 = MQSCO_CELL—Cell scope.

Shareability Mapped Value F Indicates whether queue can be shared or is opened for exclusive use.

0 = MQQA_NOT_SHAREABLE—Queue is not shareable.

1 = MQQA_SHAREABLE—Queue is shareable.

Storage Class Name (z/OS only)

String F Name of the storage class.

Transmission Queue

String R Transmission queue name.

Trigger Control Mapped Value F Trigger control.

0 = MQTC_OFF

1 = MQTC_ON

Trigger Data String F Data or message which the Queue Manager inserts into a trigger message when a message arriving on this queue causes a trigger message to be written to the initiation queue.

Trigger Depth Number F Number of messages of a certain priority (TriggerMsgPriority) or greater which must be on the queue before a trigger message can be written. Must be 1 or greater.

Trigger Message Priority

Number F Trigger threshold based on message priority.


Description


User Guide

Status metrics


Trigger Type Mapped Value F Trigger type.

0 = MQTT_NONE—No trigger messages.

1 = MQTT_FIRST—Trigger message when queue depth goes from 0 to 1.

2 = MQTT_EVERY—Trigger message for every message.

3 = MQTT_DEPTH—Trigger message when depth threshold exceeded.

Usage Mapped Value M 0 = MQUS_NORMAL—Normal usage.

1 = MQUS_TRANSMISSION—Transmission queue.


Description


Description


Dynamic



Dynamic



Dynamic

M Number of messages on queue.


Number

Dynamic


Dequeue Count Interval Count

Dynamic

R Number of messages removed from the queue.


Number

Dynamic

R Running count of the number of message dequeues in the last six hours.


Number

Dynamic

R Running count of the number of message dequeues in the last day.


Number

Dynamic

R Running count of the number of message dequeues in the last hour.


Number

Dynamic

R Running count of the number of message dequeues in the last minute.



Enqueue Count Interval Count

Dynamic

R Number of messages added to the queue, including messages that have been put to the queue, but have not yet been committed.


Number

Dynamic

R Running count of the number of message enqueues in the last six hours.


Number

Dynamic

R Running count of the number of message enqueues in the last day.


Number

Dynamic

R Running count of the number of message enqueues in the last hour.


Number

Dynamic

R Running count of the number of message enqueues in the last minute.

Last Get Date String

Dynamic

M Date of last Get command.

Last Get Time String

Dynamic

M Time of last Get command.

Last Put Date String

Dynamic

M Date of last Put command.

Last Put Time String

Dynamic

M Time of last Put command.

Media Recovery Log Extent Name

String

Dynamic

F Name of the earliest log extent required to perform media recovery.


Number

Dynamic

M Age of the oldest message on the queue, in seconds.


Number

Dynamic

M Running maximum oldest message age over the last six hours.


Number

Dynamic

M Running maximum oldest message age over the last day.


Number

Dynamic



Dynamic

M Number of handles that are currently valid for removing messages from the queue.


Dynamic

M Number of handles that are currently valid for adding messages to the queue


Description


User Guide


Dynamic








Number M Average time, in milliseconds, that a message spent on the queue, based on activity over a longer period.



Number M Average time, in milliseconds, that a message spent on the queue, based on activity over a shorter period.



Number

Dynamic

M Number of uncommitted messages.


Description



Channel Initiator metrics

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

Configuration settings


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


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.


User Guide

Active Channels Started

Number

Dynamic

R The number of active channel connections that have started.

Active Channels Stopped

Number

Dynamic

M The number of active channel connections that have stopped, requiring manual intervention.

Active Dispatchers Number

Dynamic

R The number of active dispatchers.

Active SSL Tasks Number

Dynamic

R The number of active SSL server subtasks.

Channel Initiator Status

Mapped Value

Dynamic

M Status of the channel initiator. One of:

0 = MQSVC_STATUS_STOPPED or Unknown—stopped/unknown.

1 = MQSVC_STATUS_STARTING—starting.

2 = MQSVC_STATUS_RUNNING—running.

3 = MQSVC_STATUS_STOPPING—stopping.

4 = MQSVC_STATUS_RETRYING—retrying.

Current Channel Connections

Number

Dynamic

M The number of current channel connections.


Description



Log metrics

Log metrics are reported for Queue Managers running on z/OS hosts only.

For each of the logs configured by an administrator on a Queue Manager, the metrics are divided into three groups—Configuration Properties, Log Copy Records, Status. The following illustration shows the Log metrics:



Description

Archive Status Mapped Value R Specifies whether archiving is on or off. One of:

0 = No—no archiving.

1 = Yes—archiving is on.

Deallocation Interval

Number R Specifies the length of time, in minutes, that an allocated archive read tape unit is allowed to remain unused before it is deallocated.

The value can be in the range zero through 1440. If it is zero, the tape unit is deallocated immediately. If it is 1440, the tape unit is never deallocated.


User Guide

Dual Archive Logging

Mapped Value R Specifies whether dual archive logging is being used. One of:

0 = No—no dual archive archiving.

1 = Yes—dual archive logging is on.

Dual BSDS Logging Mapped Value R Specifies whether dual BSDS is being used. One of:

0 = No—no dual BSDS.

1 = Yes—dual BSDS is on.

Dual Logging Mapped Value R Specifies whether dual logging is being used. One of:

0 = No—no dual logging.

1 = Yes—dual logging is on.

Input Buffer Size Number R Specifies the size of input buffer storage for active and archive log data sets.

Log Suspend Status Mapped Value R Specifies whether logging is suspended. One of:

0 = No—log is not suspended.

1 = Yes—log has been suspended.

Maximum Archive Log

Number R Specifies the maximum number of archive log volumes that can be recorded in the BSDS.

Maximum Tape Units

Number R Specifies the maximum number of dedicated tape units that can be allocated to read archive log tape volumes.

Output Buffer Count

Number R Specifies the number of output buffers to be filled before they are written to the active log data sets.

Output Buffer Size Number R Size of output buffer storage for active and archive log data sets.

Parameter Type Mapped Value R Specifies how the parameters are to be reset. One of:

10 = MQSYSP_TYPE_INITIAL—The initial settings of the log parameters.

11 = MQSYSP_TYPE_SET—The settings of the log parameters if they have been altered since

their initial setting.

12 = MQSYSP_TYPE_LOG_COPY—Information relating to the active log copy.

13 = MQSYSP_TYPE_LOG_STATUS—Information relating to the status of the logs.

Queue Manager Start Date

String R The date on which the Queue Manager was started, in the form yyyy-mm-dd.

Queue Manager Start Time

String R The time that the Queue Manager was started, in the form hh.mm.ss.


Description



Log Copy Records


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


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.


User Guide

Usage metrics

Under the Usage node, you can see two sub-nodes:

Buffer Pools

For each of the buffer pools configured by an administrator on a Queue Manager, the metrics are divided into two groups:


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

The following illustration shows the Usage node, containing Buffer Pools and Page Sets:





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



s



Description

Buffer Pool ID Number R Buffer pool identifier.

Page Set Expand Count

Number R The number of times the page set has been dynamically expanded since restart.

Page Set Expand Type

Mapped Value R How the Queue Manager expands a page set when it becomes nearly full, and further pages are required within it. One of:

1 = MQUSAGE_EXPAND_USER—The secondary extent size that was specified when the page set was defined is used. If no secondary extent size was specified, or it was specified as zero, then no dynamic page set expansion can take place. At restart, if a previously used page set has been replaced with a data set that is smaller, it is expanded until it reaches the size of the previously used data set. Only one extent is required to reach this size.

2 = MQUSAGE_EXPAND_SYSTEM—A secondary extent size that is approximately 10 per cent of the current size of the page set.

3 = MQUSAGE_EXPAND_NONE—No further page set expansion is to take place.

Page Set ID Number R Page set identifier; a two digit number from 00 to 99.

Queue Manager Name

String R The name of the Queue Manager that generates responses.

Usage Type Mapped Value R The type of information to be returned. One of:

MQIACF_USAGE_PAGESET—Return page set and buffer pool information.

MQIACF_USAGE_DATA_SET—Return data set information for log data sets.

MQIACF_USAGE_ALL—Return page set and data set information.


User Guide

Status metrics


Description

Page Set Status Mapped Value

Dynamic

M Current status of the page set. One of:

0 = MQUSAGE_PS_AVAILABLE—The page set is available.

1 = MQUSAGE_PS_DEFINED—The page set has been defined but has never been used.

2 = MQUSAGE_PS_OFFLINE—The page set is currently not accessible by the Queue Manager, for example because the page set has not been defined to the Queue Manager.

3 = MQUSAGE_PS_NOT_DEFINED—The command was issued for a specific page set that is not defined to the Queue Manager.

Pages Holding Non Persistent Data

Number

Dynamic

M The number of pages holding non-persistent message data.

Pages Holding Persistent Data

Number

Dynamic

M The number of pages used to store object definitions and persistent message data.

Total Pages Number

Dynamic

M The total number of 4KB pages in the page set.

Unused Pages Number

Dynamic

M The number of pages that are not used and hence available.



Queue Manager Status metrics


Description

Active Channels (z/OS only)

Number

Dynamic

M Number of active channels.


Dynamic



Dynamic


Channel Initiator Dispatchers (z/OS only)

Number

Dynamic

M Number of dispatchers.

Channel Initiator Status (not available on z/OS)

Mapped Value

Dynamic

M 0 = MQSVC_STATUS_STOPPED or unknown—Channel Initiator stopped/unknown.

1 = MQSVC_STATUS_STARTING—Channel Initiator starting up.

2 = MQSVC_STATUS_RUNNING—Channel Initiator running.

3 = MQSVC_STATUS_STOPPING—Channel Initiator shutting down.

4 = MQSVC_STATUS_RETRYING—Channel Initiator retrying.

Command Server Status (not available on z/OS)

Mapped Value

Dynamic

M One of:

2 = MQQMSTA_RUNNING—RUNNING.

0 = Unknown—UNKNOWN.

Connection Count (not available on z/OS)

Mapped Value

Dynamic

M Current number of connections to the Queue Manager.

Current Log Extent Name (not available on z/OS)

String

Dynamic

F The name of the log extent that was being written to at the time of the Inquire command. If the Queue Manager is using circular logging, this is blank.

Log Path (not available on z/OS)

String

Dynamic

F The location of the recovery log extents.

Media Recovery Log Extent Name (not available on z/OS)

String

Dynamic

F Name of the oldest log extent required by the Queue Manager to perform media recovery. This is available only on Queue Managers using linear logging. If the Queue Manager is using circular logging, this is blank.

Message Broker metrics 181

User Guide

Message Broker metricsThe Investigator displays Message Broker metrics in a tree with these nodes:


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.



For each Message Broker that you configure to send metrics to Introscope, you can view the following:

Broker properties

Metrics for each execution group

Metrics for the Queue Manager belonging to the Message Broker

The following sections describe each of the metrics you can find under these nodes.

» Note The intervals used by the Message Broker metrics can vary.

Aggregate metrics and “traffic lights” are based on calculations done by the Introscope Enterprise Manager, which uses a default interval. This is almost always 15 seconds.

Message Flow metrics are based on reports from WebSphere Message Broker and use Message Broker’s default interval, which is always 20 seconds.

Metrics returned by the CMP (Configuration Manager Proxy) are based on the results of queries that are sent at a frequency which the administrator defines using the Static Delay Time setting in the MBMonitor.properties file. See CMP Connection Section (mandatory) on page 34.

Configuration Manager aggregate totals

Under the Configuration Manager node, the Investigator displays the aggregated Message Flow statistics and Broker Statistics, aggregated to the level of the Configuration Manager, as described in the following table.


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.


User Guide

Broker properties and aggregate totals

Under the Configuration Manager metrics, the Investigator displays a node for the broker. This node displays broker properties and aggregate metrics for all Execution Groups managed by the broker.

The totals are calculated and have a 15 second interval, and everything else comes from CMP basic topology.


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.


Number Aggregate total of dropped messages across all Execution Groups configured on this broker.

Number of Subcomponents

Number Number of subcomponents of this Broker.

Shared Object String TRUE—Broker is shared.FALSE—Broker is not shared.

Timeouts Total Number Number of timeouts.

UUID String Unique identifier for this Broker.



Execution Groups metrics

Execution Groups are logical groupings of message flows within a broker.

The four metrics shown under the Execution Groups node are aggregated across all Execution Groups on the broker


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


User Guide

Execution Group properties and aggregate metrics

The calculated metrics roll up data from the message flows in that execution group.


Architecture String This identifies the processor architecture of the Execution Group. Following values are reported to Introscope for different architecture execution groups:

32-bit for 32-bit architecture64-bit for 64-bit architecturedefault for default architecture

Backouts Total Number Aggregate total of messages backed out across all Message Flows in this Execution Group.

Component Runstate String Indicates whether the Execution Group is RUNNING or STOPPED.

Errors Total Number Aggregate total of errors reported across all Message Flows in this Execution Group.

Messages Dropped Total Number Aggregate total of dropped messages across all message flows configured under this Execution Group. Calculated by adding the following Client Statistics:

Disconnected Messages Dropped TotalMessages Dropped Total

Number of Subcomponents

Number Number of message flows and message sets under this Execution Group.

Shared Object String TRUE—Execution Group is shared.FALSE—Execution Group is not shared.

Timeouts Total Number Aggregate total of timeouts across all Message Flows in this Execution Group.

UUID String Unique identifier for the Execution Group

Broker statistics

Some Execution Groups publish Broker Statistics, also known as publish/subscribe statistics. They provide information about the performance of brokers and the throughput between clients that are connected to the broker.

As shown in the illustration below, the Broker Statistics node contains 3 summary nodes:

Client statistics—message throughput between the broker and clients that are connected to the broker.

Neighbor statistics—message throughput between the broker and any other brokers with which it has been configured as a neighbor to share publications and subscriptions.



Wide Statistics—subscriber, client and neighbor counts for the broker.

Client and Neighbor Statistics report the metrics in the table below. The Wide Statistics node reports only summary counts which are self-explanatory.

» Note Totals are reported from the time the broker was started, not from an interval, and are cumulative.

Client and Neighbor statistics

Client Statistics report on message throughput between clients connected to the broker. Neighbor Statistics report on message throughput between brokers which

have been configured as neighbors.


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.


User Guide

Wide Statistics


Description

Client Count Total Number M The total number of clients that are connected to the broker.

Neighbor Count Total Number M The total number of neighbor brokers that are connected to the broker.

Subscription Count Total

Number M The number of subscriptions held by the broker.

Statistics generated by Publication Node

In general, each node provides one statistics element. However, the Publication node is split into five types of nodes and appears five times in the statistics.

Bytes Queued Total Number F The number of bytes of data that are currently queued by the broker for delivery to clients/neighboring brokers.

Bytes Received Total Number R The total number of bytes that have been received by the broker from its clients/neighboring brokers.

Bytes Sent Total Number R The total number of bytes that the broker has delivered to its clients/neighboring brokers.

Bytes Sent Without Being Queued Total

Number F The total number of bytes of data that were sent immediately to clients/neighboring brokers, without being queued internally by the broker.

Disconnected Bytes Dropped Total

Number F The number of bytes that have been dropped due to queue overflow, where the client/neighboring broker was subsequently disconnected from the broker.

Disconnected Messages Dropped Total

Number M The number of messages that have been dropped due to queue overflow, where the client/neighboring broker was subsequently disconnected from the broker.


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.



For example, when you subscribe to the Surfwatch MessageFlow in the PagerExecutionGroup in the IBM Pager sample, you can see statistics reported for a single publication under five different nodes:

<NodeStatistics Label="Publish Reports.ComIbmMQOutput" Type="MQOutputNode" ...

<NodeStatistics Label="Publish Reports.ComIbmMQeOutput" Type="MQeOutputNode" ...

<NodeStatistics Label="Publish Reports.ComIbmPSService" Type="PSServiceNode" ...

<NodeStatistics Label="Publish Reports.ComIbmSCADAOutput" Type="SCADAOutputNode"

<NodeStatistics Label="Publish Reports.Response" Type="MQOutputNode" ...

Message Flow statistics

A Message Flow contains two or more Message Nodes.

Each of the Message Flows under an Execution Group reports the following statistics:

Message Flow properties and aggregate metrics covering all Message Nodes under the Message Flow

Errors—Error statistics for the Message Flow

Message Flow Invocations—Total number of invocations during the interval being monitored.

Message Statistics—Statistics regarding count and size of messages during the interval being monitored.

Node Statistics (if the Message Flow has been configured to report them)—Statistics for each of the Message Nodes

Performance—Performance statistics for the Message Flow

Data collection rules

Accounting and statistics data is collected only for message flows that start with an MQInput, HTTPInput, or user-defined input node.

Data collection follows these rules:

If you start data collection for a message flow that starts with one of these nodes, the data is collected for all built-in and user-defined nodes, including those in subflows.

If the message flow starts with another input node (for example, a Real-timeInput node), no data is collected (and no errors are reported).


User Guide

Intervals

Message flow metrics use a 20-second interval, except for calculated aggregates, which run on the Enterprise Manager and use a 15-second interval.

Aggregate metrics across all Message Flows

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


Description

Backouts Total Number M Total number of backouts occurring across all Message Flows

Errors Total Number M Total number of errors occurring across all Message Flows, calculated by adding:

MQ Errors TotalMessages With Errors Total Processing Errors Total

Timeouts Total Number M Total number of timeouts occurring across all Message Flows

Properties and aggregate metrics for each Message Flow

Under each individual Message Flow, you can see several metrics mixed together:

Message Flow properties (for example, Message Flow State)

Aggregate metrics for all nodes under the Message Flow




Backouts Total Number Total number of backouts across all nodes under this Message Flow.

CPU Time Total Number Total CPU time (milliseconds) spent processing input messages by all nodes under this Message Flow.

Database Time Stamp String The time this Message Flow was updated in the Message Broker database.

Deployed String TRUE—Message Flow has been deployed to the broker.FALSE—Message Flow has not been deployed to the broker.

Elapsed Time Total Number Time spent waiting for messages, aggregated for all nodes under this Message Flow.

Errors Total Number Total number of errors, aggregated for all nodes under this Message Flow.

Invocations Total Number Total number of Message Flow invocations.

Message Count Total Number Total number of messages processed by this node.

Message Flow Coordinated Transactions Allowed

Number Whether coordinated transactions are allowed for this Message Flow. One of:

TRUE—Coordinated transactions are allowed.FALSE—Coordinated transactions are not allowed.

Message Flow Deploy Time

String Date and time this Message flow was deployed.

Message Flow State String Whether the message flow is:RUNNINGSTOPPED

Message Flow UUID String Unique identifier for this Message Flow.

Message Flow User Trace

String Defines the type of user trace configured for this message flow. One of:

debug— Defines debug user trace.none—States that user trace is not running.normal—Defines normal user trace.unknown—Defines an unknown user trace setting.

Name String Name of the Message Flow.

Statistics Reported String Whether statistics are being reported for this Message Flow. One of:

TRUE—Statistics are reported for this Message Flow.FALSE—Statistics are not reported for this Message Flow.

Timeouts Total Number Number of timeouts that occurred on this Message Flow while processing a message, aggregated for all nodes under this Message Flow.


User Guide

Errors


Description

MQErrors Total Number M Number of MQGET errors (MQInput node) or Web services errors (HTTPInput node) during the most recent 20-second interval.

Messages With Errors Total

Number M Number of messages that contain errors during the most recent 20-second interval.

Processing Errors Total Number M Number of errors processing a message during the most recent 20-second interval.

Thread Count In Pool Total Number R Number of threads in pool.

Thread Maximum Reached Total

Number M Number of times the maximum number of threads was reached during the most recent 20-second interval.

Timeouts Total Number M Number of timeouts processing a message (AggregateReply node only) during the most recent 20-second interval.

Message Flow Invocations

Metric name Type In Description

Message Flow Backouts Total

Number M Number of transaction backouts aggregated from all nodes of this message flow during the most recent 20-second interval.

Message Flow Commits Total

Number M Number of transaction commits aggregated from all nodes of this message flow during the most recent 20-second interval.

Message Flow Invocations Total

Number M Total number of invocations, that is, sum of Message Flow Backouts Total and Message Flow Commits Total.

Total Broker Threads for Message Flow

Number The number of additional threads that the broker can use to service the message flow.



Message Statistics


Description

Message Count Total Number M Total number of messages processed during the most recent 20-second interval.

Message Size Average Number M Average size of input messages (bytes) during the most recent 20-second interval.

Message Size Maximum Number M Maximum input message size (bytes) during the most recent 20-second interval.

Message Size Minimum Number M Minimum message input size (bytes) during the most recent 20-second interval.

Message Size Total Number M Total size of input messages (bytes) during the most recent 20-second interval.

Node Statistics

Message Flow node statistics are crucial in identifying Message Flow performance problems. The following metrics are reported for each node if Message Flow statistics are configured for the Execution Group.

» Note Time measurements are in milliseconds.


Description

CPU Processing Time Number M Total CPU time, in milliseconds, this node has spent processing input messages during the most recent 20-second interval.

CPU Processing Time Average

Number M Average CPU time, in milliseconds, this node takes to process an input message during the most recent 20-second interval.


User Guide

Performance

Elapsed Time Number M Total elapsed time, in milliseconds, the node has spent waiting for input messages during the most recent 20-second interval.

Elapsed Time Average Number M Average elapsed time, in milliseconds, the node has spent waiting for input messages during the most recent 20-second interval.

Node Invocation Total Number M Total number of messages processed by this node during the most recent 20-second interval.

Node Type String R Type of the node being monitored. This should correspond to the node name, e.g. MQInputNode.

Number of Input Terminals Number F Each message flow node has a fixed number of input and output points or terminals which serve as entrances to or exits from a node. These metrics measure the total number of input and output terminals for the node.

Number of Output Terminals

Number F


Description

CPU Time Number R Total CPU time spent processing input messages.

CPU Time Average Number F Average CPU time spent processing input messages (in milliseconds)

CPU Time Maximum Number M Maximum CPU time spent processing an input message (in milliseconds)

CPU Time Minimum Number M Minimum CPU time spent processing an input message (in milliseconds)

CPU Time Waiting For Input Average

Number M Average CPU time spent waiting for input messages (in milliseconds)

CPU Time Waiting For Input Total

Number M Total CPU time spent waiting for input messages (in milliseconds)

Elapsed Time Average Number R Average elapsed time spent processing input messages (in milliseconds)

Elapsed Time Maximum Number M Maximum elapsed time spent processing an input message (in milliseconds)

Elapsed Time Minimum Number F Minimum elapsed time spent processing an input message (in milliseconds)

Elapsed Time Number M Total elapsed time spent processing input messages (in milliseconds)



Broker Queue Manager metrics

Beneath the Execution Groups node in the Message Broker metrics tree is a node for the Message Broker’s Queue Manager.

Elapsed Time Waiting For Input Average

Number F Average elapsed time spent waiting for input messages (in milliseconds)

Elapsed Time Waiting For Input Total

Number F Total elapsed time spent waiting for input messages (in milliseconds)


User Guide

The Investigator displays the same set of metrics for this Queue Manager as detailed in the section on Queue Manager metrics on page 146.

Configuration Manager’s Queue Manager metrics

Metrics for the Configuration Manager’s Queue Manager appear under a Configuration Manager|Dedicated Queue Manager node in the MB metrics tree.

The Investigator displays the same set of metrics for this Queue Manager as detailed in Queue Manager metrics on page 146.

Display of shared and non-shared Queue Managers

The Message Broker topology enables the user to use the same Queue Manager for the Configuration Manager and its default Broker. In this case, the Queue Manager is shared by the Configuration Manager and one (and only one) Broker, the PowerPackNameShort Agent reports this Queue Manager and its related metrics under the Broker in the Introscope Investigator tree.

In cases where the Configuration Manager has its own non shared Queue Manager, the Queue Manager appears right under the Configuration Manager|Dedicated Queue Manager node, which is on the same level where brokers appear.



MQ Java Connector metricsWebSphere MQ classes for Java (also referred to as WebSphere MQ base Java) allow a Java application to:

Connect to WebSphere MQ as a WebSphere MQ client

Connect directly to a WebSphere MQ server

WebSphere MQ classes for Java Message Service (also referred to as WebSphere MQ JMS) is a set of Java classes that implement Sun’s Java Message Service (JMS) interfaces to enable JMS programs to access WebSphere MQ systems.

To find data from MQ Java Connectors:

1 Expand the SuperDomain node and look under the <hostname> > WebSphere > WebSphereAgent (*SuperDomain*) node.

2 Look under certain nodes in the tree, as shown in the following illustration:

Operational groups

MQ returns metrics from MQ Java base classes using operational groups. Appendix B, JCA/JMS Operational Groups beginning on page 207, lists the member of each operational group and the MQ Java base class they use.

MQ Java Connector metrics 197

User Guide

Backend metrics

Introscope reports metrics for backend systems, including databases, a mail server, a transaction processing system (such as CICS or Tuxedo) or, in this case, WebSphere MQ. You can use these metrics to monitor the performance of any running application using MQ.

The following illustration shows how WebSphere MQ appears under the Investigator’s Backends node.

In the above illustration, Investigator displays two WebSphere MQ servers. The MQ instance on host2 is expanded to show:

Aggregate metrics

Connector node, with the following for each Queue Manager on the Connector:

Operations

Queues

JMS node:

Operations

Queues

Topics



Instance Counts metrics

The Investigator displays instance counts for the WebSphere MQ base classes

under the Instance Counts node. To enable Instance counts, uncomment PowerPackForWebSphereMQ_v8.1_InstanceCounts.pbd file in the PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbl file.

Only one metric, Approximate Instance Count, is reported for each instance:

Metric Description

Approximate Instance Count

The number of times the WebSphere MQ system called the class corresponding to the instance during the most recently completed interval.

You can use instance count metrics to monitor the number of times the object of the particular class was created.

JCA node metrics

Under the JCA node, the Investigator displays metrics for each of the connection pools you configured a service for (see Configure MQ Java Connectors on page 49).


User Guide

» Note Two of the metrics displayed for connection pools are labeled differently depending on whether you are monitoring WebSphere Application Server

(WAS) v5.1 or v6.0.

Metric Description

PercentMaxed Average percent of the time that all connections are in use.

PercentUsed The percentage of the connection pool that is currently in use.

PoolSize The size of the connection pool to the data source.

AvgWaitTime (WAS v5.1)

WaitTime (WAS v6.0/v6.1)

The average waiting time in milliseconds until a connection is granted.

ConcurrentWaiters (WAS v5.1)

WaitingThreadCount (WAS v6.0/v6.1)

The number of threads that are currently waiting for a connection.

» Note JCA Connection Pool metrics are only visible for WebSphere v5.1, v6.x, and later.

WebSphereMQ node metrics

Under the WebSphereMQ node, you can see most of the metrics you can use to monitor the performance of your WebSphere MQ Java Connectors.

» Note These aggregated metrics are not visible unless and until the corresponding Operations are invoked.

» Note The Average Response Time (ms) for Commit and Rollback Operations are aggregated together.

The top level of the tree shows aggregated metrics rolling up Average Response Time for all of the Connectors and JMS operations in the tree below.



Th

Metric Description

Average Response Time (ms) The weighted average response times for all operational groups of this name on nodes lower in the tree

e metrics are organized by operation name, but they are all the same metric:

The tree is organized by this hierarchy:

Top level node (Connector/JMS)Aggregate response time metrics, organized by Operational Group namehost name

Queue Manager NameOperations

Operational GroupAggregate metrics for the operational groupIndividual operation name

Metrics for the individual operationQueues

Individual queue nameOperational group

Aggregate metrics for the operational groupIndividual operation name

Metrics for the individual operationTopics (JMS only)

Individual topic nameOperational group

Aggregate metrics for the operational groupIndividual operation name

Metrics for the individual operation

Operational groups

The Investigator displays metrics on operations (such as connect, get, rollback, etc.) under the following Operation Groups:

Connect

Disconnect

Send

Receive

Commit

Rollback

Close


User Guide

Operational Group metrics

The tree displays the following metrics for each operation group:

Aggregate metrics for all the operations in that group

Metrics for each individual operation

For each Aggregate Operation, the Investigator displays five aggregated metrics

at the operational group level:

Metric Description

Average Response Time (ms)

The weighted average response time, in milliseconds, for all operations under this node, during the most recent interval.

Concurrent Invocations The total number of requests for all operations under this node that were completed, during the most recent interval.

Errors Per Interval The total number of errors for all operations under this node that occurred, during the most recent interval.

Responses Per Interval Total responses per interval of all operations under this node, during the most recent interval.

Stall Count The total number of stalled transactions for all operations under this node, during the most recent interval.

» Note Introscope uses a default 15-second interval, not the 20-second interval which WebSphere MQ uses to report its internal metrics. Whenever you see the metrics in the table above in the Java Connectors tree, the interval is always the default Introscope interval.



asdf

The following illustrations show how metrics for operational groups are displayed throughout the WebSphereMQ node.


User Guide

Aggregate and individual metrics

Aggregate metrics are calculated using metrics of the same name on nodes lower in a hierarchy. For example, expanding the Connect operation group displays:

Aggregate metrics for all the operations in the group

Nodes for each individual operation in that group

This pattern, in which aggregate metrics roll up the metrics from the nodes under them, is repeated throughout the tree.

The illustration below shows the relation of the aggregate metrics to the nodes whose metrics are rolled up in the aggregate metrics:



ErrorDetector metrics

The PowerPackForWebSphereMQ_v8.1_ErrorDetector.pbd file (see Configure ErrorDetector on page 53) generates Errors Per Interval metrics that appear under several operational group nodes, as shown in the following illustration:

The Errors view, available when a resource or component is selected in the Investigator tree, lists errors and error details for the selected item.

The top half of the Errors view lists the time, description, and type of each error. The lower half of the view shows detailed information for each component involved in the error selected.


User Guide

The following illustration shows this view.

JCA/JMS Operational Groups 207

APPENDIX B

JCA/JMS Operational Groups

This appendix lists the operation names for each Operational Group.


JCA Queue Manager Operations . . . . . . . . . . . . . . 208

JCA Queue Operational Groups . . . . . . . . . . . . . . 210

JMS Queue Manager Operational Groups . . . . . . . . . . . 211

JMS Queue/Topic Operational Groups . . . . . . . . . . . . 213

JCA Operational Groups

This section describes the following JCA Operational Groups:

JCA Queue Manager Operations

JCA Queue Operational Groups

208 JCA/JMS Operational Groups


JCA Queue Manager Operations

Disconnect Operational Group

Operation name Description

Manager Disconnect Monitors the Queue Manager disconnect functions in the com.ibm.mq.jar file.

Unregister Monitors the Queue Manager unregister functions in the com.ibm.mq.jar file.

Cleanup Monitors the cleanup functions called on the Queue Manager object in the com.ibm.mq.jar file.

Destroy Monitors the destroy functions called on the Queue Manager object in the com.ibm.mq.jar file.

Session Disconnect Monitors all the session disconnection operations on the Queue Manager object in the com.ibm.mq.jar file.

Connect Operational Group


Begin Monitors the Queue Manager begin() operation in the com.ibm.mq.jar file.

Access Process Monitors the Queue Manager process access operation in the com.ibm.mq.jar file.

Get Connection Monitors the Queue Manager connection get operations in the com.ibm.mq.jar file.

Session Connect Monitors the Queue Manager session connect operations, such as MQCONN, MQCONNX in the com.ibm.mq.jar file.

XA Session Start Monitors the Queue Manager session start operations in the com.ibm.mq.jar file.

XA Session Prepare Monitors the Queue Manager XA enabled prepare session operations in the com.ibm.mq.jar file.

Queue Process Get Type Monitors the Application Type operations in the com.ibm.mq.jar file.

209

User Guide

Commit Operational Group


Manager Commit Monitors the Queue Manager commit operations in com.ibm.mq.jar.

Session Commit Monitors the Queue Manager session client commit operations in com.ibm.mq.jar.

XA Session Commit Monitors the Queue Manager XA enabled session client commit operations in com.ibm.mq.jar.

Put Operational Group


Manager Put Monitors the Queue Manager put operations in com.ibm.mq.jar.

Distribution List Put Monitors the Queue Manager distribution list put operations in com.ibm.mq.jar.

Get Operational Group


Access Queue Monitors the Queue Manager queue access operations in com.ibm.mq.jar.

Distribution List Get Monitors the Queue Manager distribution list get operations in com.ibm.mq.jar.

Get Count Monitors the Queue Manager getcount() operation

Open Operational Group


Session Open Monitors the session client open operations in the com.ibm.mq.jar file.

XA Session Open Monitors the XA enabled session client open operations in the com.ibm.mq.jar file.



Close Operational Group


Session Close Monitors the session client close operations in the com.ibm.mq.jar file.

XA Session Close Monitors the XA enabled session client open operations the in com.ibm.mq.jar file.

Process Close Monitors the mqprocess object operations in the com.ibm.mq.jar file.

Rollback Operational Group


Session Rollback Monitors the session client rollback operations in the com.ibm.mq.jar file.

XA Session Rollback Monitors the XA enabled session client rollback operations in the com.ibm.mq.jar file.

XA Session Recover Monitors the session client recover operations in the com.ibm.mq.jar file.

JCA Queue Operational Groups

Put operational group

Operation Names Description

Queue Put Monitors the queue put operations in the com.ibm.mq.jar file.

Get operational group

Operation Names Description

Queue Get Monitors the queue get operations in the com.ibm.mq.jar file.

JMS Operational Groups

This section describes the following JMS Operational Groups:

JMS Queue Manager Operational Groups

JMS Queue/Topic Operational Groups

211

User Guide

JMS Queue Manager Operational Groups

Receive Operational Group


Create Receiver Monitors the JMS create receiver operations in the com.ibm.mqjms.jar file.

Create Subscriber Monitors the JMS create subscriber operations in the com.ibm.mqjms.jar file.

Create Browser Monitors the JMS create browser operations in the com.ibm.mqjms.jar file.

Create Consumer Monitors the JMS create consumer operations in the com.ibm.mqjms.jar file.

Get Topic Monitors the JMS get topic operations in the com.ibm.mqjms.jar file.

Async Receive Monitors the JMS Async receive operations in the com.ibm.mqjms.jar file.

Receive No Wait Monitors the JMS receive no wait operations in the com.ibm.mqjms.jar file.

Consumer Receive Monitors the JMS consumer receive operations in the com.ibm.mqjms.jar file.

Send Operational Group


Create Sender Monitors the JMS sender creation operations in the com.ibm.mqjms.jar file.

Create Producer Monitors the JMS producer creation operations in the com.ibm.mqjms.jar file.

Create Destination Monitors the JMS destination creation operations in the com.ibm.mqjms.jar file.

Create Message Monitors the JMS message creation operations in the com.ibm.mqjms.jar file.

Process Message Monitors the JMS message process operations in the com.ibm.mqjms.jar file.





Create Queue Monitors the JMS queue creation operations in the com.ibm.mqjms.jar file.

Create Publisher Monitors the JMS create publisher operations in the com.ibm.mqjms.jar file.

Create Topic Monitors the JMS Topic creation operations in the com.ibm.mqjms.jar file.

Get Server Session Pool Monitors the JMS session pool operations in the com.ibm.mqjms.jar file.



Unsubscribe Monitors the JMS unsubscribe operations in the com.ibm.mqjms.jar file.

Close Connect Monitors the JMS connection close operations in the com.ibm.mqjms.jar file.

Close Operational Group


Session Close Monitors the JMS session close operations in the com.ibm.mqjms.jar file.

Commit Operational Group


Session Commit Monitors the JMS session commit operations in the com.ibm.mqjms.jar file.

Rollback Operational Group


Session Recover Monitors the JMS session recover operations in the com.ibm.mqjms.jar file.

Session Rollback Monitors the JMS connection close operations in the com.ibm.mqjms.jar file.

213

User Guide

JMS Queue/Topic Operational Groups

Send Operational Group


Publish Monitors the JMS Queue/Topic publish operations in the com.ibm.mqjms.jar file.

Producer Send Monitors the JMS Queue/Topic send operations in the com.ibm.mqjms.jar file.

Process Message Monitors the JMS agent thread process message operations in the com.ibm.mqjms.jar file.

Receive Operational Group


Get Topic Monitors the JMS Topic get operations in the com.ibm.mqjms.jar file.

Async Receive Monitors the JMS Queue/Topic async receive operations in the com.ibm.mqjms.jar file.

Receive No Wait Monitors the JMS Queue/Topic receive no wait operations in the com.ibm.mqjms.jar file.

Consumer Receive Monitors the JMS Queue/Topic consumer receive operations in the com.ibm.mqjms.jar file.



Get Server Session Pool Monitors the JMS session pool get operations in the com.ibm.mqjms.jar file.



Close Connection Monitors the JMS Queue/Topic connection close operations in the com.ibm.mqjms.jar file.

Performance and Sizing 215

APPENDIX C

Performance and Sizing

This appendix contains instructions, best practices, and tips for optimizing the sizing and performance of your PowerPack for MQ deployment and environment.

» Important The configurations listed in this appendix are only examples and do not indicate the recommended WebSphere MQ or WebSphere MB configurations.


MQMonitor agent background . . . . . . . . . . . . . . . 215

WebSphere MQ Sizing . . . . . . . . . . . . . . . . . 216

WebSphere MB Sizing . . . . . . . . . . . . . . . . . 221

MQMonitor agent backgroundIn an Introscope deployment, the agent collects application and environmental metrics, and relays them to the Enterprise Manager. As an Introscope Agent, the MQMonitor agent collects WebSphere MQ and WebSphere MB-specific metrics to monitor the performance of WebSphere MQ and WebSphere MB to quickly isolate the source of WebSphere MQ-related and WebSphere MB-related performance problems.

The factors that would affect the performance and overhead of MQMonitor agent are:

The number of Queue Managers monitored and the number of WebSphere MQ objects (queues, channels, and so on) in each monitored Queue Manager for WebSphere MQ.

The number of message brokers monitored and the number of execution groups and message flows in each monitored message broker for WebSphere MB.

The number of WebSphere MQ clusters and the size of each cluster.

The metric display and control level (minimum, recommended, full) for a component.

216 Performance and Sizing


The Java Heap size of the MQMonitor agent.

%CPU utilization of the MQMonitor agent.

State of the Transaction Tracer (whether switched on or switched off).

Hardware configuration of the machines involved.

WebSphere MQ SizingTo perform sizing on WebSphere MQ, you must perform sizing on the EM and the MQMonitor agent.

Sizing your EM

The number of metrics contributed by the PowerPack for MQ agent determines the sizing consideration of your EM. The metric count depends on the number of Queue Manager objects that you plan to monitor. To find out the number of metrics that are reported to your EM, calculate the Maximum Metric Count per Queue Manager for different levels of monitoring. The Maximum Metric Count is the maximum number of metrics that are reported including aggregated metrics. The formulas for calculating the Maximum Metric Count for distributed and z/OS systems at the full, recommended, and minimum monitoring levels are as follows:

Distributed systems:

At the full monitoring level:

Maximum Metric Count = (Q * 76) + (C * 48) + 69

At the recommended level:


At the minimum level:


where:

Q is the number of Queues for a Queue Manager

C is the number of Channels for a Queue Manager

z/OS systems:

At the full monitoring level:

Maximum Metric Count = (Q * 97) + (C * 48) + (CI * 18) + (L * 19) + ((PS * 15) + 1) + 91

WebSphere MQ Sizing 217

User Guide





where:

Q is the number of Queues for a Queue Manager

C is the number of Channels for a Queue Manager

CI is the number of Channel Initiators for a Queue Manager

L is the number of Logs for a Queue Manager

PS is the number of Page Sets for a Queue Manager

» Note The number of metrics equal to the Maximum Metric Count is added to your EM’s metric count. To find out the existing metric count, go to Custom Metric Host > Custom Metric Agent > Enterprise Manager > Connections > Number of Metrics in the Investigator tree. You can then see the Introscope EM sizing guide to size your EM.

» Note If you do not see all the metrics that should be reported by the MQMonitor agent, then you must check if the metrics are being clamped by the EM. To do this, login to the Investigator tree and observe the following metric:

If the Is Clamped metric displays the value 1, then the agent metrics are being clamped by the EM, so you need to increase the limit of metrics that the agent can report. To do this, set the introscope.enterprisemanager.agent.metrics.limit to a desired value and restart the EM.

Alternatively, you can change the monitoring level for the WebSphere MQ objects from Full to Recommended or Recommended to Minimum.

SuperDomain > Custom Metric Agent (Virtual) > Custom Metric Agent (Virtual) (*SuperDomain*) > Agents > <Agent Machine Name> > <Agent Name> > <Agent Process> > Is Clamped



Sizing your MQMonitor agent

The following sections describe the settings and capacity limits that you need to set up, maintain, and configure PowerPack for MQ environment for monitoring WebSphere MQ. The monitoring level defined at the MQMonitor agent determines the number of metrics reported by the PowerPack for MQ to the EM.

» Note The information below is only a guideline for the sizing of your configuration. The sizing information can vary depending on the hardware configuration of your EM, the MQMonitor agent, and the WebSphere MQ machines.

WebSphere MQ Sizing 219

User Guide

Sample MQMonitor agent sizing table

The MQMonitor agent sizing table is as follows:

Configuration: Single Queue Manager with Multiple Queues

Configuration: Multiple Queue Managers with Multiple Queues

Monitoring Level

Delaytime, Static frequency

Heap Size (minimum to maximum)

Number of queues

Number of metrics

Minimum 300, 2 256 to 512 5800 122000

600, 2 256 to 512 6000 126200

Recommended 300, 2 256 to 512 4200 126300

600, 2 256 to 512 4500 135300

Full 300, 2 256 to 512 1700 129500

600, 2 256 to 512 1800 137100

Monitoring Level

Delaytime, Static frequency

Heap Size (minimum to maximum)

Number of Queue Managers / Number of queues per Queue Manager

Number of metrics

Minimum 300, 2 256 to 512 Queue Managers: 5

Queues per Queue Manager: 1100

116800

600, 2 256 to 512 Queue Managers: 5


127300

Recommended 300, 2 256 to 512 Queue Managers: 5


121600



121600

Full 300, 2 256 to 512 Queue Managers: 5


116570



116570



Environment Details

Enterprise Manager:

System Requirement Details

Operating system Microsoft Windows Server 2003 Enterprise Edition

System Model Dell Inc., PowerEdge 6950

Processor Dual Core AMD Opteron™ Processor 8220,MMX,3D Now(8CPUs), ~2.8HZ

Memory 16GB

Total Free Space 210GB

MQMonitor agent:



System Model Dell Inc., PowerEdge GX620

Processor Intel Pentium® 4 CPU 3.00 GHz, ~3.0 GHz

Memory 2GB


4-512MB




Processor Intel Pentium® D CPU 3.00 GHz, ~3.0 GHz

Memory 2GB


MQ Machine:

With the above WebSphere MQ configuration and the number of metrics generated by the MQMonitor agent, the EM processing cycle increases. The overload on the MQMonitor agent is, however, minimal, so you must ensure that you size your EM appropriately for sizing PowerPack for MQ for WebSphere MQ objects. See the Introscope Sizing Guide to size your EM appropriately.

» Note If you plan to use the same agent for monitoring WebSphere MQ and WebSphere MB, or if you plan to use the same MQMonitor agent for transaction tracing, then the number of supported objects would reduce.

WebSphere MB Sizing 221

User Guide

WebSphere MB SizingTo perform sizing on WebSphere MB, you must perform sizing on the EM and the MQMonitor agent for WebSphere MB.

Sizing your EM

The number of metrics contributed by the PowerPack for MQ agent determines the sizing consideration of your EM. The metric count depends on the number of WebSphere MB objects that you plan to monitor. To find out the number of metrics that are reported to your EM, calculate the Maximum Metric Count for different levels of monitoring.

The formulas for calculating the Maximum Metric Count at the full, recommended, and minimum monitoring levels are as follows:

At full monitoring level:

Maximum Metric Count = 4 + (4 + 5 * B) + (4 + 29 * EG * B) + (3 + 36 * MF * EG * B) + (7 * N)





» Note This is the maximum number of metrics that are reported when all the aggregated and normal metrics are reported.

where:

B is the number of brokers

EG is the number of execution groups

MF is the number of message flows

N is the number of nodes per message flow

» Note The number of metrics equal to the Maximum Metric Count is added to your EM’s metric count. To find out the existing metric count, go to Custom Metric Host > Custom Metric Agent > Enterprise Manager > Connections > Number of Metrics in the Investigator tree. You can then see the Introscope EM sizing guide to size your EM.



Sizing your MQMonitor agent for WebSphere MB

The following sections describe the settings and capacity limits that you need to set up, maintain, and configure your PowerPack for MQ environment for monitoring WebSphere MB.

» Note The information below is only a guideline for the sizing of your configuration. The sizing information can vary depending on the hardware configuration of your EM, MQMonitor agent, and WebSphere MB machines.

Sample MQMonitor agent sizing table for WebSphere MB

The MQMonitor agent sizing table for WebSphere MB is as follows:

Configuration: Single Broker Multiple Execution Groups and Multiple Message flows

Monitoring Level Number of execution groups per broker

Total number of message flows

Number of nodes per message flow

Number of metrics reported

Minimum 25 150 51 8700

Recommended 25 150 51 10400

Full 25 150 51 13600

Minimum 15 90 51 5800


Full 15 90 51 9400

Minimum 5 30 51 1800


Full 5 30 51 2900

WebSphere MB Sizing 223

User Guide

Configuration: Multiple brokers (total number of brokers used is 3) multiple execution groups and multiple message flows in each broker.

Environment Details

Enterprise Manager




Processor Dual Core AMD Opteron™ Processor 8220, MMX, 3D Now(8CPUs), ~2.8HZ

Memory 16GB


:

MQMonitor agent:

System Requirement

Details


System Model Dell Inc., Optiplex GX620

Processor Intel Pentium® 4 CPU 3.00 GHz, ~3.0 GHz

Memory 2GB


4-512MB

Monitoring Level Number of execution groups per broker

Total number of message flows

Number of nodes per message flow

Number of metrics reported

Minimum 10 130 51 8100


Full 10 130 51 12600

System Requirement

Details


System Model Dell Inc., Optiplex 745

Processor Intel Pentium® D CPU 3.00 GHz, ~3.0 GHz

Memory 2GB




MB Machine:

With the above WebSphere MB configuration, the overload on the MQMonitor machine is minimal (only 2%) and the number of metrics reported to EM is comparatively lesser than the number of metrics reported when you monitor large WebSphere MQ configurations. So, depending on your WebSphere MB machine configuration, the MQMonitor agent can be utilized better.

Also, if you plan to use the same agent for monitoring WebSphere MQ and WebSphere MB, or if you plan to use the same MQMonitor agent for transaction tracing, then the number of supported objects would reduce.

» Important We recommend that you do not perform Management Module hot deployments on production collectors or MOMs, as it locks the system and also prevents the metric data from being reported.

Frequently Asked Questions 225

APPENDIX D

Frequently Asked Questions

This appendix includes frequently asked questions about installation, metrics, transaction tracing, alerts, and dashboards in PowerPack for MQ.

This appendix includes the following topics:

Alerts and dashboards . . . . . . . . . . . . . . . . . 225

Installation . . . . . . . . . . . . . . . . . . . . . 226

Metrics . . . . . . . . . . . . . . . . . . . . . . 226

Queues . . . . . . . . . . . . . . . . . . . . . . 227

Transaction Tracing . . . . . . . . . . . . . . . . . . 227

Alerts and dashboards

What is the purpose of the WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard?

The WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard helps you check if your MQ infrastructure is configured properly for the cross-process transaction trace to work.

I do not see any color for the Connection Pool alert in the WebSphere MQ Client And Server Overview – Details and WebSphere MQ – Client Connection dashboards. Why is this so?

Connection pool alerts are applicable only for the WebSphere application server. If your Java application server is WebSphere and you have enabled PMI metrics reporting, then you would see this alert reporting data from the WebSphere PMI connection pool data.

How do I triage the WebSphere MQ infrastructure problems?

To troubleshoot WebSphere MQ infrastructure issues:

a Log in to the Introscope Console Workstation.

b Open the WebSphere MQ Client And Server - Overview dashboard.

226 Frequently Asked Questions


c Observe the traffic lights to determine the health of your MQ Client connections, MQ Client operations, and MQ Server.

d Double-click the traffic light that reports a warning and go to the details page.

On the Details page, view the MQ connections, MQ operations, and MQ Server information, to determine and analyze the problem in your MQ infrastructure.

Installation

On UNIX or Linux, do I need to install PowerPack for MQ using the “root” account?

No, you do not need the root account to install PowerPack for MQ on UNIX or Linux platforms. For details, see Security settings for CMP, JMS, PCF connections on page 32.

Which version of connector JAR file does the PowerPack for MQ support? How can I know the version of connector jar file used by my application?

PowerPack for MQ v8.x supports the v6.x and v7.x connector JAR files only.

To determine the version of Connector JAR files, locate the com.ibm.mq.jar file, open the JAR file, and see the version of the connector in the manifest.mf file.

When Java 2 security is enabled on my application server and I deploy PowerPack for MQ, I see security exception being reported in the application server log. What do I do?

You must ensure that you provide adequate permission on the application server to prevent any security exceptions. For configuring PowerPack for MQ to enable Java 2 security, see (Optional) Configure application server when Java 2 security is enabled on page 48.

Metrics

At what intervals are the message broker metrics updated?

Configuration manager metrics are updated as per the delay time property in the MBMonitor.properties file.

Message flow statistics are updated every 20 seconds, and are reported accordingly.

Broker statistics are updated depending on the mqsichangeproperties command issue on the Message Broker.

How do I interpret Enqueue Count and Dequeue Count metrics? How is this related to the Queue Depth metric?

227

User Guide

The Enqueue Depth metric gives the number of messages that were added to a queue since the last polling cycle of the MQMonitor agent. This includes uncommitted messages.

The Dequeue Count metric gives the number of messages that were removed from the queue since the last polling cycle of the MQMonitor agent.

The Current Queue Depth can be confirmed as follows:

Current Queue Depth = [Queue Depth at the previous polling cycle] + [Enqueue Count] – [Dequeue Count]

What is the difference between Message metrics and Current Messages metrics for Channels?

The Message metrics indicate the number of messages that have been sent or received (or, for server-connection channels, the number of MQI calls handled) since the channel was started. This is applicable to Sender, Receiver, Cluster-sender, Cluster-receiver, Server, Requester, Server-connection channel types

The Current Messages metric indicates the number of messages sent/received in the current batch. This is not applicable to Server Connection channels but applicable to all other channel types.

Queues

PowerPack for MQ provides the “includeonly” regular expression for monitoring queues. How can I exclude queues from monitoring?

You can use the regular expression with the “includeonly” property to exclude the monitoring of relevant queues.

If you want to filter out all queues starting queue1 and queue2 of the WebSphere MQ instance named QM1, then you can use the following regular expression:

QM1.queue.filter.includeonly.regex=(?!((queue1.*)|(queue2.*))).*

Transaction Tracing

I am using the cross-process transaction trace feature. However, I do not see MQ traces. Why is this so?

Open the WebSphereMQ Cross Process Transaction Trace Health & Availability dashboard. Check if any of the traffic lights is red and view the details for that traffic light. If all the traffic lights are green or yellow, and if you still don't see MQ Trace data, then ensure that you restart all the active channels of the monitored Queue Managers. If the problem persists, check the log files and Introscope version.



If my business transaction passes through any WebSphere MQ v5.3 Queue Managers, can I view the transaction traces from WebSphere MQ version v5.3 Queue Managers?

No, you cannot view transaction traces from WebSphere MQ v5.3 Queue Managers. Cross-process transaction tracing is supported for WebSphere MQ v6.x and v7.x only.

After setting the Activity Reporting property to “Queue”, why should I restart the active channels of the monitored Queue Managers or the Queue Managers?

Restarting the Queue Manager also restarts the MCA’s. This ensures that the trace data generated by WebSphere MQ goes to SYSTEM.ADMIN.ACTIVITY.QUEUE.

Why is the Average Response Time of the Queue Put operation under the WebSphereMQ node greater than that of the Backend node?

The time difference is due to the additional processing logic (involving the tracers) for the Queue Put operation performed under the WebphereMQ node. When cross-process transaction tracing is turned off, the Average Response Time of the Queue Put operation under the WebSphereMQ node and Backend node remains the same.

How do I interpret the Total Duration column in the Transaction Trace Viewer window?

The Total Duration column indicates the total duration taken by your MQ transaction. For example, if your application puts a message into a queue and read the response from the reply to queue; traces will be generated for the Java component and MQ components. Suppose your application puts a message at 12:05:01 and the last MQ trace appears in the Transaction Trace Viewer window at 12:06:01, then your total transaction time is 60 seconds or 1 min. This is reflected in the Transaction Trace Viewer window for each trace in the transaction.

What properties do I need to configure in my EM to see the Total Duration column?

To configure EM to view the Total Duration column, add the following properties in the <Introscope Home>\config\IntroscopeEnterpriseManager.properties file:

introscope.workstation.transactiontracer.showTotalDuration=true

introscope.workstation.transactiontracer.showTotalDuration.sumAllTraceComponents=true

229

User Guide

I set the Activity Recording option to “Queue” on a z/OS Queue Manager, but restarting the Queue Manager changes it back to “Message”. Why does this happen; how does this affect transaction tracing?

On z/OS, a Queue Manager on startup refers to the config setup in the start-up job. If the config has the Activity Recording set to “Message”, such as,

ROUTEREC( MSG ) ACTIVREC( MSG ) + then the Activity Recording for that Queue Manager is always set to “Message” after the Queue Manager is restarted. Because of this, transaction tracing does not occur for that Queue Manager, that is, traces for remote queues do not appear for that Queue Manager.

I see lot of Backends data in the transaction trace viewer. I am not interested in this information. How can I disable the Backends information?

To disable the Backends data from appearing in the transaction trace viewer and the Investigator tree, open the PowerPackForWebSphereMQ_v8.1_JavaConnectors.pbd file in the \wily directory and comment all the directives containing Backends|WebSphereMQ on {hostname}.

Troubleshooting 231

APPENDIX E

Troubleshooting

This appendix provides solutions for troubleshooting issues that you may encounter in PowerPack for MQ. The following table lists the errors, the probable causes of the errors, and the troubleshooting steps:

Errors in Log/Console Cause of the error Troubleshooting steps

[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.TracerDriverThread] MQMonitor: For configuration instance <QueueManager name>@localhost and the drivers(manager,manager) an error occured in sending query to MQ. The target MQ (localhost:19100) may be down. Reason code 2035 MQRC_NOT_AUTHORIZED

The user running the MQMonitor agent does not have adequate permissions to run the MQMonitor agent and connect to the Queue Manager.

Do one of the following:If the server connection channel used by the MQMonitor agent is CLIENT.WILY and the MCA user ID is set to user Wily, then the user “Wily” must be made member of mqm group, so that the MQMonitor agent can connect to the Queue Manager without any problem.Leave the MCA user ID blank so that the user ID is set to a default value of MQADMIN by the the PCF APIs, and hence becomes part of the mqm group.

[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.TracerDriverThread] MQMonitor: For configuration instance <QueueManager name>@<hostname> and the drivers(queue,queue,queue,queue,queue,queue) an error occured in sending query to MQ. The target MQ (localhost:3414) may be down. Reason code 2397 MQRC_JSSE_ERROR

Indicates that the truststore or keystore paths or passwords provided in the MQMonitor.properties file are incorrect. Can also indicate a problem with creating or exchanging the certificates between the WebSphere MQ server and client (MQMonitor agent) such as Certificate expiry.

In the IntroscopeAgent.profile file under MQMonitor properties directory, remove the comment ‘#’ for the following line: #log4j.logger.com.wily.powerpack.websphereMQ.agent.MQMonitor.TracerDriverThread=DEBUG

This displays the SSL handshake debug statements which will have details such as truststore path, keystorepath certificates used and their expiry dates. This information is useful to get to root of the JSSE Error.

232 Troubleshooting


[ERROR]

TraceManager.startUp ClassNotFoundException: Activity report parsing classes are not available. Make sure to have PCF JAR file from latest MS0B support pack.

Incorrect version of PCF JAR file was used.

Ensure that you use the com.ibm.mq.pcf-6.1.jar file in the ms0b.zip file. For more information, see Obtain third-party libraries on page 17.

[ERROR]sun.io.MalformedInputException at sun.io.ByteToCharUTF8.convert(ByteToCharUTF8.java(Compiled Code))

Locale specific environment variable contains suffix ".UTF-8"

Perform the following steps on all UNIX-flavored operating systems:

1 Check for locale-specific environment variables such as LANG, LC_ALL. You can retrieve these details by running the "locale" command.

2 Remove the suffix .UTF-8 from the locale-specific environment variables, if this suffix exists.

3 For example, change LANG=en_US.UTF-8 to LANG=en_US


[DEBUG] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] User <userName> is not authorized to connect to queue manager <ConfigMgrQmgr> (MQ reason code 2035 while trying to connect)

The MQMonitor agent user is not authorized to connect to the Configuration Manager’s Queue Manager.

Perform the following steps:

1 Apply the allmqi permission on Queue Manager of Configuration Manager using the following command: setmqaut -m <CMPQMName> -

t qmgr -p <userName@DomainName> +allmqi

2 Apply the put permission on the SYSTEM.BROKER.CONFIG.QUEUE queue of the same Queue Manager using the following command: setmqaut -m <CMPQMName>-n

SYSTEM.BROKER.CONFIG.QUEUE -t queue - p <userName@DomainName> +put


233

User Guide

[DEBUG] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] ConfigManagerProxy information was not received from the Configuration Manager. Either the Configuration Manager is not available or the user 'userName\MachineName' does not have authority to view the object. (UUID='', required attribute='name')

[FATAL] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] Configuration Manager is not initialized.

Either the Configuration Manager is not available or the user 'hostname\username' does not have authority to view the object. (UUID='', required attribute='name').


1 Check the MBMonitor.properties file. Also, check the CMP credentials.

2 Include the user of the MQMonitor agent into the ACL entry of the Configuration manager. To include the user into ACL entry, use following command and restart the Configuration manager and the MQMonitor agent.mqsicreateaclentry

<ConfigurationManagerName> -u <user> -m <machine> -x F –p

[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.BrokerStatistics] MQJMS1111: JMS1.1 The required Queues/Publish Subscribe services are not set up {0}

JMS Broker Queue Manager does not have the prerequisite queues for Pub/Sub.

Create all prerequisite JMS queue on JMS Broker Queue Manager using the MBMonitorJMSQueues.mqsc script and restart the MQMonitor agent.

runmqsc <QMName> <MBMonitorJMSQueues.mqsc


234 Troubleshooting


[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeMsgflowStatistics] MQJMS2013: invalid security authentication supplied for MQQueueManager.

JMS Broker Queue manager does not have suitable user permission.


Stop the MQMonitor agent and modify the privileges of Queue Manager of JMS Broker using the following commands:

1 Apply the allmqi permission on Queue Manager as follows: setmqaut -m <JMSQMName> -t

qmgr -p <userName@DomainName> +allmqi

2 Apply the allmqi permission on all JMS queues (all JMS queue name starts with SYSTEM.JMS.*) setmqaut -m <JMSQMName> -n

<NameOfJMSQueue> -t queue -p <userName@DomainName> +allmqi

3 If MQMonitor user is not domain user, then create the same user in the MQ server and give privileges to this user. In this case, give the name of user without specifying domain name with user name. setmqaut -m <JMSQMName> -t

qmgr -p <userName> +allmqi

After changing privileges on the Queue Manager, refresh the security or restart the Queue Manager. Also, restart the MQMonitor agent.

[FATAL] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] Configuration Manager is not initialized.

[FATAL] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeConfigMain] Start the Configuration Manager and run MB Agent again.

Configuration Manager is not available.

Stop the MQMonitor agent and turn on Configuration Manager using following command:

mqsistart <ConfigurationManagerName>


235

User Guide

[INFO] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.MBTreeMsgflowStatistics] No Execution groups to monitor.

[INFO] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.BrokerStatistics] No Execution groups to monitor.

[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.ExecutionGroupTracer] Statistics for all Execution groups are missing. MB Agent probably lost connection.

[INFO] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.ExecutionGroupTracer] MB Agent restart will be preformed now.

In the MBMonitor.properties file, the statistics.broker.list property has been set to a broker but, at the same time no execution groups have been specified for monitoring on that broker using the <BROKER>.executiongroup property.

Check the values of the statistics.broker.list and <BROKER1>.executiongroup properties. If statistics.broker.list is set to any value other than all, then for the same broker name , <BROKER1>.executiongroup must have some value.

For example:

statistics.broker.list=amqbroker_ca amqbroker_ca.executiongroup=amqbroker_ca_exegrp

where amqbroker_ca is a name of broker that user wants to monitor and amqbroker_ca_exegrp is the execution group defined in it.


236 Troubleshooting


[ERROR] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.ExecutionGroupTracer] Statistics for all Execution groups are missing. MB Agent probably lost connection.

[INFO] [com.wily.powerpack.websphereMQ.agent.MQMonitor.MBMonitor.ExecutionGroupTracer] MB Agent restart will be performed now.

Message Flow statistics and Broker statistics are not enabled for the execution groups on WebSphere MB.

Check if Message flow statistics and Broker Statistics are turned on using IBM commands. See the Configure WebSphere MB Section of this user documentation for more information on how to enable Message Flow statistics and Broker Statistics.

[WARN]

[Manager.Agent] The Agent WebSphere MQ and Message Broker Agent is reporting too many metrics (current=50000, max=50000). New metrics will not be accepted

The metrics reported by the MQMonitor agent are clamped by the EM as it is sending more than 50000 metrics. Because of this, no new metrics will be reported by the EM.

Do one of the following:Open the IntroscopeEnterpriseManager.properties file and increase the limit for the number of metrics that an agent can report. You can set this by editing the property:introscope.enterprisemana

ger.agent.metrics.limit=50000

Restart the EM.Lower the monitoring level of the WebSphere MQ objects such as Queue Managers, Queues, Channels, and z/OS specific components such as Channel Initiators, PageSets, and Logs. For example, to lower the monitoring level for queues to the Minimum level, set the property as:<QueueManager

name>@localhost.monitor.queue=minimum

Restart the MQMonitor agent.


Support for IPv6 Environment 237

APPENDIX F

Support for IPv6 Environment

This appendix describes how you can configure the MQMonitor agent and the MQ Java Connectors to connect to the Introscope EM in an IPv6 environment. The appendix also describes how you can add support for WebSphere MQ and WebSphere MB in the IPv6 environment.

Connect to the Introscope EM in an IPv6 environment

You can connect to the Introscope EM in an IPv6 environment by configuring the MQMonitor agent and the MQ Java Connectors.

MQMonitor agent

In a pure IPv6 Java environment, you must configure the MQMonitor agent with the java.net.preferIPv6Addresses property to display IPv6 addresses for the MQMonitor agent in the Investigator tree.

To configure the MQMonitor agent:

Set the property -Djava.net.preferIPv6Addresses=true in the MQMonitor startup script as shown below:

On Windows, update the startMQMonitor.bat file as:

%JAVA_HOME%\bin\java -Xms4m -Xmx512m -cp %CLASSPATH% -Dcom.wily.introscope.agentProfile=.\properties\IntroscopeAgent.profile -DProperties=.\properties\ com.wily.powerpack.websphereMQ.agent.MQMonitor.MQMonitor -Djava.net.preferIPv6Addresses=true

On UNIX, update the startMQMonitor.sh with the same argument specified above.

The Investigator will then display the full IPv6 IP address under *SuperDomain* > <hostname> > WebSphere MQ and Message Broker > WebSphere MQ and Message Broker Agent > Host:IP Address.

238 Support for IPv6 Environment

Local Product

» Note If the IPv6 address is not mentioned in the hosts file of the machine on which the MQMonitor agent is running, it displays 0:0:0:0:0:0:0:1.

MQ Java Connectors

To configure the MQ Java Connectors:

Follow the steps described in the Introscope 8.0.3.0 Release Notes to enable IPV6 addresses for the MQ Java Connectors.

Support for WebSphere MQ and WebSphere MB in an IPv6 environment

If WebSphere MQ and WebSphere MB are in an IPv6 environment, the relevant IPv6 addresses can be provided in the MQMonitor.properties and MBMonitor.properties files. For example, to monitor a Queue Manager QMGR1 that is configured on an IPv6 machine, add the following lines to your MQMonitor.properties file:

mq.monitor.list=QMGR1

QMGR1.host=2002:9b23:2d7b:0:20f:1fff:fe7e:59c4

» Note The following configuration does not work:

mq.monitor.list=QMGR1@2002:9b23:2d7b:0:20f:1fff:fe7e:59c4

Glossary 239

GLOSSARY

Glossary

backout

When errors occur in a Message Broker Message Flow, a message rolls back and is backed out onto the input queue. Each of these events is called a backout.

coordinated transaction

Message flows execute within a globally coordinated transaction. In coordinated transaction mode, either all or none of the changes associated with one message are accepted.

coupling facility

On z/OS, a special logical partition that provides high-speed caching, list processing, and locking functions.

cross-process transaction

A cross-process trasaction is a transaction that spans all Java and non-Java processes

in doubt

A message queue channel is said to be in doubt when the sending Message Channel Agent is waiting for an acknowledgement of receipt for a batch of messages. It is not in doubt at all other times, including the period during which messages are being sent but before an acknowledgment has been requested.

Java trace

A Java trace is a trace generated by the MQ Java Connector agent.

handshake

The communication between the MQMonitor agents and MQ Java Connector agents is called a handshake. You can perform handshake by creating a queue (called handshake queue) on an existing Queue Manager or a new Queue Manager, that is accessible from all application servers and MQMonitor agents.

240 Glossary

CA Wily Introscope PowerPack for WebSphere MQ Connectors and Messaging System

message channel agent (MCA)

A program that transmits prepared messages from a transmission queue to a communication link, or from a communication link to a destination queue.

MQ Trace

An MQ trace is a trace generated by the MQMonitor agent.

queue depth

The number of messages on a queue. Maximum queue depth is defined for each queue and is measured as a percentage. When a queue reaches this maximum, no more messages can be put on it, leading to performance problems. Therefore, increases in queue depth are an indication of possible performance problems.

retry, long/short

WebSphere administrators can specify the maximum number of times a channel tries to allocate a session to its partner; this can be stated using two variables, a long retry count (LONGRTY) and a short retry count (SHORTRTY). If the initial allocation attempt fails, the short retry count number is decremented and the channel retries the remaining number of times. If it still fails, it retries a long-retry-count number of times with an interval of long retry interval between each try. If it is still unsuccessful, the channel closes down.

timeout

A delay in sending a message into a message flow after it has been received.

Index 241

INDEX

Index

Aagent directory 10aggregated metrics 125, 127, 147, 148, 182,

183, 184, 185, 189application server host 10

BBroker Statistics 35

Cchannels 71, 81CMP (Configuration Management Proxy) 34Compute Node 84configuration

delay times 37IntroscopeAgent.profile 41JCA Connection Pool 55MBMonitor.properties 33MQ Events 23MQMonitor.properties 20WebSphere MB 64

configuring MQMonitor agent 20Console 67

Ddashboard colors 76dashboards 68, 81

MessageBroker 118Overview dashboard 207, 210, 215

Dead Letter Queue 72, 162

EEnterprise Manager (EM)

host 71ErrorDetector 54Execution Group 72, 184, 185

Ffiltering metrics 30

Iinstallation

download software 11extract MQMonitor agent files 15Management Modules 56MQ Java Connectors 47MQMonitor agent 15

IntroscopeAgent.profile 41

Llast check 72, 163

MManagement Modules 56, 67, 109Message Broker 181message throughput 83metric data types 123metrics

aggregated 76Channel Initiator 169log metrics 174Message Broker 72, 181

Broker Queue Manager 194Broker statistics

Client and Neighbor statistics 186Wide Statistics 187

Configuration Manager 182Message Flow 188

Queue Manager 71, 146channels 148Configuration properties 153host status 147queues 164

242 Index

CA Wily Introscope PowerPack for WebSphere MQ Connectors and Messaging System

status 147Queue Manager Cluster 125

configuration properties 136workload balance 139

Queue Manager Cluster-Receiver Channel 132

Queue Manager Cluster-Sender Channel 132metrics sets 25, 124MQ Events 79

NNode Statistics 37

PPercent Queue Depth Variation 144PMI settings 56

QQueue Manager 73

metrics 146

Rrecommended metrics set 26

Sstarting the MQMonitor agent 43stopping the MQMonitor agent 43

Ttraffic lights 75troubleshooting 81

WWebSphere MB 64WebSphere Message Broker node 64

powerpack for websphere mq v8 1userguide

Documents