OMEGAMON XE for WebSphere Application Server,...

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


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


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


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


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


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

https://www.candle.com/www1/techdocs/red.html

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


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.

http://www.adobe.com

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


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


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.

http://www.candle.com

http://www.candle.com

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


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


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


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




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


(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


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




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


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


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


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


� 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




� In the In-flight Workloads attribute group


� In the JMS Summary attribute group

– Manager Name– Name– Type


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


What’s New 29


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:


– DefaultCollectWorkloadMaxDepth (See “KWEAGENT” on page 91 for details.)


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


– CollectInFlightWorkloads (See “Keywords for the KWEINSTR tag” on page 124 for details.)


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



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


What’s New 31


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:


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


– DefaultCollectHistorical (See “KWEAGENT” on page 91 for details.)


– CollectHistorical (See “MonitorAppServer tag” on page 103 for details.)



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 keyword for kweiuser.xml

There is this new attribute keyword for the kweiuser.xml file:


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


– DisplayServletWorkloadAs– DisplayEJBAs

(See “Keywords for the KWEINSTR tag” on page 124 for details.)


– DisplayServletWorkloadAs– DisplayEJBAs

(See “Keywords for the Class tag” on page 131 for details.)



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.


New attribute� The CPU Time attribute of the Selected Workload Delays attribute group


Renamed attribute group� The JVM Garbage Collector Activity attribute group has been renamed

the Garbage Collector Activity attribute group.

What’s New 35


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



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


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


� The Interval Time attribute of the Longest Running Workloads V2 attribute group


Renamed Take Action command� The WAS Set Workload Exception Thresholds command has been

renamed the WAS Set Longest Running Workload Threshold command.


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.




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


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



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


� 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



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


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.



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


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



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


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



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



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



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


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



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


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



� 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


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


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



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



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.



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



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


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



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.


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



� 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



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



� 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


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.



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


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.



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


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.


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.



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



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



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



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.



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.



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



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


Setting instrumentation levels from the WebSphere administrative console forV4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Setting instrumentation levels from the WebSphere administrative console forV5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116


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


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.


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



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.



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.



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="" />



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



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>


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



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.



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.



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



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



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.



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.



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



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



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



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=



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



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



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:


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



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.



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



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



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.


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.


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.



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.


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.



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.


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



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.


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.


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.



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.



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



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



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



the contents of a jar, ear, or war file and select the classes and methods you want instrumented.


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



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.



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>



Figure 7. Default kweiuser_certification.xml Workload Analysis Control File


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>



Figure 8. Default kweiuser_production.xml Workload Analysis Control File


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>



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.



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



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



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.



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.



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.



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



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



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



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



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.



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



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.



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.



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.



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)



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



Example:

CtgDelayPlugin="MyCtgDelayPlugin"UserClassPath="C:/Candle/CMA"



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


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


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



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.



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



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.



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



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.


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.



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.




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.


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


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:




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.


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.




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>


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


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.


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



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





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


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.



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.



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



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


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


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.



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



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


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



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



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



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



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.


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.



Figure 9. Navigator Items for the OMEGAMON XE for WebSphere Application Server V130 Agent


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



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.



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



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



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



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


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


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


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


Command Use


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


Command Use

Introduction


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.


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.



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


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.


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.



Overview


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.




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



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.



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



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.



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.



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>



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.


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.



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>



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



Figure 12. JDBC Providers screen



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.



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



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



Figure 14. databaseName screen

C. Press the Apply button.D. Save both the local and master configuration.The CandleDS datasource is created.



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.


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.



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.



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.



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.



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.



The CandleBP application is installed.

WebSphere Application Server V5 users:


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



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



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.



Figure 20. Installation Options installation step



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.



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.



Figure 22. Map Resource References installation step



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.



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.



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.



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.


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



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.



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



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:


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:


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.



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.



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


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


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


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




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




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


Allocation Failure Block Detail attribute group

