Kqiuserguide 601

Tivoli IBM Tivoli OMEGAMON XE for Messaging

Version 6.0.1
WebSphere Message Broker Monitoring User’s Guide
SC23-7954-00
Tivoli IBM Tivoli OMEGAMON XE for Messaging
®

Version 6.0.1
WebSphere Message Broker Monitoring User’s Guide
SC23-7954-00
Note:
Before using this information and the product it supports, read the information in Appendix F, “Notices,” on page 133.
Second Edition (August 2007)

This edition applies to version 6.0.1 of IBM Tivoli OMEGAMON XE for Messaging: WebSphere Message Broker
Monitoring (product number 5724-N13 on Windows, UNIX and Linux; product number 5698-A87 on z/OS) and to
all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 2005,2006. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . v Monitoring a large number of brokers . . . . 19
Splitting the brokers among several agents on
Tables . . . . . . . . . . . . . . . vii z/OS . . . . . . . . . . . . . . . 19
Dividing broker monitoring between different
agents on UNIX and Linux . . . . . . . . 20
Preface . . . . . . . . . . . . . . . ix Dividing broker monitoring between different
About This document . . . . . . . . . . . ix agents on Windows. . . . . . . . . . . 20
Who should read this document . . . . . . ix
Related publications . . . . . . . . . . ix
Chapter 3. Customizing the
Publications . . . . . . . . . . . . . x
Accessing publications online . . . . . . . . . x CandleMonitor node . . . . . . . . . 23
Ordering publications . . . . . . . . . . . xi The CandleMonitor node . . . . . . . . . . 23
Tivoli technical training . . . . . . . . . xi Making the CandleMonitor node available to
Support information . . . . . . . . . . xi message flows . . . . . . . . . . . . . 24
Documentation conventions . . . . . . . . . xi Deleting the CandleMonitor node . . . . . . 25
Panels and figures . . . . . . . . . . . xi Message Brokers Toolkit V5.0 . . . . . . . 25
Revision bars . . . . . . . . . . . . . xi Message Brokers Toolkit V5.1 . . . . . . . 26
Variables and literals . . . . . . . . . . xii Message Brokers Toolkit V6.0 . . . . . . . 27
Symbols . . . . . . . . . . . . . . xii CandleMonitor node attributes . . . . . . . . 27
type . . . . . . . . . . . . . . . . 27
collectQueueTime . . . . . . . . . . . 28
What’s New in Version 6.0.1 . . . . . xiii
eventMessage. . . . . . . . . . . . . 28
subFlowName . . . . . . . . . . . . 28
Chapter 1. WebSphere Message Broker activateNode . . . . . . . . . . . . . 29
Monitoring . . . . . . . . . . . . . 1 Positioning the CandleMonitor node . . . . . . 30
What WebSphere Message Broker Monitoring does . 1 Monitoring the input or output of a message
How WebSphere Message Broker Monitoring works 1 flow . . . . . . . . . . . . . . . . 30
IBM Tivoli Monitoring . . . . . . . . . . . 2 Monitoring subflows . . . . . . . . . . 31
Tivoli Enterprise Monitoring Server . . . . . . 2 Monitoring other aspects of a message flow . . 33
Tivoli Enterprise Portal . . . . . . . . . . 2 Producing event messages . . . . . . . . 33
Tivoli Enterprise Monitoring agents . . . . . . 3 Best practice guidelines . . . . . . . . . 34
IBM Tivoli OMEGAMON DE . . . . . . . . 3 Customizing a CandleMonitor node . . . . . . 34
Policy Management . . . . . . . . . . . 3 Changing variables on Windows . . . . . . 34
Where to find more information . . . . . . . 4 Changing variables on UNIX or Linux . . . . 35
Key features . . . . . . . . . . . . . . 4 Changing variables on z/OS. . . . . . . . 35
Predefined workspaces and views . . . . . . 4 Configuration variables . . . . . . . . . 35
User-defined workspaces . . . . . . . . . 4
Predefined monitoring situations . . . . . . 5 Chapter 4. Usage scenarios . . . . . . 39
Attributes . . . . . . . . . . . . . . 5 Monitoring application message flow performance 39
Take Action commands . . . . . . . . . . 5 Determining application delivery failure of
Historical data collection . . . . . . . . . 6 messages . . . . . . . . . . . . . . . 40
Debugging a message flow . . . . . . . . . 40
Chapter 2. Parameters and performance Determining when a message flow has failed . . . 41
considerations . . . . . . . . . . . . 7 Verifying the broker configuration . . . . . . . 41
The parameter file . . . . . . . . . . . . 7 Collecting requested system trace data for a broker
Names and locations of agent parameter files . . 7 on a remote system . . . . . . . . . . . . 42
The default agent parameter file . . . . . . . 8 Stopping a message flow that has a full output
Agent parameter file syntax . . . . . . . . 9 queue . . . . . . . . . . . . . . . . 42
Setting Agent Parameters . . . . . . . . . . 9 Automatically starting a broker that is stopped . . 42
Modifying an existing parameter . . . . . . 9 Planning broker capacity . . . . . . . . . . 43
Adding new parameters . . . . . . . . . 10 Ensuring reasonable message flow response times 43
Agent parameter descriptions . . . . . . . . 11 Preventing inadvertent use of trace active . . . . 44
KqiAgent . . . . . . . . . . . . . . 11 Starting and stopping message flows at periodic
MonitorBroker . . . . . . . . . . . . 15 intervals . . . . . . . . . . . . . . . 44
ConnectQueueManager . . . . . . . . . 18 For individual message flows . . . . . . . 44
Agent performance considerations . . . . . . . 19 For all message flows within an execution group 44
© Copyright IBM Corp. 2005,2006 iii

Verifying subscriptions without accessing the Message Processing Node Information workspace 84
Message Brokers Toolkit . . . . . . . . . . 45 Message Processing Nodes with Queue workspace 85
Subscribing to a topic fails security . . . . . . 45 Multicast Group Statistics workspace . . . . . . 86
Multicast Summary Statistics workspace . . . . . 87
Chapter 5. Situations and Take Action Multicast Topic Statistics workspace . . . . . . 88
commands . . . . . . . . . . . . . 47 Neighbors workspace . . . . . . . . . . . 89
Product Events workspace . . . . . . . . . 89
Predefined situations . . . . . . . . . . . 47
Publish-Subscribe Statistics workspace . . . . . 90
Alerts . . . . . . . . . . . . . . . 47
Retained Publications workspace . . . . . . . 92
Take Action commands . . . . . . . . . . 48
Snapshot Message Flow Accounting workspace . . 92
Issuing Take Action commands . . . . . . . 48
Snapshot Node Accounting workspace . . . . . 95
Command restrictions on z/OS . . . . . . . 48
Snapshot Terminal Accounting workspace . . . . 96
Commands for agent-managed systems . . . . 48
Snapshot Thread Accounting workspace . . . . . 97
Commands for broker-managed systems . . . 50
Sub-Flow Statistics workspace . . . . . . . . 99
Using Take Action commands in situations . . . 54
Subscriptions workspace . . . . . . . . . 100
Chapter 6. Workspaces . . . . . . . . 57
Chapter 7. Historical data . . . . . . 103
Prerequisites . . . . . . . . . . . . . . 57
Initial settings for historical collection . . . . . 103
User statistics . . . . . . . . . . . . . . 57
Starting historical data collection . . . . . . . 104
Snapshot and archive accounting statistics . . . . 58
Stopping historical data collection . . . . . . 105
Reset of statistics . . . . . . . . . . . . 59
Viewing historical data for a selected time frame 106
Upgrading workspaces . . . . . . . . . . 59
Workspace summary . . . . . . . . . . . 60
Agent and application status workspaces . . . 60 Appendix A. Support Information . . . 109
Broker and message flow Information Obtaining fixes . . . . . . . . . . . . . 109
workspaces . . . . . . . . . . . . . 60 Receiving weekly support updates . . . . . . 110
Event workspaces . . . . . . . . . . . 61 Contacting IBM Software Support . . . . . . 110
Statistics workspaces . . . . . . . . . . 61 Determining the business impact . . . . . . . 111
Accounting workspaces . . . . . . . . . 61 Describing problems and gathering information 112
Publish and Subscribe workspaces . . . . . . 62 Submitting problems . . . . . . . . . . . 112
ACL Entries workspace . . . . . . . . . . 62
Agent Status Workspace (agent-level summary) . . 63 Appendix B. Disk Space Requirements
Archive Message Flow Accounting workspace . . . 63 for Historical Data Tables . . . . . . 113
Archive Node Accounting workspace . . . . . . 65 Historical data tables . . . . . . . . . . . 113
Archive Terminal Accounting workspace . . . . 67 Historical table record sizes . . . . . . . . . 114
Archive Thread Accounting workspace . . . . . 68 Historical space requirements worksheets . . . . 116
Broker Events workspace . . . . . . . . . . 69 Historical disk space summary worksheet . . . . 122
Broker Information workspace . . . . . . . . 70
Broker Statistics workspace . . . . . . . . . 72
Appendix C. Language codes . . . . 123
Broker Status workspace (broker-level summary) . . 73
Broker Summary workspace (multiple monitored
brokers) . . . . . . . . . . . . . . . 74 Appendix D. Architecture codes . . . 125
CandleMonitor Node Statistics workspace . . . . 75
Components workspace . . . . . . . . . . 76 Appendix E. Glossary . . . . . . . . 127
Execution Group Information workspace . . . . 77
Execution Group Statistics workspace . . . . . 78 Appendix F. Notices . . . . . . . . 133
Message Flow Events workspace . . . . . . . 80 Trademarks . . . . . . . . . . . . . . 135
Message Flow Information workspace . . . . . 81
Message Flow Statistics workspace . . . . . . 82
Message Processing Node Attributes workspace . . 83
Index . . . . . . . . . . . . . . . 137
iv IBM Tivoli OMEGAMON XE for Messaging: WebSphere Message Broker Monitoring User’s Guide
Figures
1. Agent–Server–Client Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Default kqi.xml file on Windows, UNIX, and Linux . . . . . . . . . . . . . . . . . . . . 8
3. Default KQIXML file on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4. Example of a monitored flow . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5. Type I subflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6. Type II subflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
7. Example of ″QI Start Component″ command in a situation . . . . . . . . . . . . . . . . . . 54
8. QI Agent in the Navigator physical view . . . . . . . . . . . . . . . . . . . . . . . . 63
9. Broker managed system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
10. Broker managed system merged with the QI Broker . . . . . . . . . . . . . . . . . . . . 74
11. QI broker in the Navigator physical view . . . . . . . . . . . . . . . . . . . . . . . 75
© Copyright IBM Corp. 2005,2006 v

vi IBM Tivoli OMEGAMON XE for Messaging: WebSphere Message Broker Monitoring User’s Guide
Tables
1. Symbols in command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
2. The effect of providing a subFlowName attribute for each node type . . . . . . . . . . . . . . 28
3. Workspaces with user statistics links . . . . . . . . . . . . . . . . . . . . . . . . . 58
4. WebSphere Message Brokers Monitoring historical data tables . . . . . . . . . . . . . . . . 113
5. WebSphere Message Brokers Monitoring Table Record Sizes . . . . . . . . . . . . . . . . . 114
6. Components (kqitcomp) worksheet . . . . . . . . . . . . . . . . . . . . . . . . . 116
7. Product Events (kqitprev) worksheet . . . . . . . . . . . . . . . . . . . . . . . . . 116
8. Broker Information (kqitbrkr) worksheet . . . . . . . . . . . . . . . . . . . . . . . 116
9. Broker Events (kqitbrev) worksheet . . . . . . . . . . . . . . . . . . . . . . . . . 117
10. Message Flow Events (kqitflev) worksheet . . . . . . . . . . . . . . . . . . . . . . . 117
11. Broker Statistics (kqitstbr) worksheet . . . . . . . . . . . . . . . . . . . . . . . . . 117
12. Execution Group Statistics (kqitsteg) worksheet . . . . . . . . . . . . . . . . . . . . . 117
13. Message Flow Statistics (kqitstmf) worksheet . . . . . . . . . . . . . . . . . . . . . . 117
14. Sub-Flow Statistics (kqitstsf) worksheet . . . . . . . . . . . . . . . . . . . . . . . . 118
15. CandleMonitor Node Statistics (kqitstfn) worksheet . . . . . . . . . . . . . . . . . . . . 118
16. Message Flow Accounting (kqitasmf) worksheet . . . . . . . . . . . . . . . . . . . . . 118
17. Thread Accounting (kqitasth) worksheet . . . . . . . . . . . . . . . . . . . . . . . 118
18. Node Accounting (kqitasnd) worksheet . . . . . . . . . . . . . . . . . . . . . . . . 119
19. Terminal Accounting (kqitastr) worksheet . . . . . . . . . . . . . . . . . . . . . . . 119
20. Execution Group Information (kqitdfeg) worksheet . . . . . . . . . . . . . . . . . . . . 119
21. Message Flow Information (kqitdfmf) worksheet . . . . . . . . . . . . . . . . . . . . . 119
22. Message Processing Node Information (kqitdffn) worksheet . . . . . . . . . . . . . . . . . 120
23. Neighbors (kqitdsen) worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . 120
24. Subscriptions (kqitdses) worksheet . . . . . . . . . . . . . . . . . . . . . . . . . 120
25. Retained Publications (kqitdser) worksheet . . . . . . . . . . . . . . . . . . . . . . 120
26. ACL Entries (kqitdsea) worksheet . . . . . . . . . . . . . . . . . . . . . . . . . . 120
27. Multicast group statistics (kqitpsms) worksheet . . . . . . . . . . . . . . . . . . . . . 121
28. Multicast summary statistics (kqitpsmg) worksheet . . . . . . . . . . . . . . . . . . . . 121
29. Multicast topic statistics (kqitpsmt) worksheet . . . . . . . . . . . . . . . . . . . . . 121
30. Publish-subscribe statistics (kqitpsst) worksheet . . . . . . . . . . . . . . . . . . . . . 121
31. Language codes for the supported languages . . . . . . . . . . . . . . . . . . . . . . 123
32. Operating system architecture abbreviations . . . . . . . . . . . . . . . . . . . . . . 125
© Copyright IBM Corp. 2005,2006 vii

viii IBM Tivoli OMEGAMON XE for Messaging: WebSphere Message Broker Monitoring User’s Guide
Preface
WebSphere Message Broker Monitoring is a component of the IBM Tivoli
OMEGAMON XE for Messaging product suite. It can help you monitor, analyze,
and manage IBM® message broker products in your IBM business integration
system.
About This document

This document describes the features and capabilities of WebSphere Message
Broker Monitoring, and explains how to use it to monitor your business integration
systems.
Who should read this document

This document is intended for IT operations staff or administrators who monitor
the reliability and availability of business integration systems and must react to
any problems that occur within those systems. It is also useful for application
developers who design, implement, and test business integration components and
systems.
Note: To perform any of the actions described in this document, you must have
IBM Tivoli Monitoring and WebSphere Message Broker Monitoring installed
and configured within your environment. For instructions, see the
installation and configuration documents listed in “Related publications.”
Related publications
This section lists documents and other publications that may be useful for users of
IBM Tivoli® Monitoring and IBM Tivoli OMEGAMON XE for Messaging. All the
publications are available from IBM's online Tivoli Library. See “Accessing
publications online” on page x for information about accessing these publications.
The installation and configuration instructions in the following documents are a

prerequisite to the instructions in WebSphere® Message Broker Monitoring User's
Guide:
v Windows®, UNIX®, and Linux®:
– IBM Tivoli Monitoring Installation and Setup document, SC32-9407
– IBM Tivoli OMEGAMON XE for Messaging: Installation Guide, GC32-1829
v z/OS®:
– Configuring Tivoli Enterprise Monitoring Server on z/OS , SC32-9463
– IBM Tivoli OMEGAMON XE for Messaging on z/OS: Configuration Guide,
SC32-1830-00
The following documents explain how to use the other component products of
IBM Tivoli OMEGAMON XE for Messaging:
v IBM Tivoli OMEGAMON XE for Messaging: WebSphere MQ Monitoring User’s
Guide, SC32-1825
v IBM Tivoli OMEGAMON XE for Messaging: WebSphere MQ Configuration User’s
Guide, SC32-1826
© Copyright IBM Corp. 2005,2006 ix

v IBM Tivoli OMEGAMON XE for Messaging: WebSphere InterChange Server
Monitoring User’s Guide, SC32-1828
v IBM Tivoli OMEGAMON XE for Messaging: Problem Determination Guide,
SC32-1831
Publications
This section lists publications in the IBM Tivoli OMEGAMON XE for Messaging
library.
IBM Tivoli OMEGAMON XE for Messaging library

This following documents provide information about IBM Tivoli OMEGAMON XE
for Messaging:
v IBM Tivoli OMEGAMON XE for Messaging: Installation and Setup Guide,
GI11-8074-00 Describes how to install IBM Tivoli OMEGAMON XE for
Messaging on Windows, UNIX, Linux and OS/400.
v Upgrading to IBM Tivoli OMEGAMON XE for Messaging 6.0.1 Provides
information about how to upgrade or migration from previous versions to IBM
Tivoli OMEGAMON XE for Messaging 6.0.1.
v IBM Tivoli OMEGAMON XE for Messaging on z/OS: Configuration Guide,
SC23-7951-00 Provides information about installing and setting up IBM Tivoli
OMEGAMON XE for Messaging and upgrading from a previous installation.
v IBM Tivoli OMEGAMON XE for Messaging: WebSphere MQ Monitoring User's
Guide, SC23-7952-00 Provides instructions for using the features of WebSphere
MQ Monitoring.
v IBM Tivoli OMEGAMON XE for Messaging: WebSphere MQ Configuration User's
Guide, SC23-7953-00 Provides instructions for using the features of WebSphere
MQ Configuration.
v IBM Tivoli OMEGAMON XE for Messaging: WebSphere Message Broker Monitoring
User's Guide, SC23-7954-00 Provides instructions for using the features of
WebSphere Message Broker Monitoring.
v IBM Tivoli OMEGAMON XE for Messaging: WebSphere InterChange Server
Monitoring User's Guide, SC23-7950-00 Provides instructions for using the
features of WebSphere InterChange Server Monitoring.
The following documents also provide useful information:

v IBM Tivoli Monitoring Administrator’s Guide SC32-9408, describes the support
tasks and functions required for the Tivoli Enterprise Portal Server and clients,
including Tivoli Enterprise Portal user administration.
v IBM Tivoli Monitoring User’s Guide SC32-9409, provides hands-on lessons and
detailed instructions for all Tivoli Enterprise Portal features.
v IBM Tivoli Monitoring Problem Determination Guide GC32-9458, provides
information and messages to assist users with troubleshooting problems with
IBM Tivoli Monitoring.
Accessing publications online

IBM posts publications for all Tivoli products, as they become available and
whenever they are updated, to the Tivoli software information center Web site.
Access the Tivoli software information center by first going to Tivoli Library at:
http://www.ibm.com/software/tivoli/library/
x IBM Tivoli OMEGAMON XE for Messaging: WebSphere Message Broker Monitoring User’s Guide
Click the Tivoli Product manuals link. In the Tivoli Technical Product Documents
Alphabetical Listing window, click the link for the information that you want to
view.
If you print PDF documents on paper that is not letter sized, set the option in the
File > Print window that enables Adobe Reader to print letter-sized pages on your
local paper.
Ordering publications
You can order Tivoli publications online at the following Web site:
http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/
pbi.cgi
You can also order by telephone by calling one of the following numbers:
v In the United States: 800-879-2755
v In Canada: 800-426-4968
In other countries, contact your software account representative to order Tivoli

publications.
Tivoli technical training

For Tivoli technical training information, see the following IBM Tivoli Software
Training and Certification Web site:
http://www.ibm.com/software/tivoli/education
Support information
If you have a problem with your IBM software, you want to resolve it quickly. IBM
provides the following ways for you to obtain the support you need:
v Searching knowledge bases: You can search across a large collection of known
problems and workarounds, Technotes, and other information.
v Obtaining fixes: You can locate the latest fixes that are already available for your
product.
v Contacting IBM Software Support: If you still cannot solve your problem, and
you need to work with someone from IBM, you can use a variety of ways to
contact IBM Software Support.
For more information about these three ways of resolving problems, see
Appendix A, “Support Information,” on page 109.
Documentation conventions
This document uses several conventions for special terms and actions, and for
operating-system-dependent commands and paths.
Panels and figures

The panels and figures in this document are representations. Actual product panels
might be different from what is shown.
Revision bars
Revision bars (|) in the left margin identify new or updated material.
Preface xi
Variables and literals
In examples of command syntax for the z/OS, OS/400, and NonStop Kernel
platforms, uppercase letters indicate actual values (literals) that you should type;
lowercase letters indicate variables that represent data supplied by the user:
LOGON APPLID (cccccccc)
However, for the Windows, UNIX and Linux operating systems, variables are
shown in italics:
-itm.kzy.instrument.control.file=instrumentation_control_file_name
-itm.kzy.agent.parms=agent_control_file_name
Note: In ordinary text, variable names appear in italics, regardless of operating

system.
Symbols
The following symbols might appear in command syntax:
Table 1. Symbols in command syntax
Symbol Usage
| A vertical bar is used to denote a choice. This means that you can
choose either the argument on the left or the argument on the right.
Example:
YES | NO In this example, you can specify YES or NO.

[] Brackets denote optional arguments. Arguments not enclosed in
brackets are required.
Example:
APPLDEST DEST [ALTDEST] In this example, DEST is a required

argument and ALTDEST is optional.
{} Braces denote required arguments, or to group arguments for clarity.
Example:
COMPARE {workload} -
REPORT={SUMMARY | HISTOGRAM} The workload variable is
required. The REPORT keyword must be specified with a value of
SUMMARY or HISTOGRAM.
_ Default values are underscored.
Example:
COPY infile outfile - [COMPRESS={YES | NO}] In this example, the

COMPRESS keyword is optional. If specified, the only valid values are
YES or NO. If omitted, the default is YES.
xii IBM Tivoli OMEGAMON XE for Messaging: WebSphere Message Broker Monitoring User’s Guide
What’s New in Version 6.0.1
WebSphere Message Broker Monitoring version 6.0.1 has the following new
features and enhancements:
v Better performance. In previous versions of WebSphere Message Broker
Monitoring, if message brokers in your environment processed a very large
volume of messages, the collection of data for the Message Processing Node
Information and Message Processing Nodes with Queue workspaces would
drastically degrade performance. If you encounter this problem, you can now
disable these 2 workspaces using variables in the WebSphere Message Broker
Monitoring agent configuration files. On the other hand, you can use these
variables to enable the workspaces if you want to see the detail data. These 2
workspaces are disabled by default.
v 64-bit architecture support. To take full advantage of systems with a 64-bit
architecture, WebSphere Message Broker Monitoring now includes a 64-bit
version of the CandleMonitor node. This provides improved performance and is
compatible with AIX®, Solaris and HP-UX.
v Product-predefined workspaces cannot be customized. You can use a
product-predefined workspace as a template to create a new one. See
“User-defined workspaces” on page 4
v Support for the following operating systems has been added to this release:
– i5/OS® 5.4
– RedHat Enterprise Linux 4 on AMD64/EM64T
– RedHat Enterprise Linux 4 on iSeries™ and pSeries®
– SUSE Linux Enterprise Server 9 for iSeries and pSeries
– SUSE Linux Enterprise Server 10 for iSeries and pSeries
– SUSE Linux Enterprise Server 10 Intel®
– SUSE Linux Enterprise Server 10 on AMD64/EM64T
– SUSE Linux Enterprise Server 10 for zSeries® 64-bit
– HP-UX 11i on Itanium®
– z/OS 1.7
– z/OS 1.8
For a complete list of operating systems that are supported by IBM Tivoli
OMEGAMON® XE for Messaging V6.0.1, see IBM Tivoli OMEGAMON XE for
Messaging: Installation and Setup Guide, GI11-8074-00.
v IBM Support Assistant. You can use the IBM Support Assistant (ISA) to help you
find and view information about IBM Tivoli WebSphere MQ Monitoring quickly
and easily. The ISA is a stand-alone application, which can be downloaded for
free from the IBM Web site, and provides links to all IBM Tivoli OMEGAMON
XE for Messaging online resources in a single place, and extensive search
capabilities.
© Copyright IBM Corp. 2005,2006 xiii

xiv IBM Tivoli OMEGAMON XE for Messaging: WebSphere Message Broker Monitoring User’s Guide
Chapter 1. WebSphere Message Broker Monitoring
WebSphere Message Broker Monitoring is a monitoring and management tool that
provides you with the means to verify, analyze, and tune Message Broker
topologies associated with the following WebSphere products:
v IBM WebSphere Business Integration Event Broker V5
v IBM WebSphere Business Integration Message Broker V5
v IBM WebSphere Business Integration Message Broker with Rules and Formatter
Extension V5
v IBM WebSphere Event Broker V6
v IBM WebSphere Message Broker V6
v IBM WebSphere Message Broker with Rules and Formatter Extension V6
Note: In this user guide, these IBM products are referred to jointly as WebSphere
Message Brokers or IBM broker products. The version numbers (V2.1, V5,
and V6) are used to distinguish between the three suites of products as
necessary.
What WebSphere Message Broker Monitoring does

WebSphere Message Broker Monitoring helps ensure the reliability and
performance of your broker environment by detecting and correcting broker and
message flow problems before they have an impact on service speed and
availability. WebSphere Message Broker Monitoring also reduces the amount of
time it takes to deploy broker applications by helping you to debug message flows
and providing statistics that you can use to tune your environment.
You can use WebSphere Message Broker Monitoring to perform the following
tasks:
v Monitor the status of your IBM broker product and its components.
v View information and performance statistics for broker topologies at broker,
execution group, message flow, node, terminal, and thread level in both tabular
and chart form.
v Issue IBM broker product commands using the WebSphere Message Broker
Monitoring interface to directly manage your environment, or create automatic
responses to WebSphere Message Broker events.
v Receive alerts when performance thresholds are exceeded or when message flow
events occur.
v Retain data samples in history files and save them to a historical database for
reporting and analysis purposes.
How WebSphere Message Broker Monitoring works

WebSphere Message Broker Monitoring agents collect data from WebSphere
Message Brokers. The data is presented in charts and tables that you can examine
to monitor the performance of your WebSphere Business Integration systems. The
agents also evaluate the data to determine when specified values meet criteria that
you have defined and trigger alerts or programmed actions in response.
© Copyright IBM Corp. 2005,2006 1

In addition, WebSphere Message Broker Monitoring provides a CandleMonitor
node. When inserted into a message flow, the CandleMonitor node collects
message flow and subflow performance statistics and provides a mechanism for
generating user-defined events.
IBM Tivoli Monitoring

IBM Tivoli Monitoring manages system and network applications on several
operating systems and keeps track of the availability and performance of all parts
of your enterprise. It provides IBM Tivoli OMEGAMON XE products with a
common agent-server-client architecture:
Tivoli Enterprise Monitoring Server
Tivoli Enterprise
Portal Clients
Monitoring Agents
Tivoli Enterprise Portal Server
Figure 1. Agent–Server–Client Architecture
Tivoli Enterprise Monitoring Server

Tivoli Enterprise Monitoring Server (TEMS) gathers data from the Tivoli Enterprise
Monitoring Agent (TEMA) and acts as a collection and control point for alerts that
are received from the agents. The TEMS sends the data that it receives from the
agents to Tivoli Enterprise Portal clients, where it is displayed in tabular or graphic
views in a set of predefined or customized workspaces. The TEMS also accepts
requests for information or action from Tivoli Enterprise Portal clients and
distributes them to the agents for processing.
Tivoli Enterprise Portal

Tivoli Enterprise Portal (TEP) is the Java-based interface to the data monitoring
and management resources of IBM Tivoli Monitoring. Depending on how it is
installed, Tivoli Enterprise Portal can be used as either a desktop or browser-based
client.
Tivoli Enterprise Portal has its own server, Tivoli Enterprise Portal Server (TEPS).
TEPS performs common Tivoli Enterprise Portal functions, which reduces the
processing performed by the Tivoli Enterprise Portal client.
2 IBM Tivoli OMEGAMON XE for Messaging: WebSphere Message Broker Monitoring User’s Guide
Tivoli Enterprise Monitoring agents
Tivoli Enterprise Monitoring agents (TEMA) collect system or application data
from monitored, or managed, systems. The WebSphere MQ Monitoring agent, for
example, let you easily collect and analyze WebSphere MQ-specific data for all
your remote and local queue managers from a single vantage point. The data is
passed to the TEMS, and displayed in the Tivoli Enterprise Portal client.
TEMA can also compare the current values of monitored properties against a set of
defined conditions, and trigger alerts or actions when those conditions occur. They
can accept and perform requested actions that are relayed to them from TEP clients
by the TEMS.
Configuration agents can create and configure objects. The WebSphere MQ

Configuration agent can configure objects such as WebSphere MQ queue managers
and all their components (queues, channels, processes, and so on).
IBM Tivoli OMEGAMON DE

The IBM Tivoli OMEGAMON DE feature package for Tivoli Enterprise Portal
offers a process-driven view of your enterprise. It enables you to bring together
information from disparate sources, including a range of operating systems,
servers, databases, mainframes, and network and Internet components, in one
workspace and provides a single point of control from which you can manage all
the resources your business-critical applications rely on.
IBM Tivoli OMEGAMON DE extends the capabilities of IBM Tivoli OMEGAMON

