User’s GuideOMEGAMON® XE for
WebSphere Application Server
Version 130
GC32-9194-00
August 2004
Candle Corporation100 North Sepulveda Blvd.
El Segundo, California 90245
2 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Registered trademarks and service marks of Candle Corporation: AF/OPERATOR, AF/REMOTE, Availability Command Center, Candle, Candle CIRCUIT, Candle Command Center, Candle Direct logo, Candle eDelivery, Candle Electronic Customer Support, Candle logo, Candle Management Server, Candle Management Workstation, CandleLight, CandleNet, CandleNet Command Center, CandleNet eBusiness Platform, CandleNet Portal, CL/CONFERENCE, CL/SUPERSESSION, CommandWatch, CT, CT/Data Server, CT/DS, DELTAMON, DEXAN, eBA, eBA*ServiceMonitor, eBA*ServiceNetwork, eBusiness at the speed of light, eBusiness Assurance, eBusiness Institute, ELX, EPILOG, ESRA, ETEWatch, IntelliWatch, IntelliWatch Pinnacle, MQSecure, MQView, OMEGACENTER, OMEGAMON, OMEGAMON II, OMEGAMON Monitoring Agent, OMEGAMON Monitoring Agents, OMEGAVIEW, OMEGAVIEW II, PQEdit, Response Time Network, Roma, SitePulse, Solutions for Networked Applications, Solutions for Networked Businesses, TMA2000, Transplex, and Volcano.Trademarks and service marks of Candle Corporation: AF/Advanced Notification, AF/PERFORMER, Alert Adapter, Alert Adapter Plus, Alert Emitter, AMS, Amsys, AutoBridge, AUTOMATED FACILITIES, Availability Management Systems, Business Services Composer, Candle Alert, Candle Business Partner Logo, Candle Command Center/SentinelManager, Candle CommandPro, Candle eSupport, Candle Insight, Candle InterFlow, Candle Managing what matters most, Candle Service Suite, Candle Technologies, CandleNet, CandleNet 2000, CandleNet Conversion, CandleNet eBP, CandleNet eBP Access for S.W.I.F.T., CandleNet eBP Administrator, CandleNet eBP Broker Access for Mercator or MQSI, CandleNet eBP Configuration, CandleNet eBP Connector, CandleNet eBP File Transfer, CandleNet eBP Host Connect, CandleNet eBP Object Access, CandleNet eBP Object Browser, CandleNet eBP Secure Access, CandleNet eBP Service Directory, CandleNet eBP Universal Connector, CandleNet eBP Workflow Access, CandleNet eBusiness Assurance, CandleNet eBusiness Exchange, CandleNet eBusiness Platform Administrator, CandleNet eBusiness Platform Connector, CandleNet eBusiness Platform Connectors, CandleNet eBusiness Platform Powered by Roma Technology, CandleNet eBusiness Platform Service Directory, Candle Vision, CCC, CCP, CCR2, CEBA, CECS, CICAT, CL/ENGINE, CL/GATEWAY, CL/TECHNOLOGY, CMS, CMW, Command & Control, Connect-Notes, Connect-Two, CSA ANALYZER, CT/ALS, CT/Application Logic Services, CT/DCS, CT/Distributed Computing Services, CT/Engine, CT/Implementation Services, CT/IX, CT/Workbench, CT/Workstation Server, CT/WS, !DB Logo, !DB/DASD, !DB/EXPLAIN, !DB/MIGRATOR, !DB/QUICKCHANGE, !DB/QUICKCOMPARE, !DB/SMU, !DB/Tools, !DB/WORKBENCH, Design Network, e2e, eBA*SE, eBAA, eBAAuditor, eBAN, eBANetwork, eBAAPractice, eBP, eBusiness Assurance Network, eBusiness at the speed of light, eBusiness at the speed of light logo, eBusiness Exchange, eBX, End-to-End, eNotification, ENTERPRISE, Enterprise Candle Command Center, Enterprise Candle Management Workstation, Enterprise Reporter Plus, ER+, ERPNet, ETEWatch Customizer, HostBridge, InterFlow, Candle InterFlow, Lava Console, Managing what matters most, MessageMate, Messaging Mastered, Millennium Management Blueprint, MMNA, MQADMIN, MQEdit, MQEXPERT, MQMON, NBX, NC4, NetGlue, NetGlue Extra, NetMirror, NetScheduler, New Times, New Team, New Readiness, OMA, OMC Gateway, OMC Status Manager, OMEGACENTER Bridge, OMEGACENTER Gateway, OMEGACENTER Status Manager, OMEGAMON/e, OMEGAMON Management Center, OSM, PathWAI, PC COMPANION, Performance Pac, Powered by Roma Technology, PowerQ, PQConfiguration, PQScope, Roma Application Manager, Roma Broker, Roma BSP, Roma Connector, Roma Developer, Roma FS/A, Roma FS/Access, RomaNet, Roma Network, Roma Object Access, Roma Secure, Roma WF/Access, Roma Workflow Access, RTA, RTN, SentinelManager, Somerset, Somerset Systems, Status Monitor, The Millennium Alliance, The Millennium Alliance logo, The Millennium Management Network Alliance, Tracer, Unified Directory Services, WayPoint, and ZCopy.Trademarks and registered trademarks of other companies: AIX, DB2, MQSeries and WebSphere are registered trademarks of International Business Machines Corporation. Citrix, WinFrame, and ICA are registered trademarks of Citrix Systems, Inc. Multi-Win and MetaFrame are trademarks of Citrix Systems, Inc. SAP is a registered trademark and R/3 is a trademark of SAP AG. UNIX is a registered trademark in the U.S. and other countries, licensed exclusively through X/Open Company Ltd. HP-UX is a trademark of Hewlett-Packard Company. SunOS is a trademark of Sun Microsystems, Inc. All other company and product names used herein may be trademarks or registered trademarks of their respective owners.
Copyright © 11 August 2004, Candle Corporation, a California corporation. All rights reserved. International rights secured.
Threaded Environment for AS/400, Patent No. 5,504,898; Data Server with Data Probes Employing Predicate Tests in Rule Statements (Event Driven Sampling), Patent No. 5,615,359; MVS/ESA Message Transport System Using the XCF Coupling Facility, Patent No. 5,754,856; Intelligent Remote Agent for Computer Performance Monitoring, Patent No. 5,781,703; Data Server with Event Driven Sampling, Patent No. 5,809,238; Threaded Environment for Computer Systems Without Native Threading Support, Patent No. 5,835,763; Object Procedure Messaging Facility, Patent No. 5,848,234; End-to-End Response Time Measurement for Computer Programs, Patent No. 5,991,705; Communications on a Network, Patent Pending; Improved Message Queuing Based Network Computing Architecture, Patent Pending; User Interface for System Management Applications, Patent Pending.
NOTICE: This documentation is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions set forth in the applicable license agreement and/or the applicable government rights clause.This documentation contains confidential, proprietary information of Candle Corporation that is licensed for your internal use only. Any unauthorized use, duplication, or disclosure is unlawful.
Contents 3
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Adobe Portable Document Format . . . . . . . . . . . . . . . . . . . . . . . . . . 14Documentation Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Candle Customer Service and Satisfaction . . . . . . . . . . . . . . . . . . . . 18
What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19New Features in Version 130 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21New Features in Version 120 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38New Features in the Programming Enhancements to Version 110 . . . 45New Features in Version 110 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Chapter 1. Overview of the OMEGAMON XE for WebSphere ApplicationServer Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55OMEGAMON XE for WebSphere Application Server Operating Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Introducing OMEGAMON XE for WebSphere Application Server . . . 63Situations for OMEGAMON XE for WebSphere Application Server. . 67Take Action Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Chapter 2. An Introduction to Configuration . . . . . . . . . . . . . . . . . . . . . . . 71Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Configuration Basics About Your Agent. . . . . . . . . . . . . . . . . . . . . . . 73
Contents
4 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Chapter 3. Setting Configuration Parameters, Environmental Variables, andInstrumentation Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83A Look Inside Your Agent’s Configuration Files . . . . . . . . . . . . . . . . . 85Your Agent’s Configuration Parameters and XML Tags . . . . . . . . . . . 91Using Your Agent’s Environment Variables . . . . . . . . . . . . . . . . . . . 112Setting Instrumentation Levels to Collect PMI Data . . . . . . . . . . . . . 115
Chapter 4. Preparing the Instrumentation Control File for Workloads andApplication Traces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117Instrumentation Basics about Workloads and Tracing . . . . . . . . . . . 118Inside the User Instrumentation Control File . . . . . . . . . . . . . . . . . . 120
Chapter 5. Collecting Workload Analysis, Application Trace, and HeapData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143Workload Analysis, Application Traces, and Instrumentation . . . . . . 145Launching the Class Loader Script for Workload Analysis . . . . . . . . 148Changing the WebSphere Application Server Configuration . . . . . . 150Collecting Specific Workload Analysis Data for Different Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Creating Specific Agent Control Files for Different Agents . . . . . . . . 161
Chapter 6. Introducing OMEGAMON XE for WebSphere Application ServerInformation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165OMEGAMON XE for WebSphere Application Server Data . . . . . . . 166Accessing the OMEGAMON XE for WebSphere Application Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Historical Reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171OMEGAMON XE for WebSphere Application Server Workspaces. . 172
Chapter 7. The CandleNet Portal Take Action Commands . . . . . . . . . . . .177Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Using Take Action Commands in Situations . . . . . . . . . . . . . . . . . . 183
Appendix A. A Sample WebSphere Application Server Application: BestPractices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Installing the Best Practices Samples . . . . . . . . . . . . . . . . . . . . . . . . 189
Contents 5
Performing the installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Configuring OMEGAMON XE for WebSphere Application Server for the Best Practices Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Executing the Best Practices Samples . . . . . . . . . . . . . . . . . . . . . . . 220Uninstalling the Best Practices Samples . . . . . . . . . . . . . . . . . . . . . . 222
Appendix B. Historical Reference Information for Attributes . . . . . . . . . . . .225
Appendix C. OMEGAMON XE for WebSphere Application ServerMessages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
6 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figures 7
Figure 1. Product Components for OMEGAMON XE for WebSphere ApplicationServer V4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Figure 2. Product Components for OMEGAMON XE for WebSphere ApplicationServer V5—Base Deployment Configuration . . . . . . . . . . . . . . . . . . 75
Figure 3. Product Components for OMEGAMON XE for WebSphere ApplicationServer V5—Network Deployment Configuration. . . . . . . . . . . . . . . . 76
Figure 4. Sample Default Parameters in kwe.xml . . . . . . . . . . . . . . . . . . . . . . . 88Figure 5. Expanded Configuration Parameters in kwesmpl.xml . . . . . . . . . . . . 90Figure 6. Sample kweiuser_development.xml Workload Analysis Control File 121Figure 7. Default kweiuser_certification.xml Workload Analysis Control File. . 122Figure 8. Default kweiuser_production.xml Workload Analysis Control File . . 123Figure 9. Navigator Items for the OMEGAMON XE for WebSphere Application
Server V130 Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Figure 10. Data Source Properties window . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Figure 11. J2C Authentication Data Entries panel . . . . . . . . . . . . . . . . . . . . . . 196Figure 12. JDBC Providers screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Figure 13. Datasource parameters screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Figure 14. databaseName screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Figure 15. Install Enterprise Application Wizard . . . . . . . . . . . . . . . . . . . . . . . . 204Figure 16. Selecting Application Servers screen . . . . . . . . . . . . . . . . . . . . . . . . 205Figure 17. Server or Server Group window . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Figure 18. Completing the Application Installation Wizard screen. . . . . . . . . . . 207Figure 19. Preparing for the application installation screen . . . . . . . . . . . . . . . . 209Figure 20. Installation Options installation step. . . . . . . . . . . . . . . . . . . . . . . . . 211Figure 21. Provide Default Datasource Mapping installation step . . . . . . . . . . . 213Figure 22. Map Resource References installation step. . . . . . . . . . . . . . . . . . . . 214Figure 23. Map Virtual Hosts installation step. . . . . . . . . . . . . . . . . . . . . . . . . . 215Figure 24. Map Modules to Application Servers installation step . . . . . . . . . . . 216
Figures
8 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Tables 9
Table 1. Symbols in Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Table 2. New Attribute Groups in Version 110 . . . . . . . . . . . . . . . . . . . . . . . . 51Table 3. Predefined Situations for the OMEGAMON XE Agent . . . . . . . . . . . . 68Table 4. Configuration Setup Take Action Command: Edit Argument Values
Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Table 5. Take Action Commands for the OMEGAMON XE Agent. . . . . . . . . 179Table 6. Candle’s Best Practices Source Fragments for Java Programming . . 186Table 7. All Workloads V2 attribute group (KWEWLDS2) . . . . . . . . . . . . . . . 227Table 8. Allocation Failure Block Detail attribute group (KWEGCAFB) . . . . . 231Table 9. Application Server attribute group (KWEAPPSRV) . . . . . . . . . . . . . 233
Table 10. Application Server Errors attribute group (KWEASERR) . . . . . . . . . 237Table 11. Application Server Status attribute group (KWEAPSST) . . . . . . . . . 238Table 12. Container Object Pools attribute group (KWEEBOP). . . . . . . . . . . . 239Table 13. Container Transactions attribute group (KWETRANS). . . . . . . . . . . 241Table 14. CTG Summary attribute group (KWETGSUM) . . . . . . . . . . . . . . . . 244Table 15. Current Objects for Selected Class attribute group (KWEHUDTL) . . 246Table 16. Datasources attribute group (KWEDATAS) . . . . . . . . . . . . . . . . . . . 248Table 17. DB Connection Pools attribute group (KWEDBCONP) . . . . . . . . . . 250Table 18. Dynamic Cache attribute group (KWECACHE). . . . . . . . . . . . . . . . 252Table 19. Dynamic Cache Templates attribute group (KWECACHT) . . . . . . . 253Table 20. EJB Containers attribute group (KWECONTNR). . . . . . . . . . . . . . . 255Table 21. Enterprise Java Beans for attribute group (KWEEJB) . . . . . . . . . . . 259Table 22. Enterprise Java Bean Methods attribute group (KWEEJBMTD). . . . 262Table 23. Garbage Collector Activity attribute group (KWEGC) . . . . . . . . . . . 263Table 24. Garbage Collection Cycle Detail attribute group (KWEGCCYC) . . . 265Table 25. Heap Usage attribute group (KWEHUSUM) . . . . . . . . . . . . . . . . . . 267Table 26. HTTP Sessions attribute group (KWEHTTPS) . . . . . . . . . . . . . . . . . 268Table 27. In-flight Workloads attribute group (KWEIFWSM) . . . . . . . . . . . . . . 270Table 28. In-flight Workload Detail attribute group (KWEIFWDT) . . . . . . . . . . 274Table 29. J2C Connection Pools attribute group (KWEJ2C) . . . . . . . . . . . . . . 276Table 30. JMS Summary attribute group (KWEMQSAC) . . . . . . . . . . . . . . . . 278
Tables
10 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Table 31. Lock Analysis by Method Detail attribute group (KWEMCDCM) . . . 280Table 32. Lock Analysis by Method Summary attribute group (KWEMCCMS) 282Table 33. Lock Analysis by Workload attribute group (KWEMCMW) . . . . . . . 283Table 34. Lock Analysis by Workload Detail attribute group (KWEMCDWL). . 284Table 35. Lock Owner for Selected In-flight Workload attribute group
(KWEIFML). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Table 36. Longest Running Workloads V2 attribute group (KWEWLEX2) . . . . 288Table 37. Methods Instantiating Selected Class attribute group (KWEWHUBM)291Table 38. WebSphere Distributed Product Events attribute group (KWEPREV) 292Table 39. References to Objects for Selected Allocation Source attribute group
(KWEOBJRF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Table 40. Selected Workload Delays attribute group (KWEWKLDD). . . . . . . . 295Table 41. Servlet Sessions attribute group (KWESERVS) . . . . . . . . . . . . . . . . 297Table 42. Servlets JSPs attribute group (KWESERVLT). . . . . . . . . . . . . . . . . . 299Table 43. Suspected Memory Leaks attribute group (KWEHUPML) . . . . . . . . 300Table 44. Thread Pools attribute group (KWETHRDP) . . . . . . . . . . . . . . . . . . 301Table 45. Web Applications attribute group (KWEAPP) . . . . . . . . . . . . . . . . . 302Table 46. Workload Class Instantiations attribute group (KWEWHUSE) . . . . . 304Table 47. Workload Management WLM Client attribute group (KWEWLMCL) 305Table 48. Workload Management WLM Server attribute group (KWEWLMSR) 306
Preface 11
Preface
This guide provides a fundamental understanding of how to use Version 130 of Candle’s OMEGAMON® XE for WebSphere Application Server product to monitor availability and performance of IBM’s WebSphere Application Server V3.5 or higher on distributed platforms.
This guide is designed to help you:
� understand how OMEGAMON XE for WebSphere Application Server works with the frontend known as CandleNet Portal™ (CNP).
� access specific information about events occurring in your WebSphere Application Server environment.
� use the real-time data, alerts, historical data, and automation that OMEGAMON XE for WebSphere Application Server provides as a management tool.
P
About This Book
12 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
About This Book
Who should read this bookThis guide is intended to be used by administrators and application programmers for IBM’s WebSphere Application Server. It is also intended for systems experts who perform a variety of tasks such as performance tuning and troubleshooting.
This manual assumes that:
� IBM’s WebSphere Application Server is already installed and configured, and that you are familiar with its basic concepts. Refer to the IBM WebSphere Application Server documentation for details.
� you or someone at your site have installed and configured Candle Management Server® (CMS®) and the Candle Management Workstation® (CMW™) for administrative purposes.
� you have installed a server, client, or Web-based version of CNP and the OMEGAMON XE for WebSphere Application Server agent.
� you are familiar with basic CNP concepts, tasks, and features, including:
– how to use attributes to define situations and how to modify predefined situations.
– the roles managed systems and managed objects play in an enterprise.
– what alerts and events are and how they affect managed objects.
– how to act upon an alert or other event.
Preface 13
About This Book
Becoming orientedIf you are performing administrative tasks for OMEGAMON XE for WebSphere Application Server and its users, please review the CandleNet Portal Administrator’s Guide, the CMW online tutorial, and the Candle Management Workstation Quick Reference before beginning this manual.
If you are unfamiliar with the CNP interface, concepts, and tasks, please review the online Quick Tour for CandleNet Portal to become familiar with its features and capabilities.
Where to look for more informationFor more information related to this product and other related products, please see the
� technical documentation CD-ROM that came with your product
� technical documentation information available on the Candle Web site at www.candle.com
� online help provided with this and the other related products
Adobe Portable Document Format
14 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Adobe Portable Document Format
Printing this bookCandle supplies documentation in the Adobe Portable Document Format (PDF). The Adobe Acrobat Reader will print PDF documents with the fonts, formatting, and graphics in the original document. To print a Candle document, do the following:
1. Specify the print options for your system. From the Acrobat Reader Menu bar, select File > Page Setup… and make your selections. A setting of 300 dpi is highly recommended as is duplex printing if your printer supports this option.
2. To start printing, select File > Print... on the Acrobat Reader Menu bar.
3. On the Print pop-up, select one of the Print Range options for� All� Current page� Pages from: [ ] to: [ ]
4. (Optional). Select the Shrink to Fit option if you need to fit oversize pages to the paper size currently loaded on your printer.
Printing problems?The print quality of your output is ultimately determined by your printer. Sometimes printing problems can occur. If you experience printing problems, potential areas to check are:� settings for your printer and printer driver. (The dpi settings for both your
driver and printer should be the same. A setting of 300 dpi is recommended.)
� the printer driver you are using. (You may need a different printer driver or the Universal Printer driver from Adobe. This free printer driver is available at www.adobe.com.)
� the halftone/graphics color adjustment for printing color on black and white printers (check the printer properties under Start > Settings > Printer). For more information, see the online help for the Acrobat Reader.
� the amount of available memory in your printer. (Insufficient memory can cause a document or graphics to fail to print.)
For additional information on printing problems, refer to the documentation for your printer or contact your printer manufacturer.
Preface 15
Adobe Portable Document Format
Contacting AdobeIf additional information is needed about Adobe Acrobat Reader or printing problems, see the Readme.pdf file that ships with Adobe Acrobat Reader or contact Adobe at www.adobe.com.
Adding annotations to PDF filesIf you have purchased the Adobe Acrobat application, you can add annotations to Candle documentation in .PDF format. See the Adobe product for instructions on using the Acrobat annotations tool and its features.
Documentation Conventions
16 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Documentation Conventions
IntroductionCandle documentation adheres to accepted typographical conventions for command syntax. Conventions specific to Candle documentation are discussed in the following sections.
Panels and figuresThe panels and figures in this document are representations. Actual product panels may differ.
Required blanksThe slashed-b (!) character in examples represents a required blank. The following example illustrates the location of two required blanks.
!!!!eBA*ServiceMonitor!!!!0990221161551000
Revision barsRevision bars (|) may appear in the left margin to identify new or updated material.
Variables and literals in command syntax examplesIn examples of command syntax for the OS/390, VM, OS/400, and NonStop Kernel platforms, uppercase letters indicate actual values (literals) that the user should type; lowercase letters indicate variables that represent data supplied by the user:
LOGON APPLID (cccccccc)
However, for the Windows and UNIX platforms, variables are shown in italics:
-candle.kzy.instrument.control.file=instrumentation_control_file_name-candle.kzy.agent.parms=agent_control_file_name
Note: In ordinary text, variable names appear in italics, regardless of platform.
Preface 17
Documentation Conventions
SymbolsThe following symbols may appear in command syntax:
Table 1. Symbols in Command Syntax
Symbol Usage
| The “or” symbol is used to denote a choice. Either the argument on the left or the argument on the right may be used. Example:
YES | NOIn this example, YES or NO may be specified.
[ ] Denotes optional arguments. Those arguments not enclosed in square brackets are required. Example:
APPLDEST DEST [ALTDEST]In this example, DEST is a required argument and ALTDEST is optional.
{ } Some documents use braces to 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.
Candle Customer Service and Satisfaction
18 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Candle Customer Service and Satisfaction
BackgroundTo assist you in making effective use of our products, Candle offers a variety of easy-to-use online support resources. The Candle Web site provides direct links to a variety of support tools that include these services:
eSupport allows you to create and update service requests opened with Customer Service and Satisfaction (CSS).
eDelivery allows you to download products, documentation, and maintenance 24 hours a day, 7 days a week.
eNotification notifies you of product updates and new releases.
In addition, you can find information about training, maintenance plans, consulting and services, and other useful support resources. Refer to the Candle Web site at www.candle.com for detailed customer service information.
Candle Customer Service and Satisfaction contactsYou will find the most current information about how to contact Candle CSS by telephone or email on the Candle Web site. Go to the www.candle.com support section, and choose the link to Support Contacts to locate your regional support center.
What’s New 19
What’s New
IntroductionThis topic introduces the new features and enhancements that were added as the programming enhancements that make up Version 130 of OMEGAMON XE for WebSphere Application Server.
Also listed below, for historical purposes, are the Version 120 enhancements, the small programming enhancements to Version 110, and the original Version 110 enhancements themselves.
Chapter contents
New Features in Version 130. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Support for new PMI Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Lock analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Support for WebSphere Portal Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24J2EE 1.3 Workload Delays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Workload Analysis performance improvements . . . . . . . . . . . . . . . . . . . . . . . 29Multiple sample kweiuser.xml files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Alteration of the procedures for changing the WebSphere Application Server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Global flag to disable instrumentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Selective Historical Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Application server discovery adjustments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Dynamic refresh instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Determination of the total size of HTTP Session objects . . . . . . . . . . . . . . . . . 32Workload Reporting by URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Other enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
W
20 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
New Features in Version 120. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38PathWAI Performance Analyzer product simplifies trace analysis and workload instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Analysis of classes’ heap allocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Identification of memory leaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Support for in-flight workloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Support for user-defined delays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Support for CTG workloads as a delay type . . . . . . . . . . . . . . . . . . . . . . . . . . 42Support for JCA workloads as a delay type . . . . . . . . . . . . . . . . . . . . . . . . . . 44
New Features in the Programming Enhancements to Version 110 . . . . . . . . . . . . . 45Enhanced garbage-collection statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Support for user-defined workloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Support deleted for the JVM profiler and its reports . . . . . . . . . . . . . . . . . . . . 48
New Features in Version 110. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Support for WebSphere Application Server V5.0 . . . . . . . . . . . . . . . . . . . . . . 49Workload analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Application tracing for specific workloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50New Take Action commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Configuration changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Additional attribute groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Additional workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52The Best Practices samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Changes in Version 110 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53New chapters and appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
What’s New 21
New Features in Version 130
New Features in Version 130
Support for new PMI ModulesOMEGAMON XE for WebSphere Application Server supports some of the new PMI modules that are featured in IBM WebSphere Application Server V5.
New workspaces� Servlet Sessions� Servlet Sessions for Selected Web Application� J2EE Connector Connection Pools� Thread Pools� Dynamic Cache� Workload Management� Pool Utilization
(See the online help for details.)
New attribute groups � Dynamic Cache � Dynamic Cache Templates� J2EE Connector Connection Pools� Servlet Sessions� Workload Management Server� Workload Management Client� Thread Pools
(See the online help for details.)
New Take Action commands� WAS SetIL - Dynamic Cache� WAS SetIL - J2C Pool� WAS SetIL - ORB� WAS SetIL - Servlet Sessions� WAS SetIL - Workload Management Client� WAS SetIL - Workload Management Server
(See the online help for details.)
New Features in Version 130
22 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Lock analysisThis feature enables you to use the Workload Analysis feature to monitor the lock contentions in applications running within the WebSphere Application Server. It is possible for you to see whenever a lock on an object’s lock is requested and acquired by a Java thread. It is possible for you to determine the contention and it’s cost. You gain insight as to how lock contention is affecting the execution of each workload.
Only when the locking (or contending) logic is instrumented will the detected locking and contention be reported.
There are at least three levels of collection:
1. Disabled – this is the default. The agent will not collect any data for lock accesses.
2. Enabled – The agent will track the cost of lock accesses by each class method, workload, and delay. This allows you to identify the costs associated with lock accesses. A higher cost associated with lock access will indicate a higher lock contention.
3. High – In addition to the data collected by the Enabled collection level, you can track the locked objects. Whenever the lock of an object is requested or acquired, you can determine the other accessing class methods and workloads. Though there will be a higher cost to analyze, this information will allow you to identify the competing parties involved in a high lock contention situation.
New keywords in XML control files
Lock analysis gets enabled by adding these new attribute keywords in the XML control files:
� At the KWEAGENT level:
– DefaultLockAnalysisLevel– DefaultCollectLockAnalysisMinCost
(See “KWEAGENT” on page 91 for details.)
� At the MonitorAppServer level:
– LockAnalysisLevel– CollectLockAnalysisMinCost
What’s New 23
New Features in Version 130
(See “MonitorAppServer tag” on page 103 for details.)
New keywords in kweiuser.xml
Before Lock analysis data can be collected, the Workload Analysis component must instrument the appropriate byte code. This is done by adding these new attribute keywords to the kweiuser.xml file:
� At the KWEINSTR level:
– LockAnalysisSystemClasses– LockAnalysisUserClasses
(See “Keywords for the KWEINSTR tag” on page 124 for details.)
� At the Class level:
– LockAnalysis (See “Keywords for the Class tag” on page 131 for details.)
New workspaces� Lock Analysis� Lock Owner for Selected Inflight Workload� Lock Analysis for Selected Workload - Current Interval� Lock Analysis for Selected Method - Current Interval� Lock Contention for Selected Workload - Current Interval� Lock Contention for Selected Method - Current Interval
(See the online help for details.)
New attribute groups� Lock Analysis by Method Detail� Lock Analysis by Method Summary� Lock Analysis by Workload� Lock Analysis by Workload Detail� Lock Owner for Selected In-flight Workload
(See the online help for details.)
New Features in Version 130
24 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
New attributes for existing attribute groups� In All Workloads V2 attribute group
– Lock Wait Percent– Number of Locks Acquired
� In-flight Workloads attribute group
– Lock Wait Time
(See the online help for details.)
New Take Action command� WAS Set Lock Analysis Level—see the online help for details.
Changes to existing Take Action commands� WAS Start Application Tracing—see the online help for details.
Support for WebSphere Portal ServerWith support for WebSphere Portal Server versions 4.2.x and 5.0.x, you can identify commonly referenced portal runtime components (Java classes, interfaces) and leverage Workload Analysis capability to expose the portlet and portal interactions and have a better understanding of your portals. The information collected and provided will be useful for identification of bottlenecks.
Portlets are a Java technology based web component, managed by a portlet container, that processes requests and generates dynamic content. Portlets are used by portals as pluggable user interface components that provide a presentation layer to various, heterogeneous Enterprise Information Systems (EIS) or Information Systems (IS). They are reusable components that provide access to applications, diversified contents, and legacy systems.
Portals provide a mechanism for aggregating information and access to enterprise services into a single consolidated view. WebSphere Portal Server provides infrastructure for hosting, administration, and management of portlets.
What’s New 25
New Features in Version 130
Portlet as a workload type
In OMEGAMON XE for WebSphere Application Server, the concept of a workload has now been expanded to include portlets, so you can identify portlet invocations wherever you are monitoring workloads. Portlets have been added as a separate workload type in these attribute groups:
� Application Trace File� Current Objects for Selected Class� Suspected Memory Leaks (Allocating Workload Type)� In-flight Workload Detail � In-flight Workloads � References to Objects for Selected Allocation Source (Referenced Object
Allocating Workload Type)� Methods Instantiating Selected Class � Workload Class Instantiations � Selected Workload Delays � All Workloads V2� Longest Running Workloads
(See the online help for details.)
Portlet as a delay type
In OMEGAMON XE for WebSphere Application Server, the concept of a delay has now been expanded to include portlets, so you can identify portlet invocations wherever you are monitoring delays. In other words, portlets can now be defined as separate workloads. Portlets have been added as a separate delay type in this attribute group:
� Selected Workload Delays (See the online help for details.)
Updated Take Action commands
These Take Action commands are now able to enter and filter Portlet as a valid type:
� WAS Dynamic Workload Analysis (See the online help for details.)� WAS Start Application Tracing (See the online help for details.)
New Features in Version 130
26 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
New parameter for keyword in kweiuser.xml
This attribute keyword for the kweiuser.xml file includes a new parameter for characterizing portlets that enables the workload analysis component to identify and instrument them:
� At the Class level :
– MethodType now includes the PORTLET parameter. (See “MethodType” on page 135 for details.)
J2EE 1.3 Workload DelaysJ2EE Version 1.3 has introduced several new items. Those that impact Candle’s solution for WebSphere include:
� Support for the Enterprise Java Bean (EJB) Specification, Version 2.0, which includes:
– The integration of EJB with the Java Message Service (JMS) via Message driven Beans.
– Local interfaces to EJBs to allow beans to be more tightly coupled to their clients, thus reducing overhead.
� Support for Java Message Service (JMS) Topic Subscriber and Publication (pub/sub) message types
Candle addresses these new J2EE features by adding new workload delay types.
Parameters for the new ClassTypeDef keyword in kweiuser.xml
There are these parameters for the new ClassTypeDef attribute keyword of the KWEINSTR.tag in the kweiuser.xml file:
� Local EJB Support
– CLASSTYPE_EJBLOCALHOMECLASS– CLASSTYPE_EJBLOCALOBJECTCLASS
� Message driven Beans
– CLASSTYPE_EJBMESSAGEDRIVENBEAN
What’s New 27
New Features in Version 130
� JMS Publish/Subscribe Support
– CLASSTYPE_JMS_TOPIC– CLASSTYPE_JMS_TOPICCONNECTION– CLASSTYPE_JMS_TOPICCONNECTIONFACTORY– CLASSTYPE_JMS_TOPICPUBLISHER– CLASSTYPE_JMS_TOPICSUBSCRIBER– CLASSTYPE_JMS_TOPICSESSION
(See “ClassTypeDef” on page 124 for details.)
Changed workspaces
These existing workspaces have changed due to added EJB local object delay support or added JMS publish/subscribe delay support:
� All Workloads (new delay types for the 10 Worst Average Response Times bar chart)
� Selected Workloads (new delay types for the Selected Workload Average Response Time pie chart)
New attributes for existing attribute groups� In the All Workloads V2 attribute group
– EJB Local Home Delay Percent– EJB Local Home Delay Time– EJB Local Object Delay Percent– EJB Local Object Delay Time\– Number EJB Local Home Delays– Number EJB Local Object Delays
� In the Longest Running Workloads V2 attribute group
– EJB Local Home Delay Percent– EJB Local Home Delay Time– EJB Local Object Delay Percent– EJB Local Object Delay Time\– Number EJB Local Home Delays– Number EJB Local Object Delays
New Features in Version 130
28 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
� In the In-flight Workloads attribute group
– EJB Local Home Delay Percent– EJB Local Home Delay Time– EJB Local Object Delay Percent– EJB Local Object Delay Time\– Number EJB Local Home Delays– Number EJB Local Object Delays
� In the JMS Summary attribute group
– Manager Name– Name– Type
(See the online help for details.)
New parameters for the Delay Type attribute in the Selected Workload Delays attribute group� Create JMS� Create JMS Publisher� EJB Local Home Create Call� EJB Local Home Find Call� EJB Local Home Remove Call� EJB Local Object Business Method Call� JMS on Message� JMS Publish Message� Subscriber
(See the online help for details.)
What’s New 29
New Features in Version 130
Workload Analysis performance improvementsVarious performance improvements have been implemented within Workload Analysis in Version 130. These enhancements offer you more control and flexibility in the instrumentation and data collection process, so you can better tune the product and balance the tradeoff between performance and quantity of data collected.
New keywords for kwe.xml
There are these new attribute keywords for the XML control files:
� At the KWEAGENT level:
– DefaultCollectWorkloadMaxDepth (See “KWEAGENT” on page 91 for details.)
� At the MonitorAppServer level:
– CollectWorkloadMaxDepth (See “MonitorAppServer tag” on page 103 for details.)
New keywords for kweiuser.xml
There are these new attribute keywords for the kweiuser.xml file:
� At the KWEINSTR level:
– CollectInFlightWorkloads (See “Keywords for the KWEINSTR tag” on page 124 for details.)
� At the Class level:
– DepthSensitiveInstrumentation (See “Keywords for the Class tag” on page 131 for details.)
Updated Take Action command
There is a new parameter to the WAS Dynamic Workload Analysis Take Action command:
� MaxDepth (See the online help for details.)
New Features in Version 130
30 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Multiple sample kweiuser.xml filesWith this enhancement, the product includes 3 different sample kweiuser.xml files. They provide various levels of instrumentation that fulfill the most common performance requirements. You can use an unaltered version of one of these new sample kweiuser.xml files, customize one of them, or ignore them and create your own.
(See “Sample kweiuser.xml instrumentation control files” on page 120 for details.)
Alteration of the procedures for changing the WebSphere Application Server configuration
Some of the functions of the kweinstr.xml file have been assumed by the kweiuser.xml file so that you will never need to make copies of the kweinstr.xml file to configure instrumentation for multiple application servers with different performance requirements.
Changes to functioning of control files� kweiuser.xml replaces kweinstr.xml as the main instrumentation control
file.
� A new java property, com.candle.kwe.instrument.user_control_file, replaces com.candle.kwe.instrument.control_file.
(See “Changing the WebSphere Application Server Configuration” on page 150 for details.)
Updated Take Action command
There is a new parameter to the WAS Configuration Setup Take Action command:
� File
(See the online help for details.)
What’s New 31
New Features in Version 130
Global flag to disable instrumentationThis enhancement introduces a new global attribute in the instrumentation control file which can be used to disable all instrumentation, regardless of the settings in the individual class tags. This feature is useful when you are only interested in using Workload Analysis to monitor (as a primary example) Garbage Collection and have no desire to instrument either WebSphere or application classes. This attribute allows you to disable all instrumentation merely by changing one parameter in the kweiuser.xml file.
New keyword for kweiuser.xml
There is this new attribute keyword for the kweiuser.xml file:
� At the KWEINSTR level:
– GlobalInstrumentation (See “Keywords for the KWEINSTR tag” on page 124 for details.)
Selective Historical ReportingWith this enhancement, you can indicate in the agent’s configuration file whether or not historical data will be collected for a particular application server. The attribute which indicates this can be set either at the global level, or at the individual server level. The user can specify which groups of data should be, and should not be, collected for historical purposes.
New keywords in XML control files
Selective historical reporting gets enabled by adding these new attribute keywords in the XML control files:
� At the KWEAGENT level:
– DefaultCollectHistorical (See “KWEAGENT” on page 91 for details.)
� At the MonitorAppServer level:
– CollectHistorical (See “MonitorAppServer tag” on page 103 for details.)
New Features in Version 130
32 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Application server discovery adjustmentsTo improve performance, the amount of time between discovery cycles will be increased from a smaller interval (for example, by default every 15 minutes) to a default interval of every 12 hours. One drawback to this is that the agent will be slower to recognize new servers.
As an option to compensate for the slower recognition of newly defined application servers, there is a new Take Action command that will force the agent to perform a discovery cycle prior to the regularly scheduled discovery.
New Take Action command� WAS Discover Servers (See the online helps for details.)
Dynamic refresh instrumentationThis enhancement allows you to change the kweiuser.xml file and use the new definitions for which classes and methods should be instrumented without having to restart the application server.
New Take Action command� WAS Dynamic Refresh Instrumentation (See the online helps for details.)
Determination of the total size of HTTP Session objectsWith this enhancement, you can determine the approximate size (in bytes) of all the objects associated with HTTP sessions. The HTTP Sessions workspace reports this value, and the number of uncountable objects, on a per-session basis. In addition, the Application Server workspace reports the total byte count for all HTTP session objects for a particular server.
New attributes for existing attribute groups� The HTTP Session Object Size attribute of the HTTP Sessions attribute
group
� The HTTP Session Uncountable Objects attrIbute of the HTTP Sessions attribute group
� The Total HTTP Session Object Size attribute of the Application Server attribute group
What’s New 33
New Features in Version 130
(See the online help for details.)
New keyword for kweiuser.xml
There is this new attribute keyword for the kweiuser.xml file:
� At the KWEINSTR level:
– CollectHTTPSessStats—see “Keywords for the KWEINSTR tag” on page 124 for details
Workload Reporting by URLWith this enhancement, you have an option of using a portion of a URL name, instead of a servlet class name, as a workload major name. This allows you to break workloads into more meaningful categories.
Also, this enhancement provides an option for including the qualifying EAR and/or JAR file name for an EJB, whenever that EJB is displayed as a workload and/or delay major name within the product.
New keywords in kweiuser.xml
These new attribute keywords have been added to the kweiuser.xml file:
� At the KWEINSTR level:
– DisplayServletWorkloadAs– DisplayEJBAs
(See “Keywords for the KWEINSTR tag” on page 124 for details.)
� At the Class level:
– DisplayServletWorkloadAs– DisplayEJBAs
(See “Keywords for the Class tag” on page 131 for details.)
New Features in Version 130
34 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Other enhancements
New navigation
The existing workspaces were reorganized to both shorten the list of available OMEGAMON XE for WebSphere Application Server workspaces and to make the workspace order more logical.
New workspaces� Servlets/JSPs for Selected Web Application� Enterprise Java Bean Methods for Selected Bean
Renamed workspaces� The Product Events workspace has been renamed Agent Events
workspace.
� The JVM Garbage Collector Activity workspace has been renamed Garbage Collector Activity workspace.
� The Web Applications History workspace has been renamed Selected Web Application History workspace.
� The DB Connection Pools History workspace has been renamed Selected DB Connection Pool - History workspace.
(See the online help for details.)
New attribute� The CPU Time attribute of the Selected Workload Delays attribute group
(See the online help for details.)
Renamed attribute group� The JVM Garbage Collector Activity attribute group has been renamed
the Garbage Collector Activity attribute group.
What’s New 35
New Features in Version 130
Renamed attributes� In the Web Applications attribute group:
– Application Name attribute renamed Web Application Name
– Web Application Instrumentation Level attribute renamed Instrumentation Level
– Web Application Subinstrumentation Level attribute renamed Subinstrumentation Level
� In the Application Server attribute group:
– Session Manager Instrumentation Level attribute renamed Instrumentation Level
– OTP Instrumentation Level attribute renamed ORB Thread Pool Instrumentation Level
– Java Virtual Machine Instrumentation Level attribute renamed JVM Instrumentation Level
� In the DB Connection Pools attribute group:
– Database Connection Pool Instrumentation Level attribute renamed Instrumentation Level
– Summary of All DB Connections attribute renamed Summary of All Database Connections
� In the Servlets JSPs attribute group:
– Servlet/JSP Instrumentation Level attribute renamed Instrumentation Level
– Application Name attribute renamed Web Application Name
– Java Virtual Machine Instrumentation Level attribute renamed JVM Instrumentation Level
� In the Garbage Collection Cycle Detail attribute group:
– GC Date and Time attribute renamed Garbage Collection Date and Time
– Kbytes Free at Start of GC attribute renamed Kbytes Free at Start of Garbage Collection
New Features in Version 130
36 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
� The Date and Time attribute of the Application Server Status attribute group has been renamed Sample Date and Time.
� The EJB Container Instrumentation Level attribute of the EJB Containers attribute group has been renamed Instrumentation Level.
� The Enterprise Bean Instrumentation Level attribute of the Enterprise Java Beans attribute group has been renamed Instrumentation Level.
� The Enterprise Bean Method Instrumentation Level attribute of the Enterprise Java Bean Methods attribute group has been renamed Instrumentation Level.
� The Transaction Instrumentation Level attribute of the Container Transactions attribute group has been renamed Instrumentation Level.
� The Kbytes Free at Start of GC attribute of the Allocation Failure Block Detail attribute group has been renamed Kbytes Free at Start of Garbage Collection.
� The Row Number attribute of the References to Objects for Selected Allocation Source attribute group has been renamed Allocation Source.
� The Allocation Source Number attribute of the Suspected Memory Leaks attribute group has been renamed Allocation Source.
(See the online help for details.)
Obsolete and removed attributes� The Number of Containers attribute of the Application Server attribute
group
� From the JMS Summary attribute group:
– Queue Manager Name– Queue Name– Topic Manager Name– Topic Name
� From the All Workloads V2 attribute group:
– Process ID– Workload Full Name
What’s New 37
New Features in Version 130
� The Interval Time attribute of the Longest Running Workloads V2 attribute group
(See the online help for details.)
Renamed Take Action command� The WAS Set Workload Exception Thresholds command has been
renamed the WAS Set Longest Running Workload Threshold command.
(See the online help for details.)
Revised Documentation
In prior releases, the documentation for workspaces and the Take Action commands was split between the user’s guide and the online helps, with much information duplicated between the two. As of Version 130, all workspace and Take Action information has been coalesced in the online helps, for more immediate access.
New Features in Version 120
38 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
New Features in Version 120
The Version 120 enhancements include:
� Among its other capabilities, Candle’s new PathWAI Performance Analyzer product allows you to:
1. Create or update the kweiuser.xml file to specify the classes and methods to be instrumented for workload analysis.
2. Analyze application trace data. This new capability obviates the previous Application Trace workspace (but not the Application Trace Files workspace).
� The JVMProfilingPort parameter in the kwe.xml file has been renamed CollectorSessionPort; this reflects the fact that support for the JVM profiler was deleted as part of the programming enhancements for Version 110 (see “Support deleted for the JVM profiler and its reports” on page 48). For the same reason, the DefaultJVMProfilerSampleInterval and JVMProfilerSampleInterval parameters have been renamed DefaultCollectorSessionSampleInterval and CollectorSessionSampleInterval.
Note, however, that the original names (JVMProfilingPort, DefaultJVMProfilerSampleInterval, and JVMProfilerSampleInterval) are still supported.
� Extensive analysis of classes’ heap allocations has been added to the workload analysis feature.
� New workspaces assist you in isolating memory leaks in your WebSphere Application Server applications.
� Support for in-flight workloads (those that are in the process of running) in the workload analysis feature. Previously, only workloads that have run to completion were reported on.
� Support for user-defined workloads has been extended to report your site’s own user-defined delays as well.
� Support for CICS Transaction Gateway (CTG) workloads as a delay type.
� Support for J2EE Connector Architecture (JCA) workloads as a delay type.
What’s New 39
New Features in Version 120
� You can now specify a WorkloadCapturePercent keyword in kwe.xml to define a percentage of workloads to be randomly analyzed by workload analysis. (This control also applies to the new heap-analysis workspaces, via the new HeapCapturePercent keyword).
This enhancement also added a new Take Action command, WAS Set Capture Percent, that you can use for changing the capture percentages dynamically from CandleNet Portal.
� For every cofiguration parameter that requires a class mask, you may now specify an exclusion mask that identifies classes to be excluded. This includes the Dynamic Workload Analysis and Start Heap Collection Take Action commands as well.
� New samples have been added to the Best Practices application.
Other changes instituted with this new version include:
� The All Workloads attribute group (table name KWEWKLDS) has been renamed All Workloads V2 (table name KWEWLDS2), and the Longest Running Workloads attribute group (table name KWEWKLEX) has been renamed Longest Running Workloads V2 (table name KWEWLEX2). Note, however, that situations you created using the old group names should function as before.
� Numerous attributes have been renamed across all attribute groups to make them consistent with the OMEGAMON XE for WebSphere Application Server for OS/390 product.
� The automatic installer for the Best Practices sample has been desupported. Instead guidelines are provided for manually installing the sample using standard WebSphere Application Server processes.
� Support has been dropped for WebSphere Application Server V3.5.
New Features in Version 120
40 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
PathWAI Performance Analyzer product simplifies trace analysis and workload instrumentation
Among its many other capabilities, Candle’s PathWAI Performance Analyzer product allows you to:
� Import your kweliuser.xml control file, update it to specify the classes and methods to be instrumented for workload analysis, and export the updated file. With PathWAI Performance Analyzer, you can browse the contents of a jar, ear, or war or ear file and select the classes and methods you want instrumented.
� Analyze application trace data in ways CandleNet Portal never could, including the viewing of vastly greater quantities of trace data. Among its other enhancements, PathWAI Performance Analyzer adds a graphical trace viewer and a tree view of your methods’ calling parameters.
This new capability obviates the previous Application Trace workspace (but not the Application Trace Files workspace or the Take Action commands that let you start or stop application tracing and delete application trace files).
For complete information, see the online PathWAI Performance Analyzer User Guide.
Analysis of classes’ heap allocationsThis feature uses the Java instrumentation techniques developed for the Workload Analysis feature to monitor use of the Java heap by applications running within the WebSphere Application Server. An application acquires heap storage by performing a new request within some Java method. There are generally three types of new requests:
1. A request for a new Java object.2. A request for a new Java primitive array.3. A request for a new Java object array.This enhancement necessitated the addition of several attributes to the kwe.xml file for the OMEGAMON XE agent.
For default control of all application servers:
� DefaultCollectHeapLevel
What’s New 41
New Features in Version 120
� DefaultCollectHeapClasses� MaxReferenceSearchTime
For control of a specific application server via the MonitorAppServer tag:
� CollectHeapLevel� CollectHeapClasses
In addition, to specify the classes whose heap allocations are to be instrumented, these attriutes were added to the kweiuser.xml file:
� NumHeapAnalysisClasses� HeapAnalysisSystemClasses� HeapAnalysisUserClasses� MeasureHeapDelays
The HeapAnalysis attribute was added to the kweiuser.xml Class tag.
Finally, Take Action command WAS Start Heap Collection was added to allow the CandleNet Portal user to dynamically start and stop the collection of heap-allocation statistics.
Identification of memory leaksThe new Suspected Memory Leaks workspace can help you isolate workloads with rapidly growing memory requirements so you can identify the workload that is causing them. This enhancement also incorporates the Suspected Memory Leaks attributes.
Support for in-flight workloadsPrior to the version 120 workload analysis feature, only workloads that have actually run to completion were reported on. Workloads that are still running were ignored.
Many customers need to examine those workloads that are currently running within the application server, to determine whether the workloads have been running for a long period of time, and if so, why. Is the workload in a loop? Is it waiting for an event notification from some other thread?
The In-flight Workloads feature provides several new tables and workspaces that show the status of workloads that are running but have not yet
New Features in Version 120
42 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
completed. These workspaces can help you determine which workloads are running or waiting on another workload.
This enhancement added these CandleNet Portal workspaces:
� In-flight Workloads Summary� In-flight Workloads Detail
This enhancement necessitated the addition of the DefaultInflightThreshold attribute to the kwe.xml file for the OMEGAMON XE agent, and for control of a specific application server via the MonitorAppServer tag, the InflightThreshold attribute. It also added Take Action command WAS Set In-flight Threshold, which users can invoke from CNP to dynamically change this in-flight threshold.
Support for user-defined delaysVersion 110 of the WebSphere Application Server’s workload analysis feature supports a long list of delay types; these represent a specific set of J2EE methods. Although version 110 also allows you to instrument virtually any user class or method, each instrumented method shows up as its own unique delay category; the result is that a single workload execution displays as dozens or even hundreds of delays, all contributing very minimally to the user’s overall response time.
The user-defined delays enhancement allows you to define your own delay types that aggregate into and can be identified by meaningful, business-oriented, major and minor names that you choose (much as you can assign your own major and minor names to your site’s user-defined workloads). Further, these delays can represent entire sets of methods that together compose a common business function, thus simplifying the presentation of the workload’s delay information for the CandleNet Portal user.
This enhancement necessitated the addition of the Delay tag to the kweiuser.xml file.
Support for CTG workloads as a delay typeWebSphere Application Server can now analyze calls to the CICS Transaction Gateway via the new CTG workload delay type.
What’s New 43
New Features in Version 120
IBM’s CTG provides your WebSphere Application Server applications access to data within Enterprise Information Systems (EIS) via CICS. A number of application programming interfaces are available with which your programmers can execute CICS transactions that retrieve and update information in CICS resources such as DB2. Using CTG it is possible to incorporate services provided by legacy CICS applications into new distributed and enterprise applications.
Of particular interest to WebSphere Application Server users is a set of Java interfaces that allow WebSphere Application Server applications to access CICS. These three Java interfaces are:
� ECI (the External Call Interface) directly calls a CICS program (through the program link facility) and uses the CICS COMMAREA to pass parameters and retrieve data.
Note:To include COMMAREA information about ECI applications, you must create a special plugin to extract that information and add it to the Selected Workload Delays - Current Interval workspace; this process is described in “Prerequisite for CTG users” on page 139. The CtgDelayPlugin and UserClassPath attributes were added to the kweiuser.xml file so the workload analysis component can locate and invoke this plugin.
� EPI (the External Presentation Interface) enables a non-CICS client to emulate the functions of a 3270 terminal and access CICS 3270-based transactions using the 3270 data stream. EPI is not available on CICS Transaction Gateway for z/OS.
� ESI (the External Security Interface) provides an interface to APPC’s Password Expiration Management (PEM) feature, through which user IDs and passwords can be validated by a CICS external security subsystem such as RACF.
This enhancement comprises a new set of CTG-related delay types in the workloads workspaces; it also added the CTG Summary workspace, which reports information about the CICS Transaction Gateway transactions processed by an application server. This new feature necessitated the addition of the CTG keyword to the MethodType attribute of the kweiuser.xml file’s Class tag and the addition of class type G to the DefaultCollectWorkloadClassType and CollectWorkloadClassType keywords in the kwe.xml file.
New Features in Version 120
44 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Support for JCA workloads as a delay typeWebSphere Application Server can now analyze workloads that invoke the JCA (the J2EE Connector Architecture) application programming interface as a new delay type. JCA defines a standard approach by which J2EE applications can connect to backend enterprise information systems (EIS). WebSphere Application Server V5.0 supports the JCA 1.5 specification.
The new JCA delay support gives workload analysis the ability to collect and report on metrics provided by the JCA API. JCA delay counts, delay totals, and time percentages have been added as new columns to existing workload analysis tables, including the All Workloads and Longest Running Workloads table views, in the same manner as JMS and JTA delay information, and in like manner to the new CTG columns.
This new feature necessitated the addition of the JCA keyword to the MethodType attribute of the kweinstr.xml file’s Class tag and the addition of class type C to the DefaultCollectWorkloadClassType and CollectWorkloadClassType keywords in the kwe.xml file.
What’s New 45
New Features in the Programming Enhancements to Version 110
New Features in the Programming Enhancements to Version 110
The programming enhancements to Version 110 include
� additional JVM garbage-collector workspaces and attribute groups that provide a more finely grained look at the heap allocation problems that cause the Java Virtual Machine to initiate garbage collection
� the workload analysis feature now supports Model/View/Controller workloads (including struts applications)
� no more support for the JVM profiler and its reports
� the new IPAddresses and UserIds parameters of the WAS Start Application Tracing Take Action command allow you to start application tracing on Web applications initiated from certain IP addresses (for Web browsers) or by certain WebSphere Application Server user IDs
� support for HP-UX and Linux
� it is no longer necessary that sites disable the just-in-time compiler when installing the OMEGAMON XE agent for WebSphere Application Server, nor is it still necessary to copy the kweprof.dll file to the WebSphere Application Server \bin directory
� Numerous changes have been made to the installation/deinstallation of the Best Practices sample application; these include, among others:
– The supported UNIX platforms now include Linux and HP-UX.
– Installation now supports WebSphere Application Server V5.0 Network Deployment.
– The installation batch file/shell script has been renamed from CandleBP to BPInstall.
– The generated deinstallation batch file/shell script has been renamed from BPUninstall<WASv> to BPUninstall<WASv><nodename>, where <WASv> is the WebSphere Application Server version and <nodename> is the UNIX or Windows node where the Best Practices application was installed.
The installation and deinstallation processes have changed so much that Candle strong recommends you reread “A Sample WebSphere
New Features in the Programming Enhancements to Version 110
46 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Application Server Application: Best Practices” on page 185 before installing or deinstalling this sample application.
Enhanced garbage-collection statisticsThe three new JVM garbage-collector workspaces and two new attribute groups provide far more detailed information about this Java Virtual Machine function than was previously provided with the garbage-collection reports from the old JVM profiler. This enhancement is based on the logs produced by the verbose:gc JVM parameter within WebSphere Application Server. With this enhancement, there are now four garbage-collection workspaces; they are:
JVM Garbage Collector Activity– Garbage Collections—Current Interval– Allocation Failures
-- Garbage Collections—Selected Allocation Failure
With this enhancement, there are now three attribute groups that you can use in writing situations that detect problems in the garbage collector:
� JVM Garbage Collector Activity� Allocation Failure Block Detail� Garbage Collection Cycle Detail
Note: The CPU Percent and Total CPU Used attributes, formerly part of the JVM Garbage Collector Activity attribute group, have been deleted.
This enhancement also changed the OMEGAMON XE for WebSphere Application Server agent and its configuration in these ways:
� It added the DefaultGCCollect and GCCollect parameters to the agent startup file, kwe.xml.
� The JVMProfilingPort attribute in the kweiuser.xml file and the JVMProfilerSampleInterval and DefaultJVMProfilerSampleInterval attributes in the kwe.xml file now control garbage-collection statistics as well as the workload analysis feature.
� The WAS Configuration Setup Take Action command was updated to reconfigure WebSphere Application Server to start or stop writing out garbage-collection log records.
What’s New 47
New Features in the Programming Enhancements to Version 110
� The new WAS Verbose GC Collection Take Action command was added to allow CandleNet Portal users to dynamically start reporting garbage-collection statistics.
Support for user-defined workloadsThe workload analysis feature now allows you to instrument classes and methods built according to the Model/View/Controller architecture (such as struts applications), and assign them major and minor names that best describe their business purpose. Thus you can now report on your site’s business functions via the new “User” workload type in the All Workloads and Selected Workload reports.
This enhancement also added workload type User to Take Action command WAS Start Application Tracing.
Note: This enhancement expanded the meaning of the Class Name column within the All Workloads, Longest Running Workloads, and Selected Workload workspaces: this field now represents either the servlet or EJB class name, or the major name you specified for the user-defined workload when instrumenting it. Similarly, the Method Name column now represents either the servlet/EJB method name or the minor name you specified for the workload. For this reason, the column headings were changed from “Class Name“ and “Method Name” to “Class Name/Major Name“ and “Method Name/Minor Name“.
Note that this change affects only the reports. The attribute names (Class Name and Method Name) in the All Workloads, Longest Running Workloads, and Selected Workload attribute groups did not change.
New Features in the Programming Enhancements to Version 110
48 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Support deleted for the JVM profiler and its reportsSupport for the JVM profiler (included the profiler-related workspaces and attribute groups) has been deleted. This feature, built on IBM and Sun’s experimental Java Virtual Machine Profiler Interface (JVMPI), provided these workspaces and attribute groups:
� JVM Threads� JVM Monitor Contention� JVM Methods� JVM Method Summary� JVM Heap Usage
Except for the JVMProfilingPort, JVMProfilerSampleInterval, and DefaultJVMProfilerSampleInterval XML attributes, support for all profiler-related configuration parameters has been deleted, as have the WAS JVMSTAT Take Action command and the CPU time attributes within the Selected Workload Delays attribute group (since they depend upon profiler data). In addition, the kwe.xml file’s DefaultCollectWorkloadClassType and CollectWorkloadClassType parameters’ value N (to collect workload data for socket-related classes) has been dropped.
What’s New 49
New Features in Version 110
New Features in Version 110
The Version 110 enhancements include
� support for WebSphere Application Server V5.0
� new attributes that collect workload analysis and application trace data
� configuration options that enable you to define workload and application traces for which you want to collect data
� new workspaces that enable you to view workload and application tracing information
� Take Action commands to manage workload analysis and application tracing
� new attributes that collect information about databases, HTTP sessions, Java Message Service (JMS) queues, and Java Virtual Machine (JVM) threads
� new workspaces that enable you to view information about databases, HTTP sessions, JMS queues, and JVM threads
� a Best Practices application comprising seven samples that illustrate the performance advantages of selected Java coding practices
Support for WebSphere Application Server V5.0Version 110 of the OMEGAMON XE for WebSphere Application Server product recognizes and reports on the new WebSphere Application Server V5.0 product. The reports are the same as those for WebSphere Application Server V4.0.
The OMEGAMON XE agent now supports these WebSphere Application Server versions:
� WebSphere Application Server V3.5 Advanced Edition� WebSphere Application Server V4 Advanced Edition� WebSphere Application Server V5 Base Deployment, Network
Deployment, and Enterprise Edition
New Features in Version 110
50 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Workload analysisA key feature of this release is the capability to perform workload analysis and analyze the performance of specific units of work. Workload analysis identifies resource bottlenecks affecting your WebSphere Application Server applications; it measures the response time of servlets, JSPs, and EJB methods, and identifies where these workloads are causing delays. You can selectively define workloads that you want to track and turn workload analysis on and off when you need to collect this type of information.
These features can help you fine-tune your application development and achieve better results.
Application tracing for specific workloadsVersion 110 also includes an application trace capability to supplement workload analysis. Application tracing is an extension of workload analysis that uses the workload analysis instrumention to track method calls within an application. You can use this capability for in-depth application tuning.
New Take Action commandsThis release contains new Take Action commands for managing workload analysis from within the CandleNet Portal (CNP) interface. To facilitate the collection and control of workload and application tracing data, Version 110 provides the following new Take Action commands:
� WAS Dynamic Workload Analysis� WAS Set Workload Exception Thresholds� WAS Start Application Tracing� WAS Stop Application Tracing� WAS Delete Application Tracing Files
Configuration changesAdditional configuration options have been added to the product to support the enhancements for workload analysis and application tracing. The basic configuration file for the agent, kwe.xml. contains new parameters for workload analysis. In addition, the product provides a kweiuser.xml file and a
What’s New 51
New Features in Version 110
class loader script to let you define and implement your specific settings for collecting this data.
Additional attribute groupsThe Version 110 of OMEGAMON XE for WebSphere Application Server provides nine new attribute groups that expand its data collection capabilities. This table identifies each new group and contains a summary of its purpose.
Table 2. New Attribute Groups in Version 110
Attribute Group Use
All Workloads Reports summary data about workloads and areas that are causing the most degradation and delays
Application Trace Shows the flow of method calls within traced applications
Application Trace File Reports information about any traces that were performed for the application server
Datasources Reports database usage information
HTTP Sessions Reports data about active HTTP sessions
JMS Summary Reports data about how WebSphere Application Server applications are using JMS and WebSphere MQ messaging
JVM Threads Reports data about threads running in the JVMs that are hosting an application server
Longest Running Workloads Reports response times for individual invocations of a servlet, EJB method, or JSP that exceeds a response time threshold. Breaks down the individual response times into delay components. The key difference between this attribute group and the All Workloads groups is that this one enables you to identify users receiving bad response times when the average response is good
Selected Workload Delays Reports detailed information for a delay component (JMS, JNDI, SQL, and so on) related to an individual workload. For example, displays average response times for each SQL update request made by a workload
New Features in Version 110
52 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Additional workspacesThe Version 110 of OMEGAMON XE for WebSphere Application Server also provides new workspaces that give you an immediate view of the new data you can now collect. The additional workspaces include
� All Workloads—to view summary data about all the instrumented workloads that were executed during the current interval.
� Application Trace—to view detailed information about trace entries stored in a specific trace file.
� Application Trace Files—to list the trace files that have collected in the trace directory.
� Datasources—to view current and historical database usage information.� HTTP Sessions—to view information about active HTTP sessions in an
application server.� JMS Summary—to view current data about how WebSphere Application
Server applications are using JMS and WebSphere MQ messaging and to access selected queue history information.
� JVM Threads—to view summary information about all the threads running in a JVM that is hosting an application server.
� Longest Running Workloads—to view detailed information about delay time for the longest running workloads.
� Selected Workload Delays—to view detailed information about a specific delay component (JMS, JNDI, SQL, and so on) related to an individual workload.
The Best Practices samplesCandle has added a Best Practices application comprising seven sample programs that demonstrate the performance advantages of different Java coding practices. This application, including its installation, configuration, operation, and deinstallation, is fully documented in Appendix A, “A Sample WebSphere Application Server Application: Best Practices” on page 185.
What’s New 53
New Features in Version 110
Changes in Version 110
Revised configuration information
Rather than cover all the various configuration options in one chapter, this guide presents the material in chapters 2–6 in a configuration section. Covering separate configuration topics in separate chapters should make it easier to locate specific configuration information that pertains to the collection of optional data. The first chapter in the section provides an overview of configuration requirements. The remaining chapters cover general agent configuration, configuration requirements and the collection of JVM profiler data, and configuration requirements and the collection of workload analysis and application trace information.
WAS Setup Profiler Take Action command replaced
This release has replaced the WAS Setup Profiler Take Action command with the WAS Configuration Setup Take Action command; this new command includes controls for the new workload analysis feature.
Support for WebSphere Application Server V3.5 dropped from the DB Connection Pools workspace
The OMEGAMON XE agent still supports WebSphere Application Server V3.5 via its Container Transactions and EJB Containers workspaces; however support has been dropped for WebSphere Application Server V3.5 from the DB Connection Pools workspace.
New chapters and appendixes In addition to updating the existing text where applicable, this User’s Guide also contains several new chapters and appendixes. The new sections in the guide group related chapters together. The new appendixes cover the messages that are produced by the OMEGAMON XE agent and a cross-reference for identifying attribute information that you collect for long-term historical information. These new items include
� Chapter 2, “An Introduction to Configuration” on page 71
� Chapter 3, “Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels” on page 81
� Chapter 4, “Collecting JVM Profiler Performance Data” on page 93
New Features in Version 110
54 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
� Chapter 5, “Preparing the Instrumentation Control File for Workloads and Application Traces” on page 117
� Chapter 6, “Collecting Workload Analysis, Application Trace, and Heap Data” on page 143
� Chapter 18, “All Workloads Workspace” on page 199
� Chapter 21, “The CandleNet Portal Take Action Commands” on page 177
� Appendix B, “Historical Reference Information for Attributes” on page 225
� Appendix C, “OMEGAMON XE for WebSphere Application Server Messages” on page 309
In addition, a glossary has also been added.
Overview of the OMEGAMON XE for WebSphere Application Server Product 55
Overview of theOMEGAMON XE for WebSphere
Application Server Product
OverviewThis chapter introduces the OMEGAMON XE for WebSphere Application Server and explains how it can help you monitor and administer your systems that deploy IBM WebSphere Application Server. It places this agent into the context of the CandleNet Portal, a suite of products used to monitor a mixed systems environment.
Chapter contents
OMEGAMON XE for WebSphere Application Server Operating Environment . . . 57What is OMEGAMON XE?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Components of the environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58What is CandleNet Portal? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58What is the Candle Management Workstation?. . . . . . . . . . . . . . . . . . . . . . . . 59Further information about the CMW and CandleNet Portal . . . . . . . . . . . . . . 59What is OMEGAMON DE?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59What is OMEGAMON DE Policy Management? . . . . . . . . . . . . . . . . . . . . . . . 60PathWAI Performance Analyzer product simplifies trace analysis and workload instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Historical data collection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Introducing OMEGAMON XE for WebSphere Application Server . . . . . . . . . . . . . 63What is an OMEGAMON XE agent? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63What this agent does . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Workload analysis and application tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . 64How the agent works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Product packages that include this agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
1
56 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Situations for OMEGAMON XE for WebSphere Application Server . . . . . . . . . . . 67Predefined situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67How situations work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Avoid using negative values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Available predefined situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68In-depth information about situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Take Action Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Predefined Take Action commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Overview of the OMEGAMON XE for WebSphere Application Server Product 57
OMEGAMON XE for WebSphere Application Server Operating Environment
OMEGAMON XE for WebSphere Application Server Operating Environment
Overview
OMEGAMON XE for WebSphere Application Server can help you address the increasing challenges presented by today’s technical environment. In this topic, you learn about the operating environment in which the OMEGAMON XE agent resides.
What is OMEGAMON XE?OMEGAMON XE is a suite of products that assists you in monitoring your mainframe and distributed systems on a variety of platforms using a variety of workstations.
It provides a way to monitor the availability and performance of all the systems in your enterprise from one or several designated workstations. It provides many useful reports you can use to track trends and understand and troubleshoot system problems. You can use OMEGAMON XE to
� establish your own performance thresholds
� create situations, which are conditions to monitor
� create and send commands to systems in your managed enterprise by means of the Take Action feature. Take Action enables you to, for instance, restart a process that is not functioning properly or send a message
� create comprehensive reports about system conditions
� monitor for alerts on the systems and platforms you are managing
� trace the causes leading up to an alert
� define your own queries, using the attributes provided by OMEGAMON XE for WebSphere Application Server, to monitor conditions of particular interest to you
OMEGAMON XE for WebSphere Application Server Operating Environment
58 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Components of the environmentThe client/server/agent implementation includes
� a client, which can be
– a CandleNet Portal workstation client– a CandleNet Portal browser client
� a server, known as the Candle Management Server® (CMS™)
� a workstation, known as the Candle Management Workstation® (CMW™)
� a CandleNet Portal server that performs common CandleNet Portal functions and serves to lighten the CandleNet Portal client
� monitoring agents that collect and distribute data to a CMS. The OMEGAMON XE for WebSphere Application Server is such an agent.
Two additional feature packages are available with OMEGAMON XE. These are OMEGAMON DE and OMEGAMON DE Policy Management. Each of these feature packages provides all the capability of OMEGAMON XE, plus additional capabilities: The additional capabilities provided by OMEGAMON DE and OMEGAMON DE Policy Management are described later in this chapter.
What is CandleNet Portal?CandleNet Portal is the user interface into your OMEGAMON XE product. It provides a view of your enterprise from which you can drill down to examine components of your systems environment more closely. Its application window consists of a Navigator that shows all the systems in your enterprise where Candle agents are installed and a workspace that includes table and chart views of system and application conditions.
CandleNet Portal runs situations at regular intervals to check that your applications and systems are running, and running well. A failed test causes event indicators to appear in the Navigator.
CandleNet Portal offers two modes of operation: desktop and browser. In desktop mode, the application software is installed on your system. In browser mode, the system administrator installs the application on the web server and you start CandleNet Portal from your browser. In browser mode, the
Overview of the OMEGAMON XE for WebSphere Application Server Product 59
OMEGAMON XE for WebSphere Application Server Operating Environment
application is downloaded to your system the first time you log on to CandleNet Portal, and, thereafter, only when there are software updates.
What is the Candle Management Workstation?When using OMEGAMON XE for WebSphere Application Server, you use the Candle Management Workstation (CMW) for CMS administrative functions that manage work groups and work lists, data items, and managed systems lists.
Further information about the CMW and CandleNet PortalFor further information about CandleNet Portal, refer to the product’s online help and to the Administering OMEGAMON Products: CandleNet Portal Guide.
For further information about using the CMW for user administration, refer to the Candle Management Workstation Administrator’s Guide as well as the CMW help.
What is OMEGAMON DE?The OMEGAMON DE feature package for CandleNet Portal offers a dashboard view of your enterprise. This feature provides a single point of control from which you can manage the resources your business-critical applications rely on, including a range of operating systems, servers, databases, mainframes, and Web components. It enables you to pull together the data and functionality built into all the Candle monitoring solutions.
OMEGAMON DE provides all the capability of OMEGAMON XE, plus these additional capabilities:
� Multiple applications can be displayed 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.
� You can link application workspaces
You can define a link from a workspace associated with one monitoring agent to a workspace associated with another agent.
OMEGAMON XE for WebSphere Application Server Operating Environment
60 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
� You can define enterprise-specific Navigator views
The Navigator physical view shows the hierarchy of your managed enterprise by operating platforms and types of Candle agents. The Navigator business view shows the hierarchy of any managed objects defined through the CMW. You can also define Navigator views for any logical grouping, such as a departmental or site hierarchy.
� You can define a graphic view
The graphic view enables you to retrieve and display real-time monitoring data from Candle agents. Using the graphic view, you can create a background image or import one, then place objects (Navigator items) on the image or have it done automatically using geographical coordinates. You can zoom in and you can add such graphics as floor plans and organization charts.
� You can integrate information provided by Candle’s Universal Integrator
Candle’s Universal Integrator is an agent you can configure to monitor any data you collect. It lets you integrate data from virtually any platform, any resource, and any source, such as custom applications, databases, systems, and subsystems. Your defined data providers are listed in the Navigator, and default workspaces are automatically created.
Detailed information about OMEGAMON DE is provided in the CandleNet Portal online help.
What is OMEGAMON DE Policy Management?OMEGAMON DE Policy Management incorporates all of the features of OMEGAMON XE and adds automation capabilities. 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.
Overview of the OMEGAMON XE for WebSphere Application Server Product 61
OMEGAMON XE for WebSphere Application Server Operating Environment
PathWAI Performance Analyzer product simplifies trace analysis and workload instrumentation
Among its many other capabilities, Candle’s PathWAI Performance Analyzer product allows you to:
� Import your kweliuser.xml control file, update it to specify the classes and methods to be instrumented for workload analysis, and export the updated file. With PathWAI Performance Analyzer, you can browse the contents of a jar, ear, or war or ear file and select the classes and methods you want instrumented.
� Analyze application trace data in ways CandleNet Portal never could, including the viewing of vastly greater quantities of trace data. Among its other enhancements, PathWAI Performance Analyzer adds a graphical trace viewer and a tree view of your methods’ calling parameters.
This new capability obviates the previous Application Trace workspace (but not the Application Trace Files workspace or the Take Action commands that let you start or stop application tracing and delete application trace files).
For complete information, see the online PathWAI Performance Analyzer User Guide.
Historical data collectionYou can use the facilities of CandleNet Portal’s historical data collection function to store and save the data being collected by your OMEGAMON XE for WebSphere Application Server agents.
The historical data collection function permits you to specify
� the attribute group or groups for which data is to be collected
� the interval at which data is to be collected
� the interval at which data is to be warehoused (if you choose to do so)
� the location (either at the agent or at the CMS) at which the collected data is to be stored
To ensure that data samplings are saved to populate your predefined historical workspaces, you must first configure and start historical data collection. This requirement does not apply to workspaces that use attribute groups that are
OMEGAMON XE for WebSphere Application Server Operating Environment
62 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
historical in nature and show all their entries without you having to start data collection. See the Historical Data Collection Guide for OMEGAMON XE and CandleNet Command Center for information. The CandleNet Portal online help also contains additional information about using this historical reporting feature.
Overview of the OMEGAMON XE for WebSphere Application Server Product 63
Introducing OMEGAMON XE for WebSphere Application Server
Introducing OMEGAMON XE for WebSphere Application Server
What is an OMEGAMON XE agent?The OMEGAMON XE agent for WebSphere Application Server is an intelligent agent that resides on managed distributed systems that use the IBM WebSphere Application Server product. As a monitoring agent, it collects and distributes real-time and historical performance data as needed to a CMS.
What this agent doesThe OMEGAMON XE for WebSphere Application Server agent enables you to monitor the health and availability of your WebSphere Application Server environment, as well as the performance of the deployed J2EE applications.
In particular, you can use the OMEGAMON XE agent in the following ways:
� report current data and monitor performance for multiple platforms, operating systems, and applications
� track and report the status of the WebSphere Application Server application servers in your enterprise
� centrally administer WebSphere Application Servers in your enterprise, including starting and stopping servers and setting instrumentation levels to control performance data collection
� perform workload analysis to monitor application transactions that are running in an application server
� collect and report traffic and resource use within each WebSphere Application Server
� report activity levels for each Enterprise Java Beans (EJB) container defined in each application server
� report activity levels for the enterprise bean object pools associated with Enterprise beans
� collect and report statistics on EJB transactions� report activity levels for individual enterprise beans, including method
invocation data
Introducing OMEGAMON XE for WebSphere Application Server
64 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
� collect and report utilization and contention for the database connection pools associated with each application server
� collect and report activity levels associated with each Web application running in each application server’s servlet engine
� report statistical information associated with each servlet or the Java Server Pages running in the application servers
� report statistical information on HTTP sessions� report error and exception conditions for the application servers, as
recorded in the each server’s log file� examine the performance of your application servers� provide needed monitoring tools, statistics, and information� identify performance problems� analyze data to determine if the Java virtual machine (JVM), thread pools,
the application server, servlets, Enterprise beans or workloads are consuming capacity beyond the limits of your hardware and software
� identify bottlenecks in ebusiness applications� invoke Take Action commands to avoid costly downtime and
performance slowdowns
Workload analysis and application tracingThe Candle workload analysis feature reports data about application transactions that are running in an application server. This data let you see how often transactions run, their response times, and causes of performance degradation. Workload analysis lets you define a workload for a servlet, JSP, or EJB method, or with any method invocation including your own, to monitor its execution. By examining the delay factors associated with a workload, you can determine what factors affect response time for transactions.
Usually you will want to define workloads that represent business functions. As a result of running workload analysis, you discover that the workloads are being delayed by, for example, connecting to a JDBC database or making an SQL request.
Workload analysis lets you collect
Overview of the OMEGAMON XE for WebSphere Application Server Product 65
Introducing OMEGAMON XE for WebSphere Application Server
� aggregate data on each workload that ran along with detailed information about delays that contributed to the response time of the workload
� workload exception information that reports response times and delays for individual workloads
� aggregate data for defined data sources � HTTP session data� information about transactions running against the CICS Transaction
Gateway (CTG) and about JCA transactions (JCA allows J2EE applications to connect to backend enterprise information systems).
� Java Messaging Service (JMS) data for WebSphere MQ queues accessed by WebSphere Application Server applications
To collect this data, the OMEGAMON XE agent uses an instrumentation process, which inserts hooks into application classes and system classes as they are loaded into the JVM. You need to complete several steps to setup this workload analysis feature. These steps include running the setupCandleWAEnabler shell script, customizing WebSphere Application Server configuration, and setting up the workload analysis instrumentation file, kweiuser.xml.
See “Preparing the Instrumentation Control File for Workloads and Application Traces” on page 117 for information about defining workload collection parameters in kweiuser.xml and “Collecting Workload Analysis, Application Trace, and Heap Data” on page 143 for information about running the shell script and collecting workload data.
The agent also provides several Take Action commands that let you control the collection of workload analysis data and manage application traces. See “The CandleNet Portal Take Action Commands” on page 177 for information about these commands.
How the agent worksEach OMEGAMON XE agent collects information about one WebSphere Application Server node. The interface for CandleNet Portal enables you to view the data and monitor the health and performance of your WebSphere Application Server environment.
OMEGAMON XE agent performs the following types of monitoring functions.
Introducing OMEGAMON XE for WebSphere Application Server
66 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
� It obtains data from a WebSphere Application Server and uses it to create various views of data that you choose. These graphic views and reports are useful for examining the performance of the WebSphere Application Server system.
� It evaluates situations to detect when OMEGAMON XE for WebSphere Application Server attribute values exceed preset thresholds you have defined and makes this exception information available to you.
Monitoring for exceptions requires you to create situations that are meaningful to the WebSphere Application Server conditions you are monitoring.
Product packages that include this agentThe OMEGAMON XE agent for WebSphere Application Server is included in these Candle product packages:
� PathWAI Deployment for WebSphere on Distributed� PathWAI Dashboard for WebSphere Infrastructure on Distributed� PathWAI Monitor for WebSphere Application Server on Distributed� PathWAI Tuning Workbench for J2EE on Distributed� OMEGAMON XE for WebSphere Application Server on Distributed
Overview of the OMEGAMON XE for WebSphere Application Server Product 67
Situations for OMEGAMON XE for WebSphere Application Server
Situations for OMEGAMON XE for WebSphere Application Server
Predefined situationsOMEGAMON XE for WebSphere Application Server provides predefined situations to monitor key attributes. You can use these situations
� to immediately begin monitoring your WebSphere Application Servers� to monitor and manage through localized automation, widely dispersed
resources� as models for creating your own situations
The predefined situations issue a Critical alert whenever they are triggered. You can investigate an event by opening its workspace. If you choose to modify the situations shipped with your product, first make a copy to ensure its recovery if necessary. See the online help for the OMEGAMON XE agent for detailed information about these predefined situations.
How situations workSituations are expressions of system conditions you want to monitor that are embedded in IF-TRUE statements. This means that if the specified condition exists, then this situation is true. You can use situations to monitor particular conditions on managed systems. For example, you might want to monitor errors for a particular Web application. Situations can monitor conditions on one or more managed systems in your enterprise.
Avoid using negative valuesIf you define a situation that uses a range of numbers, always provide a threshold and set the values for a positive range of numbers. For example, use a greater-than or equal-to-zero expression. This prevents a situation from falsely tripping if the agent encounters a missing attribute value that it interprets as a negative number.
Situations for OMEGAMON XE for WebSphere Application Server
68 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Available predefined situationsOMEGAMON XE for WebSphere Application Server provides the following predefined situations that you can use to monitor your system.
In-depth information about situationsFor more information about using pre-defined situations, creating your own situations, refer to the following product information:
� To find information about the pre-defined situations for the WebSphere Application Server, see the agent’s online help.
� To create and use situations from CandleNet Portal, refer to the Administering OMEGAMON Products: CandleNet Portal Guide. The help for CandleNet Portal also provides additional information.
� To create and use situations from the CMW, refer to the Candle Management Workstation Administrator’s Guide. The CMW help provides additional information.
Table 3. Predefined Situations for the OMEGAMON XE Agent
Situation Function
WebSphere_Application_Svr_Err Monitors error messages for WebSphere Application Server
WebSphere_Servlets_JSPs_Error Monitors the error count for servlets and JSPs
WebSphere_Start_AppServer Monitors the status of the WebSphere Application Server and automatically restarts the server if it is stopped
WebSphere_Web_Application_Error Monitors the error count for Web applications
WebSphereContainerTransRollBack Monitors the transaction-roll-back count for global and local transactions for containers
WebSphereDBConnPoolsThrdTimeOut Monitors the thread-time-out count for DB connection pools
Overview of the OMEGAMON XE for WebSphere Application Server Product 69
Take Action Commands
Take Action Commands
Overview
The Take Action feature lets you stop or start a process at any system in your network where one or more OMEGAMON XE agents are installed. You can implement Take Action commands from a workspace, from a situation, in an ad hoc mode, or by recalling a saved Take Action command. See the CandleNet Portal online help for using Take Action commands in general.
Predefined Take Action commandsOMEGAMON XE for WebSphere Application Server provides several predefined Take Action commands. You can issue commands from the browser interface to:
� stop, start, and recycle an application server
� adjust the instrumentation level for various WebSphere Application Server resources that you want to monitor such as database connection pools and HTTP sessions
� dynamically configure WebSphere Application Server for workload analysis and/or the collection of garbage-collection statistics
� collect workload analysis data and set workload exception thresholds
� start and stop application tracing, and delete application trace files
Because of high overhead, some data is not automatically collected and reported in certain workspaces. Use the Take Action commands to set the instrumentation level for certain attributes as indicated, and to accumulate workload analysis, application trace, and garbage-collection information.
For descriptions of these predefined commands and explanations of each of their functions, see “The CandleNet Portal Take Action Commands” on page 177.
Take Action Commands
70 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
An Introduction to Configuration 71
An Introduction toConfiguration
OverviewThis chapter presents an introduction to configuration concepts, product components, and tools that you will use to manage certain operations of OMEGAMON XE for WebSphere Application Server.
Chapter contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72When and why do you configure the agent?. . . . . . . . . . . . . . . . . . . . . . . . . . 72
Configuration Basics About Your Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Product components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Supported WebSphere Application Server Versions and Configurations . . . . . 77How are the product components configured? . . . . . . . . . . . . . . . . . . . . . . . . 78UNIX requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Applying product maintenance: IBM service packs . . . . . . . . . . . . . . . . . . . . . 80Restarting the application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
2
Introduction
72 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Introduction
Chapter goalsThis chapter introduces configuration section and basic configuration information that affects the operation of the OMEGAMON XE for WebSphere Application Server agent, KWEAGENT. This chapter
� presents an overview of the product components
� introduces the basic configuration mechanisms for the OMEGAMON XE agent
� provides cross-references to detailed information about how to configure various product features
PrerequisitesThis user’s guide assumes that you
� have installed CandleNet Portal and OMEGAMON XE for WebSphere Application Server from the product CD-ROM
� are familiar with the WebSphere administrative console
� have read Chapter 1 in this user’s guide to become familiar with the product’s operating environment and general features
When and why do you configure the agent?The default configuration values for KWEAGENT that you define during the installation process should suit most installations initially. They reflect the configuration choices that you supplied during the installation process.
However, from time to time you will likely want to change some configuration settings to activate and deactivate certain product features. Several types of data collection are turned off by default because of the overhead they incur. Other types of data collection require custom settings that you must provide to reflect your operating environment and data collection needs.
An Introduction to Configuration 73
Configuration Basics About Your Agent
Configuration Basics About Your Agent
IntroductionThis topic looks at the components of the OMEGAMON XE for WebSphere Application Server product and introduces key configuration mechanisms that control certain operations and data collection for the product.
Product componentsFigure 1 on page 74 shows the product components and how data is transmitted among them and the IBM WebSphere Application Server V4 product (Figure 2 on page 75 and Figure 3 on page 76 show the V5 environment in either of two configurations, base deployment and network deployment). Note the Candle workload collector: the OMEGAMON XE agent uses this product component to gather workload analysis, application trace data, and Java Virtual Machine (JVM) garbage-collection statistics from a WebSphere Application Server.
Configuration Basics About Your Agent
74 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 1. Product Components for OMEGAMON XE for WebSphere Application Server V4
OMEGAMON XEAgent
(KWEAGENT)
CNP
CMS
WebSphereAdministrative
Server
WebSphereApplication
Server
Workload Analysis
Monitored Node
Java Virtual Machine
Collector
An Introduction to Configuration 75
Configuration Basics About Your Agent
Figure 2. Product Components for OMEGAMON XE for WebSphere Application Server V5—Base Deployment Configuration
OMEGAMON XEAgent
(KWEAGENT)
CNP
CMS
Monitored Node
WebSphere V5 instance
Performance
InfrastructureMonitoring
Workload AnalysisCollector
Configuration Basics About Your Agent
76 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 3. Product Components for OMEGAMON XE for WebSphere Application Server V5—Network Deployment Configuration
OMEGAMON XEAgent
(KWEAGENT)
CNP
CMS
Monitored Node
WebSphere V5 Node Agent
Workload AnalysisCollector
Performance
InfrastructureMonitoring
Managed Process
An Introduction to Configuration 77
Configuration Basics About Your Agent
Supported WebSphere Application Server Versions and Configurations
Candle’s OMEGAMON XE agent supports these WebSphere Application Server versions:
� WebSphere Application Server V4 Advanced Edition� WebSphere Application Server V5 Base Deployment, Network
Deployment, and Enterprise Edition
OMEGAMON does not support the following WebSphere Application Server versions:
� WebSphere Application Server V4 Single-Server Edition� WebSphere Application Server V5 WSINSTANCE servers
A single OMEGAMON XE agent can monitor only one WebSphere Application Server version at a time and only WebSphere application servers running on the same physical machine. Thus, if you have WebSphere Application Server V4 and WebSphere Application Server V5 running on a single system, you must run two instances of the OMEGAMON XE agent to monitor them simultaneously, one for V4 and one for V5.
For WebSphere Application Server V5 Network Deployment, all members of the cell running on the same physical node are monitored.
Refer to IBM’s WebSphere Application Server documentation for more information on these various types of configurations.
Configuration Basics About Your Agent
78 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
How are the product components configured?You should become acquainted with several configuration mechanisms that affect operations of certain product components. The following identifies these components and the configuration mechanisms that affect them.
CNP CandleNet Portal (CNP) is the user interface for OMEGAMON XE agents. It provides status of your enterprise and the views of the data that KWEAGENT collects. CNP also gives you access to Take Actions commands and situations that you can use further customize data collection and reporting.
CMS This component controls framework operations for Candle Technologies (CT) and CandleNet Portal. It uses its environmental variables to obtain information about the operating environment and its functions.
You can change the default settings for these environmental variables if needed. For example, certain debugging and tracing options are turned off by default. See “Using Your Agent’s Environment Variables” on page 112 for more information.
KWEAGENT This component is the OMEGAMON XE for WebSphere Application Server agent. It uses the kwe.xml file to define its default configuration and operation. For example, some of the configuration parameters in this file control the collection of certain types of data related to the workload analysis component. You can also add optional parameters that you may want to use for your installation.
The reporting of certain data is turned off by default because of the high overhead associated with its collection. You must edit the configuration file to enable certain types of data collection. See “Your Agent’s Configuration Parameters and XML Tags” on page 91 for more information.
Candle workload collector
This component uses the kweiuser.xml file to track the workloads that you define for your operation. In addition, the workload collector (also called a “collector session”) requires that you run a class loader setup script on WebSphere Application Server to enable the collection of workload data. See “Collecting Workload Analysis, Application Trace, and Heap Data” on page 143 for more information.
The workload collector is also required to collect garbage-collection statistics for a particular Java Virtual Machine.
An Introduction to Configuration 79
Configuration Basics About Your Agent
UNIX requirementsThe OMEGAMON XE monitoring agent for WebSphere Application Server, kweagent, can run with or without root authority on UNIX platforms. However, if the OMEGAMON XE agent is started with a nonroot user ID, you must grant this user ID read access to the following files:
For WebSphere Application Server V4:
� WASROOT/properties/sas.server.props
� WASROOT/properties/sas.client.props
� WASROOT/bin/admin.config
where WASROOT is the directory in which WebSphere Application Server V4 is installed. Use this user ID to start kweagent instead of using a user ID that has root authority.
If you do not want to give the OMEGAMON XE agent agent read access to these files, you can specify alternate file names that contain the contents of these files and that supply the monitoring agent with needed information. The SasServerProps and SasClientProps parameters in the kwe.xml file (described on page 100) identify a pair of files that the agent should read instead of sas.server.props and sas.client.props, respectively; similarly, if the agent doesn't have read access to the admin.config file, you must provide the kwe.xml NamingServerPort parameter (described on page 100), unless you allow OMEGAMON XE for WebSphere Application Server to use the default naming server port, 900. For information on these kwe.xml parameters, see “Your Agent’s Configuration Parameters and XML Tags” on page 91.
For WebSphere Application Server V5:
� WASROOT/bin/setupCmdLine.sh
� WASROOT/properties/wsadmin.properties
� WASROOT/config (including all subdirectories and files)
where WASROOT is the directory in which WebSphere Application Server V5 is installed. Use this user ID to start kweagent instead of using a user ID that has root authority.
If your site has enabled WebSphere Application Server global security, also configure the SOAPClientProps parameter in the kwe.xml file (described on page 101). This information enables the agent to be authenticated by your
Configuration Basics About Your Agent
80 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
WebSphere Application Server security infrastructure. For information on the SOAPClientProp parameter, see “Your Agent’s Configuration Parameters and XML Tags” on page 91.
Historical data collection in Linux
If your site uses Linux as its WebSphere Application Server operating environment, you need to synchronize historical data collection at the agent with the timezone of the CandleNet Portal client. To do this, set a time zone variable in the Linux /etc/profile file. For example, to set the Linux time zone to the U.S. Pacific time zone:
1. For Red Hat Linux, set:ZONE="US/Pacific"export ZONE
For SuSE Linux, set:
TIMEZONE="US/Pacific"export TIMEZONE
2. Reboot your Linux machine.
Applying product maintenance: IBM service packsStop the Candle WebSphere Application Server monitoring agent before you install any fixpacks for WebSphere Application Server. Attempting to install an IBM WebSphere Application Server service pack while the Candle monitoring agent is running can cause your WebSphere Application Server environment not to function.
Restarting the application serverWhenever you change the WebSphere Application Server environment, you must restart the application server for the changes to take affect. You also need to restart the application server after applying maintenance to or upgrading the OMEGAMON XE agent.
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 81
Setting Configuration Parameters,Environmental Variables, and
Instrumentation Levels
OverviewThis chapter discusses the default configuration parameters and environment variables that are used for OMEGAMON XE for WebSphere Application Server. It also contains instructions for setting the instrumentation levels so the OMEGAMON XE agent can collect PMI performance data.
Chapter contents
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Chapter goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
A Look Inside Your Agent’s Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . 85What are the kwe.xml default parameters? . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Configuration files for multiple agents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Sample parameter defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Additional configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Sample definitions for all configuration values . . . . . . . . . . . . . . . . . . . . . . . . 89
Your Agent’s Configuration Parameters and XML Tags . . . . . . . . . . . . . . . . . . . . . 91KWEAGENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91MonitorAppServer tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Using Your Agent’s Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112What are the environment variables? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Variables for OMEGAMON XE for WebSphere Application Server . . . . . . . . 112
Setting Instrumentation Levels to Collect PMI Data . . . . . . . . . . . . . . . . . . . . . . . 115Setting instrumentation levels dynamically via CandleNet Portal. . . . . . . . . . 115
3
82 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Setting instrumentation levels from the WebSphere administrative console forV4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Setting instrumentation levels from the WebSphere administrative console forV5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 83
Getting Started
Getting Started
BackgroundThe intelligent remote agent (IRA), KWEAGENT, for OMEGAMON XE for WebSphere Application Server uses environment variables, configuration parameters, and instrumentation settings in its operation. This chapter discusses the environment variables and basic configuration parameters. It covers their use and the changes you can make to the default installation settings. See “Preparing the Instrumentation Control File for Workloads and Application Traces” on page 117 for information about parameters for defining workloads for workload analysis.
Chapter goalsThis chapter contains detailed configuration information that enables you to modify the operation of the OMEGAMON XE for WebSphere Application Server agent. It contains
� an example of the default configuration settings for the OMEGAMON XE agent
� an example of optional configuration parameters that you can add to the configuration for the OMEGAMON XE agent
� detailed descriptions of each configuration parameter
� descriptions of each of the environment variables that affect the operation of Candle Technologies (CT) environment, which supports the Candle products
Configuration parametersThe kwe.xml file, which is placed on your system during the installation of the OMEGAMON XE for WebSphere Application Server, contains the configuration parameters for the agent. See Figure 4 on page 88 for an example of kwe.xml and its default settings. The parameters and settings in this file control the general operation of the OMEGAMON XE agent.
At the end of the installation procedure, you will be given an opportunity to view and edit the kwe.xml file that contains the parameter settings for the
Getting Started
84 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
OMEGAMON XE agent. You can also edit this file whenever you need to change its configuration parameters that control the collection of certain types of data.
If you choose, you can add optional configuration parameters to the kwe.xml file for your installation. Examples of these optional parameter are provided in the kwesmpl.xml file. This file is also placed on your system when you install OMEGAMON XE for WebSphere Application Server. See Figure 5 on page 90 for an example of kwesmpl.xml and its location and contents.
For descriptions about all possible configuration variables, their use, values, and default settings, see “Your Agent’s Configuration Parameters and XML Tags” on page 91.
Note: Before you edit the default kwe.xml file, make a backup copy for security.
Environment variablesThe OMEGAMON XE environment that supports OMEGAMON XE for WebSphere Application Server uses IRA environment variables that affect the operation of the KWEAGENT agent. See “Using Your Agent’s Environment Variables” on page 112 for the descriptions of the variables that are used by KWEAGENT.
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 85
A Look Inside Your Agent’s Configuration Files
A Look Inside Your Agent’s Configuration Files
IntroductionThis topic presents two examples of configuration files that are installed on your system. One is the kwe.xml file that contains the default parameters for the KWEAGENT agent. The other example is the kwesmpl.xml file that contains sample settings for all the configuration parameters that you might want to set.
What are the kwe.xml default parameters?The default parameters that determine the basic operational and monitoring characteristics of the agent reside in kwe.xml file that is created during the installation process. these defaults should suit most installation sites initially. From time to time, you will probably change these defaults to meet your specific needs and tailor the type and amount of data that the agent monitors and reports.
Location of the kwe.xml parameter file
If you use the installation location defaults, you will find the kwe.xml file in the following locations:
� For Windows systems, the file is in the C:\Candle\CMA directory.
� For UNIX systems, the file is in the $CANDLEHOME$/config/ directory, where $CANDLEHOME$ is the directory where you installed your site’s Candle software.
Configuration files for multiple agentsTo support multiple agents on the same system, the installation process creates separate configuration files for each secondary instance and assigns each of these files a unique name.
Windows systems
On Windows systems, the task name for a secondary agent becomes part of the configuration file name for the secondary agent. For example, if you add
A Look Inside Your Agent’s Configuration Files
86 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
an agent with a task name of Secondary, the name of the configuration file for this instance becomes kwe_Secondary.xml.
UNIX systems
On UNIX systems, the AgentId for a secondary agent becomes part of the configuration file name for the agent. For example, if you add an agent whose AgentId is test, the name of the configuration file for this instance becomes kwe_test_##_<HOSTNAME>.xml, where <HOSTNAME> is the name of the host on which the configuration file was generated.
Parameters for secondary agents
The definitions for the following parameters are also significant in creating configuration files for secondary agent on Windows and UNIX platforms.
WASAppServerRoot Indicates the directory path name to the location of the WebSphere Application Server. Required on UNIX and on Windows if multiple WebSphere Application Server versions are running on this node.
CollectorSessionPort Indicates the number of the IP port number that the workload analysis component will use to communicate with the workload analysis and garbage-collection components within the application servers to be monitored. Required
Note: Always pick an IP port not in use by any other application. If you are running multiple agents on a single node, each secondary agent needs a unique CollectorSessionPort value. If you need to change the default port, valid values are between 1 and 65535; please contact your network administrator to assign a valid port that is not used by other applications.
AgentID Provides an identifier for the secondary agent and becomes part of the name of the configuration file for the secondary agent. (Required for secondary agents)
Note: If you are running multiple agents on a single node, each secondary agent needs a unique AgentID value.
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 87
A Look Inside Your Agent’s Configuration Files
Sample parameter defaultsThe default kwe.xml file in Figure 4 on page 88 contains the basic parameters and settings. For a detailed description of these parameters, see “Your Agent’s Configuration Parameters and XML Tags” on page 91.
AppTraceDirectory Identifies the root directory in which the application trace files are stored for the secondary agent. The installation process will automatically create this directory if it does not exist.
A Look Inside Your Agent’s Configuration Files
88 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 4. Sample Default Parameters in kwe.xml
Additional configuration parametersThe default configuration file, kwe.xml, defines basic required values for the configuration parameters. In addition to this file, OMEGAMON XE for WebSphere Application Server also includes a sample configuration file, kwesmpl.xml, that shows the usage of all the configuration parameters that you might want to specify for your installation.
<?xml version="1.0" encoding="UTF-8" ?>
<KWEAGENT VERSION="130" AgentID="" CollectorSessionPort="65535" DefaultCollectHeapClasses="*" DefaultCollectHeapLevel="High" DefaultCollectLockAnalysisMinCost="0" DefaultCollectorSessionSampleInterval="60" DefaultCollectWorkloadClassName="*" DefaultCollectWorkloadClassType="A" DefaultExceptionWorkloadMax="20" DefaultExceptionWorkloadMinRespTime="0" DefaultExceptionWorkloadName="*" DefaultExclude="No" DefaultGCCollect="Y" DefaultInflightThreshold="0" DefaultLockAnalysisLevel="High" DefaultLogScanInterval="60" DefaultMinimumSamplingInterval="20" DefaultRetainLogFileEvents="15" DefaultStatisticInterval="0" DiscoverInterval="900" JavaLogFileName="KWERAS1_Java.log" NamingServerPort="900" RetainProductEvents="50" TakeActionAuthUsers="*" WASAppServerRoot="" />
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 89
A Look Inside Your Agent’s Configuration Files
Sample definitions for all configuration valuesThe sample configuration file, kwesmpl.xml, in Figure 5 on page 90 shows the usage of all the KWEAGENT parameters. For a detailed description of these parameters, see “Your Agent’s Configuration Parameters and XML Tags” on page 91. You can find the sample kwesmpl.xml file in the following locations.
� For a Windows system, the kwesmpl.xml file is inC:\Candle\CMA
� For an AIX system, the kwesmpl.xml file is in $CANDLEHOME$/config/aix433/we/files
where $CANDLEHOME$ is the directory where you installed your site’s Candle software.
� For a Solaris system, the kwesmpl.xml file is in $CANDLEHOME$/config/sol273/we/files
� For an HP-UX system, the kwesmpl.xml file is in $CANDLEHOME$/config/hp11/we/files
� For a Linux system running on Intel hardware, the kwesmpl.xml file is in $CANDLEHOME$/config/li6243/we/files
� For a Linux system running on zSeries hardware, the kwesmpl.xml file is in $CANDLEHOME$/config/ls3223/we/files
A Look Inside Your Agent’s Configuration Files
90 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 5. Expanded Configuration Parameters in kwesmpl.xml
<KWEAGENT Version="130" CollectorSessionPort="65535" DefaultCollectHeapClasses="*" DefaultCollectHeapLevel="High" DefaultCollectLockAnalysisMinCost="0" DefaultCollectorSessionSampleInterval="60" DefaultCollectWorkloadClassName="*" DefaultCollectWorkloadClassType="A" DefaultExceptionWorkloadMax="20" DefaultExceptionWorkloadMinRespTime="0" DefaultExceptionWorkloadName="*" DefaultExclude="No" DefaultGCCollect="Y" DefaultInflightThreshold="0" DefaultLockAnalysisLevel="High" DefaultLogScanInterval="60" DefaultMinimumSamplingInterval="20" DefaultRetainLogFileEvents="15" DefaultStatisticInterval="0" DiscoverInterval="900" JavaLogFileName="KWERAS1_Java.log" NamingServerPort="900" RetainProductEvents="50" TakeActionAuthUsers="*" WASAppServerRoot=""> <MonitorAppServer Name="All Application Servers default" CollectorSessionSampleInterval="60" Exclude="No" LogScanInterval="60" RetainLogFileEvents="5" StatisticInterval="0" SubnodeAliasName="" TakeActionAuthUsers="*" /></KWEAGENT>
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 91
Your Agent’s Configuration Parameters and XML Tags
Your Agent’s Configuration Parameters and XML Tags
IntroductionThis topic covers each of the parameters in the kwe.xml file that can be used to configure the KWEAGENT agent. It describes their uses and values and provides their default settings. The following is a complete list of the keywords for the KWEAGENT and MonitorAppServer XML tags and their values.
Note that only a few of these keywords are used in the default kwe.xml configuration file shown in “Sample Default Parameters in kwe.xml” on page 88. The others are optional keywords that you can use to customize the operation of the agent and the type of data it collects. The kwesmpl.xml file in “Expanded Configuration Parameters in kwesmpl.xml” on page 90 contains an example of all the keywords. The keywords are organized alphabetically under each XML tag.
KWEAGENTThe KWEAGENT XML tag encapsulates all parameters for the agent. The attributes that follow this tag apply to the agent as a whole. They specify monitoring and connection defaults that can be overridden if desired at the individual application server level by the MonitorAppServer tag. All are optional except the Version attribute.
AgentId
This parameter gives a very short identifier for the agent. Specify this attribute if there will be multiple KWEAGENTs running on the same host system. Each separate agent needs a different identifier so that the nodes on the same host do not have the same name. The default agent ID is "" (none).
AppTraceDirectory
This keyword identifies the root directory where the application trace files are stored. The valid format is a fully-qualified directory name. Both the WebSphere Application Server and the Candle monitoring agent must have read-write authority to this directory. The default for this parameter is the Candle agent log directory (for example, C:\Candle\CMA\logs on Windows; /$CANDLEHOME$/logs on UNIX).
Your Agent’s Configuration Parameters and XML Tags
92 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
CollectorSessionPort
This parameter indicates the IP port number the monitoring agent will use for communicating with the workload analysis and garbage-collection components of the application servers being monitored. The default is 65535.
DefaultCollectHeapClasses
Specifies the instantiated classes to which the heap collection level set by the DefaultCollectHeapLevel attribute applies for all application servers, unless explicitly overridden for a particular application server. This value comprises one or more class masks separated by semicolons; each class mask can contain '*' and '?' wildcard characters. Note that the classes specified here are instantiated class names. The default is blanks (that is, no classes).
You may also specify exclusion masks. An exclusion mask identifies classes to be specifically excluded from collection. An exclusion mask begins with a exclamation point (!) and is followed by a class mask. Heap data for any class that matches an exclusion mask is not collected. For example, DefaultCollectHeapClasses="*;!java.lang*" says that heap analysis data should be collected for all instantiated classes except those that match the mask java.lang*.
The DefaultCollectHeapClasses attribute may contain two special keyword masks:
Value Meaning
%COLLECTIONS% Indicates that heap collection should be performed on any instantiated class that implements one of the standard Java collection interfaces.
%ARRAYS% Indicates that heap analysis should be performed on all instrumented array instantiations.
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 93
Your Agent’s Configuration Parameters and XML Tags
DefaultCollectHeapLevel
Specifies the default level of heap statistics to be collected by workload analysis for all application servers, unless specifically overridden for a particular application server. Possible values are:
DefaultCollectHistorical
Defines which historical data is to be collected by the agent. This attribute applies to all application servers, unless it is overidden by the specification of the CollectHistorical attribute for an individual application server on the MonitorAppServer tag. (See “MonitorAppServer tag” on page 103.) Possible values are:
The default value is ALL. Multiple keywords (other than NONE or ALL) can be specified, separated by commas.
Value Meaning
none no heap statistics are collected
Low the number of objects allocated by each workload are tracked
Medium in addition to the data collected by collection level Low, object allocation and garbage collection by Java class, workload, and associated workload delay are also tracked
High In addition to the data collected by collection level Medium, individual heap objects are also tracked
Value Meaning
NONE No historical data is to be collected.
ALL History is to be collected for all data.
PMI History is to be collected for PMI data.
WA History is to be collected for workload analysis data.
Verbose GC
History is to be collected for garbage collection data.
Heap History is to be collected for heap analysis data.
Lock History is to be collected for lock analysis data.
Your Agent’s Configuration Parameters and XML Tags
94 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Example: To collect only historical PMI and Garbage Collection data, specify:
DefaultCollectHistorical="PMI,VerboseGC"
Note: The setting of this attribute is independent of the historical configuration setting within the CandleNet Portal. Therefore, there could be differences in these specifications for the collection of historical data, resulting in inconsistent data collection results. It is recommended that you set historical configuration within CandleNet Portal consistent with the above attribute. See the topic on configuring historical data collection in the CandleNet Portal help or user’s guide. See also the Historical Data Collection Guide for OMEGAMON XE and CandleNet Command Center.
DefaultCollectLockAnalysisMinCost
This keyword defines the smallest locking cost (the time in milliseconds for a workload to acquire a synchronization lock) that will be collected. The valid format is an integer. The default value for this parameter is 0.
DefaultCollectorSessionSampleInterval
This parameter provides the default sampling interval for both workload analysis data and garbage-collection data for each application server, in seconds. If this value is nonzero, the KWEAGENT will collect data from the application servers based on the time specified. If this value is 0, then the agent will collect data from the application servers only when requested. The default is 60.
DefaultCollectWorkloadClassName
This keyword is used in combination with the DefaultCollectWorkloadClassType parameter to identify those classes for which workload analysis data is to be collected. This keyword can specify multiple masks, separated by commas or semicolons. The masks can contain the asterisk (*) and question mark (?) wildcard characters.
To collect workload analysis data for a class, the class must have a type in the DefaultCollectWorkloadClassType list and a name that matches one of the DefaultCollectWorkloadClassName masks.
You may also specify exclusion masks for DefaultCollectWorkloadClassName. An exclusion mask identifies classes to be specifically excluded from
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 95
Your Agent’s Configuration Parameters and XML Tags
collection. An exclusion mask begins with a exclamation point (!) and is followed by a class mask. Workload data for any class that matches an exclusion mask is not collected. For example, DefaultCollectWorkloadClassName="*;!trade*" says workload data should be collected for all classes except for those that match the mask trade*.
DefaultCollectWorkloadClassType
This keyword specifies the type of workload analysis data that will be collected by default for all application servers. The valid format is an alphabetic string of one or more of the following characters. Each character, shown in the following list, represents a specific type of workload data that should be collected.
DefaultCollectWorkloadMaxDepth
Indicates the maximum stack depth at which instrumentation is to be enabled for all application servers. The valid value is a numeral. This attribute is only effective for those classes which have been instrumented with the DepthSensitiveInstrumentation attribute set to a value of ‘true”. This attribute has no meaning if classes are not instrumented using Depth Sensitive Instrumentation. This value can be overridden for a particular application server with the CollectWorkloadMaxDepth attribute specified at the
Value Meaning
A Indicates that all workload data should be collected
B Indicates that workload data for EJB-related classes should be collected
C Indicates that workload data for JCA-related classes should be collected
D Indicates that workload data for SQL-related classes should be collected
G Indicates that workload data for CTG-related classes should be collected
I Indicates the workload date of JNDI-related classes should be collected
M Indicates that workload data for user-defined methods should be collected
Q Indicates that workload data for JMS-related classes should be collected
S Indicates that workload data for servlet classes should be collected
T Indicates that workload data for transaction-related classes should be collected
Your Agent’s Configuration Parameters and XML Tags
96 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
MonitorAppServer level. The default value is 0, which indicates that Depth Sensitive Instrumentation is effectively disabled. The value of 0 for this attribute indicates that instrumentation is not sensitive to the stack depth and is enabled at all depths.
DefaultExceptionWorkloadMax
This keyword sets a limit on the number of exception transactions for each workload identified by the DefaultExceptionWorkloadName parameter. These transactions are those that are reported for exceeding the limits you set for your site. These exceptions are displayed in the Longest Running Workloads workspace. The valid format contains a positive number that specifies the maximum number of exception transactions to collect for each workload.
DefaultExceptionWorkloadMinRespTime
This keyword specifies a response time threshold for reporting exception transactions. Transactions having lower response times than this threshold value are not reported in the Longest Running Workloads workspace. The valid format contains a positive number that specifies the number of milliseconds.
DefaultExceptionWorkloadName
This keyword identifies the class name or names of the workloads for which exception transactions are to be collected. It applies to all application servers. The valid format is one or more masks, separated by commas, that may contain the asterisk (*) and question mark (?) wildcard characters to identify the class or classes on the application servers for which exceptions are to be collected. If this keyword is omitted, workload exception data is not collected for application servers unless specified at the application server level or by a Set Workload Exception Thresholds Take Action command.
DefaultExclude="Yes|No"
This parameter indicates whether or not the application servers are to be monitored by default. If DefaultExclude is set to a value of Yes, then no application servers are monitored, unless there is an overriding Exclude value specified for a particular application server.
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 97
Your Agent’s Configuration Parameters and XML Tags
DefaultGCCollect="Y|N"
This parameter indicates whether or not garbage-collection data is to be collected from the application servers by default. If DefaultGCCollect is set to N, then no garbage-collection statistics are collected, unless an overriding GCCollect value is specified for a particular application server.
You may also use the WAS Verbose GC Collection Take Action command to dynamically start collecting garbage-collection data; see the OMEGAMON XE for WebSphere Application Server online help for information.
DefaultGCPollFrequency
This parameter indicates how frequently, in seconds, the workload analysis component should check the WebSphere Application Server logs for garbage-collection records.
DefaultHeapCapturePercent
Specifies the default heap capture percentage for all application servers. Only the specified percentage of heap-allocation requests (randomly selected) are measured and reported by workload analysis. This attribute can be overridden for individual application servers with the HeapCapturePercent attribute. Valid values are from 1 to 100; if not specified, the default is 100.
DefaultInflightThreshold
Specifies the minimum time, in milliseconds, that a workload can run before appearing in the In-flight Workloads Summary workspace. This threshold applies to all application servers, unless specifically overridden for a particular application server. Workloads that have been running for less than the time specified are not reported. The default is 5 (milliseconds).
DefaultLockAnalysisLevel
This keyword specifies the default level of monitor contention monitoring to be performed for all application servers, unless specifically overridden at the application server level. There are three possible values for this attribute:
Disabled Lock Analysis is disabled. This is the default value.
Enabled The cost of monitor locking is collected for each involving workload, delay and class method.
Your Agent’s Configuration Parameters and XML Tags
98 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
High In addition to the data collected by the Enabled collection level, the sources of monitor contention will be identified.
DefaultLogScanInterval
This parameter indicates the default value, in seconds, for scanning each application server log file in order to detect error or exception conditions. Periodically, based on the time provided by this parameter, the KWEAGENT will open and read any new entries written into the log file for each application server. Any new entries indicating an error or exception condition will be noted in the application server error table as a pure event. The default for this parameter is 60.
DefaultMinimumSamplingInterval
This parameter provides a default minimum interval between sample requests for a particular resource or resource type within an application server. This value is meaningful only when either the StatisticInterval paremeter or the DefaultStatisticInterval parameter is set to 0, or when either the CollectorSessionSampleInterval paremeter or the DefaultCollectorSessionSampleInterval parameter is set to 0.
This parameter specifies a minimum number of seconds for obtaining updated information from an application server for which on-demand sampling is active. For example, if DefaultMinimumSamplingInterval is set to 15 seconds and if two requests for information for the same resource or resource type are received by the OMEGAMON XE agent within 15 seconds of one another, the second request returns the identical data as the first request. The purpose of this parameter is to avoid too frequent sampling.
DefaultRetainLogFileEvents
This parameter gives a count of how many log file events to retain for viewing in reports. The default value is 5.
DefaultStatisticInterval
This parameter provides the default sampling interval for PMI data collected for each application server, in seconds. If this value is nonzero, then KWEAGENT will collect data from the application servers based on the time specified, whether or not the data is required. If this value is 0, then the agent
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 99
Your Agent’s Configuration Parameters and XML Tags
will collect data from the application servers only when required. The default value is 60.
DefaultWorkloadCapturePercent
Specifies the default workload capture percentage for all application servers. Only the specified percentage of executing workloads (randomly selected) are measured and reported by workload analysis. This attribute can be overridden for individual application servers with the WorkloadCapturePercent attribute. Valid values are from 1 to 100; if not specified, the default is 100.
DiscoverInterval
This parameter specifies how often, in minutes, KWEAGENT will poll WebSphere Application Server to search for newly defined application servers. The default is 15.
ExceptionWorkloadHistoricalMax
This parameter helps you tailor the collection of exception transactions for each unique workload. It limits the number of exception transactions that are to be saved historically for each historical period. The default is 10 transactions.
JavaLogFileName
This parameter indicates the file to which the KWEAGENT’s Java code writes trace logs. The default is KWERAS1_Java.log.
LogScanDateFormat
This parameter allows the OMEGAMON XE agent to recognize and process Japanese date formats from the WebSphere Application Server logs. The date must follow one of these formats:
dd/mm/yydd/yy/mmmm/dd/yymm/yy/ddyy/mm/ddyy/dd/mm
Your Agent’s Configuration Parameters and XML Tags
100 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
The date separator can be any special character except the exclamation point (!). The third input character is the date separator, and both date separators must be the same.
MaxReferenceSearchTime
The maximum time, in seconds, that workload analysis should spend checking for object references in order to construct the object reference workspace. If this time limit is reached, workload analysis stops looking for additional references. The default is 5 (seconds).
NamingServerPort
This parameter indicates the number of the IP port that is used to connect to the Java Naming Service for the WebSphere Application Server domain. This IP port is used to contact the naming server contained within the WebSphere administrative server. If this parameter is omitted, then the agent determines the port number by reading the admin.config file in the /WebSphere/AppServer/bin directory. If the port number cannot be obtained this way, the agent uses the default value (900).
Note: Always pick an IP port not in use by any other application. If you are running multiple agents on a single node, each secondary agent needs a unique NamingServerPort value. IIf you need to change the default port, valid values are between 1 and 65535; please contact your network administrator to assign a valid port that is not used by other applications.
RetainProductEvents
This parameter gives a count of how many product events to retain as a total for viewing in reports. These events are always reported as pure events for situations, and if historical situations are active, they can be viewed historically. However, the most recent x number of events can be viewed in regular reports where x is the count given by this parameter.
SasClientProps
Applies only to WebSphere Application Server V4.0. This parameter contains the fully qualified path name of the file containing the contents of the WebSphere Application Server sas.client.props file. If this parameter is omitted, the agent reads the contents of the
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 101
Your Agent’s Configuration Parameters and XML Tags
WASHOME/properties/sas.client.props file, where WASHOME is the WebSphere Application Server installation directory. If you do not want to give the agent read-access to this file, then copy the contents of this file to another file, and specify the fully qualified name of this file in the SasClientProps parameter.
SasServerProps
Applies only to WebSphere Application Server V4.0. This parameter contains the fully qualified path name of the file containing the contents of the WebSphere Application Server sas.server.props file. If this parameter is omitted, the agent will read the contents of the WASHOME/properties/sas.server.props file, where WASHOME is the WebSphere Application Server installation directory. If you do not want to give the agent read-access to this file, then copy the contents of this file to another file, and specify the fully qualified name of this file in the SasServerProps parameter.
SOAPClientProps
Applies only to WebSphere Application Server V5.0. This parameter contains the fully qualified path name of the WebSphere Application Server soap.client.props file property file, which contains authentication information that allows the OMEGAMON XE agent to access WebSphere Application Server system management functions when WebSphere Application Server global security is on. If this parameter is omitted, the agent reads the WASHOME/properties/soap.client.props file, where WASHOME is the WebSphere Application Server V5.0 installation directory. If you do not want to give the agent read access to this file, then copy this file to another file, and specify this file’s fully qualified name in the SOAPClientProps parameter.
To create this property file:
1. Copy WASHOME/properties/soap.client.props to either C:\Candle\CMA\logs\kweclient.soap.props (for Windows platforms) or to $CANDLEHOME$/logs/kweclient.soap.props (for UNIX platforms), where $CANDLEHOME is the OMEGAMON XE agent’s installation directory.
2. Modify these properties in the new kweclient.soap.props file: com.ibm.SOAP.securityEnabled=true com.ibm.SOAP.loginUserid= com.ibm.SOAP.loginPassword=
Your Agent’s Configuration Parameters and XML Tags
102 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Enter the correct loginUserid and loginPassword. The login userid should belong to the administrator role.
3. If the login password you specified is readable text, use the WASHOME/bin/PropFilePasswordEncoder utility to encode the loginPassword field in the kweclient.soap.props file to protect it.
Note: If you do not configure the SOAPClientProps parameter, the OMEGAMON XE agent uses the serverId and serverPassword from the activeUserRegistry in security.xml inside WASHOME\config\cells\your_cell (for Windows platforms) or WASHOME/config/cells/your_cell (for UNIX platforms) for authentication.
TakeActionAuthUsers
This parameter indicates which CandleNet Portal (CNP) users are authorized to issue Take Action commands. Note that there can be multiple entries, separated by commas, associated with this parameter. Each entry can be a ‘mask’ which can include the ‘*’ and ‘?’ wildcard characters. A CandleNet Portal user whose ID matches any mask in this list is authorized to issue a Take Action command. These CandleNet Portal user IDs are defined within the CMS and do not necessarily exist on the node on which the KWEAGENT is running.
Version
Required. This parameter gives the version of the product for which the parameters were set. The KWEAGENT will verify that a value of 130, 120, or 110 appears in this field and will not proceed until either value is found.
WASAppServerRoot
This parameter indicates the directory path name to the location where the WebSphere Application Server product is installed. This parameter is required on UNIX systems; on Windows NT systems, if this parameter is missing, the directory path is determined from the registry.
If multiple versions of WebSphere Application Server are installed on the node, then the WASAppServerRoot parameter is required on Windows to tell the agent which WebSphere Application Server version to monitor. Each copy of the agent can monitor only a single version, and the agent’s default
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 103
Your Agent’s Configuration Parameters and XML Tags
behavior is to monitor the first version specified in the registry. The WASAppServerRoot parameter must be specified explicitly and uniquely for each agent in order to monitor all versions of WebSphere Application Server.
MonitorAppServer tagThe MonitorAppServer XML tag encapsulates parameters that apply to a single application server to be monitored by the agent. This tag is optional unless the monitoring requirements for a particular application server are different from the default settings for the agent. The agent automatically discovers each application server running on the domain of the WebSphere administrative server running on the same node. If there is no specific MonitorAppServer tag for an application server, then that server is monitored using the default KWEAGENT parameters.
The following is a listing of the keywords for the MonitorAppServer tag. All are optional except the Name keyword.
CollectLockAnalysisMinCost
This keyword defines the smallest locking cost that will be collected. The valid value is an integer. The default value is the value of the DefaultCollectLockAnalysisMinCost parameter specified at the KWEAGENT level, or Disabled if the DefaultCollectLockAnalysisMinCost parameter was not specified.
CollectHeapClasses
Specifies the instantiated classes to which the heap collection level set by the CollectHeapLevel attribute applies for a particular application server. This value comprises one or more class masks separated by semicolons; each class mask can contain '*' and '?' wildcard characters. Note that the classes specified here are instantiated class names.
You may also specify exclusion masks. An exclusion mask identifies classes to be specifically excluded from collection. An exclusion mask begins with a exclamation point (!) and is followed by a class mask. Heap data for any class that matches an exclusion mask is not collected. For example, CollectHeapClasses="*;!java.lang*" says that heap analysis data should be collected for all instantiated classes except those that match the mask java.lang*.
Your Agent’s Configuration Parameters and XML Tags
104 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
The CollectHeapClasses attribute may contain two special keyword masks:
This parameter is optional.
CollectHeapLevel
Specifies the level of heap statistics to be collected by workload analysis for a particular application server. Possible values are:
This parameter is optional.
CollectHistorical
Defines which historical data is to be collected by the agent. This attribute overrides the DefaultCollectHistorical attribute specified at the KWEAGENT
Value Meaning
%COLLECTIONS% Indicates that heap collection should be performed on any instantiated class that implements one of the standard Java collection interfaces.
%ARRAYS% Indicates that heap analysis should be performed on all instrumented array instantiations.
Value Meaning
none no heap statistics are collected
Low the number of objects allocated by each workload are tracked
Medium in addition to the data collected by collection level Low, object allocation and garbage collection by Java class, workload, and associated workload delay are also tracked
High In addition to the data collected by collection level Medium, individual heap objects are also tracked
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 105
Your Agent’s Configuration Parameters and XML Tags
level for the application server associated with this MonitorAppServer tag. (See “KWEAGENT” on page 91.) Possible values are:
Multiple keywords (other than NONE or ALL) can be specified, separated by commas. The default is the value of the DefaultCollectHistorical attribute specified at the KWEAGENT level.
Note: The setting of this attribute is independent of the historical configuration set within the CandleNet Portal. Therefore, there could be differences in these specifications for the collection of historical data, resulting in inconsistent data collection results. It is recommended that you set historical configuration within CandleNet Portal consistent with the above attribute. See the topic on configuring historical data collection in the CandleNet Portal help or user’s guide. See also the Historical Data Collection Guide for OMEGAMON XE and CandleNet Command Center.
CollectorSessionSampleInterval
This parameter provides the sampling interval, in seconds, for both workload analysis data and garbage-collection data for this application server. If this value is nonzero, the KWEAGENT will collect data from the application server based on the interval specified, whether or not the data is required. If this value is 0, then the agent will collect data from the application server only when required. The default is 60. This parameter is optional.
Value Meaning
NONE No historical data is to be collected.
ALL History is to be collected for all data.
PMI History is to be collected for PMI data.
WA History is to be collected for workload analysis data.
Verbose GC
History is to be collected for garbage collection data.
Heap History is to be collected for heap analysis data.
Lock History is to be collected for lock analysis data.
Your Agent’s Configuration Parameters and XML Tags
106 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
CollectWorkloadClassName
Optional. This keyword is used in combination with the CollectWorkloadClassType keyword to specifically identify those classes for which workload analysis data is to be collected for this application server. In order to collect workload analysis data for a class, the class must have a type on the CollectWorkloadClassType list, and have a name that matches one of the CollectWorkloadClassName masks. The valid format is one or more class name masks separated by commas or semicolons. Each class name mask may contain the asterisk (*) and question mark (?) wildcard characters.
You may also specify exclusion masks for CollectWorkloadClassName. An exclusion mask identifies classes to be specifically excluded from collection. An exclusion mask begins with a exclamation point (!) and is followed by a class mask. Workload data for any class that matches an exclusion mask is not collected. For example, CollectWorkloadClassName="*;!trade*" says workload data should be collected for all classes except for those that match the mask trade*.
CollectWorkloadClassType
Optional. This keyword specifies the type of workload analysis data that will be collected for this application server.. The valid format is an alphabetic string of one or more of the following characters. Each character, shown in the following list, represents a specific type of workload data that should be collected
Value Type of Workload Data
A Indicates that all workload data should be collected
B Indicates that workload data for EJB-related classes should be collected
C Indicates that workload data for JCA-related classes should be collected
D Indicates that workload data for SQL-related classes should be collected
G Indicates that workload data for CTG-related classes should be collected
I Indicates the workload data of JNDI-related classes should be collected
M Indicates that workload data for user-defined methods should be collected
Q Indicates that workload data for JMS-related classes should be collected for Java
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 107
Your Agent’s Configuration Parameters and XML Tags
CollectWorkloadMaxDepth
This keyword indicates the maximum stack depth at which instrumentation is to be enabled for this application server. The valid value is a numeral. This attribute is only effective for those classes which have been instrumented with the DepthSensitiveInstrumentation attribute set to a value of ‘true”. This attribute has no meaning if classes are not instrumented using Depth Sensitive Instrumentation. The default is the value of the DefaultCollectWorkloadMaxDepth attribute set at the KWEAGENT tag.
ExceptionWorkloadMax
Optional. This keyword sets a limit on the number of exception transactions for each workload identified by the ExceptionWorkloadName parameter. The valid format contains a positive integer that specifies the maximum number of exception transactions to collect for each defined workload.
If you issue a workload exception request for a workload mask that identifies multiple workloads, then the exception transactions for all the workloads that match the mask are collected. For example, if you have two workloads that match the mask, and you have this parameter set to 10, the agent would report a maximum of 10 exception transactions for each workload. The workload exception table view, in this case, would display up to 20 entries.
ExceptionWorkloadMinRespTime
Optional. This keyword specifies a response time threshold for reporting exception transactions. Any transactions having lower response times than the threshold value are not reported in the Longest Running Workloads workspace. The valid format contains an integer that specifies the number of milliseconds.
S Indicates that workload data for servlet classes should be collected
T Indicates that workload data for transaction-related classes should be collected
Value Type of Workload Data
Your Agent’s Configuration Parameters and XML Tags
108 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
ExceptionWorkloadName
Optional. This keyword identifies the workloads running on this application server for which exception transactions are to be collected. It contains one or more masks, separated by commas, that identify the class or classes of the workloads for which exception transactions are to be collected. Each mask may contain the asterisk (*) and question mark (?) wildcard characters. If this keyword is omitted, workload exception data is not collected for this application server unless data collection is specified for the KWEAGENT XML tag or by a Set Workload Exception Thresholds Take Action command.
Exclude="Yes|No"
This parameter indicates whether or not the application server should be monitored. If Exclude=Yes is specified, all other MonitorAppServer parameters, with the exception of Name are ignored. If Exclude=No is specified, then it overrides the DefaultExclude=Yes parameter which may have been specified at the agent level.
This parameter is optional.
GCCollect="Y|N"
This parameter indicates whether or not garbage-collection data is to be collected from the application server. If GCCollect is set to N, then no garbage-collection statistics are collected.
You may also use the WAS Verbose GC Collection Take Action command to dynamically start collecting garbage-collection data; see the OMEGAMON XE for WebSphere Application Server online help for information.
This parameter is optional.
GCPollFrequency
This parameter indicates how frequently, in seconds, the workload analysis component should check the WebSphere Application Server logs for garbage-collection records. The default is 60. This parameter is optional.
HeapCapturePercent
Specifies the heap capture percentage for this application server. Only the specified percentage of heap-allocation requests (randomly selected) are measured and reported by workload analysis. Valid values are from 1 to 100.
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 109
Your Agent’s Configuration Parameters and XML Tags
As an example, you set HeapCapturePercent to 30. This means that workload analysis will only provide detailed measurements on 30% of the heap allocations (chosen randomly) that it saw running. The other 70% of heap allocations are ignored.
This parameter is optional.
InflightThreshold
Specifies the minimum time, in milliseconds, that a workload can run before appearing in the In-flight Workloads Summary workspace. This threshold applies to the current application server. Workloads that have been running for less than the time specified are not reported. The default is 5 (milliseconds). This parameter is optional.
LockAnalysisLevel
This keyword specifies the level of lock contention monitoring to be performed for the application server referenced by this MonitorAppServer tag. There are three possible values for this attribute:
Disabled Lock Analysis is disabled.
Enabled The cost of monitor locking is collected for each involving workload, delay and class method.
High In addition to the data collected by the Enabled collection level, the sources of monitor contention will be identified.
The default value is the value of the DefaultLockAnalysisLevel parameter specified at the KWEAGENT level, or Disabled if the DefaultLockAnalysisLevel parameter was not specified.
LogScanInterval
This parameter indicates the interval value, in seconds, for scanning the application server’s log file to detect error or exception conditions. Periodically, based on the time set by this parameter, the KWEAGENT will open and read any new entries written into the log file for the application server. Any new entries that indicate an error or exception condition are noted in the Application Server Errors table as a pure event. The default for this parameter is 60. This parameter is optional.
Your Agent’s Configuration Parameters and XML Tags
110 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
MinimumSamplingInterval
This parameter provides a minimum interval between sample requests for a particular resource or resource type within this application server. This value is meaningful only when either the StatisticInterval paremeter or the DefaultStatisticInterval parameter is set to 0, or when either the CollectorSessionSampleInterval paremeter or the DefaultCollectorSessionSampleInterval parameter is set to 0.
This parameter specifies a minimum time value, in seconds, for obtaining updated information from the server when on-demand sampling is active. For example, if MinimumSamplingInterval is set to 15 and if two requests for information for the same resource or resource type are received by the OMEGAMON XE agent within 15 seconds of one another, the second request returns the identical data as the first request. The purpose of this parameter is to avoid too frequent sampling.
This parameter is optional.
Name
This required parameter specifies the name of the WebSphere Application Server to which this tag applies.
StatisticInterval
This parameter provides the sampling interval for PMI data collected for this application server, in seconds. If this value is nonzero, then the KWEAGENT will collect data from the application server based on the time specified, whether or not the data is requested. If this value is 0, then the agent will collect data from the application server only when required. The default is 60. This parameter is optional.
SubnodeAliasName
This parameter lets you specify an alias name for this application server for the purpose of creating a Candle Technologies (CT) subnode name representing the server. KWEAGENT normally constructs a subnode name for the server with the following format:
<application-server-name>:<node-name>:KWEB
where <application-server-name> is the name of the application server name, and <node-name> is the name of the system on which the application
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 111
Your Agent’s Configuration Parameters and XML Tags
server is running. Because of a 32-character restriction for CT node names, however, either the application server name or the node name or both, can be truncated. This can result in duplicate subnode names if more than one application server running on a system have names prefixed with the same set of characters. The SubnodeAliasName parameter allows you to specify an alias name for this server which will be used as the <application-server-name> portion of the subnode name. This lets you ensure that subnode names can be unique.
This parameter is optional.
TakeActionAuthUsers
This parameter indicates which CandleNet Portal users are authorized to issue Take Action commands for this application server. There can be multiple entries, separated by commas, associated with this parameter. Each entry can be a mask which can include the asterisk (*) and question mark (?) wildcard characters. A CandleNet Portal user is allowed to perform a Take Action on an application server if the user ID matches an entry in either the agent-level or application server level TakeActionAuthUsers list.
Note that these CandleNet Portal user IDs are defined within the CMS, and do not necessarily exist on the node on which the KWEAGENT is running. You can also specify this parameter at the agent level. If specified at both the agent and application server level, the mask lists are effectively merged for the application server.
WorkloadCapturePercent
Specifies the workload capture percentage for this application server. Only the specified percentage of executing workloads (randomly selected) are measured and reported by workload analysis. Valid values are from 1 to 100.
As an example, you set WorkloadCapturePercent to 30. This means that workload analysis will only provide detailed measurements regarding user response times and delays on 30% of the workloads (chosen randomly) that it saw running. The other 70% of the workloads are ignored.
This parameter is optional.
Using Your Agent’s Environment Variables
112 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Using Your Agent’s Environment Variables
What are the environment variables?OMEGAMON XE for WebSphere Application Server uses key environment variables that affect the operations of its IRA, KWEAGENT. For most environments, you only need to specify the CT_CMSLIST environment variable during installation. The default values for the others should be satisfactory for most systems. You can, however, change their settings as needed by your system.
Variables for OMEGAMON XE for WebSphere Application ServerThe following is a list of environment variables that you can use for the OMEGAMON XE agent.
BinPath
This variable identifies the directory containing the KWEAGENT binary files. This environment variable is only used by the KWEAGENT on Windows systems.
CT_CMSLIST
Required. This variable identifies the host name of the machine that is running the CMS to which you want the agent to connect. This variable is prefixed by the protocol used to reach that host, such as, ip: or sna:. You can list multiple hosts to connect to a backup CMS.
CTIRA_HIST_DIR
This variable identifies the directory location to write history files when historical situations are set.
CTIRA_LOG_PATH
This variable identifies the directory location for the IRA operation log. This log contains user-oriented messages written by the IRA framework and KWEAGENT.
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 113
Using Your Agent’s Environment Variables
KBB_RAS1
This optional variable can be set to turn on tracing. The possible values for this variable are the same as with all CT products. Do not define this parameter unless directed to do so by Candle.
KWE_MSG_PATH
This variable identifies the directory which contains the kwemsgs file. This file contains all the messages that are issued by the KWEAGENT. This variable is only used in the UNIX environment; on Windows systems, the kwemsgs file is assumed to be located in the directory identified by BinPath.
KWE_AGENT_COMPONENT_TRACE
This variable indicates whether or not the internal tracing of requests to KWEAGENT should be enabled. This is an internal, wrap-around trace that contains the flow of requests and responses to and from the agent. The default for this variable is YES.
KWE_INTERNAL_TRACE
This variable indicates whether the internal flow tracing within KWEAGENT should be enabled. This is an internal, wrap-around trace that shows the flow of control through the functions of the agent.
KWE_HEAP_DEBUG
This variable indicates whether or not the heap debugging option should be enabled for KWEAGENT. The default is NO.
KWE_SERVICE_INIT_TIME
This variable is only used in the Windows NT or 2000 environment when KWEAGENT is running as a service. This variable specifies the time, in milliseconds, that the agent service should require to initialize itself. The default for this variable is 5000 (5 seconds).
KWE_PARM_FILE
This variable contains the name of the file that contains the configuration parameters for KWEAGENT. This environmental variable is only used in a Windows environment. The default for this variable is kwe.xml. The file must exist in the directory identified by the BinPath variable.
Using Your Agent’s Environment Variables
114 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
$CANDLEHOME$
This variable contains the name of the directory into which the OMEGAMON XE for WebSphere Application Server agent has been installed. This environment variable is used only by the KWEAGENT on UNIX systems.
Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 115
Setting Instrumentation Levels to Collect PMI Data
Setting Instrumentation Levels to Collect PMI Data
OverviewThe Performance Monitoring Infrastructure (PMI) API extracts WebSphere Application Server performance data. This topic explains how to set the instrumentation levels to collect the performance data that you want reported. If you do not have the correct instrumentation levels set, you will not see the performance data in the workspaces. For example, if you do not set the correct instrumentation levels, you will not see performance data in the EJB Containers workspace.
You can set instrumentation levels in two ways: dynamically from CandleNet Portal or manually from the WebSphere administrative console. This topic covers these procedures.
Setting instrumentation levels dynamically via CandleNet PortalOMEGAMON XE for WebSphere Application Server provides SetIL Take Action commands to change PMI instrumentation levels; these are listed in Table 5 on page 179. When you execute one of these commands, the monitoring agent changes the WebSphere Application Server configuration on behalf of the targeted application server.
See the OMEGAMON XE for WebSphere Application Server online help for instructions on using these Take Action commands.
Setting instrumentation levels from the WebSphere administrative console for V4
This procedure explains how to use the WebSphere administrative console to set instrumentation levels to collect performance data for WebSphere Application Server V4.
1. Select the application server that needs to be monitored.
2. Choose the Services tab in the property pane.
3. Select the Performance Monitoring Settings in the service listing.
4. Click the Edit Properties button to bring up the Performance Monitoring Settings pop-up window.
Setting Instrumentation Levels to Collect PMI Data
116 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
5. Activate the Enable performance counter monitoring check box.
6. Expand all the resource categories in the hierarchy.
7. Select the desired resource category and choose one of the instrumentation levels on the right side: None, Low, Medium, High, or Max.
8. Click OK to apply the settings and close the dialog box.
Setting instrumentation levels from the WebSphere administrative console for V5
This procedure explains how to use the WebSphere administrative console to set instrumentation levels to collect performance data for WebSphere Application Server V5.
1. Access the WebSphere administrative console.
2. Expand the WebSphere administrative console navigation tree: in the lefthand window, click the + sign.
3. Select Application Servers.
4. In the righthand window, choose the application server whose configuration you want to modify.
5. In the resulting screen, select the Configuration tab.
6. From the Additional Properties, select Performance Monitoring Service.
7. In the resulting screen, activate the Startup check box.
8. Select an Initial specification level higher than None. See IBM’s WebSphere Application Server V5.0 documentation for more information.
9. Click the Apply button.
10. To save your updates, click the Save hyperlink
Preparing the Instrumentation Control File for Workloads and Application Traces 117
Preparing the InstrumentationControl File for Workloads
and Application Traces
OverviewThis chapter discusses the configuration parameters in kweiuser.xml that you define to instrument workloads for collection of workload analysis and application trace information.
Chapter contents
Instrumentation Basics about Workloads and Tracing . . . . . . . . . . . . . . . . . . . . . 118What are the instrumentation files for the agent? . . . . . . . . . . . . . . . . . . . . . 118Simplifying the instrumentation process: PathWAI Performance Analyzer . . . 118Collecting the workload and application trace data. . . . . . . . . . . . . . . . . . . . 119
Inside the User Instrumentation Control File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Sample kweiuser.xml instrumentation control files . . . . . . . . . . . . . . . . . . . . 120Keywords for the KWEINSTR tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Keywords for the Class tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Keywords for the Workload tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Keywords for the Workload_Class tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Keywords for the Delay tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Keywords for the Delay_Class tag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138About data collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Prerequisite for CTG users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
4
Instrumentation Basics about Workloads and Tracing
118 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Instrumentation Basics about Workloads and Tracing
OverviewOnce you have dynamically added the appropriate instrumentation code to your application code, the OMEGAMON XE agent can collect workload analysis data (including statistics about heap usage and garbage collections) and application trace data after you modify the WebSphere Application Server configuration to enable this data collection. This chapter details the instrumentation parameters that you define for the agent. For information about implementing this data collection, see “Collecting Workload Analysis, Application Trace, and Heap Data” on page 143.
What are the instrumentation files for the agent?Once you install the agent, your system will have three sample instrumentation files: kweiuser_certification.xml, kweiuser_development.xml, and kweiuser_production.xml—see “Sample kweiuser.xml instrumentation control files” on page 120.) Either you must indicate the filename of one of these files when you invoke the WAS Configuration Setup Take Action command, or alternatively, you must choose and rename one of these files to kweiuser.xml (the name of the default instrumentation control file); see “Dynamic method: using CandleNet Portal” on page 156.
The default instrumentation control file, kweiuser.xml, is the user instrumentation file in which you define instrumentation parameters for collecting the workload analysis and application trace data that you need. A sample of the kweiuser.xml file is shown on page page 121. For detailed descriptions of its XML tags and keywords, see the definitions that begin on page 124.
Simplifying the instrumentation process: PathWAI Performance Analyzer
Among its many other capabilities, Candle’s PathWAI Performance Analyzer product allows you to import your kweiuser.xml control file, update it to specify the classes and methods to be instrumented for workload analysis, and export the updated file. PathWAI Performance Analyzer also lets you browse
Preparing the Instrumentation Control File for Workloads and Application Traces 119
Instrumentation Basics about Workloads and Tracing
the contents of a jar, ear, or war file and select the classes and methods you want instrumented.
For complete information, see the online PathWAI Performance Analyzer User Guide.
Collecting the workload and application trace dataAfter you define your workload analysis and instrumentation settings in kweiuser.xml, you also need to change the WebSphere Application Server configuration. (See “Changing the WebSphere Application Server Configuration” on page 150.) Once you have properly configured WebSphere Application Server, you can then use Take Action commands on an as-needed basis to start and stop collecting the workload and trace data that you want.
Inside the User Instrumentation Control File
120 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Inside the User Instrumentation Control File
OverviewThis topic contains samples of the 3 different kweiuser.xml files that are shipped with your product and describes the instrumentation settings that you use to implement this optional feature.
Sample kweiuser.xml instrumentation control filesThe three Candle-provided sample kweiuser.xml instrumentation files are:
� kweiuser_development.xml: this can be used in a development environment, where maximum data should be collected. This file enables maximal instrumentation, and is virtually identical to the kweiuser.xml sample file shipped with prior versions of OMEGAMON XE for WebSphere Application Server.
� kweiuser_certification.xml: this can be used for instrumenting certification environments, that is, nonproduction environments that are normally used to certify applications prior to full integration into the production environment. This xml file provides for a medium level of instrumentation, reducing the overhead by using depth-sensitive instrumentation.
� kweiuser_production.xml: this file can be used for instrumenting full-fledged production environments, where minimum overhead is expected. Instrumentation should be minimal; no specific user methods are selected.
Location of kweiuser.xml instrumentation control files
You will find these kweiuser.xml files in one of the following locations.
� On Windows systems, the default location of the kweiuser.xml file is in the C:\Candle\CMA directory.
� On UNIX systems, the default location of the kweiuser.xml file is in the $CANDLEHOME$/config/ directory, where $CANDLEHOME$ is the directory where you installed your site’s Candle software.
Preparing the Instrumentation Control File for Workloads and Application Traces 121
Inside the User Instrumentation Control File
Sample kweiuser.xml files
You can use an unaltered version of one of these sample kweiuser.xml files, customize one of them, or ignore them and create your own.. For a detailed description of their XML tags and keywords, see the definitions that begin on page 124.
Figure 6. Sample kweiuser_development.xml Workload Analysis Control File
<?xml version="1.0" encoding="UTF-8" ?> - <KWEINSTR Version="130"
CollectCPUTime="true" CollectHTTPSessStats="true" CollectInFlightWorkloads="all" CollectorSessionPort="65535" CtgDelayPlugin="" DisplayEJBAs="EAR:CLASS" DisplayServletWorkloadAs="CLASS" GlobalInstrumentation="all" HeapAnalysisUserClasses="*" InternalTrace="false" LockAnalysisSystemClasses="NONE" LockAnalysisUserClasses="*" LogFileName="kweinstr.log" MaxTrivialMethodInstructions="10" MaxClasses="25000" MeasureHeapDelays="true" NumHeapAnalysisClasses="10000" ShowInternalWorkloads="false" ShowMethodArguments="true" SysInstr="Direct" toStringIsSafeToUse="false">
<Class Name="*" ClassType="user" DepthSensitiveInstrumentation="false" DisplayServletWorkloadAs="CLASS" HeapAnalysis="*" IgnoreTrivialMethods="false" LockAnalysis="true" MethodNames="*" MethodType="SERVLET,EJB,METHODS,PORTLET" />
</KWEINSTR>
Inside the User Instrumentation Control File
122 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 7. Default kweiuser_certification.xml Workload Analysis Control File
<?xml version="1.0" encoding="UTF-8" ?> - <KWEINSTR Version="130"
CollectCPUTime="true" CollectHTTPSessStats="true" CollectInFlightWorkloads="captured" CollectorSessionPort="65535" CtgDelayPlugin="" DisplayEJBAs="EAR:CLASS" DisplayServletWorkloadAs="CLASS" GlobalInstrumentation="all" HeapAnalysisUserClasses="*" InternalTrace="false" LockAnalysisSystemClasses="NONE" LockAnalysisUserClasses="*" LogFileName="kweinstr.log" MaxTrivialMethodInstructions="10" MaxClasses="10000" MeasureHeapDelays="true" NumHeapAnalysisClasses="5000" ShowInternalWorkloads="false" ShowMethodArguments="false" SysInstr="Direct" toStringIsSafeToUse="false">
<Class Name="*" ClassType="user" DepthSensitiveInstrumentation="true" DisplayServletWorkloadAs="CLASS" HeapAnalysis="*" IgnoreTrivialMethods="true" LockAnalysis="true" MethodNames="*" MethodType="SERVLET,EJB,METHODS,PORTLET" />
</KWEINSTR>
Preparing the Instrumentation Control File for Workloads and Application Traces 123
Inside the User Instrumentation Control File
Figure 8. Default kweiuser_production.xml Workload Analysis Control File
<?xml version="1.0" encoding="UTF-8" ?> - <KWEINSTR Version="130"
CollectCPUTime="false" CollectHTTPSessStats="false" CollectInFlightWorkloads="captured" CollectorSessionPort="65535" CtgDelayPlugin="" DisplayEJBAs="EAR:CLASS" DisplayServletWorkloadAs="CLASS" GlobalInstrumentation="all" HeapAnalysisUserClasses="" InternalTrace="false" LockAnalysisSystemClasses="" LockAnalysisUserClasses=""LogFileName="kweinstr.log" MaxTrivialMethodInstructions="10" MaxClasses="10000" MeasureHeapDelays="true" NumHeapAnalysisClasses="5000" ShowInternalWorkloads="false" ShowMethodArguments="false" SysInstr="Direct" toStringIsSafeToUse="false">
<Class Name="*" ClassType="user" DepthSensitiveInstrumentation="true" DisplayServletWorkloadAs="CLASS" HeapAnalysis="" IgnoreTrivialMethods="true" LockAnalysis="false" MethodType="SERVLET,EJB,PORTLET" />
</KWEINSTR>
Inside the User Instrumentation Control File
124 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Keywords for the KWEINSTR tagThe KWEINSTR XML tag encapsulates all keywords for workload instrumentation. They provide overall controls for the instrumentation process. The definitions for each of these keywords are given in the order they appear in the kweiuser.xml file.
ClassTypeDef
The following entries describe types of classes:
� Local EJB support
– CLASSTYPE_EJBLOCALHOMECLASS– CLASSTYPE_EJBLOCALOBJECTCLASS
� Message-driven beans
– CLASSTYPE_EJBMESSAGEDRIVENBEAN
� JMS publish/subscribe support
– CLASSTYPE_JMS_TOPIC– CLASSTYPE_JMS_TOPICCONNECTION– CLASSTYPE_JMS_TOPICCONNECTIONFACTORY– CLASSTYPE_JMS_TOPICPUBLISHER– CLASSTYPE_JMS_TOPICSUBSCRIBER– CLASSTYPE_JMS_TOPICSESSION
CollectCPUTime
This keyword indicates whether or not CPU usage data is to be collected. The valid values are true and false. The default value is false.
CollectHTTPSessStats
This keyword indicates whether or not Workload Analysis should attempt to determine the sizes of all HTTP session related objects. The valid values are true and false.
The default value is false.
Preparing the Instrumentation Control File for Workloads and Application Traces 125
Inside the User Instrumentation Control File
CollectInFlightWorkloads
This keyword indicates whether or not Workload Analysis should capture call stack information for workloads which could potentially appear in the In Flight Workloads workspace. The valid values are:
All Collect call stack information for the In Flight Workloads workspace for all workloads, regardless of whether the workload is being measured.
None Don’t collect In Flight Workload information at all.
Captured Only collect call stack information for the In Flight Workloads workspace for workloads that are being measured. If the workload capture percent is less than 100, then call stack information will not be collected for all workloads.
The default value is All.
CollectorSessionPort
This keyword indicates the IP port number to be used for communicating with the agent. It must match the CollectorSessionPort value used in the kwe.xml file.
This parameter is ignored if the com.candle.kwe.instrument.agent_parms property is set in the command-line arguments for the application server. In this case, the value for the port is taken from the agent control file identified by the “com.candle.kwe.instrument.agent_parms” property, which should refer to the same kwe.xml file that the agent is using. If workload analysis cannot obtain the port number from the agent parameter file, then it uses the value of the CollectorSessionPort in kweiuser.xml. The default value is 65535.
CtgDelayPlugin
Applies only to CICS Transaction Gateway (CTG) ECI applications. Candle provides a Java interface that you can use for writing a plugin that extracts COMMAREA information and adds it as the minor delay name in the Selected Workload Delays - Current Interval report (for instructions on building this plugin, see “Prerequisite for CTG users” on page 139). This keyword specifies the name of the compiled plugin; use the UserClassPath keyword to specify its location (see “UserClassPath” on page 131).
Inside the User Instrumentation Control File
126 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
DisplayEJBAs
This keyword indicates how EJB major names for delays and workloads are to be constructed for all EJB-related classes.
The possible value is a string containing either the word “class” or the string “ear:class”. The default value is “ear:class”.
The keyword “class” indicates that EJB-related major and minor names are to be composed of the fully-qualified class name only. The string “ear:class” indicates that EJB related major names are to be composed of the EAR and/or JAR file name, followed by a “;”, then followed by the fully-qualified class name.
DisplayServletWorkloadAs
The presence of this tag indicates that the workload major name for servlets and JSPs is to be constructed from the URL used to invoke the servlet or JSP.
The possible value is a string consisting either of the word “class” or of two string fields separated by a colon. The first field contains either “hostname” or “null”. The second field contains either an asterisk or a number. The default value is “class”.
If the word “class” is specified, it indicates that servlets and JSPs are to be reported by class and method name. If the first portion of the string contains “hostname”, then the major name will contain the host name portion of the URL. If the first portion contains "null", then the host name is not included. If the second portion of the string contains a numeric value, then it indicates how many qualifiers within the URL, counting from the right, are included in the major name. If the second portion of the string contains "*", then all of the qualifiers in the URL are included. The "*" does not pertain, however, to the host name portion of the URL, which is included or excluded based upon the first portion of the string.
This attribute can be overridden for a class or set of classes by the DisplayServletWorkloadAs attribute at the Class tag level; see “Keywords for the Class tag” on page 131.
GlobalInstrumentation
This attribute is used to globally enable or disable all instrumentation.
The possible values are “none” or “all.”
Preparing the Instrumentation Control File for Workloads and Application Traces 127
Inside the User Instrumentation Control File
If a value of “all” is specified, then the behavior of the product is exactly like the prior product behavior. In other words, Java classes are instrumented based upon the specifications in kweiuser.xml. If a value of “none” is specified, then no instrumentation at all is performed, regardless of the other specifications in the instrumentation control files. A value of “none” implies that only garbage collection data will be collected.
The default value is “all.”
HeapAnalysisSystemClasses
This keyword defines one or more class masks, separated by semicolons, that identify the instantiated system classes (those that are part of WebSphere Application Server iself) whose heap allocations can potentially be measured. Each class mask can contain '*' and '?' wildcard characters.
This attribute can be overridden by the HeapAnalysis attribute of the Class tag; see “Keywords for the Class tag” on page 131.
A class mask can begin with an exclamation point (!) character, which indicates that class names matching the mask are to be excluded from data collection. For example, to instrument all classes whose names begin with java.lang except for the java.lang.String class, specify
HeapAnalysisSystemClasses="java.lang.*;!java.lang.String.”
HeapAnalysisUserClasses
One or more class masks separated by semicolons that identify the instantiated classes for which heap allocations are to be instrumented. Each class mask can contain '*' and '?' wildcard characters.
This attribute can be overridden by the HeapAnalysis attribute of the Class tag; see “Keywords for the Class tag” on page 131.
A class mask can begin with a '!' character, which indicates that class names matching the mask are to be excluded from data collection.
InternalTrace
This keyword indicates whether or not workload analysis tracing should be enabled and written to a detailed log file. The default value is false. Do not change the default setting unless directed otherwise by Candle Customer Support.
Inside the User Instrumentation Control File
128 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
LockAnalysisSystemClasses
This keyword specifies the one or more class masks, separated by semi-colons, which identify those system classes for which lock accesses are to be instrumented. Each class mask can contain ‘*’ and ‘?’ wildcard characters. This attribute can be overridden at the class level specification set in the Class tag. The default value is blank; if omitted, lock accesses are not instrumented for system classes.
LockAnalysisUserClasses
This keyword specifies the one or more class masks, separated by semi-colons, which identify those user classes for which lock accesses are to be instrumented. Each class mask can contain ‘*’ and ‘?’ wildcard characters. This attribute can be overridden at the class level specification set in the Class tag. The default value is blank; if omitted, lock accesses are not instrumented for system classes.
LogFileName
This keyword identifies the log file for workload analysis. The valid format is alphanumeric; the default value is kweinstru.log.
MaxClasses
This keyword identifies the maximum number of classes to instrument. The valid format is a positive number; the default value is 1000.
MaxHTTPSessions
This keyword limits the number of HTTP sessions that the workload analysis component is to track individually. Tracking individual HTTP sessions can be expensive if there are large number of active sessions. This parameter allows you to limit the number of sessions for which workload analysis will collect detailed data: only the number of sessions specified by this parameter will appear in the HTTP Sessions workspace. The default for this parameter is 0, which indicates that workload analysis will attempt to collect detailed data for all HTTP sessions.
Preparing the Instrumentation Control File for Workloads and Application Traces 129
Inside the User Instrumentation Control File
MaxTrivialMethodInstructions
Indicates the maximum number of Java byte code instructions for a method to be considered trivial (see the description of the “IgnoreTrivialMethods” on page 134 parameter). The default value is 10.
MeasureHeapDelays
Indicates whether or not workload analysis should track workload delays due to heap allocations. Valid values are true and false; the default is false.
NumHeapAnalysisClasses
This keyword defines the maximum number of instantiated classes for which heap allocations can be instrumented. The default is 5000.
ShowInternalWorkloads
This keyword indicates whether or not workloads invoked by other workloads should be tracked as separate workloads, or whether they should appear as delays to the original invoking workload. The valid values are true and false. A value of '”true” indicates that internally invoked workloads are tracked as separate workloads. The default value is false.
Note: Portlet invocations are always tracked as workloads, no matter what the value of ShowInternalWorkloads is.
ShowMethodArguments
This keyword indicates whether or not workload analysis should collect the arguments that are passed to instrumented methods. If the arguments are collected, they are displayed on the workload analysis Longest Running Workloads workspace, as well as in application traces. A value of “true” indicates that the method parameters will be collected and displayed; the default value is false.
Inside the User Instrumentation Control File
130 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
SysInstr
Do not change this keyword setting unless you are told to do so by Candle. This keyword indicates how instrumentation will be performed on the system classes. The valid values are shown in the following table.
SystemClassLoaderClasses
This parameter identifies the class names of the Java class loaders responsible for loading Java and WebSphere Application Server system classes. It consists of one or more class name masks, separated by semicolons. Each mask can contain '*' and '?' wildcard characters.
A default value for SystemClassLoaderClasses is shipped with the OMEGAMON XE agent; do not specify this parameter unless instructed by Candle Customer Service and Satisfaction.
ToStringIsSafeToUse
Indicates whether it is safe for workload analysis to call the toString() method for application classes passed as input or return parameters when calling an instrumented method. This attribute has two possible values, “true” and “false”; “true” allows workload analysis to provide more-detailed information in application traces.
“True” indicates it is safe for the workload analysis to call toString() to obtain a displayable form of the class name. The version of toString() provided must be safely callable by the instrumentation data-collection thread that is created in the application server without affecting the deployed applications’ normal operation.
“False” indicates that toString() method is not generally safe to be called by the instrumentation data-collection thread and that calling it may have some unintended side effects on running applications.
The default is “false”.
Value Meaning
Direct Default. Indicates called system class methods will be instrumented
Indirect Indicates the system class methods called from the user class will be instrumented
Preparing the Instrumentation Control File for Workloads and Application Traces 131
Inside the User Instrumentation Control File
UserClassPath
Applies only to CICS Transaction Gateway (CTG) ECI applications. Candle provides a Java interface that you can use for writing a plugin that extracts COMMAREA information and adds it as the minor delay name in the Selected Workload Delays - Current Interval report (for instructions on building this plugin, see the online help for the OMEGAMON XE agent). This keyword specifies the location of the compiled plugin; use the CtgDelayPlugin keyword to specify its name (see “CtgDelayPlugin” on page 125).
Version
This keyword identifies the version of the product for which the parameters were set. It ensures the parameter settings will be interpreted correctly in future releases. The current valid values are 130, 120, or 110.
Keywords for the Class tagThe control file contains multiple Class entries. Each Class XML tag specifies the type and level of instrumentation that is to be performed on the class or classes that match the class name parameter. The definitions for each of these keywords are given in the order they appear in the kweiuser.xml file.
Name
This keyword is a mask that identifies the names of the class or classes to which this statement applies. The mask may contain the asterisk (*) and question mark (?) wildcard characters to identify a group of matching class names.
ClassType
This keyword indicates the type of class being identified by this statement. The valid values are shown below.
The default value is “user”.
Value Meaning
user Indicates a user-defined class
system Indicates a WebSphere Application Server system class
Inside the User Instrumentation Control File
132 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
DepthSensitiveInstrumentation
This keyword indicates whether or not the classes which match this Class tag should be instrumented with Depth Sensitivity. The valid values are “True” and “False.” If a value of “True” is specified, then the instrumentation for each selected method will be sensitive to the stack depth, and will not be enabled unless the current stack depth is less than or equal to the maximum stack depth as specified by the agent. The default value is “False”, which indicates that instrumentation for this class is not sensitive to the stack level; in other words, it is either enabled or disabled.
DisplayEJBAs
This keyword indicates how EJB major names for delays and workloads are to be constructed for EJB-related classes that match this Class tag.
The possible value is a string containing either the word “class” or the string “ear:class”. The default value is the value of the DisplayEJBAs attribute set at the KWEINSTR level; see“Keywords for the KWEINSTR tag” on page 124.
The keyword “class” indicates that EJB-related major and minor names are to be composed of the fully-qualified class name only. The string “ear:class” indicates that EJB related major names are to be composed of the EAR and/or JAR file name, followed by a “;”, then followed by the fully-qualified class name.
This attribute overrides the value of DisplayEJBAs specified at the KWEINSTR level.
Examples: The class name is com.ibm.websphere.samples.plantsbywebsphereejb.CatalogBean, and it is deployed in the PlantsByWebSphereEJB.jar file within the PlantsByWebSphere.ear file.
1. For DisplayEJBAs="class", this EJB information is displayed:com.ibm.websphere.samples.plantsbywebsphereejb.CatalogBean
2. For DisplayEJBAs="ear:class", this EJB information is displayed:PlantsByWebSphere.ear\PlantsByWebSphereEJB.jar; com.ibm.websphere.samples.plantsbywebsphereejb.CatalogBean
Preparing the Instrumentation Control File for Workloads and Application Traces 133
Inside the User Instrumentation Control File
DisplayServletWorkloadAs
The presence of this tag indicates that the workload major name for servlets and JSPs is to be constructed from the URL used to invoke the servlet or JSP for servlet classes which match this Class tag.
The possible value is a string consisting either of the word “class” or of two string fields separated by a colon. The first field contains either “hostname” or “null”. The second field contains either an asterisk or a number. The default value is the value of the DisplayServletWorkloadAs attribute set at the KWEINSTR level; see “Keywords for the KWEINSTR tag” on page 124.
If the word “class” is specified, it indicates that servlets and JSPs are to be reported by class and method name. If the first portion of the string contains “hostname”, then the major name will contain the host name portion of the URL. If the first portion contains "null", then the host name is not included. If the second portion of the string contains a numeric value, then it indicates how many qualifiers within the URL, counting from the right, are included in the major name. If the second portion of the string contains "*", then all of the qualifiers in the URL are included. The "*" does not pertain, however, to the host name portion of the URL, which is included or excluded based upon the first portion of the string.
This attribute overrides the value of DisplayServletWorkloadAs specified at the KWEINSTR level.
Examples: The application URL is:
http://www.ABWinsurance1.com:9080/ABWhome/applications/eagent/queryaccount
1. For DisplayServletWorkloadAs="hostname:*", this major name is displayed:www.ABWinsurance1.com:9080/ABWhome/applications/eagent/queryaccount
2. For DisplayServletWorkloadAs="hostname:1", this major name is diplayed:
www.ABWinsurance1.com:9080/queryaccount
3. For DisplayServletWorkloadAs="null:1", this major name is displayed:queryaccount
4. For DisplayServletWorkloadAs="hostname:0", this major name is displayed:
www.ABWinsurance1.com:9080
Inside the User Instrumentation Control File
134 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
HeapAnalysis
One or more class masks separated by semicolons that identify the instantiated classes whose heap allocations can potentially be measured. Each class mask can contain '*' and '?' wildcard characters.
This attribute overrides the HeapAnalysisSystemClasses and HeapAnalysisUserClasses attributes in the KWEINSTR tag for any matching class mask.
A class mask can begin with an exclamation point (!) character, which indicates that class names matching the mask are to be excluded from data collection. For example, to instrument all classes whose names begin with java.lang except for the java.lang.String class, specify
HeapAnalysis="java.lang.*;!java.lang.String.”
IgnoreTrivialMethods
Instructs workload analysis not to instrument methods it considers too trivial to monitor. A method is considered trivial if it is small, contains no loops, and calls no other methods. A trivial method contains no more Java byte code instructions than the limit set by the MaxTrivialMethodInstructions parameter; see “MaxTrivialMethodInstructions” on page 129.
Valid values are “true” and “false”; the default is “true”.
LockAnalysis
This specifies if the class tag defined class is to be instrumented for monitoring of lock contentions. The valid values are True and False. False is the default value.
MethodNames
Indicates which methods for the class should be specifically instrumented. This parameter is meaningful only when the MethodType parameter contains the keyword METHODS. The format for the MethodNames parameter is one or more method name masks, separated by commas or semicolons. Each mask may contain the asterisk (*) and question mark (?) wildcard characters. Each method in the class or classes whose name matches one of the masks in the MethodNames parameter will be instrumented.
Preparing the Instrumentation Control File for Workloads and Application Traces 135
Inside the User Instrumentation Control File
To exclude specific methods from instrumentation, preceed the method name with an exclamation point. For example, to instrument all methods except those that begin with get or set, specfiy:
MethodNames="*,!get*,!set*"
MethodType
This keyword indicates the type of methods that should be instrumented with the class or classes. The valid values are shown below. There is no default value. Use commas to separate multiple values for this keyword.
The MethodType keyword must contain the METHODS value in order for the MethodNames keyword to be specified.
Value Meaning
CTG Indicates that CICS Transaction Gateway-related methods should be instrumented.
EJB Indicates that EJB-related methods should be instrumented
JCA Indicates that JCA-related methods should be instrumented
JMS Indicates that JMS-related methods should be instrumented
JNDI Indicates that JNDI-related methods should be instrumented
JTS Indicates that methods relating to the Java Transaction Service (JTS) should be instrumented
METHODS Indicates that method names explicitly specified by the MethodNames keyword are to be instrumented
PORTLET Indicates that portlet-related methods should be instrumented.
SERVLET Indicates that servlet-related methods should be instrumented
SOCKET Indicates that socket-related methods should be instrumented
SQL Indicates that JDBC-related methods should be instrumented
Inside the User Instrumentation Control File
136 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Keywords for the Workload tagThe Workload tag represents a user-defined workload (such as those based on the Model/View/Controller architecture, including struts applications), and defines the major and minor names you want assigned to this business application.
Note that if a workload is defined via a Workload tag, it need not also be defined via a Class tag. Instrumentation of methods associated with user-defined workloads is implicit.
MajorName
The major name you want to assign to the workload when displayed in CandleNet Portal; you can choose whatever major name best describes your business application. The combination of major name and minor name identifies the user-defined workload.
MinorName
The minor name you want to assign to the workload when displayed in CandleNet Portal; you can choose whatever minor name best describes your business application. The combination of major name and minor name identifies the user-defined workload.
Keywords for the Workload_Class tagEach Workload_Class tag within the Workload tag defines the classes and methods OMEGAMON XE for WebSphere Application Server should recognize as representing the workload; the execution of any method matching one of the Workload_Class tags is considered an execution of the user-defined workload.
Name
This keyword is a mask that identifies one or more classes whose methods represent the user-defined workload to which this tag applies. The mask may contain the asterisk (*) and question mark (?) wildcard characters to identify a group of matching workload names.
Preparing the Instrumentation Control File for Workloads and Application Traces 137
Inside the User Instrumentation Control File
Methods
This keyword identifies one or more method name masks separated by commas or semicolons. Each method name mask can contain the asterisk (*) and question mark (?) wildcard characters. Any method name whose class matches the Name attribute and whose method name matches one of the entries in the Methods attribute represents an execution of the workload.
Example of the Workload tag
<Workload MajorName="StrutsInputAction"MinorName="StrutsApp">
<Workload_Class Name="org.struts.example.StrutsInputAction"Methods="perform,execute"/>
</Workload>
Keywords for the Delay tagThe Delay tag represents a user-defined delay. It specifies which classes and methods are recognized as representing the delay, and defines the major and minor names you want assigned to it. Use this feature whenever you want to aggregate multiple method calls into a single user-defined delay that represent a business function. This user-defined delay will then be displayed in the Selected Workload Delays - Current Interval workspace.
MajorName
The major name you want to assign to the delay when displayed in CandleNet Portal; you can choose whatever major name best describes your business application. The combination of major name and minor name identifies the user-defined delay.
MinorName
The minor name you want to assign to the delay when displayed in CandleNet Portal; you can choose whatever minor name best describes your business application. The combination of major name and minor name identifies the user-defined delay.
Inside the User Instrumentation Control File
138 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
IncludeChildDelays
Either TRUE or FALSE; the default is FALSE. Specifies whether or not to treat methods invoked from each instrumented Delay_Class as one delay. The default is to treat invoked methods as unique delays.
Keywords for the Delay_Class tagEach Delay_Class tag within the Delay tag defines the classes and methods OMEGAMON XE for WebSphere Application Server should recognize as representing a single delay; the execution of any method matching one of the Delay_Class tags is considered an occurrence of the user-defined delay.
Name
This keyword is a mask that identifies one or more classes whose methods represent the user-defined delay to which this tag applies. The mask may contain the asterisk (*) and question mark (?) wildcard characters to identify a group of matching delay names.
Methods
This keyword identifies one or more method name masks separated by commas or semicolons. Each method name mask can contain the asterisk (*) and question mark (?) wildcard characters. Any method name whose class matches the Name attribute and whose method name matches one of the entries in the Methods attribute represents an occurrence of the delay.
Note: If while parsing kweiuser.xml the agent finds that a method mask has been associated with more than one user-defined object, OMEGAMON XE for WebSphere Application Server issues a warning message (to the workload analysis log file and to the Product Events table view) and then uses the first definition encountered. This duplication occurs only if the same class and method mask are specified in more than one Workload_Class or Delay_Class tag.
Preparing the Instrumentation Control File for Workloads and Application Traces 139
Inside the User Instrumentation Control File
About data collectionAfter you define the workloads, classes, and methods to be instrumented in kweiuser.xml, you need to begin collecting the data. See “Collecting Workload Analysis, Application Trace, and Heap Data” on page 143 for details.
Prerequisite for CTG users
Retrieving CICS COMMAREA data for ECI applications
The OMEGAMON XE for WebSphere Application Server product’s workload analysis feature provides statistics about the number and duration of calls made to CICS through a CICS Transaction Gateway (CTG). In the Selected Workload Delays - Current Interval workspace, the major delay name shows the hostname of the CTG Gateway, the Gateway port, the CICS server name, and the type of request (ECI, EPI, or ESI). By default, the minor delay name for ECI requests is the CICS program name to be called. (For EPI and ESI requests, the CICS Transaction ID is shown.)
Some customers may want a more meaningful identifier than the CICS program name, to better identify the underlying reason for exceptional response times. The CICS Communication Area, COMMAREA, is often used with ECI requests to pass parameters to CICS, which may use a program as a router to other CICS transactions. The COMMAREA may contain simple text data (in either ASCII or EBCDIC) or complex data structures that would be meaningless or unprintable if displayed.
To include COMMAREA contents in the Selected Workload Delays - Current Interval reports’ Minor Delay Name column, Candle provides a Java interface for writing a plugin that can extract this COMMAREA information and include it in the Selected Workload Delays attribute group.
Your program must implement the com.candle.kwe.workanalysis.CtgDelayPluginInterface interface. To do so, you must provide an implementation for the getMinorDelay method, which has the following signature:
public String getMinorDelay(String _Parent,String _Server,String _Program,byte[ ] _Commarea,int _CommareaLen)
Inside the User Instrumentation Control File
140 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
where:
_Parent is the class name of the object making the CTG request._Server is the name of the destination CICS server (may not be
present for ListSystems request)._Program is the CICS program name to be invoked._Commarea is a byte array containing the CICS COMMAREA data
to be passed._CommareaLen is the number of bytes in _Commarea.
Note that the getMinorDelay method is called only for ECI requests.
A sample plugin program, CtgDelaySample.java, is provided in the C:\Candle\CMA directory (for Windows) or the /$CANDLEHOME$/classes directory (for UNIX).
Compiling the CTG delay plugin
Use JVM V1.3.1 (supplied with WebSphere Application Server) to compile a CTG plugin.
1. Use the following command to compile your plugin and create a .class file.On Windows, specify:
javac -classpath .;C:\Candle\CMA\kwewa.jar CtgDelaySample.java
On UNIX, specify:
javac -classpath .;$CANDLEHOME$/classes/kwewa.jar CtgDelaySample.java
2. Copy this file to a suitable location (C:\Candle\CMA, for example).
Defining the CTG delay plugin to workload analysis
Once you have created your plugin, you must define it to the OMEGAMON XE agent’s workload analysis feature:
1. Edit file kweiuser.xml.
2. Specify the plugin name using the CtgDelayPlugin keyword for the KWEINSTR tag. For more information, see “CtgDelayPlugin” on page 125
3. Specify the location of the CtgDelayPlugin classfile using the UserClassPath keyword for the KWEINSTR tag. For more information, see “UserClassPath” on page 131
Preparing the Instrumentation Control File for Workloads and Application Traces 141
Inside the User Instrumentation Control File
Example:
CtgDelayPlugin="MyCtgDelayPlugin"UserClassPath="C:/Candle/CMA"
Inside the User Instrumentation Control File
142 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Collecting Workload Analysis, Application Trace, and Heap Data 143
Collecting Workload Analysis,Application Trace,
and Heap Data
OverviewThis chapter details configuration settings and initial steps you must take to collect workload and application trace information, including heap usage and garbage-collection statistics.
Chapter contents
Workload Analysis, Application Traces, and Instrumentation . . . . . . . . . . . . . . . . 145Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Moving on: the workload analysis Take Action commands . . . . . . . . . . . . . . 147
Launching the Class Loader Script for Workload Analysis . . . . . . . . . . . . . . . . . . 148Run the class loader setup script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
For Windows systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148For UNIX systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Changing the WebSphere Application Server Configuration . . . . . . . . . . . . . . . . 150Step 1. Change the application server configuration. . . . . . . . . . . . . . . . . . . 150
Manual method: using the WebSphere administrative console for V4 stand-alone application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Manual method: using the WebSphere administrative console for V4 cloned application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152Manual method: using the WebSphere administrative console for V4 server groups implementing vertical scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Manual method: using the WebSphere administrative console for V5. . . 154Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Dynamic method: using CandleNet Portal . . . . . . . . . . . . . . . . . . . . . . . 156
Step 2. Recycle the application server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
5
144 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Collecting Specific Workload Analysis Data for Different Application Servers . . . 159Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Create separate instrumentation files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Modify the WebSphere Application Server command-line settings . . . . . . . . 159
Creating Specific Agent Control Files for Different Agents . . . . . . . . . . . . . . . . . . 161Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Create separate agent configuration files. . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Specifying an alternate agent configuration file. . . . . . . . . . . . . . . . . . . . . . . 163
Dynamic method: using CandleNet Portal . . . . . . . . . . . . . . . . . . . . . . . 163Manual method: using the WebSphere administrative console . . . . . . . . 163
Collecting Workload Analysis, Application Trace, and Heap Data 145
Workload Analysis, Application Traces, and Instrumentation
Workload Analysis, Application Traces, and Instrumentation
OverviewThis topic introduces basic configuration concepts related to enabling the workload analysis and application tracing capabilities in the OMEGAMON XE agent. The workload analysis feature enables you to collect and display workload data for application transactions. This data lets you see how often these workload transactions run, determine their response times, and discover what might be causing performance degradation. In addition, you can also initiate the application tracing feature to see, for example, the sequence of method calls within a workload.
You can also use these features to see if workloads are meeting their response-time service levels or if workloads are consuming excessive resources. For example, workload analysis may indicate a problem with SQL calls to a database or higher CPU usage than expected.
BackgroundFollows these steps to configure the agent for workload analysis and application tracing.
1. Define the appropriate configuration parameters in kwe.xml, the default configuration file for the OMEGAMON XE agent. See “Your Agent’s Configuration Parameters and XML Tags” on page 91 for details.
2. Define your instrumentation definitions in the kweiuser.xml file. See “Preparing the Instrumentation Control File for Workloads and Application Traces” on page 117 for details.
3. Run the Candle class loader setup script that will enable the OMEGAMON XE agent to collect workload data from WebSphere Application Server. See “Launching the Class Loader Script for Workload Analysis” on page 148 for details.
Note: You will need to run this utility again whenever you apply IBM maintenance that affects the Java Development Kit (JDK).
Workload Analysis, Application Traces, and Instrumentation
146 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
4. Change the WebSphere Application Server’s configuration either through CandleNet Portal or through the WebSphere administrative console. See “Changing the WebSphere Application Server Configuration” on page 150 for details.
5. Restart the WebSphere Application Server.
6. Use the agent’s Take Action commands to control the dynamic collection of workload analysis and application trace data. See the descriptions of the Take Action commands in the online help for details.The following pages explain the configuration steps you need to complete to enable the collection of workload analysis and trace information.
Collecting Workload Analysis, Application Trace, and Heap Data 147
Workload Analysis, Application Traces, and Instrumentation
Moving on: the workload analysis Take Action commandsSee the online help for the OMEGAMON XE agent for WebSphere Application Server for details about:
� WAS Configuration Setup Take Action command for changing an application server’s configuration to perform workload analysis
� WAS Set Workload Exception Thresholds Take Action command for defining thresholds for collecting exception transactions
� WAS Dynamic Workload Analysis Take Action command for managing data collection for specific classes
� WAS Start Heap Collection Take Action command for managing data collection for object allocations
� WAS Verbose GC Collection Take Action command for stopping and starting the collection of garbage-collection statistics
� WAS Set Capture Percent Take Action command for settinng the percentage of workload and heap-allocation invocations the workload analysis component should collect.
� WAS Set In-flight Threshold Take Action command for defining the CPU time threshold below which in-flight workloads are not reported.
� WAS Set Longest Running Workload Threshold Take Action command for defining the threshold for the collection and reporting of exceptional transaction data
� WAS Set Lock Analysis Level Take Action command for setting monitor-contention analysis levels and the minimum cost threshold for a particular application server
Launching the Class Loader Script for Workload Analysis
148 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Launching the Class Loader Script for Workload Analysis
OverviewThis topic explains how to use the class loader setup script, which enables the agent to collect workload analysis and application trace data. This script creates a jar file that is later referenced for the WebSphere Application Server startup environment.
Note: You must run this script whenever you install the agent or apply IBM maintenance to WebSphere Application Server and again whenever you apply maintenance to OMEGAMON XE for WebSphere Application Server.
Run the class loader setup scriptUse the appropriate procedure to run the class setup loader script on your system. Then, modify the WebSphere Application Server environment as explained in “Changing the WebSphere Application Server Configuration” on page 150.
For Windows systems
On Windows, run the setupCandleWAEnabler.bat file from a command prompt. From the C:\Candle\CMA directory, use this command,
setupCandleWAEnabler.bat
For UNIX systems
On UNIX, run the setupCandleWAEnabler.sh file from a command prompt. From the $CANDLEHOME$/bin directory, use this command,
./setupCandleWAEnabler.sh
Your system displays the following prompt:
Please enter the WebSphere Application Server installation directory
Provide the path name of the directory in which WebSphere Application Server is installed, for example, /usr/WebSphere/AppServer for most UNIX environments.
Collecting Workload Analysis, Application Trace, and Heap Data 149
Launching the Class Loader Script for Workload Analysis
You should see the following message if the setupCandleWAEnabler.sh script finishes successfully:
======================================Candle Workload Analysis setup finished successfully.Please follow the Installation Manual to update yourWebSphere Application Server configuration to enableCandle Workload Analysis data collection.======================================
Note: If you have multiple versions of WebSphere Application Server installed on a UNIX platform, run the setupCandleWAEnabler.sh script for each version of WebSphere Application Server that you have installed.
Changing the WebSphere Application Server Configuration
150 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Changing the WebSphere Application Server Configuration
IntroductionThis topic explains the changes that you will need to make to the configuration for WebSphere Application Server to enable the agent to collect workload analysis and trace data or to collect garbage-collection statistics.
Step 1. Change the application server configurationTo enable workload analysis for the agent, you need to change the WebSphere Application Server configuration. You can use either of the following methods to do this.
� Dynamic: Use the agent’s Configuration Setup Take Action command to modify the WebSphere Application Server configuration parameters. See “Dynamic method: using CandleNet Portal” on page 156.
Candle recommends you use the Configuration Setup Take Action command whenever feasible, as it eliminates much reconfiguration work.
� Manual: Use one of the methods below to modify the WebSphere Application Server configuration parameters.
Manual method: using the WebSphere administrative console for V4 stand-alone application servers
Use these steps to modify the configuration setting for a stand-alone application server to enable the collection of workload analysis and trace data.
1. Access the WebSphere administrative console.
2. In the WebSphere administrative console navigation tree, choose the application server you want.
3. Choose the JVM Settings tab and the Advanced JVM Settings button to display the data entry area.
Collecting Workload Analysis, Application Trace, and Heap Data 151
Changing the WebSphere Application Server Configuration
4. Locate the Command line arguments field for the application server.
Note: Type the command arguments that are described in the following steps on the same line and separate them with a space. See the format for “Examples” on page 156.
A. Next, enter the appropriate information for your OMEGAMON XE agent. Modify the configuration information as indicated by the black text.-Dcom.candle.kwe.instrument.user_control_file=<name of the main
instrumentation control file>
� For Windows, the file name is usually C:\Candle\CMA\<kweiuser.xml>
For UNIX, the file name is usually $CANDLEHOME$/config/<kweiuser.xml>
where <kweiuser.xml> is a Candle-provided or custom kweiuser.xml file. (See “Sample kweiuser.xml files” on page 121.)
-Dcom.candle.kwe.instrument.agent_parms=<full path name of the kweagent control file>
� For Windows, the file name is usually C:\Candle\CMA\kwe.xml
For UNIX, the file name is usually $CANDLEHOME$/config/kwe.xml
B. Add the following configuration information to the Boot classpath (prepend): field on the Advanced JVM Settings dialog. This file was created when you ran the Candle class loader setup script (see “Launching the Class Loader Script for Workload Analysis” on page 148).
� For Windows, enter:
C:\Candle\CMA\<kwescl.*.jar>;C:\Candle\CMA\kwewa.jar
For UNIX systems, enter:
$CANDLEHOME$/classes/<kwescl.*.jar>:$CANDLEHOME$/classes/kwewa.jar
Note: The name of the kwescl.*.jar file shown above depends upon your site’s version of the JDK; the actual JDK version number replaces the asterisk (*). For example, the name of this file in a WebSphere Application Server V4.0.3 environment for Windows is kwescl.1.3.1.jar.
5. If you choose to enable collection of garbage-collection statistics, activate the Enable garbage collection verbose mode option.
Changing the WebSphere Application Server Configuration
152 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
6. Click the Apply button.
Manual method: using the WebSphere administrative console for V4 cloned application servers
Use these steps to modify the configuration setting for an application server that belongs to a server group to enable the collection of workload analysis and trace data.
Note: You must follow these steps for horizontally cloned application servers. You may also use these steps to modify configuration setting for a vertical clone.
1. Access the WebSphere administrative console.
2. From the WebSphere administrative console’s navigation tree, choose the application server you want.
3. Select the JVM Settings tab, and, within the System Properties pane, press the Add button to define the following two system properties:A. Enter com.candle.kwe.instrument.user_control_file in the Name field.B. Enter <name of the main instrumentation control file> in the Value field. � For Windows, the file name is usually C:\Candle\CMA\<kweiuser.xml>.
For UNIX, the file name is usually $CANDLEHOME$/config/<kweiuser.xml>.
where <kweiuser.xml> is a Candle-provided or custom kweiuser.xml file. (See “Sample kweiuser.xml files” on page 121.)
4. Press the Add button, and then define the following two additional system properties:A. Enter com.candle.kwe.instrument.agent_parms in the Name field.B. Enter <full path name of the kweagent control file> in the Value field. For
Windows, the file name is usually C:\Candle\CMA\kwe.xml. For UNIX, the file name is usually $CANDLEHOME$/config/kwe.xml.
5. Press the Advanced JVM Settings button, and add the following jar files to the Boot classpath (prepend) field:For Windows:
C:\Candle\CMA\<kwescl.*.jar>;C:\Candle\CMA\kwewa.jar
Collecting Workload Analysis, Application Trace, and Heap Data 153
Changing the WebSphere Application Server Configuration
For Unix:
$CANDLEHOME/classes/<kwescl.*.jar>:$CANDLEHOME$/classes/kwewa.jar
Note: The name of the kwescl.*.jar file shown above depends upon your site’s version of the JDK; the actual JDK version number replaces the asterisk (*). For example, the name of this file in a WebSphere Application Server V4.0.3 environment for Windows is kwescl.1.3.1.jar.
Manual method: using the WebSphere administrative console for V4 server groups implementing vertical scaling
Use these steps to modify the configuration setting for a vertical server group to enable the collection of workload analysis and trace data for all the application servers that belong to the group.
1. Access the WebSphere administrative console.
2. From the WebSphere administrative console’s navigation tree, select the ServerGroup you want.
3. Press the Advanced JVM Settings button.The Advanced JVM Settings dialog appears.
4. Locate the Command Line Arguments field and enter the appropriate configuration settings for workload analysis and verbose garbage collection:For Windows:
-Xbootclasspath/p:C:\Candle\CMA\kwescl.*.jar;C:\Candle\CMA\kwewa.jar-Dcom.candle.kwe.instrument.user_control_file=<name of the main
instrumentation control file>-Dcom.candle.kwe.instrument.agent_parms=<full path name of the kweagent
control file>-verbosegc
On Windows, <name of the main instrumentation control file> is usually C:\Candle\CMA\<kweiuser.xml>, whereas <full path name of the kweagent control file> is usually C:\Candle\CMA\kwe.xml.
where <kweiuser.xml> is a Candle-provided or custom kweiuser.xml file. (See “Sample kweiuser.xml files” on page 121.)
Changing the WebSphere Application Server Configuration
154 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
For Unix:
-Xbootclasspath/p:$CANDLEHOME$/classes/kwescl.*.jar:$CANDLEHOME$/classes/kwewa.jar
-Dcom.candle.kwe.instrument.user_control_file=<name of the main instrumentation control file>
-Dcom.candle.kwe.instrument.agent_parms=<full path name of the kweagent control file>
-verbosegc
where $CANDLEHOME is the OMEGAMON XE agent installation directory. On UNIX, <name of the main instrumentation control file> is usually $CANDLEHOME$/config/<kweiuser.xml>, whereas <full path name of the kweagent control file> is usually $CANDLEHOME$/config/kwe.xml.
where <kweiuser.xml> is a Candle-provided or custom kweiuser.xml file. (See “Sample kweiuser.xml files” on page 121.)
Notes:
1. The name of the kwescl.*.jar file shown above depends upon your site’s version of the JDK; the actual JDK version number replaces the asterisk (*). This file was created when you ran the Candle class loader setup script; see “Launching the Class Loader Script for Workload Analysis” on page 148.
2. The -verbosegc parameter is required if your site is accumulating garbage-collection statistics; see “Your Agent’s Configuration Parameters and XML Tags” on page 91.
5. Press the OK button to close the Advanced JVM Settings dialog.
6. Press the Apply button to save and propagate the settings to all clones of this server group.
Manual method: using the WebSphere administrative console for V5
Follow these steps to modify the configuration setting for an application server to enable the collection of workload analysis and trace data.
1. Access the WebSphere administrative console.
2. Expand the WebSphere administrative console navigation tree: in the lefthand window, click the + sign.
3. Select Application Servers.
Collecting Workload Analysis, Application Trace, and Heap Data 155
Changing the WebSphere Application Server Configuration
4. In the righthand window, choose the application server whose configuration you want to modify.
5. In the resulting screen, select the Configuration tab.
6. From the Additional Properties area, select Process Definition.
7. In the resulting screen, under Additional Properties, select Java Virtual Machine.You must modify these fields in the General Properties area of the next screen:
A. The first field you modify is Boot classpath. Add the following configuration information.
� For Windows, enter:
C:\Candle\CMA\<kwescl.*.jar>;C:\Candle\CMA\kwewa.jar
For UNIX systems, enter:
$CANDLEHOME$/classes/<kwescl.*.jar>:$CANDLEHOME$/classes/kwewa.jar
Note: The name of the kwescl.*.jar file shown above depends upon your site’s version of the JDK; the actual JDK version number replaces the asterisk (*). For example, the name of this file in a WebSphere Application Server V5 environment for Windows is kwescl.1.3.1.jar. This file was created when you ran the Candle class loader setup script; see “Launching the Class Loader Script for Workload Analysis” on page 148.
B. Next, update the Generic JVM arguments field with the appropriate information for your OMEGAMON XE agent, as follows:-Dcom.candle.kwe.instrument.user_control_file=<file name of the main
instrumentation control file>
� For Windows, this file name is usually C:\Candle\CMA\<kweiuser.xml>.
For UNIX, this file name is usually $CANDLEHOME$/config/<kweiuser.xml>.
where <kweiuser.xml> is a Candle-provided or custom kweiuser.xml file. (See “Sample kweiuser.xml files” on page 121.)
-Dcom.candle.kwe.instrument.agent_parms=<full path name of the kweagent control file>
Changing the WebSphere Application Server Configuration
156 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
� For Windows, this file name is usually C:\Candle\CMA\kwe.xml
For UNIX, this file name is usually $CANDLEHOME$/config/kwe.xml
C. If you choose to enable collection of garbage-collection statistics, activate the Verbose garbage collection option.
8. Click the Apply button.
9. To save your updates, click the Save hyperlink.
Examples� Windows example:
-Dcom.candle.kwe.instrument.user_control_file=C:\Candle\CMA\kweiuser_development.xml
-Dcom.candle.kwe.instrument.agent_parms=C:\Candle\CMA\kwe.xml� UNIX example:
-Dcom.candle.kwe.instrument.user_control_file=/candle/config/kweiuser_production.xml
-Dcom.candle.kwe.instrument.agent_parms=/candle/config/kwe.xml
Dynamic method: using CandleNet Portal
Use this procedure to issue the Configuration Setup Take Action command in CandleNet Portal. This command alters the WebSphere Application Server configuration so that the workload analysis feature (including the heap usage and garbage-collection components) will be active in the application server the next time it starts. (You must have previously defined your workloads in kweiuser.xml and run the class loader setup script, setupCandleWAEnabler.)
1. In the Navigator, select and then right-click a WebSphere Application Server subnode, and choose Take Action from the pop-up menu.
2. In the Take Action dialog box, scroll through the Name box until you reach the WAS Configuration Setup command.
Collecting Workload Analysis, Application Trace, and Heap Data 157
Changing the WebSphere Application Server Configuration
3. Complete the fields in the Edit Argument Values dialog box that opens. Table 4 summarizes these fields.
4. From the Destination System(s) list, select one or more systems for which you want to report data.
5. Click OK to issue the Take Action command.
Note: The WAS Configuration Setup Take Action command does not overwrite an application server’s existing workload analysis configuration. If the server has already been configured for workload analysis (for example, for an older version of the OMEGAMON XE agent or from an agent installed on a different location), issue the WAS Configuration Setup N/N command to clean up the server’s existing workload analysis configuration; then reissue the WAS Configuration Setup Take Action command to enable workload analysis and garbage collection.
Table 4. Configuration Setup Take Action Command: Edit Argument Values Window
Argument Value Explanation
Workload_Analysis_Y_or_N=<{Y | N}> Do you want the server to collect workload analysis data? Type Y for yes or N for no.
VerboseGC_Y_or_N=<{Y | N}> Do you want the server to collect garbage-collection data? Type Y for yes or N for no.
File=<kweiuser.xml file name> <kweiuser.xml file name> is the name of the user instrumentation file, a Candle-provided or custom kweiuser.xml file. (See “Sample kweiuser.xml files” on page 121.)
This parameter is optional; if not specified, the name "kweiuser.xml" is used by default. The file specified here must exist in the standard location: \candle\cma on the Windows platform, and /CANDLEHOME/config on the UNIX platforms; see “Sample kweiuser.xml instrumentation control files” on page 120.
Changing the WebSphere Application Server Configuration
158 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Step 2. Recycle the application serverAfter you change the configuration settings for an application server, recycle the server to apply the settings for data collection. Use the Recycle Application Server Take Action command to recycle one or more application servers via the CandleNet Portal.
Collecting Workload Analysis, Application Trace, and Heap Data 159
Collecting Specific Workload Analysis Data for Different Application Servers
Collecting Specific Workload Analysis Data for Different Application Servers
BackgroundTo collect different classes of workload data when you have different WebSphere Application Servers running on the same node or different nodes, you need to provide a separate instrumentation control file for each server. You also need to customize the WebSphere Application Server command-line settings for the Advanced JVM Settings. This topic explains these procedures.
Create separate instrumentation filesDo the following to customize collection of workload data for multiple servers.
1. Make a separate copy of the kweiuser.xml file for each server for which you want to collect customized workload data, and save each with a unique name.
2. Put the copy of the kweiuser.xml instrumentation file in the correct location for your system.� On Windows systems, place the additional copies of the kweiuser.xml
instrumentation file in the C:\Candle\CMA directory.
� On UNIX systems, place the additional copies of the kweiuser.xml instrumentation file in the $CANDLEHOME$/config/ directory.
Modify the WebSphere Application Server command-line settingsWhen you want to collect data for an application server that requires an alternate version of the kweiuser.xml instrumentation file, you need to modify the WebSphere Application Server command-line settings to point to this alternative file:
1. Specify the JVM settings: Complete “Step 1. Change the application server configuration” on page 150 under section “Changing the WebSphere Application Server Configuration”.
2. Bring up the WebSphere administrative console.
Collecting Specific Workload Analysis Data for Different Application Servers
160 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
3. Modify the statement -Dcom.candle.kwe.instrument.control_file in the JVM Command line arguments field as follows: � For Windows systems, enter:
-Dcom.candle.kwe.instrument.control_file=C:\Candle\CMA\alternate_kweiuser.xml
For UNIX systems, enter:
-Dcom.candle.kwe.instrument.control_file=$CANDLEHOME$/config/alternate_kweiuser.xml
where alternate_kweiuser.xml is the name you selected for the alternate instrumentation file in step 1.
Collecting Workload Analysis, Application Trace, and Heap Data 161
Creating Specific Agent Control Files for Different Agents
Creating Specific Agent Control Files for Different Agents
BackgroundTo control the operation of the OMEGAMON XE agent on the same node (for example, because the node is running multiple versions of WebSphere Application Server) or different nodes, you need to provide a separate kwe.xml configuration file for each agent. You also need to customize the WebSphere Application Server command-line settings for the Advanced JVM Settings. This topic explains these procedures.
Create separate agent configuration filesCreate a separate agent configuration file (kwe.xml) for each agent:
On Windows, follow these steps:
1. Right-click on WebSphere Application Server Agent in the Manage Candle Services window, and select Create Instance.
2. Specify unique values for agent ID (for example, WIN001) and CollectorSessionPort.
3. Press the OK button.
4. A new agent instance appears in the Manage Candle Services window, and a new file, kwe_<AGENTID>.xml, is created in the C:\Candle\CMA directory for this agent. For example, kwe_WIN001.xml.
5. To customize this file, reconfigure the agent instance in Manage Candle Services window.
6. Using Manage Candle Services, start the agent.
Creating Specific Agent Control Files for Different Agents
162 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
On UNIX, follow these steps:
1. From the $CANDLEHOME$/bin directory, issue this command:./CandleCreateWEXML
2. Specify unique values for:– agent ID (for example, UNIX01)– WASAppServerRoot– CollectorSessionPort– (optional) AppTraceDirectory
For information about WASAppServerRoot, CollectorSessionPort, and AppTraceDirectory, see “Configuration files for multiple agents” on page 85.
A new file, kwe_<AGENTID>_##_<HOSTNAME>.xml, is created in $CANDLEHOME$/config directory. For example, kwe_UNIX01_##_host01.xml.
3. Edit this file, and update it as needed.
4. To start or stop the new agent, issue this command from the $CANDLEHOME$/bin directory:
./CandleAgent -o AGENTID start | stop we
Example:
./CandleAgent -o UNIX01 start we
Collecting Workload Analysis, Application Trace, and Heap Data 163
Creating Specific Agent Control Files for Different Agents
Specifying an alternate agent configuration fileWhen you want to customize an OMEGAMON XE agent’s kwe.xml configuration file, you need to modify the WebSphere Application Server command-line settings to point to the alternate file.
Dynamic method: using CandleNet Portal
1. Use CandleNet Portal’s Configuration Setup Take Action command to alter the WebSphere Application Server configuration to support the agent's workload analysis and garbage-collection features: Complete “Dynamic method: using CandleNet Portal” on page 156 under section “Changing the WebSphere Application Server Configuration”.
Manual method: using the WebSphere administrative console
1. Alter the WebSphere Application Server configuration to support the agent's workload analysis component: Based on your site’s WebSphere Application Server version, complete one of the manual methods given in “Step 1. Change the application server configuration” on page 150 under section “Changing the WebSphere Application Server Configuration”.
2. Start the WebSphere administrative console.
3. Modify the statement -Dcom.candle.kwe.instrument.agent_parms in either the JVM Command line arguments field (for WebSphere Application Server V4.0) or the Generic JVM arguments field (for WebSphere Application Server V5.0) as follows:For Windows systems, enter:
-Dcom.candle.kwe.instrument.agent_parms=C:\Candle\CMA\kwe_<AGENTID>.xml
For UNIX systems, enter:
-Dcom.candle.kwe.instrument.agent_parms=$CANDLEHOME$/config/kwe_<AGENTID>_##_<HOSTNAME>.xml
where <AGENTID> is the agent ID and <HOSTNAME> is the name of the host system.
Creating Specific Agent Control Files for Different Agents
164 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Introducing OMEGAMON XE for WebSphere Application Server Information 165
Introducing OMEGAMON XE forWebSphere Application Server
Information
OverviewThis chapter introduces you to the types of information reported by the various OMEGAMON XE for WebSphere Application Server workspaces. It explains how to access the information and provides a summary of its organization.
Chapter contents
OMEGAMON XE for WebSphere Application Server Data . . . . . . . . . . . . . . . . . 166Using OMEGAMON XE for WebSphere Application Server information. . . . 166Associating table views and charts with attributes . . . . . . . . . . . . . . . . . . . . . 167Data in the table views and charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Synchronizing data in reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Accessing the OMEGAMON XE for WebSphere Application Server Information . 169Accessing workspaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Historical Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Workspaces with historical data links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Requirements for historical data collection . . . . . . . . . . . . . . . . . . . . . . . . . . 171
OMEGAMON XE for WebSphere Application Server Workspaces. . . . . . . . . . . . 172Available workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
6
OMEGAMON XE for WebSphere Application Server Data
166 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
OMEGAMON XE for WebSphere Application Server Data
IntroductionThe OMEGAMON XE agent for WebSphere Application Server, like many other Candle agents, provides data that helps you monitor the health and performance of your WebSphere Application Server environment. CandleNet Portal (CNP) displays this information in named workspaces. Within a given workspace, this data can be presented in a tabular report format. CNP refers to this format as a table view. Data provided to workspace can also be displayed in the form of charts, graphs, or other formats that you choose.
Using OMEGAMON XE for WebSphere Application Server informationOMEGAMON XE for WebSphere Application Server provides the ability to view information about the WebSphere Application Server runtime environment that you are monitoring.
You can use this information to
� track the status of your WebSphere Application Server environment, including the WebSphere administrative server and one or more application servers that it is managing
� monitor the performance of each WebSphere Application Server, helping you to identify system bottlenecks and evaluate tuning decisions
� monitor the performance of your J2EE applications
� monitor the performance of workloads that you have defined
� collect and review trace data to analyze your J2EE performance
� select the most effective threshold values for situations you create
� review status information when a change in the state of a given resource occurs such as from OK to Warning or Warning to Critical
Introducing OMEGAMON XE for WebSphere Application Server Information 167
OMEGAMON XE for WebSphere Application Server Data
Associating table views and charts with attributesThere is a direct relationship between attribute groups in OMEGAMON XE for WebSphere Application Server and the table views and charts that display data in the workspaces. Individual attributes within a group correspond to the columns in the table views and data items presented by a chart shown in a workspace.
For example, the Application Server table view displays information collected by the Application Server attribute group. Each table view displays real-time information for many attributes. You can also display historical data collected over a time period that you define.
Data in the table views and chartsThe data in OMEGAMON XE for WebSphere Application Server table views or reports and charts is obtained from the WebSphere administrative server, the application servers it manages, the standard output logs for application servers, as well as the Candle Workload Analysis component, if it is active. If there is no data available for a particular attribute, the corresponding column in a table view will be blank.
By changing configuration settings for the OMEGAMON XE agent and the WebSphere Application Server and using the agent’s Take Action commands, you can activate the collection of workload, application trace, and heap data or set instrumentation levels for desired attributes. See the configuration section for detailed information.
� Performance data—You need to set instrumentation levels for certain attributes to collect and report performance data in workspaces that provide this information. For example, you need to set appropriate instrumentation level for the Enterprise Java Beans running in your WebSphere Application Server, so the agent can collect desired attributes to report EJB performance data. See “Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels” on page 81 for details.
� Workload data—You need to set up the collection of workload data in the kweiuser.xml file in which you define the workloads you want to track. After running the class loader setup script discussed in “Launching the Class Loader Script for Workload Analysis” on page 148 and adjusting the
OMEGAMON XE for WebSphere Application Server Data
168 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
WebSphere Application Server configuration you can begin data collection. See “Preparing the Instrumentation Control File for Workloads and Application Traces” on page 117 for details.
� Application trace data—You need to use the Start Application Tracing Take Action command to start tracing your application. This Take Action command will create a trace file, which you can review using the PathWAI Performance Analyzer product. See “Preparing the Instrumentation Control File for Workloads and Application Traces” on page 117 for details.
Synchronizing data in reportsYou may notice some discrepancies in the totals reported in columns for certain attributes in a table view. This anomaly is temporary and only happens the first time a new WebSphere Application Server resource is invoked and reported to the agent. Refreshing the reported data after invoking a new WebSphere Application Server resource will reconcile this data.
The discrepancies are related to the way sample data is reported. For most attributes, we report the delta value between two samples. In the very first sample that is used as the base, all the attributes are 0. When the next sample is taken, the delta values between the two samples are reported for the attributes. For server-level summary attributes, however, data are summarized in the WebSphere Application Server runtime, and this summarized total is used to calculate the delta value.
For example, if you invoke a new WebSphere Application Server application resource just after the agent reports a sample to CNP, the next agent sample will show a discrepancy in some totals reported for individual rows in the table view because the server level summary data is calculated using the total summarized by WebSphere Application Server, which already counts the activities in the newly invoked resource. Therefore, the totals reported in a server level summary row are not the same as the sum of the totals reported in other rows report.
Introducing OMEGAMON XE for WebSphere Application Server Information 169
Accessing the OMEGAMON XE for WebSphere Application Server Information
Accessing the OMEGAMON XE for WebSphere Application Server Information
Accessing workspacesTo access the workspaces for OMEGAMON XE for WebSphere Application Server, start from the CandleNet Portal Navigator, shown in Figure 9 on page 170. The hierarchy levels shown in the Navigator depend upon your enterprise’s customizations of the CandleNet Portal; however, to view the predefined workspaces provided by Candle, the navigation is:
1. Within the CandleNet Portal’s Navigator pane, expand Windows Systems, UNIX Systems, or Linux Systems, as appropriate.All monitored nodes of the selected type are listed.
2. Expand the entry that corresponds to the node whose WebSphere Application Server environment you need to examine.All OMEGAMON XE agents running on that node are listed.
3. Expand WebSphere Application Server Agent.The agent’s Application Trace Files and Product Events workspaces are listed, along with the WebSphere Application Servers that the agent is monitoring on this node.
4. Expand the WebSphere Application Server entry.All of this node’s WebSphere Application Servers are listed.
5. Expand the entry that corresponds to the server you need to examine.The predefined workspaces defined for this WebSphere Application Server are listed.
Note: To expand an entry, select the plug sign, +, to the left. The plus sign changes to a minus, -, and the entry’s constituent parts are listed. To collapse an expanded entry, select the minus.
Grayed-out items are not selectable.
Accessing the OMEGAMON XE for WebSphere Application Server Information
170 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 9. Navigator Items for the OMEGAMON XE for WebSphere Application Server V130 Agent
Introducing OMEGAMON XE for WebSphere Application Server Information 171
Historical Reporting
Historical Reporting
Workspaces with historical data linksMost workspaces allow collection and viewing of historical data. You can specify a time span over which to collect these data. The default setting is 15 minutes, but you can modify this setting to suit your needs.
Historical data is available in the table, bar chart, pie chart, and plot chart views when historical collection has been configured and started for the OMEGAMON XE agent associated with the view. Use these steps.
1. Open the workspace with the view for which you want historical data or define a historical workspace if none exists.
2. In the CandleNet Portal interface, choose the History Configuration icon in the tool bar shown here, or press Ctrl-H.
3. Complete the information for History Collection Configuration dialog box. See the CandleNet Portal online help for details.
Note: Before you can use the history feature, you must start historical data collection for the Candle agent or agents you want to report. See the Historical Data Collection Guide for OMEGAMON XE and CandleNet Command Center for details.
Requirements for historical data collectionTo ensure that data samplings are saved to populate your predefined historical workspaces, you must first configure your system to collect this data and then start historical data collection. This requirement does not apply to workspaces, such as the Product Events workspace, that use attribute groups that are historical in nature and show all their entries without you having to start data collection. See the Historical Data Collection Guide for OMEGAMON XE and CandleNet Command Center for more information.
OMEGAMON XE for WebSphere Application Server Workspaces
172 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
OMEGAMON XE for WebSphere Application Server Workspaces
OverviewThe workspaces for OMEGAMON XE for WebSphere Application Server are your windows to the data reported for WebSphere Application Server. They provide you with status, definitions, and statistical information for your WebSphere Application Server system.
Available workspacesOMEGAMON XE for WebSphere Application Server provides the following workspaces for managing your system. This workspace list reflects the order of the workspaces in the Navigator. Workspaces that are available from within are also listed.
� WebSphere Application Server Agent: The WebSphere Application Server Agent workspace displays system-wide status information that includes enterprise events, product events, and the current status of all the WebSphere Application Servers installed on the node. It also reports the status of the WebSphere administrative server being monitored by the OMEGAMON XE agent.
� Application Trace Files: The Application Trace File workspace reports information about each trace file in the trace directory.
� Agent Events*: The Product Events workspace reports product events that affect the ability of the agent for WebSphere Application Server to collect data.
� WebSphere Application Server - server name: The WebSphere Application Server - server name workspace displays server status information and graphic views of memory use and current active and live sessions.
� Application Server*: The Application Server workspace displays server status information and graphic views of memory use, database connections, transaction rates, and servlet rates.
Introducing OMEGAMON XE for WebSphere Application Server Information 173
OMEGAMON XE for WebSphere Application Server Workspaces
� All Workloads*: The All Workloads workspace contains information about all workloads that were executed during the interval.
� Suspected Memory Leaks*: The Suspected Memory Leaks workspace helps you identify workloads consuming excessive memory due to memory leaks in your applications.
� Heap Usage*: The Heap Usage workspaces provide statistics about attempts by applications running in the Java Virtual Machine to allocate object space on the heap.
� Garbage Collector Activity*: The JVM Garbage Collector Activity workspace displays garbage collection information for each JVM running an application server and graphic views of the number of garbage collections and percent of CPU used. This workspace monitors the overhead associated with running the garbage collector.
� Pool Utilization*: The Pool Utilization workspace displays information about the usage of several types of WebSphere Application Server pools, including Web container, ORB, J2C connection, and database connection.
� In-flight Workloads: The In-flight Workloads allow you to watch applications as they run in the Java Virtual Machine; this can help you isolate workloads that are hung up and consuming excessive CPU time.
� Longest Running Workloads*: The Longest Running Workloads workspace reports detailed information delay times for the longest running individual workload executions.
� HTTP Sessions*: The HTTP Sessions workspace reports information about active HTTP sessions for an application server.
� Datasources*: The Datasources workspace provides database usage information.
� Lock Analysis: The Lock Analysis workspace displays summary information by class and method regarding resources that have been locked by WebSphere Application Server.
� CTG Summary: The CTG Summary workspaces provide information about transactions running against the CICS Transaction Gateway, which provides WebSphere Application Server programmers access to legacy CICS applications.
OMEGAMON XE for WebSphere Application Server Workspaces
174 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
� JMS Summary: The JMS Summary workspace furnishes information about the JVM Message Services (JMS) queues that are accessed by an application server.
� Web Applications*: The Web Applications workspace displays information for each Web application running in each application server, including graphic views of average servlet response times and servlet exception and request rates.
� EJB Containers*: The EJB Containers workspace displays aggregated EJB information for each container in each application server and graphic views of bean instantiation rates and total method invocations.
� DB Connection Pools*: The DB Connection Pools workspace displays information for database connection pools associated with each applications server and graphic views of average pool size, average wait and use times, and connection rates.
These workspaces apply only to WebSphere Application Server V5.0 and above:
� J2EE Connector Connection Pools: The J2EE Connector Connection Pools workspace reports information about connectors that adhere to J2C, the WebSphere Application Server implementation of the J2EE Connector Architecture (JCA). JCA enables enterprise beans to connect to and interact with back-end systems, such as the Customer Information Control System (CICS) and the Information Management System (IMS).
� Thread Pools: The Thread Pools workspace reports information about the various thread pools, including thread creation and destruction rates and active versus free threads for each thread pool.
� Dynamic Cache*: The Dynamic Cache workspace reports information about the dynamic cache. WebSphere Application Server consolidates several caching activities, including servlets, Web services, and WebSphere commands into one service called the dynamic cache. The dynamic cache works within an application server Java Virtual Machine (JVM), intercepting calls to cachable objects and either storing the object’s output to or providing the object’s content from the dynamic cache.
Introducing OMEGAMON XE for WebSphere Application Server Information 175
OMEGAMON XE for WebSphere Application Server Workspaces
� Workload Management: The Workload Management workspace displays information about the Workload Management (WLM) server and the client that initiate workload requests. Workload management optimizes the distribution of client processing tasks. Incoming work requests are distributed to the application servers, enterprise beans, servlets, and other objects that process the requests.
WebSphere Application Server implements workload management by using clusters, transports, and replication domains.
* A history view of this workspace is also supplied.
OMEGAMON XE for WebSphere Application Server Workspaces
176 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
The CandleNet Portal Take Action Commands 177
The CandleNet PortalTake Action Commands
OverviewThis chapter identifies the Take Action commands available for OMEGAMON XE for WebSphere Application Server. It also provides some general guidelines regarding their use.
Chapter contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178About Take Action commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Prerequisite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Who can issue Take Action commands? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Available Take Action commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Initiating Take Action commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Using Take Action Commands in Situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
7
Introduction
178 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Introduction
About Take Action commandsOMEGAMON XE for WebSphere Application Server provides several predefined Take Action commands, which can be initiated from CandleNet Portal (CNP). This topic introduces you to the available commands and covers some general guidelines about their use.
Take Action commands let you stop or start the OMEGAMON XE agent’s data collection. They also help you configure WebSphere Application Server to enable the agent to collecting certain types of data, such as garbage-collection data. You can issue the commands for the agent in several ways: from the Take Action view, from a situation (when it becomes true), from the Navigator, and from a row in a table view.
For more information on how to use Take Action commands, refer to the online help for CandleNet Portal and the OMEGAMON XE agent.
PrerequisiteYou must include the TakeActionAuthUsers parameter in the kwe.xml configuration file in order to enable Take Action commands; see “Your Agent’s Configuration Parameters and XML Tags” on page 91. No one can issue Take Action commands unless this parameter is specified.
Who can issue Take Action commands?You can configure the OMEGAMON XE for WebSphere Application Server so that only a designated set of users can successfully issue its Take Action commands. To do this, authorize users to use Take Action commands through configuration options at
� the agent level, using the TakeActionAuthUsers keyword on the KWEAGENT XML tag in the kwe.xml configuration file
� the monitored application server level, using the TakeActionAuthUsers keyword on the MonitorAppServer XML tag in the kwe.xml configuration file
The CandleNet Portal Take Action Commands 179
Introduction
See “Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels” on page 81 for details on these parameters.
Available Take Action commandsOMEGAMON XE for WebSphere Application Server provides the following Take Action commands. The shaded rows group related commands.
Table 5. Take Action Commands for the OMEGAMON XE Agent
Command Use
WAS Start Application Server Start an application server
WAS Stop Application Server Stop an application server
WAS Recycle Application Server Stop and restart an application server
WAS Configuration Setup Change an application server’s configuration to perform workload analysis and, possibly, collect garbage-collection statistics as well
WAS SetIL Set instrumentation levels for WebSphere Application Server resources to collect performance data
WAS SetIL - All Set a single instrumentation level for all WebSphere Application Server resources
WAS SetIL - Dynamic Cache Set the PMI instrumentation level for dynamic caching activities
WAS SetIL - HTTP Session Set the instrumentation level for the HTTP sessions for the servlet engine
WAS SetIL - JVMMemory Set the instrumentation level for the Java Virtual Machine running the application server
WAS SetIL - J2C Pool Set the PMI instrumentation level for resource adapters that comply with the Java Connector Architecture (JCA) specification, including JMS destinations such as queues and topics
WAS SetIL - Object Pool Set instrumentation level for the bean object pool and specify arguments for the instrumentation level, container name, and bean name
Introduction
180 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
WAS SetIL - ORB Set the PMI instrumentation level for the object request brokers (ORBs)
WAS SetIL - Orb Thread Pool Set the instrumentation level for the ORB thread pools
WAS SetIL - Servlet Sessions Set the PMI instrumentation level for servlet sessions
WAS SetIL - ThreadPool Set the instrumentation level for the container thread pool
WAS SetIL - WCThread Pool Set the instrumentation level for the Web container thread pool
WAS SetIL - WebApplicationSubModule Set the instrumentation level for servlets/JSPs for a Web application
WAS SetIL - Workload Management Client
Set the PMI instrumentation level for workload management clients
WAS SetIL - Workload Management Server
Set the PMI instrumentation level for workload management servers
WAS Dynamic Workload Analysis Start or stop collecting workload analysis data
WAS Set Workload Exception Thresholds Define thresholds for collecting exception transactions
WAS Start Heap Collection Start or stop collecting heap data for a particular application server.
WAS Verbose GC Collection Stop and start the collection of garbage-collection statistics
WAS Set Capture Percent Set the percentage of workload and heap-allocation invocations the workload analysis component should collect.
WAS Set In-flight Threshold Define the CPU time threshold below which in-flight workloads are not reported.
WAS Set Longest Running Workload Threshold
Define the threshold for the collection and reporting of exceptional transactiondata
Table 5. Take Action Commands for the OMEGAMON XE Agent
Command Use
The CandleNet Portal Take Action Commands 181
Introduction
WAS Set Lock Analysis Level Set monitor-contention analysis levels and the minimum cost threshold for a particularapplication server
WAS Start Application Tracing Start application tracing.
WAS Stop Application Tracing Stop application tracing.
WAS Delete Application Tracing Files Delete application trace files.
WAS Dynamic Refresh Instrumentation Force the Workload Analysis component to re-read the instrumentation control file, kweiuser.xml
WAS Discover Servers Force the agent to discover newly defined application servers prior to the regularly scheduled discovery. (Auto-discovery currently runs every 15 minutes.)
Table 5. Take Action Commands for the OMEGAMON XE Agent
Command Use
Introduction
182 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Initiating Take Action commandsThese steps outline the general procedure for initiating a Take Action command. Refer to the CandleNet Portal online help for additional information about initiating and using Take Action commands.
1. Use one of the following procedures to initiate a Take Action command.� Select an item in the Navigator, right-click to display a pop-up menu, and
choose Take Action.
� Select a row within a table in a workspace right-click to display a pop-up menu, and choose Take Action.
2. In the Take Action dialog box, scroll the values in the Name field to bring up a list of commands.
3. In the Name field, choose the Take Action command you want and click Arguments to bring up the Edit Argument Values dialog.
4. Complete the Value fields and click OK to close the dialog.
5. In the Destination System(s) box, select one nor more systems for which you want to initiate the command.
6. Click OK to complete the dialog and issue the command.Each command and the values for its arguments are discussed in the remainder of this chapter.
The CandleNet Portal Take Action Commands 183
Using Take Action Commands in Situations
Using Take Action Commands in Situations
IntroductionYou can use Take Action commands from within predefined situations and in situations that you write. This feature is built into OMEGAMON XE products and is explained in the CandleNet Portal online help and in the Administering OMEGAMON Products: CandleNet Portal guide. The term that is used in these sources, reflex automation, refers to a situation that issues a command.
ProcedureTo issue a Take Action command, click the Action tab within the situation editor, and complete the System Command field. Prefix the command with WE:, and follow it with the Take Action command you want to use. Then press the Attribute Substitution button to add an attribute to the command. Enclose this attribute in single quotes.
Using Take Action Commands in Situations
184 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Appendix A: A Sample WebSphere Application Server Application: Best Practices 185
A Sample WebSphereApplication Server
Application: Best Practices
IntroductionThis appendix describes the ten samples that compose the Best Practices application. It also describes the process by which you install, configure, use, and uninstall this sample J2EE application.
Contents
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Installing the Best Practices Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Installation prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
DB2 database requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189WebSphere Application Server requirements . . . . . . . . . . . . . . . . . . . . . 189
Performing the installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Step 1. Install the CANDLEBP database. . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Step 2. Define the CandleDS datasource . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Step 3. Install the Best Practices application . . . . . . . . . . . . . . . . . . . . . . . . . 203Trouble-shooting the Best Practices installation. . . . . . . . . . . . . . . . . . . . . . . 218
Configuring OMEGAMON XE for WebSphere Application Server for the Best Practices Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Executing the Best Practices Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Before you invoke the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Running the Best Practices samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
The Best Practices Web interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Uninstalling the Best Practices Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Step 1. Uninstall the Best Practices application . . . . . . . . . . . . . . . . . . . . . . . 222Step 2. Remove the CandleDS datasource . . . . . . . . . . . . . . . . . . . . . . . . . . 222Step 3. Remove the CANDLEBP database. . . . . . . . . . . . . . . . . . . . . . . . . . 223
A
Overview
186 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Overview
Candle has developed samples that illustrate the preferred way to achieve certain results when using Java. Table 6 lists the functions provided in this single WebSphere Application Server application, as well as the programming principle each one illustrates.
Table 6. Candle’s Best Practices Source Fragments for Java Programming
Name Title and Principle Illustrated
AIMBP002 Better String Concatenation
Illustrates the performance advantage of using StringBuffer (rather than the ‘+’ operator) to concatenate strings.
AIMBP004 Make Read-only Entity Bean Methods
When you call an Entity bean method, the EJB 1.1 container first calls ejbLoad to get the latest data from the database for that bean, and then calls ejbStore to update the bean data in the database. When you call a read-only method that requires only getting data from the database, the EJB 1.1 container calls ejbLoad to get the data but still calls ejbStore to update the database. In this case, it is the unnecessary ejbStore call that causes extra overhead.
To reduce this overhead, WebSphere Application Server allows you to configure the access intent for Entity bean methods; the default is UPDATE. You should reconfigure read-only methods with READ access intent; this configuration tells WebSphere Application Server not to call ejbStore for that particular method.
AIMBP005 Use Proper Transaction Isolation Level
When concurrent transactions are trying to access a resource such as a database row, problems (like dirty read, unrepeatable read, phantom read) may arise. You can configure isolation levels to control these problems.
This example shows the performance impact of two different isolation levels, serializable and read committed.
Note: Not available with WebSphere Application Server V5.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 187
Overview
AIMBP006 Reuse EJB Home Objects
EJB clients must look up EJBHome object references through JNDI to access them; this type of naming and access mechanism ensures location transparency to all EJBs. But completing this JNDI lookup each time for an EJBHome object is redundant and unnecessary, and can cause code maintenance problems. Encapsulating and caching EJBHome object references in one place can resolve these problems.
AIMBP011 Use JDBC Connection Pooling
A JDBC connection represents a physical connection to a database. Acquiring and releasing connections imposes a great deal of overhead. The solution is to create a connection pool and get a connection from the connection pool.
AIMBP032 Use JDBC PreparedStatements
JDBC offers two statements (Statement and PreparedStatement) that you can use for invoking your own SQL statements. Choosing the right statement can improve performance significantly.
AIMBP033 Tune SQL Statements
Inefficient SQL statements require more processing time than efficient SQL statements; this sample demonstrates that difference. It also shows how a developer can miss response-time problems caused by inefficient SQL statements by testing with insufficient data.
AIMBP036 Use Proper useBean Scope
There are four scope attributes defined for the JSP useBean tag (page, request, session, application). Every scope has its own lifetime and occupies memory until its lifetime ends. Using the correct scope attribute consumes fewer memory resources and improves performance.
Table 6. Candle’s Best Practices Source Fragments for Java Programming
Name Title and Principle Illustrated
Overview
188 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Each sample describes the concept behind the indicated best practice and illustrates it with two applications, one that demonstrates adherence to the best practice and the other deviation from it. When executing each sample, you can explore OMEGAMON XE for WebSphere Application Server features that highlight the performance difference between each version.
AIMBP039 Use proper Synchronization
When analyzing multithreaded Java applications, thread contention can degrade the application performance significantly. This performance problem often occurs when multiple threads access synchronized methods or blocks simultaneously. Each thread remains in the queue to enter the synchronized method/block and reduces the throughput.
Two simple techniques can be implemented to reduce thread contention:
1. Synchronize only the necessary code blocks.2. Divide shared resources.This sample shows the advantage of fine-grained synchronization as described in technique 1.
AIMBP056 Release Object references when not needed
If unused objects remain referenced anywhere in your program, the JVM garbage collector cannot remove them. To avoid memory leaks programmers must explicitly unreference these objects whenever the references are held by other objects.
One additional interface button, Release Resources, is provided to explicitly remove this static variable data. When you press Release Resources, it removes all objects in static variables and invokes the garbage collector.
Table 6. Candle’s Best Practices Source Fragments for Java Programming
Name Title and Principle Illustrated
Appendix A: A Sample WebSphere Application Server Application: Best Practices 189
Installing the Best Practices Samples
Installing the Best Practices Samples
Installation prerequisitesThe Best Practices samples require either WebSphere Application Server V4 or WebSphere Application Server V5. Candle recommends you not install this application on your site’s production WebSphere Application Server or DB2 environment.
DB2 database requirements
Some of the samples interact with a DB2 database named CANDLEBP, as well as a schema and a table. Thus DB2 UDB should have been installed and be running when installing Best Practices. In the case of WebSphere Application Server V5, the WebSphere Application Server environment should have been configured to access DB2 as well (after configuring WebSphere Application Server V5 for DB2 access, you should test the database connection by using the WebSphere administrative console to create and test a sample datasource).
Installing the Best Practices populates the database with the necessary sample data. Hence the DB2 client must be installed and running on the local machine when you perform the installation.
Finally, you need a userid and a password that can modify the CANDLEBP database.
WebSphere Application Server requirements
The CandleBP application can be installed on either WebSphere Application Server V4 or WebSphere Application Server V5; the installation process you follow depends on the WebSphere Application Server version you’re running. To install the application, you must know the location of your WebSphere Application Server, which must already have been installed.
Performing the installation
190 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Performing the installation
Installing the application involves three steps, and they depend upon the operating platform and WebSphere Application Server version your site is running. These steps are:
Step 1. Install the CANDLEBP database . . . . . . . . . . . . . . . . . . . . . . . . 190Step 2. Define the CandleDS datasource . . . . . . . . . . . . . . . . . . . . . . . . 193Step 3. Install the Best Practices application . . . . . . . . . . . . . . . . . . . . . . 203
Note: If your WebSphere Application Server environment contains the 110 version of the Best Practices application (named CANDLEBP) or your DB2 environment contains the 110 version of the CANDLEBP database, you must first uninstall the previous application and datasource and drop the database before completing the following steps. See “Uninstalling the Best Practices Samples” on page 222.
Step 1. Install the CANDLEBP databaseThis step creates a DB2 UDB database named CANDLEBP, a schema, and a table; it is split into separate procedures by platform.
This procedure is separated by operating platform. UNIX users, see page 191.
Windows sites:
1. Update the db2cmd file CandleBPInstall.sql in directory C:\Candle\CMA\samples\j2ee_best_practices\websphere\database as follows:A. Edit the file.B. Locate this line:
connect to CANDLEBP;
C. Add the correct DB2 user name and password, like this:connect to CANDLEBP user <db2user> using <db2password>;
Use the same username and password you specify when running the AIMBP011 sample to create the connection pool. Note that these values are case-sensitive.
D. Save your changes, and close the editor.
2. Press the Windows Start button, select Programs –> IBM DB2, and open a DB2 command window from the pop-up menu.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 191
Performing the installation
3. To create and populate the CANDLEBP database, invoke the edited SQL file:db2cmd /c /w /i db2 -tf C:\Candle\CMA\samples\j2ee_best_practices\websphere\database\CandleBPInstall.sql
Note: The first time you build the database you will receive this error:
SQL1013N The database alias name or database name "CANDLEBP" could not be found. SQLSTATE=42705
Ignore this message.
Skip to “Step 2. Define the CandleDS datasource” on page 193.
UNIX sites:
1. To set environment variables and enable the DB2 command line processor, invoke this command:
<db2home>/<db2instance>/sqllib/db2profile
This procedure sets the following environment variables and values change as per your DB2 instance directory:
PATH= /home/db2inst1/sqllib/bin:/home/db2inst1/sqllib/adm:/home/db2inst1/sqllib/miscCLASSPATH=/home/db2inst1/sqllib/function:/home/db2inst1/sqllib/java/db2java.zip:
/home/db2inst1/sqllib/java/runtime.zip:.DB2INSTANCE=db2inst1SHLIB_PATH=:/home/db2inst1/sqllib/lib <This is the value for HP. For AIX, this
value is LIBPATH; for Solaris and Linux, it is LD_LIBRARY_PATH>
2. If you are using DB v7.2 or earlier, invoke the usejdbc2 command from the <db2home>/<db2instance>/sqllib/java12 directory. This command updates the CLASSPATH environment variable to point to the java12 directory rather than the java directory set in #1., as shown here:
CLASSPATH=/home/db2inst1/sqllib/function:/home/db2inst1/sqllib/java12/db2java.zip:/home/db2inst1/sqllib/java/runtime.zip:.
Note: If your site is running two DB2 instances, you must not run different db2profile files and mix environment variables from each.
3. Locate the DB2 command file CandleBPInstall.sql in directory $CANDLEHOME$/<platform>/samples/j2ee_best_practices/websphere/database, where <platform> is one of:
for AIX: aix433for HP-UX: hp11for Linux on Intel: li6243
Performing the installation
192 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
for Linux on zSeries: ls3223for Solaris: sol273
Update this file as follows:
A. Edit the file.B. Locate this line:
connect to CANDLEBP;
C. Add the correct DB2 user name and password, like this:connect to CANDLEBP user <db2user> using <db2password>;
Use the same username and password you specify when running the AIMBP011 sample to create the connection pool. Note that these values are case-sensitive.
D. Save your changes, and close the editor.
4. Open the DB2 command-line tool.
5. To create and populate the CANDLEBP database, invoke the edited SQL file:db2 -tf $CANDLEHOME$/<platform>/samples/j2ee_best_practices/websphere/database/CandleBPInstall.sql
where <platform> is one of the subdirectories listed in item 3.
6. Start or restart the server so WebSphere Application Server can locate the JDBC driver using the environment variables as redefined and can create the proper DB2 connections in the connection pool.Notes for both Windows and UNIX sites:
1. If security or other concerns prevent your creating the database with the above command, try creating the database, schema, and table using the individual SQL commands in CandleBPInstall.sql.
2. You must not alter the database, schema, or table names in the commands since the application uses same names to access the database.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 193
Performing the installation
Step 2. Define the CandleDS datasourceThis procedure is separated by WebSphere Application Server version. Version 5 users, see page 195.
WebSphere Application Server V4 sites:
1. Open the WebSphere administrative console.
2. Select Resources –> JDBC Providers –> Sample DB Driver –> Data Sources.
3. Right-click on Data Sources, and select New from the pop-up menu.The Data Source Properties window, shown in Figure 10 on page 194, appears.
Performing the installation
194 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 10. Data Source Properties window
4. Fill in this panel as follows:Name: CandleDSJNDI Name: CandleDS <this parameter is case sensitive>Description: To access CANDELBP databasedatabaseName: CANDLEBPuser: <DB2 user name to access the CANDLEBP database>password: <DB2 password to access the specified user name>
Appendix A: A Sample WebSphere Application Server Application: Best Practices 195
Performing the installation
5. Test the new database connection: press the Test Connection button. If this test fails, reenter the database values, and retest the connection.
6. Press the OK button.The CandleDS datasource is created. Continue with “Install the Best Practices application” on page 203.
WebSphere Application Server V5 sites:
UNIX users: Before beginning the datasource definition, you must set the proper DB2 environment variables: rerun db2profile from the same prompt where you started WebSphere Application Server; then start or restart the WebSphere Application Server V5 server. db2profile is located in <db2home>/<db2instance>/sqllib/db2profile. Either rerun db2profile whenever you start or restart the WebSphere server, or add this command to your own startup profile so it runs automatically whenever you log in.
1. Open the WebSphere administrative console.
2. Select Environment –> Manage WebSphere Variables, and ensure that the DB2_JDBC_DRIVER_PATH variable has a value. This variable must include the path containing the JDBC driver (db2java.zip).If this variable is undefined or doesn’t have the proper value, select the DB2_JDBC_DRIVER_PATH link, and enter the location of db2java.zip. This is typically the <db2InstanceDirectory>\sqllib\java directory (for Windows) or the <db2home>/<db2instance>/sqllib/java12 directory (for UNIX).
Notes:
1. UNIX users: Two java directories are available in <db2home>/<db2instance>/sqllib, one for java and one for java12. Both directories contain file db2java.zip (with their own JDBC drivers), so be careful when you set this value. You must use the java12 directory to leverage the Java 2 JDBC drivers.
2. If you are using the Network Deployment console to deploy the application and find that you have two database servers, one in a base server node and the other in a Network Deployment server node, this path should be the database path that communicates with the base server, since the application is deployed in the base server.
Performing the installation
196 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
3. Create the J2C Authentication Alias to access the database:A. Select Security –> JAAS Configuration –> J2C Authentication Data, and
press the New button.The J2C Authentication Data Entries panel, shown in Figure 11 on page 196, appears.
Figure 11. J2C Authentication Data Entries panel
B. Fill in this panel as follows:Alias: BPAliasUser ID: <DB2 user name to access the CANDLEBP database>Password: <DB2 password to access the specified user name>
Appendix A: A Sample WebSphere Application Server Application: Best Practices 197
Performing the installation
C. Press the Apply button.D. When prompted, save the master configuration.
4. Ensure the JDBC provider has been created: Select Resources –> JDBC Providers, and see whether the DB2 JDBC Provider (or, for WebSphere Application Server V5.1, the DB2 Legacy CLI-based Type 2 JDBC Driver) is listed among the DB2 databases in the JDBC Providers section. If it is, skip to part 5. on page 199; if not, you must create it:A. If you are using a Network Deployment console, first set the scope of the
base server and its node since you are going to deploy the Best Practices application in the base server rather than Network Deployment server (see Figure 12 on page 198):
Performing the installation
198 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 12. JDBC Providers screen
Appendix A: A Sample WebSphere Application Server Application: Best Practices 199
Performing the installation
a. Press the Browse Nodes button, and select the appropriate node.b. Press the Browse Servers button, and select the apprpriate server.c. Press the Apply button.
B. Press the New button, and select DB2 JDBC Provider (or, for WebSphere Application Server V5.1, the DB2 Legacy CLI-based Type 2 JDBC Driver) from the dropdown list.
C. Press the Apply button.The general properties of the DB2 JDBC Provider appear.
D. Press the Apply button to create either the DB2 JDBC Provider or the DB2 Legacy CLI-based Type 2 JDBC Driver.
E. Save both the local and master configuration.
5. Create the datasource:A. Select Resources –> JDBC Providers, and select either the DB2 JDBC
Provider or DB2 Legacy CLI-based Type 2 JDBC Driver link.B. Scroll to the bottom of the screen, and select the Data Sources link.C. Press the New button.
The datasource parameters screen, shown in Figure 13 on page 200, appears.
Performing the installation
200 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 13. Datasource parameters screen
D. Fill in this panel as follows:Name: CandleDSJNDI Name: CandleDS <case sensitive>Container manager persistence: <activate this check box>Description: datasource to access CANDLEBP database
Appendix A: A Sample WebSphere Application Server Application: Best Practices 201
Performing the installation
Datasource Helper Classname: <accept the default class name com.ibm.websphere.rsadapter.DB2DataStoreHelper; this class name should appear as the default; if not, supply it>
Component-managed Authentication Alias: BPAliasContainer-managed Authentication Alias: BPAlias
Note: The Best Practices application uses CandleDS as the JNDI name when accessing the database, so you must not change this.
E. Press the Apply button to create the CandleDS datasource.
6. Item 5. doesn’t create a fully operable datasource, so you must define the database name in its custom properties:A. Scroll to the bottom of the screen, and select Custom Properties.B. Select databaseName, and enter CANDLEBP in the Value field (see
Figure 14 on page 202).
Performing the installation
202 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 14. databaseName screen
C. Press the Apply button.D. Save both the local and master configuration.The CandleDS datasource is created.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 203
Performing the installation
Step 3. Install the Best Practices applicationThis procedure is separated by WebSphere Application Server version. Version 5 users, see page 208.
WebSphere Application Server V4 users:
1. Ensure the WebSphere administrative server is running.
2. Open the WebSphere administrative console.
3. Select the Enterprise Applications tab.
4. Right-click on Enterprise Applications, and select Install Enterprise Application from the pop-up menu.You are prompted to choose an ear file.
5. Press the Install Application (*ear) radio button; then press the Browse button to choose an ear file
6. Locate the BP40.ear file. For Windows, this files in located in:c:\Candle\CMA\samples\j2ee_best_practices\websphere\was4
UNIX users, look in:
$CANDLEHOME$/<platform>/samples/j2ee_best_practices/websphere/was4
where <platform> is one of:
for AIX: aix433for HP-UX: hp11for Linux on Intel: li6243for Linux on zSeries: ls3223for Solaris: sol273
7. The Install Enterprise Application Wizard, shown in Figure 15 on page 204, appears.
Performing the installation
204 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 15. Install Enterprise Application Wizard
8. Enter CandleBP as the application name.
9. Click the Next button, and continue clicking Next until you reach the Selecting Application Servers screen, shown in Figure 16 on page 205.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 205
Performing the installation
Figure 16. Selecting Application Servers screen
10. Select the BPEJB module, and press the Select Server button.The Select a Server or Server Group window, shown in Figure 17 on page 206, appears.
Performing the installation
206 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 17. Server or Server Group window
11. Select Default Server, and press the OK button.
Note: You may choose any server; it need not be the default server.
12. Repeat parts 10. and 11. for the BPWeb module.
13. Press the Next button.The Completing the Application Installation Wizard screen, shown in Figure 18 on page 207, appears.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 207
Performing the installation
Figure 18. Completing the Application Installation Wizard screen
14. Press the Finish button.A dialog box appears with message “Application code necessary for installation has already been generated. Regenerate code now?”.
15. Press the No button.The application is installed; when finished, a dialog box with message “Command "EnterpriseApp.install" completed successfully” appears.
16. Press the OK button.
17. Restart the default server (or whichever server you specified in part 11. on page 206).The Best Practices application is now installed.
Performing the installation
208 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
The CandleBP application is installed.
WebSphere Application Server V5 users:
1. Open the WebSphere administrative console.
2. In the Environment –> Manage WebSphere Variables screen, ensure environment variable APP_INSTALL_ROOT is set to ${USER_INSTALL_ROOT}/installedApps.
3. Select Applications –> Enterprise Applications.
4. Press the Install button.You are prompted to choose an ear file (see Figure 19 on page 209).
Appendix A: A Sample WebSphere Application Server Application: Best Practices 209
Performing the installation
Figure 19. Preparing for the application installation screen
5. If the ear file resides on the same machine as the browser, press the Local Path radio button, then press the Browse button, and locate the bp50.ear file, as Figure 19 illustrates. On the other hand, if the ear resides on any of the nodes in your cell context, press the Server Path radio button, and enter the path. For Windows this is:
C:\Candle\CMA\samples\j2ee_best_practices\websphere\was5\BP50.ear
For UNIX this is:
$CANDLEHOME$/<platform>/samples/j2ee_best_practices/websphere/was5/BP50.ear
Performing the installation
210 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
where <platform> is one of:
for AIX: aix433for HP-UX: hp11for Linux on Intel: li6243for Linux on zSeries: ls3223for Solaris: sol273
6. Press the Next button.
7. Leave the Preparing for the Application Installation menu options at their default settings, and press the Next button.The WebSphere administrative console begins guiding you through the multistep installation process:
A. At the first step, Provide Options to Perform the Installation (shown in Figure 20 on page 211), enter these values, leaving other values set as default:
Note: If your site is running Network Deployment, enter the appropriate node name for your base server.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 211
Performing the installation
Figure 20. Installation Options installation step
Performing the installation
212 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Using the base server console:Directory to install application: $(APP_INSTALL_ROOT)/$(CELL)Application name: CandleBP
Using the Network Deployment console:Directory to install application:
$(APP_INSTALL_ROOT)/<nodeName><where nodeName is the node name of the base server where you want to deploy the application; this you can obtain via System Administration –> Nodes. Note that if you fail to enter the correct node name at this step, the application will not be deployed in the proper place, and you may not be able to invoke it>
Application name: CandleBPPre-compile JSP <Put a check mark in this box, as shown in
Figure 20, to deactivate run-time compilation>
3. Press the Next button.4. Skip the subsequent installation steps (by pressing the Next button) until
you reach the Provide Default Datasource Mapping for Modules Containing 2.0 Entity Beans step (shown in Figure 21 on page 213).
5. At this step, select module BPEJB.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 213
Performing the installation
Figure 21. Provide Default Datasource Mapping installation step
6. Press the Next button.7. Skip the subsequent steps (by pressing the Next button) until you reach
the Map Resource References to Resources step (shown in Figure 22 on page 214).
8. At this step and again at the next step, Map Virtual Hosts for Web Modules (shown in Figure 23 on page 215), select the BestPractices module.
Performing the installation
214 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 22. Map Resource References installation step
Appendix A: A Sample WebSphere Application Server Application: Best Practices 215
Performing the installation
Figure 23. Map Virtual Hosts installation step
9. In the Map Modules to Application Servers step (shown in Figure 24 on page 216), select modules BPEJB and BestPractices, then select server1, and press the Apply button.
Performing the installation
216 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Figure 24. Map Modules to Application Servers installation step
10. Then select the BPEJB and BestPractices modules again, and press the Next button.
11. Skip all remaining steps (by pressing the Next button again) until you reach the Summary.
12. Press the Finish button.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 217
Performing the installation
A dialog box showing a confirmation message appears, prompting you to save the master configuration.
8. Select the Save to Master Configuration link.
9. Select Applications –> Enterprise Applications.
10. Select CandleBP, and press the Start button.
11. Recycle the application server.The CandleBP application is started and ready to serve client requests.
Performing the installation
218 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Trouble-shooting the Best Practices installationProblem: I see blank pages when I run the Make read only Entity bean methods and the Use JDBC Connection Pooling samples.Response: The Best Practices application uses the following values to access both the datasource and the database. Ensure you have created the data source and data base with these names:
Datasource Name: CandleDSDatasource JNDI Name: CandleDS <note that this specification is case
sensitive>Database Name: CANDLEBP
Problem: I couldn’t install Best Practices using the bp50.ear file.Response: If you don’t follow the installation instructions carefully, the installation may fail. Delete the CANDLEBP application as described in “Uninstalling the Best Practices Samples” on page 222, and install again.
Problem: I couldn’t invoke the application using the URL http://<hostname>:<port>/BestPractices.Response: Verify the host name and port number. Ensure the port number is defined in the Virtual Hosts screen of the WebSphere administrative console.
In a Network Deployment environment, this problem arises if the base server’s HTTP port number is not defined to Network Deployment when you added the node to the cell. Using the WebSphere administrative console, add the base server’s HTTP port number to the Network Deployment host aliases: Go to Environment –> Virtual Hosts –> default_host –> Host Aliases, press the New button, and set Host Name to * and Port to the base server’s HTTP port number.
Problem: Some Best Practices samples are throwing exception SQL1224N A database agent could not be started to service a request, or was terminated as a result of a database system shutdown or a force command. SQLSTATE=55032 on UNIX platforms.Response: This exception occurs because DB2 could not obtain a new shared memory segment. Go to IBM’s DB2 technical support Knowledge Base Web site, and follow the instructions in the Details for Technote 1009742 section to fix this DB2 problem.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 219
Configuring OMEGAMON XE for WebSphere Application Server for the Best Practices Sam-
Configuring OMEGAMON XE for WebSphere Application Server for the Best Practices Samples
If you want to use the OMEGAMON XE agent for WebSphere Application Server to collect workload analysis data about the Best Practices application, you must first configure the agent to collect workload data. Here is a sample Class tag that instruments the Best Practices application for workload analysis; add this to your site’s other Class specifications in the kweiuser.xml control file.
<Class Name="*BP*"ClassType="user"MethodNames="*"MethodType="SERVLET,EJB,METHODS"HeapAnalysis="*"LockAnalysis="true">
</Class>
For details about kweiuser.xml and its contents, see “Inside the User Instrumentation Control File” on page 120.
Executing the Best Practices Samples
220 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Executing the Best Practices Samples
Before you invoke the applicationIf you install the Best Practices application on WebSphere Application Server V4.1 and later upgrade to WebSphere Application Server V4.2 or later, you must modify the CandleBPDataSource: You must change the database password to the value you specified during installation, as follows:
1. From the WebSphere administrative console, select Resources –> JDBC Drivers –> CandleBP DB Driver.
2. Select the Data Sources folder.
3. In the Custom Properties panel, modify the password value.You can start WebSphere Application Server (either the default server or server1, depending on the version of WebSphere Application Server your site is running) from either the WebSphere administrative console or the OMEGAMON XE agent for WebSphere Application Server, via the Take Action command WAS Start Application Server.
Running the Best Practices samplesAccess the Best Practices from your Internet browser, using the URL http://<node>:<port>/BestPractices, where:
� <node> is the computer running WebSphere Application Server
� <port> is either the port assigned to the default application server when you install the Best Practices under WebSphere Application Server V4 or the HTTP port assigned to the default application server, server1, when you install the Best Practices under WebSphere Application Server V5 (usually this is 8880).
WebSphere Application Server V4 users can determine the port number using the WebSphere administrative console under the Virtual Hosts tab. You will also find the port number in the WebSphere administrative console’s message area when you start or restart the default server: the message area displays a message showing the listening port number, for example, “SRVE0171I: Transport http is listening on port 9,117”. In this case, the port number is 9117.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 221
Executing the Best Practices Samples
WebSphere Application Server V5 users can determine the port number using the WebSphere administrative console: select Environment –> Virtual Hosts –> default_host –> Host Aliases.
Example: You’re running WebSphere Application Server V4. If your Web browser is running on the same Windows host, named Java01, as the default server and WebSphere administrative console tells you the port number is 9081, access the application via this URL:
http://Java01:9081/BestPractices
You can use any of the features of OMEGAMON XE for WebSphere Application Server to observe the server’s behavior while executing the Best Practices samples, but the workload analysis feature may be the most valuable; see “Configuring OMEGAMON XE for WebSphere Application Server for the Best Practices Samples” on page 219 for instructions for enabling this feature.
The Best Practices Web interface
When you select a Best Practice from the Best Practices Web page, a new page with the following selectable items appears:
The Description provides the background for a bad coding practice and introduces the recommended practice.
The Sample description explains the structure of the sample code for both the bad coding practice and the recommended practice. Use each description in conjunction with the code fragments in the Sample Code section.
Under Test the Sample the Execute Bad Code button executes the sample code with the bad coding practice, whereas the Execute Good Code button executes the sample code that follows the recommended practice. Press a button to observe the response time for that code fragment; the response time appears beneath the buttons.
See the results in OMEGAMON describes specific CandleNet Portal workspaces where you can observe the response-time information that the OMEGAMON XE agent collects for each sample.
The Sample Code section provides the code fragments for both the bad and the recommended practice.
To return to the Best Practices home page, click the Return to Directory hyperlink.
Uninstalling the Best Practices Samples
222 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Uninstalling the Best Practices Samples
Uninstalling Best Practices is again a three-step process: First you need to uninstall the CandleBP application, then remove the CandleDS data source, and finally drop the CANDLEBP database.
Step 1. Uninstall the Best Practices applicationWebSphere Application Server V4 users:
1. Open the WebSphere administrative console.
2. Select Enterprise Applications –> CandleBP.
3. Right-click CandleBP, and select Stop from the pop-up menu to stop the CandleBP application,
4. Right-click CandleBP again, and select Remove from the pop-up menu.A confirmation dialog box appears.
5. Press the Yes button.WebSphere Application Server V5 users:
1. Open the WebSphere administrative console.
2. Select Applications –> Enterprise Applications –> CandleBP.
3. Press the Stop button to stop the CandleBP application.
4. Press the Uninstall button to remove the application.A dialog box appears prompting you to save your changes.
5. Press the Save button.A second dialog box appears prompting you to save the master configuration.
6. Press the Save button again.
Step 2. Remove the CandleDS datasourceWebSphere Application Server V4 users:
1. Select Resources –> JDBC Providers –> Sample DB Driver –> Data Sources, and select CandleDS.
2. Right-click CandleDS, and select Remove from the pop-up menu.
Appendix A: A Sample WebSphere Application Server Application: Best Practices 223
Uninstalling the Best Practices Samples
A confirmation dialog box appears.
3. Press the Yes button.WebSphere Application Server V5 users:
1. Select Resources –> JDBC Providers –> DB2 JDBC Provider –> Data Sources, and select CandleDS.
Note: In version 119 of the Best Practices application, the datasource was named CANDLEBP instead of CandleDS.
2. Press the Delete button.A dialog box appears prompting you to save your changes.
3. Press the Save button.A second dialog box appears prompting you to save the master configuration.
4. Press the Save button again.
Step 3. Remove the CANDLEBP databaseThese instructions depend on the platform your site is running. UNIX users, see page 224.
Windows sites:
You can delete the database using either an SQL DROP statement or the DB2 Control Center. To use SQL, enter this command:
DROP DATABASE CANDLEBP
The CANDLEBP database is deleted.
To delete the database using the DB2 Control Center:
1. Press the Windows Start button, select Programs –> IBM DB2, and select Open DB2 Control Center.
2. Select Systems –> <node name> –> DB2 –> Databases –> CANDLEBP.
3. Right-click on CANDLEBP, and select Drop from the pop-up menu.
4. Press the OK button.The CANDLEBP database is deleted.
Uninstalling the Best Practices Samples
224 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Note: If security or other concerns prevent your deleting the database with this command, uninstall the database using the SQL DROP command given above.
UNIX sites:
To delete the CANDLEBP database, use the following SQL DROP command:
DROP DATABASE CANDLEBP
The CANDLEBP database is deleted.
Appendix B: Historical Reference Information for Attributes 225
Historical ReferenceInformation for Attributes
IntroductionThis appendix lists the attribute tables that are accumulated by default in the long-term historical data collection (HDC) files and shows the historical reference information that identifies each attribute within each table.
The tables are arranged in alphabetical order according to the name of the attribute group. The value in parentheses in each title is the name of the attribute table.
Each table is sorted alphabetically by the HDC terms used for the attributes. Scroll the left column in a table for the HDC reference term that was reported in the HDC data, and then look in the right column for the name of the attribute, as documented in the online help for OMEGAMON XE for WebSphere Application Server.
Appendix contentsAll Workloads V2 attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Allocation Failure Block Detail attribute group. . . . . . . . . . . . . . . . . . . . . . . . . . . 231Application Server attribute group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Application Server Errors attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Application Server Status attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Container Object Pools attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Container Transactions attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241CTG Summary attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244Current Objects for Selected Class attribute group. . . . . . . . . . . . . . . . . . . . . . . . 246Datasources attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248DB Connection Pools attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Dynamic Cache attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
B
226 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Dynamic Cache Templates attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253EJB Containers attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255Enterprise Java Beans attribute group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Enterprise Java Bean Methods attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . 262Garbage Collector Activity attribute group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Garbage Collection Cycle Detail attribute group . . . . . . . . . . . . . . . . . . . . . . . . . 265Heap Usage attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267HTTP Sessions attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268In-flight Workloads attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270In-flight Workload Detail attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274J2C Connection Pools attribute group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276JMS Summary attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Lock Analysis by Method Detail attribute group . . . . . . . . . . . . . . . . . . . . . . . . . 280Lock Analysis by Method Summary attribute group . . . . . . . . . . . . . . . . . . . . . . 282Lock Analysis by Workload attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283Lock Analysis by Workload Detail attribute group . . . . . . . . . . . . . . . . . . . . . . . . 284Lock Owner for Selected In-flight Workload attribute group . . . . . . . . . . . . . . . . 286Longest Running Workloads V2 attribute group . . . . . . . . . . . . . . . . . . . . . . . . . 288Methods Instantiating Selected Class attribute group . . . . . . . . . . . . . . . . . . . . . . 291WebSphere Distributed Product Events attribute group . . . . . . . . . . . . . . . . . . . . 292References to Objects for Selected Allocation Source attribute group. . . . . . . . . . 293Selected Workload Delays attribute group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295Servlet Sessions attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Servlets JSPs attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Suspected Memory Leaks attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Thread Pools attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Web Applications attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Workload Class Instantiations attribute group . . . . . . . . . . . . . . . . . . . . . . . . . . . 304Workload Management WLM Client attribute group . . . . . . . . . . . . . . . . . . . . . . 305Workload Management WLM Server attribute group . . . . . . . . . . . . . . . . . . . . . 306
Appendix B: Historical Reference Information for Attributes 227
All Workloads V2 attribute group
Table 7. All Workloads V2 attribute group (KWEWLDS2)
Term Reported by HDC Attribute Name
C1 Node Name
C2 Sample Date and Time
C3 Interval Time
C7 Number of Occurrences
C8 Rate of Occurrence
C9 Total Time
C10 Average Time
C11 Max Time
C12 Number Servlet Delays
C13 Servlet Delay Time
C14 Servlet Delay Percent
C15 Number EJB Method Delays
C16 EJB Method Delay Time
C17 EJB Method Delay Percent
C18 Number EJB Home Delays
C19 EJB Home Delay Time
C20 EJB Home Delay Percent
C21 Number EJB Remote Delays
C22 EJB Remote Delay Time
C23 EJB Remote Delay Percent
C24 Number SQL Connection Delays
C25 SQL Connection Delay Time
C26 SQL Connection Delay Percent
C27 Number SQL Query Delays
228 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
C28 SQL Query Delay Time
C29 SQL Query Delay Percent
C30 Number SQL Update Delays
C31 SQL Update Delay Time
C32 SQL Update Delay Percent
C33 Number JNDI Delays
C34 JNDI Delay Time
C35 JNDI Delay Percent
C36 Number JMS Delays
C37 JMS Delay Time
C38 JMS Delay Percent
C39 Number JTA Delays
C40 JTA Delay Time
C41 JTA Delay Percent
C45 Number User-defined Delays
C46 User-defined Delay Time
C47 User-defined Delay Percent
C48 Number Miscellaneous Delays
C49 Miscellaneous Delay Time
C50 Miscellaneous Delay Percent
C53 Total CPU Time
C54 Average CPU Time
C55 Number CTG Delays
C56 CTG Delay Time
C57 CTG Delay Percent
Table 7. All Workloads V2 attribute group (KWEWLDS2)
Term Reported by HDC Attribute Name
Appendix B: Historical Reference Information for Attributes 229
C58 Number JCA Delays
C59 JCA Delay Time
C60 JCA Delay Percent
C61 Number Heap Alloc Delays
C62 Heap Alloc Delay Time
C63 Heap Alloc Delay Percent
C64 Total Number Heap Alloc
C65 Average Number Heap Alloc
C66 Number EJB Local Home Delays
C67 EJB Local Home Delay Time
C68 EJB Local Home Delay Percent
C69 Number EJB Local Object Delays
C70 EJB Local Object Delay Time
C71 EJB Local Object Delay Percent
C72 Number of Locks Acquired
C73 Average Time To Lock
ORIGINNODE Origin Node
SERVER_NAM Server Name
WORK_NM1 Class/Major Name
WORK_NM2 Method/Minor Name
WORK_TYPE Workload Type
Table 7. All Workloads V2 attribute group (KWEWLDS2)
Term Reported by HDC Attribute Name
230 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
HDC Parameters:All Workloads V2 attribute group (KWEWLDS2)
Active by default? no
Record size in bytes 1208
Recording frequency 1 record per interval for each workload in each application server
Appendix B: Historical Reference Information for Attributes 231
Allocation Failure Block Detail attribute group
Table 8. Allocation Failure Block Detail attribute group (KWEGCAFB)
Term Reported by HDC Attribute Name
ACTIONS Action Taken
AF_NO Allocation Failure Number
BYTE_FREED Kbytes Freed
BYTES_NEED Bytes Needed
EXP_HEAP Heap Expanded (KB)
GC_CYCLES Number of Garbage Collection Cycles
HEAP_FREEP Percent of Heap Free
INT_TIME Interval Time
MAIN_AVAIL Main Heap Space Free (KB)
MAIN_TOTAL Main Heap Capacity (KB)
NODE_NAME Node Name
OBJS_MOVED Objects Moved
ORIGINNODE Origin Node
OUT_OF_MEM Heap Status
PID Process ID
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
TIME_COMP Time to Complete
TIME_INT Time since Last Failure
TOTAL_AVAI Kbytes Free at Start of GC
TOTAL_FREE Total Kbytes Freed
TOTAL_USED Kbytes in Use
WILD_AVAIL Wilderness Heap Space Free (KB)
WILD_TOTAL Wilderness Heap Capacity (KB)
232 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
HDC Parameters:Allocation Failure Block Detail attribute group
(KWEGCAFB)
Active by default? no
Record size in bytes 664
Recording frequency 1 record per interval fo each allocation failure block
Appendix B: Historical Reference Information for Attributes 233
Application Server attribute group
Table 9. Application Server attribute group (KWEAPPSRV)
Term Reported by HDC Attribute Name
AS_CPU CPU Milliseconds Used
AS_CPUP Percent of CPU Used
AVG_ACTSES Average Concurrently Active Sessions
AVG_LIVSES Average Number of Concurrently Live Sessions
AVG_SESLIF Lifetime of Sessions
HTTP_SESS Number of HTTP Sessions
HTTP_SESSA Number of HTTP Session Attributes
INT_TIME Interval Time
JVM_IL Java Virtual Machine Instrumentation Level
MAX_SIZE Configured Maximum Number of ORB Pooled Threads
MAX_WC_SIZ Configured Maximum Number of WC Pooled Threads
MEM_FREE JVM Free Memory Size
MEM_SIZE JVM Used Memory Size
MEM_TOTAL JVM Total Memory Size
NODE_NAME Node Name
NUM_ACTTHR Average Active Threads in the ORB Pool
NUM_ALLOC Connections Allocated
NUM_CCREAT Connections Created
NUM_CDESTR Connections Destroyed
NUM_CREATE ORB Threads Created
NUM_DESTRY ORB Threads Destroyed
NUM_SCREAT Sessions Created
NUM_SFINAL Sessions Finalized
234 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
NUM_SINVAL Sessions Invalidated
NUM_TOTTHR Average Threads in the ORB Pool
NUM_WC_ATH Average Active Threads in the WC Pool
NUM_WC_CRT WC Threads Created
NUM_WC_DST WC Threads Destroyed
NUM_WC_TTH Average Threads in the WC Pool
OTP_IL OTP Instrumentation Level
ORIGINNODE Origin Node
PCT_TIMMAX % of Time ORB Thread Count Exceeded Maximum
PCT_TO_TMM % of Time Thread Count Exceeded Maximum in All Pools
PCT_WC_TMM % of Time WC Thread Count Exceeded Maximum
PID Process ID
PROF_AVAL Collector Session Active
PROF_TYPE Collector Session Type
RTE_COMMIT Transaction Commit Rate
RTE_CREATE ORB Thread Creation Rate
RTE_DESTRY ORB Thread Destroy Rate
RTE_ERROR Servlet Exception Rate
RTE_INSTNT Bean Instantiation Rate
RTE_RB Transaction Rollback Rate
RTE_REQ Servlet Request Rate
RTE_SCREAT Session Creation Rate
RTE_SFINAL Session Finalization Rate
Table 9. Application Server attribute group (KWEAPPSRV)
Term Reported by HDC Attribute Name
Appendix B: Historical Reference Information for Attributes 235
RTE_SINVAL Session Invalidation Rate
RTE_TO_CRT Total Thread Creation Rate
RTE_TO_DST Total Thread Destroy Rate
RTE_TO_CRT Total Thread Creation Rate
RTE_TO_DST Total Thread Destroy Rate
RTE_TRANS Transaction Process Rate
RTE_WC_CRT WC Thread Creation Rate
RTE_WC_DST WC Thread Destroy Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SESS_CREAT Total Sessions Created
SESS_I_2_F Session Invalidation to Finalization Time
SESS_UTRAK Total Untracked Sessions
SESSM_IL Session Manager Instrumentation Level
STDATE_TIM Start Date and Time
STATUS Status
S1 Number of In-flight Workloads
S2 Workload Capture Percentage
S3 Heap Capture Percentage
S4 Total HTTP Session Object Size
TO_THRD_IL Total Thread Instrumentation Level
TYPE Server Type
WAS_VERS Version
WC_THRD_IL WC Thread Instrumentation Level
Table 9. Application Server attribute group (KWEAPPSRV)
Term Reported by HDC Attribute Name
236 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
HDC Parameters:Application Server attribute group (KWEAPPSRV)
Active by default? yes
Record size in bytes 1048
Recording frequency 1 record per interval per application server
Appendix B: Historical Reference Information for Attributes 237
Application Server Errors attribute group
Table 10. Application Server Errors attribute group (KWEASERR)
Term Reported by HDC Attribute Name
COMPONENT Component
ERR_MSG Message Text
MSG_ID Message ID
NODE_NAME Node Name
ORIGINNODE Origin Node
SDATE_TIME Error Date and Time
SERVER_NAM Server Name
SEVERITY Severity
THREADID Thread ID
HDC Parameters:Application Server Errors attribute group (KWEASERR)
Active by default? no
Record size in bytes 998
Recording frequency 1 record for every record written into the application server log file
238 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Application Server Status attribute group
Table 11. Application Server Status attribute group (KWEAPSST)
Term Reported by HDC Attribute Name
NODE_NAME Node Name
ORIGINNODE Origin Node
PID Process ID
SDATE_TIME Date and Time
SERVER_NAM Server Name
SRVGRP_NAM Cluster Name
STATUS Status
STDATE_TIM Start Date and Time
TYPE Server Type
HDC Parameters:Application Server Status attribute group (KWEAPSST)
Active by default? no
Record size in bytes 712
Recording frequency 1 record per server per cycle
Appendix B: Historical Reference Information for Attributes 239
Container Object Pools attribute group
Table 12. Container Object Pools attribute group (KWEEBOP)
Term Reported by HDC Attribute Name
AVG_DR_SZ Average Number of Objects Discarded
CONT_NAME Container Name
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
NODE_NAME Node Name
NUM_DRAIN Times the Pool Was Found Idle
NUM_GET_FN Pool Retrieval Hit Count
NUM_GETS Calls Retrieving an Object from the Pool
NUM_PUT Calls Returning an Object to the Pool
NUM_PUT_DS Times the Returned Object Was Discarded
ORIGINNODE Origin Node
POOL_SIZE Average Number of Objects in the Pool
RTE_DRAIN Drain Rate
RTE_GET_FN Retrieve Availability Rate
RTE_GETS Retrieval Rate
RTE_PUT Return Rate
RTE_PUT_DS Discard Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SUMMARY Summary of All Containers
240 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
HDC Parameters:Container Object Pools attribute group (KWEEBOP)
Active by default? no
Record size in bytes 832
Recording frequency 1 record per interval per application server, plus 1 record per interval per EJB container
Appendix B: Historical Reference Information for Attributes 241
Container Transactions attribute group
Table 13. Container Transactions attribute group (KWETRANS)
Term Reported by HDC Attribute Name
ACT_GL_TRN Active Global Transactions
ACT_LC_TRN Active Local Transactions
AVG_DUR Average Duration of Transactions
AVG_TRANS Average Number of Active Transactions
CONT_NAME Container Name
GL_BC_DUR Global Before Completion Duration
GL_CM_DUR Global Commit Duration
GL_PR_DUR Global Prepare Duration
GL_TR_BEG Global Transactions Begun
GL_TR_COM Global Transactions Committed
GL_TR_DUR Global Transaction Duration
GL_TR_INV Global Transactions Involved
GL_TR_RB Global Transactions Rolled Back
GL_TR_TO Global Transaction Timeouts
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
LC_BC_DUR Local Before Completion Duration
LC_CM_DUR Local Commit Duration
LC_TR_BEG Local Transactions Begun
LC_TR_COM Local Transactions Committed
LC_TR_DUR Local Transaction Duration
LC_TR_RB Local Transactions Rolled Back
LC_TR_TO Local Transaction Timeouts
NODE_NAME Node Name
242 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
NUM_BPT Average Bean Objects per Transaction
NUM_COMMIT Transactions Committed
NUM_MPT Average Methods per Transaction
NUM_OPT Number Optimization
NUM_RB Transactions Rolled Back
NUM_TRANS Transactions Processed
ORIGINNODE Origin Node
RTE_COMMIT Transaction Commit Rate
RTE_GT_BEG Global Transactions Begun Rate
RTE_GT_COM Global Transactions Commit Rate
RTE_GT_INV Global Transactions Involved Rate
RTE_GT_RB Global Transactions Rollback Rate
RTE_GT_TO Global Transaction Timeout Rate
RTE_LT_BEG Local Transactions Begun Rate
RTE_LT_COM Local Transactions Commit Rate
RTE_LT_RB Local Transactions Rollback Rate
RTE_LT_TO Local Transaction Timeout Rate
RTE_OPT Optimization Rate
RTE_RB Transaction Rollback Rate
RTE_TRANS Transaction Process Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SUMMARY Summary of All Containers
TRANS_IL Transaction Instrumentation Level
Table 13. Container Transactions attribute group (KWETRANS)
Term Reported by HDC Attribute Name
Appendix B: Historical Reference Information for Attributes 243
HDC Parameters:Container Transactions attribute group (KWETRANS)
Active by default? no
Record size in bytes 920
Recording frequency 1 record per interval per application server, plus 1 record per interval per EJB container
244 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
CTG Summary attribute group
Table 14. CTG Summary attribute group (KWETGSUM)
Term Reported by HDC Attribute Name
AVG_CTG Average CTG Response Time
AVG_ECTIME Average ECI Time
AVG_EPTIME Average EPI Time
AVG_ESTIME Average ESI Time
CICS_SERVR CICS Server
CTG_HOST Gateway Host Name
CTG_PORT Gateway Port
ECI_RATE ECI Rate
EPI_RATE EPI Rate
ESI_RATE ESI Rate
INT_TIME Interval Time
NODE_NAME Node Name
NUM_ECI Total ECI Requests
NUM_EPI Total EPI Requests
NUM_ESI Total ESI Requests
ORIGINNODE Origin Node
PID Process ID
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
TOT_ECTIME Total ECI Time
TOT_EPTIME Total EPI Time
TOT_ESTIME Total ESI Time
TOT_REQ Total Requests
TOT_TIME Total Time
Appendix B: Historical Reference Information for Attributes 245
HDC Parameters:CTG Summary attribute group (KWETGSUM)
Active by default? no
Record size in bytes 836
Recording frequency 1 record per CICS server per cycle
246 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Current Objects for Selected Class attribute group
Table 15. Current Objects for Selected Class attribute group (KWEHUDTL)
Term Reported by HDC Attribute Name
ALOC_CLAS Allocating Class Name
ALOC_METH Allocating Method Name
AVG_AGE Average Object Age
CLAS_NAME Class Name
GROW_RATE Growth Rate
GROW_TIME Growth Time Interval
LINE_NUM Allocating Source File Line
NODE_NAME Node Name
NUM_LV_OBJ Number of Live Objects
NUM_OBJ Number of Objects
OLDEST_AGE Oldest Object Age
ORIGINNODE Origin Node
PID Process ID
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SOURCE_NUM Allocation Source Number
TOT_HEAP Estimated Bytes Used
WORK_NM1 Allocating Workload Major Name
WORK_NM2 Allocating Workload Minor Name
WORK_TYPE Workload Type
Appendix B: Historical Reference Information for Attributes 247
HDC Parameters:Current Objects for Selected Class attribute group
(KWEHUDTL)
Active by default? no
Record size in bytes 1520
Recording frequency 1 record per object per cycle
248 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Datasources attribute group
Table 16. Datasources attribute group (KWEDATAS)
Term Reported by HDC Attribute Name
AVG_CWAIT Average Connection Wait Time
AVG_QRESP Average Query Processing Time
AVG_URESP Average Update Processing Time
CONN_RATE Connection Rate
INT_TIME Interval Time
MAX_CWAIT Max Connection Wait Time
NAME Datasource Name
NODE_NAME Node Name
NUM_CONN Number of Connections
NUM_QUERY Number of Queries
NUM_UPDATE Number of Updates
ORIGINNODE Origin Node
PID Process ID
PROD_NAME Database Product
PROD_VER Database Product Version
QRY_RATE Query Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
TOT_CWAIT Total Connection Wait Time
TOT_QRESP Total Query Processing Time
TOT_URESP Total Update Processing Time
TOT_WAIT Total Wait Time
UPD_RATE Update Rate
Appendix B: Historical Reference Information for Attributes 249
HDC Parameters:Datasources attribute group (KWEDATAS)
Active by default? no
Record size in bytes 1132
Recording frequency 1 record per interval per data source in each application server
250 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
DB Connection Pools attribute group
Table 17. DB Connection Pools attribute group (KWEDBCONP)
Term Reported by HDC Attribute Name
AVG_WAIT Average Number of Threads Waiting
AVG_WAITTM Average Wait Time
AVG_TIMHLD Average Use Time
DCP_IL Database Connection Pool Instrumentation Level
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
MAX_SIZE Maximum Pool Size
NAME Datasource Name
NODE_NAME Node Name
NUM_ALLOC Connections Allocated
NUM_CREATE Connections Created
NUM_DESTRY Connections Released
NUM_PSCD Prep Statement Cache Discards
NUM_RTN Number of Returns
NUM_TOW Threads That Timed Out
ORIGINNODE Origin Node
PCT_MAX Percent Maximum Use Time
PCT_USED Percent Used
POOL_SIZE Average Size of the Pool
RTE_ALLOC Connection Allocation Rate
RTE_CREATE Connection Creation Rate
RTE_DESTRY Connection Destroy Rate
RTE_PSCD Prep Statement Cache Discard Rate
RTE_RTN Return Rate
Appendix B: Historical Reference Information for Attributes 251
RTE_TOW Thread Timeout Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SUMMARY Summary of All DB Connections
HDC Parameters:DB Connection Pools attribute group (KWEDBCONP)
Active by default? no
Record size in bytes 1052
Recording frequency 1 record per interval per application server, plus 1 record per interval per datasource
Table 17. DB Connection Pools attribute group (KWEDBCONP)
Term Reported by HDC Attribute Name
252 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Dynamic Cache attribute group
Table 18. Dynamic Cache attribute group (KWECACHE)
Term Reported by HDC Attribute Name
CACHE_IL Cache Instrumentation Level
CACHE_SIZE Current In-memory Cache Entries
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
MAX_SIZE Maximum In-memory Cache Entries
NODE_NAME Node Name
ORIGINNODE Origin Node
PMI_ENABLE PMI Enable
RTE_TTOUT Total In-memory and Disk Timeout Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
TOTAL_TOUT Total In-memory and Disk Timeouts
HDC Parameters:Dynamic Cache attribute group (KWECACHE)
Active by default? yes
Record size in bytes 584
Recording frequency 1 record per cache per cycle
Appendix B: Historical Reference Information for Attributes 253
Dynamic Cache Templates attribute group
Table 19. Dynamic Cache Templates attribute group (KWECACHT)
Term Reported by HDC Attribute Name
CACHET_IL Cache Template Instrumentation Level
CACHET_NAM Cache Object Type
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
NODE_NAME Node Name
NUM_CREATE Current Cache Entries
NUM_CREQS Requests from Client
NUM_DISHIT Disk Hits
NUM_DISINV Explicit Invalidations from Disk
NUM_EXPINV Total Explicit Invalidations
NUM_JVMREQ Requests from Other Cache in Cluster
NUM_LOCINV Explicit Local Invalidations
NUM_LRUINV Least Recently Used Invalidations
NUM_MEMHIT Memory Hits
NUM_MEMINV Explicit Invalidations from Memory
NUM_MISSES Cache Misses
NUM_RCREAT Remote Cache Entry Received
NUM_REMHIT Remote Hits
NUM_REMINV Explicit Remote Invalidations
NUM_TOUT Timeout Invalidations
ORIGINNODE Origin Node
PCT_USED Percent Used
REF_NUM Row Number
RTE_CREQS Request from Client Rate
254 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
RTE_DISHIT Disk Hit Rate
RTE_DISINV Explicit Invalidation from Disk Rate
RTE_EXPINV Total Explicit Invalidation Rate
RTE_JVMREQ Request from Other Cache in Cluster Rate
RTE_LOCINV Explicit Local Invalidation Rate
RTE_LRUINV Least Recently Used Invalidation Rate
RTE_MEMHIT Memory Hit Rate
RTE_MEMINV Explicit Invalidation from Memory Rate
RTE_MISSES Cache Miss Rate
RTE_RCREAT Remote Cache Entry Receive Rate
RTE_REMHIT Remote Hit Rate
RTE_REMINV Explicit Remote Invalidation Rate
RTE_TOUT Timeout Invalidation Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SUMMARY Summary of Cache Templates
HDC Parameters:Dynamic Cache Templates attribute group (KWECACHT)
Active by default? no
Record size in bytes 956
Recording frequency 1 record per cache template per cycle
Table 19. Dynamic Cache Templates attribute group (KWECACHT)
Term Reported by HDC Attribute Name
Appendix B: Historical Reference Information for Attributes 255
EJB Containers attribute group
Table 20. EJB Containers attribute group (KWECONTNR)
Term Reported by HDC Attribute Name
AVG_CR_TIM Average Create Time
AVG_EB_ACT Average Active Entity Beans
AVG_EB_LIV Average Live Entity Beans
AVT_EB_ML Average Entity Bean Concurrent Invocations
AVG_RM_TIM Average Remove Time
AVG_SF_ACT Average Active Stateful Beans
AVG_SF_LIV Average Live Stateful Beans
AVG_SF_ML Average Stateful Invocations
AVG_SL_LIV Average Live Stateless Bean Objects
AVG_SL_ML Average Stateless Concurrent Invocations
AVG_TO_ACT Total Average Concurrent Active
AVG_TO_LIV Total Concurrent Live
AVG_TO_ML Total Active Methods
CONT_IL EJB Container Instrumentation Level
CONT_NAME Container Name
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
MTHD_CALLS Total Method Invocations
MTHD_RT Average Method Response Time
NODE_NAME Node Name
NUM_EB_ACT Entity Bean Activations
NUM_EB_CR Entity Bean Creates
NUM_EB_DS Entity Bean Destroys
NUM_EB_IN Entity Bean Instantiations
256 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
NUM_EB_LOD Entity Bean Loads
NUM_EB_PAS Entity Bean Passivations
NUM_EB_RM Entity Bean Removes
NUM_EB_STO Entity Bean Stores
NUM_SF_ACT Stateful Activations
NUM_SF_CR Stateful Creates
NUM_SF_DS Stateful Destroys
NUM_SF_IN Stateful Instantiations
NUM_SF_PAS Stateful Passivations
NUM_SF_RM Stateful Removes
NUM_SL_DS Stateless Destroys
NUM_SL_IN Stateless Instantiations
NUM_TO_ACT Total Activates
NUM_TO_CR Total Creates
NUM_TO_DS Total Destroys
NUM_TO_IN Total Instantiates
NUM_TO_PAS Total Passivates
NUM_TO_RM Total Removes
ORIGINNODE Origin Node
RTE_EB_ACT Entity Bean Activation Rate
RTE_EB_CR Entity Bean Create Rate
RTE_EB_DS Entity Bean Destroy Rate
RTE_EB_IN Entity Bean Instantiation Rate
RTE_EB_LOD Entity Bean Load Rate
RTE_EB_PAS Entity Bean Passivation Rate
Table 20. EJB Containers attribute group (KWECONTNR)
Term Reported by HDC Attribute Name
Appendix B: Historical Reference Information for Attributes 257
RTE_EB_RM Entity Bean Remove Rate
RTE_EB_STO Entity Bean Store Rate
RTE_MT_CAL Total Method Invocation Rate
RTE_SF_ACT Stateful Activation Rate
RTE_SF_CR Stateful Create Rate
RTE_SF_DS Stateful Destroy Rate
RTE_SF_IN Stateful Instantiation Rate
RTE_SF_PAS Stateful Passivation Rate
RTE_SF_RM Stateful Remove Rate
RTE_SL_DS Stateless Destroy Rate
RTE_SL_IN Stateless Instantiation Rate
RTE_TO_ACT Total Activate Rate
RTE_TO_CR Total Create Rate
RTE_TO_DS Total Destroy Rate
RTE_TO_IN Total Instantiate Rate
RTE_TO_PAS Total Passivate Rate
RTE_TO_RM Total Remove Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SUMMARY Summary of All Containers
Table 20. EJB Containers attribute group (KWECONTNR)
Term Reported by HDC Attribute Name
258 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
HDC Parameters:EJB Containers attribute group (KWECONTNR)
Active by default? no
Record size in bytes 1024
Recording frequency 1 record per interval per application server, plus 1 record per interval per EJB container
Appendix B: Historical Reference Information for Attributes 259
Enterprise Java Beans attribute group
Table 21. Enterprise Java Beans for attribute group (KWEEJB)
Term Reported by HDC Attribute Name
AVG_CR_TIM Average Create Time
AVG_DR_SZ Average Number of Objects Discarded
AVG_RM_TIM Average Remove Time
BEAN_IL Enterprise Bean Instrumentation Level
BEAN_NAME Bean Name
BEAN_TYPE Bean Type
CONT_NAME Container Name
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
MTHD_CALLS Total Method Invocations
MTHD_LOAD Average Number of Invocations Processed Concurrently
MTHD_RT Average Method Response Time
NODE_NAME Node Name
NUM_ACTIV Activations
NUM_BACTIV Average Number of Active Bean Instances
NUM_BLIVE Average Number of Live Bean Instances
NUM_CREATE Create Calls
NUM_DSTRY Times Bean Objects Were Destroyed
NUM_GET_FN Bean Object Pool Retrieval Hits
NUM_GETS Calls Retrieving an Object from the Bean Object Pool
NUM_DRAIN Times the Bean Object Pool Was Found Idle
NUM_INSTNT Times Bean Objects Were Created
NUM_LOAD Loads
260 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
NUM_PASSIV Passivations
NUM_PUT Calls Returning an Object to the Bean Object Pool
NUM_PUT_DS Times the Returned Object Was Discarded
NUM_REMOVE Remove Calls
NUM_STORE Stores
ORIGINNODE Origin Node
POOL_SIZE Average Number of Objects in the Bean Object Pool
RTE_ACTIV Bean Instance Activation Rate
RTE_CREATE Create Call Rate
RTE_DRAIN Bean Object Pool Drain Rate
RTE_DSTRY Bean Object Destroy Rate
RTE_GET_FN Bean Object Pool Retrieve Availability Rate
RTE_GETS Bean Object Pool Retrieval Rate
RTE_INSTNT Bean Objects Creation Rate
RTE_LOAD Bean Data Load Rate
RTE_MT_CAL Total Method Invocation Rate
RTE_PASSIV Passivate Rate
RTE_PUT Bean Object Pool Return Rate
RTE_PUT_DS Bean Object Pool Discard Rate
RTE_REMOVE Remove Call Rate
RTE_STORE Bean Store Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
Table 21. Enterprise Java Beans for attribute group (KWEEJB)
Term Reported by HDC Attribute Name
Appendix B: Historical Reference Information for Attributes 261
HDC Parameters:Enterprise Java Beans for attribute group (KWEEJB)
Active by default? no
Record size in bytes 1048
Recording frequency 1 record per interval for each EJB method
262 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Enterprise Java Bean Methods attribute group
Table 22. Enterprise Java Bean Methods attribute group (KWEEJBMTD)
Term Reported by HDC Attribute Name
BEAN_NAME Bean Name
BEANM_IL Enterprise Bean Method Instrumentation Level
CONT_NAME Container Name
FULL_NAME Full Method Name
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
MTHD_NAME Method Name
NODE_NAME Node Name
NUM_CALLS Times the Method Was Called
ORIGINNODE Origin Node
RT Average Response Time
RTE_CALLS Call Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
HDC Parameters:Enterprise Java Bean Methods attribute group
(KWEEJBMTD)
Active by default? no
Record size in bytes 1180
Recording frequency 1 record per interval for each EJB method
Appendix B: Historical Reference Information for Attributes 263
Garbage Collector Activity attribute group
Table 23. Garbage Collector Activity attribute group (KWEGC)
Term Reported by HDC Attribute Name
BYTE_FREE Total Kbytes Freed
GC_RATE Garbage Collection Rate
IN_USE Kbytes in Use
IN_USE_D Kbytes in Use Delta
INT_TIME Interval Time
NODE_NAME Node Name
NUM_FREE Objects Freed
NUM_MOVE Objects Moved
NUM_RUN Times Run
NUMB_FREE Kbytes Free
ORIGINNODE Origin Node
PID Process ID
REAL_TIME Real Time
REAL_TPCT Real Time Percent
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
264 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
HDC Parameters:Garbage Collector Activity attribute group (KWEGC)
Active by default? yes
Record size in bytes 740
Recording frequency 1 record per interval per application server
Appendix B: Historical Reference Information for Attributes 265
Garbage Collection Cycle Detail attribute group
Table 24. Garbage Collection Cycle Detail attribute group (KWEGCCYC)
Term Reported by HDC Attribute Name
AF_NO Allocation Failure Number
BYTE_FREE KBytes Free at Start of GC
BYTE_FREED Kbytes Freed
BYTE_MOVED Kbytes Moved
BYTE_USED Kbytes in Use
CM_REASON Compaction Reason
FINAL_REFS Final Refs
GC_NO Garbage Collection Number
GC_TIME GC Date and Time
HEAP_AVAIL Heap Space Free (KB)
HEAP_FREEP Percent of Heap Free
HEAP_TOTAL Heap Capacity (KB)
INT_TIME Interval Time
NODE_NAME Node Name
OBJS_MOVED Objects Moved
ORIGINNODE Origin Node
PHAN_REFS Phantom Refs
PID Process ID
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SOFT_REFS Soft Refs
TIME_COMP Time to Complete
TIME_CPAT Compact Time
TIME_MARK Mark Time
266 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
TIME_SWEEP Sweep Time
WEAK_REFS Weak Refs
HDC Parameters:Garbage Collection Cycle Detail attribute group
(KWEGCCYC)
Active by default? no
Record size in bytes 656
Recording frequency 1 record per garbage-collection cycle per interval
Table 24. Garbage Collection Cycle Detail attribute group (KWEGCCYC)
Term Reported by HDC Attribute Name
Appendix B: Historical Reference Information for Attributes 267
Heap Usage attribute group
Table 25. Heap Usage attribute group (KWEHUSUM)
Term Reported by HDC Attribute Name
CLAS_NAME Class Name
COL_LEVEL Collection Level
GROW_RATE Growth Rate
GROW_TIME Growth Time Interval
INT_TIME Interval Time
NODE_NAME Node Name
NUM_ALLOC Allocation Requests
NUM_FREE Objects Deleted
NUM_LV_OBJ Number of Live Objects
NUM_OBJ Number of Objects
ORIGINNODE Origin Node
PID Process ID
RTE_FREE Object Deletion Rate
RTE_HEAP Allocation Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
TOT_HEAP Estimated Bytes Used
HDC Parameters:Heap Usage attribute group (KWEHUSUM)
Active by default? no
Record size in bytes 880
Recording frequency 1 record per heap per class per cycle
268 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
HTTP Sessions attribute group
Table 26. HTTP Sessions attribute group (KWEHTTPS)
Term Reported by HDC Attribute Name
CDATE_TIME Create Date and Time
INT_TIME Interval Time
IP_ADDR Creating IP Address
LDATE_TIME Last Accessed Time
MAX_INACT Maximum Inactive Interval
NODE_NAME Node Name
NUM_OBJ Associated Attributes
NUM_OBJ_NS HTTP Session Uncountable Objects
OBJ_TOT_SZ HTTP Session Object Size
ORIGINNODE Origin Node
PID Process ID
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SESS_ID Session ID
USER Creating User
WEB_APP Web Application Name
WORK_NM1 Class Name
WORK_NM2 Method Name
WORK_TYPE Workload Type
Appendix B: Historical Reference Information for Attributes 269
HDC Parameters:HTTP Sessions attribute group (KWEHTTPS)
Active by default? no
Record size in bytes 1276
Recording frequency 1 record per interval for each active HTTP session in each application server
270 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
In-flight Workloads attribute group
Table 27. In-flight Workloads attribute group (KWEIFWSM)
Term Reported by HDC Attribute Name
I2 Server Name
I3 Node Name
I4 Sample Date and Time
I5 Interval Time
I6 Process ID
I7 Workload Type
I8 Workload Major Name
I9 Workload Minor Name
I10 Thread Name
I11 IP Address
I12 User ID
I13 Workload ID
I14 Date/Time Workload Started
I15 Workload Run Time
I16 CPU Time Used
I17 CPU Time Used Current Interval
I18 CPU Percent
I19 Method Arguments
I20 Current Stack Level
I21 Current Class and Method
I22 Current State
I23 Time in Current State
I24 Number Servlet Delays
I25 Servlet Delay Time
Appendix B: Historical Reference Information for Attributes 271
I26 Servlet Delay Percent
I27 Number EJB Method Delays
I28 EJB Method Delay Time
I29 EJB Method Delay Percent
I30 Number EJB Home Delays
I31 EJB Home Delay Time
I32 EJB Home Delay Percent
I33 Number EJB Remote Delays
I34 EJB Remote Delay Time
I35 EJB Remote Delay Percent
I36 Number SQL Connection Delays
I37 SQL Connection Delay Time
I38 SQL Connection Delay Percent
I39 Number SQL Query Delays
I40 SQL Query Delay Time
I41 SQL Query Delay Percent
I42 Number SQL Update Delays
I43 SQL Update Delay Time
I44 SQL Update Delay Percent
I45 Number JNDI Delays
I46 JNDI Delay Time
I47 JNDI Delay Percent
I48 Number JMS Delays
I49 JMS Delay Time
I50 JMS Delay Percent
Table 27. In-flight Workloads attribute group (KWEIFWSM)
Term Reported by HDC Attribute Name
272 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
I51 Number JTA Delays
I52 JTA Delay Time
I53 JTA Delay Percent
I54 Number Network Socket Delays
I55 Network Socket Delay Time
I56 Network Socket Delay Percent
I57 Number User-defined Delays
I58 User-defined Delay Time
I59 User-defined Delay Percent
I60 Number Miscellaneous Delays
I61 Miscellaneous Delay Time
I62 Miscellaneous Delay Percent
I63 Number CTG Delays
I64 CTG Delay Time
I65 CTG Delay Percent
I66 Number JCA Delays
I67 JCA Delay Time
I68 JCA Delay Percent
I69 Number Heap Alloc Delays
I70 Heap Alloc Delay Time
I71 Heap Alloc Delay Percent
I72 Lock Wait Time
I79 Number EJB Local Home Delays
I80 EJB Local Home Delay Time
I81 EJB Local Home Delay Percent
Table 27. In-flight Workloads attribute group (KWEIFWSM)
Term Reported by HDC Attribute Name
Appendix B: Historical Reference Information for Attributes 273
I82 Number EJB Local Object Delays
I83 EJB Local Object Delay Time
I84 EJB Local Object Delay Percent
ORIGINNODE Origin Node
HDC Parameters:In-flight Workloads attribute group (KWEIFWSM)
Active by default? no
Record size in bytes 2008
Recording frequency 1 record per in-flight workload per cycle
Table 27. In-flight Workloads attribute group (KWEIFWSM)
Term Reported by HDC Attribute Name
274 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
In-flight Workload Detail attribute group
Table 28. In-flight Workload Detail attribute group (KWEIFWDT)
Term Reported by HDC Attribute Name
CALL_ARGS Called Arguments
CPU_TIME CPU Time Used
CPU_TIMEI CPU Time Used Current Interval
CPU_TIMEP CPU Percent
CUR_METHD Class and Method
HEAP_ALLOC Heap Allocations
INMETH_TIM Time in Method
INT_TIME Interval Time
LAST_METHD Last Completed Method
NODE_NAME Node Name
ORIGINNODE Origin Node
PID Process ID
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
STACK_LVL Stack Level
THRED_NAM Thread Name
TIME_START Date/Time Method Entered
WORK_ID Workload ID
WORK_NM1 Workload Major Name
WORK_NM2 Workload Minor Name
WORK_TYPE Workload Type
Appendix B: Historical Reference Information for Attributes 275
HDC Parameters:In-flight Workload Detail attribute group (KWEIFWDT)
Active by default? no
Record size in bytes 1536
Recording frequency 1 record per instrumented stack per in-flight workload per cycle
276 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
J2C Connection Pools attribute group
Table 29. J2C Connection Pools attribute group (KWEJ2C)
Term Reported by HDC Attribute Name
AVG_USE Average Use Time
AVG_WAIT Average Wait Time
AVG_WAITER Concurrent Thread Waiters
CFACT_NAME Connection Factory Name
FREE_PSIZE Free Managed Connection Pool Size
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
J2C_IL J2C Connection Pools Instrumentation Level
MAX_SIZE Maximum Pool Size
NODE_NAME Node Name
NUM_ALLOC Managed Connections Allocated
NUM_CONN Current Connections
NUM_CREATE Managed Connections Created
NUM_DESTRY Managed Connections Destroyed
NUM_FREED Managed Connections Returned
NUM_MGCON Current Managed Connections
NUM_TOUT Managed Connection Pool Timeouts
ORIGINNODE Origin Node
PERC_USED Pool Percent Used
PERC_MAXED Pool Percent Maxed
POOL_SIZE Managed Connection Pool Size
RTE_ALLOC Managed Connection Allocation Rate
RTE_CREATE Managed Connection Creation Rate
RTE_DESTRY Managed Connection Destroy Rate
Appendix B: Historical Reference Information for Attributes 277
RTE_FREED Managed Connection Return Rate
RTE_TOUT Managed Connection Pool Timeout Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SUMMARY Summary of J2C Connections
HDC Parameters:J2C Connection Pools attribute group (KWEJ2C)
Active by default? no
Record size in bytes 912
Recording frequency 1 record per J2EE connection pool per cycle
Table 29. J2C Connection Pools attribute group (KWEJ2C)
Term Reported by HDC Attribute Name
278 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
JMS Summary attribute group
Table 30. JMS Summary attribute group (KWEMQSAC)
Term Reported by HDC Attribute Name
AVG_BTIME Average Browse Time
AVG_GTIME Average Get Time
AVG_PTIME Average Put Time
BROW_RATE Browse Rate
FULL_NAME Full Name
GET_RATE Get Rate
INT_TIME Interval Time
NODE_NAME Node Name
NUM_BROWSE Number of Browse Gets
NUM_GET Number of Gets
NUM_PUT Number of Puts
ORIGINNODE Origin Node
PID Process ID
PUT_RATE Put Rate
QUEUE_NAME Name
QMGR_NAME Manager Name
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
TOT_BTIME Total Browse Time
TOT_GTIME Total Get Time
TOT_PTIME Total Put Time
TOT_TIME Total Time
TYPE Type
Appendix B: Historical Reference Information for Attributes 279
HDC Parameters:JMS Summary attribute group (KWEMQSAC)
Active by default? no
Record size in bytes 816
Recording frequency 1 record per interval per MQSeries queue in each application server
280 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Lock Analysis by Method Detail attribute group
Table 31. Lock Analysis by Method Detail attribute group (KWEMCDCM)
Term Reported by HDC Attribute Name
AVG_LOC Average Contention Time
CLAS_NAME Class Acquiring Locks
INT_TIME Interval Time
LOC_CLS Lock Object Class
LOC_TIME Total Contention Time
MAX_LOC Maximum Contention Time
MTD_NAME Method Acquiring Locks
NODE_NAME Node Name
NUM_LOC Number of Lock Contentions
ORIGINNODE Origin Node
PID Process ID
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
WLD_NM21 Second Contending Workload Major Name
WLD_NM22 Second Contending Workload Minor Name
WLD_TYPE2 Second Contending Workload Type
WORK_NM1 First Contending Workload Major Name
WORK_NM2 First Contending Workload Minor Name
WORK_TYPE First Contending Workload Type
Appendix B: Historical Reference Information for Attributes 281
HDC Parameters:Lock Analysis by Method Detail attribute group
(KWEMCDCM)
Active by default? no
Record size in bytes 1488
Recording frequency 1 record per method, lock, first workload, and second workload per cycle
282 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Lock Analysis by Method Summary attribute group
Table 32. Lock Analysis by Method Summary attribute group (KWEMCCMS)
Term Reported by HDC Attribute Name
AVG_LOC Average Time to Acquire Lock
CLAS_NAME Class Acquiring Locks
INT_TIME Interval Time
LOC_TIME Total Time to Acquire Lock
MAX_LOC Maximum Time to Acquire Lock
MTD_NAME Method Acquiring Locks
NODE_NAME Node Name
NUM_LOC Number of Locks Acquired
ORIGINNODE Origin Node
PID Process ID
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
HDC Parameters:Lock Analysis by Method Summary attribute group
(KWEMCCMS)
Active by default? no
Record size in bytes 964
Recording frequency 1 record per method and lock per cycle
Appendix B: Historical Reference Information for Attributes 283
Lock Analysis by Workload attribute group
Table 33. Lock Analysis by Workload attribute group (KWEMCMW)
Term Reported by HDC Attribute Name
AVG_LOC Average Time to Acquire Lock
CLAS_NAME Class Acquiring Locks
INT_TIME Interval Time
LOC_CLS Lock Object Class
LOC_TIME Total Time to Acquire Lock
MAX_LOC Maximum Time to Acquire Lock
MTD_NAME Method Acquiring Locks
NODE_NAME Node Name
NUM_LOC Number of Locks Acquired
ORIGINNODE Origin Node
PID Process ID
REF_NUM Row Number
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
WORK_NM1 Workload Major Name
WORK_NM2 Workload Minor Name
WORK_TYPE Workload Type
HDC Parameters:Lock Analysis by Workload attribute group (KWEMCMW)
Active by default? no
Record size in bytes 1228
Recording frequency 1 record per method, workload, and lock per cycle
284 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Lock Analysis by Workload Detail attribute group
Table 34. Lock Analysis by Workload Detail attribute group (KWEMCDWL)
Term Reported by HDC Attribute Name
AVG_LOC Average Contention Time
CLAS_NAME1 First Contending Class Name
CLAS_NAME2 Second Contending Class Name
INT_TIME Interval Time
LOC_CLS Lock Object Class
LOC_TIME Total Contention Time
MAX_LOC Maximum Contention Time
MTD_NAME1 First Contending Method Name
MTD_NAME2 Second Contending Method Name
NODE_NAME Node Name
NUM_LOC Number of Lock Contentions
ORIGINNODE Origin Node
PID Process ID
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
WORK_NM1 Workload Major Name
WORK_NM2 Workload Minor Name
WORK_TYPE Workload Type
Appendix B: Historical Reference Information for Attributes 285
HDC Parameters:Lock Analysis by Workload Detail attribute group
(KWEMCDWL)
Active by default? no
Record size in bytes 1488
Recording frequency 1 record per workload, lock, first workload, and second workload per cycle
286 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Lock Owner for Selected In-flight Workload attribute group
Table 35. Lock Owner for Selected In-flight Workload attribute group (KWEIFML)
Term Reported by HDC Attribute Name
I2 Server Name
I3 Node Name
I4 Sample Date and Time
I5 Interval Time
I6 Process ID
I7 Waiting Workload Type
I8 Waiting Workload Major Name
I9 Waiting Workload Minor Name
I10 Waiting Class
I11 Waiting Method
I12 Lock Object Class
I13 Owner Workload Type
I14 Owner Workload Major Name
I15 Owner Workload Minor Name
I16 Owner Class
I17 Owner Method
I18 Time Waiting for Lock
I19 Waiting Workload ID
I20 Owner Workload ID
I21 Waiting Thread Name
I22 Owner Thread Name
ORIGINNODE Origin Node
Appendix B: Historical Reference Information for Attributes 287
HDC Parameters:Lock Owner for Selected In-flight Workload attribute group
(KWEIFML)
Active by default? no
Record size in bytes 2248
Recording frequency 1 record per lock, waiting workload, and owner workload per cycle
288 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Longest Running Workloads V2 attribute group
Table 36. Longest Running Workloads V2 attribute group (KWEWLEX2)
Term Reported by HDC Attribute Name
C1 Node Name
C2 Workload Ended Date and Time
C3 Interval Time
C9 User ID
C10 IP Address
C11 Response Time
C12 Number Servlet Delays
C13 Servlet Delay Time
C14 Servlet Delay Percent
C15 Number EJB Method Delays
C16 EJB Method Delay Time
C17 EJB Method Delay Percent
C18 Number EJB Home Delays
C19 EJB Home Delay Time
C20 EJB Home Delay Percent
C21 Number EJB Remote Delays
C22 EJB Remote Delay Time
C23 EJB Remote Delay Percent
C24 Number SQL Connection Delays
C25 SQL Connection Delay Time
C26 SQL Connection Delay Percent
C27 Number SQL Query Delays
C28 SQL Query Delay Time
C29 SQL Query Delay Percent
Appendix B: Historical Reference Information for Attributes 289
C30 Number SQL Update Delays
C31 SQL Update Delay Time
C32 SQL Update Delay Percent
C33 Number JNDI Delays
C34 JNDI Delay Time
C35 JNDI Delay Percent
C36 Number JMS Delays
C37 JMS Delay Time
C38 JMS Delay Percent
C39 Number JTA Delays
C40 JTA Delay Time
C41 JTA Delay Percent
C45 Number User-defined Delays
C46 User-defined Delay Time
C47 User-defined Delay Percent
C48 Number Miscellaneous Delays
C49 Miscellaneous Delay Time
C50 Miscellaneous Delay Percent
C52 Workload Full Name
C53 Total CPU Time
C54 Method Arguments
C55 Number CTG Delays
C56 CTG Delay Time
C57 CTG Delay Percent
C58 Number JCA Delays
Table 36. Longest Running Workloads V2 attribute group (KWEWLEX2)
Term Reported by HDC Attribute Name
290 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
C59 JCA Delay Time
C60 JCA Delay Percent
C61 Number Heap Alloc Delays
C62 Heap Alloc Delay Time
C63 Heap Alloc Delay Percent
C64 Total Number Heap Alloc
C66 Number EJB Local Home Delays
C67 EJB Local Home Delay Time
C68 EJB Local Home Delay Percent
C69 Number EJB Local Object Delays
C70 EJB Local Object Delay Time
C71 EJB Local Object Delay Percent
ORIGINNODE Origin Node
PID Process ID
SERVER_NAM Server Name
WORK_NM1 Class/Major Name
WORK_NM2 Method/Minor Name
WORK_TYPE Workload Type
HDC Parameters:Longest Running Workloads V2 attribute group
(KWEWLEX2)
Active by default? no
Record size in bytes 1472
Recording frequency 1 record per interval for each exceptional workload in each application server
Table 36. Longest Running Workloads V2 attribute group (KWEWLEX2)
Term Reported by HDC Attribute Name
Appendix B: Historical Reference Information for Attributes 291
Methods Instantiating Selected Class attribute group
Table 37. Methods Instantiating Selected Class attribute group (KWEWHUBM)
Term Reported by HDC Attribute Name
ALOC_CLAS Allocating Class Name
ALOC_METH Allocating Method Name
CLAS_NAME Class Name
INT_TIME Interval Time
PID Process ID
LINE_NUM Allocating Source File Line
NODE_NAME Node Name
NUM_ALLOC Allocation Requests
ORIGINNODE Origin Node
RTE_HEAP Allocation Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
WORK_NM1 Workload Major Name
WORK_NM2 Workload Minor Name
WORK_TYPE Workload Type
HDC Parameters:Methods Instantiating Selected Class attribute group
(KWEWHUBM)
Active by default? no
Record size in bytes 1500
Recording frequency 1 record per workload per cycle
292 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
WebSphere Distributed Product Events attribute group
Table 38. WebSphere Distributed Product Events attribute group (KWEPREV)
Term Reported by HDC Attribute Name
MSG_DESC Message Description
MSG_ID Message ID
NODE_NAME Node Name
ORIGINNODE Origin Node
SDATE_TIME Event Date and Time
SEVERITY Severity
HDC Parameters:WebSphere Distributed Product Events attribute group
(KWEPREV)
Active by default? no
Record size in bytes 612
Recording frequency 1 record for each product event. These records are written when problems occur. It is impossible to say how often this may occur
Appendix B: Historical Reference Information for Attributes 293
References to Objects for Selected Allocation Source attribute group
Table 39. References to Objects for Selected Allocation Source attribute group (KWEOBJRF)
Term Reported by HDC Attribute Name
NODE_NAME Node Name
LINE_NUM Referenced Object Allocating Source Line
NUM_OBJ Number of Objects
OALOC_CLAS Referenced Object Allocating Class Name
OALOC_METH Referenced Object Allocating Method Name
OCLAS_NAME Referenced Object Class Name
OWORK_NM1 Referenced Object Allocating Workload Class Name
OWORK_NM2 Referenced Object Allocating Workload Method Name
OWORK_TYPE Referenced Object Allocating Workload Type
ORIGINNODE Origin Node
PID Process ID
RALOC_CLAS Referencing Object Allocating Class Name
RALOC_METH Referencing Object Allocating Method Name
RCLAS_NAME Referencing Object Class Name
REF_NUM Allocation Source
REF_TYPE Reference Type
RLINE_NUM Referencing Object Allocating Source Line
RWORK_NM1 Referencing Object Allocating Workload Class Name
RWORK_NM2 Referencing Object Allocating Workload Method Name
RWORK_TYPE Referencing Object Workload Type
SDATE_TIME Sample Date and Time
294 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
SERVER_NAM Server Name
HDC Parameters:References to Objects for Selected Allocation Source
attribute group (KWEOBJRF)
Active by default? no
Record size in bytes 2020
Recording frequency 1 record per object per cycle
Table 39. References to Objects for Selected Allocation Source attribute group (KWEOBJRF)
Term Reported by HDC Attribute Name
Appendix B: Historical Reference Information for Attributes 295
Selected Workload Delays attribute group
Table 40. Selected Workload Delays attribute group (KWEWKLDD)
Term Reported by HDC Attribute Name
AVG_ALLOC Average Number of Heap Alloc
AVG_TIME Average Time
CPU_TIME CPU Time
DELAY_NAME Delay Full Name
DELAY_NM1 Delay Major Name
DELAY_NM2 Delay Minor Name
DELAY_TYPE Delay Type
INT_TIME Interval Time
MAX_TIME Max Time
NODE_NAME Node Name
NUM_ALLOC Total Number of Heap Alloc
NUM_OCCUR Number of Occurrences
ORIGINNODE Origin Node
PCT_TIME Delay Percent
PID Process ID
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
TOTAL_TIME Total Time
WORK_NM1 Class/Major Name
WORK_NM2 Method/Minor Name
WORK_TYPE Workload Type
296 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
HDC Parameters:Selected Workload Delays attribute group (KWEWKLDD)
Active by default? no
Record size in bytes 1272
Recording frequency 1 record per interval for each workload degradation in each application server
Appendix B: Historical Reference Information for Attributes 297
Servlet Sessions attribute group
Table 41. Servlet Sessions attribute group (KWESERVS)
Term Reported by HDC Attribute Name
AVG_ACTSES Average Concurrently Active Sessions
AVG_LIVSES Average Concurrently Live Sessions
AVG_SESS Average Serializable Session Object Size
AVG_SLIFET Average Session Lifetime
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
LACT_TIME Time since Last Activated
MAX_SESS Maximum Serializable Session Object Size
MIN_SESS Minimum Serializable Session Object Size
NODE_NAME Node Name
NUM_AFFBRK Affinity Breaks Requests
NUM_CDISC Cache Discards
NUM_NORM No Room for New Session Requests
NUM_NOSESR Nonexistent Session Requests
NUM_SCREAT Sessions Created
NUM_SINVAL Sessions Invalidated
ORIGINNODE Origin Node
READ_SIZE External Read Size
READ_TIME External Read Time
RTE_AFFBRK Affinity Breaks Request Rate
RTE_CDISC Cache Discard Rate
RTE_NORM No Room for New Session Request Rate
RTE_NOSESR Nonexistent Session Request Rate
RTE_SCREAT Session Creation Rate
298 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
RTE_SINVAL Session Invalidation Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SERVSES_IL Servlet Sessions Instrumentation Level
SUMMARY Summary of Servlet Sessions
TOT_SESS Total Serializable Session Object Size
WAPPL_NAME Web Application Name
WRITE_SIZE External Write Size
WRITE_TIME External Write Time
HDC Parameters:Servlet Sessions attribute group (KWESERVS)
Active by default? no
Record size in bytes 936
Recording frequency 1 record per servlet session
Table 41. Servlet Sessions attribute group (KWESERVS)
Term Reported by HDC Attribute Name
Appendix B: Historical Reference Information for Attributes 299
Servlets JSPs attribute group
Table 42. Servlets JSPs attribute group (KWESERVLT)
Term Reported by HDC Attribute Name
APPL_NAME Web Application Name
AVG_CREQ Average Number of Concurrent Requests
AVG_RT Average Servlet Response Time
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
JSPP_NAME JSP Path Name
LOAD_TIME Date and Time the Servlet Was Loaded
NODE_NAME Node Name
NUM_ERRORS Errors
NUM_REQ Total Requests
ORIGINNODE Origin Node
RTE_ERRORS Servlet Error Rate
RTE_REQ Servlet Request Rate
SDATE_TIME Sample Date and Time
SERVE_IL Servlet/JSP Instrumentation Level
SERVER_NAM Server Name
SVLT_NAME Servlet/JSP Name
SVLT_TYPE Type
VHOST_NAME Virtual Host Name
HDC Parameters:Servlets JSPs attribute group (KWESERVLT)
Active by default? no
Record size in bytes 1212
Recording frequency 1 record per interval per servlet
300 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Suspected Memory Leaks attribute group
Table 43. Suspected Memory Leaks attribute group (KWEHUPML)
Term Reported by HDC Attribute Name
ALOC_CLAS Allocating Class Name
ALOC_METH Allocating Method Name
CLAS_NAME Class Name
GROW_PCT Growth Percent
GROW_RATE Growth Rate
GROW_TIME Growth Time Interval
LINE_NUM Allocating Source File Line
NODE_NAME Node Name
NUM_LV_OBJ Number of Live Objects
ORIGINNODE Origin Node
PID Process ID
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SOURCE_NUM Allocation Source
TOT_HEAP Estimated Bytes Used
WORK_NM1 Allocating Workload Major Name
WORK_NM2 Allocating Workload Minor Name
WORK_TYPE Allocating Workload Type
HDC Parameters:Suspected Memory Leaks attribute group (KWEHUPML)
Active by default? no
Record size in bytes 1384
Recording frequency 1 recrd per suspected memory leak per cycle
Appendix B: Historical Reference Information for Attributes 301
Thread Pools attribute group
Table 44. Thread Pools attribute group (KWETHRDP)
Term Reported by HDC Attribute Name
AVG_INACT Average Free Threads
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
MAX_SIZE Configured Maximum Number of Threads
NODE_NAME Node Name
NUM_ACTTHR Average Active Threads
NUM_CREATE Threads Created
NUM_DESTRY Threads Destroyed
ORIGINNODE Origin Node
PCT_TIMMAX All Threads in Use Percent
POOL_SIZE Average Threads
RTE_CREATE Thread Creation Rate
RTE_DESTRY Thread Destruction Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SUMMARY Summary of Thread Pools
THRDP_IL Thread Pools Instrumentation Level
THRDP_NAME Thread Pool Name
HDC Parameters:Thread Pools attribute group (KWETHRDP)
Active by default? no
Record size in bytes 864
Recording frequency 1 record per thread pool
302 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Web Applications attribute group
Table 45. Web Applications attribute group (KWEAPP)
Term Reported by HDC Attribute Name
APPL_NAME Web Application Name
AVG_CREQ Average Number of Concurrent Requests
AVG_RT Average Servlet Response Time
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
NODE_NAME Node Name
NUM_ERRORS Errors
NUM_RELOAD Reloaded Servlets
NUM_REQ Total Requests
NUM_SVRLT Loaded Servlets
ORIGINNODE Origin Node
RTE_ERRORS Servlet Exception Rate
RTE_REQ Servlet Request Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SUMMARY Summary of All Applications
VHOST_NAME Virtual Host Name
WEB_IL Web Application Instrumentation Level
WEBSUB_IL Web Application Subinstrumentation Level
Appendix B: Historical Reference Information for Attributes 303
HDC Parameters:Web Applications attribute group (KWEAPP)
Active by default? no
Record size in bytes 852
Recording frequency 1 record per interval per Web application
304 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Workload Class Instantiations attribute group
Table 46. Workload Class Instantiations attribute group (KWEWHUSE)
Term Reported by HDC Attribute Name
CLAS_NAME Class Name
INT_TIME Interval Time
NODE_NAME Node Name
NUM_ALLOC Allocation Requests
ORIGINNODE Origin Node
PID Process ID
RTE_HEAP Allocation Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
WORK_FULL Workload Full Name
WORK_NM1 Workload Major Name
WORK_NM2 Workload Minor Name
WORK_TYPE Workload Type
HDC Parameters:Workload Class Instantiations attribute group
(KWEWHUSE)
Active by default? no
Record size in bytes 1240
Recording frequency 1 record per workload class
Appendix B: Historical Reference Information for Attributes 305
Workload Management WLM Client attribute group
Table 47. Workload Management WLM Client attribute group (KWEWLMCL)
Term Reported by HDC Attribute Name
C_RSPTIME Client Response Time
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
NODE_NAME Node Name
NUM_CCUPDT Client Cluster Updates
NUM_OUTREQ Outgoing Requests
ORIGINNODE Origin Node
RTE_CCUPDT Client Cluster Update Rate
RTE_OUTREQ Outgoing Request Rate
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
WLMC_IL WLM Instrumentation Level
HDC Parameters:Workload Management WLM Client attribute group
(KWEWLMCL)
Active by default? no
Record size in bytes 588
Recording frequency 1 record per WLM client
306 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Workload Management WLM Server attribute group
Table 48. Workload Management WLM Server attribute group (KWEWLMSR)
Term Reported by HDC Attribute Name
ILTYPE Set Instrumentation Level Type
INT_TIME Interval Time
NODE_NAME Node Name
NUM_CREQS Concurrent Requests
NUM_INAREQ Incoming Non-affinity Requests
NUM_INREQS Incoming Requests
NUM_ISAREQ Incoming Strong Affinity Requests
NUM_NWLMR Incoming Non-WLM Object Requests
NUM_SCUPDT Server Cluster Updates
NUM_WLMCS WLM Clients Serviced
ORIGINNODE Origin Node
RTE_INAREQ Incoming Non-affinity Request Rate
RTE_INREQS Incoming Request Rate
RTE_ISAREQ Incoming Strong Affinity Request Rate
RTE_NWLMR Incoming Non-WLM Object Request Rate
RTE_SCUPDT Server Cluster Update Rate
RTE_WLMCS WLM Clients Serviced Rate
S_RSPTIME Server Response Time
SDATE_TIME Sample Date and Time
SERVER_NAM Server Name
SRV_WEIGHT WLM Server Weight
WLMS_IL WLM Instrumentation Level
Appendix B: Historical Reference Information for Attributes 307
HDC Parameters:Workload Management WLM Server attribute group
(KWEWLMSR)
Active by default? no
Record size in bytes 628
Recording frequency 1 record per WLM server
308 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 309
OMEGAMON XE forWebSphere Application Server
Messages
IntroductionThis appendix documents the KWE-prefixed messages that are produced by the OMEGAMON XE agent for WebSphere Application Server. It also documents the KWEWA-prefixed messages issued by the OMEGAMON XE agent’s workload analysis component. The KWEWA messages begin on page 329.
KWE messagesThe following messages cover a numbering range of KWE0001I–KWE0125E and are listed alphanumerically.
KWE0001I OMEGAMON XE for WebSphere Application Server startup completeExplanation: The OMEGAMON XE for WebSphere Application Server monitoring agent has successfully completed initialization.
KWE0002E cccc exception caught in module_name function_name.Explanation: A program exception has occurred in the OMEGAMON XE for WebSphere Application Server monitoring agent. The variable in the message indicate the type of exception, the module in which the exception occurred, and the function involved.User Response: Collect the agent log, and contact Candle Customer Service and Satisfaction.
KWE0003E Environmental error error_type caught in function_name RC = return_codeExplanation: An environmental error has occurred in the OMEGAMON XE for WebSphere Application Server monitoring agent. The
C
310 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
variables in the message indicate the type of error, the name of the function where the error was detected, and the return code.User Response: Collect the agent log and contact Candle Customer Service and Satisfaction.
KWE0004E Exception cccc caught. Explanation: This message is produced after an exception condition is caught in the Windows environment. This variable in the message indicates the type of exception that was caught.User Response: Collect the agent log and contact Candle Customer Service and Satisfaction.
KWE0005E Exception address xxxx. Explanation: This message is produced after an exception condition has occurred in the Windows environment. The xxxx variable indicates the address where the exception took place.User Response: Collect the agent log and contact Candle Customer Service and Satisfaction.
KWE0006E Windows exception address xxxx. Explanation: This message is produced after an exception condition has occurred in the Windows environment. The xxxx variable indicates the address where the exception took place.User Response: Collect the agent log and contact Candle Customer Service and Satisfaction.
KWE0007I Application server servername discovered.Explanation: The OMEGAMON XE for WebSphere Application Server monitoring agent has discovered a defined application server in the WebSphere Application Server configuration. No data collection for an application server occurs until the agent writes out this message. Also, if the status is anything other than Active, the agent does not start collecting data for the application server until the KWE0017I message is written, indicating that the application server is now Active.
KWE0008I Background EPM monitor started for application server servername. Explanation: The OMEGAMON XE for WebSphere Application Server monitoring agent has started Enterprise Performing Monitoring (EPM) for the application server identified by the servername variable. OMEGAMON XE for WebSphere Application Server will now collect EPM performance information on this application server.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 311
KWE0009I Background EPM monitor stopping for application server servername. Explanation: OMEGAMON XE for WebSphere Application Server monitoring agent has stopped Enterprise Performing Monitoring (EPM) for the application server indicated by the servername variable. The monitoring agent will no longer collect EPM performance information about this application server.
KWE0010I Background collector session monitor started for application server servername. Explanation: The OMEGAMON XE for WebSphere Application Server monitoring agent has started the collector session for the application server indicated by servername. The monitoring agent will now collect performance information on this application server.
KWE0011I Background collector session monitor stopping for application server servername. Explanation: The OMEGAMON XE for WebSphere Application Server monitoring agent has stopped the collector session for the application server indicated by servername. One of the following conditions has occurred.� The collector session has ended normally.
or� There was a problem with the collector session for the application server,
in which case there should be a prior message indicating the cause of the problem.
The monitoring agent will no longer collect performance information on the application server.
KWE0012I Collector session session started for application server servername. Explanation: The OMEGAMON XE monitoring agent for has made contact with the collector session running on the application server indicated by the servername variable.
KWE0015E Error error received on socket interface for application server servername.Explanation: An error occurred on the interface to the profiler or workload analysis component running on the application server indicated by servername. error is a description of the problem.User Response: Attempt to determine why the error condition occurred. This error can occur if the application server was stopped.
312 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
KWE0016E Socket interface for application server servername shut down.Explanation: The connection between the OMEGAMON XE for WebSphere Application Server monitoring agent and the profiler running on the application server indicated by the servername variable was ended. An error is the probable cause.User Response: Look for the KWE0015E message, which should have preceded this one. Follow the user response instructions for the KWE0015E message.
KWE0017I Application server servername is now active.Explanation: OMEGAMON XE for WebSphere Application Server has detected the fact that the application server identified by the servername variable has become active.
KWE0018I Application server servername is no longer active.Explanation: The OMEGAMON XE for WebSphere Application Server monitoring agent has detected that the application server identified by the servername variable is no longer active.
KWE0019E Unable to load Java Virtual Machine shared library.Explanation: The OMEGAMON XE for WebSphere Application Server monitoring agent was unable to load the Java Virtual Machine shared library. The library name is jvm.dll on Windows, libjvm.a on AIX, libjvm.so on Solaris and Linux, and libjvm.sl on HP-UX.User Response: Ensure that the WASAppServerRoot parameter in the kwe.xml file correctly identifies the root directory where the WebSphere Application Server is installed.
KWE0020E Unable to locate JNI_CreateJavaVM within Java Virtual Machine shared library.Explanation: The OMEGAMON XE for WebSphere Application Server monitoring agent was unable to locate the JNI_CreateJavaVM entry point in the Java Virtual Machine shared library. The library name is jvm.dll on Windows, libjvm.a on AIX, libjvm.so on Solaris and Linux, and libjvm.sl on HP-UX.User Response: Contact Candle Customer Service and Satisfaction.
KWE0021E Unable to create Java Virtual Machine. RC = return_code.Explanation: The OMEGAMON XE for WebSphere Application Server monitoring agent was unable to create the Java Virtual Machine. The return_code variable is the code received from the JNI_CreateJavaVM function in the JVM shared library.User Response: Contact Candle Customer Service and Satisfaction.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 313
KWE0022E Unable to locate KWEEPMClient class.Explanation: The OMEGAMON XE for WebSphere Application Server monitoring agent was unable to locate the KWEEPMClient Java class.User Response: Ensure that the kwepmiclient.jar file (for a WebSphere Application Server 4.0.x environment) is available in the appropriate directory.� For UNIX, the file should be in the HOME/classes directory.� For Windows, the file should be in the \candle\cma directory
KWE0025E Default WAS path is not set - EPM data not available.Explanation: The WASAppServerRoot parameter was not provided in the kwe.xml file. This parameter, which identifies the root directory where the WebSphere Application Server was installed, is required on UNIX systems. User Response: Provide the WASAppServerRoot parameter in the kwe.xml file.
KWE0026E Unable to find WAS path in the Windows registry.Explanation: The WASAppServerRoot parameter was not provided in the kwe.xml file, and the OMEGAMON XE for WebSphere Application Server monitoring agent was unable to locate the HKWY_LOCAL_MACHINE/SOFTWARE/IBM/WebSphere Application Server key in the Windows registry.User Response: Either provide the value for the WebSphere Application Server install directory in the WASAppServerRoot parameter in the kwe.xml file, or ensure that the Windows registry correctly reflects the fact that WebSphere Application Server is installed.
KWE0027E Error encountered processing configuration file - Reason: ‘error’.Explanation: An error was encountered in processing the kwe.xml parameter file. The error field indicates the type of error.User Response: Examine the error string, and take the appropriate action. If necessary, contact Candle Customer Service and Satisfaction.
KWE0028W Error aaaa getting samples for originnode dddd SampleType=bbbb Situation=cccc FilterInfo = eeee ffff gggg hhhh.Explanation: A problem was encountered returning data to the Candle Management Server. The variables in the message have the following meanings.
aaaa The return code.dddd The application server.bbbb The type of data requested.
314 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
User Response: Usually, this message is produced when a request is made for data that the agent is not currently collecting, or when a request is specified for a resource that does not exist.
KWE0030E Function function_name failed. Details= ‘error’.Explanation: Function function_name encountered the error described by ‘error’.User Response: This message reports the return code from the operating system. If you require more help, contact Candle Customer Service and Satisfaction.
KWE0032W Invalid configuration parameter parameter_name.Explanation: An invalid configuration parameter indicated by the value variable was specified in the kwe.xml file. The parameter_name variable indicates the invalid parameter.User Response: Correct the configuration parameter.
KWE0033W Application Server servername referenced in configuration file but does not exist in WebSphere.Explanation: The kwe.xml configuration file contained a reference to an application server identified by the servername variable, but this application server does not exist in the WebSphere Application Server environmentUser Response: This message is a warning. The configuration parameters pertaining to servername are ignored. If necessary, correct the kwe.xml file.
KWE0034W Invalid StatisticInterval configuration value nnn for application server servername. Default value ddd used.Explanation: An invalid value was specified for the StatisticInterval parameter in the kwe.xml configuration file for the application server, servername. The nnn variable indicates the invalid value.User Response: Correct this parameter value in the kwe.xml file.
KWE0036W Invalid CollectorSessionSampleInterval configuration value nnn for application server servername. Default value ddd used.Explanation: An invalid value for the CollectorSessionSampleInterval parameter was specified in the kwe.xml configuration file for the application
cccc The name of the situation for which the data is requested.eeee ffffgggghhhh
Additional filter parameters that were specified for the request.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 315
server identified by the servername variable. The nnn variable indicates the invalid value. The indicated default value of this parameter is being used.User Response: Correct this parameter value in the kwe.xml file.
KWE0038W Invalid LogScanInterval configuration value nnn for application server servername. Default value ddd used.Explanation: An invalid value was specified for the LogScanInterval parameter in the kwe.xml configuration file. The indicated default value of this parameter is being used.User Response: Correct the value of the LogScanInterval parameter in the kwe.xml file.
KWE0039E Invalid RetainLogFileEvents configuration value nnn for application server servername. Default value ddd used.Explanation: An invalid value was specified for the RetainLogEvents_ parameter in the kwe.xml configuration file for the application server, servername. The indicated default value of this parameter is being used.User Response: Correct the value of this parameter in the kwe.xml file.
KWE0046E Thread on application server servername can't be killed - kill is pending for another threadExplanation: You attempted to kill a Java thread; however, the profiler cannot process the request because another kill request is pending for another thread.
KWE0047E Thread on application server servername can't be killed - thread id not foundExplanation: You attempted to kill a Java thread; however, the profiler could not find the requested thread.
KWE0049E Thread on application server servername can't be killed - Thread class not foundExplanation: You attempted to kill a Java thread; however, the profiler could not locate the java.lang.Thread class.User Response: Contact Candle Customer Service and Satisfaction.
KWE0050E Thread on application server servername can't be killed - Thread.stop() method not foundExplanation: You attempted to kill a Java thread; however, the profiler could not locate the stop() method for the java.lang.Thread class.User Response: Contact Candle Customer Service and Satisfaction.
316 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
KWE0051E Unable to open WAS properties file filename. WAS version not determinedExplanation: The OMEGAMON XE monitoring agent was unable to open the WebSphere Application Server .xml file indicated. The agent is unable to determine the current version of WebSphere Application Server.User Response: Ensure that the .xml file exists in the WebSphere properties/com/ibm/websphere directory and that the agent has access to the file.
KWE0052E Unable to open Java log file filename. No logging from EPM client will be doneExplanation: The OMEGAMON XE for WebSphere Application Server monitoring agent was unable to open the log file identified by filename variable. This is a log file used by the OMEGAMON XE for WebSphere Application Server EPM/PMI data collection. Logging from this component will not be done.User Response: Attempt to determine why the file identified in the message could not be opened.
KWE0055W cccc exception caught in unit-name function-name.Explanation: This message indicates that a WARNING exception of the type indicated by the cccc variable has occurred in the OMEGAMON XE for WebSphere Application Server agent. The unit-name and function-name variables in the message contain the names of the unit and the function in which the exception occurred.User Response: This is a warning condition. If you cannot explain this error, contact Candle Customer Service and Satisfaction.
KWE0056I cccc exception caught in unit_name function_name.Explanation: This message indicates that an informational exception of the type indicated by the cccc variable has occurred in the OMEGAMON XE for WebSphere Application Server monitoring agent. The unit_name and function_name variables in the message contain the names of the unit and the function in which the exception occurred.
KWE0057I Version vvv of WebSphere Application Server detectedExplanation: The OMEGAMON XE for WebSphere Application Server agent has found and reported the version level of WebSphere Application Server currently installed.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 317
KWE0058E Can’t create Java Virtual Machine. Error create temporary properties file: filenameExplanation: The OMEGAMON XE for WebSphere Application Server monitoring agent was unable to create a temporary properties files identified by the filename variable. As a result, no WebSphere Application Server monitoring is possible.User Response: Attempt to determine why the file identified by the error message cannot be created. This could be a problem related to authorization problem or a shortage of disk space.
KWE0064E Default workload collection request failed for AppServer appserver Reason: "error"Explanation: The workload request specified in the agent configuration file, kwe.xml, for application server appserver failed with error ‘error’.User Response: See accompanying messages KWE0073E or KWE0074E for more details.
KWE0065I Started collecting workload data for appserver ClassType=aaa ClassName=bbbExplanation: This message indicates that the OMEGAMON XE for WebSphere Application Server monitoring agent successfully started collecting workload data for application server appserver for the ClassType aaa and ClassName bbb.
KWE0066I Started collecting exception workload data for appserver for WorkloadName=aaaExplanation: This message indicates that the OMEGAMON XE for WebSphere Application Server monitoring agent successfully started collecting exception workload data for application server appserver for the workload named aaa.
KWE0067I Started application trace ‘trace_name’ for AppServer appserverExplanation: This message indicates that in response to a Take Action command the OMEGAMON XE for WebSphere Application Server monitoring agent successfully started recording application trace information for appserver to the file named trace_name.
KWE0068E Failed to start application trace trace_name for AppServer servername with Reason: ‘error_code’ response_dataExplanation: This message indicates that in response to a Take Action command, the OMEGAMON XE for WebSphere Application Server monitoring agent failed to start recording to the application trace file specified
318 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
by trace_name because of the error indicated by 'error_code' and response_data.User Response: Examine the error string, and take the appropriate action. If necessary, contact Candle Customer Service and Satisfaction.
KWE0069I Application trace ‘trace_name’ is deletedExplanation: This message indicates that in response to a Take Action command the OMEGAMON XE for WebSphere Application Server monitoring agent successfully deleted the application trace file specified by the trace_name variable.
KWE0070E Failed to delete application trace ‘trace_name’ , Reason: ‘error_code’Explanation: This message indicates that in response to a Take Action command, the OMEGAMON XE for WebSphere Application Server monitoring agent failed to delete the application trace file specified by trace_name. The ‘error_code’ field describes the error..User Response: Verify that the file with the name specified by trace_name exists and that the agent has authority to delete it.
KWE0071I Take Action command ‘command_name’ completed successfully.Explanation: This message indicates that the Take Action command was successfully processed by the OMEGAMON XE for WebSphere Application Server monitoring agent.
KWE0072E Take Action command ‘command_name’ failed - Reason: ‘error_code’Explanation: This message indicates that the Take Action command identified by command_name was not successfully processed by the OMEGAMON XE for WebSphere Application Server monitoring agent because of the specified error_code.
KWE0073E Failed to start collecting workload data for servername ClassType=aaa ClassName=bbb with Reason: ‘error_code’ response_dataExplanation: This message indicates that the OMEGAMON XE for WebSphere Application Server monitoring agent failed to start collecting workload data for the ClassType and ClassName specified because of the error indicated by ‘error_code’ and response_data.
KWE0074E Failed to start collecting exception workload data for servername WorkloadName=aaa with Reason: ‘error_code’ response_dataExplanation: This message indicates that the OMEGAMON XE for WebSphere Application Server monitoring agent failed to start collecting workload data for the specified WorkloadName because of the error indicated by ‘error_code’ and response_data.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 319
KWE0075E Application tracing stop failed with Reason: ‘error_code’ for AppServer servernameExplanation: This message indicates that in response to a Take Action command, the OMEGAMON XE for WebSphere Application Server monitoring agent failed to stop application tracing because of the specified ‘error_code’.
KWE0076E Deleting the application trace file file_name is not allowed. Trace file is for server instance instance1_name but request was issued against server instance instance2_nameExplanation: The attempt to delete the application trace file indicated in the file_name variable was rejected because the file was produced for the server instance indicated by the instance1_name variable, but the request was issued against the server instance indicated in the instance2_name variable. User Response: Retry the Take Action, and specify the correct destination system.
KWE0079E Socket error detected. Function=function_name ConnectionName=connection_name Reason="error_code" Details="errno = errno, err_text"Explanation: The OMEGAMON XE monitoring agent encountered an error on the socket connection to a WebSphere Application Server JVM profiler or workload analysis component. The function_name indicates the type of socket operation and may be one of the following values:� Send� Receive� Connect� Listen� Bind
The connection_name indicates the name of the application server region. The specific error is described by "error_code" and "err_text"; the error number is errno.
User Response: Based upon the "error_code", attempt to determine what caused the problem. If necessary, contact Candle Customer Service and Satisfaction.
KWE0082W Unable to open file_nameExplanation: The OMEGAMON XE for WebSphere Application Server agent was unable to read the profiler restrictions file KWEProfilerRestrictions.ini.
320 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
User Response: Ensure the KWEProfilerRestrictions.ini file is present in the agent directory (C:\Candle\CMA in Windows; $CANDLEHOME/config/ on UNIX) and that the agent has read access to it.
KWE0083E Unable to open Property file filenameExplanation: The OMEGAMON XE monitoring agent was unable to open the specified Java property property file as required.User Response: Determine why the file could not be opened. Correct and restart the monitoring agent.
KWE0084E Unable to open server IP port nnnnn. Incoming connections from application server regions will not be received. Agent will retry in 60 seconds.Explanation: The OMEGAMON XE monitoring agent could not open the IP port specified by nnnnn.User Response: Specify a different, unused port number, and restart the agent.
KWE0086E Default heap collection request failed for AppServer xxxx Reason: "reason".Explanation: Workload analysis was unable to start heap collection for the application server indicated by xxxx. The failure reason is provided in reason.User Response: Investigate the reason for the failure. If necessary, call Candle Customer Service and Satisfaction.
KWE0087I Started heap data collection for AppServer xxxx Classes: mask Level: lvlExplanation: Heap collection was started for application server xxxx for classes that match the class mask xxxx at the recording level given.
KWE0088I SetInflightThreshold request successful for AppServer xxxx Value: "aaa".Explanation: The SetInflightThreshold Take Action command was successfully executed for application server xxxx. The threshold was set to aaa milliseconds.
KWE0089E Failed to SetInflightThreshold for AppServer xxxx with Reason: "reason1" reason2.Explanation: The SetInflightThreshold Take Action command for application server xxxx failed. The failure reason is provided in reason1 and reason2.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 321
User Response: Investigate the reason for the failure. If necessary, call Candle Customer Service and Satisfaction.
KWE0090I SetCapturePercent request successful for AppServer xxxx Value: "val1 val2".Explanation: The SetCapturePercent Take Action command was successfully executed for application server xxxx. The workload capture percent was set to val1; the heap capture percent was set to val2.User Response:
KWE0091E Failed to SetCapturePercent for AppServer &1 with Reason: "reason1" reason2.Explanation: The SetCapturePercent Take Action command for application server xxxx failed. The failure reason is provided in reason1 and reason2.User Response: Investigate the reason for the failure. If necessary, call Candle Customer Service and Satisfaction.
KWE0092I SetLockAnalysisLevel request successful for appServer xxxx: Level = "lvl" Mincost="mc"Explanation: The SetLockAnalysisLevel Take Action command was successfully processed. The application server name is xxxx, the level is lvl, and the minimum cost is mc.
KWE0094E Failed to start collecting heap data for xxxx with Reason: "reason1" reason2.Explanation: The StartHeapCollection Take Action command for application server xxxx failed. The failure reason is provided in reason1 and reason2.User Response: Investigate the reason for the failure. If necessary, call Candle Customer Service and Satisfaction.
KWE0095I RefreshInstrumentation request successful for appServer xxxx File: fl. RestartApps: restExplanation: The RefreshInstrumentation Take Action command was successfully processed. xxxx is the targeted application server, fl is the name of the instrumentation control file, and rest is the enterprise application mask.
322 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
KWE0096E RefreshInstrumentation request failed for appServer xxxx with Reason: "reason1" reason2Explanation: The RefreshInstrumentation request failed. xxxx is the targeted application server, reason1 is the reason for the failure, and reason2 contains additional information passed from Workload Analysis.User Response: Determine why the RefreshInstrumentation request failed, and re-enter the command.
KWE0097I RefreshInstrumentation request restarted the following application: appExplanation: WebSphere Application Server application app was restarted as a result of processing the RefreshInstrumentation Take Action command
KWE0098E Invalid CollectHistorical attribute value: valExplanation: An invalid value, val, was passed as the value of the DefaultCollectHistorical or CollectHistorical attribute in the agent configuration file. The attribute is ignored.User Response: Correct the invalid attribute in the agent configuration file, and restart the agent.
KWE0099W Historical data not being collected for sample type tttt on application server xxxxExplanation: Historical data collection was attempted for the sample type identified by tttt; however, no historical data was available because the DefaultCollectHistorical or CollectHistorical attributes within the agent configuration file indicated that historical data should not be collected for this sample type. xxxx indicates the application server name.User Response: If historical data should be collected for this type of data, modify the DefaultCollectHistorical or CollectHistorical attribute in the agent configuration file to request this type of data. Otherwise reconfigure historical data collection using CandleNet Portal so this type of historical data is no longer requested.
KWE0100E Cannot initiate EPM data collector. JAVA exception: ccccExplanation: The OMEGAMON agent was unable to create PMI components, which are needed to retrieve WebSphere performance data. As a result, no WebSphere monitoring is possible. The cccc value contains the original Java exception.User Response: For WebSphere Application Server V4.0, ensure that the WebSphere administrative server is running and that NamingServerPort in kwe.xml has the same value as com.ibm.ejs.sm.adminServer.bootstrapPort in WASHOME/bin/admin.config. If WebSphere global security is enabled,
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 323
recycle the OMEGAMON agent after the WebSphere administrative server restarts.For WebSphere Application Server V5.0, ensure that the application server and node agent (for Network Deployment) are running and that the Performance Monitoring Service is enabled.
KWE0101E Cannot get the status of the administration server. JAVA exception: ccccExplanation: The OMEGAMON XE for WebSphere Application Server agent was unable to contact the WebSphere administrative server to get its status. As a result, further WebSphere monitoring is not possible. The cccc value contains the original Java exceptionUser Response: For WebSphere Application Server V4.0, ensure the WebSphere administrative server is running. If WebSphere global security is enabled, recycle the OMEGAMON XE agent after the WebSphere administrative server restarts.For WebSphere Application Server V5.0, ensure the application server and node agent (for Network Deployment) are running.
KWE0102I Cannot finish cleanup. JAVA exception: cccc - ignoredExplanation: The OMEGAMON XE agent encountered problem in closing its RAS1 log file. The cccc value contains the original Java exception.
KWE0103W Cannot complete the requested task. JAVA exception: ccccExplanation: The OMEGAMON XE agent was unable to invoke the components in the WebSphere administrative server to perform the requested task. The cccc variable contains the original Java exception.User Response: For WebSphere Application Server V4.0, ensure the WebSphere administrative server is running. Also make sure the database server for the WebSphere administrative repository is running.For WebSphere Application Server V5.0, ensure the application server and node agent (for Network Deployment) are running and that the Performance Monitoring Service is enabled.
KWE0104I Cannot get WAS server status. JAVA exception: cccc - ignoredExplanation: The OMEGAMON XE agent was unable to invoke remote methods in the WebSphere administrative server and failed to get status information for the application server instances. The cccc value contains the original Java exception.User Response: Ensure the WebSphere administrative server is running and that the database server for the WebSphere administrative repository is also running.
324 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
KWE0105I server_name is not a valid WAS server name. - ignoredExplanation: The OMEGAMON XE agent was unable to find the application server instance, server_name.User Response: Use the correct application server name when creating situations. (The name is case sensitive.) When an application server is removed from a WebSphere domain, use CMW to remove the subnode for that application server instance.
KWE0106E Cannot retrieve EPM performance data as EPMService bean is not available.Explanation: The OMEGAMON XE agent was unable to retrieve performance data due to component errors in the WebSphere administrative server (for WebSphere Application Server V4.0) or the application server/node agent (for WebSphere Application Server V5.0).User Response: For WebSphere Application Server V4.0, ensure that the WebSphere administrative server is running and that the database server for WebSphere administrative repository is also running.For WebSphere Application Server V5.0, ensure the application server and node agent (for Network Deployment) are running and that the Performance Monitoring Service is enabled.
KWE0107I server_name server instance stopped. - ignoredExplanation: The OMEGAMON XE agent detected that the server_name application server instance is stopped. As a result, no performance data is available for the server instance.
KWE0108I xxxxx is not a valid instrumentation level. - ignoredExplanation: The OMEGAMON XE agent detected that an incorrect value was used to set up the instrumentation level for WebSphere resources. Valid instrumentation levels include: NONE, LOW, MEDIUM, HIGH, and MAXIMUM.User Response: Use valid instrumentation levels when invoking Set IL take action commands through CNP.
KWE0109I Invalid WAS resource name is used for setting up instrumentation level - ignoredExplanation: The OMEGAMON XE agent could not set up the instrumentation level for a non-existent WebSphere resource. User Response: Ensure that the required WebSphere resource is loaded to an application server runtime environment. Performance data for a WebSphere resource is not collected until the resource has been loaded to an application server runtime since the server was started. For example, use a browser to invoke a servlet.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 325
KWE0110I Cannot setup instrumentation level for path_to_resource - ignoredExplanation: The OMEGAMON XE agent could not set up the instrumentation level for a specific WebSphere resource. The specified WebSphere resource may not exist anymore in the application server’s runtime. The path variables in the message contain the full path to the WebSphere resource.User Response: Ensure that the required WebSphere resource exists in an application server runtime.
KWE0111W Cannot retrieve performance data for WAS resource resource_name of instance_name server instance. JAVA exception: ccccExplanation: The OMEGAMON XE agent was unable to invoke the components in the WebSphere administrative server to retrieve performance data for the specific WebSphere resource. The resource_name variable value contains the name of the specified WebSphere resource. The cccc value contains the original Java exception.User Response: Ensure that WebSphere administrative server is running and that the database server for WebSphere administrative repository is also running.
KWE0112W Cannot recursively retrieve performance data for WAS resource resource_name of instance_name server instance. JAVA exception: ccccExplanation: The OMEGAMON XE agent was unable to invoke the components in the WebSphere administrative server to retrieve performance data for the specific WebSphere resource and all resources below this resource. The resource_name value contains the name of the specified WebSphere resource; cccc contains the original Java exception.User Response: Ensure that the WebSphere administrative server is running and that the database server for the WebSphere administrative repository is also running.
KWE0114I WAS resources resource_name may not exist or are initiated at instance_name server instance - ignoredExplanation: The OMEGAMON XE agent was unable to retrieve performance data for the specific WebSphere resource. The resource may not exist or may not be initialized in the application server, instance_name, runtime. The resource_name value contains the name of the specified WebSphere resource.User Response: Ensure that the required WebSphere resource exists in the application server, instance_name, runtime.
326 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
KWE0115W Cannot get PMI modules for instance_name server instance - xxxx]Explanation: The OMEGAMON XE agent could not find any WebSphere resource in a specific application server, instance_name. The application server instance might stop. The xxxx value contains detailed error information.User Response: For WebSphere Application Server V4.0, ensure that the WebSphere administrative server is running and the application server instance_name is also running.For WebSphere Application Server V5.0, ensure the application server and node agent (for Network Deployment) are running and that the Performance Monitoring Service is enabled.
KWE0116W Cannot get PMI data for resource_name - xxxxExplanation: The OMEGAMON XE agent agent was unable to retrieve performance data for the specific WebSphere resource named in the resource_name variable. The xxxx variable contains detailed error information.User Response: For WebSphere Application Server V4.0, ensure that WebSphere administrative server is running and that the required WebSphere resource exists in an application server’s runtime environment.For WebSphere Application Server V5.0, ensure the application server and node agent (for Network Deployment) are running and that the Performance Monitoring Service is enabled.
KWE0117W PMI data is NULL for resource_name - Resources may be stopped or removedExplanation: The OMEGAMON XE agent found empty performance data for the specific WebSphere resource identified by the resource_name variable.User Response: For WebSphere Application Server V4.0, ensure that the WebSphere administrative server is running and that the required WebSphere resource exists in an application server’s runtime environment.For WebSphere Application Server V5.0, ensure the application server and node agent (for Network Deployment) are running and that the Performance Monitoring Service is enabled.
KWE0118W Cannot setup instrumentation level for resource_name at server_name server instance -xxxx Explanation: The OMEGAMON XE agent could not setup the instrumentation level for a specific WebSphere resource. The specified WebSphere resource may not exist anymore in the application server’s runtime. The resource_name value contains the full path to the WebSphere
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 327
resource; server_name contains the name of an application server; and xxxx contains detailed error information.User Response: For WebSphere Application Server V4.0, ensure that the WebSphere administrative server is running and that the required WebSphere resource exists in an application server’s runtime environment.For WebSphere Application Server V5.0, ensure the application server and node agent (for Network Deployment) are running and that the Performance Monitoring Service is enabled.
KWE0119W Cannot get PMI modules for instance_name server instance - [xxxx]Explanation: The OMEGAMON XE agent failed to get PMI modules for the application server named instance_name. The application server instance might stop. The xxxx field contains detailed error information.User Response: For WebSphere Application Server V4.0, ensure that the WebSphere administrative server is running and that application server instance_name is also running.For WebSphere Application Server V5.0, ensure that the application server and node agent (for Network Deployment) are running and that the Performance Monitoring Service is enabled.
KWE0120E No verbose gc output log file was specified for application server appserver. RC - error_codeExplanation: The Candle verbose garbage collection component could not determine the application server file where verbose garbage collection messages are logged because of the specified error_code.User Response: Ensure that the most current version of OMEGAMON XE agent is installed.
KWE0121E Verbose GC data collection request failed for AppServer appserver Reason: "error_code".Explanation: The Candle verbose garbage collection request for application server appserver was not successful because of the specified error_code.User Response: Determine if there has been an error on application server appserver. Correct and restart verbose garbage collection.
KWE0122I Started collecting verbose gc data for application server appserver.Explanation: The Candle verbose garbage collection component has been fully initialized for the given application server.
328 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
KWE0123E Failed to start collecting verbose gc data for appserver with Reason: "error_code" response_data.Explanation: The Candle verbose garbage collection component did not complete initialization for application server appserver because of the specified error_code. Additional information provided in response_data.User Response: Determine if there has been an error for the given application server. Correct and restart verbose garbage collection.
KWE0124I Verbose GC stopped for application server appserver.Explanation: The Candle verbose garbage collection component has been stopped for the given application server.
KWE0125W Invalid config_name configuration value nnn entered. An integer is expected. Default value ddd used.Explanation: An invalid value for parameter config_name was specified in the kwe.xml configuration file. The nnn variable shows the invalid value. The indicated default value of this parameter is being used.User Response: Correct this parameter value in kwe.xml.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 329
KWEWA messagesThe KWEWA messages are issued by the workload analysis component (also called the collector session) within the WebSphere Application Server’s region. These messages cover numbers of the form KWEWAxxx and are listed numerically.
KWEWA001E AgentConnection class initializer not able to load native library: library_name.Explanation: The Candle Workload Analysis component was unable to load the native library library_name. The Workload Analysis component cannot continue.User Response: Ensure the native library identified by library_name is installed in the proper directory. The default is /WebSphere/AppServer/bin.
KWEWA002I Candle Workload Analysis Enabler is being initialized.Explanation: The Candle Workload Analysis Enabler is starting its initialization.
KWEWA003I Workload Analysis library(wa-jarfile-name) build level level-1 incompatible with Candle_WA_Enabler(scl-jarfile-name) build level level-2.Explanation: During initialization, the Workload Analysis Enabler found that the build level of its jar file (level-2) is incompatible with the build level of the Workload analysis component jar file (level-1). The Workload Analysis component cannot continue.User Response: If Candle maintenance was recently applied, ensure that all steps in the configuration process were completed successfully. Ensure also that you successfully ran the setupCandleWAEnabler.sh shell script on UNIX or setupCandleWAEnabler.bat on Windows.
KWEWA004E -JavaRoot option is set twice.Explanation: The -JavaRoot parameter was specified multiple times to the setupCandleWAEnabler utility.User Response: Correct the error and rerun.
KWEWA005E -JavaRoot directory name is missing.Explanation: The -JavaRoot parameter was specified with no value to the setupCandleWAEnabler utility.User Response: Correct the error and rerun.
KWEWA006E -JarFile option is set twice.Explanation: The -JarFile parameter was specified multiple times to the setupCandleWAEnabler utility.
330 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
User Response: Correct the error and rerun.
KWEWA007E -JarFile directory name is missing.Explanation: The -JarFile parameter was specified with no value to the setupCandleWAEnabler utility.User Response: Correct the error and rerun.
KWEWA008E -ClassLoader option is set twice.Explanation: The -ClassLoader parameter was specified multiple times to the setupCandleWAEnabler utility.User Response: Correct the error and rerun.
KWEWA009E -ClassLoader directory name is missing.Explanation: The -ClassLoader parameter was specified with no value to the setupCandleWAEnabler utility.User Response: Correct the error and rerun.
KWEWA010E -OutFile option is set twice.Explanation: The -OutFile parameter was specified multiple times to the setupCandleWAEnabler utility.User Response: Correct the error and rerun.
KWEWA011E -OutFile directory name is missing.Explanation: The -OutFile parameter was specified with no value to the setupCandleWAEnabler utility.User Response: Correct the error and rerun.
KWEWA012E -Replace option is set twice.Explanation: The -Replace parameter was specified multiple times to the setupCandleWAEnabler utility.User Response: Correct the error and rerun.
KWEWA013E -Replace directory name is missing.Explanation: The -Replace parameter was specified with no value to the setupCandleWAEnabler utility.User Response: Correct the error and rerun.
KWEWA014E Unrecognized option: option.Explanation: An unrecognized option was specified to the setupCandleWAEnabler utility.User Response: Correct the error and rerun.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 331
KWEWA015E Required parameter missing: -JavaRoot.Explanation: The -JavaRoot parameter was not specified to the setupCandleWAEnabler utility. This parameter is required.User Response: Correct the error and rerun.
KWEWA016E Required parameter missing: -OutFile.Explanation: The -OutFile parameter was not specified to the setupCandleWAEnabler utility. This parameter is required.User Response: Correct the error and rerun.
KWEWA017E Required parameter missing: -Replace.Explanation: The -Replace parameter was not specified to the setupCandleWAEnabler utility. This parameter is required.User Response: Correct the error and rerun.
KWEWA018E Unable to instrument jar file filename because of ZipException exception.Explanation: The setupCandleWAEnabler utility failed because of a problem reading or writing a jar file. The specific reason for the failure is given in exception.User Response: Correct the error and rerun.
KWEWA019E exceptionExplanation: The setupCandleWAEnabler utility failed because of a Java exception. The specific reason for the failure is given by exception variable.User Response: Correct the error and rerun. If necessary, call Candle Customer Service and Satisfaction.
KWEWA020I Candle workload analysis class loader hook is active.Explanation: The Candle workload analysis component class loader has been activated.
KWEWA022I Candle WAS Workload Analysis component has been initialized. Build Level: build-levelExplanation: The Candle workload analysis component has been fully initialized. The build level of the component is given by build-level variable.
KWEWA023I Candle workload analysis collector is being activated.Explanation: The Candle workload analysis component is being activated.
332 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
KWEWA025E Exception caught by instrumentClass.Explanation: A Java exception was caught while attempting to perform instrumentation on a Java class. Details of the exception will appear in the Workload Analysis component log file.User Response: If necessary, call Candle Customer Service and Satisfaction.
KWEWA026I Candle workload analysis detailed logging is enabled with type trace-type.Explanation: Based upon the contents of the XML configuration files, the Workload Analysis component has enabled detailed logging; trace-type indicates the type of tracing being performed.
KWEWA027I Candle workload analysis detailed logging is disabled.Explanation: Based upon the contents of the XML configuration file(s), the Workload Analysis component has disabled detailed logging.
KWEWA029W Error parsing User control file file_name. User control file ignored.Explanation: The Workload Analysis component encountered an error parsing the user instrumentation control file identified by the file_name variable. The entire contents of the user instrumentation control file are ignored.User Response: Check for the KWEWA030W message, which gives the exact cause of the error. Correct the user instrumentation control file.
KWEWA030W parse-error.Explanation: This message indicates that an error took place parsing a user instrumentation control file. The exact error is given by the parse-error variable.User Response: Correct the user instrumentation control file.
KWEWA031W User configuration file file_name does not exist - ignored.Explanation: The user instrumentation control file file-name, identified by the UserConfigFile attribute of the main instrumentation control file, cannot be located. The Workload Analysis component continues instrumentation using only the main instrumentation control fileUser Response: If you want to provide user-specific instrumentation parameters, you should create the file specified by file-name.
KWEWA032E Error parsing control file file_name.Explanation: The Workload Analysis component encountered an error parsing the main instrumentation control file identified by the file_name variable. The Workload Analysis component cannot continue.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 333
User Response: Check for the KWEWA033W message, which will indicate the exact cause of the error. Correct the instrumentation control file.
KWEWA033W parse-error.Explanation: This message indicates that a error took place parsing the main instrumentation control file. The exact error is given by the parse-error variable.User Response: Correct the instrumentation control file.
KWEWA034I Candle workload analysis control file is file_name.Explanation: This message indicates the name of an instrumentation control file which is being used by the Workload Analysis component.
KWEWA035I Candle workload analysis control file file_name has been parsed.Explanation: This message indicates that the instrumentation control file file-name has been successfully parsed.
KWEWA036W Class Definition is being ignored because error.Explanation: This message indicates a Class definition tag in an instrumentation control file is being ignored because of a syntax error. The specific error is given by the error variable.User Response: Correct the instrumentation control file.
KWEWA037I ClassTypeDef Definition is being ignored because error.Explanation: This message indicates a ClassTypeDef definition tag in an instrumentation control file is being ignored because of a syntax error. The specific error is given by the error variable.User Response: Correct the instrumentation control file.
KWEWA038E Incompatibility detected between Java library(wa_jarfile_name) and Native Library(native_library_name). Java library build level is level-1. Native library build level is level-2.Explanation: During initialization, the workload analysis component found that the build level of its jar file (level-1) is incompatible with the build level of the workload analysis component native library (level-2). The workload analysis component cannot continue.User Response: If Candle maintenance was recently applied, ensure that all steps in the configuration process were completed successfully.
334 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
KWEWA039E Incompatibility detected between Native library(native_library_name) and Java Library(wa_jarfile_name). Native library build level is level-1. Java library build level is level-2.Explanation: During initialization, the workload analysis component found that the build level of the workload analysis native library (level-1) is incompatible with the build level of the workload analysis jar file (level-2). The workload analysis component cannot continue.User Response: If Candle maintenance was recently applied, ensure that all steps in the configuration process were completed successfully.
KWEWA040E Error exception caught attempting to verify Native library compatibility.Explanation: An exception occurred when the Workload Analysis component was attempting to verify compatibility with the native library. The exact error is given by exception.User Response: If Candle maintenance was recently applied, ensure that all steps in the configuration process were completed successfully. Otherwise, contact Candle Customer Service and Satisfaction.
KWEWA042E Initialization failed due to failure parsing control file.Explanation: The Workload Analysis component was unable to complete initialization because of an error parsing the instrumentation control file. The Workload Analysis component cannot continue. User Response: Find the prior KWEWA032E and KWEWA033W to determine the exact source of the error. Correct the instrumentation control file.
KWEWA043E Initialization failed due to exception: exception.Explanation: The Workload Analysis component was unable to complete initialization because of a Java exception. The specific exception is given by the exception variable. User Response: Contact Candle Customer Service and Satisfaction.
KWEWA044W Unable to open log-file-name due to exception: exception.Explanation: The Workload Analysis component was unable to open the log file specified by log-file-name because of the exception given by exception. The Workload Analysis component proceeds without a log fileUser Response: Attempt to determine what caused the exception. Ensure that the application server has the authority to create log files. If necessary, contact Candle Customer Service and Satisfaction.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 335
KWEWA045I Candle workload enabler completed initialization.Explanation: The Workload Analysis Enabler has successfully completed initialization.
KWEWA046E Exception: exception caught initializing Candle workload enabler.Explanation: The Workload Analysis Enabler was unable to complete initialization because of a Java exception. User Response: Contact Candle Customer Service and Satisfaction.
KWEWA047E Exception: exception caught in DataGatherer threadExplanation: A Java exception was caught while attempting to collect data for transmission to a Candle monitoring agent. A stack trace is also written into the logUser Response: Contact Candle Customer Service and Satisfaction.
KWEWA048E Exception: exception caught processing Poll requestExplanation: A Java exception was caught while attempting to collect data for transmission to a Candle monitoring agent. A stack trace is also written into the log.User Response: Contact Candle Customer Service and Satisfaction.
KWEWA049E Unable to check native library build level because native library not availableExplanation: The Workload Analysis component was unable to verify the compatibility of the kweprof native library, because the library was not located.User Response: Contact Candle Customer Service and Satisfaction.
KWEWA051W Unable to locate com.candle.kwe.instrument.agent_parms propertyExplanation: The -Dcom.candle.kwe.instrument.agent_parms property was not set in the Java command line arguments for the application server. The Workload Analysis component is unable to access the configuration parameters used to start the monitoring agent. The agent profiler port is obtained from the instrumentation control file.User Response: None. If you want Workload Analysis to obtain the port number from the agent configuration file, you must provide the full name of the file in the com.candle.kwewl.instrument.agent_parms property on the Java command line arguments.
KWEWA052E Unable to locate agent control file file-nameExplanation: The -Dcom.candle.kwe.instrument.agent_parms property was specified in the Java command line arguments for the application server,
336 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
but the Workload Analysis component was unable to open the file. The agent profiler port is obtained from the instrumentation control fileUser Response: Determine why the file could not be opened. Verify the correctness of the -Dcom.candle.kwe.instrument.agent_parms property on the Java command line arguments.
KWEWA053E IOException parsing agent control file: exceptionExplanation: The -Dcom.candle.kwe.instrument.agent_parms property was specified in the Java command line arguments for the application server, but the Workload Analysis component encountered a problem attempting to parse the file. The agent profiler port is obtained from the instrumentation control file.User Response: Determine why the file could not be parsed. Correct the problem and rerun.
KWEWA054I Attempting to connect to agent on port port-numberExplanation: The Workload Analysis component is attempting to connect to the monitoring agent on the IP port given by port-number
KWEWA055E Unable to obtain current working directory - exceptionExplanation: A Java exception was caught trying to determine the name of the current working directory.User Response: Contact Candle Customer Service and Satisfaction.
KWEWA057E -OutFileVersion option is set twiceExplanation: The -OutFileVersion option is set twice on the invocation of setupCandleWAEnabler.User Response: Correct the error and resubmit
KWEWA058I Candle Workload Analysis has connected to the agent on port port-numberExplanation: The collector session has established a connection with the monitoring agent on IP port port-number.
KWEWA059E Candle Workload Analysis has become disconnected from the agentExplanation: The collector session has lost connection with the monitoring agent.User Response: Investigate the cause of the failure. This could be because the monitoring agent has stopped running, or has disconnected for some reason. If necessary, contact Candle Customer Service and Satisfaction.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 337
KWEWA060E Candle Workload Analysis has caught exception exception in background processingExplanation: A Java exception was caught in the background thread of the collector session.User Response: Contact Candle Customer Service and Satisfaction.
KWEWA061E -ThreadInstr option is set twiceExplanation: The -ThreadInstr option is set twice on the invocation of setupCandleWAEnabler.User Response: Correct the error and resubmit.
KWEWA062E Unable to instrument class class-name and method method-name because total code length would exceed 65535Explanation: The Workload Analysis component is attempting to instrument method method-name in class class-name. However, the insertion of instrumentation hooks into this method would force the size of the method to exceed 65535 bytes, which is the Java architectural limit. As a result, instrumentation of this method is abandoned.
KWEWA063E Unable to instrument class class-name and method method-name because of BCEL error exception.Explanation: The workload analysis component is attempting to instrument method method-name in class class-name. However, the class could not be instrumented because of an exception in the Byte Code Engineering Library.User Response: Contact Candle Customer Service and Satisfaction.
KWEWA067I Workload Analysis detailed log opened on filenameExplanation: The workload analysis is writing a diagnostic log file to the file name specified by filename.
KWEWA068I Contents of xml-file-name follows:Explanation: The contents of the named XML file name are written to the standard output log following this message.
KWEWA069W Potentially missing application trace entries detected. Expected Stack Level: levelExplanation: The application trace facility has determined that entries are potentially missing from the application trace file. As a result, the application trace is closed.
338 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
KWEWA070W Current Entry: app trace entryExplanation: This message follows message KWEWA069W and indicates the application trace entry where the problem was detected.
KWEWA071W Application Trace entry could not be written: app trace entryExplanation: The application trace entry could not be written to the application trace file, probably because application trace entries are being created faster than they can be written.
KWEWA072E Maximum number of classes to instrument exceededExplanation: The maximum number of instrumented classes, defined by the MaxClasses attribute in the kweiuser.xml file, has been exceeded. No more classes will be instrumented.User Response: Increase the MaxClasses value.
KWEWA073I Workload Definition is being ignored because reasonExplanation: The Workload definition in kweiuser.xml was ignored for the stated reason.User Response: Correct the Workload definition, and restart the application server.
KWEWA074I Workload_Class contains duplicate methods. Removing method=method from specification workload-nameExplanation: A duplicate method name was detected in a Workload definition specified in kweiuser.xml.User Response: Correct the Workload definition, and restart the application server.
KWEWA075I Workload_Class does not conform to specifications, ignoredExplanation: This message usually follows a KWEWA074I message. It indicates that the Workload definition is being ignored.User Response: Correct the Workload definition, and restart the application server.
KWEWA076I Workload_Class Definition is being ignored because reasonExplanation: This message states the reason that a Workload_Class definition is being ignored.User Response: Correct the Workload_Class definition, and restart the application server.
KWEWA077I Candle workload analysis library library-name is loadedExplanation: The shared library indicated by library-name was loaded by workload analysis.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 339
KWEWA078E Candle workload analysis library library-name is not loadedExplanation: Workload analysis could not load the shared library indicated by library-name. A stack trace is written to the standard out log.User Response: Check the stack trace to determine why the library could not be loaded. If necessary, contact Candle Customer Service and Satisfaction.
KWEWA079E Candle workload analysis library library-name is not accessibleExplanation: Workload analysis could not load the shared library indicated by library-name because of installation security.User Response: Change the security definitions to allow the library to be accessed by OMEGAMON XE for WebSphere Application Server. If necessary, contact Candle Customer Service and Satisfaction.
KWEWA080E Candle workload analysis library library-name is missingExplanation: Workload analysis could not locate the shared library indicated by library-name.User Response: Determine why the file system could not locate the shared library. If necessary, contact Candle Customer Service and Satisfaction.
KWEWA081I Candle workload analysis library property-name is boot-library-pathExplanation: This message identifies the contents of the sun.boot.library.path Java property.
KWEWA082E Candle workload analysis library library-name is not foundExplanation: Candle workload analysis encountered an UnsatisfiedLinkError Java exception attempting to load the shared library library-name.User Response: Examine the file system to determine why the shared library could not be located. If necessary, contact Candle Customer Service and Satisfaction.
KWEWA083E Delay Definition is being ignored because reasonExplanation: The Delay definition in kweiuser.xml was ignored for the stated reason.User Response: Correct the Delay definition, and restart the application server.
KWEWA084W Delay_Class contains duplicate methods. Removing method=method from specification specificationExplanation: A duplicate method name was detected in a Delay definition specified in kweiuser.xml.
340 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
User Response: Correct the Delay definition, and restart the application server.
KWEWA085W Delay_Class does not conform to specifications, ignoredExplanation: This message usually follows a KWEWA083W message. It indicates that the Delay definition is being ignored.User Response: Correct the Delay definition, and restart the application server.
KWEWA086W Delay_Class Definition is being ignored because reasonExplanation: This message states the reason that a Delay_Class definition is being ignored.User Response: Correct the Delay definition, and restart the application server.
KWEWA087I Setting user class path to: user-class-path-nameExplanation: This message is produced as a result of the UserClassPath value in the kweiuser.xml file. It indicates that the class path names specified by user-class-path-name is recognized as the class path for loading user plugin classes.
KWEWA089E Incompatible Agent build level detected. Actual = actual-build-level Required = required-build-level. Agent session disconnected.Explanation: This message indicates that workload analysis has made contact with a back-level monitoring agent, which is unsupported.User Response: Determine why the monitoring agent is back-level from the workload analysis component. If necessary, contact Candle Customer Service and Satisfaction.
KWEWA090E I/O encountered writing log file log-file-nameExplanation: An I/O error was detected writing the workload analysis log file specified in the message.User Response: Determine why the log file could not be written.
KWEWA091I Application Server shutdown detectedExplanation: The Workload Analysis component has detected that the application server is shutting down. Workload Analysis will terminate.
KWEWA092I Candle Workload Analysis Background Thread EndedExplanation: This message usually follows message KWEWA091I. It indicates that the Workload Analysis background thread is ending as a result of the application server shutdown.
Appendix C: OMEGAMON XE for WebSphere Application Server Messages 341
KWEWA093W nnnn workloads could not be measured by Workload AnalysisExplanation: Workloads were completing faster than workload analysis could measure. Consequently, some of the workloads were not measured. The number of workloads not measured is nnnn.User Response: None. This error usually occurs only in very busy environments.
KWEWA094E Unable to locate file fl - Candle workload analysis disabledExplanation: \Workload Analysis was unable to locate the file identified by fl in the kwewa.jar file; Workload Analysis initialization fails.User Response: Examine the kwelwa.jar file to determine why the specified file cannot be located. If necessary, contact Candle Customer Service and Satisfaction.
342 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
Glossary 343
Glossary
C
class file A file containing Java object code for a single Java class of objects.
class loader A Java component that loads Java object classes into the heap.
CGI Common Gateway Interface. The standard way for a Web server to pass a Web user's request to an application program and to receive data back to forward to the user. When the user supplies information on a Web page, it usually needs to be processed by an application program. The Web server typically passes the form information to a small application program that processes the data and may send back a confirmation message. This method or convention for passing data back and forth between the server and the application is called the Common Gateway Interface (CGI). It is part of the Web's Hypertext Transfer Protocol (HTTP).
component In object-oriented programming environments like Java, a component is a reusable program building block that can be combined with other components running on the same or different computers in a distributed network to form an application. Examples of a component include a single button in a graphical user interface, an interface to a database
manager, and an EJB. A component runs within a container.
container In the Enterprise JavaBeans (EJB) architecture, a container is an application program that executes the program building block known as a component (that is, a JavaBean). You write a Java container (such as a GUI button or a database requester) that runs both prewritten and site-developed JavaBeans. Examples of containers include pages on a Web site as well as the Web browsers themselves.
CPU Central Processing Unit. The part of the computer that interprets and executes instructions.
CT Candle Technologies. The software foundation that supports the development and operations of CandleNet Portal, the Candle Management Server, and its OMEGAMON XE agents.
CTG CICS Transaction Gateway. CTG integrates your site’s WebSphere Application Server applications with key legacy business systems running on CICS servers. CTG integrates middle-tier application servers with CICS by providing a multiuser gateway that supports Web applications written in Java and other languages, including C/C++, Visual Basic, and COBOL. The Gateway process communicates with
344 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
CICS applications after receiving requests from:� Java programs such as applets and
servlets.� Special Java classes such as the class
JavaGateway, which establishes communication with the CTG process.
� Native code that handles the communication from the Gateway daemon to the CICS server.
CTG supports these programming interfaces:� the External Call Interface (ECI),
used when calling COMMAREA-based CICS applications
� the External Presentation Interface (EPI), used for communicating with 3270-based transactions
� the External Security Interface (ESI), used for exchanging userid/password information with CICS
The latest version of CTG implements the J2EE Connector Architecture (JCA), which allows enterprise Java technology to exploit CICS applications.
D
datasources Data pertaining to J2EE data sources, which are logical connections to database subsystems.
DCE Distributed Computing Environment. A specification from the Open Software Foundation (OSF) that supports remote function execution
across a network. WebSphere Application Server uses DCE to provide certain types of security, for example, authentication of tokens, tickets, or credentials in an untrusted network.
delay A measurable factor that contributes to the response time of a workload (or transaction), for example, connecting to a JDBC database, reading a row from an SQL database, committing a transaction, or calling a user-defined method. Workloads themselves can be delays to other workloads, for example, a servlet invoking an EJB method.
design patterns Written narratives that define a recurring problem, outline a solution, and describe the tradeoffs involved in implementing that solution. In object-oriented programming environments like Java, a design pattern also describes certain objects and object classes to be used when architecting such a solution.
DHCP Dynamic Host Configuration Protocol. A communications protocol that lets network administrators centrally manage the assignment of Internet Protocol (IP) addresses across an organization's network. Without DHCP, each computer’s IP address must be entered manually at each computer and, if computers move to another location in another part of the network, a new IP address must be chosen. DHCP lets a network administrator supervise and distribute IP addresses from a central point and automatically sends a new IP
Glossary 345
address when a computer is plugged into a different network location.
E
EJB Enterprise JavaBean. A component-based application programming interface that implements component architecture for multitier client/server systems written in Java. See also JavaBean and container.
G
garbage collection A facility of the JVM that deallocates and frees up memory lost when objects are created and later destroyed. Garbage collection usually occurs when insufficient heap space is available for allocating new objects, although you can trigger it manually by invoking the System.gc method.Garbage collection can be expensive since it involves identifying all the unreferenced objects, removing them from the heap, and then possibly compacting the heap.
H
heap A memory storage area known as the System Resources Area that stores system information about running applications. The main storage area used for allocating Java classes and object instances, as well as executable code. The allocation of objects on the heap creates a live or active object, which exists as long as the JVM maintains a pointer to it; when all
references to an object cease to exist, it is subject to garbage collection.
HTTP Hypertext Transfer Protocol. A suite of protocols for the Internet that transfer and display hypertext documents.
HTTP sessions Data related to sessions of specific World Wide Web browsers.
I
IIOP Internet Inter-ORB Protocol. A protocol that distributed programs written in different programming languages can use to communicate over the Internet. IIOP, a part of the Common Object Request Broker Architecture (CORBA), is based on the client/server computing model, in which a client program makes requests of a server program that waits to respond to a client's requests. With IIOP, you can write client programs that communicate with your site's existing server programs wherever they are located and without having to understand anything about the server other than the service it performs and its address (called the Interoperable Object Reference, IOR, which comprises the server's port number and IP address).
instrumentation The process of modifying program code so the time it takes the code to run, along with other statistics, can be measured. These modifications insert hooks into these Java methods so that the real time and CPU time spent executing the methods
346 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
can be measured. Instrumentation is key to OMEGAMON XE for WebSphere Application Server’s workload analysis feature.
J
J2C WebSphere Application Server’s implementation of the connection-management and pool-management components of JCA. Applications needing a backend resource reference a connection factory suitable for use with that resource; the connection factory in turn calls WebSphere Application Server’s DB2 Relational Resource Adapter, DB2 RRA (which, despite its name, also supports Oracle, SQL Server, and other database management systems). The DB2 RRA passes the connection request to a J2C connection manager, which tries to provide an available connection from a predefined pool. But when all connections are in use, the J2C connection manager calls back to the DB2 RRA to obtain a new connection from the backend system; once this connection is returned, the connection manager adds it to the connection pool for future reuse.
J2C container The third type of container within WebSphere Application Server (EJB containers and Web containers are the other two types). A J2C container contains connection factories that represent backend resources; it also manages access to these resources via a connection manager associated with each connection factory.
J2EE Java 2 Platform, Enterprise Edition. An environment for developing and deploying multitier enterprise applications. J2EE simplifies development of enterprise applications by basing them on standard, modular components; it comprises a set of services, application programming interfaces (APIs), and protocols that provide the necessary functions for developing multitiered, Web-based applications.
JAR file A Java archive file, which is a ZIP file containing many class files along with their directory structure.
JavaBean The Java implementation of component-based software architecture, which defines how small, tested software entities called components can be integrated to build complete software solutions called containers.
JCA J2EE Connector Architecture. A template for writing your own connectors, which is a binding between a J2EE application server and a backend enterprise information system (EIS) or data repository such as IMS or DB2.
JDBC Java Database Connectivity. An application programming interface (API) for connecting Java programs to the data in a relational database. With this API, you can encode data requests in Structured Query Language (SQL) that JDBC then passes to the database manager for interpretation and processing.
Glossary 347
JMS Java Message Service. A programming interface that connects Java programs to middleware messaging applications, for example, WebSphere MQ.
JMS summary data Data regarding the use of WebSphere MQ by WebSphere Application Server applications.
JMX Java Management Extensions. A standard technology for management and monitoring that defines architecture, application programming interfaces (APIs), and services for application and network management in Java. JMX provides tools for building distributed, Web-based solutions for managing and monitoring Java devices and applications.A JMX agent is an Mbean container.
JNDI Java Naming and Directory Interface. An application programming interface (API) that connects Java applications to naming and directory servers such as LDAP.
JSP Java server page. A Web page that specifies one or more servlets whose execution on the Web server modifies the page’s content or appearance before it is presented to the user.
JTA Java Transaction API. An application programming interface developed by Sun Microsystems that specifies standard Java interfaces between a transaction manager (such as Tuxedo) and other players in a distributed transaction system: the
resource manager, the application server, the transactional applications, and often the database manager as well.
JVM Java virtual machine. A software implementation of a central processing unit (CPU) that runs Java applets and applications. The JVM provides a software execution engine that safely and compatibly executes the byte codes in Java class files on various microprocessors, whether embedded in a computer or in another electronic device.
K
Kerberos A security system from the Massachusetts Institute of Technology that provides security services for networking.
L
LDAP Lightweight Directory Access Protocol. A protocol that uses TCP/IP to access directory databases where applications can store and retrieve common naming and location data. For example, applications can use LDAP to access such information as email addresses, service configuration parameters, and public keys.
lock A semaphore created through the use of the Java synchronized keyword that prevents simultaneous access to a Java object or section of code.
logstream A system logger application that records error information, unexpected conditions, or failure
348 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
detected within WebSphere Application Server code.
longest-running workloads Data related to individual transactions (executions of a workload) that exceed user-defined response-time criteria.
M
MBeans Managed Beans. A set of standard instrumentation methods for use in Java programs and by Java management applications like OMEGAMON XE for WebSphere Application Server that allows monitoring and management of Java-based applications. An Mbean is a JavaBean that represents a JMX-manageable resource.
monitor 1) A transaction environment for maintaining large quantities of data in a consistent state and that controls which users and clients can access data through authorized servers. 2) A programming primitive created so that multiple program threads can share the same resource (such as an object). A program creates a monitor for a given resource by requesting it from the system; the system returns a unique ID for that monitor. After that, any thread needing the resource must use the monitor to lock the resource while the thread is using it. If the monitor is already locked, a thread requesting the resource is queued by the system and then given control when the monitor becomes unlocked. Also called a mutex.
MVC The Model/View/Controller design pattern is based on the separation of an application into three objects: the user interface (“view”), the logical structure of the data the application requires (“model”), and the user commands that change the view or the model (“controller”).
N
node Any managed system, such as a J2EE server, that CandleNet Portal is monitoring. A node can also be a managed system of subnodes, all of which are being managed as components of the primary node.
O
OLT Object Level Trace. A tool for testing distributed applications that includes a graphical trace facility and a remote debugger.
P
PMI Performance Monitoring Infrastructure. The application programming interface (API) that IBM provides for extracting WebSphere Application Server performance data on UNIX and Windows platforms and (as of WebSphere Application Server V5.0.1) OS/390 as well. PMI must be enabled and the appropriate instrumentation levels set for the OMEGAMON XE agent to extract PMI data and populate certain workspaces.Under WebSphere Application Server V5.0, PMI runs as an interface to JMX.
Glossary 349
R
RMI Remote Method Invocation. A Java standard from Sun Microsystems that performs a remote procedure call (RPC) to allow Java objects stored in the network to be accessed remotely in a client/server environment.
RPC Remote Procedure Call. A protocol based on the Open Software Foundation's Distributed Computing Environment (DCE) that allows one program to request services from a program running on another computer in a network. (A procedure call is also known as a function call or a subroutine call.) RPC uses the client/server model: the requesting program is the client, and the responding program is the server. As with a local procedure call, an RPC is a synchronous operation: the requesting program is suspended until the remote procedure returns its results.
S
servlet A Java application that runs in an application server or Web server, and that provides server-side processing.
signature The name of an operation or method and its parameters.
SSL Secure Sockets Layer. A security protocol for communication privacy that provides secure client/server conversations.
struts A widely used framework for developing servlet- or JSP-based Web applications that is distributed as open
source by the Apache Jakarta Project. Struts encourages application architectures based on the Model 2 approach, a variation of the Model/View/Controller (MVC) design paradigm.
T
thread A dispatchable unit of work.
transaction A single execution of a workload.
U
URL Universal Resource Locator. The unique address for a file that is accessible on the Internet. A common way to get to a Web site is to enter the URL of its home page in your Web browser's address line. However, any file within that Web site can also be specified as the URL. Such a file might be any Web (HTML) page other than the home page, an image file, or a program such as a Common Gateway Interface application or Java applet. The URL contains the name of the protocol used to process the file, a domain name that identifies the specific computer on the Internet, and a pathname to the file on that computer.
W
Web container A special J2EE container that manages Web applications in a J2EE architecture. A Web container specifies a runtime
350 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
environment for Web components, including security, concurrency, life-cycle management, transaction, deployment, and other services; it also enables a Web application to access external resources such as relational databases (via JDBC) and Enterprise Java Beans. A Web container provides the same services as a JSP container and provides support for managing Java Server Pages.Every J2EE server contains at least one Web container.
workload The entry point into an application whose processing or response time directly affects the response time the end user perceives. In OMEGAMON XE for WebSphere Application Server, the workload is a servlet, JSP, or EJB method. Sometimes called a transaction. See also delay.
workload analysis A configuration technique for a workload (that is, a transaction) within WebSphere
Application Server that allows you to see how often the workload runs, how much CPU time it consumes, and what factors about the workload degrade its performance. The workload analysis feature collects workload data—aggregate data on each workload that ran, along with detailed information about the delays that contributed to the workload’s response time of the workload. Its primary purpose is to report on workloads running in the application server, how often they run, their response time, and what is causing performance degradation. It account for the time a workload (servlet, JSP, or EJB method) executes by assigning one or more delay factors to the workload.Workload analysis works by dynamic object code instrumentation, which modifies the Java object code for the application’s classes as they are being loaded into the JVM.
Index 351
Index
Aaccessing workspaces 169administrative tasks, performing 13Adobe portable document format 14Agent Events workspace 172All Workloads V2 attribute group 227All Workloads workspace 173Allocation Failure Block Detail attribute
group 231Application Server attribute group 233Application Server Errors attribute
group 237application server for WebSphere
Application Server V4.0, default 220
Application Server Status attribute group 238
Application Server workspace 172Application Trace File workspace 172application tracing feature
collecting data for 143–163configuration file for 117–139Take Action commands for 168
attribute groupsAll Workloads V2 227Allocation Failure Block Detail 231Application Server 233Application Server Errors 237Application Server Status 238associating with table views 167Container Object Pools 239Container Transactions 241CTG Summary 244Current Objects for Selected Class 246Datasources 248DB Connection Pools 250Dynamic Cache 252Dynamic Cache Templates 253
EJB Containers 255Enterprise Java Bean Methods 262Enterprise Java Beans 259Garbage Collection Cycle Detail 265Garbage Collector Activity 263Heap Usage 267historical data collection and 225–307HTTP Sessions 268In-flight Workload Detail 274In-flight Workloads 270J2C Connection Pools 276JMS Summary 278Lock Analysis by Method Detail 280Lock Analysis by Method Summary 282Lock Analysis by Workload 283Lock Analysis by Workload Detail 284Lock Owner for Selected In-flight
Workload 286Longest Running Workloads V2 288Methods Instantiating Selected Class 291References to Objects for Selected
Allocation Source 293Selected Workload Delays 295Servlet Sessions 297Servlets JSPs 299Suspected Memory Leaks 300Thread Pools 301Web Applications 302WebSphere Distributed Product
Events 292Workload Class Instantiations 304Workload Management WLM Client 305Workload Management WLM Server 306
attribute information, viewing 166attributes and reports, relationship
between 167
352 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
BBest Practices sample application 185–224
AIMBP002 sample 186AIMBP004 sample 186AIMBP005 sample 186AIMBP006 sample 187AIMBP011 sample 187, 190, 192AIMBP032 sample 187AIMBP033 sample 187AIMBP036 sample 187AIMBP039 sample 188AIMBP056 sample 188Better String Concatenation sample 186CANDLEBP database for 189, 190, 222,
223CandleDS datasource for 193, 222configuring the OMEGAMON XE agent
for 219database installation 190database requirements 189datasource installation for WAS V4 193datasource installation for WAS V5 195DB2 requirements 189executing 220–221installation for WAS V4 203installation for WAS V5 208installing 39, 189–217Make Read-only Entity Bean Methods
sample 186overview 186–188Release Object references when not
needed sample 188Reuse EJB Home Objects sample 187Tune SQL Statements sample 187uninstalling 222–224Use JDBC Connection Pooling
sample 187Use JDBC PreparedStatements
sample 187Use proper Synchronization sample 188Use Proper Transaction Isolation Level
sample 186
Use Proper useBean Scope sample 187Web interface for 221WebSphere Application Server
requirements 189workload analysis setup for 219
bottlenecks, identifying 166
CCandle Customer Service and
Satisfaction 18Candle Management Server 12, 58Candle Management Workstation 12, 58
benefits 59online tutorial 13
Candle product packages that include the OMEGAMON XE agent 66
Candle Web site 13, 18CandleNet Portal 11, 12
benefits 58browser client 58desktop client 58graphic view 60historical data collection 61Navigator view 60server 58
CICS Transaction Gateway 173Class XML tag
ClassType parameter 131DepthSensitiveInstrumentation
parameter 132DisplayEJBAs parameter 132DisplayServletWorkloadAs parameter 133HeapAnalysis parameter 134IgnoreTrivialMethods parameter 134LockAnalysis parameter 134MaxTrivialMethodInstructions
parameter 129MethodNames parameter 134MethodType parameter 135Name parameter 131parameters 131–135
configuration
Index 353
basics 73–80control file for 117–139
default 85sample 87
parameters 83, 91definitions 91
prerequisites 72product components 78
Configuration Setup Take Action command 156
Container Object Pools attribute group 239Container Transactions attribute group 241CTG Summary attribute group 244CTG Summary workspace 173CTG users
CtgDelaySample.java sample plugin program 140
prerequisite for ECI applications 139Current Objects for Selected Class attribute
group 246
DDatasources attribute group 248Datasources workspace 173DB Connection Pools attribute group 250DB Connection Pools workspace 174Delay XML tag
IncludeChildDelays parameter 138MajorName parameter 137MinorName parameter 137parameters 137–138
Delay_Class XML tagMethods parameter 138Name parameter 138parameters 138
Dynamic Cache attribute group 252Dynamic Cache Templates attribute
group 253Dynamic Cache workspace 174
EEJB Containers attribute group 255
EJB Containers workspace 174Enterprise Java Bean Methods attribute
group 262Enterprise Java Beans attribute group 259environment variables, configuration 84,
112–114$CANDLEHOME$ 114BinPath 112CT_CMSLIST 112CTIRA_HIST_DIR 112CTIRA_LOG_PATH 112KBB_RAS1 113KWE_AGENT_COMPONENT_TRACE 1
13KWE_HEAP_DEBUG 113KWE_INTERNAL_TRACE 113KWE_MSG_PATH 113KWE_PARM_FILE 113KWE_SERVICE_INIT_TIME 113
error messagesSee messages
evaluating tuning decision 166
Ffeatures, new
Version 110 49–54Version 110 programming
enhancements 45–48Version 120 38–44Version 130 21–37
Ggarbage collection
collecting data about 143–163Garbage Collection Cycle Detail attribute
group 265Garbage Collector Activity attribute
group 263Garbage Collector Activity workspace 173
Hheap usage
354 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
collecting data about 143–163Heap Usage attribute group 267Heap Usage workspace 173historical data collection 61, 171
attribute tables for 225–307requirements 171
HTTP Sessions attribute group 268HTTP Sessions workspace 173
Iidentifying system bottlenecks 166In-flight Workload Detail attribute
group 274In-flight Workloads attribute group 270In-flight Workloads workspace 173instrumentation
control file for 117–139instrumentation levels 69, 167
setting dynamically via CandleNet Portal 115
setting to collect performance data 115–116
settings for WAS V4.0 115settings for WAS V5.0 116Take Action commands 115
JJ2C Connection Pools attribute group 276J2EE Connector Connection Pools
workspace 174JMS Summary attribute group 278JMS Summary workspace 174
Kkwe.xml file 83, 85, 178
AgentId parameter 91alternate version of 161, 163AppTraceDirectory parameter 91CollectHeapClasses parameter 103CollectHeapLevel parameter 104CollectHistorical parameter 104
CollectLockAnalysisMinCost parameter 103
CollectorSessionPort parameter 92CollectorSessionSampleInterval
parameter 105CollectWorkloadClassName
parameter 106CollectWorkloadClassType parameter 106CollectWorkloadMaxDepth
parameter 107DefaultCollectHeapClasses parameter 92DefaultCollectHeapLevel parameter 93DefaultCollectHistorical parameter 93DefaultCollectLockAnalysisMinCost
parameter 94DefaultCollectorSessionSampleInterval
parameter 94DefaultCollectWorkloadClassName
parameter 94DefaultCollectWorkloadClassType
parameter 95DefaultCollectWorkloadMaxDepth
parameter 95DefaultExceptionWorkloadMax
parameter 96DefaultExceptionWorkloadMinRespTime
parameter 96DefaultExceptionWorkloadName
parameter 96DefaultExclude parameter 96DefaultGCCollect parameter 97DefaultGCPollFrequency parameter 97DefaultHeapCapturePercent
parameter 97DefaultInflightThreshold parameter 97DefaultLockAnalysisLevel parameter 97DefaultLogScanInterval parameter 98DefaultMinimumSamplingInterval
parameter 98DefaultRetainLogFileEvents parameter 98DefaultStatisticInterval parameter 98DefaultWorkloadCapturePercent
parameter 99
Index 355
DiscoverInterval parameter 99ExceptionWorkloadHistoricalMax
parameter 99ExceptionWorkloadMax parameter 107ExceptionWorkloadMinRespTime
parameter 107ExceptionWorkloadName parameter 108Exclude parameter 108GCCollect parameter 108GCPollFrequency parameter 108HeapCapturePercent parameter 108InflightThreshold parameter 109JavaLogFileName parameter 99LockAnalysisLevel parameter 109LogScanDateFormat parameter 99LogScanInterval parameter 109MaxReferenceSearchTime parameter 100MinimumSamplingInterval
parameter 110Name parameter 110NamingServerPort parameter 100RetainProductEvents parameter 100sample 87SasClientProps parameter 100SasServerProps parameter 101SOAPClientProps parameter 101StatisticInterval parameter 110SubnodeAliasName parameter 110TakeActionAuthUsers parameter 102,
111Version parameter 102WAS V4.0 151, 152, 153, 154WAS V5.0 155WASAppServerRoot parameter 102WorkloadCapturePercent parameter 111
KWEAGENT XML tagAgentId parameter 91AppTraceDirectory parameter 91CollectorSessionPort parameter 92DefaultCollectHeapClasses parameter 92DefaultCollectHeapLevel parameter 93DefaultCollectHistorical parameter 93
DefaultCollectLockAnalysisMinCost parameter 94
DefaultCollectorSessionSampleInterval parameter 94
DefaultCollectWorkloadClassName parameter 94
DefaultCollectWorkloadClassType parameter 95
DefaultCollectWorkloadMaxDepth parameter 95
DefaultExceptionWorkloadMaxType parameter 96
DefaultExceptionWorkloadMinRespTimeType parameter 96
DefaultExceptionWorkloadName parameter 96
DefaultExclude parameter 96DefaultGCCollect parameter 97DefaultGCPollFrequency parameter 97DefaultHeapCapturePercent
parameter 97DefaultInflightThreshold parameter 97DefaultLockAnalysisLevel parameter 97DefaultLogScanInterval parameter 98DefaultMinimumSamplingInterval
parameter 98DefaultRetainLogFileEvents parameter 98DefaultStatisticInterval parameter 98DefaultWorkloadCapturePercent
parameter 99DiscoverInterval parameter 99ExceptionWorkloadHistoricalMax
parameter 99JavaLogFileName parameter 99LogScanDateFormat parameter 99MaxReferenceSearchTime parameter 100NamingServerPort parameter 100parameters 91RetainProductEvents parameter 100SasClientProps parameter 100SasServerProps parameter 101SOAPClientProps parameter 101TakeActionAuthUsers parameter 102,
356 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
178Version parameter 102WASAppServerRoot parameter 102
KWEAPP attribute group 302KWEAPPSRV attribute group 233KWEAPSST attribute group 238KWEASERR attribute group 237KWECACHE attribute group 252KWECACHT attribute group 253KWECONTNR attribute group 255KWEDATAS attribute group 248KWEDBCONP attribute group 250KWEEBOP attribute group 239KWEEJB attribute group 259KWEEJBMTD attribute group 262KWEGC attribute group 263KWEGCAFB attribute group 231KWEGCCYC attribute group 265KWEHTTPS attribute group 268KWEHUDTL attribute group 246KWEHUPML attribute group 300KWEHUSUM attribute group 267KWEIFML attribute group 286KWEIFWDT attribute group 274KWEIFWSM attribute group 270KWEINSTR XML tag
CollectCPUTime parameter 124CollectHTTPSessStats parameter 124CollectInFlightWorkloads parameter 125CollectorSessionPort parameter 125CtgDelayPlugin parameter 125DisplayEJBAs parameter 126DisplayServletWorkloadAs parameter 126GlobalInstrumentation parameter 126HeapAnalysisSystemClasses
parameter 127HeapAnalysisUserClasses parameter 127InternalTrace parameter 127LockAnalysisSystemClasses
parameter 128LockAnalysisUserClasses parameter 128LogFileName parameter 128
MaxClasses parameter 128MaxHTTPSessions parameter 128MeasureHeapDelays parameter 129NumHeapAnalysisClasses parameter 129parameters 124–139ShowInternalWorkloads parameter 129ShowMethodArguments parameter 129SysInstr parameter 130SystemClassLoaderClasses
parameter 130ToStringIsSafeToUse parameter 130UserClassPath parameter 131Version parameter 131
kweiuser.xml file 117, 118, 119, 120, 156, 159, 167
alternate version of 160sample instrumentation files 121WAS V4.0 151, 152, 153, 154WAS V5.0 155
KWEJ2C attribute group 276KWEMCCMS attribute group 282KWEMCDCM attribute group 280KWEMCDWL attribute group 284KWEMCMW attribute group 283KWEMQSAC attribute group 278KWEOBJRF attribute group 293KWEPREV attribute group 292kwescl.jar file
WAS V4.0 151, 152, 154WAS V5.0 155
KWESERVLT attribute group 299KWESERVS attribute group 297kwesmpl.xml file 90KWETGSUM attribute group 244KWETHRDP attribute group 301KWETRANS attribute group 241KWEWHUBM attribute group 291KWEWHUSE attribute group 304KWEWKLDD attribute group 295KWEWKLDS attribute group 227KWEWKLEX attribute group 288KWEWLMCL attribute group 305
Index 357
KWEWLMSR attribute group 306
LLock Analysis by Method Detail attribute
group 280Lock Analysis by Method Summary attribute
group 282Lock Analysis by Workload attribute
group 283Lock Analysis by Workload Detail attribute
group 284Lock Analysis workspace 173Lock Owner for Selected In-flight Workload
attribute group 286Longest Running Workloads V2 attribute
group 288Longest Running Workloads workspace 173
Mmaintenance, applying 80, 148messages
KWE-prefixed 309–328KWEWA-prefixed 329–341OMEGAMON XE for WebSphere
Application Server 309–341Methods Instantiating Selected Class
attribute group 291MonitorAppServer XML tag
CollectHeapClasses parameter 103CollectHeapLevel parameter 104CollectHistorical parameter 104CollectLockAnalysisMinCost
parameter 103CollectorSessionSampleInterval
parameter 105CollectWorkloadClassName
parameter 106CollectWorkloadClassType parameter 106CollectWorkloadMaxDepth
parameter 107ExceptionWorkloadMax parameter 107ExceptionWorkloadMinRespTime
parameter 107ExceptionWorkloadName parameter 108Exclude parameter 108GCCollect parameter 108GCPollFrequency parameter 108HeapCapturePercent parameter 108InflightThreshold parameter 109LockAnalysisLevel parameter 109LogScanInterval parameter 109MinimumSamplingInterval
parameter 110Name parameter 110parameters 103StatisticInterval parameter 110SubnodeAliasName parameter 110TakeActionAuthUsers parameter 111,
178WorkloadCapturePercent parameter 111
monitoringperformance 166setting thresholds for 66
monitoring agents 58, 63
Nnew features
Version 110 49–54Version 110 programming
enhancements 45–48Version 120 38–44Version 130 21–37
OOMEGAMON DE
definition 58, 59OMEGAMON DE Policy Management
definition 58, 60OMEGAMON XE
components 58definition 57–58
OMEGAMON XE for WebSphere Application Server
configuration 81–90
358 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
different agents for 161functions 63–66introduction 165–175maintenance 80, 148messages 309–341overview 55–66
OMEGAMON XE for WebSphere Application Server product package 66
Pparameter file, default configuration 85parameters
sample configuration 87PathWAI Dashboard for WebSphere
Infrastructure product package 66PathWAI Deployment for WebSphere
product package 66PathWAI Monitor for WebSphere Application
Server product package 66PathWAI Performance Analyzer product 38,
40, 61use when instrumenting workloads 118
PathWAI Tuning Workbench for J2EE product package 66
PDF files, adding annotations 15performance
monitoring 166performance data
reporting 115–116setting instrumentation levels for 167
PMI instrumentation levelssetting dynamically via CandleNet
Portal 115setting to collect performance data 115–
116settings for WAS V4.0 115settings for WAS V5.0 116Take Action commands 115
Policy Management, OMEGAMON DE 58, 60
Pool Utilization workspace 173
predefined situations 67–68printing problems 14product maintenance 80, 148product packages that include the
OMEGAMON XE agent 66
RReferences to Objects for Selected Allocation
Source attribute group 293reported data 166
synchronizing 168reports
historical 171relationship between attributes and 167
Ssample application
Best Practices 185–224AIMBP002 sample 186AIMBP004 sample 186AIMBP005 sample 186AIMBP006 sample 187AIMBP011 sample 187, 190, 192AIMBP032 sample 187AIMBP033 sample 187AIMBP036 sample 187AIMBP039 sample 188AIMBP056 sample 188Better String Concatenation
sample 186CANDLEBP database for 189, 190,
222, 223CandleDS datasource for 193, 222configuring the OMEGAMON XE agent
for 219database installation 190database requirements 189datasource installation for WAS V4 193datasource installation for WAS V5 195DB2 requirements 189executing 220–221installation for WAS V4 203installation for WAS V5 208installing 39, 189–217
Index 359
Make Read-only Entity Bean Methods sample 186
overview 186–188Release Object references when not
needed sample 188Reuse EJB Home Objects sample 187Tune SQL Statements sample 187uninstalling 222–224Use JDBC Connection Pooling
sample 187Use JDBC PreparedStatements
sample 187Use proper Synchronization
sample 188Use Proper Transaction Isolation Level
sample 186Use Proper useBean Scope sample 187Web interface for 221WebSphere Application Server
requirements 189workload analysis setup for 219
Selected Workload Delay - History workspace
prerequisite for CTG users 139Selected Workload Delays - Current Interval
workspace 137prerequisite for CTG users 139
Selected Workload Delays attribute group 295
server1 default server for WebSphere Application Server V5.0 220
Servlet Sessions attribute group 297Servlets JSPs attribute group 299SetIL Take Action commands
for instrumentation levels 115setupCandleWAEnabler file 65, 148, 156setupCandleWAEnabler.sh shell script 140situations
available 67–68using Take Action commands with 183
Start Application Tracing Take Action command 168
state changesidentifying 166
Suspected Memory Leaks attribute group 300
Suspected Memory Leaks workspace 173
Ttable views 167
associating with attributes 167Take Action commands 69, 178–183
available commands 179Configuration Setup 156configuring 178designating users 178for instrumentation levels 115prerequisite 178security for 178Start Application Tracing 168use in situations 183
Thread Pools attribute group 301Thread Pools workspace 174threshold values, setting 166tuning decisions 166
UUNIX requirements 79
VVersion 110 changes and
enhancements 49–54Version 110 programming
enhancements 45–48Version 120 changes and
enhancements 38–44Version 130 changes and
enhancements 21–37
WWeb Applications attribute group 302Web Applications workspace 174Web site, Candle 13, 18WebSphere Application Server
command-line settings 159
360 OMEGAMON XE for WebSphere Application Server User’s Guide, V130
configuration changes for 150–158using CandleNet Portal 156–157Version 4.0 cloned application
servers 152Version 4.0 server groups 153Version 4.0 stand-alone application
servers 150Version 5.0 154
support for version 3.5 39, 53support for version 5.0 49versions supported 11, 77
WebSphere Application Server Agent workspace 172
WebSphere Application Server workspace 172
WebSphere Distributed Product Events attribute group 292
workload analysis feature 64, 78class loader script for 148–149collecting data for 143–163
different application servers 159configuration file for 117–139instrumenting 167prerequisite for CTG users 139specifying an alternate agent parameter
file for 163Workload Class Instantiations attribute
group 304Workload Management WLM Client
attribute group 305Workload Management WLM Server
attribute group 306Workload Management workspace 175Workload XML tag
example 137MajorName parameter 136MinorName parameter 136
parameters 136–137Workload_Class XML tag
Methods parameter 137Name parameter 136parameters 136–137
workspacesaccessing 169Agent Events 172All Workloads 173Application Server 172Application Trace File 172available 172–175CTG Summary 173Datasources 173DB Connection Pools 174Dynamic Cache 174EJB Containers 174Garbage Collector Activity 173Heap Usage 173HTTP Sessions 173In-flight Workloads 173J2EE Connector Connection Pools 174JMS Summary 174Lock Analysis 173Longest Running Workloads 173Pool Utilization 173Suspected Memory Leaks 173Thread Pools 174Web Applications 174WebSphere Application Server 172WebSphere Application Server Agent 172Workload Management 175
XXML tags for configuration 91