Table 8. Allocation Failure Block Detail attribute group (KWEGCAFB)


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


OUT_OF_MEM Heap Status

PID Process ID

SDATE_TIME Sample Date and Time


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)


HDC Parameters:Allocation Failure Block Detail attribute group

(KWEGCAFB)



Recording frequency 1 record per interval fo each allocation failure block


Application Server attribute group

Table 9. Application Server attribute group (KWEAPPSRV)


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


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


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


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




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



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




HDC Parameters:Application Server attribute group (KWEAPPSRV)

Active by default? yes


Recording frequency 1 record per interval per application server


Application Server Errors attribute group

Table 10. Application Server Errors attribute group (KWEASERR)


COMPONENT Component

ERR_MSG Message Text

MSG_ID Message ID

NODE_NAME Node Name


SDATE_TIME Error Date and Time


SEVERITY Severity

THREADID Thread ID

HDC Parameters:Application Server Errors attribute group (KWEASERR)



Recording frequency 1 record for every record written into the application server log file


Application Server Status attribute group

Table 11. Application Server Status attribute group (KWEAPSST)


NODE_NAME Node Name


PID Process ID

SDATE_TIME Date and Time


SRVGRP_NAM Cluster Name

STATUS Status

STDATE_TIM Start Date and Time

TYPE Server Type

HDC Parameters:Application Server Status attribute group (KWEAPSST)



Recording frequency 1 record per server per cycle


Container Object Pools attribute group

Table 12. Container Object Pools attribute group (KWEEBOP)


AVG_DR_SZ Average Number of Objects Discarded

CONT_NAME Container Name

ILTYPE Set Instrumentation Level Type


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


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



SUMMARY Summary of All Containers


HDC Parameters:Container Object Pools attribute group (KWEEBOP)



Recording frequency 1 record per interval per application server, plus 1 record per interval per EJB container


Container Transactions attribute group

Table 13. Container Transactions attribute group (KWETRANS)


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


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



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


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


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




TRANS_IL Transaction Instrumentation Level

Table 13. Container Transactions attribute group (KWETRANS)



HDC Parameters:Container Transactions attribute group (KWETRANS)





CTG Summary attribute group

Table 14. CTG Summary attribute group (KWETGSUM)


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


NODE_NAME Node Name

NUM_ECI Total ECI Requests

NUM_EPI Total EPI Requests

NUM_ESI Total ESI Requests


PID Process ID



TOT_ECTIME Total ECI Time

TOT_EPTIME Total EPI Time

TOT_ESTIME Total ESI Time

TOT_REQ Total Requests

TOT_TIME Total Time


HDC Parameters:CTG Summary attribute group (KWETGSUM)



Recording frequency 1 record per CICS server per cycle


Current Objects for Selected Class attribute group

Table 15. Current Objects for Selected Class attribute group (KWEHUDTL)


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


PID Process ID



SOURCE_NUM Allocation Source Number

TOT_HEAP Estimated Bytes Used

WORK_NM1 Allocating Workload Major Name

WORK_NM2 Allocating Workload Minor Name



HDC Parameters:Current Objects for Selected Class attribute group

(KWEHUDTL)



Recording frequency 1 record per object per cycle


Datasources attribute group

Table 16. Datasources attribute group (KWEDATAS)


AVG_CWAIT Average Connection Wait Time

AVG_QRESP Average Query Processing Time

AVG_URESP Average Update Processing Time

CONN_RATE Connection Rate


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


PID Process ID

PROD_NAME Database Product

PROD_VER Database Product Version

QRY_RATE Query Rate



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


HDC Parameters:Datasources attribute group (KWEDATAS)



Recording frequency 1 record per interval per data source in each application server


DB Connection Pools attribute group

Table 17. DB Connection Pools attribute group (KWEDBCONP)


AVG_WAIT Average Number of Threads Waiting

AVG_WAITTM Average Wait Time

AVG_TIMHLD Average Use Time