XE to include:
v Enterprise-specific Navigator views
The Navigator physical view shows the hierarchy of your managed enterprise
by operating system and type of Tivoli Enterprise Monitoring agent. The
Navigator business view offered by IBM Tivoli OMEGAMON DE shows the
hierarchy of managed objects. You can also define Navigator views for any
logical groupings, such as business processes or by departmental hierarchy.
v Views of data from different types of monitoring agents in one workspace
In a single workspace, you can build a table or chart with data from one type of
monitoring agent, and another table or chart with data from a different agent.
Within that workspace, you can show views from as many different agent types
as are included on that branch of the Navigator.
v Linking application workspaces
You can define links from a workspace associated with one type of monitoring
agent to workspaces associated with other types of agents.
Policy Management
The Tivoli Enterprise Portal Policy Management solution incorporates all the
features of IBM Tivoli OMEGAMON DE policy management and adds automation
capabilities by means of the Workflow editor. The Workflow editor enables you to
design sets of automated system processes, called policies, to resolve system
problems. A policy performs actions, schedules work to be performed by users, or
automates manual tasks.
Chapter 1. WebSphere Message Broker Monitoring 3

Where to find more information
For more information about IBM Tivoli Monitoring, see the Tivoli Enterprise Portal
online help and the books available in the online Tivoli software information
center.
Key features
This section describes the key features of WebSphere Message Broker Monitoring
and explains how they can help you monitor and manage message brokers and
message flows.
Predefined workspaces and views

Workspaces provide you with status, definition, and statistical information in
tabular and graphical form.
The predefined WebSphere Message Broker Monitoring workspaces provide the

following information:
v Status information for brokers, components, and agents
v Information about brokers, execution groups, message flows, and message
processing nodes
v Information about product, broker, and message flow events
v Information about the environment's publish and subscribe configuration
v Performance statistics organized by broker, execution group, message flow, and
subflow
v Accounting statistics organized by message flow, thread, node, and terminal
You can use the information provided by these workspaces to trace the causes of
performance problems or the reasons why an alert was triggered. You can also
customize these workspaces and the views they contain, or create your own
workspaces and views.
For information about predefined workspaces included with WebSphere Message

Broker Monitoring, see Chapter 6, “Workspaces,” on page 57 or the WebSphere
Message Broker Monitoring section of the Tivoli Enterprise Portal online help. For
information about creating and customizing views and workspaces, see the Tivoli
Enterprise Portal online help or IBM Tivoli Monitoring User’s Guide.
User-defined workspaces
You can create your own workspaces to display information about a specific set of
attributes.
Creating a workspace using a predefined workspace as a

template
Perform the following steps to create your new workspace using a predefined one
as a template:
1. Open the predefined workspace that you want to use as a template.
2. Click File > Save Workspace As to create a copy of the predefined workspace.
3. Enter a workspace name and, optionally, a description. The workspace name
appears on the title bar.
4. Optionally, select one or more of the following workspace options:
v Assign as default for this Navigator Item: Select this option if you want this
workspace to be displayed when this Navigator Item is clicked.
v Do not allow modifications: Select this option to prevent this workspace from
being modified in the future.
v Only selectable as the target of a workspace link: Select this option if you do
not want this workspace to be displayed unless it is linked to from another
workspace.
5. Click OK. A copy of the predefined workspace is created with the name that
you entered.
6. Open the new workspace and customize it to meet your requirements.
Predefined monitoring situations

Situations are descriptions of conditions to which you want to be alerted. When
situations are used on monitored systems they can, for example, alert you to a
broker that has not been started, or to a message flow event. Situations can also be
used to automate responses to problems, such as restarting a component or
stopping a message flow that is consuming too much CPU processing time.
WebSphere Message Broker Monitoring provides a set of predefined situations

designed to help you monitor critical activity and to serve as templates for creating
customized situations of your own.
For information about the predefined situations included with WebSphere Message
Broker Monitoring, see “Predefined situations” on page 47. For information about
creating and editing situations, see the Tivoli Enterprise™ Portal online help.
Attributes
Attributes are characteristics or properties of the objects monitored by WebSphere
Message Broker Monitoring ; for example, the status of brokers, execution groups,
and message flows, or the average time taken for a message flow to process a
message. You specify attributes in query definitions, which are used to collect
information presented in workspace views and to specify the conditions, or
situations, that trigger alerts and automated actions.
WebSphere Message Broker Monitoring monitors 22 groups of attributes. You can

use these attributes to customize predefined views or to create your own views
and workspaces. You can also use attributes to define situations related to specific
thresholds, events, or performance problems that you want to monitor.
For more information about attributes, see the WebSphere Message Broker
Monitoring section of the Tivoli Enterprise Portal online help.
Take Action commands

Using Tivoli Enterprise Portal, you can interact directly with your brokers and
message flows through the Take Action feature. Take Action lets you enter your
own commands, or choose from a list of predefined commands.
You can add a Take Action command to a monitoring situation and configure it to
be run every time the situation becomes true. If you have IBM Tivoli
OMEGAMON DE, you can also create automation policies using Take Action
commands.
You can use the Take Action commands included with WebSphere Message Broker
Monitoring to issue IBM broker product commands from Tivoli Enterprise Portal.
For example, you can start or stop IBM broker products and their queue managers,
Chapter 1. WebSphere Message Broker Monitoring 5

and start and stop message flows, or change their trace characteristics. You can
even change the type of Accounting statistics collected or the interval at which
they are collected.
For information on the commands provided with WebSphere Message Broker

Monitoring, see “Take Action commands” on page 48 or the WebSphere Message
Broker Monitoring section of the Tivoli Enterprise Portal online help.
Historical data collection

You can use Tivoli Enterprise Portal’s historical data collection function to store
data collected by WebSphere Message Broker Monitoring. You can define following
properties of historical data collection:
v The interval at which data is collected
v The interval at which data is stored in a data warehouse (if you choose to do so)
v The location (either at the agent or at the TEMS) at which the collected data is
stored
You can find more information about using the historical data collection function
in the Tivoli Enterprise Portal online help and the IBM Tivoli Monitoring
Administrator’s Guide.
See Chapter 7, “Historical data,” on page 103 for information about the WebSphere
Message Broker Monitoring attributes for which historical data can be collected.
Chapter 2. Parameters and performance considerations
When you install WebSphere Message Broker Monitoring, configuration parameters
for the monitoring agents are set to their default values. This chapter describes the
parameters, and includes instructions for how to change their values if required. It
also describes performance considerations that can affect how you should
configure agents.
The parameter file

The parameters that determine the operational and monitoring characteristics of an
agent are stored in an XML file that is created during the WebSphere Message
Broker Monitoring installation process.
On distributed platforms such as Windows and UNIX, this parameter file is

encoded using UTF–8 and can contain non-English language characters. On these
platforms you can use the remote agent configuration feature instead of editing
this file directly. On z/OS platforms, however, the file is encoded using EBCDIC
and must be edited manually on z/OS system.
After installation, you can view and edit the agent parameter settings file at any
time. You can also add optional configuration parameters to the file.
Names and locations of agent parameter files

This section describes the name and location of the agent parameter file on
different platforms.
Agents parameter files on Z/OS

The agent parameter file member name is KQIXML, by default it is installed in the
following partitioned data set:
&rhilev.RKANDATV
Agent parameter files on UNIX and Linux

The agent parameter file name is kqi.xml.
If you specify broker and agentId parameters when the agent is started, the name
of the agent parameter file is modified. The agent parameter file name for an agent
started with optional broker and agentId parameters has the form:
<hostName>_qi_<brokerName>_##_<agentId>.xml
If you specify only the agentId parameter and not broker parameters when the
agent is started, then the agent parameter file name has the form:
<hostName>_qi_<agentId>.xml
The agent parameter file is located the <install_dir>/config, where <install_dir> is

the directory in which IBM Tivoli OMEGAMON XE for Messaging is installed.
The agent parameter file on Windows

The agent parameter file name is kqi.xml.

If you use the Create Instance option in Manage Tivoli Monitoring Services to
replicate the agent, the name of the agent parameter file is modified. The agent
parameter file name for a file that associated with an agent that was created in this
way is:
kqi_<taskname>.xml
The agent parameter file is located in the directory <install_dir>\TMAITM6, where

<install_dir> is the directory in which IBM Tivoli OMEGAMON XE for Messaging
is installed.
The default agent parameter file

The agent parameter file, as included with WebSphere Message Broker Monitoring,
contains a base set of parameters that are configured to their default values.
However, you can modify the values of these parameters to suit the needs of your
environment and you can add more parameters.
The default file on UNIX, Linux, and Windows

When you first install WebSphere Message Broker Monitoring, the default file
kqi.xml resembles the file shown in Figure 2 on page 8:
This default file contains the core parameters that control reporting and monitoring
by the agent on UNIX, Linux and Windows systems. Because no individual
brokers or queue managers are specified in the file, using the default parameters
shown in this example results in all brokers being monitored by the agent.
<KqiAgent version="601"
defaultRetainBrokerEvents="10"
defaultRetainFlowEvents="10"
retainProductEvents="10"
discoveryInterval="300"
defaultStatisticInterval="60"
defaultFlowEventInterval="15"
defaultHistoricalAccountingType="Archive"
defaultRetainRecentSnapshotSamples="15"
defaultRetainRecentArchiveSamples="5"
defaultRetainRecentPubSubSamples="15"
holdTimeForQuery="180"
defaultReplyQueueName="KQI.AGENT.REPLY.QUEUE"
defaultReplyQueueModel="SYSTEM.BROKER.MODEL.QUEUE"
defaultTakeActionAuthUsers="*"
defaultCollectNodeData="NO">
</KqiAgent>
Figure 2. Default kqi.xml file on Windows, UNIX, and Linux
The default file on z/OS

When you first install WebSphere Message Broker Monitoring, the default file
KQIXML resembles the file shown Figure 3 on page 9.
On z/OS systems, you must specify all monitored brokers in the parameter file
using the MonitorBroker tag. Using the parameters shown in Figure 3 results in
broker MQP1BRK being monitored by the agent. To monitor additional brokers,
add additional MonitorBroker tags as necessary.
<KqiAgent version=”601”
agentId=”QI27”
defaultRetainBrokerEvents=”10”
defaultRetainFlowEvents=”10”
retainProductEvents=”10”
discoveryInterval=”300”
defaultStatisticInterval=”60”
defaultFlowEventInterval=”15”
defaultHistoricalAccountingType="ARCHIVE"
defaultReplyQueueName=”KQI.AGENT.REPLY.QUEUE”
defaultReplyQueueModel=”SYSTEM.BROKER.MODEL.QUEUE”
defaultTakeActionAuthUsers=”*”
<MonitorBroker name=”M53ABRK”
alias="M53ABRK"
componentDirectory=”/var/wmqi/MQP1BRK”>
</MonitorBroker>
</KqiAgent>
Figure 3. Default KQIXML file on z/OS
Agent parameter file syntax

The agent parameter file contains a single pair of top-level <KqiAgent></
KqiAgent> tags. It might also contain one or more instances of the
<MonitorBroker></MonitorBroker> and <ConnectQueueManager></
ConnectQueueManager>. Agent parameters are defined using attributes of these
elements.
The parameters in the kqi.xml file (or KQIXML member on z/OS) are stored in
XML format. You must adhere to XML syntax conventions when modifying the
file. All attribute values must be enclosed in double quotes. However, the actual
coding is not column-specific, so the spacing and line separation shown in the
sample files are not critical.
Setting Agent Parameters

You can change the agent configuration by modifying the default parameter values
listed in the agent parameter file or adding new parameters to it.
Modifying an existing parameter

To modify a parameter that already exists in the agent parameter file, substitute
the original parameter value with your new value; enclose the new value in a set
of double quotes (““).
Original parameter:
defaultStatisticInterval=“original value”
Modified parameter:
defaultStatisticInterval=“new value”
Chapter 2. Parameters and performance considerations 9

Adding new parameters
To add new parameters to the agent parameter file, you must first determine
whether an appropriate XML tag already exists for the parameter.
v If the XML tag that the attribute belongs to already exists, insert the new
parameter string into the tag block. The following examples show how to add
an agentId parameter to a shortened version of the default file kqi.xml:
Original version:
defaultTakeActionAuthUsers=”*”>
</KqiAgent>
Modified version:
agentId=”new_value”
</KqiAgent>
v If the appropriate XML tag does not already exist, insert the correct opening and
closing XML tags before adding the parameter string.
For example, to set MonitorBroker parameters, insert the <MonitorBroker></
MonitorBroker> tags and then add the parameters as follows:
v Original version:
</KqiAgent>
Modified version:
<<KqiAgent version=”601”
<MonitorBroker name="MySpecialBrokerName"
statisticInterval="60"
flowEventInterval="20"
retainBrokerEvents="5"
retainFlowEvents="5"
takeActionAuthUsers="A?B,C*">
</MonitorBroker>
<ConnectQueueManager name="MY.BROKER.QMGR"
replyQueueName="SOME.OTHER.NAME"
replyQueueModel="MY.SPECIAL.MODEL.QUEUE">
</ConnectQueueManager>
</KqiAgent>
Each tag block encapsulates the parameters of a particular component. The
sample file kqismpl.xml is included with UNIX, Linux and Windows versions of
WebSphere Message Broker Monitoring; you can use this file as a template when
you create your own kqi.xml file.
On UNIX and Linux, the file kqismpl.xml is stored in the following directory:
install_dir/config
On Windows, the file kqismpl.xml is stored in the following directory:
<install_dir>\TMAITM6
where <install_dir> is the installation directory of IBM Tivoli OMEGAMON XE
for Messaging.
Agent parameter descriptions
The parameters that you can set in the file kqi.xml (or in the member KQIXML on
z/OS systems), and their associated XML tags, are described in the following
sections. All the parameters are attributes of one of three tags: KqiAgent,
MonitorBroker, and ConnectQueueManager.
KqiAgent
You can use the KqiAgent tag to specify parameters related to the agent itself. Any
attributes that follow this tag apply to the agent as a whole and provide
monitoring and connection defaults that can be overridden at the individual broker
or queue manager level. All attributes are optional.
version
The version attribute specifies the version of WebSphere Message Broker
Monitoring for which the parameters are set. This attribute is reserved for future
product use. Do not alter this attribute from its default value unless instructed to
do so by IBM Software Support.
agentId
The agentId attribute provides a short identifier (maximum length 4 alphanumeric
characters) for the WebSphere Message Broker Monitoring agent.
You must assign a unique agentID to each agent in the following circumstances:
v You are running more than one WebSphere Message Broker monitoring agent on
the same host.
v You are running more than one monitored broker with the same name on
different hosts.
Unique agent IDs differentiate the broker-managed system names in the Tivoli
Enterprise Monitoring Server (TEMS) so that Tivoli Enterprise Portal displays them
correctly.
This parameter is not set by default. To set it, supply an alphanumeric character
string with no spaces. The value is used to create a unique managed system name.
defaultRetainBrokerEvents
The defaultRetainBrokerEvents attribute determines how many broker events to
retain per broker. Report information is available only for retained broker events.
When used with situations, these events are never reset automatically and if
historical situations are active, you can view them historically.
The default number of events to retain is 10. This value must be greater than 0.
defaultRetainFlowEvents
The defaultRetainFlowEvents attribute determines how many message flow events
to retain per broker. Report information is available only for retained message flow
events. When used with situations, these events are never reset automatically and
if historical situations are active, you can view them historically.
retainProductEvents
The retainProductEvents attribute determines the number of product events to
retain. Report information is available only for retained product events. When used

with situations, these events are never reset automatically and if historical
situations are active, you can view them historically.
discoveryInterval
The discoveryInterval attribute determines the interval (in seconds) at which the
agent attempts to rediscover brokers created on the system. This attribute must be
greater than 0; the default value is 300 seconds. This attribute can have a very high
value, for example, 86400 seconds (24 hours) or even longer when you are no
longer creating new brokers. However, if you have a dynamic environment in
which new brokers are created frequently, you should adjust this attribute
accordingly.
defaultStatisticInterval
The defaultStatisticInterval attribute determines the minimum interval at which
broker statistics are sampled, in seconds.
If you are collecting historical data for one of the statistics attribute groups, the
historical data collection interval must be a multiple of the defaultStatisticInterval
value; otherwise, historical data might be inaccurate. For example, if you configure
historical data collection for one of the statistics attribute groups to run every 5
minutes (300 seconds), then the defaultStatisticInterval value must be one of the
following: 60 (1 minute), 75 (1.25 minutes), 100 (1.67 minutes), 150 (2.5 minutes), or
300 (5 minutes). Additionally, for accurate results, the historical data collection
interval of all statistics attribute groups for which historical collection is being
collected must be the same.
This value must be greater than 0; the default value is 60 seconds.
defaultFlowEventInterval
The defaultFlowEventInterval attribute determines the interval at which message
flow events are sampled, in seconds. This interval does not apply to broker events
or product events.
defaultReplyQueueName
The defaultReplyQueueName attribute specifies the name of the queue that will be
used to receive publications and reply messages from the broker. A temporary
dynamic queue is created if the name given does not pre-exist as a permanent
queue name on the broker’s queue manager. If the specified queue name is less
than 33 characters long, the queue manager automatically modifies it to ensure that
it is unique. This value can be overridden for individual queue managers using the
replyQueueName attribute
The default value is KQI.AGENT.REPLY.QUEUE.
defaultReplyQueueModel
The defaultReplyQueueModel attribute specifies the name of the queue that will be
used as a model for creating the agent reply queue for any queue manager to
which the agent connects. The agent will create a queue with the name specified
by the defaultReplyQueueName attribute for each queue manager it monitors
using the properties of the queue specified by defaultReplyQueueModel as a
model. Thus, by changing the properties of the queue named by this attribute, you
can modify the properties of agent reply queues used by queue managers to which
the agent connects. This value can be overridden for individual queue managers
using the replyQueueModel attribute.
The default value is SYSTEM.BROKER.MODEL.QUEUE.
defaultTakeActionAuthUsers
The defaultTakeActionAuthUsers attribute specifies which Tivoli Enterprise Portal
users are authorized to issue the Take Action commands associated with an agent.
You can specify multiple values for this attribute to authorize multiple users and
use the asterisk (*) and question mark (?) wildcard characters to authorize a group
of users. Only Tivoli Enterprise Portal users who have an ID that matches the
values of this attribute are authorized to issue Take Action commands handled by
the WebSphere Message Broker Monitoring agent. Tivoli Enterprise Portal user IDs
are defined in the TEMS and do not necessarily exist on the node on which the
agent is running. This attribute’s values apply only to commands that are not
related to a particular broker, or that are related to a broker that does not have a
specific list of users specified using the takeActionAuthUsers parameter.
The default value is an asterisk (*), which authorizes all Tivoli Enterprise Portal
users to issue Take Action commands that are associated with this agent.
commandTimeoutInterval
The commandTimeoutInterval attribute specifies the amount of time (in seconds)
after sending a command that the agent waits for a response from a broker before
issuing a message indicating that the broker is not responding.
Do not modify this attribute unless directed to do so by IBM Software Support.
maximumCommandRetryCount
The maximumCommandRetryCount attribute specifies the number of times that
the agent reissues commands after failing to receive a response from a broker
before giving up.
This value must be greater than 0; the default value is 4.
Do not modify this attribute unless you are directed to do so by IBM Software
Support.
maximumAgentCollectionThreads
The maximumAgentCollectionThreads attribute specifies the number of agent
collection threads that are used by the agent for monitoring brokers. You can
modify this value to increase or decrease the number of brokers that the agent can
monitor.
The default value is 42 threads, which is enough to monitor 10 brokers. This value
must be greater than 0.
On AIX systems, do not attempt to monitor more than 10 brokers with a single
agent. If you need to monitor more than 10 brokers, split them among several
agents. See “Monitoring a large number of brokers” on page 19 for further details.
To use a single agent to monitor more than 10 brokers on operating systems other
than AIX, increase this value by 4 for each additional broker monitored.

Do not modify this attribute unless absolutely necessary because monitoring a
large number of brokers with a single agent might adversely affect monitoring
performance. To monitor large number of brokers, create additional agents to
monitor some brokers. See “Agent performance considerations” on page 19 for
more details.
holdTimeForQuery
The holdTimeForQuery attribute specifies the length of time, in seconds, that the
agent should retain detailed accounting data. This data must be retained for
viewing detailed information in accounting workspaces. The greater this value, the
more data is available in the accounting workspaces.
This attribute’s default value is 180, which means that, regardless of other
parameters related to data retention, you will be able to view detailed information
about a selected data sample for at least 3 minutes after the data sample was
originally displayed. If you view the retained data in a workspace, then every time
you refresh the workspace the length of time for which the data is retained is
extended by the holdTimeForQuery value.
This parameter must have a value greater than 0. If you do not want the agent to
retain data, specify a value of 1 (1 second).
For example, the Snapshot Message Flow Accounting workspace displays a list of
monitored message flows and their statistics. By default, for the next 3 minutes
you can select a row in the table and link to a more detailed view of the displayed
data (either Snapshot Thread Accounting or Snapshot Node Accounting). Each
time that you view a data pertaining to a given message flow, you extend the time
that you can view the sample by 3 minutes. If the sample is not retained for some
other reason and if you do not access refresh the data for 3 minutes, then the data
is deleted. If the data is deleted, then data from the most recent sample is
displayed instead.
defaultHistoricalAccountingType
The defaultHistoricalAccountingType attribute tells the agent which types of
accounting data (snapshot and archive) to log historically. The value of this
parameter has no effect unless historical data collection for any of the four
accounting attribute groups has been enabled within TEP (this is active by default).
This parameter can have the following values:
All All accounting data is logged historically.
Snapshot Only Snapshot accounting data is logged historically.
Archive Only Archive accounting data is logged historically. This is the
default setting.
None No accounting data is logged historically, even if historical data
collection is enabled in TEP.
defaultRetainRecentSnapshotSamples
The defaultRetainRecentSnapshotSamples attribute specifies the default number of
recent snapshot records that are stored by the agent for any given message flow.
The default value of this attribute is 15, which is equivalent to approximately 5
minutes of snapshot data. However, the agent always ensures that it retains
enough historical samples to log the data historically if historical data collection is
enabled.
defaultRetainRecentArchiveSamples
The defaultRetainRecentArchiveSamples attribute specifies the number of recent
archive records that are stored by the agent for any given message flow. The
greater this value, the more data will be available in the Archive Message Flow
Accounting workspace. The default archive interval for a broker is 60 minutes. The
default value of the defaultRetainRecentArchiveSamples attribute is 5, so 5 hours
of recent archive data can be viewed in the Archive Message Flow Accounting
workspace if the default archive interval has not been changed. The agent always
ensures that it retains enough historical samples to log the data historically if
historical data collection is enabled.
defaultRetainRecentPubSubSamples
The defaultRetainRecentPubSubSamples attribute specifies the minimum number
of recent publish-subscribe data records stored by the Agent. The higher this value,
the more data will be available in the Publish-Subscribe Statistics workspace. The
agent always ensures that it retains enough recent samples to log all data
historically if historical data collection is enabled, so more than the number of
records specified by this parameter might retained.
This attribute’s value must be greater than 0. The default value is 15.
defaultCollectNodeData
The defaultCollectNodeData attribute determines whether node definition detail
data collection and parsing are performed. Possible values are YES to enable this
data or NO to disable it. This attribute can be overridden for individual message
brokers using the “collectNodeData” on page 18 attribute.
If the defaultCollectNodeData attribute is set to NO then the “Message Processing

Node Information workspace” on page 84 and “Message Processing Node
Attributes workspace” on page 83 will not contain data, because this option must
be enabled for the data displayed in the workspaces to be collected. However, if
message brokers in your environment have very large message flows with a lot of
message processing node data, enabling this option might drastically degrade
system performance.
The default value is NO.
Note: This attribute is case-sensitive on z/OS and must be YES or NO. It is not
case-sensitive on distributed platforms.
MonitorBroker
The MonitorBroker tag encapsulates parameters that apply to a single monitored
broker. Specify one MonitorBroker tag for each broker.
On UNIX, Linux, and Windows: If no brokers are specified, all brokers running on
the same host system as the agents are monitored, as determined by self-discovery.
If any brokers are specified explicitly using this tag, then any other brokers that
you want to monitor must also be specified using MonitorBroker tags. All
associated attributes are optional except for the name attribute.
On z/OS: WebSphere Message Broker Monitoring does not currently support

self-discovery of brokers on z/OS systems. Each broker to be monitored must be
explicitly specified using MonitorBroker tags and attributes. All associated
attributes are optional except for the name and componentDirectory attributes.

name
The name attribute specifies the name of the broker monitored by the agent.
The name attribute is required for all MonitorBroker tags.
alias
The alias attribute provides an alternative name for a broker in addition to that
specified using the name attribute. If specified, the alias is displayed as the
broker’s managed system name (node name) in TEP. You can use this attribute if
you want to specify a more user-friendly name for your broker to simplify
managing you system. This is especially useful when the name attribute of a
Broker is exceptionally long or you have several Brokers with similar names and
you want to be able to distinguish them easily in TEP. The alternative name must
conform to the following rules:
v The maximum length is 22 characters.
v Only alphanumeric ASCII characters can be included on distributed systems, or
EBCDIC characters on z/OS.
For example, if you have a broker named BROKER1 on your machine, you can
specify aliasl as follows:
<MonitorBroker name=”BROKER1” alias=”BK1”> </MonitorBroker>
The alias attribute is optional unless the broker name contains non-ASCII
characters (or non-EBCDIC characters on z/OS), in which case it must be specified.
statisticInterval
The statisticInterval attribute overrides the global defaultStatisticInterval attribute
and determines the minimum interval at which broker statistics are sampled, in
seconds If this attribute is not specified, the defaultStatisticInterval value is used
instead. If this attribute is specified, the value must be greater than 0.
If you are collecting history data for one of the statistics attribute groups, the
configured historical data collection interval must be a multiple of the
statisticInterval value; otherwise, historical data collection might produce
unpredictable results. For example, if you configure historical data collection for
one of the statistics attribute groups to run every 5 minutes (300 seconds), then the
statisticInterval value must be one of the following: 60 (1 minute), 75 (1.25
minutes), 100 (1.67 minutes), 150 (2.5 minutes), or 300 (5 minutes). For accurate
results, the historical data collection interval must be the same value for all
statistics attribute groups for which historical data collection is enabled.
flowEventInterval
The flowEventInterval attribute overrides the global defaultFlowEventInterval
attribute and determines the interval at which message flow events are sampled, in
seconds. If this attribute is not specified, the defaultFlowEventInterval value is
used instead. If this attribute is specified, the value must be greater than 0.
retainBrokerEvents
The retainBrokerEvents attribute overrides the global defaultRetainBrokerEvents
attribute and determines how many broker events to retain per broker. Report
information is available only for retained broker events. When used with
situations, these events are never reset automatically and if historical situations are
active, you can view them historically. If this attribute is not specified, the
defaultRetainBrokerEvents value is used instead. If the attribute is specified, the
value must be greater than 0.
retainFlowEvents
The retainFlowEvents attribute overrides the global defaultRetainFlowEvents
attribute and determines how many message flow events to retain per broker.
Report information is available only for retained message flow events. When used
with situations, these events are never reset automatically and if historical
situations are active, you can view them historically. If this attribute is not
specified, the defaultRetainFlowEvents value is used instead. If this attribute is
specified, the value must be greater than 0.
retainRecentPubSubSamples
The retainRecentPubSubSamples attribute specifies the minimum number of recent
publish and subscribe data records stored by the agent. The higher this value, the
more data will be available in the Publish-Subscribe Statistics workspace. This
attribute overrides the global defaultRetainRecentPubSubSamples attribute.
By default, this parameter is not specified in the configuration file. The global
defaultRetainRecentPubSubSamples attribute is used instead.
componentDirectory
This attribute is required on z/OS systems and ignored if it is specified on other
platforms.
The componentDirectory attribute specifies the directory path created when the
monitored broker was customized. This is the same as the component directory
name, which is used when specifying the -c parameter on the mqsicreatebroker
command. The component directory is described in the IBM broker product z/OS
documentation.
takeActionAuthUsers
The takeActionAuthUsers attribute specifies which Tivoli Enterprise Portal users
are authorized to issue the Take Action commands to a particular agent running on
a particular broker. You can specify multiple values for this attribute to authorize
multiple users. Include the asterisk (*) and question mark (?) characters in the
values to authorize a group of users. Only Tivoli Enterprise Portal users who have
an ID that matches the values of this attribute are authorized to issue Take Action
commands handled by the WebSphere Message Broker Monitoring agent. Tivoli
Enterprise Portal user IDs are defined in the TEMS and do not necessarily exist on
the node on which the agent is running. This attribute’s values apply only to
commands that are not related to a particular broker, or that are related to a broker
that does not have a specific list of users specified using the takeActionAuthUsers
parameter. This attribute overrides the global defaultTakeActionAuthUsers
attribute.
If this attribute is not specified, the defaultTakeActionAuthUsers value is used

instead.
historicalAccountingType
The historicalAccountingType attribute tells the agent which of the two types of
accounting data, snapshort and archive, to log historically. The value of this
parameter has no effect unless historical data collection for any of the four
accounting attribute groups has been activated in TEP (this is active by default).
This attribute overrides the global defaultHistoricalAccountingType attribute. For
more information see “defaultHistoricalAccountingType” on page 14.