DCP_IL Database Connection Pool Instrumentation Level



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


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


RTE_TOW Thread Timeout Rate



SUMMARY Summary of All DB Connections

HDC Parameters:DB Connection Pools attribute group (KWEDBCONP)



Recording frequency 1 record per interval per application server, plus 1 record per interval per datasource

Table 17. DB Connection Pools attribute group (KWEDBCONP)



Dynamic Cache attribute group

Table 18. Dynamic Cache attribute group (KWECACHE)


CACHE_IL Cache Instrumentation Level

CACHE_SIZE Current In-memory Cache Entries



MAX_SIZE Maximum In-memory Cache Entries

NODE_NAME Node Name


PMI_ENABLE PMI Enable

RTE_TTOUT Total In-memory and Disk Timeout Rate



TOTAL_TOUT Total In-memory and Disk Timeouts

HDC Parameters:Dynamic Cache attribute group (KWECACHE)



Recording frequency 1 record per cache per cycle


Dynamic Cache Templates attribute group

Table 19. Dynamic Cache Templates attribute group (KWECACHT)


CACHET_IL Cache Template Instrumentation Level

CACHET_NAM Cache Object Type



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


PCT_USED Percent Used

REF_NUM Row Number

RTE_CREQS Request from Client Rate


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



SUMMARY Summary of Cache Templates

HDC Parameters:Dynamic Cache Templates attribute group (KWECACHT)



Recording frequency 1 record per cache template per cycle

Table 19. Dynamic Cache Templates attribute group (KWECACHT)



EJB Containers attribute group

Table 20. EJB Containers attribute group (KWECONTNR)


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




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


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


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




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







HDC Parameters:EJB Containers attribute group (KWECONTNR)





Enterprise Java Beans attribute group

Table 21. Enterprise Java Beans for attribute group (KWEEJB)


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




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


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


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



Table 21. Enterprise Java Beans for attribute group (KWEEJB)



HDC Parameters:Enterprise Java Beans for attribute group (KWEEJB)



Recording frequency 1 record per interval for each EJB method


Enterprise Java Bean Methods attribute group

Table 22. Enterprise Java Bean Methods attribute group (KWEEJBMTD)


BEAN_NAME Bean Name

BEANM_IL Enterprise Bean Method Instrumentation Level


FULL_NAME Full Method Name



MTHD_NAME Method Name

NODE_NAME Node Name

NUM_CALLS Times the Method Was Called


RT Average Response Time

RTE_CALLS Call Rate



HDC Parameters:Enterprise Java Bean Methods attribute group

(KWEEJBMTD)



Recording frequency 1 record per interval for each EJB method


Garbage Collector Activity attribute group

Table 23. Garbage Collector Activity attribute group (KWEGC)


BYTE_FREE Total Kbytes Freed

GC_RATE Garbage Collection Rate

IN_USE Kbytes in Use

IN_USE_D Kbytes in Use Delta


NODE_NAME Node Name

NUM_FREE Objects Freed

NUM_MOVE Objects Moved

NUM_RUN Times Run

NUMB_FREE Kbytes Free


PID Process ID

REAL_TIME Real Time

REAL_TPCT Real Time Percent




HDC Parameters:Garbage Collector Activity attribute group (KWEGC)



Recording frequency 1 record per interval per application server


Garbage Collection Cycle Detail attribute group

Table 24. Garbage Collection Cycle Detail attribute group (KWEGCCYC)


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)


NODE_NAME Node Name

OBJS_MOVED Objects Moved


PHAN_REFS Phantom Refs

PID Process ID



SOFT_REFS Soft Refs

TIME_COMP Time to Complete

TIME_CPAT Compact Time

TIME_MARK Mark Time


TIME_SWEEP Sweep Time

WEAK_REFS Weak Refs

HDC Parameters:Garbage Collection Cycle Detail attribute group

(KWEGCCYC)



Recording frequency 1 record per garbage-collection cycle per interval