retainRecentSnapshotSamples
The retainRecentSnapshotSamples attribute specifies the number of recent snapshot
records to keep for any given message flow. It overrides the global
defaultRetainRecentSnapshotSamples attribute. By default, this attribute is not
specified in the configuration file; the value of
defaultRetainRecentSnapshotSamples is used instead.
retainRecentArchiveSamples
The retainRecentArchiveSamples attribute determines the number of recent archive
records to keep for any given message flow. The greater this value, the more data
will be available in the Archive Message Flow Accounting workspace. The default
archive interval for a broker is 60 minutes. The default value of the
defaultRetainRecentArchiveSamples attribute is 5, so 5 hours of recent archive data
can be viewed in the Archive Message Flow Accounting workspace if the default
archive interval has not been changed. It overrides the global
defaultRetainRecentArchiveSamples attribute. By default this attribute is not
specified in the configuration file, and the value of
defaultRetainRecentArchiveSamples is used instead.
collectNodeData
The collectNodeData attribute determines whether node definition data collection
and parsing are performed. Possible values are YES to enable these options or NO
to disable them. If this attribute is not specified for a message broker, the default
value specified by the global “defaultCollectNodeData” on page 15 attribute is
used instead.
If the collectNodeData attribute is set to NO then the “Message Processing Node

Information workspace” on page 84 and “Message Processing Node Attributes
workspace” on page 83 will not contain data for this message broker, because this
option must be enabled for the data displayed in the workspaces to be collected.
However, if message brokers in your environment have very large message flows
with a lot of message processing node data, enabling this option might drastically
degrade system performance.
Note: This attribute is case-sensitive on z/OS and must be YES or NO. It is not
case-sensitive on distributed platforms.
ConnectQueueManager
The ConnectQueueManager tag encapsulates parameters that affect queue
managers. You can specify multiple ConnectQueueManager tags for different
queue managers. This tag is optional, but if you specify it, the name attribute is
required. If this tag is not specified, agent-level defaults are used for the remaining
attributes, and the agent automatically connects to the monitored broker’s
associated queue manager. However, if the default reply and model queue names
are not sufficient for a broker queue manager, then you should specify all
attributes of this tag:
name
The name attribute specifies the name of the queue manager that the agent
connects to. This attribute is required.
replyQueueName
The replyQueueName attribute specifies the name of the queue that is used by the
agent to receive publications and reply messages from the broker using this queue
manager. If the named queue does not exist, a temporary dynamic queue is created
automatically. If the specified queue name is less than 33 characters long, the
queue manager automatically modifies the name to ensure that it is unique.
If this attribute is not specified, the defaultReplyQueueName value is used instead.
replyQueueModel
The replyQueueModel attribute specifies the name of the queue that is used as a
model for creating the agent reply queue on this queue manager. The agent will
create a queue with the name specified by the replyQueueName attribute for the
queue manager using the properties of the queue specified by replyQueueModel as
a model. Thus, by changing the properties of the queue named by this attribute,
you can modify the properties of the agent reply queue used by the queue
manager.
If this attribute is not specified, the defaultReplyQueueModel is used instead.
Agent performance considerations

This section explains how you can split monitoring among several agents when the
performance of an agent is adversely affected by simultaneously monitoring a
large number of brokers.
Monitoring a large number of brokers

To minimize performance overhead, run only one WebSphere Message Broker
Monitoring agent on each host system. However, if the performance of the agent
becomes adversely affected by monitoring a large number of brokers
simultaneously, you can split monitoring between several agents.
For most distributed systems, one agent per host system should suffice, because
the agent is designed to monitor all brokers on such a system, or to monitor a
subset of brokers, as specified in the agent parameter file. For systems with a large
number of brokers, such as z/OS systems, you might need to adjust the agent
parameter that limits the number of brokers that are monitored (see
“maximumAgentCollectionThreads” on page 13) and verify that the large number
of brokers is not reducing performance. If performance is affected, you can split
monitoring between several agents.
If CPU usage is very high or response times for displaying Tivoli Enterprise Portal
workspace reports or situation monitoring actions are unacceptably long,
performance might be adversely affected by monitoring too many brokers. You
might need to experiment to determine the best number of agents for your
enterprise.
AIX systems:: Because of shared memory limitations, do not attempt to monitor

more than 10 brokers with a single agent on an AIX host.
Splitting the brokers among several agents on z/OS

You can edit the XML parameter member for any runtime agent that you have
configured with the configuration tool, so that you can add additional brokers that
you want to monitor. (The configuration tool prompts for only one broker). If you
intend to run more than one agent on a host, you must specify the agentID
parameter.
See “Setting Agent Parameters” on page 9 and “agentId” on page 11.

Dividing broker monitoring between different agents on UNIX
and Linux
Perform the following steps to configure each agent that you want to monitor a set
of brokers. For each agent, you must specify one broker to be the lead broker, used
to send commands to the other brokers when the itmcmd agent start and stop
commands are issued.
1. Start the agent, using the itmcmd agent start command with the -o and -p
options.
v The -o option specifies the monitoring agent ID (maximum of 4 characters).
v The -p option specifies the broker name. This parameter is optional
Example:
itmcmd agent -o AGT1 -p WBIBRK1 start qi
The file [Hostname]_qi_[brokername]_##_[agentID].xml is created automatically.
2. Edit the XML file to specify additional brokers.
In this example (for the file unixhost01_qi_ WBIBRK1_##_ AGT1.xml), brokers
WBIBRK2 and WBIBRK3 are added:
<KqiAgent version="601"
agentId="AGT1"
defaultRetainBrokerEvents="10"
defaultRetainFlowEvents="10"
retainProductEvents="10"
discoveryInterval="300"
defaultStatisticInterval="60"
defaultFlowEventInterval="15"
defaultHistoricalAccountingType="Archive"
defaultReplyQueueName="KQI.AGENT.REPLY.QUEUE"
defaultReplyQueueModel="SYSTEM.BROKER.MODEL.QUEUE"
defaultTakeActionAuthUsers="*"
<MonitorBroker name="WBIBRK1">
</MonitorBroker>
</MonitorBroker>
</MonitorBroker>
</KqiAgent>
3. Stop and restart the agent, using the itmcmd agent stop and itmcmd agent
start commands with the -o and -p options.
Example:
itmcmd agent -o AGT1 -p WBIBRK1 stop qi
itmcmd agent -o AGT1 -p WBIBRK1 start qi
Dividing broker monitoring between different agents on

Windows
To create a new instance of the monitoring agent:
1. Click Start >Programs>IBM Tivoli Monitoring > Manage Tivoli Monitoring
Services.
2. Right-click the installed agent, and select Create Instance.
You are prompted to update the parameter file.
3. Use the MonitorBroker keyword to specify which brokers to monitor. Specify
the agentID parameter value directly in the parameter file to run more than
one instance on a single Windows host.
See “agentId” on page 11 and “MonitorBroker” on page 15 for more
information.

Chapter 3. Customizing the CandleMonitor node
The CandleMonitor node is an optional component that collects message-flow
performance statistics for a broker and provides a mechanism for generating
user-defined events within a message flow.
This chapter provides instructions for positioning the CandleMonitor node to

monitor message-flow statistics and events, turning monitoring off and on, and
customizing the CandleMonitor node.
Note: Before you can follow the instructions in this chapter, you must have
installed the CandleMonitor node during the product installation and setup.
See the IBM Tivoli OMEGAMON XE for Messaging: Installation Guide for
further information.
The CandleMonitor node

The CandleMonitor node is an optional component of WebSphere Message Broker
Monitoring. It collects message flow performance statistics for a broker and
provides a mechanism for generating user-defined events within a message flow.
These events can be used by situations to detect abnormalities in the message flow.
For example, situations based on statistics that are generated by a CandleMonitor
node can be used to create a situation that automatically stops a message flow that
has messages flowing along an abnormal path
The CandleMonitor node is a simple pass-through node with one input terminal
and one output terminal, which is placed in a message flow to collect statistics (see
Figure 4). Messages passing through the CandleMonitor node are propagated
between its in and out terminals without change. The CandleMonitor node is
implemented in the kqipnode.lil file.
Figure 4. Example of a monitored flow
You can use the CandleMonitor node to perform the following actions:
v View message flow reports at broker, execution group, message flow and node
levels.
v Detect high input and output rates in message flows.

v Detect high average time spent in message flows.
v Detect high queue times for input to message flows.
v Determine which part of a message flow is taking more time.
v View statistics from the last sampling interval and average values taken over a
particular period of time.
v Be alerted to non-normal or low-use paths.
v Detect events and trigger automatic responses.
By default, statistics are sampled once per minute and events are sampled once
every 15 seconds.
Note: With broker versions V5 and later, accounting statistics can be available in
the Tivoli Enterprise Portal without using a CandleMonitor node. Some of
the accounting statistics are similar to those provided by the CandleMonitor
node. However, the CandleMonitor node can be used to monitor subflows
and define message flow events. Message flows without a CandleMonitor
node are not represented in the Statistics workspaces.
Before you can use the CandleMonitor node to monitor message flows, perform
the following tasks:
1. Install the CandleMonitor node in the broker environment. See the following
documents for information about installing the CandleMonitor node:
v IBM Tivoli OMEGAMON XE for Messaging: Installation Guide, GC32-1829
v IBM Tivoli OMEGAMON XE for Messaging on z/OS: Configuration Guide,
SC32-1830
2. Make the CandleMonitor node available in the Message Brokers Toolkit (V5,
V5.1 or V6), as described in“Making the CandleMonitor node available to
message flows.”
Making the CandleMonitor node available to message flows

Before you can insert the CandleMonitor node into message flows, you must make
the node available to the Message Brokers Toolkit (V5, V5.1 or V6).
The CandleMonitor node is stored in a file that created when you install
WebSphere Message Broker Monitoring. Several versions of this file are
downloaded with the product during installation of the monitoring agent on
Windows. The different versions are as follows:
v If you are using IBM WebSphere Business Integration Message Brokers Toolkit
V5.0, use the CandleMonitor node file kqicm500.exe. By default, this file is
stored in the following location:
C:\IBM\ITM\TMAITM6
v If you are using IBM WebSphere Business Integration Message Brokers Toolkit
V5.1, use the CandleMonitor node file kqicm510.exe. By default, this file is
stored in the following location:
C:\IBM\ITM\TMAITM6
v If you are using IBM WebSphere Message Brokers Toolkit V6.0:
– On the Windows operating system, use the CandleMonitor node file
kqicm600.exe. By default, this file is stored in the following location:
C:\IBM\ITM\TMAITM6
– On the Linux operating system, use the CandleMonitor node file
kqicm600.tar. By default, this file is stored in the following location:
/opt/IBM/ITM/arch/qi/bin
where arch specifies the architecture code of the operating system of this
computer. See Appendix D, “Architecture codes,” on page 125 for a list of
architecture codes.
Deleting the CandleMonitor node

This section describes how to delete the CandleMonitor node from different
versions of IBM broker products.
Message Brokers Toolkit V5.0

To delete the CandleMonitor node:
1. Shut down the toolkit if it is active.
2. Delete any subdirectory with a name that starts with com.candle.monitor_
from directory C:\Program Files\IBM\WebSphere Business Integration Message
Brokers\eclipse\plugins (or an alternative location if WebSphere Message Broker
Monitoring was not installed to the default location).

2. Delete any subdirectory with a name starts with com.candle.monitor_ from
directory C:\Program Files\IBM\WebSphere Business Integration Message
Brokers\evtoolkit\eclipse\plugins (or an alternative location if WebSphere
Message Broker Monitoring was not installed to the default location).
Message Brokers Toolkit V6

2. Do one of the following:
v If you are using the Windows operating system, delete any subdirectory that
has a name starting with com.candle.monitor from directory C:\Program
Files\IBM\MessageBrokersToolkit\6.0\evtoolkit\eclipse\plugins (or an alternative
location if WebSphere Message Broker Monitoring was not installed in the
default location).
v If you are using the Linux operating system, delete any subdirectory with a
name starting with com.candle.monitor from directory /opt/ibm/
MessageBrokersToolkit/6.0/evtoolkit/eclipse/plugins (or an alternative location if
WebSphere Message Broker Monitoring was not installed in the default
location).

This following procedure describes how to make the CandleMonitor node available
in Message Brokers Toolkit V5.0. If you have performed this step while using IBM
Tivoli OMEGAMON XE for Messaging V6.0, then you can skip it because there is
no change to the CandleMonitor node from OMEGAMON XE for Messaging V6.0
to V6.0.1.
Perform the following steps to make the CandleMonitor node available in the
Message Brokers Toolkit V5.0:
1. Exit the Message Brokers Toolkit if it is active.
Chapter 3. Customizing the CandleMonitor node 25

2. Run the program kqicm500.exe to install the CandleMonitor node Eclipse
plugin. If WebSphere Message Broker Monitoring was installed in the default
directory, the DOS command is as follows:
C:\IBM\ITM\TMAITM6>kqicm500.exe -d "C:\Program Files\IBM\
WebSphere Business Integration Message Brokers\eclipse\plugins"
The following two subdirectories are created:

v com.candle.monitor_6.0.0 (contains all the necessary plugin support files).
v com.candle.monitor.nl1_6.0.0 (contains all the native language support files).
Note: The version number in the subdirectory name, such as 6.0.0, indicates
the last OMEGAMON XE for Messaging release where some change
has been made to the plugin support files. The subdirectory in IBM
Tivoli OMEGAMON XE for Messaging V6.0.1 still has the characters
6.0.0 in it because no change is made to the plugin support files from
IBM Tivoli OMEGAMON XE for Messaging V6.0 to V6.0.1.
3. Restart the Message Brokers Toolkit.
You should see the CandleMonitor node in the message flow editor palette
under the category IBM in the Broker Application Development Perspective.

to V6.0.1.
Perform the following steps to make the CandleMonitor node available in Message
Brokers Toolkit V5.1:
1. Exit the Message Brokers Toolkit if it is open.
directory, the DOS command is as follows:
C:\IBM\ITM\TMAITM6>kqicm510.exe -d "C:\Program Files\IBM\
WebSphere Business Integration Message Brokers\
evtoolkit\eclipse\plugins"

3. Restart the Message Brokers Toolkit.
to V6.0.1.
Perform the following steps to make the CandleMonitor node available in Message
Brokers Toolkit V6.0:
1. Exit the Message Brokers Toolkit if it is open.
directory, the commands are as follows:
v On Windows operating systems:
C:\IBM\ITM\TMAITM6>kqicm600.exe -d
"C:\Program Files\IBM\MessageBrokersToolkit\
6.0\evtoolkit\eclipse\plugins"
v On Linux operating systems:
cp /opt/IBM/ITM/li6243/qi/bin/kqicm600.tar
/opt/ibm/MessageBrokersToolkit/6.0/evtoolkit/eclipse/plugins
cd /opt/ibm/MessageBrokersToolkit/6.0/evtoolkit/eclipse/plugins
tar -xf kqicm600.tar
3. Restart the Message Brokers Toolkit with the -clean option
Note: Whenever a new user-defined extension plug-in is added in the

evtoolkit\eclipse\plugins directory, or when the plugin.xml file is
changed, you must restart the Toolkit using the -clean option. To do this,
specify -clean when you start the Toolkit from command line.
CandleMonitor node attributes

You can set the properties of the CandleMonitor node when you place it in a
message flow. The attribute values that you set determine how the node operates.
type
The type attribute specifies the type of statistics that are gathered. Possible values
are:
v input—Identifies the node as a main message flow input node which records
entry of messages into the message flow. For example, specify input when
placing the CandleMonitor node immediately after the MQInput node.

v output—Identifies the node as a main message flow output node, which records
that exit of messages from the message flow. For example, specify output when
placing the CandleMonitor immediately in front of node just before any
MQOutput, MQReply, or Publication node.
v subFlowInput—Identifies the node as a subflow input node
v subFlowOutput—Identifies the node as a subflow output node
v other—Identifies the node as being used for other purposes, such as ad-hoc
statistics or message flow event generation. For example, specify other when
placing the CandleMonitor node wherever necessary to debug your message
flows.
collectQueueTime
The collectQueueTime attribute specifies whether the node should collect queue
timings. Possible values are:
v no—Queue times are not collected for these messages.
v yes—Queue times are collected for these messages.
Queue times are calculated using the put date and time of the messages in the
queue. If the input queue to a message flow has messages with put date and times
that do not reflect accurately when the message was put into the input queue, then
the collectQueueTime attribute should be set to no so that queue times are not
collected for these messages. (See also “Monitoring the input or output of a
message flow” on page 30.)
eventMessage
The eventMessage attribute is used to produce user-defined message flow events
that can trigger Message Flow Events situations and reports. An event is produced
when the message enters the node if this attribute’s value is set to anything other
than cleared (“”).
When a node is placed for the purpose of generating events, the type attribute
should be other and the eventMessage attribute should be set to the message text
that appears in TEP workspaces and can be detected in monitoring situations.
By default this value is cleared (“”) (no events are produced).
subFlowName
The subFlowName attribute specifies an identifying name for the subflow. This
attribute is required for nodes of type subFlowInput and subFlowOutput; these
nodes do not produce subflow statistics correctly without it.
You can specify subFlowName attribute for other types of nodes. The following
table summarizes the effect of providing a subFlowName attribute for each node
type.
Table 2. The effect of providing a subFlowName attribute for each node type
subFlowName
Type attribute attribute Effect
requirement
input Optional The node is a combination node; it marks not only the beginning of a
message flow, but also the beginning of a subflow in the message flow.
output Optional The node is a combination node; it marks not only the end of a message
flow, but also the end of a subflow within the message flow.
Table 2. The effect of providing a subFlowName attribute for each node type (continued)
subFlowName
Type attribute attribute Effect
requirement
other Optional The node is a part of the subflow. This combination of settings has very
little effect. However, it causes the CandleMonitor node to be displayed in
the list of CandleMonitor nodes for the named subflow. Statistics for this
node appear in the CandleMonitor Node Statistics workspace.
subFlowInput Required The subFlowInput type node marks the beginning of a monitored subflow
and requires a name so that statistical data is correlated with the subflow.
There can be multiple inputs to a subflow; for multiple inputs, use the
same subFlowName for each node.
subFlowOutput Required The subFlowOutput type node marks the end of a monitored subflow and
requires a name so that statistical data is correlated with the subflow.
There can be multiple outputs for a subflow; for multiple outputs, use the
same subFlowName for each node.
See “Monitoring subflows” on page 31 for more information about placing

CandleMonitor nodes and required attribute values.
activateNode
The activateNode attribute controls the activation of instances of a CandleMonitor
node. Possible values are:
v yes—The CandleMonitor node is active. This setting is appropriate for a test
environment.
v no—The CandleMonitor node is not active.
v eventOnly—The CandleMonitor node is activated only if the eventMessage
attribute is specified. The node does not produce statistics; it produces only
message flow events. This setting is useful when you are interested in message
flow events, but you do not want to gather statistics.
v inputOutputOnly—The CandleMonitor node is activated if the node’s type is
input or output. This setting produces statistics (and events, if eventMessage is
assigned).
v inputOutputAndEventOnly—The CandleMonitor node is activated if the node’s
type is input or output, or if the eventMessage attribute is set. Statistics are
produced; events are produced also if the eventMessage is assigned. This setting
is useful in a production environment when you want message flow statistics
and event messages, but you do not want any of the additional details provided
by other node types.
If you are monitoring WebSphere Business Integration broker version 5.0 later, you
can configure the activateNode attribute. Set this attribute when you are
configuring bar files, so the attribute can have a different setting for different bar
files in test and production environments. In addition, with version 5.0 you can
promote the attribute setting so that this attribute has the same setting for each
CandleMonitor node in a message flow.
The set of possible values for the attribute supports specification of some general
rules for when the node should be active; for example, it could be active for nodes
of type input and output only. In general, when you are customizing a
CandleMonitor node in a message flow, use the default value yes to facilitate node
usage during testing. Then, when you are deploying the node to a production

broker, configure the bar file setting for the activateNode attribute to the level that
you want and promote the attribute to automatically change the settings of all
nodes in the flow to that activation level.
You can specify a runtime override setting for the activateNode attribute, which
allows different activation levels for different brokers (see “KQIActivateNode” on
page 36).
Positioning the CandleMonitor node

The primary use of the CandleMonitor node is to produce the statistics that are
displayed in the high-level statistics workspaces in IBM Tivoli Enterprise Portal
(the Broker Statistics, Execution Group Statistics, Message Flow Statistics, and
subflow Statistics workspaces). To ensure that the correct statistics are gathered, the
node must be correctly placed within message flows.
You must provide unique label names to CandleMonitor nodes in a message flow.
The names should be unique with respect to any other names in the entire
message flow, including its subflows. If the CandleMonitor node label names are
not unique, data for different nodes is combined in illogical ways. You should not
use the default names that are assigned to your CandleMonitor nodes. If you are
migrating message flows with subflows from V2.1 to V5.0, you might have to
change CandleMonitor node label names if you did not name them uniquely
before. The same method applies to migration from V2.1 or V5 to V6.
Monitoring the input or output of a message flow

When you are designing a message flow that is to be monitored by a broker, you
should place a CandleMonitor node immediately following the MQInput node. The
CandleMonitor node can then gather the information required for input rate
calculations. The type attribute of a CandleMonitor node placed in this position
should be set to input.
If you want to place only a single CandleMonitor node in a message flow, the
input position is the best choice, because most statistics are generated from this
position.
However, another important location for placing the CandleMonitor node is

immediately in front of any MQOutput, MQReply, or Publication node, to permit
output rate calculations. If you place the CandleMonitor node in front of these
nodes, set the type attribute of the CandleMonitor node to output.
When queue time statistics are determined, queue times are calculated using the
put date and time of the message in the queue. If the input queue to a message
flow contains messages that have times that do not accurately reflect when the
message was put into the input queue, and you are using a CandleMonitor node
with a type attribute of input, set the collectQueueTime attribute to no so that
queue times are not calculated for these messages.
Put date and times are not accurate when origin context is preserved for a message
during the put operation by the application performing the operation. Put date and
time inaccuracies commonly occur when an application is a message mover that
transfers messages from one queue to another, or when any application passes or
sets origin context for a message. If the input queue to Message Flow B is the
output queue of Message Flow A, the broker passes the origin context so that the
put date and time for the message in Message Flow B is not an accurate calculation
of queue time. The collectQueueTime attribute for a CandleMonitor node placed
in Message Flow B should be set to no.
Monitoring subflows
A subflow is a section of a message flow that includes one or more message
processing nodes. In general terms, a subflow can be any section of a message flow
that can be separately identified. You can consider the message flow as being like a
main routine and a subflow as being a subroutine. You can explicitly delineate the
subroutine in the Message Brokers Toolkit by making a separate message flow,
which is then embedded in the main flow (referred to here as Type I). Or, the
message flow can have sections of nodes that you want to monitor as subflows,
even though they are not explicitly delineated into a separate flow (referred to in
this example as Type II).
When a message flow is deployed to a broker, the broker regards the entire
message flow as a single entity. There is no obvious delineation in the broker for
dividing the flow into separate subflows. The name assigned to a Type I subflow is
not known to the broker (this entity only appears in the Message Brokers Toolkit
and configuration manager). Any given message processing node is not aware of
the other message processing nodes around it. Therefore, for the CandleMonitor
node to be useful in monitoring both types of subflows, you must provide the
required information by customizing the node.
To gather correct subflow statistics for either type of subflow, the subFlowOutput
CandleMonitor node is required in the subflow; it is not optional, as is the case
with the output node for a main message flow.
Monitoring a Type I subflow

To monitor a Type I subflow, place a CandleMonitor node immediately following
the Input Terminal in the flow and place another CandleMonitor node immediately
in front of the Output Terminal or other output of the flow (see Figure 5). Assign
all nodes the same subFlowName attribute value. The type of the node at the input
location is subFlowInput and the type of node at the output location is
subFlowOutput (or output if the output is a node such as MQOutput and
represents the end of the message flow for a message going down a particular
path).

Main Message Flow
SubFlow1
subFlowName=subFlow1 subFlowName=subFlow1
Figure 5. Type I subflow
Monitoring a Type II subflow

To monitor a Type II subflow, place a CandleMonitor node at any designated
starting place in the message flow; set the type to subFlowInput, and specify the
subFlowName attribute. Place another CandleMonitor node at a corresponding
end point in the message flow; set the type to subFlowOutput and specify the
same subFlowName attribute (see Figure 6 on page 32). If the section of message
flow that is to be monitored has multiple input connectors or multiple output
connectors, you must add multiple CandleMonitor nodes in the same way with the
same subFlowName.
subFlowName=subFlow1 subFlowName=subFlow1
Figure 6. Type II subflow
Embedded and nested subflows
subflows embedded in subflows, or nested subflows, are supported. However, the
subFlowName attribute for any nested subflows must be different for different
subflows. You must be aware of the names assigned to subflow monitoring nodes
and not reuse them.
subflow names
For Type I message flows, you can set the subFlowName to the name that was
specified in the Message Brokers Toolkit for the message flow that represents the
subflow. However, for Type II message flows, you need to use a different name
that uniquely describes what is being monitored.
CandleMonitor Node Statistics (the lowest level, most detailed report) combines
data for all instances of the same node that are part of a subflow that has been
embedded multiple times in the same message flow.
You can assign subFlowName attribute to an input or output CandleMonitor node.

When you use input and output node types in combination you do not need to
insert two CandleMonitor nodes in a flow at the same position when a subflow
comes either at a beginning or end of a message flow. The combination output
node will probably be used more, because a Type I subflow might have an output
that is the destination for a message going through the whole message flow as well
as through the subflow. (For a description of the effects of assigning a
subFlowName attribute to a node type other than subFlowInput or
SubFlowOutput, see “subFlowName” on page 28.)
Monitoring other aspects of a message flow

You can place the CandleMonitor node anywhere in a message flow and gather
statistics on that particular portion of the message flow.
When you place a CandleMonitor node in a place other than the extreme
beginning or end of a flow, you should set the type attribute of the CandleMonitor
node to other. The results can be viewed in the low-level statistics and
CandleMonitor Node Statistics workspaces in IBM Tivoli Enterprise Portal.
Producing event messages

A secondary use of the CandleMonitor node is to produce user-defined message
flow events that can be detected by Message Flow Event situations and viewed in
the Message Flow Events workspace.
When positioning the CandleMonitor node for this purpose, set the type attribute
to other. Set the eventMessage attribute to display the message text that you want
to appear in the workspace when the message enters the CandleMonitor node.
WebSphere Message Broker Monitoring includes other information about events to

help identify which portion of the message flow is affected, as well as to isolate
which message was being processed at the time the event occurred.
The placement of the CandleMonitor node for such events is entirely at your
discretion. However, the node should not be placed in portions of the message
flow that are used regularly during normal processing, because this will produce a
very large number of events. For example, setting the eventMessage attribute for
any input or output type node would produce an unnecessarily large number of
events. Instead, you should place the CandleMonitor node in paths of a message
flow that represent processing failures or other irregular conditions that warrant an

alert notification. In this capacity, the CandleMonitor node serves only as an alert
mechanism; it cannot perform error recovery because it is a pass-through node
only.
Best practice guidelines

v For production flow statistics, place the CandleMonitor node immediately
following MQInput (or other input) nodes and specify the type input.
v For output rates and counts, place the CandleMonitor node immediately in front
of MQOutput, MQReply, and Publication nodes and specify the type output.
v Any other placement in the flow should not use types input or output because
inaccurate data will be generated.
v Generally, an eventMessage attribute should be specified only for nodes that
have the types subFlowInput, subFlowOutput, and other. This attribute should
not be set for the normal processing part of a flow or for a node with a type
attribute of input or output (unless the node is not used frequently and there is
a specific reason for doing so) because it might have an adverse affect on system
performance.
v For message flow development, nodes that have the type other can be used to
determine areas of a flow that has poor performance.
v If you are going to shut down the broker or agent, they should complete the
entire shutdown process whenever possible.
Customizing a CandleMonitor node

Some aspects of a CandleMonitor node’s behaviors are controlled by configuration
variables. You can modify the values of these variables to suit your requirements.
After changing the value of any of these variables, you must restart the broker
before the changes take effect.
On Windows operating systems, configuration variables are available in the

registry that is created when you configure the monitoring agent. On UNIX and
Linux operating systems, the configuration variables are stored in the file
kqipnode.cfg in the directory <install_dir>/<arch_code>/qi/bin, where
<install_dir> is IBM Tivoli Monitoring installation directory and <arch_code> is
architecture code for the platform on which the agent is running. For a list of
architecture codes, see Appendix D, “Architecture codes,” on page 125. On z/OS,
the configuration variables are stored in the file kqipnode.cfg in an HFS directory
<install_dir>/kqi/lil.
Note: All of the kqipnode variable names and values are case sensitive. You must
enter the variable names exactly as shown. For example, if you are
specifying the no override value for KQIActivateNode, you must specify
NoOverride.
Changing variables on Windows

To change the values of variables on Windows, perform the following steps:
1. Stop the WebSphere Message Broker Monitoring agent that has variables you
want to edit.
2. From the Start menu, click Programs>IBM Tivoli Monitoring>Manage Tivoli
Monitoring Services .
3. Right-click the WebSphere Message Broker Monitoring Agent and click
Advanced > Edit Variables .
4. If the variable is in the list, do the following:
a. Select the variable and click Edit.
b. Enter the new value in the Value field and click OK.
See “Configuration variables” on page 35 for descriptions of the variables and
their valid values.
5. If the variable is not in the list, do the following:
a. Click Add.
b. Select the variable that you want to add from the drop-down list.
c. Enter the new value in the Value field and click OK.
6. Click OK.
7. You are prompted whether you want to update the file kqi.xml before you
configure WebSphere Message Broker Monitoring Agent. Click No.
Changing variables on UNIX or Linux

To change variables on UNIX or Linux, edit the kqipnode.cfg file in the
<install_dir>/<arch_code>/qi/bin directory, where <install_dir> is IBM Tivoli
Monitoring installation directory and <arch_code> is architecture code for the
platform on which the agent is running. For a list of architecture codes, see
Appendix D, “Architecture codes,” on page 125.
The format of the configuration file is as follows:

variable value
variable value
Changing variables on z/OS

On z/OS, the configuration variables are stored in the kqipnode.cfg file in the
<install_dir>/kqi/lil directory. Edit this file to change the values of the variables. If
you do not want your changes to be overwritten by subsequent configuration with
the configuration tool (for example, when a PTF is installed), you must edit the
member kqipnode in your TKANPAR data set.
Configuration variables
The following sections provide a detailed description of each configuration
variable.
KQIMemorySize
KQIMemorySize specifies the size (in bytes) of a shared memory segment created
by the plug-in. The plug-in creates three of these shared memory segments for
holding different types of data. The default value is 32768 bytes. Do not modify
this variable unless instructed to do so by IBM Software Support.
KQITempDirectory
The KQITempDirectory variable is not applicable on Windows.
KQITempDirectory variable specifies the directory to be used for shared memory

and mutexes. The broker and the agent must have the authority to read, write and
create files in this directory. Its default value is /tmp.
The only safe time to delete files with file names containing kqi from the defined
directory is after you shut down all brokers and WebSphere Message Broker
monitoring agents on the system. The KQITempDirectory variable is used by all
brokers and WebSphere Message Broker monitoring agents on the system, so they
must all be stopped before you can delete any files that have kqi in the name.

Under normal circumstances, you do not need to delete the files because when all
the brokers and agents are stopped, they will not be present. However, in
exceptional circumstances where the files still exist after all the components have
stopped, you can delete the files manually . These files implement shared memory
and mutexes, and WebSphere Message Broker Monitoring will not behave
normally if you delete them while the processes that use the files are active.
By default, temporary files used by the CandleMonitor node and related to

mutexes and shared memory are stored in the /tmp directory. The user IDs used
by the broker and the Message Broker Monitoring agent must both have write
access to this directory. If the user IDs do not have this access, you can use the
KQITempDirectory parameter in the kqi.xml file to specify a different directory for
storing this information. You should also use this parameter to specify a different
location if there is the possibility that the /tmp directory will become full, as this
might impair performance, or when the /tmp directory is used by a large number
of applications, as this may result in files being accidentally overwritten by other
programs.
KQINodeTrace
KQINodeTrace determines whether or not kqipnode.lil tracing is turned on.
Possible values are Off and On. The default is Off. For tracing to actually occur,
the broker’s normal tracing must be turned on for one or more of the applicable
broker, execution group, message flow. You should set this value to On only when
instructed to do so by IBM Software Support.
KQIActivateNode
Use this parameter to override the CandleMonitor node activateNode attribute of
any broker on the system. If a value other than the default NoOverride is
specified, that value overrides the value set for the attribute for all CandleMonitor
nodes deployed on a broker.
The possible values are:

v NoOverride—The value of the activateNode attribute that is deployed for each
instance of the CandleMonitor node is honored; no override takes place. This is
the default setting.
v Yes—Every instance of the CandleMonitor node is active.
v No—All instances of the CandleMonitor node are inactive. No statistics or
message flow events are generated.
v EventOnly—An instance of the CandleMonitor node is active only if the
eventMessage attribute is assigned. No statistics are produced; only message
flow events are produced.
v InputOutputOnly—An instance of the CandleMonitor node is active only if the
type is input or output. Statistics are generated (and events, if the eventMessage
attribute is assigned).
v InputOutputAndEventOnly—Instances of the CandleMonitor node are active
only if they are of type input or output, or if the eventMessage attribute is
assigned. Statistics are produced, and message flow events are produced, if the
eventMessage attribute is assigned.
KQIActivateNodeForBROKERNAME
Use this parameter to override the CandleMonitor node activateNode attribute of
any one broker on the system . If this variable is specified, the kqipnode.lil plug-in
running in broker BROKERNAME uses this setting instead of the setting specified
in the KQIActivateNode attribute. This variable name does not exist by default;
you must add it to the file kqipnode.cfg (UNIX, Linux, or z/OS) or type it the
variable field instead of selecting it from the drop-down list (Windows).

Chapter 4. Usage scenarios
This chapter provides examples of monitoring situations that are common to many
IBM broker product environments, and shows how WebSphere Message Broker
Monitoring can be used in these circumstances.
Each scenario presents a case in which you need to monitor some aspect or
component of your IBM broker product environment, followed by a description of
how to set up WebSphere Message Broker Monitoring to gather important
information.
Monitoring application message flow performance

This scenario describes how you can use WebSphere Message Broker Monitoring in
a performance monitoring situation in which an application message flow is taking
excessively long to process messages.
Perform the following steps to enable WebSphere Message Broker Monitoring to

gather the appropriate statistics:
1. Place one CandleMonitor node immediately following the MQInput node so
that the entry of the messages into the message flow is recorded.
2. Set the type attribute of this CandleMonitor node to input.
3. Place another CandleMonitor node immediately in front of the MQOutput node
so that the exit of the messages from the message flow is recorded.
4. Set the type attribute of this CandleMonitor node to output.
5. Start the WebSphere Message Broker Monitoring agent.
After you have positioned the CandleMonitor nodes and WebSphere Message
Broker Monitoring is running, do the following:
1. Open the Message Flow Statistics workspace and examine the values of the
Current® Average Queue Time and Current Average Flow Time attributes. For a
detailed description of these attributes and their values, see the online help for
2. If you think that the times reported by the Current Average Queue Time
attribute are excessively long, consider increasing the Additional Instances
value for the monitored message flow. Additional Instances specifies the
number of additional instances of the message flow that the execution group
should run so that more messages can be processed concurrently.
3. If you think that the times reported by the Current Average Flow Time are
excessively long, then you need to debug the monitored message flow. To
perform this task, do the following:
a. Insert CandleMonitor nodes before each processing node in the message
flow. This can help you determine which node is causing the problem.
b. Set the type attribute of the new CandleMonitor nodes to other.
c. Restart the WebSphere Message Broker Monitoring agent.
d. Open the CandleMonitor subflow Statistics workspace, and examine the
flow times of any subflows in the message flow. For more information on
this workspace, see “Sub-Flow Statistics workspace” on page 99.

e. Compare statistics for the subflows to determine which section of the
message flow is causing problems.
Determining application delivery failure of messages

This scenario describes how you can use WebSphere Message Broker Monitoring to
determine the cause of the problem when messages that are destined for an
application are not being received by that application.
Perform the following steps to enable WebSphere Message Broker Monitoring to

gather the appropriate statistics:
that the entry of the messages into the message flow is recorded.
2. Set the type attribute of this CandleMonitor node to input.
3. Place another CandleMonitor node immediately in front of the MQOutput node
so that the exit of the messages from the message flow is recorded.
4. Set the type attribute of this CandleMonitor node to output.
After you have placed and set the CandleMonitor nodes, and WebSphere Message
1. Open the Message Flow Information workspace and examine the Status
attribute. The Status column for the monitored message flow should have the
value Started. If it does not, start the message flow manually.
2. Open the Message Flow Statistics workspace and compare the Current Message
Input Count and Current Message Output Count attributes. A discrepancy
between these values indicates that messages are being lost in the monitored
message flow. For a detailed description of these attributes and their values, see
the online help for WebSphere Message Broker Monitoring.
3. Open the Message Flow Events workspace and determine whether any
exceptions have been triggered by a node in the monitored message flow. For
information about the workspace, see “Message Flow Events workspace” on page
80.
Debugging a message flow

debug the operation of a message flow.
To determine which node in the message flow is causing a problem, perform the
following steps so that WebSphere Message Broker Monitoring can gather
appropriate statistics for you to analyze:
1. Place CandleMonitor nodes on each side of nodes or subflows that you think
are functioning incorrectly in the message flow.
2. Set the type attribute of a CandleMonitor node placed in front of a node or
subflow to subFlowInput.
3. Set the type attribute of a CandleMonitor node placed following a node or
subflow to subFlowOutput.
4. Set the subFlowName attribute of each pair of nodes to the same value, which
should be unique within the message flow.
1. Open the CandleMonitor subflow Statistics workspace, and examine the flow
times of all subflows in the message flow. For more information about this
workspace, see “Sub-Flow Statistics workspace” on page 99.
2. Compare statistics for different subflows to determine which section of the
message flow is problematic.
Determining when a message flow has failed

determine when a message flow has failed and to notify you of a failure in a
message flow.
To determine when a message flow has failed, perform the following steps so that
WebSphere Message Broker Monitoring can gather the appropriate statistics:
1. Place CandleMonitor nodes after failure terminals for processing nodes in the
message flow.
2. Set the type attribute of these CandleMonitor nodes to other.
3. Describe the failures in a meaningful way in the eventMessage attribute of the
CandleMonitor nodes.
4. Restart the WebSphere Message Broker Monitoring agent.
v Define situations for Message Flow Events so that an alert is raised each time a
message flows down a path that is failing. See Tivoli Enterprise Portal online
help or IBM Tivoli Monitoring User’s Guide for information about defining a
situation.
v Deploy the situations that you defined to the system on which the monitored
message flow is running.
v Look in the Message Flow Events workspace to see data about the message
being processed when the events that you defined occur.
Verifying the broker configuration

verify that the broker configuration matches your configuration as depicted in the
Message Brokers Toolkit.
After you have configured WebSphere Message Broker Monitoring, start the agent
so that the necessary statistics can be gathered, and then do the following:
1. Examine the various information workspaces, such as Execution Group
Information, Message Flow Information, Message Processing Node Information,
Neighbors, Subscriptions, Retained Publications, and ACL Entries. These
workspaces contain data from the broker perspective as opposed to the
Message Brokers Toolkit perspective.
2. Compare the data in the workspaces with what you expected to determine
whether the proper configuration was deployed to the broker.
Chapter 4. Usage scenarios 41

Collecting requested system trace data for a broker on a remote
system
collect system trace data requested by IBM Software Support for a broker that is
located on a remote system.
1. Right-click a WebSphere Message Broker Monitoring agent and click Take
Action > Select to open the Take Action window in Tivoli Enterprise Portal.
2. Select QI Change Trace Broker from the Name drop-down list and set the
destination to the appropriate broker. For more information about the QI
Change Trace Broker command, refer to “Take Action commands” on page 48.
3. Select the broker managed system for the broker that needs to be traced from
the Destination Systems list and click OK.
Stopping a message flow that has a full output queue

quickly stop a message flow that is failing because it has a full output queue. This
scenario is intended for users who do not always start the Configuration Manager
and Message Brokers Toolkit so that they can conserve system resources.
1. Right-click a WebSphere Message Broker Monitoring agent and click Take
Action > Select to open the Take Action window in Tivoli Enterprise Portal.
2. Select QI Stop Message Flow(s) from the Name drop-down list and set the
arguments to the appropriate broker, execution group, and message flow. For
more information about the QI Stop Message Flow command, see “Take Action
commands” on page 48.
3. Select the broker managed system for the broker with the failing message flow
from the Destination Systems list and click OK
Automatically starting a broker that is stopped

automatically restart a broker whenever it is stopped.
so that necessary statistics can be gathered, and then do the following:
1. Define a situation for the Broker Information workspace that checks whether
the Broker Status is stopped. For information about how to define a situation,
see IBM Tivoli Monitoring User’s Guide.
2. Set the action for the situation to use the QI Start Broker reflex
automation/Take Action command to restart the broker. For additional details
about the QI Start Broker command, see“Take Action commands” on page 48.
Note: There is a predefined situation for the Components workspace that you
can use for the same purpose, but that situation also starts the
Configuration Manager and User Name Server, if either one stops.
Planning broker capacity
help you plan the capacity for your brokers.
To determine the most recent message that was sent between two applications,
perform the following steps so that WebSphere Message Broker Monitoring can
gather the necessary statistics:
that the entry of the message into the message flow is recorded.
2. Set the type attribute of the CandleMonitor node to input.
3. Place one CandleMonitor node immediately in front of the MQOutput node so
that the exit of the message from the message flow is recorded.
4. Set the type attribute of the CandleMonitor node to output.
Broker Monitoring is running, perform the following steps:
1. Open statistics workspaces, such as Message Flow Statistics for individual
message flows, Execution Group Statistics for summarization over an entire
execution group, or Broker Statistics for statistics summarizing the operation of
an entire broker.
2. Examine the statistics workspaces and their historical workspaces (which you
can link to from the statistics workspaces).
3. If you find that for a particular message flow the Current Message Input Rate
is higher than expected, or that the Current Average Queue Time is
unacceptably long, add more instances to the flow in the Message Brokers
Toolkit.
4. If you find that for a particular execution group the Current Message Input
Rate is higher than expected, or that the Current Average Queue Time is
unacceptably long, add a new execution group and assign instances as
appropriate.
5. If you find that for a particular broker the Current Message Input Rate is
higher than expected, or that the Current Average Queue Time is unacceptably
long, consider adding a new broker with a configuration that will offload some
processing from the current broker.
Ensuring reasonable message flow response times

ensure that the response times of your message flows are reasonable.
To monitor message flow response times, perform the following steps so that
WebSphere Message Broker Monitoring can gather the necessary statistics:
that the entry of the message into the message flow is recorded.
2. Set the type attribute of the CandleMonitor node to input.
3. Place one CandleMonitor node immediately in front of the MQOutput node so
that the exit of the message from the message flow is recorded.
4. Set the type attribute of the CandleMonitor node to output.

After you have positioned the CandleMonitor nodes, and WebSphere Message
Broker Monitoring is running, perform the following steps:
1. Open the Message Flow Statistics workspace for individual message flows. For
a detailed description of these attributes and their values, see the online help
for WebSphere Message Broker Monitoring.
2. Examine the workspaces and their historical equivalents (you can link to the
historical information from the statistics workspaces).
3. If the Current Average Flow Time for a particular message flow is higher than
expected, debug the message flow as described in “Debugging a message flow”
on page 40. Compare the Average Flow Times for each section of the message
flow to help you identify where problems are occuring.
Preventing inadvertent use of trace active

prevent the trace active feature from being used inadvertently and adversely
affecting broker performance.
v Define a situation for the Broker Information, Execution Group Information, and
Message Flow Information workspaces that verifies that the Trace Level and
User Trace Level attribute values are not none. An alert is triggered whenever
tracing is active so that you can determine whether the tracing activity is valid.
See Tivoli Enterprise Portal online help or IBM Tivoli Monitoring User’s Guide for
information about defining a situation.
v Deploy the situation to the broker managed systems where you want to detect
active trace.
Starting and stopping message flows at periodic intervals

automatically start and stop message flows at certain times of the day.
so that you can gather the necessary statistics, and then do the following:
For individual message flows

1. Define a situation for the Message Flow Information workspace’s Status
attribute with additional matches for the Local Time attribute. This determines
when a message flow should be started or stopped. See Tivoli Enterprise Portal
online help or IBM Tivoli Monitoring User’s Guide for information about defining
a situation.
2. Set the action for the situation to use the QI Start Message Flow or QI Stop
Message Flow Take Action command to start or stop the message flow; specify
both the execution group name argument and the message flow name
argument.
For all message flows within an execution group

1. Define a situation for the Started Message Flows attribute with additional
matches for the Local Time attribute. These values specify when all message
flows in the execution group should be started or stopped. See Tivoli Enterprise
Portal online help or IBM Tivoli Monitoring User’s Guide for information about
defining a situation.
2. Set the action for the situation to use the QI Start Message Flow or QI Stop
Message Flow Take Action command to start or stop all message flow.
Specifying only the execution group name argument and do not specify a
message flow name argument. For additional detail about the QI Start Message
Flow(s) or QI Stop Message Flow(s) commands, refer to “Take Action
commands” on page 48.
Verifying subscriptions without accessing the Message Brokers Toolkit

verify your subscriptions when you do not have access to the Message Brokers
Toolkit.
so that the appropriate information can be gathered, and then do the following:
1. Open the Subscriptions workspace for each broker from which you expect the
application to be receiving publications.
2. If your subscription appears in a single broker, examine the report data to
determine whether you have specified the Local option for the subscription;
look in the Local Only column for the value Yes. This setting prevents the
subscription from being propagated to neighboring brokers.
Subscribing to a topic fails security

This scenario describes how you can use WebSphere Message Broker Monitoring
when your application attempts to subscribe to a topic and fails for security
reasons.
so that necessary statistics can be gathered, and then do the following:
v Open the ACL Entries workspace to determine whether the application’s user ID
matches a Principal that allows subscribe access to the topic or whether its user
ID is a member of a group that matches a principal that allows subscribe access
to the topic.

Chapter 5. Situations and Take Action commands
This chapter describes the predefined situations and Take Action commands that
are included with WebSphere Message Broker Monitoring.
Predefined situations
WebSphere Message Broker Monitoring provides a set of predefined situations that
are useful in different circumstances. Most predefined situations enable you to
monitor critical activity and serve as templates for creating customized situations
for your own use.
The predefined situations included with WebSphere Message Broker Monitoring

have names that begin with the letters QI.
Predefined situations are activated when they are deployed to the node that you
want to monitor. After they have been configured correctly, situation alerts trigger
event notification.
For information about creating or modifying situations, see the Tivoli Enterprise
Portal online help or IBM Tivoli Monitoring User’s Guide.
Note: If you choose to modify a predefined situation, make a copy and modify the
copy, preserving the original for later use.
Alerts
The following situations issue alerts based on critical status criteria. Except where
noted, these situations apply to broker-managed systems. Alerts are raised if one of
the following occur:
v The Broker Information.Broker Status value is not started.
(QI_Broker_Not_Started)
v The Broker Information.Queue Manager Status value is not connected.
(QI_Broker_QMgr_Not_Connected)
v Broker Events reports a Status Stop event type. (QI_Status_Stop_Event)
v Message Flow Events reports any event from a CandleMonitor node.
(QI_Message_Flow_Events)
v Product Events reports any event affecting the agent. This situation applies to
agent-managed systems. (QI_Product_Events)
v Broker Events reports a Publication Expiration event type.
(QI_Publication_Expiry_Event)
v Broker Events reports a Subscription Expirations event type.
(QI_Subscription_Expiry_event)
v The Message Flow Statistics.Average Flow Seconds value exceeds a threshold.
Note that the threshold value given in the situation is an example, and should
be modified to match expectations in your environment.
(QI_Average_Flow_Time High)
v The Components.Component Status value is not started. This situation has reflex
automation: If the situation becomes true, the correct command is issued to start
the component. This situation applies only to agent-managed systems.
(QI_Automation_Start_Component)

Take Action commands
You can use Take Action commands to automatically run commands from inside
WebSphere Message Broker Monitoring. These commands would otherwise have to
be entered either from a command prompt, or from the Message Brokers Toolkit.
You can issue the commands from the Take Action view, from the situation
window when a situation has become true, from the Navigator, or from a row in a
table view. For more information about how to send a Take Action command, see
Tivoli Enterprise Portal online help.
The Take Action commands for WebSphere Message Broker Monitoring have
names beginning with the characters QI:.
Issuing Take Action commands

You can configure WebSphere Message Broker Monitoring so that only a
designated set of users can issue Take Action commands. You can specify
authorized Take Action users in the following ways:
v At the agent level, using the defaultTakeActionAuthUsers parameter.
v At the monitored broker level, using the takeActionAuthUsers parameter.
See “Agent parameter descriptions” on page 11 for details.
Command restrictions on z/OS

v The Take Action commands for WebSphere Message Broker Monitoring require
the broker name to be the same as the procedure name of the task that is started
or stopped.
v If the syntax of the Take Action command contains the Parms parameter, and the
parameter value contains lower case letter(s), enclose the value in quotation
marks.
v WebSphere Message Broker Monitoring cannot start or stop a queue manager on
z/OS.
v If you want to issue a command that is not supported by the agent, you can
issue it as a system command (a z/OS console command) instead. Use the exact
syntax of the command as documented by IBM.
v The exact command that is issued by the agent varies depending on the host
operating system on which the agent runs (especially on z/OS systems). Also,
although the commands can be issued by the agent on all supported operating
systems, some differences exist in the supported actions (especially on z/OS
systems). Differences in actions, if they exist, are noted for each command in the
following sections.
Commands for agent-managed systems

The Take Action commands for WebSphere Message Broker Monitoring agent
managed systems are described in the section.
Note: The name of the component in the commands can be a broker name, a
configuration manager name, or the name of a user name server, unless
otherwise noted.
mqsiStart
This command starts an IBM broker product component.
Identify the component to be started by specifying its name in the Edit Argument
window. The destination of this command must be an agent-managed system.
The syntax of the command that is sent to the agent is:

QI:mqsiStart ‘ComponentName’
On UNIX, Linux, and Windows: This command also starts the queue manager that
is associated with the component if it is not already active.
On UNIX, Linux, and Windows: You can also use this command to start the
configuration manager (component = ConfigMgr).
On z/OS: You cannot use this command to start a queue manager or user name
server. See “Command restrictions on z/OS” on page 48 for more information.
mqsiStop
This command stops an IBM broker product component.
On UNIX, Linux, and Windows: You can also use this command to stop the
configuration manager (component=ConfigMgr).
On z/OS: you cannot use this command to stop a user name server
(component=UserNameServer).
Identify the component that you want to stop by specifying its name in the Edit
Argument window. The destination of this command must be an agent-managed
system.

QI:mqsiStop ‘ComponentName’
mqsiStop-q
On UNIX, Linux, and Windows: This command stops the IBM broker product
component and the queue manager that is associated with it.
On UNIX, Linux, and Windows: You can also use this command to stop the
configuration manager (component=ConfigMgr).
On z/OS: This command does not stop a queue manager; see “Command
restrictions on z/OS” on page 48. This command has the same effect as the QI
Stop Component command; it stops only an IBM broker product component.
Identify the component that you want to stop by specifying its name in the Edit
Argument window. The destination of this command must be the agent-managed
system.

QI:mqsiStop-q ‘ComponentName’
mqsiChangeTrace
This command changes the trace characteristics of IBM broker product
components.
On UNIX, Linux, and Windows: You can also use this command to change trace
characteristics for the configuration manager (component=ConfigMgr).
Chapter 5. Situations and Take Action commands 49

Identify the component by specifying its name in the top field of the Edit
Argument window. If the component name contains spaces, enclose the entire
string in a pair of quotation marks (for example, ““aaaaaa bbbb cc””). Specify the
new trace parameters in the lower field of the Edit Argument window. The format
of the argument is the same as the mqsichangetrace command, using double
quotes in pairs as shown in the previous example. For change trace commands
targeted at z/OS brokers, follow the broker’s documentation precisely for the
changetrace command parameters, but use a pair of quotation marks, as
previously described. On z/OS, enclose all lowercase label names in single
quotation marks, and use commas to separate parameters. For example, on z/OS,
use the following argument to turn on the normal trace function for the default
execution group:
u=yes,e=""default"",l=normal
On other operating systems, the following argument has the same result:
-u -e default -l normal
The destination of this command must be the agent-managed system.

QI:mqsiChangeTrace ‘ComponentName’ ‘Parms’
Commands for broker-managed systems

The Take Action commands for WebSphere Message Broker Monitoring broker
managed systems are as follows.
mqsiStart
This command starts a broker.
On z/OS: The product does not currently support the f broker, startcomponent
command form of starting the broker. The s broker command form is used.
Specify the name of the broker that you want to start in the Edit Argument
window. The destination of this command must be a broker-managed system.
Note: On UNIX and Linux platforms, this command can only be used to start a
broker after the database used by the broker has been sourced.

QI:mqsiStart ‘BrokerName’
mqsiStop
This command stops a broker.
On z/OS: The product does not currently support the f broker, stopcomponent
command form of stopping the broker. The p broker command form is used.
On z/OS: Using the f broker,stopcomponent command to stop the broker is not

currently supported. You must use the p broker command must be used instead.
Specify the name of the broker that you want to stop in the Edit Argument

QI:mqsiStop ‘BrokerName’
mqsiStop-q
On UNIX, Linux, and Windows: This command stops the broker and its associated
queue manager.
On z/OS: This command does not stop a queue manager (see “Command
restrictions on z/OS” on page 48). This command has the same effect as the QI
Stop Broker command; it stops a broker.
Specify the name of the broker that you want to stop in the Edit Argument

QI:mqsiStop-q ‘BrokerName’
mqsiChangeTrace
This command changes the trace characteristics of an IBM broker product.
Identify the broker by specifying its name within the top field of the Edit
Argument pop-up. If the broker name contains spaces, the entire string must be
enclosed within two sets of double quotes (for example, ““aaaaaa bbbb cc””).
Specify the new trace parameters within the lower field of the Edit Argument
pop-up. The format of the argument should use the same format as used by IBM’s
.mqsichangetrace command, using two sets of double quotes for any double
quotes used. For change trace commands targeted to z/OS brokers, follow the
brokers documentation precisely for the changetrace command parameters, except
use two sets of double quotes instead of single quotes. Remember that on z/OS
any lowercase label names must be in quotes, and commas must separate
parameters. For example, on z/OS, supply this argument to turn on normal trace
for the default execution group:
u=yes,e=""default"",l=normal
On other operating systems, the following argument has the same result:
-u -e default -l normal
The destination of this command must be a broker-managed system.

QI:mqsiChangeTrace ‘BrokerName’ ‘Parms’
mqsiChangeBroker
Use this command to change the archiving interval of a broker from Tivoli
Enterprise Portal. You can also modify other broker properties using this
command.
mqsichangebroker command, using two sets of double quotes for any double
quotes used. For change broker commands targeted to z/OS brokers, follow the
brokers documentation precisely for the changebroker command parameters,
except use two sets of double quotes instead of single quotes. Remember that on
z/OS any lowercase label names must be in quotes, and commas must separate
parameters.

QI:mqsiChangeBroker" ‘BrokerName’ ‘Parms’
The BrokerName value is the name of the targeted broker. The Parms value
provides the rest of the necessary parameters that are required or optional for the
mqsichangebroker (changebroker on z/OS) command as documented by IBM.
Tivoli Enterprise Portal does not parse or verify the parameters.
mqsiChangeFlowStats
Use this command to activate or deactivate Message Flow Accounting and
Statistics from Tivoli Enterprise Portal.
mqsichangeflowstats command, using two sets of double quotes for any double
quotes used. For change trace commands targeted to z/OS brokers, follow the
brokers documentation precisely for the changeflowstats command parameters,
except use two sets of double quotes instead of single quotes. Remember that on
z/OS any lowercase label names must be in quotes, and commas must separate
parameters.

QI:mqsiChangeFlowStats ‘BrokerName’ ‘Parms’
The BrokerName value parameter specifies the name of the targeted broker. Parms
specifies the remainder of the parameters for the mqsichangeflowstats
(changeflowstats on z/OS) command as documented by IBM. Tivoli Enterprise
Portal does not parse or verify the parameters. If you want to be able to view data
in the accounting workspaces, you must specify xml as the output (-o xml).
mqsiChangeProperties
Use the QI Change Properties command to enable Publish-Subscribe Statistics,
Multicast Summary Statistics, Multicast Group Statistics, and Multicast Topic
Statistics workspaces. This command is available only for the broker subnode
affinity.
The command has two parameters. The BrokerName parameter specifies the name
of the broker that is being targeted. The Parms parameter specifies the rest of the
mqsiChangeProperties command parameters. This command is not available on
z/OS.

QI:mqsiChangeProperties ‘BrokerName’ ‘Parms’
mflowStart
This command starts one or all of the message flows that associated with an
execution group. Enter the name of the execution group to which the message flow
belongs in the top field of the Edit Argument window. Specify the message flow to
that you want to start in the lower field of the Edit Argument window. If you do
not specify a value in the lower field, then the command starts all message flows
in the execution group. The destination of this command must be a
broker-managed system.
QI:mflowStart ‘ExecutionGroup’ ‘MessageFlow’
mflowStop
This command stops one or all of the message flows that are associated with an
execution group. Enter the name of execution group to which the message flow
belongs in the top field of the Edit Argument window. Specify the message flow
that you want to stop in the lower field of the Edit Argument window. If you do
not specify a value in the lower field, then the command stops all message flows
in the execution group. The destination of this command must be a

QI:mflowStop ‘ExecutionGroup’ ‘MessageFlow’
retainedPubDelete
This command deletes a retained publication for the specified topic and
subscription point. Enter the topic of the publication that you want to delete in the
top field of the Edit Argument window. Enter the subscription point of the
publication that you want to delete in the lower field of the Edit Argument
window. If you do not specify a subscription point, then publication for the default
subscription point is deleted. The destination of this command must be a

QI:retainedPubDelete ‘Topic’ ‘SubscriptionPoint’
createUserStatistics
This command creates user statistics that are associated with the Tivoli Enterprise
Portal logon ID that issues the command.
The logon ID that was used to create the statistics must also be used to view them.
In the Edit Argument window, specify the number of minutes that the user
statistics that are created by this command are retained by the agent without being
sampled or queried for display. If you do not specify a value, then the data is
stored until the destroyUserStatistics command is issued. The target of this
command must be a broker-managed system.

QI:createUserStatistics ‘MaxInactivityTime’
sampleUserStatistics
This command causes the agent to take a sample of CandleMonitor statistics for
the Tivoli Enterprise Portal logon ID that issues the command. A QI Create User
Statistics command must have previously been issued for the logon ID for this
command to be valid. You can use this command to effectively set an interval
during which statistics are gathered and sent to the statistics workspaces. Issue one
QI Sample User Statistics command when you want the interval to begin; issue
another QI Sample User Statistics command when you want the interval to end.
The destination of this command must be a broker-managed system.

QI:sampleUserStatistics

destroyUserStatistics
This command cleans up all user statistics data that is associated with the Tivoli
Enterprise Portal logon ID that issues the command and ensures that the agent
does not store user statistics data any more. The storage space that is used by the
data should be released when it is no longer required. The destination of this
command must be a broker-managed system.

QI:destroyUserStatistics
resetStatistics
Use this command to reset all the statistics that are collected by the CandleMonitor
node to zeros. This is useful when you are using summary statistics to perform
controlled timings. It resets all statistics for all nodes in the broker. It also updates
the shared memory area that the CandleMonitor node uses to communicate the
data to the agent, so that all uses of these statistics (regular or user) are affected.
Without this command, the statistics are reset automatically when the broker is
deployed or when overflow is detected. You cannot reset statistics for only part of
a broker because inconsistent data will be generated in Broker Statistics and
historical data reports.
Issue this command during a period of broker inactivity; otherwise, unpredictable

results might be produced, and it might seem that some statistics have not been
reset because of current activity. The destination of this command must be a

QI:resetStatistics
Using Take Action commands in situations

You can use Take Action commands in situations that you write. For more
information about Take Action commands see IBM Tivoli OMEGAMON XE for
Messaging: WebSphere MQ Monitoring User’s Guide. The term reflex automation refers
to a situation that issues a command.
To issue a command to an agent from a situation, enter the QI: syntax form of the
command on the Action page of the Situations Editor. Figure 7 shows an example
of using the QI Start Component command in a situation.
Figure 7. Example of ″QI Start Component″ command in a situation
This example shows predefined situation QI_Automation_Start_Component, which
substitutes an attribute from this product’s Components workspace. The Attribute
Substitution button was used to choose the attribute (this prevents misspellings
and inserts the ampersand character which is used for attribute substitution). The
single quotes enclosing the command parameter are required. When you are using
a Take Action command in a situation, create a working, manual version of the
Take Action command before you attempt to automate its use by adding it to a
situation.

Chapter 6. Workspaces
WebSphere Message Broker Monitoring is installed with default views that are
displayed in workspaces. Where applicable, links are provided in the workspace to
link from a parent view to a more detailed view of a selected row, or to a related
workspace (for example, a workspace containing historical information).
You can customize the format and appearance of the views in a workspace.
Note: Customize a copy of the workspace and not the workspace that WebSphere
Message Broker Monitoring provides. Use the Save as command first to
copy the workspace and give it a new name, then make changes to the copy.
You can set the workspace that you create in this manner to be the default
workspace for a given Navigator item. If you do not replace the
product-provided workspaces, you will be able to see new features that
might become available in later versions of WebSphere Message Broker
Monitoring without having to revert to the original workspace. For
information on customizing workspaces and views, see the Tivoli Enterprise
Portal online help.
The following sections provide information about workspace groups. For detailed
descriptions of individual attributes in a workspace, see the online help for
Prerequisites
The availability of some data and statistics depends on prior conditions. If these
conditions are not met, no information is available in the workspace:
v For archive or snapshot accounting data to be available, brokers must be
configured to collect it and the destination of the statistics output (-o) must be
xml.
You can use the QI Change Flow Stats Take Action command to configure the
broker to collect archive or snapshot accounting statistics from Tivoli Enterprise
Portal.
v For user statistics to be available, the QI Create User Statistics Take Action
command must have been issued for the user’s logon ID.
v For message flow and sub-flow statistics and events to be available,
CandleMonitor nodes must be included in the message flow (see Chapter 3,
“Customizing the CandleMonitor node,” on page 23).
v For accounting origin information to be available in accounting workspaces,
participating message flows must be configured to provide the appropriate
origin identifier. If you do not specify a value, the Accounting Origin column in
the Accounting workspaces contains the value Anonymous.
User statistics
In a development environment, sampling statistics at a set interval might not
provide the flexibility that you need. The user statistics feature, implemented by
three Take Action commands, enables you to collect statistics that are associated
with a particular Tivoli Enterprise Portal logon ID. These user statistics are
displayed in the statistics workspaces from which they are derived and can be

linked to from related statistics workspaces, as shown in Table 3.
Table 3. Workspaces with user statistics links
Workspace User statistics links
User Broker Statistics
Broker Statistics
User Execution Group Statistics
User Execution Group Statistics
Execution Group Statistics
User Message Flow Statistics
User Message Flow Statistics
Message Flow Statistics User Sub-Flow Statistics
User CandleMonitor Node Statistics
User Sub-Flow Statistics
Sub-Flow Statistics
User CandleMonitor Node Statistics
CandleMonitor Node Statistics User CandleMonitor Node Statistics
You must issue a QI Create User Statistics Take Action command for the user’s
logon ID the user statistics workspaces can be accessed. If you try to follow a link
to a workspace before the command has been issued for your logon ID, no data
will be available in the workspace that you linked to.
The user statistics are not collected historically.
Snapshot and archive accounting statistics

Two types of accounting and statistics data for message flows are provided with
version 5 of WebSphere Message Brokers: snapshot and archive. You can turn on
one or both types of collection for all message flows in a broker, all message flows
in an execution group, or individual message flows in an execution group. The
actual data produced for both types are similar; however, you has some control
over how much detail is provided.
Snapshot data is collected at 20-second intervals. This type of data collection is not
done for prolonged periods of time, because of the resource overhead involved
with collecting the statistics. Archive data is collected at an interval that you can
configure; the default interval is every 60 minutes. This data is intended for use in
more long-term accounting and statistics.
WebSphere Message Broker Monitoring displays accounting and statistics data in a

set of workspaces. You can view data that was collected during the current
collection interval, recent sampling intervals, or during historical collection
intervals.
Although there is considerable overlap between the accounting statistics provided

by WebSphere Message Brokers and the statistics provided by the CandleMonitor
node, the CandleMonitor node statistics provide a high-level view (by broker and
execution group), but the accounting statistics provide a more detailed view (by
terminal and thread). User statistics, sub-flow statistics, queue times, and message
flow events are available only if you are collecting statistics using a CandleMonitor
node. CPU time statistics are available only as part of accounting statistics.
WebSphere Message Broker Monitoring historical data collection allows you to
track the archive statistics for accounting purposes without purchasing or
developing a second application.
You must configure brokers to collect the data that is displayed in the accounting
workspaces. If you have not configured the brokers to collect the level of detail
given in a certain workspace, no data is displayed. In addition, you must set the
output destination for the accounting and statistics data to xml. See
“mqsiChangeFlowStats” on page 52 and the details of the IBM
mqsichangeflowstats command in WebSphere Message Broker documentation to
determine how to set the broker to collect the statistics that you want.
If you intend to use the accounting origin support to organize your data, you must
configure participating message flows to provide the appropriate origin identifier.
As described in the WebSphere Message Broker documentation, this involves
coding an ESQL statement in either a Compute, Database, or Filter node that sets
the value that you want. In addition, you must specify the -b basic parameter on
the the mqsichangeflowstats command that you use to start data collection.
Reset of statistics
Cumulative statistics with Overall attribute names are maintained internally at the
CandleMonitor node level. These statistics are simultaneously reset to 0 for all
CandleMonitor nodes when a deploy operation to a broker involves any message
flow containing a CandleMonitor node, when any CandleMonitor node detects an
overflow condition for statistics, or when the Reset Statistics Take Action command
has been issued.
A reset of statistics includes all statistics maintained for the broker in order to
preserve the integrity of summarized statistics. The CandleMonitor node produces
an Event Log message when a reset occurs due to a numerical overflow condition,
and the monitoring agent logs a message when a reset is detected.
At the time of a reset of statistics, workspaces will show that the Overall statistics
have started over from zero.
Historical workspaces will show data prior to the reset combined with data
following the reset for the interval in which the reset occurred. This ensures that
no historical data is lost. In subsequent intervals, the historical workspaces will
show the Overall values as having started over from zero.
Upgrading workspaces
If you have upgraded WebSphere Message Broker Monitoring from a lower
version, you will see product-provided workspaces but not the new features. To
gain access to the new features, revert to the product-provided workspaces by
following these steps for each Statistics workspace:
1. In the Navigator pane, select a Statistics workspace.
2. On the File menu, select Restore Original Workspace.
3. Refresh the workspace.
You should now be able to use the new features.
Chapter 6. Workspaces 59
Workspace summary
Use the references in this section to find information about the following
workspaces:
v “Agent and application status workspaces”
v “Broker and message flow Information workspaces”
v “Event workspaces” on page 61
v “Statistics workspaces” on page 61
v “Accounting workspaces” on page 61
v “Publish and Subscribe workspaces” on page 62
Agent and application status workspaces

v The Agent Status workspace summarizes event and IBM broker product
component information at the agent level. See “Agent Status Workspace
(agent-level summary)” on page 63.
v The Components workspace displays a list of IBM broker product components
and their state at the agent level. See “Components workspace” on page 76.
v The Broker Summary workspace summarizes broker status and definition data
when multiple brokers are monitored by the same agent. See “Broker Summary
workspace (multiple monitored brokers)” on page 74.
v The Broker Status workspace summarizes event and definition information at
the broker level. See “Broker Status workspace (broker-level summary)” on page
73
Broker and message flow Information workspaces

v The Broker Information workspace summarizes broker activity, displays the
name of the broker’s associated queue manager, and indicates whether or not
the agent can connect to the broker’s queue manager. See “Broker Information
workspace” on page 70.
v The Execution Group Information workspace displays execution groups that are
defined for the broker and as well as definition information for each execution
group. See “Execution Group Information workspace” on page 77.
v The Message Flow Information workspace displays defined message flows by
execution group and definition information for each. See “Message Flow
Information workspace” on page 81.
v The Message Processing Node Information workspace displays defined message
processing nodes by their execution group and message flow. See “Message
Processing Node Information workspace” on page 84.
– The Message Processing Nodes with Queue workspace lists all
message-processing nodes in the system that have the same queue name
(when you link from a row in the Message Processing Node Information
workspace). See “Message Processing Nodes with Queue workspace” on page
85.
– The Message Processing Node Attributes workspace displays all attribute
values for a message-processing node (when you link to the workspace from
a row in the Message Processing Node Information workspace). See “Message
Processing Node Attributes workspace” on page 83.
Event workspaces
v The Product Events workspace displays events that are generated by the agent
when a problem occurs that affects the agent’s ability to collect data. See
“Product Events workspace” on page 89.
v The Broker Events workspace lists events that are generated by a broker as they
occur. See “Broker Events workspace” on page 69.
v The Message Flow Events workspace lists events that are generated by a
CandleMonitor node as they occur. See “Message Flow Events workspace” on
page 80.
Statistics workspaces
v The Broker Statistics workspace provides summarized message flow statistics at
the broker level. See “Broker Statistics workspace” on page 72.
v The CandleMonitor Node Statistics workspace provides message flow statistics
at the individual node level at which they are collected. See “CandleMonitor
Node Statistics workspace” on page 75.
v The Execution Group Statistics workspace provides summarized message flow
statistics at the execution group level. See “Execution Group Statistics
v The Message Flow Statistics workspace provides summarized message flow
statistics at the message flow level. See “Message Flow Statistics workspace” on
page 82.
v The Sub-Flow Statistics workspace provides summarized statistics at the
sub-flow level. See “Sub-Flow Statistics workspace” on page 99.
Note: With V5 and V6 brokers, IBM provides message flow accounting and
statistics that partially overlap with the statistics provided by the
CandleMonitor node and can be monitored in Tivoli Enterprise Portal
without including the CandleMonitor node in message flows. However, the
CandleMonitor node provides additional statistics, as well as the ability to
monitor sub-flows and define message flow events. Message flows without a
CandleMonitor node are not represented in Statistics workspaces. The
CandleMonitor node does not function with WebSphere MQ Event Broker
v2.1.
Accounting workspaces
Accounting workspaces provide IBM broker product statistics at message flow,
node, thread, and terminal level. The data in the workspaces is sampled at
snapshot (short term) or archive (long term) intervals. Top-level snapshot and
archive workspaces present current accounting data for that interval. Each
workspace links to workspaces that show the same data for the most recent
collection intervals and for the historical collection intervals, if those intervals are
configured.
v The Snapshot Message Flow Accounting and Archive Message Flow Accounting
workspaces provide statistics at the message flow level. See “Snapshot Message
Flow Accounting workspace” on page 92 and “Archive Message Flow
Accounting workspace” on page 63.
v The Snapshot Node Accounting and Archive Node Accounting workspaces
provide statistics at the processing node level. See “Snapshot Node Accounting
workspace” on page 95 and “Archive Node Accounting workspace” on page 65.
v The Snapshot Terminal Accounting and Archive Terminal Accounting
workspaces provide statistics at the terminal level. See “Snapshot Terminal
Accounting workspace” on page 96 and “Archive Terminal Accounting
v The Snapshot Thread Accounting and Archive Thread Accounting workspaces
provide statistics at the thread level. See “Snapshot Thread Accounting
workspace” on page 97 and “Archive Thread Accounting workspace” on page
68.
Publish and Subscribe workspaces

v The ACL Entries workspace displays ACL entries per topic, which define access
to publish and subscribe topics. See “ACL Entries workspace” on page 62.
v The Multicast Group Statistics workspace displays current multicast group
statistics. See “Multicast Group Statistics workspace” on page 86
v The Multicast Summary Statistics workspace displays current multicast summary
statistics. See “Multicast Summary Statistics workspace” on page 87
v The Multicast Topic Statistics workspace displays current multicast topic
statistics. See “Multicast Topic Statistics workspace” on page 88
v The Neighbors workspace displays a list of neighbors to the broker in the
publish and subscribe topology, and their connection attributes. See “Neighbors
v The Publish-Subscribe Statistics workspace displays current publish and
subscribe statistics (excluding multicast data). See “Publish-Subscribe Statistics
workspace” on page 90
v The Retained Publications workspace displays a list of topic and subscription
points that contain a publication that was retained. See “Retained Publications
v The Subscriptions workspace displays a list of subscriptions to topics. See
“Subscriptions workspace” on page 100.
ACL Entries workspace

The ACL Entries workspace contains a list of Access Control List entries on a
particular managed system, organized by topic. Access Control List entries define
access to publish and subscribe topics.
Default views
This workspace contains the following default views:
v Enterprise Event Log: Shows a table that contains all situations that were raised
in the entire system, all situations that were raised in the entire system.
v ACL Entries shows, as a table, all ACL Entries for the broker.
Information presented in the ACL Entries table view

The ACL Entries table view displays data provided by the ACL Entries attributes:
v Broker
v Origin Node
v Persistent
v Principal
v Publish
v Subscribe
v Topic
For a detailed description of these attributes and their values, see the online help
Agent Status Workspace (agent-level summary)

The Agent Status workspace summarizes event and IBM broker product
component information from a particular agent managed system at the agent level.
Default views
v Product Events: Shows a table that contains the product events that were most
recently retained.
v Components shows, as a table, all components that have been created on the
system that the agent is monitoring.
Accessing this workspace

To access this workspace, in the Navigator physical view click the QI Agent folder
icon.
Figure 8. QI Agent in the Navigator physical view
Archive Message Flow Accounting workspace

This workspace provides statistics pertaining to entire message flows, for the
current archive collection interval. In this top-level view, there is one row per
monitored message flow, which contains data for the message flow that was
collected during the current collection interval. The interval at which data is
collected is configured at the broker.
If the broker has not been set to collect this type of data, no data is displayed. The
data shown in this view is available to situations by default.
Default views
v Message Flow Elapsed Time: Shows a bar chart that contains the minimum,
maximum, and average time, in microseconds, that was spent processing
messages during the current archive interval.
v Message Flow CPU Time: Shows a bar chart that contains the minimum,
maximum, and average CPU time, in microseconds, that was spent processing
messages during the current archive interval.
v Archive Message Flow Accounting: Shows a table view that contains accounting
statistics arranged by message flow.
Information presented in the Archive Message Flow

Accounting table view
The Archive Message Flow Accounting table view displays data provided by the
Message Flow Accounting attributes, which are as follows:
v Accounting Origin
v Average CPU Microseconds
v Average CPU Time
v Average Elapsed Microseconds
v Average Elapsed Time
v Average Input Message Size
v Average Input Message Size String
v Broker
v Broker UUID
v End Date
v End Date and Time
v End Time
v Execution Group
v Execution Group UUID
v Input Byte Rate
v Input Message Rate
v Input Message Wait CPU Microseconds
v Input Message Wait CPU Time
v Input Message Wait Elapsed Microseconds
v Input Message Wait Elapsed Time
v Maximum CPU Microseconds
v Maximum CPU Time
v Maximum Elapsed Microseconds
v Maximum Elapsed Time
v Maximum Input Message Size
v Maximum Input Message Size String
v Message Flow
v Minimum CPU Microseconds
v Minimum CPU Time
v Minimum Elapsed Microseconds
v Minimum Elapsed Time
v Minimum Input Message Size
v Minimum Input Message Size String
v Node Statistics Count
v Number of Threads in Pool
v Origin Node
v Query Type
v Record Code
v Record Type
v Sample Handle
v Start Date
v Start Date and Time
v Start Time
v Thread Statistics Count
v Times Maximum Number of Threads Reached
v Total CPU Microseconds
v Total CPU Time
v Total Elapsed Microseconds
v Total Elapsed Time
v Total Input Message Size
v Total Input Message Size String
v Total Input Messages
v Total Number of Aggregate Reply Wait Timeouts
v Total Number of Backouts
v Total Number of Commits
v Total Number of Errors Processing Messages
v Total Number of Messages with Errors
v Total Number of MQ Errors
For a detailed description of these attributes and their values, refer to the online
help for WebSphere Message Broker Monitoring.
Predefined links
This workspace contains links to the Archive Thread Accounting, Archive Node
Accounting and Archive Terminal Accounting workspaces. It also contains links to
Recent Archive Message Flow Accounting and Historical Archive Message Flow
Accounting workspaces for the selected message flow. The number of rows of data
that are displayed in the Recent Archive Message Flow Accounting workspace
depends on the value assigned to the defaultRetainRecentArchiveSamples (or
retainRecentArchiveSamples) parameter, which specifies the minimum number of
recent archive records to retain; however, the number of records that are retained
might be greater than specified by these parameters, depending on the data
retention requirements of historical data collection.
Archive Node Accounting workspace

This workspace contains statistical information about nodes used by message flows
during the current archive interval. There is one row per node in a message flow.
Typically, you link to this workspace for information about a specific message flow,
so all nodes shown pertain to that message flow.
The data shown in this view is available to situations by default.
Default views
v Archive Node Accounting : Shows a table that contain archive statistics for
nodes used by message flows.
v Node Elapsed Time: Shows a bar chart that contains the minimum, maximum,
and average time that the node spent processing an input message.
v Node CPU Time: Shows a bar chart that contains, the minimum, maximum and
average CPU time that spent processing an input message
Information presented in the Archive Node Accounting table

view
The Archive Node Accounting table view displays data provided by the Node
Accounting attributes, as shown on the next page. For a detailed description of
these attributes and their values, see the online help for WebSphere Message
Broker Monitoring.
v Accounting Origin
v Average CPU Time
v Broker
v Count of Invocations
v End Date and Time
v Execution Group
v Invocation Rate
v Maximum CPU Time
v Message Flow
v Minimum CPU Time
v Number of Input Terminals
v Number of Output Terminals
v Origin Node
v Processing Node Label
v Processing Node Type
v Query Type
v Record Code
v Record Type
v Sample Handle
v Total CPU Time
Predefined links
This workspace contains a link to the Archive Terminal Accounting workspace. It
also contains links to Recent Archive Node Accounting and Historical Archive
Node Accounting workspaces for the selected message flow. The number of rows
of data that are displayed in the Recent Archive Node Accounting workspace
retainRecentArchiveSamples) parameter, which determines the minimum number
of recent archive records to retain; however, the number of records that are actually
retained and available for viewing might be greater than the number specified by
these variables.
Archive Terminal Accounting workspace