Table 24. Garbage Collection Cycle Detail attribute group (KWEGCCYC)



Heap Usage attribute group

Table 25. Heap Usage attribute group (KWEHUSUM)



COL_LEVEL Collection Level




NODE_NAME Node Name

NUM_ALLOC Allocation Requests

NUM_FREE Objects Deleted




PID Process ID

RTE_FREE Object Deletion Rate

RTE_HEAP Allocation Rate




HDC Parameters:Heap Usage attribute group (KWEHUSUM)



Recording frequency 1 record per heap per class per cycle


HTTP Sessions attribute group

Table 26. HTTP Sessions attribute group (KWEHTTPS)


CDATE_TIME Create Date and 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


PID Process ID



SESS_ID Session ID

USER Creating User

WEB_APP Web Application Name

WORK_NM1 Class Name

WORK_NM2 Method Name



HDC Parameters:HTTP Sessions attribute group (KWEHTTPS)



Recording frequency 1 record per interval for each active HTTP session in each application server


In-flight Workloads attribute group

Table 27. In-flight Workloads attribute group (KWEIFWSM)


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


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




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




I82 Number EJB Local Object Delays

I83 EJB Local Object Delay Time

I84 EJB Local Object Delay Percent


HDC Parameters:In-flight Workloads attribute group (KWEIFWSM)



Recording frequency 1 record per in-flight workload per cycle




In-flight Workload Detail attribute group

Table 28. In-flight Workload Detail attribute group (KWEIFWDT)


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


LAST_METHD Last Completed Method

NODE_NAME Node Name


PID Process ID



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



HDC Parameters:In-flight Workload Detail attribute group (KWEIFWDT)



Recording frequency 1 record per instrumented stack per in-flight workload per cycle


J2C Connection Pools attribute group

Table 29. J2C Connection Pools attribute group (KWEJ2C)


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



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


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


RTE_FREED Managed Connection Return Rate

RTE_TOUT Managed Connection Pool Timeout Rate



SUMMARY Summary of J2C Connections

HDC Parameters:J2C Connection Pools attribute group (KWEJ2C)



Recording frequency 1 record per J2EE connection pool per cycle

Table 29. J2C Connection Pools attribute group (KWEJ2C)



JMS Summary attribute group

Table 30. JMS Summary attribute group (KWEMQSAC)


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


NODE_NAME Node Name

NUM_BROWSE Number of Browse Gets

NUM_GET Number of Gets

NUM_PUT Number of Puts


PID Process ID

PUT_RATE Put Rate

QUEUE_NAME Name

QMGR_NAME Manager Name



TOT_BTIME Total Browse Time

TOT_GTIME Total Get Time

TOT_PTIME Total Put Time

TOT_TIME Total Time

TYPE Type


HDC Parameters:JMS Summary attribute group (KWEMQSAC)



Recording frequency 1 record per interval per MQSeries queue in each application server


Lock Analysis by Method Detail attribute group

Table 31. Lock Analysis by Method Detail attribute group (KWEMCDCM)


AVG_LOC Average Contention Time

CLAS_NAME Class Acquiring Locks


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


PID Process ID



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


HDC Parameters:Lock Analysis by Method Detail attribute group

(KWEMCDCM)



Recording frequency 1 record per method, lock, first workload, and second workload per cycle


Lock Analysis by Method Summary attribute group

Table 32. Lock Analysis by Method Summary attribute group (KWEMCCMS)


AVG_LOC Average Time to Acquire Lock



LOC_TIME Total Time to Acquire Lock

MAX_LOC Maximum Time to Acquire Lock


NODE_NAME Node Name

NUM_LOC Number of Locks Acquired


PID Process ID



HDC Parameters:Lock Analysis by Method Summary attribute group

(KWEMCCMS)



Recording frequency 1 record per method and lock per cycle


Lock Analysis by Workload attribute group