This workspace contains statistical information about terminals that are on nodes
used by message flows during the current archive interval. There is one row per
terminal for each node in a message flow. Typically, you link to this workspace for
a specific message flow and node; all terminals for which data is displayed belong
to that message flow and node.
Default views
v Archive Terminal Accounting: Shows a table that contains archive statistics for
terminals that are on nodes used by message flows, for the current collection
interval.
v Terminal Invocation Rate: Shows a bar chart that contains the rate at which
terminals were invoked during the current interval.
Information presented in the Archive Terminal Accounting

table view
The Archive Terminal Accounting table view contains data provided by the
Terminal Accounting attributes. For a detailed description of these attributes and
their values, see the online help for WebSphere Message Broker Monitoring.
v Accounting Origin
v Broker
v End Date and Time
v Execution Group
v Invocation Rate
v Message Flow
v Origin Node
v Query Type
v Record Code
v Record Type
v Sample Handle
v Terminal Label
v Terminal Type
Predefined links
This workspace contains links to the Recent Archive Terminal Accounting and
Historical Archive Terminal Accounting workspaces for the message flow and node
that are shown when you select a row in this workspace. The number of rows of
data that are displayed in the Recent Archive Terminal Accounting workspace
retainRecentArchiveSamples) parameter, which indicates the minimum number of
recent archive records to retain, although the number of records that are actually
retained and available for viewing might be greater than the number specified by
these variables.
Archive Thread Accounting workspace

This workspace contains archive statistics that pertain to threads that are used by
message flows. There is one row of data per thread for each message flow for the
current archive interval. Typically, you link to this workspace for a specific
message flow, so all threads that are shown relate to that message flow.
Default views
v Archive Thread Accounting: Shows a table that contains archive statistics for
threads used by message flows.
v Thread Elapsed Time: Shows a bar chart that contains the minimum, maximum,
and average time that was spent processing input messages during the current
interval.
v Thread CPU Time: Shows a bar chart that contains the minimum, maximum,
and average CPU time that was spent processing input messages during the
current interval.
Information presented in the Archive Thread Accounting table

view
The Archive Thread Accounting table view displays data that is provided by the
Thread Accounting attributes, as follows:
v Accounting Origin
v Average CPU Time
v Broker
v End Date and Time
v Execution Group
v Input Byte Rate
v Message Flow
v Origin Node
v Query Type
v Record Code
v Record Type
v Sample Handle
v Thread Number
v Total CPU Time
For a detailed description of these attributes and their values, refer to the
WebSphere Message Broker Monitoring online help.
Predefined links
This workspace contains links to Recent Archive Thread Accounting and Historical
Archive Thread Accounting workspaces for the message flow that is shown when
you select a row in this workspace. The number of rows of data displayed in the
Recent Archive Thread Accounting workspace depends on the value assigned to
the defaultRetainRecentArchiveSamples (or retainRecentArchiveSamples)
parameter, which indicates the minimum number of recent archive records,
although the number of records that is retained and the number of records that are
actually retained and available for viewing might be greater than the number
specified by these variables.
Broker Events workspace

The Broker Events workspace lists events that are generated on a particular broker
managed system as they occur. The number of events that is shown depends on
the number that are retained by the agent; that value is set in the agent parameter
file.
The agent receives broker events data by means of a subscription to broker event
publications. If a particular event is not published by an IBM broker product, then
it is not available for display in this workspace. Note that the Broker Information
attribute Broker Status is the best way to detect whether the broker is started or
stopped, since the Broker Event indicating that a broker has stopped may note
always occur.
Default views
within the whole system.
v Broker Events: Shows a table that contains the broker events that were retained
most recently.
Information presented in the Broker Events table view

The Broker Events table view displays data that is provided by the Broker Events
attributes, which are as follows:
v Broker
v Event
v Event Date and Time
v Event Qualifier 1
v Event Qualifier 2
v Event5 Type
v Origin Node
v PubSubConfig
v Qualifier Description 1
v Qualifier Description 2
The Broker Events attributes also provide data for the Broker Events History
workspace.
Predefined links
By default, you can link from the Broker Events table view to the Broker Events
History. (Broker Events short-term history collection is active by default. If the
event occurs, an entry is added to the historical log.)
Broker Information workspace

The Broker Information workspace contains information about a broker-managed
system, including the status of the broker, its process ID, information about the
operating system on which it runs, its job on z/OS systems, the queue manager
associated with its configuration manager, its associated queue manager, and
whether or not the agent can connect to the broker’s queue manager.
Default views
in the entire system.
v Broker Information: Shows a table that contains broker status and definition
data.
Information presented in the Broker Information table view

The Broker Information table view contains data that is provided by the Broker
Information attributes, which are as follows:
v Address Space Identifier
v Broker
v Broker Status
v Component Type
v Configuration Manager Queue Manager
v Data Source Name
v Execution Groups
v Jobname Taskname
v Migration Needed
v Origin Node
v Platform
v Platform Version
v Process Identifier
v Queue Manager
v Queue Manager Connection Status
v Release
v Started Message Flows
v Stopped Message Flows
v Statistics Archive Interval
v System Name
v Total Message Flows
v Trace Level
v Trusted Queue Manager
v User Name Server Queue Manager
v UUID
v Configuration Timeout
v Configuration Delay Timeout
v Publish Subscribe Access Control
v Lil Path
v Http Listener Port
v Http Listener Trace Level
v Http Listener Trace Size
v FAD Level
v Converters
The Broker Information attributes also provide data for the Broker Information
History workspace and the Neighbor Broker Information workspace.
Predefined links
By default, you can link from the Broker Information table view to Broker Statistics
and Broker Information History (Broker Information short-term history collection is
active, by default, with a collection interval of 15 minutes.)
Broker Statistics workspace
The Broker Statistics workspace provides high-level message flow statistics that are
summarized at the broker level. For this workspace to contain data, the broker
must have at least one deployed CandleMonitor node with the type attribute input
or output.
Default views
v Current Message Rates: Shows a bar chart that contains the message input rate
and message output rate for the broker.
v Current Average Message Time: Shows a bar chart that contains average queue
and flow times for the broker.
v Broker Statistics: Shows a table that contains statistical data summarized for the
broker.
Note: Move the cursor over different areas of a chart to display hover help details
about the items in the chart.
Information presented in the Broker Statistics table view

The Broker Statistics table view contains data that provided by the Broker Statistics
v BrokerCurrent Average Flow Time
v Current Average Message Size
v Current Average Message Time
v Current Average Queue Time
v Current Interval
v Current Message Byte Input Rate
v Current Message Byte Output Rate
v Current Message Input Count
v Current Message Input Rate
v Current Message Output Count
v Current Message Output Rate
v First Message Date and Time
v Jobname Taskname
v Last Message Date and Time
v Monitored Execution Groups
v Monitored Message Flows
v Origin Node
v Overall Average Flow Time
v Overall Average Message Size
v Overall Average Message Time
v Overall Average Queue Time
v Overall Maximum Flow Time
v Overall Maximum Message Size
v Overall Maximum Queue Time
v Overall Message Byte Input Rate
v Overall Message Byte Output Rate
v Overall Message Input Count
v Overall Message Input Rate
v Overall Message Output Count
v Overall Message Output Rate
v Overall Minimum Flow Time
v Overall Minimum Message Size
v Overall Minimum Queue Time
v Platform
v Platform Version
v Sample Date and Time
v Status
v System Name
The Broker Statistics attributes also provide data for the Broker Statistics History
workspace.
Predefined links
By default, you can link from the Broker Statistics table view to the Broker
Information and Broker Statistics History workspaces (Broker Statistics short-term
history collection is active, by default, with a collection interval of 15 minutes.) You
can also link to the User Broker Statistics and User Execution Group Statistics
workspaces.
Broker Status workspace (broker-level summary)

The Broker Status workspace summarizes event, status, and definition information
for a particular broker.
Default views
v Broker Events: Shows a table that contains the broker events that were retained
most recently.
v Message Flow Events: Shows a table that contains the message flow events that
were retained most recently.
v Broker Information: Shows a table that contains broker status and definition
data.

To access this workspace, in the Navigator physical view click one of the broker
managed system folder icons.
Figure 9. Broker managed system
If only one broker is monitored, the broker managed system folder icon is merged
with the QI Broker folder icon.
QI Agent
Components
Product Events
QI Broker - BK_01
Figure 10. Broker managed system merged with the QI Broker
Broker Summary workspace (multiple monitored brokers)

The Broker Summary workspace contains information about a QI Broker folder
node when multiple brokers are monitored by the same agent. It lists information
about each monitored broker.
Default views
v Broker Information : Shows a table that contains the broker status and
definition data for each broker monitored by the agent.

To access this workspace, in the Navigator physical view click the QI Broker folder
icon.
QI Agent
Components
Product Events
QI Broker
GGHE_BK
MQSI_AIX_STBK01
MQSI_AIX_STBK02
MQSI_TESTBK01
MQSI_TESTBK02
MQSI_TESTBK03
Figure 11. QI broker in the Navigator physical view
CandleMonitor Node Statistics workspace

The CandleMonitor Node Statistics workspace contains message flow statistics for
a particular broker-managed system, organized by the CandleMonitor nodes that
collected the statistics. For this workspace to contain data, the broker must have at
least one deployed CandleMonitor node with the type attribute input, output, or
other.
Default views
v Current Message Rate: Shows a bar chart that contains the message flow rate,
organized by message processing node.
v Current Average Message Time : Shows a bar chart that contains average queue
and flow times, organized by message processing node.
v CandleMonitor Node Statistics: Shows a table that contains statistical data,
organized by CandleMonitor node.
Note: Move the cursor over different areas of a chart to display hover help details
about the items in the chart.
Information presented in the CandleMonitor Node Statistics