Table 33. Lock Analysis by Workload attribute group (KWEMCMW)


AVG_LOC Average Time to Acquire Lock




LOC_TIME Total Time to Acquire Lock

MAX_LOC Maximum Time to Acquire Lock


NODE_NAME Node Name

NUM_LOC Number of Locks Acquired


PID Process ID

REF_NUM Row Number






HDC Parameters:Lock Analysis by Workload attribute group (KWEMCMW)



Recording frequency 1 record per method, workload, and lock per cycle


Lock Analysis by Workload Detail attribute group

Table 34. Lock Analysis by Workload Detail attribute group (KWEMCDWL)


AVG_LOC Average Contention Time

CLAS_NAME1 First Contending Class Name

CLAS_NAME2 Second Contending Class Name



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


PID Process ID







HDC Parameters:Lock Analysis by Workload Detail attribute group

(KWEMCDWL)



Recording frequency 1 record per workload, lock, first workload, and second workload per cycle


Lock Owner for Selected In-flight Workload attribute group

Table 35. Lock Owner for Selected In-flight Workload attribute group (KWEIFML)


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



HDC Parameters:Lock Owner for Selected In-flight Workload attribute group

(KWEIFML)



Recording frequency 1 record per lock, waiting workload, and owner workload per cycle


Longest Running Workloads V2 attribute group

Table 36. Longest Running Workloads V2 attribute group (KWEWLEX2)


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


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




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


PID Process ID





HDC Parameters:Longest Running Workloads V2 attribute group

(KWEWLEX2)



Recording frequency 1 record per interval for each exceptional workload in each application server




Methods Instantiating Selected Class attribute group

Table 37. Methods Instantiating Selected Class attribute group (KWEWHUBM)






PID Process ID


NODE_NAME Node Name









HDC Parameters:Methods Instantiating Selected Class attribute group

(KWEWHUBM)



Recording frequency 1 record per workload per cycle


WebSphere Distributed Product Events attribute group

Table 38. WebSphere Distributed Product Events attribute group (KWEPREV)


MSG_DESC Message Description

MSG_ID Message ID

NODE_NAME Node Name


SDATE_TIME Event Date and Time

SEVERITY Severity

HDC Parameters:WebSphere Distributed Product Events attribute group

(KWEPREV)



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


References to Objects for Selected Allocation Source attribute group

Table 39. References to Objects for Selected Allocation Source attribute group (KWEOBJRF)


NODE_NAME Node Name

LINE_NUM Referenced Object Allocating Source Line


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


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




HDC Parameters:References to Objects for Selected Allocation Source

attribute group (KWEOBJRF)



Recording frequency 1 record per object per cycle

Table 39. References to Objects for Selected Allocation Source attribute group (KWEOBJRF)



Selected Workload Delays attribute group

Table 40. Selected Workload Delays attribute group (KWEWKLDD)


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


MAX_TIME Max Time

NODE_NAME Node Name

NUM_ALLOC Total Number of Heap Alloc

NUM_OCCUR Number of Occurrences


PCT_TIME Delay Percent

PID Process ID



TOTAL_TIME Total Time





HDC Parameters:Selected Workload Delays attribute group (KWEWKLDD)



Recording frequency 1 record per interval for each workload degradation in each application server


Servlet Sessions attribute group

Table 41. Servlet Sessions attribute group (KWESERVS)


AVG_ACTSES Average Concurrently Active Sessions

AVG_LIVSES Average Concurrently Live Sessions

AVG_SESS Average Serializable Session Object Size

AVG_SLIFET Average Session Lifetime



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


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


RTE_SINVAL Session Invalidation Rate



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)



Recording frequency 1 record per servlet session

Table 41. Servlet Sessions attribute group (KWESERVS)



Servlets JSPs attribute group

Table 42. Servlets JSPs attribute group (KWESERVLT)


APPL_NAME Web Application Name

AVG_CREQ Average Number of Concurrent Requests

AVG_RT Average Servlet Response 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


RTE_ERRORS Servlet Error Rate



SERVE_IL Servlet/JSP Instrumentation Level


SVLT_NAME Servlet/JSP Name

SVLT_TYPE Type

VHOST_NAME Virtual Host Name

HDC Parameters:Servlets JSPs attribute group (KWESERVLT)



Recording frequency 1 record per interval per servlet


Suspected Memory Leaks attribute group

Table 43. Suspected Memory Leaks attribute group (KWEHUPML)





GROW_PCT Growth Percent




NODE_NAME Node Name



PID Process ID



SOURCE_NUM Allocation Source


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)



Recording frequency 1 recrd per suspected memory leak per cycle


Thread Pools attribute group

Table 44. Thread Pools attribute group (KWETHRDP)


AVG_INACT Average Free Threads



MAX_SIZE Configured Maximum Number of Threads

NODE_NAME Node Name

NUM_ACTTHR Average Active Threads

NUM_CREATE Threads Created

NUM_DESTRY Threads Destroyed


PCT_TIMMAX All Threads in Use Percent

POOL_SIZE Average Threads

RTE_CREATE Thread Creation Rate

RTE_DESTRY Thread Destruction Rate



SUMMARY Summary of Thread Pools

THRDP_IL Thread Pools Instrumentation Level

THRDP_NAME Thread Pool Name

HDC Parameters:Thread Pools attribute group (KWETHRDP)



Recording frequency 1 record per thread pool


Web Applications attribute group

Table 45. Web Applications attribute group (KWEAPP)


APPL_NAME Web Application Name

AVG_CREQ Average Number of Concurrent Requests

AVG_RT Average Servlet Response Time



NODE_NAME Node Name

NUM_ERRORS Errors

NUM_RELOAD Reloaded Servlets

NUM_REQ Total Requests

NUM_SVRLT Loaded Servlets


RTE_ERRORS Servlet Exception Rate




SUMMARY Summary of All Applications

VHOST_NAME Virtual Host Name

WEB_IL Web Application Instrumentation Level

WEBSUB_IL Web Application Subinstrumentation Level


HDC Parameters:Web Applications attribute group (KWEAPP)



Recording frequency 1 record per interval per Web application


Workload Class Instantiations attribute group

Table 46. Workload Class Instantiations attribute group (KWEWHUSE)




NODE_NAME Node Name



PID Process ID




WORK_FULL Workload Full Name




HDC Parameters:Workload Class Instantiations attribute group

(KWEWHUSE)



Recording frequency 1 record per workload class


Workload Management WLM Client attribute group

Table 47. Workload Management WLM Client attribute group (KWEWLMCL)


C_RSPTIME Client Response Time



NODE_NAME Node Name

NUM_CCUPDT Client Cluster Updates

NUM_OUTREQ Outgoing Requests


RTE_CCUPDT Client Cluster Update Rate

RTE_OUTREQ Outgoing Request Rate



WLMC_IL WLM Instrumentation Level

HDC Parameters:Workload Management WLM Client attribute group

(KWEWLMCL)



Recording frequency 1 record per WLM client


Workload Management WLM Server attribute group

Table 48. Workload Management WLM Server attribute group (KWEWLMSR)




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


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



SRV_WEIGHT WLM Server Weight

WLMS_IL WLM Instrumentation Level


HDC Parameters:Workload Management WLM Server attribute group

(KWEWLMSR)



Recording frequency 1 record per WLM server


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


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.


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.


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.


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.


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.


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.


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.


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


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.


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.


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.


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.


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,


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.


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.


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.


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


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.


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.


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.


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.


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.


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.


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.


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.


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,


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.


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.


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.


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.


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.


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.


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


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


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


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


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


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


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,


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


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


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

Date post:	14-Aug-2020
Category:	Documents
Upload:	others
View:	9 times
Download:	0 times

OMEGAMON XE for WebSphere Application Server,...

Documents