table view
The CandleMonitor Node Statistics table view contains data that is provided by the
CandleMonitor Node Statistics attributes, which are as follows:
v Broker
v Current Average Flow Time
v Current Interval
v Current Message Byte Rate
v Current Message Count
v Current Message Rate
v Execution Group
v Message Flow
v Monitor Type
v Origin Node
v Overall Message Byte Rate
v Overall Message Count
v Overall Message Rate
v Node Label
v subflow Name
The CandleMonitor Node Statistics attributes also provide data for the
CandleMonitor Node Statistics History workspace.
Predefined links
By default, you can link from the CandleMonitor Node Statistics table view to
Message Processing Node Information (filtered by execution group and Message
Flow), and CandleMonitor Node Statistics History (CandleMonitor Node Statistics
short-term history collection is active, by default, with a collection interval of 15
minutes.) You can also link to the User CandleMonitor Node Statistics.
Components workspace
The Components workspace contains a list of IBM broker product components and
their state at the agent level.
Default views
v Enterprise Event Log shows, as a table, all situations that were raised in the
entire system.
v Components shows, as a table, all monitored components in the system.
Information presented in the Components table view
The Components table view contains data provided by the Components attributes,
which are as follows:
v Component
v Component Type
v Jobname Taskname
v Origin Node
v Platform
v Platform Version
v Queue Manager
v Release
v Status
v System Name
v User Name Server Queue Manager
The Components attributes also provide data for the Components History
workspace.
Predefined links
By default, you can link from this Components table view to the Components
History workspace (Components short-term history collection is active, by default,
with a collection interval of 15 minutes.)
Execution Group Information workspace

The Execution Group Information workspace contains details about execution
group definitions on a particular broker.
Default views
v Execution Group Information: Shows a table that contains execution group
information.
Information presented in the Execution Group Information

table view
The Execution Group Information table view contains data that is provided by the
Execution Group Information attributes, which are as follows:
v Broker
v Event Log File Mode
v Event Log File Size
v Execution Group
v Origin Node
v Stopped Message Flows
v Total Message Flows
v Trace Filter
v Trace Level
v Trace Log File Mode
v Trace Log File Size
v User Trace Filter
v User Trace Level
v User Trace Log File Mode
v User Trace Log File Size
v UUID
Predefined links
By default, you can link from the Execution Group Information table view to
Execution Group Statistics (filtered by execution group) and the Message Flow
Information (filtered by execution group workspaces).
Execution Group Statistics workspace

The Execution Group Statistics workspace contains high-level message flow
statistics summarized at the execution group level for a particular broker-managed
system. To obtain data for this workspace, the broker must have at least one
deployed CandleMonitor node with the type attribute input or output.
Default views
v Current Message Rates: Shows a bar chart that contains message input rate and
message output rate, organized by execution group.
and flow times, organized by execution group.
v Execution Group Statistics: Shows a table that contains state and statistical data,
organized by execution group.
Note: Move the cursor over different areas of a chart to display hover help
information about the items in the chart.
Information presented in the Execution Group Statistics table

view
The Execution Group Statistics table view contains data that is provided by the
Execution Group Statistics attributes, which are as follows:
v Broker
v Current Interval
v Execution Group
v Jobname Taskname
v Monitored Message Flows
v Origin Node
v Platform
v Platform Version
v Status
v System Name
The Execution Group Statistics attributes also provide data for the Execution
Group Statistics History workspace.
Predefined links
By default, you can link from the Execution Group Statistics table view to Message
Flow Statistics (filtered by execution group), Execution Group Information (filtered
by execution group), and Execution Group Statistics History (Execution Group
Statistics short-term history collection is active, by default, with a collection
interval of 15 minutes.) You can also link to User Execution Group Statistics and
User Message Flow Statistics.
Message Flow Events workspace

The Message Flow Events workspace lists events that are generated by
CandleMonitor nodes on a particular broker-managed system as they occur. The
number of events that is shown depends on the number of events that are retained
by the agent; the value is set in the agent parameter file.
For this workspace to contain data, the broker must have at least one deployed
CandleMonitor node with the type attribute other and message text specified in
the eventMessage attribute.
Default views
v Enterprise Event Log : Shows a table that contains all situations that were raised
v Message Flow Events: Shows a table that contains the Message Flow Events that
were retained most recently.
Information presented in the Message Flow Events table view

The Message Flow Events table view displays data that is provided by the
Message Flow Events attributes, which are as follows:
v Broker
v Correlation Identifier
v Event Message
v Execution Group
v Message Flow
v Message Identifier
v Monitor Type
v Origin Node
v Put Application Name
v Put Application Type
v Put Date and Time
v Thread Identifier
The Message Flow Events attributes also provide data for the Message Flow Events
History workspace.
Predefined links
By default, you can link from this Message Flow Events table view to the Message
Processing Node Information workspace (filtered by execution group and Message
Flow) and Message Flow Events History. (Message Flow Events short-term history
collection is active by default. If the event occurs, an entry is written to the
historical log.)
Message Flow Information workspace

The Message Flow Information workspace contains information about the message
flows that defined on a particular broker-managed system, organized by execution
group. This workspace also contains a range of settings that you can use to modify
the workspace contents.
Default views
v Message Flow Information: Shows a table that contains message flow
information.
Information presented in the Message Flow Information table

view
The Message Flow Information table view displays data that is provided by the
Message Flow Information attributes, which are as follows:
v Additional Instances
v Broker
v Commit Count
v Commit Interval
v Coordinated Transaction
v Execution Group
v Message Flow
v Message Flow Type
v Origin Node
v Processing Nodes
v Status
v Statistics Archive Accounting Origin
v Statistics Archive Node Data Level
v Statistics Archive Output Format
v Statistics Archive Reset
v Statistics Archive Status
v Statistics Archive Thread Data Level
v Statistics Snapshot Accounting Origin
v Statistics Snapshot Node Data Level
v Statistics Snapshot Output Format
v Statistics Snapshot Status
v Statistics Snapshot Thread Data Level
v Trace Filter
v Trace Level
v User Trace Filter
v User Trace Level
v UUID
Predefined links
By default, you can link from the Message Flow Information table view to the
Message Flow Statistics (filtered by execution group and Message Flow) and
Message Processing Node Information views (filtered by execution group and
Message Flow).
Message Flow Statistics workspace

The Message Flow Statistics workspace contains high-level message flow statistics
summarized at the message flow level for a particular broker-managed system.
For this workspace to contain data, the broker must have at least one deployed
CandleMonitor node with the type attribute input or output.
Default views
v Current Message Rates: Shows a bar chart that contains message input and
output rate, organized by message flow.
and flow times, organized by message flow.
v Message Flow Statistics: Shows a bar chart that contains state and statistical
data, organized by message flow.
Note: Move the cursor over different areas of a chart to display hover help
information about the items in the chart.
Information presented in the Message Flow Statistics table

view
The Message Flow Statistics table view displays data that is provided by the
Message Flow Statistics attributes, which are as follows:
v Broker
v Execution Group
v Current Interval
v Message Flow
v Monitor Nodes
v Origin Node
v Sample Data and Time
v Status
The Message Flow Statistics attributes also provides data for the Message Flow
Statistics History workspace.
Predefined links
By default, you can link from the Message Flow Statistics table view to the
CandleMonitor Node Statistics (filtered by execution group and Message Flow),
Message Flow Information (filtered by execution group and Message Flow), and
Message Flow Statistics History views (Message Flow Statistics short-term history
collection is active, by default, with a collection interval of 15 minutes.) You can
also link to sub-flow Statistics, User Message Flow Statistics, User sub-flow
Statistics, and User CandleMonitor Node Statistics.
Message Processing Node Attributes workspace

The Message Processing Node Attributes workspace lists all attribute values for the
selected message processing node (within a message flow).
Message processing node attributes are defined in the IBM broker product Message
Brokers Toolkit when you configure a node within a message flow. Each node has
its own distinct attributes that you can use to customize node functionality.
This workspace only contains data if node data collection is enabled in the kqi.xml
configuration file. Note, however, that if message brokers in your environment are
configured with a large number of message flows, or message flows that have a lot
of message processing node data, enabling this option might drastically degrade
system performance. For more information on enabling node data collection for all
message brokers, see “defaultCollectNodeData” on page 15, and for a single
message broker, see “collectNodeData” on page 18.
Default views
v Message Processing Node Attributes: Shows a table that contains a list of each
attribute and its value for the selected processing node.

To access this workspace, select a row in the Message Processing Node Information
table view, and then right-click and select Message Processing Node Attributes.
Information presented in the Message Processing Node

Attributes table view
The Message Processing Node Attributes table view displays data that is provided
by the Message Processing Node Attributes group of attributes, which are as
follows:
v Attribute Name
v Attribute Value
v Broker
v Execution Group
v Message Flow
v Origin Node
v Processing Node Name
Message Processing Node Information workspace

The Message Processing Node Information workspace contains information about
nodes that process information, organized by execution group and message flow,
for a particular broker managed system.
This workspace only contains data if node data collection is enabled in the kqi.xml
configuration file. Note, however, that if message brokers in your environment are
configured with a large number of message flows, or message flows that have a lot
of message processing node data, enabling this option might drastically degrade
system performance. For more information on enabling node data collection for all
message brokers, see “defaultCollectNodeData” on page 15, and for a single
message broker, see “collectNodeData” on page 18.
Default views
in an entire system.
v Message Processing Node Information: Shows a table that contains Message
Processing Node Information.
Information presented in the Message Processing Node

Information table view
The Message Processing Node Information table view contains data that is
provided by the Message Processing Node Information attributes, which are as
follows:
v Attribute 1
v Attribute 2
v Attribute 1 Description
v Attribute 2 Description
v Broker
v Execution Group
v Message Flow
v Message Flow Type
v Origin Node
v Processing Node Name
v UUID
The Message Processing Node Information attributes also provide data for the
Message Processing Nodes with Queue workspace.
Predefined links
By default, you can link from the Message Processing Node Information table view
to the CandleMonitor Node Statistics (filtered by Execution Group and Message
Flow), Message Processing Node Attributes (filtered by Execution Group, Message
Flow, and Processing Node Label), and Message Processing Nodes with Queue
(filtered by Attribute 1 when it is a queue name).
Message Processing Nodes with Queue workspace

The Message Processing Nodes with Queue workspace lists all message processing
nodes in the enterprise that have the same queue name.
You can also use Message Processing Nodes with Queue workspace as the target
workspace of a link from a workspace that is associated with the MQ monitoring
agent (if you are using the IBM Tivoli OMEGAMON DE feature package for Tivoli
Enterprise Portal). To define such a link, study the example link provided in the
Message Processing Node Information table view to this workspace, and see the
Tivoli Enterprise Portal online help for information on customizing a workspace
link.
Default views
v Message Processing Nodes with <queue name>: Shows a table that contains
message processing node information for nodes throughout your enterprise for
which the queue name attribute matches the queue name used in the link.

To access this workspace, select a row in the Message Processing Node Information
table view that has a queue name attribute in the Attribute 1 column, then
right-click and select Message Processing Nodes with Queue.
Information Presented in the Message Processing Nodes with

<queue name> table view
The Message Processing Nodes with <queue name> table view displays data that is
provided by the Message Processing Node Information attributes described in
“Message Processing Node Information workspace” on page 84.
Multicast Group Statistics workspace

The Multicast Group Statistics workspace contains current multicast group
statistics for a particular broker-managed system.
Default views
v Multicast Group Statistics:: shows multicast statistics at the group level in the
form of a table.
v Messages Sent Rates: Shows a bar chart that contains the rate at which
multicast messages were sent by the broker during the latest interval for the
selected multicast group.
v Bytes Sent Rates: Shows a bar chart that contains number of bytes in multicast
messages that have been sent and resent by the broker during the latest interval
for the selected multicast group.
Information presented in the Multicast Group Statistics table

view
The Multicast Group Statistics table view contains data that is provided by the
Multicast Group Statistics attributes, which are as follows:
v Broker
v Bytes Queued
v Bytes Resent
v Bytes Resent per Second
v Bytes Sent
v Bytes Sent per Second
v Current Interval
v Execution Group
v Group Address
v Group Name
v Messages Sent
v Messages Sent per Second
v Origin Node
v Query Type
v Time Stamp
Predefined links
By default, you can link from the Multicast Group Statistics table view to Recent
Multicast Group Statistics and Historical Multicast Group Statistics workspaces.
You can also link to the Multicast Topic Statistics workspace. The Multicast Topic
Statistics workspace uses the Multicast Topic Statistics attributes described in
“Multicast Topic Statistics workspace” on page 88.
Multicast Summary Statistics workspace

The Multicast Summary Group Statistics workspace contains a summary of current
multicast group statistics for a particular broker-managed system.
Default views
v Multicast Summary Statistics:: shows a summary of multicast statistics in the
form of a table.
v Messages Sent Rate: Shows a bar chart that contains rate at which multicast
messages were sent by the broker over the latest interval.
v Bytes Sent Rate: Shows a bar chart that contains number of bytes in multicast
messages that have been sent and resent by the broker over the latest interval.
Information presented in the Multicast Summary Statistics

table view
The Multicast Summary Statistics table view contains data that is provided by the
Multicast Summary Statistics attributes, which are as follows:
v Broker
v Bytes Queued
v Bytes Resent
v Bytes Sent
v Current Interval
v Execution Group
v Messages Sent
v Origin Node
v Query Type
v Time Stamp
Predefined links
By default, you can link from the Multicast Summary Statistics table view to
Recent Multicast Summary Statistics and Historical Multicast Summary Statistics
workspaces. You can also link to the Multicast Group Statistics and Multicast Topic
Statistics workspaces. The Multicast Group Statistics workspace uses the Multicast
Group Statistics attributes described in “Multicast Group Statistics workspace” on
page 86, and the Multicast Topic Statistics workspace uses the Multicast Topic
Statistics attributes described in “Multicast Topic Statistics workspace” on page 88.
Multicast Topic Statistics workspace

The Multicast Topic Statistics workspace contains current multicast topic statistics
for a particular broker-managed system.
Default views
v Multicast Topic Statistics:: shows multicast statistics at the topic level in the
form of a table.
v Messages Sent Rates: Shows a bar chart that contains rate at which multicast
messages were sent by the broker during the interval for the selected multicast
topic.
v Bytes Sent Rates: Shows a bar chart that contains number of bytes in multicast
messages that have been sent and resent by the broker during the interval for
the selected multicast topic.
Information presented in the Multicast Topic Statistics table

view
The Multicast Topic Statistics table view contains data that is provided by the
Multicast Topic Statistics attributes, which are as follows:
v Broker
v Bytes Queued
v Bytes Resent
v Bytes Sent
v Current Interval
v Execution Group
v Group Name
v Messages Sent
v Origin Node
v Query Type
v Time Stamp
v Topic Name
Predefined links
By default, you can link from the Multicast Topic Statistics table view to the Recent
Multicast Topic Statistics and the Historical Multicast Topic Statistics workspaces.
Neighbors workspace
The Neighbors workspace contains a list of a particular broker’s neighbors in the
publish subscribe topology, and also their connection attributes.
Default views
v Neighbors shows, as a table, neighbor information for all of the broker’s
neighbors.
Information presented in the Neighbors table view

The Neighbors table view contains data that is provided by the Neighbors
v Broker
v Collective UUID
v Connection Queue
v Connection Queue Manager
v Neighbor UUID
v Origin Node
Predefined links
By default, you can link from the Neighbors table view to the Neighbor Broker
Information (which provides details about the neighbor broker, such as the
neighbor broker’s name). The Neighbor Broker Information workspace uses the
Broker Information attributes described in “Broker Information workspace” on
page 70.
Product Events workspace

The Product Events workspace contains a list of product events that are generated
by a particular agent when a problem occurs that affects the agent’s ability to
collect data from the broker. The number of events shown depends on the number
of events that are retained by the agent, as set in the agent parameter file (see
“retainProductEvents” on page 11).
For an explanation of the agent-generated product events and how they can be
used in problem determination, see IBM Tivoli OMEGAMON XE for Messaging:
Problem Determination Guide.
Default views
v Product Events: Shows a table that contains the product events that were
retained most recently.
Information presented in the Product Events table view

The Product Events table view contains data that is provided by the Product
Events attributes, which are as follows:
v Event
v Event Qualifier 1
v Event Qualifier 2
v Origin Node
v Reason
Product Events attributes also provide data for the Product Events History
workspace.
Note: Do not use situations based on Product Events attributes to detect the status
of a broker. Instead, use the Broker_Information.Broker_Status attribute as
demonstrated in the product-provided situations.
Predefined links
By default, you can link from this Product Events table view to the Product Events
History. (Product Events short-term history collection is active by default. If the
event occurs, an entry is added to the historical log.)
Publish-Subscribe Statistics workspace

The Publish-Subscribe Statistics workspace contains information about a
broker-managed system. It displays the current data from Publish-Subscribe
Statistics.
Default views
v Publish-Subscribe Statistics: Shows all publish-subscribe statistics, excluding
multicast data, in the form of a table.
v Client Message Rates: Shows a bar chart that contains the rate at which
messages were sent and received by the broker.
v Client Byte Rates: Shows a bar chart that contains the rate at which messages
are sent and received by the broker.
v Neighbor Message Rates: Shows a bar chart that contains all rates of messages
of the broker and its neighboring brokers.
v Neighbor Byte Rates: Shows a bar chart that contains the rate at which bytes
are sent and received between the selected broker and other neighboring
brokers.
v Publish-Subscribe Statistics: Shows a table that contains the data from
publish-subscribe statistics.
Information presented in the Publish-Subscribe Statistics
table view
The Publish-Subscribe Statistics table view contains data that is provided by the
Publish-Subscribe Statistics attributes, which are as follows:
v Broker
v Client Bytes Cut Through
v Client Bytes Cut Through per Second
v Client Bytes Dropped
v Client Bytes Dropped per Second
v Client Bytes Queued
v Client Bytes Received
v Client Bytes Received per Second
v Client Bytes Sent
v Client Bytes Sent per Second
v Client Count
v Client Disconnect Bytes Dropped
v Client Disconnect Bytes Dropped per Second
v Client Disconnect Messages Dropped
v Client Disconnect Messages Dropped per Second
v Client Messages Dropped
v Client Messages Dropped per Second
v Client Messages Received
v Client Messages Received per Second
v Client Messages Sent
v Client Messages Sent per Second
v Current Interval
v Execution Group
v Neighbor Bytes Cut Through
v Neighbor Bytes Cut Through per Second
v Neighbor Bytes Dropped
v Neighbor Bytes Dropped per Second
v Neighbor Bytes Queued
v Neighbor Bytes Received
v Neighbor Bytes Received per Second
v Neighbor Bytes Sent
v Neighbor Bytes Sent per Second
v Neighbor Count
v Neighbor Disconnect Bytes Dropped
v Neighbor Disconnect Bytes Dropped per Second
v Neighbor Disconnect Messages Dropped
v Neighbor Disconnect Messages Dropped per Second
v Neighbor Messages Dropped
v Neighbor Messages Dropped per Second
v Neighbor Messages Received
v Neighbor Messages Received per Second
v Neighbor Messages Sent
v Neighbor Messages Sent per Second
v Origin Node
v Query Type
v Time Stamp
v Subscription Count
Predefined links
By default, you can link from the Publish-Subscribe Statistics table view to the
Recent Publish-Subscribe Statistics and Historical Publish-Subscribe Statistics
workspaces.
Retained Publications workspace

The Retained Publications workspace contains a list of topic and subscription
points that have a publication that is retained, the publication of which is retained
within a particular broker-managed system.
Note: The data in this workspace is updated no more frequently than the length of
the cycle indicated by the agent parameter defaultStatisticInterval (or, if
specified for a specific broker, statisticInterval). The default for this interval
is 1 minute. If the parameter setting has not been modified, it can take up to
1 minute for a change to retained publication data to be shown in the
workspace.
Default views
v Retained Publications: Shows a table bar chart that contains all retained
publications for the broker.
Information presented in the Retained Publications table view

The Retained Publications table view displays data that is provided by the
Retained Publications attributes, which are:
v Broker
v Origin Node
v Subscription Point
v Topic
Snapshot Message Flow Accounting workspace

This workspace contains rows of snapshot statistics that pertain to entire message
flows, for the current snapshot collection interval. In this top-level view, there is
one row per monitored message flow, which contains the data collected for the
message flow during the current collection interval.
If the broker has not been set to collect the required data, no data is displayed in
this workspace. The data shown in this view is available to situations by default.
Default views
v Message Flow Elapsed Time: Shows a bar chart that contains the minimum,
maximum, and average time, in microseconds, that was spent processing
messages during the current snapshot interval.
v Message Flow CPU Time: Shows a bar chart that contains the minimum,
maximum, and average CPU time, in microseconds, that was spent processing
messages during the current snapshot interval.
v Snapshot Message Flow Accounting: Shows a table that contains accounting
statistics, organized by message flow, for the current snapshot interval.
Information presented in the Snapshot Message Flow

Accounting table view
The Snapshot Message Flow Accounting table view contains data that is provided
by the Message Flow Accounting attributes, which are as follows.
v Accounting Origin
v Average CPU Time
v Broker
v Broker UUID
v End Date
v End Date and Time
v End Time
v Execution Group
v Execution Group UUID
v Input Byte Rate
v Maximum CPU Time
v Message Flow
v Minimum CPU Time
v Node Statistics Count
v Number of Threads in Pool
v Origin Node
v Query Type
v Record Code
v Record Type
v Sample Handle
v Start Date
v Start Time
v Thread Statistics Count
v Times Maximum Number of Threads Reached
v Total CPU Time
v Total Number of Aggregate Reply Wait Timeouts
v Total Number of Backouts
v Total Number of Commits
v Total Number of Errors Processing Messages
v Total Number of Messages with Errors
v Total Number of MQ Errors
Predefined links
This workspace contains links to the Snapshot Thread Accounting, Snapshot Node
Accounting, and Snapshot Terminal Accounting workspaces. It also contains links
to the Recent Snapshot Message Flow Accounting and Historical Snapshot Message
Flow Accounting workspaces for the selected message flow. The number of rows of
data displayed in the Recent Snapshot Message Flow Accounting workspace
depends on the value assigned to the defaultRetainRecentSnapshotSamples (or
retainRecentSnapshotSamples) parameter, which indicates the minimum number
of recent snapshot records that are retained; however, the actual number of records
retained might be greater, depending on requirements for retaining data for
historical data collection.
Snapshot Node Accounting workspace
This workspace displays rows of statistics for nodes used by message flows for the
current snapshot interval. There is one row per node for each message flow.
Typically, you link to this workspace for a specific message flow; all nodes that are
shown belong to that message flow.
Default views
v Snapshot Node Accounting : Shows a table that contains snapshot statistics for
nodes that are used by message flows.
v Node Elapsed Time: Shows a bar chart that contains the minimum, maximum,
and average time that nodes spend processing input messages.
v Node CPU Time: Shows a bar chart that contains the minimum, maximum, and
average amount of CPU time that nodes used to process input messages.
Information presented in the Snapshot Node Accounting table

view
The Snapshot Node Accounting table view contains data that is provided by the
Node Accounting attributes. For a detailed description of these attributes and their
values, see the online help for WebSphere Message Broker Monitoring.
v Accounting Origin
v Average CPU Time
v Broker
v End Date and Time
v Execution Group
v Invocation Rate
v Maximum CPU Time
v Message Flow
v Minimum CPU Time
v Number of Input Terminals
v Number of Output Terminals
v Origin Node
v Processing Node Type
v Query Type
v Record Code
v Record Type
v Sample Handle
v Total CPU Time
Predefined links
This workspace contains a link to the Snapshot Terminal Accounting workspace. It
also contain links to the Recent Snapshot Node Accounting and Historical
Snapshot Node Accounting workspaces for the selected message flow. The number
of rows of data displayed in the Recent Snapshot Node Accounting workspace
depends on the value assigned to the defaultRetainRecentSnapshotSamples (or
retainRecentSnapshotSamples) parameter, which indicates minimum number of
recent archive records that should be retained; however, the number of records that
are retained might be greater than specified by these parameters, depending on the
data retention requirements of historical data collection.
Snapshot Terminal Accounting workspace

This workspace contains statistics that related to terminals that are on nodes used
by message flows during the current snapshot interval. For each message flow,
there is one row per terminal on each node. Typically, you link to this workspace
for a specific message flow and node; all terminals for which data is displayed
belong to that message flow and node.
Default views
v Snapshot Terminal Accounting: Shows a table that contains snapshot statistics
for terminals that are on nodes that are used by message flows.
v Terminal Invocation Rate: Shows the chart that contains the rate at which
terminals are invoked.
Information presented in the Snapshot Terminal Accounting

table view
The Snapshot Terminal Accounting table view contains data that is provided by the
Terminal Accounting attributes, as follows. For a detailed description of these
attributes and their values, see the online help for WebSphere Message Broker
Monitoring.
v Accounting Origin
v Attribute Name
v Broker
v End Date and Time
v Execution Group
v Invocation Rate
v Message Flow
v Origin Node
v Query Type
v Record Code
v Record Type
v Sample Handle
v Terminal Label
v Terminal Type
Predefined links
This workspace contains links to the Recent Snapshot Terminal Accounting and
Historical Snapshot Terminal Accounting workspaces for the message flow and
node selected in this workspace. The number of rows of data displayed in the
Recent Snapshot Terminal Accounting workspace depends on the value assigned to
the defaultRetainRecentArchiveSamples (or retainRecentArchiveSamples)
parameter, which indicates the minimum number of recent archive records that
should be retained; the number of records that are actually retained and available
for viewing might be greater than the number specified by these variables.
Snapshot Thread Accounting workspace

This workspace displays snapshot statistics that pertain to threads that are used by
message flows. There is one row of data per thread for each message flow for the
current snapshot interval. Typically, you link to this workspace for a specific
message flow; all threads that shown relate to a single message flow.
Default views
v Snapshot Thread Accounting: Shows a table that contains snapshot statistics for
threads that are used by message flows.
v Thread Elapsed Time: Shows a bar chart that contains the minimum, maximum,
and average amount of time that threads spent processing input messages
during the collection interval.
v Thread CPU Time: Shows a bar chart that contains the minimum, maximum,
and average amount of CPU time that threads used processing input messages
during the collection interval.
Information presented in the Snapshot Thread Accounting

table view
The Snapshot Thread Accounting table view contains data that is provided by the
Thread Accounting attributes, as follows:
v Accounting Origin
v Average CPU Time
v Broker
v End Date and Time
v Execution Group
v Input Byte Rate
v Message Flow
v Origin Node
v Query Type
v Record Code
v Record Type
v Sample Handle
v Thread Number
v Total CPU Time
Predefined links
This workspace contains links to the Recent Snapshot Thread Accounting and
Historical Snapshot Thread Accounting workspaces for the message flow selected
in this workspace. The number of rows of data displayed in the Recent Snapshot
Thread Accounting workspace depends on the value assigned to the
defaultRetainRecentSnapshotSamples (or retainRecentSnapshotSamples)
parameter, which indicates the minimum number of recent archive records that
should be retained; however, the number of records that are retained might be
greater than specified by these parameters, depending on the data retention
requirements of historical data collection.
Sub-Flow Statistics workspace
The Sub-Flow Statistics workspace provides statistics related to subflows.
When you select the Sub-Flow Statistics workspace in the Navigator panel, all
subflows of the specified broker are shown organized execution group and
message flow. If you link to this workspace from the Message Flow Statistics
workspace for a given message flow, only the subflows that associated with that
message flow are shown.
Default views
This workspace contains the following three views:
v Current Message Rates: Shows a bar chart that contains the message input and
output rates, organized by subflow.
v Current Average Message Time: Shows a bar chart that contains the average
queue and flow times, organized by subflow.
v Sub-Flow Statistics: Shows a table that contains state and statistical data,
organized by subflow.
Information presented in the Sub-Flow Statistics table view

The Sub-Flow Statistics table view contains data that is provided by the Sub-Flow
Statistics attributes, which are as follows.
v Broker
v Current Interval
v Current Message Bytes Input Rate
v Current Message Bytes Output Rate
v Execution Group
v Message Flow
v Monitor Nodes
v Origin Node
v Overall Message Bytes Input Rate
v Overall Message Bytes Output Rate
v subflow Name
The Sub-Flow Statistics attributes also provide data for the Sub-Flow Statistics
History workspace.
Predefined links
By default, you can link from the Sub-Flow Statistics table view to the Sub-Flow
Statistics History workspace. Links are also available to the CandleMonitor Node
Statistics workspace, so that the associated nodes and base statistical data can be
viewed for each node that is part of the subflow, and to User Sub-Flow Statistics
and User CandleMonitor Node Statistics workspaces.
Subscriptions workspace
The Subscriptions workspace contains a list of subscriptions to topics on a
particular broker-managed system.
Default views
v Subscriptions: Shows a table that contains all subscription information for the
broker.
Information presented in the Subscriptions table view

The Subscriptions table view contains data that is provided by the Subscriptions
v Broker
v Client Identity
v Create Date and Time
v Expiration Date and Time
v Filter
v Inform If Retained
v Local Only
v Origin Node
v Persistent
v Publish On Request Only
v Subscription Point
v Topic
v User Identifier

Chapter 7. Historical data
Tivoli Enterprise Portal provides options for configuring the collection and storage
of historical data from the WebSphere Message Broker Monitoring agent. You can
use these options to specify settings that related to historical data collection,
including the attributes for which historical data is collected, the collection interval,
warehousing interval, the length of time that historical data should be stored and
what reports are generated from the data. To view certain historical workspaces
within Tivoli Enterprise Portal, you must configure historical data collection for the
attribute groups that contain attributes that are displayed in those workspaces in
the window.
Initial settings for historical collection

The following historical collection is active by default after the agent has been
installed:
v If a Broker Events row occurs, an entry is added to the historical log.
v If a Message Flow Events row occurs, an entry is added to the historical log.
v If a Product Events row occurs, an entry is added to the historical log. This
situation applies to agent-managed systems.
v A Broker Information log entry is written every 15 minutes (one row per
broker).
v A Components log entry is written every 15 minutes (one row per IBM broker
product component that was created on the system). This situation applies to
agent managed systems.
The following 5 situations listed must always be configured with the same
historical data collection interval for accurate results. The configured historical data
collection interval must also be a multiple of the value of the agent parameter
defaultStatisticInterval (or statisticInterval); otherwise, historical data collection
might produce unpredictable results. For example, if you configure historical data
collection for the Statistics attribute groups to run every 5 minutes (300 seconds),
then the defaultStatisticInterval (or statisticInterval) must have one of the
following values: 60 (1 minute), 75 (1.25 minutes), 100 (1.67 minutes), 150 (2.5
minutes), or 300 (5 minutes).
v A Broker Statistics log entry is written every 15 minutes (one row per broker).
v An Execution Group Statistics log entry is written every 15 minutes (one row
per execution group).
v A Message Flow Statistics log entry is written every 15 minutes (one row per
message flow per execution group).
v A Sub-Flow Statistics log entry is written every 15 minutes (one row per
monitored subflow per message flow containing the subflow).
v A CandleMonitor Node Statistics log entry is written every 15 minutes (one row
per CandleMonitor Node).
The following 8 situations gather data only if data is produced. Also, by default,
the agent collects historical data only for use as Archive data, not Snapshot. See
“defaultHistoricalAccountingType” on page 14 and “historicalAccountingType” on
page 17 for more information.

v A Message Flow Accounting log entry is written for each Message Flow
Accounting and Statistics report that is produced by the broker.
v A Thread Accounting log entry is written for each Message Flow Accounting
and Statistics report that is produced by the broker.
v A Node Accounting log entry is written for each Message Flow Accounting and
Statistics report that is produced by the broker.
v A Terminal Accounting log entry is written for each Message Flow Accounting
and Statistics report that is produced by the broker.
v A Publish-Subscribe Statistics log entry is written for each Publish/Subscribe
statistics report that is produced by the broker.
v A Multicast Summary Statistics log entry is written for each Multicast Summary
v A Multicast Group Statistics log entry is written for each Multicast Group
v A Multicast Topic Statistics log entry is written for each Multicast Topic statistics
report that is produced by the broker.
The following historical situations are inactive by default after installation. To

activate them, you must first activate historical data collection for the indicated
product attribute group. Each attribute group corresponds to a product workspace.
For information about using the historical data collection function, see the Tivoli
Enterprise Portal online help and IBM Tivoli Monitoring Administrator’s Guide,.
v An Execution Group Information log entry is written every 15 minutes (one row
per execution group).
v A Message Flow Information log entry is written every 15 minutes (one row per
message flow).
v A Message Processing Node Information log entry is written every 15 minutes
(one row per message processing node).
v A Neighbors log entry is written every 15 minutes (one row per neighbor
connection).
v An ACL Entries log entry is written every 15 minutes (one row ACL entry per
topic).
v A Subscriptions log entry is written every 15 minutes (one row per subscription).
v A Retained Publications log entry is written every 15 minutes (one row per
retained publication).
Starting historical data collection

To start collecting historical data for one or more groups of attributes that are
monitored by a particular component, perform the following steps.
1. Click Edit > History Configuration from the Tivoli Enterprise Portal to open
the History Collection Configuration window.
2. Select WebSphere Message Broker from the Select a product menu, to display
a list of WebSphere Message Broker attribute groups.
3. In the Select Attribute Groups list, select one of more attribute groups for
which you want historical data to be collected. Different attribute groups
support different historical data collection options; depending on which groups
you select, some options might be unavailable. Click Show Default Groups to
select all the attribute groups that are included with the component.
Note: Some attribute groups do not support historical data collection. When
you select these attribute groups, the Start Collection and Stop Collection
buttons will be disabled.
4. In the Configuration Controls section select the following options:
a. In the Collection Interval field, select the interval at which historical data is
collected from the agent.
b. In the Collection Location field, indicate whether data is collected at the
TEMA (Tivoli Enterprise Monitoring Agent) or TEMS (Tivoli Enterprise
Monitoring Server). Collecting data at the TEMA minimizes the
performance impact on the TEMS. If you change the Collection Location
option after data collection has begun might result in loss of historical data.
c. In the Warehouse Interval field, select the interval at which data will be
sent to a data warehouse. Select Off if you do not have a data warehouse,
or if you do not want to keep long-term historical records of the attribute
groups’ values.
d. In the Summarization options section, select the types of reports that you
want to be generated from the data that is stored in the data warehouse for
the selected attribute group. This option is available only if data
warehousing is enabled.
e. In the Pruning options section, specify the frequency with which data
should be pruned (deleted) and how long it should be kept. For example, if
you select yearly pruning with data kept for two years, then every year the
data will be checked and any data over two years old will be discarded.
This option is available only if data warehousing is enabled.
5. Click Configure Groups to apply the selected configuration options to the
selected attribute groups.
6. If the groups became unselected in the last step, reselect them in the Attribute
Groups list.
7. Click Start Collection to begin collecting historical data at the specified
interval. If you have configured a large number of attributes groups
simultaneously, it might take several minutes before all agents begin collecting
historical data. After data collection begins, there might also be a slight delay
before collected data becomes available in the Tivoli Enterprise Portal historical
workspaces.
8. Click Close to close the window, or repeat the previous steps to begin
collecting historical data for other components or attribute groups.
Stopping historical data collection

To disable historical data collection for one or more groups of attributes that are
monitored by a particular component, perform the following steps.
1. Click Edit > History Configuration in the Tivoli Enterprise Portal to open the
History Collection Configuration window.
2. Select WebSphere Message Broker in the Select a product menu, to display a
list of WebSphere Message Broker attribute groups.
3. In the Select Attribute Groups list, select the attribute group or groups for
which you want to stop collecting historical data. Click Show Default Groups
to select all the attribute groups that are included with the component.
4. Click Stop Collection to stop historical data collection for the selected attribute
groups.
Chapter 7. Historical data 105

Viewing historical data for a selected time frame
In historical workspaces, you can choose to display only historical data collected
over a particular period of time in which you are interested. To do this, perform
the following steps:
1. Navigate to the historical workspace for which you want to view data from a
particular period of time.
2. Click the Specify Time Span for Query button, located in the top left of each
view in the historical workspace. The Select the Time Span window is
displayed.
3. Select what data you want to be displayed in the table. Available options are:
v Real time. If you select this option, then only the data collected during the
most recent sampling period will be displayed in the table.
v Last X hours. If you select this option, you can choose to display all
historical data going back to a certain date and time. For example, all data
collected over the past 24 hours.
v Custom. If you select this option you can specify the exact period for which
you want historical data to be displayed.
4. If you selected the Last X hours option, enter the time period for which you
want data to be displayed in the field provided, and select the units in which it
is specified (for example, hours or days). You can also specify the following
parameters:
v Use Detailed data. If you select this option then the data from the detailed
data tables will be displayed in the table without summarization. You can
also select the column that you want to be used in determining whether data
falls within the selected period from the Time column drop-down list of
columns containing timestamps.
v Use summarized data. If you select this option then the data from the
summarized data tables will be displayed in the table. This data is
aggregated by the time frame configured in the Historical Collection
Configuration window. If you configured shift times when you installed IBM
Tivoli Monitoring, then you can also select for which shifts and days data is
displayed. See your IBM Tivoli Monitoring documentation for further
information.
5. If you selected the Custom option, you can specify the following parameters:
v Use Detailed data. If you select this option then the data from the detailed
data tables will be displayed in the table without summarization. You can
also select the column that you want to be used in determining wether data
falls within the selected period from a the Time column drop-down list of
columns containing timestamps.
v Use summarized data. If you select this option then the data from the
summarized data tables will be displayed in the table. From the Interval
drop-down list, select the time period over which you want the data to be
aggregated. If you configured shift times when you installed IBM Tivoli
Monitoring, then you can also select for which shifts and days data is
displayed. See your IBM Tivoli Monitoring documentation for further
information.
v In the Start time and End time fields, select the time period for which you
want data to be displayed.
6. To apply the time span to all other views in this workspace that use the same
query, select the Apply to all views associated with this view’s query
checkbox.
7. Click OK to exit the Select the Time Span window. The workspace is refreshed
to reflect the time span you selected.
For more information about this function, see your IBM Tivoli Monitoring
documentation.
Chapter 7. Historical data 107

Appendix A. Support Information
If you have a problem with your IBM software, you want to resolve it quickly. This
section describes the following options for obtaining support for IBM software
products:
v “Searching knowledge bases”
v “Obtaining fixes”
v “Receiving weekly support updates” on page 110
v “Contacting IBM Software Support” on page 110
Searching knowledge bases

You can search the available knowledge bases to determine whether your problem
was already encountered and is already documented.
Searching the information center

IBM provides extensive documentation that can be installed on your local
computer or on an intranet server. You can use the search function of this
information center to query conceptual information, instructions for completing
tasks, and reference information.
Searching the Internet

If you cannot find an answer to your question in the information center, search the
Internet for the latest, most complete information that might help you resolve your
problem.
To search multiple Internet resources for your product, use the Web search topic in
your information center. In the navigation frame, click Troubleshooting and
support > Searching knowledge bases and select Web search. From this topic, you
can search a variety of resources, including the following:
v IBM technotes
v IBM downloads
v IBM Redbooks
v IBM developerWorks
v Forums and newsgroups
v Google
Obtaining fixes
A product fix might be available to resolve your problem. To determine what fixes
are available for your IBM software product, follow these steps:
1. Go to the IBM Software Support Web site at (http://www.ibm.com/software/
support).
2. Click Products A to Z on the options pane at the left side of the Web page.
3. Select the O category to list products with names beginning with O.
4. In the list of Tivoli OMEGAMON XE products, select the Support option next
to for Messaging for Distributed Systems.

5. In the Find downloads and drivers by product section, select [View all
downloads] for a complete list of available updates.
6. Select the name of the update that you want to download and follow the
displayed instructions to download and install.
For more information about the types of fixes that are available, see IBM Software
Support Handbook at http://techsupport.services.ibm.com/guides/
handbook.html.
Receiving weekly support updates

To receive weekly e-mail notifications about fixes and other software support news,
follow these steps:
1. Go to the IBM Software Support Web site at http://www.ibm.com/software/
support.
2. Click My Support in the upper right corner of the page.
3. If you have already registered for My Support, sign in and skip to the next
step. If you have not registered, click register now. Complete the registration
form using your e-mail address as your IBM ID and click Submit.
4. Click Edit Profile.
5. In the Products list, select Software. A second list is displayed.
6. In the second list, select a product segment, for example, Application servers.
A third list is displayed.
7. In the third list, select a product sub-segment, for example, Distributed
Application & Web Servers. A list of applicable products is displayed.
8. Select the products for which you want to receive updates, for example, IBM
HTTP Server and WebSphere Application Server.
9. Click Add products.
10. After selecting all products that are of interest to you, click Subscribe to email
on the Edit profile tab.
11. Select Please send these documents by weekly email.
12. Update your e-mail address as needed.
13. In the Documents list, select Software.
14. Select the types of documents that you want to receive information about.
15. Click Update.
If you experience problems with the My support feature, you can obtain help
in one of the following ways:
Online: Send an e-mail message to erchelp@ca.ibm.com, describing your
problem.
By phone: Call 1-800-IBM-4You (1-800-426-4968).
Contacting IBM Software Support

IBM Software Support provides assistance with product defects.
Before contacting IBM Software Support, your company must have an active IBM
software maintenance contract, and you must be authorized to submit problems to
IBM. The type of software maintenance contract that you need depends on the
type of product you have:
v For IBM distributed software products (including, but not limited to, Tivoli,
Lotus, and Rational products, as well as DB2 and WebSphere products that run
on Windows or UNIX/Linux operating systems), enroll in Passport Advantage
in one of the following ways:
– Online: Go to the Passport Advantage Web page (http://www.lotus.com/
services/passport.nsf/WebDocs/ Passport_Advantage_Home) and click How
to Enroll
– By phone: For the phone number to call in your country, go to the IBM
Software Support Web site at http://techsupport.services.ibm.com/guides/
contacts.html and click the name of your geographic region.
v For customers with Subscription and Support (S & S) contracts, go to the
Software Service Request Web site at https://techsupport.services.ibm.com/ssr/
login.
v For customers with IBMLink, CATIA, Linux, S/390, iSeries, pSeries, zSeries, and
other support agreements, go to the Support Line Web site at
http://www.ibm.com/services/us/index.wss/so/its/a1000030/dt006.
v For IBM eServer software products (including, but not limited to, DB2 and
WebSphere products that run in zSeries, pSeries, and iSeries environments), you
can purchase a software maintenance agreement by working directly with an
IBM sales representative or an IBM Business Partner. For more information
about support for eServer software products, go to the IBM Technical Support
Advantage Web site at http://www.ibm.com/servers/eserver/techsupport.html.
If you are not sure what type of software maintenance contract you need, call
1-800-IBMSERV (1-800-426-7378) in the United States. From other countries, go to
the contacts page of the IBM Software Support Handbook on the Web at
http://techsupport.services.ibm.com/guides/contacts.html and click the name of
your geographic region for phone numbers of people who provide support for
your location.
To contact IBM Software Support, follow these steps:

1. “Determining the business impact” on page 111
2. “Describing problems and gathering information” on page 112
3. “Submitting problems” on page 112
Determining the business impact

When you report a problem to IBM, you are asked to supply a severity level.
Therefore, you need to understand and assess the business impact of the problem
that you are reporting. Use the following criteria:
Severity 1 The problem has a critical business impact. You are unable to use
the program, resulting in a critical impact on operations. This
condition requires an immediate solution.
Severity 2 The problem has a significant business impact. The program is
usable, but it is severely limited.
Severity 3 The problem has some business impact. The program is usable, but
less significant features (not critical to operations) are unavailable.
Severity 4 The problem has minimal business impact. The problem causes
little impact on operations, or a reasonable circumvention to the
problem was implemented.
Appendix A. Support Information 111

Describing problems and gathering information
When explaining a problem to IBM, be as specific as possible. Include all relevant
background information so that IBM Software Support specialists can help you
solve the problem efficiently. To save time, know the answers to these questions:
v What software versions were you running when the problem occurred?
v Do you have logs, traces, and messages that are related to the problem
symptoms? IBM Software Support is likely to ask for this information.
v Can you re-create the problem? If so, what steps were performed to re-create the
problem?
v Did you make any changes to the system? For example, did you make changes
to the hardware, operating system, networking software, and so on.
v Are you currently using a workaround for the problem? If so, be prepared to
explain the workaround when you report the problem.
v What software versions were you running when the problem occurred?
Submitting problems
You can submit your problem to IBM Software Support in one of two ways:
v Online: Click Submit and track problems on the IBM Software Support site at
http://www.ibm.com/software/support/probsub.html. Type your information
into the appropriate problem submission form.
v By phone: For the phone number to call in your country, go to the contacts page
of the IBM Software Support Handbook (http://techsupport.services.ibm.com/
guides/contacts.html) and click the name of your geographic region.
If the problem you submit is for a software defect or for missing or inaccurate
documentation, IBM Software Support creates an Authorized Program Analysis
Report (APAR). The APAR describes the problem in detail. Whenever possible,
IBM Software Support provides a workaround that you can implement until the
APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the
Software Support Web site daily, so that other users who experience the same
problem can benefit from the same resolution.
Appendix B. Disk Space Requirements for Historical Data
Tables
This appendix provides information about disk space requirements for historical
data tables.
Historical data tables

The amount of default space required for a 24 hour period on a monitored system
varies greatly depending on customer configuration. The estimates below are taken
from an example Windows system with the following WebSphere Message Brokers
components installed: configuration manager, user name server, Control Center,
and a single message broker. The broker has two monitored execution groups, four
message flows being monitored configured with two sub-flows, 12 CandleMonitor
nodes, a total of 50 nodes with 150 terminals, and two threads per message flow.
Accounting statistics has been turned on to collect all possible archive data for the
four message flows with the default interval in place at 60 minutes, and the default
agent parameter setting is in place to only collect archive data for history, not
snapshot data.
Note: The historical collection interval must be set to the same value for each of
the five statistics tables (Broker Statistics, Execution Group Statistics,
Message Flow Statistics, Sub-Flow Statistics, and CandleMonitor Node
Statistics). Also, the historical collection interval must be set to the same
value for each of the four accounting tables (Message Flow Accounting,
Thread Accounting, Node Accounting, and Terminal Accounting). The
historical collection interval may be set to be a different value for the two
groups of tables (statistics and accounting). The default for all collection is
15 minutes. IBM Tivoli OMEGAMON XE for Messaging does not support
multiple collection intervals for either the statistics group of tables or the
accounting group of tables.
Table 4. WebSphere Message Brokers Monitoring historical data tables
Estimated space
required per
Attribute history Filename for managed system per
table historical data Default HDC Table 24 hours
ACL Entries Kqitdsea No
Broker Events Kqitbrev Yes 28 kilobytes
Broker Information Kqitbrkr Yes 72 kilobytes
Broker Statistics Kqitstbr Yes 65 kilobytes
CandleMonitor Node Kqitstfn Yes 1,782 kilobytes
Statistics
Components Kqitcomp Yes 234 kilobytes
Execution Group Kqitdfeg No
Information
Execution Group Kqitsteg Yes 176 kilobytes
Statistics
Message Flow Kqitasmf Yes 82 kilobytes
Accounting

Table 4. WebSphere Message Brokers Monitoring historical data tables (continued)
Estimated space
required per
Attribute history Filename for managed system per
table historical data Default HDC Table 24 hours
Message Flow Events Kqitflev Yes 24 kilobytes
Message Flow Kqitdfmf No
Information
Message Flow Kqitstmf Yes 411 kilobytes
Statistics
Message Processing Kqitdffn No
Node Information
Multicast Group Kqitpsms Yes 95 kilobytes
Statistics
Multicast Summary Kqitpsmg Yes 65 kilobytes
Statistics
Multicast Topic Kqitpsmt Yes 137 kilobytes
Statistics
Neighbors Kqitdsen No
Node Accounting Kqitasnd Yes 741 kilobytes
Product Events Kqitprev Yes 17 kilobytes
Publish-subscribe Kqitpsst Yes 78 kilobytes
statistics
Retained Publications Kqitdser No
Sub-Flow Statistics Kqitstsf Yes 252 kilobytes
Subscriptions Kqitdses No
Terminal Accounting Kqitastr Yes 1547 kilobytes
Thread Accounting Kqitasth Yes 115 kilobytes
Total Default Space 5,546 kilobytes
Historical table record sizes

Table 5. WebSphere Message Brokers Monitoring Table Record Sizes
History table Record Size Frequency
ACL Entries 1,012 bytes 1 row per ACL entry per
interval
Broker Events 972 bytes 1 row per broker event
publication (pure event table,
so not affected by interval)
Broker Information 772 bytes 1 row per interval
Broker Statistics 688 bytes 1 row per interval
CandleMonitor Node 1,584 bytes 1 row per CandleMonitor
Statistics node per interval
Components 624 bytes 1 row per WebSphere broker
component installed on
system monitored by agent
per interval
Table 5. WebSphere Message Brokers Monitoring Table Record Sizes (continued)
Execution Group Information 784 bytes 1 row per execution group
per interval
Execution Group Statistics 940 bytes 1 row per monitored
execution group per interval
Message Flow Accounting 872 bytes 1 row per message flow with
IBM’s accounting feature
turned on per IBM’s
accounting interval for
Archive data and, if selected
for history, per 20 seconds
for Snapshot data
Message Flow Events 1,604 bytes 1 row per message flow
event detected (pure event
table, so not affected by
interval)
Message Flow Information 1,040 bytes 1 row per message flow per
interval
Message Flow Statistics 1,096 bytes 1 row per monitored
message flow per interval
Message Processing Node 1,996 bytes 1 row per message
Information processing node per interval
Multicast Group Statistics 1,012 bytes 1 row per interval
Multicast Summary Statistics 692 bytes 1 row per interval
Multicast Topic Statistics 1,460 bytes 1 row per interval
Neighbors 580 bytes 1 row per neighbor to the
broker per interval
Node Accounting 632 bytes 1 row per node per message
flow with IBM’s accounting
feature turned on per IBM’s
accounting interval for
Archive data and, if selected
for history, per 20 seconds
for Snapshot data
Product Events 692 bytes 1 row per product
monitoring event noted by
agent (pure event table, so
not affected by interval)
Publish-Subscribe Statistics 828 bytes 1 row per interval
Retained Publications 1,180 bytes 1 row per retained
publication per interval
Sub-Flow Statistics 1344 bytes 1 row per monitored
sub-flow per interval
Subscriptions 1,784 bytes 1 row per subscription per
interval
Appendix B. Disk Space Requirements for Historical Data Tables 115

Table 5. WebSphere Message Brokers Monitoring Table Record Sizes (continued)
Terminal Accounting 440 bytes 1 row per terminal per node
per message flow with IBM’s
accounting feature turned on
per IBM’s accounting interval
for Archive data and, if
selected for history, per 20
seconds for Snapshot data
Thread Accounting 612 bytes 1 row per thread per
message flow with IBM’s
accounting feature turned on
per IBM’s accounting interval
for Archive data and, if
selected for history, per 20
seconds for Snapshot data
Historical space requirements worksheets

Use the following worksheets to estimate expected file sizes and additional disk
space requirements for your site. A sample calculation is provided for each
historical data collection table.
Table 6. Components (kqitcomp) worksheet
Expected File Size
Interval Record Size Formula per 24 Hours
15 min. 624 bytes (60/15 x 24 x 624 x 4) 234 kilobytes
/ 1024 for 4 installed
components
Table 7. Product Events (kqitprev) worksheet

Expected File Size
N/A 692 bytes (692 x 25) / 1024 for 17 kilobytes
25 product
monitoring events
occurring
Table 8. Broker Information (kqitbrkr) worksheet

Expected File Size
/ 1024 for 1 broker
Table 9. Broker Events (kqitbrev) worksheet
Expected File Size
N/A 972 bytes (972 x 30) / 1024 for 28 kilobytes
30 broker events
occurring
Table 10. Message Flow Events (kqitflev) worksheet

Expected File Size
N/A 1,604 bytes (1604 x 15) / 1024 for 24 kilobytes
15 message flow
events occurring
Table 11. Broker Statistics (kqitstbr) worksheet

Expected File Size
/ 1024 for 1 broker
Table 12. Execution Group Statistics (kqitsteg) worksheet

Expected File Size
/ 1024 for 2
monitored execution
groups
Table 13. Message Flow Statistics (kqitstmf) worksheet

Expected File Size
15 min. 1,096 bytes (60/15 x 24 x 1096 x 411 kilobytes
8) / 1024 for 4
monitored message
flows

Table 14. Sub-Flow Statistics (kqitstsf) worksheet
Expected File Size
2) / 1024 for 2
monitored sub-flows
Table 15. CandleMonitor Node Statistics (kqitstfn) worksheet

Expected File Size
15 min. 1,584 bytes (60/15 x 24 x 1584 x 1.782 kilobytes
12) / 1024 for 12
CandleMonitor nodes
in flows
Table 16. Message Flow Accounting (kqitasmf) worksheet

Expected File Size
1 hour * 872 bytes (60/60 x 24 x 872 x 4) 82 kilobytes
/ 1024 for 4
monitored message
flows
Note: * This is the IBM default interval; even if you set the history interval to less,
the data will only be produced as often as the IBM interval occurs.
Table 17. Thread Accounting (kqitasth) worksheet
Expected File Size
1 hour * 612 bytes (60/60 x 24 x 612 x 8) 115 kilobytes
/ 1024 for 4
monitored message
flows with 2 threads
each
Table 18. Node Accounting (kqitasnd) worksheet
Expected File Size
1 hour * 632 bytes (60/60 x 24 x 632 x 741 kilobytes
50) / 1024 for a total
of 50 nodes in
monitored message
flows
Table 19. Terminal Accounting (kqitastr) worksheet
Expected File Size
1 hour * 440 bytes (60/60 x 24 x 440 x 1,547 kilobytes
150) / 1024 for a
total of 150 terminals
in monitored
message flows
Table 20. Execution Group Information (kqitdfeg) worksheet
Expected File Size
/ 1024 for 2
execution groups
Table 21. Message Flow Information (kqitdfmf) worksheet

Expected File Size
15 min. 1,040 bytes (60/15 x 24 x 1040 x 1,170 kilobytes
12) / 1024 for 12
message flows

Table 22. Message Processing Node Information (kqitdffn) worksheet
Expected File Size
12) / 1024 for 12
message flows
Table 23. Neighbors (kqitdsen) worksheet

Expected File Size
/ 1024 for 2
neighbors to the
broker
Table 24. Subscriptions (kqitdses) worksheet

Expected File Size
20) / 1024 for 20
subscriptions
Table 25. Retained Publications (kqitdser) worksheet

Expected File Size
3) / 1024 for 3
retained publications
Table 26. ACL Entries (kqitdsea) worksheet

Expected File Size
8) / 1024 for 8 ACL
entries
Table 27. Multicast group statistics (kqitpsms) worksheet
Expected File Size
15 min. 1,012 bytes (60/15 x 24 x 1012) / 95 kilobytes
1024
Table 28. Multicast summary statistics (kqitpsmg) worksheet

Expected File Size
15 min. 692 bytes (60/15 x 24 x 692) / 65 kilobytes
1024
Table 29. Multicast topic statistics (kqitpsmt) worksheet

Expected File Size
15 min. 1,460 bytes (60/15 x 24 x 1460) / 137 kilobytes
1024
Table 30. Publish-subscribe statistics (kqitpsst) worksheet

Expected File Size
15 min. 828 bytes (60/15 x 24 x 828) / 78 kilobytes
1024
In the worksheet examples, we used the minimum collection interval unit of 15

minutes. You can create a summary table that provides a representative disk space
storage space figure for all of the history files and archived files for a one-week
time period, if all collection is done at the remote agent managed system. To do so,
multiply the expected file size per 24 hours total times seven. Note that it is not
recommended that historical collection be turned on for those tables not collected
by default. If historical data is desired for those tables, a much longer collection
interval than the default 15 minutes is recommended since the data is not expected
to change often. We recommend that you spread the disk space requirements
among the systems where data collection is performed. A disk space summary
worksheet for WebSphere Message Brokers Monitoring follows:

Historical disk space summary worksheet
Historical Data Table
Size (kilobytes) (24 Subtotal Space
History Table hours) No. of Archives Required (kilobytes)
ACL Entries
Broker Events
Broker Information
Broker Statistics
CandleMonitor Node
Statistics
Components
Execution Group
Information
Execution Group
Statistics
Message Flow
Accounting
Message Flow
Information
Message Flow Events
Message Flow
Statistics
Message Processing
Node Information
Multicast Group
Statistics
Multicast Summary
Statistics
Multicast Topic
Statistics
Neighbors
Node Accounting
Product Events
Publish-Subscribe
Statistics
Retained Publications
Subscriptions
Sub-Flow Statistics
Terminal Accounting
Thread Accounting
Total Disk Space Required
Appendix C. Language codes
Table 31 lists the languages supported by the IBM Tivoli OMEGAMON XE for
Messaging, and their corresponding language codes.
Table 31. Language codes for the supported languages
Language code
English en_US
German de_DE
Spanish es_ES
French fr_FR
Italian it_IT
Japanese ja_JP
Korean ko_KR
Portuguese (Brazilian) pt_BR
Simplified Chinese zh_CN
Traditional Chinese zh_TW

Appendix D. Architecture codes
IBM Tivoli uses abbreviations to represent the various operating system
architectures. The table below shows the most current listing of these
abbreviations.
This information can also be found in the following file on UNIX:

install_dir/registry/archdsc.tbl.
Table 32. Operating system architecture abbreviations
Abbreviation OS Architecture
aix513 AIX v5.1 (32 bit)
citrix Citrix Metaframe
hp10 HP-UX v10.01/10.10
hp102 HP-UX v10.20
hp11 HP-UX v11
hp116 HP-UX v11 (64 bit)
li622 Linux Intel v2.2
li6223 Linux Intel v2.2 (32 bit)
li624 Linux Intel v2.4
li6242 Linux Intel v2.4 GCC 2.9.5 (32 bit)
ls322 Linux zSeries, 2.2 kernel
ls3223 Linux zSeries, v2.2 (32 bit)
ls324 Linux zSeries, v2.4
ls3262 Linux S390 v2.6 GCC 2.9.5 (32 bit)
ls3263 Linux S390 v2.6 (32 bit)
ls3265 Linux S390 v2.6 GCC 2.9.5 (64 bit)

Table 32. Operating system architecture abbreviations (continued)
Abbreviation OS Architecture
ls3266 Linux S390 v2.6 (64 bit)
osf1 Digital UNIX (prior to V5.0)
os390 OS/390® or z/OS
os400 OS/400®
sol24 Solaris v2.4
sol25 Solaris v2.5
sol26 Solaris v2.6
sol273 Solaris v7 (32 bit)
sol603 Solaris v10 Opteron (32 bit)
sol606 Solaris v10 Opteron (64 bit)
tsf50 Tru64 v5.0
unix UNIX
winnt Windows 2000 and Windows 2003 Server
Appendix E. Glossary
A
application support. Provides the Tivoli Enterprise Monitoring Server (TEMS) with component product-specific
information that TEMS uses for component product-provided solutions (such as predefined situations and policies).
archive. To copy one or more files to a storage pool for long-term storage. Archived files can include descriptive
information, and they can be retrieved by archive date, file name, or by description.
agent. Software installed on systems you want to monitor that collects data about an operating system, subsystem,
or application.
aggregation. The process of collecting, interpreting, and sorting data from various locations, such as log files, into a
single file.
alert. A warning message that appears at a console to indicate an event has occurred that may require intervention.
attribute. A system or application element being monitored by the monitoring agent, such as Disk Name and Disk
Read/Writes Per Second. An attribute can also be a field in an ODBC-compliant database.
attribute group. A set of related attributes that can be combined in a data view or a situation. When you open the
view or start the situation, data samples of the selected attributes are retrieved. Each type of monitoring agent has a
set of attribute groups.
B
browser client. The software installed with the Tivoli Enterprise Portal Server system that is downloaded to your
computer when you start Tivoli Enterprise Portal browser mode.
C
chart. A graphical view of data returned from a monitoring agent. A data point is plotted for each attribute chosen
and, for bar and pie charts, a data series for each row. Types of charts include pie, bar, plot and gauge.
client/server. An architecture in which the client (personal computer or workstation) is the requesting machine and
the server is the supplying machine. Servers can be microcomputers, minicomputers or mainframes. The client
provides the user interface and may perform application processing. A database server maintains the databases and
processes requests from the client to extract data from or update the database. An application server provides
additional business processing for the clients.
configuration. (1) The manner in which the hardware and software of an information processing system are
organized and interconnected. (2) The machines, devices, and programs that make up a system, subsystem, or
network.
Customer Information Control System (CICS®). An IBM licensed program that provides online
transaction-processing services and management for business applications.
D
data mart. A subset of a data warehouse that contains data that is tailored and optimized for the specific reporting
needs of a department or team. A data mart can be a subset of a warehouse for an entire organization, such as data
contained in online analytical processing (OLAP) tools.
data warehouse. (1) A subject-oriented nonvolatile collection of data that is used to support strategic decision
making. The warehouse is the central point of data integration for business intelligence. It is the source of data for

data marts within an enterprise and delivers a common view of enterprise data. (2) A central repository for all or
significant parts of the data that an organization’s business systems collect. Also known as an information warehouse.
See also data mart.
device. Any non-client, non-server part of a network managed by Tivoli software, including, but not limited to,
Palm devices, handheld PCs, cable set-top boxes, and other pervasive devices.
deploy. To place files or install software into an operational environment.
DLL. Dynamic Link Library is a composite of one or more executable objects, bound together by a linking
procedure, and loaded at run time.
domain. A logical grouping of resources in a network for the purpose of common management and administration.
DSN. Data Source Name. The name is stored in the database server and enables you to retrieve information from
the database through ODBC. The DSN includes such information as the database name, database driver, user ID and
password.
E
encryption. In computer security, the process of transforming data into an unintelligible form in such a way that the
original data either cannot be obtained or can be obtained only by using a decryption process.
event. An action or some occurrence, such as running out of memory or completing a transaction, that can be
detected by a situation. The event causes the situation to become true and an alert to be issued.
event filter. (1) In a Tivoli environment, rules that determine which events are sent from an event adapter or
displayed on an event console. An event filter is also used to determine the events that a specific correlation rule will
apply to. (2) A logical expression of the criteria that determines which events are forwarded to the application
program that registers the event filter with the event sieve agent. (3) The criteria that an event must meet before a
rule action is executed.
event group. A set of events that meet certain criteria defined by event group filters, which include constraints that
are expressions that define the filter conditions. Event console operators can monitor event groups that are relevant to
their specific areas of responsibility. See also event filter.
event response. A preconfigured action that is triggered when an event is generated. The administrator can
configure one or more event responses to specific event types. Examples of event responses include logging the
event, notifying an individual or group by e-mail that the event has occurred, sending the event to an SNMP
application, and initiating a program or script.
F
Filter Criteria. Limits the amount of information returned to the data view in response to a query. You can apply a
pre-filter to the query to collect only certain data, or apply a post-filter to the view properties to show only certain
data from what was collected.
firewall. A functional unit that protects and controls the connection of one network to other networks. The firewall
(a) prevents unwanted or unauthorized communication traffic from entering the protected network and (b) allows
only selected communication traffic to leave the protected network.
H
host. A computer that is connected to a network (such as the Internet or an SNA network) and provides an access
point to that network. Also, depending on the environment, the host may provide centralized control of the network.
The host can be a client, a server, or both a client and a server simultaneously.
hub. 1) A central host system that collects the status of situations running on your systems. 2) The monitoring
server that has been elected to act as the focal point to which all portal servers and remote monitoring servers in this
monitored network connect. A remote monitoring server passes its collected data to the hub to be made available to
clients, creating an enterprise-wide view.
Hub TEMS. A master server that serves as the focal point for managing your environment. The hub TEMS may
receive data from agents running on the same or remote systems or other TEMSes running as remote servers in a
hierarchical configuration.
I
IBM Tivoli Monitoring. A client-server implementation comprising a Tivoli Enterprise Monitoring Server, an
application server known as theTivoli Enterprise Portal Server, the Tivoli Enterprise Portal client, and Tivoli
Enterprise Monitoring Agents that collect and distribute data to a monitoring server.
interprocess communication (IPC). (1) The process by which programs communicate data to each other and
synchronize their activities. Semaphores, signals, and internal message queues are common methods of interprocess
communication. (2) A mechanism of an operating system that allows processes to communicate with each other
within the same computer or over a network.
interval. The number of seconds that have elapsed between one sample and the next. A sample is the data that the
product collects for the server.
M
managed system. A particular operating system, subsystem, or application in your enterprise where a Tivoli
Enterprise Monitoring agent is installed and running.
managed system list. A named list of managed systems of the same type. You can see and select a managed system
list when you distribute a situation or policy, edit a query specification, or assign managed systems to Navigator
items in custom Navigator views. Example: A list of Linux managed systems for a geographic region named
LINUX_LONDON.
middleware. Software that enables the exchange of information between components in a distributed computing
environment. IBM WebSphere MQ is an example of middleware.
migration. When installing a new version or release of a program to replace an earlier version or release, move the
useful data of the earlier version or release from the old location to the new location
monitor interval. A specified time, scalable to seconds, minutes, hours, or days, for how often the monitoring server
checks to see if a situation has become true.
mount point. A logical drive through which volumes are accessed in a sequential access device class. For removable
media device types, such as cartridges, a mount point is a logical drive associated with a physical drive. For the file
device type, a mount point is a logical drive associated with an I/O stream. The number of mount points for a
device class is defined by the value of the mount limit attribute for that device class.
N
NAT. Network Address Translation is a scheme used by LANs to establish an internal and external set of IP
addresses. Internal IP addresses are kept private and must be translated to and from the external address(es) for
outbound and inbound communications. NAT is often used in firewall configurations.
Navigator. The left pane of the Tivoli Enterprise Portal window. The Navigator Physical view shows your network
enterprise as a physical hierarchy of systems grouped by platform. You can also create other views to create logical
hierarchies grouped as you specify, such as by department or function.
O
ODBC. Open DataBase Connectivity, a standard for accessing different database systems. The Query editor enables
you to write custom SQL queries for creating views that retrieve data from ODBC-compliant databases.
Appendix E. Glossary 129

P
platform. The operating system the managed system is using, such as OS/390 and Linux. The Navigator physical
mapping places the platform level under the enterprise level.
policy. A set of automated system processes that can perform actions, schedule work for users, or automate manual
tasks. It comprises a series of automated steps, called activities, whose order of execution you control.
product code. The three-letter code used by IBM Tivoli Monitoring to identify the product component. For example,
the product code for IBM Tivoli Monitoring for WebSphere Application Server is KWE.
Properties editor. A multi-tabbed window for specifying the properties of the individual views that make up a
workspace, as well as the general workspace properties.
Q
query. In a Tivoli environment, a combination of statements that are used to search a repository for systems that
meet certain criteria. The query object is created within a query library.
R
registry. The data store that contains access and configuration information for users, systems, and software.
resource. A hardware, software, or data entity that is managed by Tivoli software.
S
sample. The data that the monitoring agent collects for the server instance. The interval is the time between data
samplings.
sampled event. Sampled events happen when a situation becomes true. Situations sample data at regular intervals.
When the situation is true, it opens an event, which gets closed automatically when the situation goes back to false
(or you can close it manually).
scalability. The ability of a distributed system to expand in size without making changes to the system structure,
applications, or the way users deal with the system.
schema. The set of statements, expressed in a data definition language, that completely describe the structure of a
database. In a relational database, the schema defines the tables, the fields in each table, and the relationships
between fields and tables.
situation. A set of conditions that, when met, creates an event. A condition consists of an attribute, an operator such
as greater than or equal to, and a value. It can be read as, “If - system condition - compared to - value - is true”. An
example of a situation is: IF - CPU usage - > - 90% - TRUE. The expression “CPU usage > 90%” is the situation
condition.
SNMP. Simple Network Management Protocol. A software protocol to facilitate communications between different
types of networks. IBM Tivoli Monitoring uses SNMP messaging to discover the devices on your network and their
availability
SOAP. Single Object Access Protocol is an XML-based protocol that enables applications to converse with each other
and exchange data over the Internet, regardless of platform.
SQL. Structured Query Language is a programming language for getting information from and updating a database.
The Query editor enables you to write SQL queries to ODBC data sources for retrieval and display in table and chart
views.
state. The severity of the situation event: critical, warning, or informational. Indicated by a colored event indicator,
state is set in the Situation editor and can be different for different Navigator items.
status. The true or false condition of a situation.
summarization. The process of aggregating events and then submitting the set of events with a much smaller
number of summary events.
T
TCP/IP. Transmission Control Protocol/Internet Protocol. An open, portable communications protocol.
threshold. A customizable value for defining the acceptable tolerance limits (maximum, minimum, or reference
limit) for an application resource or system resource. When the measured value of the resource is greater than the
maximum value, less than the minimum value, or equal to the reference value, an exception is raised.
Tivoli Enterprise Monitoring Server (TEMS). This is the host data management component for IBM Tivoli
Monitoring.
Tivoli Enterprise Portal Server (TEPS). The server you log on to and connect to from the Tivoli Enterprise Portal
client. The portal server connects to the hub monitoring server. It enables retrieval, manipulation and analysis of data
from monitoring agents.
Tivoli Monitoring Services. An integrated, layered architecture consisting of data access, communication, and
presentation components that enable cross-platform operation and integration of data for systems management
applications.
trend. A series of related measurements that indicates a defined direction or a predictable future result.
U
UDB. IBM’s DB2® Universal DataBase is a relational database management system. A UDB database is installed on
the same system as the Tivoli Enterprise Portal Server and stores queries, customized workspaces, user IDs, and
custom Navigator views.
user profile. In computer security, a description of a user that includes such information as user ID, user name,
password, access authority, and other attributes that are obtained when the user logs on.
V
view. A logical table that consists of data generated by a query. A view is based on an underlying set of base tables,
and the data in a view is determined by a SELECT statement that is run on the base tables.
W
WebSphere InterChange Server Monitoring. A component product of IBM Tivoli OMEGAMON XE for Messaging
that lets you easily manage your IBM WebSphere InterChange Servers, their components, and the WebSphere
business integration systems that they support.
WebSphere Message Broker Monitoring. A component product of IBM Tivoli OMEGAMON XE for Messaging that
lets you easily collect and analyze data from any of the Message Broker products for the WebSphere Business
Integration package in order to help with the development, testing, management and troubleshooting of message
flows
WebSphere MQ Configuration. A component product of IBM Tivoli OMEGAMON XE for Messaging that helps
you simplify the time-consuming and resource-intensive tasks of defining and managing a WebSphere MQ
configuration.
WebSphere MQ Monitoring. A component product of IBM Tivoli OMEGAMON XE for Messaging that lets you
easily collect and analyze WebSphere MQ-specific data for all the remote and local queue managers from a single
vantage point.
workflow. The sequence of activities performed in accordance with the business processes of an enterprise.
Appendix E. Glossary 131

workspace. The viewing area of the Tivoli Enterprise Portal window, excluding the Navigator. Each workspace
comprises one or more views. Every Navigator item has its own default workspace and may have multiple
workspaces.
Z
z/OS. IBM’s operating system for mainframe computers that has the ability to manage large amounts of memory,
direct access storage, and data.
Appendix F. Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation

Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS

PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain

transactions, therefore, this statement might not apply to you.
This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, TX 78758 U.S.A.
Such information may be available, subject to appropriate terms and conditions,

including in some cases payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurement may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM’s future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBM’s suggested retail prices, are current and are subject
to change without notice. Dealer prices may vary.
This information is for planning purposes only. The information herein is subject to
change before the products described become available.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which

illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM for the purposes of developing, using, marketing, or distributing application
programs conforming to IBM‘s application programming interfaces.
Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights
reserved.
If you are viewing this information in softcopy form, the photographs and color
illustrations might not display.
Trademarks
IBM, the IBM logo, AIX, AS/400, Candle, Candle Command Center, Tivoli
Enterprise Management Server, Candle Management Workstation, CandleNet,
CandleNet Command Center, Tivoli Enterprise Portal, CandleLight, CICS, DB2,
developerWorks, eServer, IBMLink, IMS, Informix, iSeries, Lotus, MQIntegrator,
MVS, OMEGAMON, Tivoli Enterprise Management Agent, OS/2, OS/400,
Passport Advantage, pSeries, Rational, Redbooks, S/390, Tivoli, the Tivoli logo,
Tivoli Enterprise Console, TME, VTAM, RACF, WebSphere, z/OS, and zSeries are
trademarks or registered trademarks of International Business Machines
Corporation in the United States, other countries, or both.
Intel, Intel Inside (logos), MMX, Celeron, Intel Centrino, Intel Xeon, Itanium,
Pentium and Pentium III Xeon are trademarks or registered trademarks of Intel
Corporation or its subsidiaries in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or

registered trademarks of Sun Microsystems, Inc. in the United
States, other countries, or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or

both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Appendix F. Notices 135

Other company, product, and service names may be trademarks or service marks
of others.
Index
A capacity planning for brokers 43
collectNodeData attribute of MonitorBroker 18
ACL Entries workspace 62 collectQueueTime attribute 28
activateNode attribute 29 commands
agent parameter descriptions 11, 19 See Take Action commands
See individual parameter names commandTimeoutInterval attribute of KqiAgent 13
agent parameter file componentDirectory attribute of MonitorBroker 17
location 7 Components History workspace 77
sample 10 Components workspace 76
setting parameters 9, 10 ConnectQueueManager parameter 18
syntax of statements 9 ConnectQueueManager tag 18
Agent Status workspace 63 ConnectQueueManager tag attributes
agentId attribute of KqiAgent 11 name 18
alerts 47 replyQueueModel 19
alias attribute replyQueueName 18
of MonitorBroker 16 customer support
archive accounting statistics collection interval 58 See Software Support
Archive Message Flow Accounting workspace 63
Archive Node Accounting workspace 65
Archive Terminal Accounting workspace 67
Archive Thread Accounting workspace 68 D
attributes, more information provided in online help 57 debugging a message flow 40
automation 3 defaultCollectNodeData attribute of KqiAgent 15
defaultFlowEventInterval attribute of KqiAgent 12
defaultHistoricalAccountingType attribute of KqiAgent 14
B defaultReplyQueueModel attribute of KqiAgent 12
defaultReplyQueueName attribute of KqiAgent 12
Broker Events History workspace 70, 100 defaultRetainBrokerEvents attribute of KqiAgent 11
Broker Events workspace 69 defaultRetainFlowEvents attribute of KqiAgent 11
Broker Information History workspace 71 defaultRetainRecentArchiveSamples attribute of KqiAgent 15
Broker Information workspace 70 defaultRetainRecentPubSubSamples attribute of KqiAgent 15
Broker Statistics History workspace 73 defaultRetainRecentSnapshotSamples attribute of
Broker Statistics workspace 72 KqiAgent 14
Broker Status workspace 73 defaultStatisticInterval attribute of KqiAgent 12
Broker Summary workspace 74 defaultTakeActionAuthUsers attribute of KqiAgent 13
brokers discoveryInterval attribute of KqiAgent 12
capacity planning 43
configuration, verifying 41
performance 44
starting automatically 42 E
eventMessage attribute 28
Execution Group Information workspace 77
C Execution Group Statistics History workspace
Execution Group Statistics workspace 78
79
CandleMonitor node
activating 24
and input statistics 30
and message flow events 33 F
and subflows 31, 33 flowEventInterval attribute of MonitorBroker 16
attributes 27, 30
configuration file 35
overview 23 H
positioning 34 Historical Archive Node Accounting workspace 67
reconfiguring 34, 36 Historical Archive Terminal Accounting workspace 68
CandleMonitor node configuration file 35 Historical Archive Thread Accounting workspace 69
CandleMonitor node configuration variables 35, 36 historical data collection 6
KQIActivateNode 36 historical predefined situations
KQIActivateNodeForBROKERNAME 36 active upon product installation 103
KQIMemorySize 35 inactive upon product installation 104
KQINodeTrace 36 Historical Snapshot Message Flow Accounting workspace 94
KQITempDirectory 35 Historical Snapshot Node Accounting workspace 96
CandleMonitor Node Statistics History workspace 76 Historical Snapshot Terminal Accounting workspace 97
CandleMonitor Node Statistics workspace 75

Historical Snapshot Thread Accounting workspace 98 Message Flow Events workspace 80
historicalAccountingType attribute of MonitorBroker 17 Message Flow Information workspace 81
holdTimeForQuery attribute of KqiAgent 14 Message Flow Statistics History workspace 83
Message Flow Statistics workspace 82
Message Processing Node Attributes workspace 83
I Message Processing Node Information workspace 84
Message Processing Nodes with Queue workspace 85
IBM Tivoli Monitoring 2, 3
MonitorBroker parameter 15
information centers, searching to find software problem
MonitorBroker tag 15
resolution 109
MonitorBroker tag attributes
alias 16
collectNodeData 18
K componentDirectory 17
knowledge bases, searching to find software problem flowEventInterval 16
resolution 109 historicalAccountingType 17
kqi.xml file (or KQIXML member) 7 name 16
adding parameters 10 retainBrokerEvents 16
changing parameters 9 retainFlowEvents 17
default contents 8 retainRecentArchiveSamples 18
KQIActivateNode 36 retainRecentPubSubSamples 17
KQIActivateNodeForBROKERNAME 36 retainRecentSnapshotSamples 18
KqiAgent attributes statisticInterval 16
defaultFlowEventInterval 12 takeActionAuthUsers 17
defaultRetainRecentSnapshotSamples 14 monitoring input statistics 30
KqiAgent tag 11 monitoring subflows 31, 33
KqiAgent tag attributes Multicast Group Statistics workspace 86
agentId 11 Multicast Group Statistics workspace and Multicast Topic
commandTimeoutInterval 13 Statistics workspace 88
defaultCollectNodeData 15 Multicast Summary Statistics workspace 87
defaultHistoricalAccountingType 14 Multicast Topic Statistics workspace 87, 88
defaultReplyQueueModel 12
defaultReplyQueueName 12
defaultRetainBrokerEvents 11
defaultRetainFlowEvents 11
N
name attribute
defaultRetainRecentArchiveSamples 15
of ConnectQueueManager 18
defaultRetainRecentPubSubSamples 15
of MonitorBroker 16
defaultStatisticInterval 12
names, for subflows 33
defaultTakeActionAuthUsers 13
Neighbor Broker Information workspace 89
discoveryInterval 12
Neighbors workspace 89
holdTimeForQuery 14
maximumAgentCollectionThreads 13
maximumCommandRetryCount 13
retainProductEvents 11 O
version 11 OMEGAMON DE feature package 3
kqicm500.exe file 24
kqicm600.exe file 24
kqicm600.tar file 24
KQIMemorySize 35
P
parameter descriptions 11, 19
KQINodeTrace 36
See individual parameter names
kqismpl.xml sample agent parameter file 10
parameter file, agent
KQITempDirectory 35
location 7
KQIXML member 7
syntax of statements 9
parameters
ConnectQueueManager 18
M KqiAgent 11
maximumAgentCollectionThreads attribute of KqiAgent 13 MonitorBroker 15
maximumCommandRetryCount attribute of KqiAgent 13 performance considerations 19
Message Brokers Toolkit 24 Policy Management 3
message delivery failure 40 predefined situations
message flow historical 103
debugging 40 that raise alerts 47
determining when failed 41 Product Events History workspace 90
ensuring adequate response time 43 Product Events workspace 89
events 33 publications
starting and stopping at periodic intervals 44 related x
stopping when output queue is full 42 Publish-Subscribe Statistics workspace 90
Message Flow Events History workspace 80 Put/Get Message performance monitoring 39
Q T
QI Change Broker command 51 tag
QI Change Flow Stats 52 See parameter
QI Change Properties command 52 Take Action commands 48
QI Change Trace Broker command 51 QI Change Broker 51
QI Change Trace Component command 49 QI Change Flow Stats 52
QI Create User Statistics 53 QI Change Properties 52
QI Delete Retained Publication command 53 QI Change Trace Broker 51
QI Destroy User Statistics 54 QI Change Trace Component 49
QI Reset Statistics 54 QI Create User Statistics 53
QI Sample User Statistics 53 QI Delete Retained Publication 53
QI Start Broker command 50 QI Destroy User Statistics 54
QI Start Component command 48 QI Reset Statistics 54
QI Start Message Flow(s) command 52 QI Sample User Statistics 53
QI Stop Broker and its Queue Manager command 51 QI Start Broker 50
QI Stop Broker command 50 QI Start Component 48
QI Stop Component and its Queue Manager command 49 QI Start Message Flow(s) 52
QI Stop Component command 49 QI Stop Broker 50
QI Stop Message Flow(s) command 53 QI Stop Broker and its Queue Manager 51
queue time statistics, how calculated 30 QI Stop Component 49
QI Stop Component and its Queue Manager 49
QI Stop Message Flow(s) 53
R using in situations 54
takeActionAuthUsers attribute
Recent Archive Node Accounting workspace 67
of MonitorBroker 17
Recent Archive Terminal Accounting workspace 68
takeActionAuthUsers attribute of MonitorBroker 17
Recent Archive Thread Accounting workspace 69
Tivoli Enterprise Monitoring Server 2
Recent Snapshot Message Flow Accounting workspace 94
Tivoli Enterprise Portal 2
Recent Snapshot Node Accounting workspace 96
Tivoli Enterprise Portal Server 2
Recent Snapshot Terminal Accounting workspace 97
trace active, effect on broker performance 44
Recent Snapshot Thread Accounting workspace 98
trace data, collecting for a broker on unavailable system 42
replyQueueModel attribute of ConnectQueueManager 19
type attribute 27
replyQueueName attribute of ConnectQueueManager 18
Type I subflows 31
retainBrokerEvents attribute of MonitorBroker 16
Type II subflows 31
Retained Publications workspace 92
retainFlowEvents attribute of MonitorBroker 17
retainProductEvents attribute of KqiAgent 11
retainRecentArchiveSamples attribute of MonitorBroker 18 U
retainRecentPubSubSamples attribute of MonitorBroker 17 usage scenarios 39, 45
retainRecentSnapshotSamples attribute of MonitorBroker 18 user statistics workspaces 57
S V
scenarios for usage 39, 45 verifying the broker/Message Brokers Toolkit
security failure on a subscription, handling 45 configuration 41
snapshot accounting statistics collection interval 58 version attribute of KqiAgent 11
Snapshot Message Flow Accounting workspace 93
Snapshot Node Accounting workspace 95
Snapshot Terminal Accounting workspace 96
Snapshot Thread Accounting workspace 97
W
Workflow editor 3
Software Support
workspace 89, 92
contacting 110
workspaces
starting a broker automatically 42
ACL entries 62
statisticInterval attribute of MonitorBroker 16
Agent Status 63
stopping a message flow with a full output queue 42
Archive Message Flow Accounting 63
Sub-Flow Statistics History workspace 100
Archive Node Accounting 65
Sub-Flow Statistics Workspace 99
Archive Terminal Accounting 67
subflow names 33
Archive Thread Accounting 68
subFlowName attribute 28
Broker Events 69
subflows 31, 33
Broker Events History 70, 100
definition 31
Broker Information 70
names 33
Broker Information History 71
subscriptions
Broker Statistics 72
handling security failure 45
Broker Statistics History 73
verifying 45
Broker Status 73
Subscriptions workspace 100
Broker Summary 74
Index 139
workspaces (continued)
CandleMonitor Node Statistics 75
CandleMonitor Node Statistics History 76
Components 76
Components History 77
Execution Group Information 77
Execution Group Statistics 78
Execution Group Statistics History 79
Historical Archive Node Accounting 67
Historical Archive Terminal Accounting 68
Historical Snapshot Message Flow Accounting 94
Historical Snapshot Node Accounting 96
Historical Snapshot Terminal Accounting 97
Historical Snapshot Thread Accounting 98
Historical Thread Accounting 69
Message Flow Events 80
Message Flow Events History 80
Message Flow Information 81
Message Flow Statistics 82
Message Flow Statistics History 83
Message Processing Node Attributes 83
Message Processing Node Information 84
Message Processing Nodes with Queue 85
Multicast Group Statistics 86
Multicast Group Statistics and Multicast Topic
Statistics 88
Multicast Summary Statistics 87
Multicast Topic Statistics 87, 88, 89
Neighbor Broker Information 89
Neighbors 89
overview of 4, 57
Product Events 89
Product Events History 90
Publish-Subscribe Statistics 90
Recent Archive Node Accounting 67
Recent Archive Terminal Accounting 68
Recent Archive Thread Accounting 69
Recent Publish-Subscribe Statistics and Historical
Publish-Subscribe Statistics 92
Recent Snapshot Message Flow Accounting 94
Recent Snapshot Node Accounting 96
Recent Snapshot Terminal Accounting 97
Recent Snapshot Thread Accounting 98
Retained Publications 92
Snapshot Message Flow Accounting 93
Snapshot Node Accounting 95
Snapshot Terminal Accounting 96
Snapshot Thread Accounting 97
Sub-Flow Statistics 99
Sub-Flow Statistics History 100
Subscriptions 100
user statistics 57

Printed in USA
SC23-7954-00

Kqiuserguide 601

Загружено:

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

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

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

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

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

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

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

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

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

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

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

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

Kqiuserguide 601

Загружено:

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

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

Tivoli IBM Tivoli OMEGAMON XE for Messaging

WebSphere Message Broker Monitoring User’s Guide

WebSphere Message Broker Monitoring User’s Guide

Second Edition (August 2007)

© Copyright IBM Corp. 2005,2006 iii

© Copyright IBM Corp. 2005,2006 v

© Copyright IBM Corp. 2005,2006 vii

About This document

Who should read this document

The installation and configuration instructions in the following documents are a

© Copyright IBM Corp. 2005,2006 ix

IBM Tivoli OMEGAMON XE for Messaging library

The following documents also provide useful information:

Accessing publications online

In other countries, contact your software account representative to order Tivoli

Tivoli technical training

Panels and figures

Note: In ordinary text, variable names appear in italics, regardless of operating

YES | NO In this example, you can specify YES or NO.

APPLDEST DEST [ALTDEST] In this example, DEST is a required

COPY infile outfile - [COMPRESS={YES | NO}] In this example, the

© Copyright IBM Corp. 2005,2006 xiii

What WebSphere Message Broker Monitoring does

How WebSphere Message Broker Monitoring works

© Copyright IBM Corp. 2005,2006 1

IBM Tivoli Monitoring

Tivoli Enterprise Monitoring Server

Tivoli Enterprise Portal Server

Figure 1. Agent–Server–Client Architecture

Tivoli Enterprise Monitoring Server

Tivoli Enterprise Portal

Configuration agents can create and configure objects. The WebSphere MQ

IBM Tivoli OMEGAMON DE

IBM Tivoli OMEGAMON DE extends the capabilities of IBM Tivoli OMEGAMON

Chapter 1. WebSphere Message Broker Monitoring 3

Predefined workspaces and views

The predefined WebSphere Message Broker Monitoring workspaces provide the

For information about predefined workspaces included with WebSphere Message

Creating a workspace using a predefined workspace as a

Predefined monitoring situations

WebSphere Message Broker Monitoring provides a set of predefined situations

WebSphere Message Broker Monitoring monitors 22 groups of attributes. You can

Take Action commands

Chapter 1. WebSphere Message Broker Monitoring 5

For information on the commands provided with WebSphere Message Broker

Historical data collection

The parameter file

On distributed platforms such as Windows and UNIX, this parameter file is

Names and locations of agent parameter files

Agents parameter files on Z/OS

Agent parameter files on UNIX and Linux

The agent parameter file is located the <install_dir>/config, where <install_dir> is

The agent parameter file on Windows

© Copyright IBM Corp. 2005,2006 7

The agent parameter file is located in the directory <install_dir>\TMAITM6, where

The default agent parameter file

The default file on UNIX, Linux, and Windows

Figure 2. Default kqi.xml file on Windows, UNIX, and Linux

The default file on z/OS

Figure 3. Default KQIXML file on z/OS

Agent parameter file syntax

Setting Agent Parameters