User s Guide. OMEGAMON XE for WebSphere Application Server. Version 130 GC August 2004

Transcription

1 User s Guide OMEGAMON XE for WebSphere Application Server Version 130 GC August 2004 Candle Corporation 100 North Sepulveda Blvd. El Segundo, California 90245

2 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. 2 OMEGAMON XE for WebSphere Application Server User s Guide, V130

3 Contents Contents Figures Tables Preface About This Book Adobe Portable Document Format Documentation Conventions Candle Customer Service and Satisfaction What s New New Features in Version New Features in Version New Features in the Programming Enhancements to Version New Features in Version Chapter 1. Overview of the OMEGAMON XE for WebSphere Application Server Product OMEGAMON XE for WebSphere Application Server Operating Environment Introducing OMEGAMON XE for WebSphere Application Server Situations for OMEGAMON XE for WebSphere Application Server.. 67 Take Action Commands Chapter 2. An Introduction to Configuration Introduction Configuration Basics About Your Agent Contents 3

4 Chapter 3. Chapter 4. Chapter 5. Chapter 6. Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels Getting Started A Look Inside Your Agent s Configuration Files Your Agent s Configuration Parameters and XML Tags Using Your Agent s Environment Variables Setting Instrumentation Levels to Collect PMI Data Preparing the Instrumentation Control File for Workloads and Application Traces Instrumentation Basics about Workloads and Tracing Inside the User Instrumentation Control File Collecting Workload Analysis, Application Trace, and Heap Data Workload Analysis, Application Traces, and Instrumentation Launching the Class Loader Script for Workload Analysis Changing the WebSphere Application Server Configuration Collecting Specific Workload Analysis Data for Different Application Servers Creating Specific Agent Control Files for Different Agents Introducing OMEGAMON XE for WebSphere Application Server Information OMEGAMON XE for WebSphere Application Server Data Accessing the OMEGAMON XE for WebSphere Application Server Information Historical Reporting OMEGAMON XE for WebSphere Application Server Workspaces Chapter 7. The CandleNet Portal Take Action Commands Introduction Using Take Action Commands in Situations Appendix A. A Sample WebSphere Application Server Application: Best Practices Overview Installing the Best Practices Samples OMEGAMON XE for WebSphere Application Server User s Guide, V130

5 Performing the installation Configuring OMEGAMON XE for WebSphere Application Server for the Best Practices Samples Executing the Best Practices Samples Uninstalling the Best Practices Samples Appendix B. Historical Reference Information for Attributes Appendix C. OMEGAMON XE for WebSphere Application Server Messages Glossary Index Contents 5

6 6 OMEGAMON XE for WebSphere Application Server User s Guide, V130

7 Figures Figure 1. Product Components for OMEGAMON XE for WebSphere Application Server V Figure 2. Product Components for OMEGAMON XE for WebSphere Application Server V5 Base Deployment Configuration Figure 3. Product Components for OMEGAMON XE for WebSphere Application Server V5 Network Deployment Configuration Figure 4. Sample Default Parameters in kwe.xml Figure 5. Expanded Configuration Parameters in kwesmpl.xml Figure 6. Sample kweiuser_development.xml Workload Analysis Control File 121 Figure 7. Default kweiuser_certification.xml Workload Analysis Control File Figure 8. Default kweiuser_production.xml Workload Analysis Control File Figure 9. Navigator Items for the OMEGAMON XE for WebSphere Application Server V130 Agent Figure 10. Data Source Properties window Figure 11. J2C Authentication Data Entries panel Figure 12. JDBC Providers screen Figure 13. Datasource parameters screen Figure 14. databasename screen Figure 15. Install Enterprise Application Wizard Figure 16. Selecting Application Servers screen Figure 17. Server or Server Group window Figure 18. Completing the Application Installation Wizard screen Figure 19. Preparing for the application installation screen Figure 20. Installation Options installation step Figure 21. Provide Default Datasource Mapping installation step Figure 22. Map Resource References installation step Figure 23. Map Virtual Hosts installation step Figure 24. Map Modules to Application Servers installation step Figures 7

8 8 OMEGAMON XE for WebSphere Application Server User s Guide, V130

9 Tables Table 1. Symbols in Command Syntax Table 2. New Attribute Groups in Version Table 3. Predefined Situations for the OMEGAMON XE Agent Table 4. Configuration Setup Take Action Command: Edit Argument Values Window Table 5. Take Action Commands for the OMEGAMON XE Agent Table 6. Candle s Best Practices Source Fragments for Java Programming Table 7. All Workloads V2 attribute group (KWEWLDS2) Table 8. Allocation Failure Block Detail attribute group (KWEGCAFB) Table 9. Application Server attribute group (KWEAPPSRV) Table 10. Application Server Errors attribute group (KWEASERR) Table 11. Application Server Status attribute group (KWEAPSST) Table 12. Container Object Pools attribute group (KWEEBOP) Table 13. Container Transactions attribute group (KWETRANS) Table 14. CTG Summary attribute group (KWETGSUM) Table 15. Current Objects for Selected Class attribute group (KWEHUDTL) Table 16. Datasources attribute group (KWEDATAS) Table 17. DB Connection Pools attribute group (KWEDBCONP) Table 18. Dynamic Cache attribute group (KWECACHE) Table 19. Dynamic Cache Templates attribute group (KWECACHT) Table 20. EJB Containers attribute group (KWECONTNR) Table 21. Enterprise Java Beans for attribute group (KWEEJB) Table 22. Enterprise Java Bean Methods attribute group (KWEEJBMTD) Table 23. Garbage Collector Activity attribute group (KWEGC) Table 24. Garbage Collection Cycle Detail attribute group (KWEGCCYC) Table 25. Heap Usage attribute group (KWEHUSUM) Table 26. HTTP Sessions attribute group (KWEHTTPS) Table 27. In-flight Workloads attribute group (KWEIFWSM) Table 28. In-flight Workload Detail attribute group (KWEIFWDT) Table 29. J2C Connection Pools attribute group (KWEJ2C) Table 30. JMS Summary attribute group (KWEMQSAC) Tables 9

10 Table 31. Lock Analysis by Method Detail attribute group (KWEMCDCM) Table 32. Lock Analysis by Method Summary attribute group (KWEMCCMS) 282 Table 33. Lock Analysis by Workload attribute group (KWEMCMW) Table 34. Lock Analysis by Workload Detail attribute group (KWEMCDWL) Table 35. Lock Owner for Selected In-flight Workload attribute group (KWEIFML) Table 36. Longest Running Workloads V2 attribute group (KWEWLEX2) Table 37. Methods Instantiating Selected Class attribute group (KWEWHUBM)291 Table 38. WebSphere Distributed Product Events attribute group (KWEPREV) 292 Table 39. References to Objects for Selected Allocation Source attribute group (KWEOBJRF) Table 40. Selected Workload Delays attribute group (KWEWKLDD) Table 41. Servlet Sessions attribute group (KWESERVS) Table 42. Servlets JSPs attribute group (KWESERVLT) Table 43. Suspected Memory Leaks attribute group (KWEHUPML) Table 44. Thread Pools attribute group (KWETHRDP) Table 45. Web Applications attribute group (KWEAPP) Table 46. Workload Class Instantiations attribute group (KWEWHUSE) Table 47. Workload Management WLM Client attribute group (KWEWLMCL) 305 Table 48. Workload Management WLM Server attribute group (KWEWLMSR) OMEGAMON XE for WebSphere Application Server User s Guide, V130

11 P 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. Preface 11

12 About This Book About This Book Who should read this book This 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. 12 OMEGAMON XE for WebSphere Application Server User s Guide, V130

13 About This Book Becoming oriented If 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 information For 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 online help provided with this and the other related products Preface 13

14 Adobe Portable Document Format Adobe Portable Document Format Printing this book Candle 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 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. 14 OMEGAMON XE for WebSphere Application Server User s Guide, V130

15 Adobe Portable Document Format Contacting Adobe If 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 Adding annotations to PDF files If 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. Preface 15

16 Documentation Conventions Documentation Conventions Introduction Candle documentation adheres to accepted typographical conventions for command syntax. Conventions specific to Candle documentation are discussed in the following sections. Panels and figures The panels and figures in this document are representations. Actual product panels may differ. Required blanks The slashed-b ( ) character in examples represents a required blank. The following example illustrates the location of two required blanks. Revision bars eba*servicemonitor Revision bars ( ) may appear in the left margin to identify new or updated material. Variables and literals in command syntax examples In 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. 16 OMEGAMON XE for WebSphere Application Server User s Guide, V130

17 Documentation Conventions Symbols The 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 NO In 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. Preface 17

18 Candle Customer Service and Satisfaction Candle Customer Service and Satisfaction Background To 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 for detailed customer service information. Candle Customer Service and Satisfaction contacts You will find the most current information about how to contact Candle CSS by telephone or on the Candle Web site. Go to the support section, and choose the link to Support Contacts to locate your regional support center. 18 OMEGAMON XE for WebSphere Application Server User s Guide, V130

19 W What s New Introduction This 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 Support for new PMI Modules Lock analysis Support for WebSphere Portal Server J2EE 1.3 Workload Delays Workload Analysis performance improvements Multiple sample kweiuser.xml files Alteration of the procedures for changing the WebSphere Application Server configuration Global flag to disable instrumentation Selective Historical Reporting Application server discovery adjustments Dynamic refresh instrumentation Determination of the total size of HTTP Session objects Workload Reporting by URL Other enhancements What s New 19

20 New Features in Version PathWAI Performance Analyzer product simplifies trace analysis and workload instrumentation Analysis of classes heap allocations Identification of memory leaks Support for in-flight workloads Support for user-defined delays Support for CTG workloads as a delay type Support for JCA workloads as a delay type New Features in the Programming Enhancements to Version Enhanced garbage-collection statistics Support for user-defined workloads Support deleted for the JVM profiler and its reports New Features in Version Support for WebSphere Application Server V Workload analysis Application tracing for specific workloads New Take Action commands Configuration changes Additional attribute groups Additional workspaces The Best Practices samples Changes in Version New chapters and appendixes OMEGAMON XE for WebSphere Application Server User s Guide, V130

21 New Features in Version 130 New Features in Version 130 Support for new PMI Modules OMEGAMON XE for WebSphere Application Server supports some of the new PMI modules that are featured in IBM WebSphere Application Server V5. New workspaces Servlet Sessions Servlet Sessions for Selected Web Application J2EE Connector Connection Pools Thread Pools Dynamic Cache Workload Management Pool Utilization (See the online help for details.) New attribute groups Dynamic Cache Dynamic Cache Templates J2EE Connector Connection Pools Servlet Sessions Workload Management Server Workload Management Client Thread Pools (See the online help for details.) New Take Action commands WAS SetIL - Dynamic Cache WAS SetIL - J2C Pool WAS SetIL - ORB WAS SetIL - Servlet Sessions WAS SetIL - Workload Management Client WAS SetIL - Workload Management Server (See the online help for details.) What s New 21

22 New Features in Version 130 Lock analysis This 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 22 OMEGAMON XE for WebSphere Application Server User s Guide, V130

23 New Features in Version 130 (See MonitorAppServer tag on page 103 for details.) New keywords in kweiuser.xml Before Lock analysis data can be collected, the Workload Analysis component must instrument the appropriate byte code. This is done by adding these new attribute keywords to the kweiuser.xml file: At the KWEINSTR level: LockAnalysisSystemClasses LockAnalysisUserClasses (See Keywords for the KWEINSTR tag on page 124 for details.) At the Class level: LockAnalysis (See Keywords for the Class tag on page 131 for details.) New workspaces Lock Analysis Lock Owner for Selected Inflight Workload Lock Analysis for Selected Workload - Current Interval Lock Analysis for Selected Method - Current Interval Lock Contention for Selected Workload - Current Interval Lock Contention for Selected Method - Current Interval (See the online help for details.) New attribute groups Lock Analysis by Method Detail Lock Analysis by Method Summary Lock Analysis by Workload Lock Analysis by Workload Detail Lock Owner for Selected In-flight Workload (See the online help for details.) What s New 23

24 New Features in Version 130 New attributes for existing attribute groups In All Workloads V2 attribute group Lock Wait Percent Number of Locks Acquired In-flight Workloads attribute group Lock Wait Time (See the online help for details.) New Take Action command WAS Set Lock Analysis Level see the online help for details. Changes to existing Take Action commands WAS Start Application Tracing see the online help for details. Support for WebSphere Portal Server With 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. 24 OMEGAMON XE for WebSphere Application Server User s Guide, V130

25 New Features in Version 130 Portlet as a workload type In OMEGAMON XE for WebSphere Application Server, the concept of a workload has now been expanded to include portlets, so you can identify portlet invocations wherever you are monitoring workloads. Portlets have been added as a separate workload type in these attribute groups: Application Trace File Current Objects for Selected Class Suspected Memory Leaks (Allocating Workload Type) In-flight Workload Detail In-flight Workloads References to Objects for Selected Allocation Source (Referenced Object Allocating Workload Type) Methods Instantiating Selected Class Workload Class Instantiations Selected Workload Delays All Workloads V2 Longest Running Workloads (See the online help for details.) Portlet as a delay type In OMEGAMON XE for WebSphere Application Server, the concept of a delay has now been expanded to include portlets, so you can identify portlet invocations wherever you are monitoring delays. In other words, portlets can now be defined as separate workloads. Portlets have been added as a separate delay type in this attribute group: Selected Workload Delays (See the online help for details.) Updated Take Action commands These Take Action commands are now able to enter and filter Portlet as a valid type: WAS Dynamic Workload Analysis (See the online help for details.) WAS Start Application Tracing (See the online help for details.) What s New 25

26 New Features in Version 130 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 Delays J2EE 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 26 OMEGAMON XE for WebSphere Application Server User s Guide, V130

27 New Features in Version 130 JMS Publish/Subscribe Support CLASSTYPE_JMS_TOPIC CLASSTYPE_JMS_TOPICCONNECTION CLASSTYPE_JMS_TOPICCONNECTIONFACTORY CLASSTYPE_JMS_TOPICPUBLISHER CLASSTYPE_JMS_TOPICSUBSCRIBER CLASSTYPE_JMS_TOPICSESSION (See ClassTypeDef on page 124 for details.) Changed workspaces These existing workspaces have changed due to added EJB local object delay support or added JMS publish/subscribe delay support: All Workloads (new delay types for the 10 Worst Average Response Times bar chart) Selected Workloads (new delay types for the Selected Workload Average Response Time pie chart) New attributes for existing attribute groups In the All Workloads V2 attribute group EJB Local Home Delay Percent EJB Local Home Delay Time EJB Local Object Delay Percent EJB Local Object Delay Time\ Number EJB Local Home Delays Number EJB Local Object Delays In the Longest Running Workloads V2 attribute group EJB Local Home Delay Percent EJB Local Home Delay Time EJB Local Object Delay Percent EJB Local Object Delay Time\ Number EJB Local Home Delays Number EJB Local Object Delays What s New 27

28 New Features in Version 130 In the In-flight Workloads attribute group EJB Local Home Delay Percent EJB Local Home Delay Time EJB Local Object Delay Percent EJB Local Object Delay Time\ Number EJB Local Home Delays Number EJB Local Object Delays In the JMS Summary attribute group Manager Name Name Type (See the online help for details.) New parameters for the Delay Type attribute in the Selected Workload Delays attribute group Create JMS Create JMS Publisher EJB Local Home Create Call EJB Local Home Find Call EJB Local Home Remove Call EJB Local Object Business Method Call JMS on Message JMS Publish Message Subscriber (See the online help for details.) 28 OMEGAMON XE for WebSphere Application Server User s Guide, V130

29 New Features in Version 130 Workload Analysis performance improvements Various performance improvements have been implemented within Workload Analysis in Version 130. These enhancements offer you more control and flexibility in the instrumentation and data collection process, so you can better tune the product and balance the tradeoff between performance and quantity of data collected. New keywords for kwe.xml There are these new attribute keywords for the XML control files: At the KWEAGENT level: DefaultCollectWorkloadMaxDepth (See KWEAGENT on page 91 for details.) At the MonitorAppServer level: CollectWorkloadMaxDepth (See MonitorAppServer tag on page 103 for details.) New keywords for kweiuser.xml There are these new attribute keywords for the kweiuser.xml file: At the KWEINSTR level: CollectInFlightWorkloads (See Keywords for the KWEINSTR tag on page 124 for details.) At the Class level: DepthSensitiveInstrumentation (See Keywords for the Class tag on page 131 for details.) Updated Take Action command There is a new parameter to the WAS Dynamic Workload Analysis Take Action command: MaxDepth (See the online help for details.) What s New 29

30 New Features in Version 130 Multiple sample kweiuser.xml files With this enhancement, the product includes 3 different sample kweiuser.xml files. They provide various levels of instrumentation that fulfill the most common performance requirements. You can use an unaltered version of one of these new sample kweiuser.xml files, customize one of them, or ignore them and create your own. (See Sample kweiuser.xml instrumentation control files on page 120 for details.) Alteration of the procedures for changing the WebSphere Application Server configuration Some of the functions of the kweinstr.xml file have been assumed by the kweiuser.xml file so that you will never need to make copies of the kweinstr.xml file to configure instrumentation for multiple application servers with different performance requirements. Changes to functioning of control files kweiuser.xml replaces kweinstr.xml as the main instrumentation control file. A new java property, com.candle.kwe.instrument.user_control_file, replaces com.candle.kwe.instrument.control_file. (See Changing the WebSphere Application Server Configuration on page 150 for details.) Updated Take Action command There is a new parameter to the WAS Configuration Setup Take Action command: File (See the online help for details.) 30 OMEGAMON XE for WebSphere Application Server User s Guide, V130

31 New Features in Version 130 Global flag to disable instrumentation This enhancement introduces a new global attribute in the instrumentation control file which can be used to disable all instrumentation, regardless of the settings in the individual class tags. This feature is useful when you are only interested in using Workload Analysis to monitor (as a primary example) Garbage Collection and have no desire to instrument either WebSphere or application classes. This attribute allows you to disable all instrumentation merely by changing one parameter in the kweiuser.xml file. New keyword for kweiuser.xml There is this new attribute keyword for the kweiuser.xml file: At the KWEINSTR level: GlobalInstrumentation (See Keywords for the KWEINSTR tag on page 124 for details.) Selective Historical Reporting With this enhancement, you can indicate in the agent s configuration file whether or not historical data will be collected for a particular application server. The attribute which indicates this can be set either at the global level, or at the individual server level. The user can specify which groups of data should be, and should not be, collected for historical purposes. New keywords in XML control files Selective historical reporting gets enabled by adding these new attribute keywords in the XML control files: At the KWEAGENT level: DefaultCollectHistorical (See KWEAGENT on page 91 for details.) At the MonitorAppServer level: CollectHistorical (See MonitorAppServer tag on page 103 for details.) What s New 31

32 New Features in Version 130 Application server discovery adjustments To 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 instrumentation This 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 objects With 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 32 OMEGAMON XE for WebSphere Application Server User s Guide, V130

33 New Features in Version 130 (See the online help for details.) New keyword for kweiuser.xml There is this new attribute keyword for the kweiuser.xml file: At the KWEINSTR level: CollectHTTPSessStats see Keywords for the KWEINSTR tag on page 124 for details Workload Reporting by URL With this enhancement, you have an option of using a portion of a URL name, instead of a servlet class name, as a workload major name. This allows you to break workloads into more meaningful categories. Also, this enhancement provides an option for including the qualifying EAR and/or JAR file name for an EJB, whenever that EJB is displayed as a workload and/or delay major name within the product. New keywords in kweiuser.xml These new attribute keywords have been added to the kweiuser.xml file: At the KWEINSTR level: DisplayServletWorkloadAs DisplayEJBAs (See Keywords for the KWEINSTR tag on page 124 for details.) At the Class level: DisplayServletWorkloadAs DisplayEJBAs (See Keywords for the Class tag on page 131 for details.) What s New 33

34 New Features in Version 130 Other enhancements New navigation The existing workspaces were reorganized to both shorten the list of available OMEGAMON XE for WebSphere Application Server workspaces and to make the workspace order more logical. New workspaces Servlets/JSPs for Selected Web Application Enterprise Java Bean Methods for Selected Bean Renamed workspaces The Product Events workspace has been renamed Agent Events workspace. The JVM Garbage Collector Activity workspace has been renamed Garbage Collector Activity workspace. The Web Applications History workspace has been renamed Selected Web Application History workspace. The DB Connection Pools History workspace has been renamed Selected DB Connection Pool - History workspace. (See the online help for details.) New attribute The CPU Time attribute of the Selected Workload Delays attribute group (See the online help for details.) Renamed attribute group The JVM Garbage Collector Activity attribute group has been renamed the Garbage Collector Activity attribute group. 34 OMEGAMON XE for WebSphere Application Server User s Guide, V130

35 New Features in Version 130 Renamed attributes In the Web Applications attribute group: Application Name attribute renamed Web Application Name Web Application Instrumentation Level attribute renamed Instrumentation Level Web Application Subinstrumentation Level attribute renamed Subinstrumentation Level In the Application Server attribute group: Session Manager Instrumentation Level attribute renamed Instrumentation Level OTP Instrumentation Level attribute renamed ORB Thread Pool Instrumentation Level Java Virtual Machine Instrumentation Level attribute renamed JVM Instrumentation Level In the DB Connection Pools attribute group: Database Connection Pool Instrumentation Level attribute renamed Instrumentation Level Summary of All DB Connections attribute renamed Summary of All Database Connections In the Servlets JSPs attribute group: Servlet/JSP Instrumentation Level attribute renamed Instrumentation Level Application Name attribute renamed Web Application Name Java Virtual Machine Instrumentation Level attribute renamed JVM Instrumentation Level In the Garbage Collection Cycle Detail attribute group: GC Date and Time attribute renamed Garbage Collection Date and Time Kbytes Free at Start of GC attribute renamed Kbytes Free at Start of Garbage Collection What s New 35

36 New Features in Version 130 The Date and Time attribute of the Application Server Status attribute group has been renamed Sample Date and Time. The EJB Container Instrumentation Level attribute of the EJB Containers attribute group has been renamed Instrumentation Level. The Enterprise Bean Instrumentation Level attribute of the Enterprise Java Beans attribute group has been renamed Instrumentation Level. The Enterprise Bean Method Instrumentation Level attribute of the Enterprise Java Bean Methods attribute group has been renamed Instrumentation Level. The Transaction Instrumentation Level attribute of the Container Transactions attribute group has been renamed Instrumentation Level. The Kbytes Free at Start of GC attribute of the Allocation Failure Block Detail attribute group has been renamed Kbytes Free at Start of Garbage Collection. The Row Number attribute of the References to Objects for Selected Allocation Source attribute group has been renamed Allocation Source. The Allocation Source Number attribute of the Suspected Memory Leaks attribute group has been renamed Allocation Source. (See the online help for details.) Obsolete and removed attributes The Number of Containers attribute of the Application Server attribute group From the JMS Summary attribute group: Queue Manager Name Queue Name Topic Manager Name Topic Name From the All Workloads V2 attribute group: Process ID Workload Full Name 36 OMEGAMON XE for WebSphere Application Server User s Guide, V130

37 New Features in Version 130 The Interval Time attribute of the Longest Running Workloads V2 attribute group (See the online help for details.) Renamed Take Action command The WAS Set Workload Exception Thresholds command has been renamed the WAS Set Longest Running Workload Threshold command. (See the online help for details.) Revised Documentation In prior releases, the documentation for workspaces and the Take Action commands was split between the user s guide and the online helps, with much information duplicated between the two. As of Version 130, all workspace and Take Action information has been coalesced in the online helps, for more immediate access. What s New 37

38 New Features in Version 120 New Features in Version 120 The Version 120 enhancements include: Among its other capabilities, Candle s new PathWAI Performance Analyzer product allows you to: 1. Create or update the kweiuser.xml file to specify the classes and methods to be instrumented for workload analysis. 2. Analyze application trace data. This new capability obviates the previous Application Trace workspace (but not the Application Trace Files workspace). The JVMProfilingPort parameter in the kwe.xml file has been renamed CollectorSessionPort; this reflects the fact that support for the JVM profiler was deleted as part of the programming enhancements for Version 110 (see Support deleted for the JVM profiler and its reports on page 48). For the same reason, the DefaultJVMProfilerSampleInterval and JVMProfilerSampleInterval parameters have been renamed DefaultCollectorSessionSampleInterval and CollectorSessionSampleInterval. Note, however, that the original names (JVMProfilingPort, DefaultJVMProfilerSampleInterval, and JVMProfilerSampleInterval) are still supported. Extensive analysis of classes heap allocations has been added to the workload analysis feature. New workspaces assist you in isolating memory leaks in your WebSphere Application Server applications. Support for in-flight workloads (those that are in the process of running) in the workload analysis feature. Previously, only workloads that have run to completion were reported on. Support for user-defined workloads has been extended to report your site s own user-defined delays as well. Support for CICS Transaction Gateway (CTG) workloads as a delay type. Support for J2EE Connector Architecture (JCA) workloads as a delay type. 38 OMEGAMON XE for WebSphere Application Server User s Guide, V130

39 New Features in Version 120 You can now specify a WorkloadCapturePercent keyword in kwe.xml to define a percentage of workloads to be randomly analyzed by workload analysis. (This control also applies to the new heap-analysis workspaces, via the new HeapCapturePercent keyword). This enhancement also added a new Take Action command, WAS Set Capture Percent, that you can use for changing the capture percentages dynamically from CandleNet Portal. For every cofiguration parameter that requires a class mask, you may now specify an exclusion mask that identifies classes to be excluded. This includes the Dynamic Workload Analysis and Start Heap Collection Take Action commands as well. New samples have been added to the Best Practices application. Other changes instituted with this new version include: The All Workloads attribute group (table name KWEWKLDS) has been renamed All Workloads V2 (table name KWEWLDS2), and the Longest Running Workloads attribute group (table name KWEWKLEX) has been renamed Longest Running Workloads V2 (table name KWEWLEX2). Note, however, that situations you created using the old group names should function as before. Numerous attributes have been renamed across all attribute groups to make them consistent with the OMEGAMON XE for WebSphere Application Server for OS/390 product. The automatic installer for the Best Practices sample has been desupported. Instead guidelines are provided for manually installing the sample using standard WebSphere Application Server processes. Support has been dropped for WebSphere Application Server V3.5. What s New 39

40 New Features in Version 120 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 allocations This 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 40 OMEGAMON XE for WebSphere Application Server User s Guide, V130

41 New Features in Version 120 DefaultCollectHeapClasses MaxReferenceSearchTime For control of a specific application server via the MonitorAppServer tag: CollectHeapLevel CollectHeapClasses In addition, to specify the classes whose heap allocations are to be instrumented, these attriutes were added to the kweiuser.xml file: NumHeapAnalysisClasses HeapAnalysisSystemClasses HeapAnalysisUserClasses MeasureHeapDelays The HeapAnalysis attribute was added to the kweiuser.xml Class tag. Finally, Take Action command WAS Start Heap Collection was added to allow the CandleNet Portal user to dynamically start and stop the collection of heap-allocation statistics. Identification of memory leaks The 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 workloads Prior 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 What s New 41

42 New Features in Version 120 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 delays Version 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 type WebSphere Application Server can now analyze calls to the CICS Transaction Gateway via the new CTG workload delay type. 42 OMEGAMON XE for WebSphere Application Server User s Guide, V130

43 New Features in Version 120 IBM s CTG provides your WebSphere Application Server applications access to data within Enterprise Information Systems (EIS) via CICS. A number of application programming interfaces are available with which your programmers can execute CICS transactions that retrieve and update information in CICS resources such as DB2. Using CTG it is possible to incorporate services provided by legacy CICS applications into new distributed and enterprise applications. Of particular interest to WebSphere Application Server users is a set of Java interfaces that allow WebSphere Application Server applications to access CICS. These three Java interfaces are: ECI (the External Call Interface) directly calls a CICS program (through the program link facility) and uses the CICS COMMAREA to pass parameters and retrieve data. Note:To include COMMAREA information about ECI applications, you must create a special plugin to extract that information and add it to the Selected Workload Delays - Current Interval workspace; this process is described in Prerequisite for CTG users on page 139. The CtgDelayPlugin and UserClassPath attributes were added to the kweiuser.xml file so the workload analysis component can locate and invoke this plugin. EPI (the External Presentation Interface) enables a non-cics client to emulate the functions of a 3270 terminal and access CICS 3270-based transactions using the 3270 data stream. EPI is not available on CICS Transaction Gateway for z/os. ESI (the External Security Interface) provides an interface to APPC s Password Expiration Management (PEM) feature, through which user IDs and passwords can be validated by a CICS external security subsystem such as RACF. This enhancement comprises a new set of CTG-related delay types in the workloads workspaces; it also added the CTG Summary workspace, which reports information about the CICS Transaction Gateway transactions processed by an application server. This new feature necessitated the addition of the CTG keyword to the MethodType attribute of the kweiuser.xml file s Class tag and the addition of class type G to the DefaultCollectWorkloadClassType and CollectWorkloadClassType keywords in the kwe.xml file. What s New 43

44 New Features in Version 120 Support for JCA workloads as a delay type WebSphere 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. 44 OMEGAMON XE for WebSphere Application Server User s Guide, V130

45 New Features in the Programming Enhancements to Version 110 New Features in the Programming Enhancements to Version 110 The programming enhancements to Version 110 include additional JVM garbage-collector workspaces and attribute groups that provide a more finely grained look at the heap allocation problems that cause the Java Virtual Machine to initiate garbage collection the workload analysis feature now supports Model/View/Controller workloads (including struts applications) no more support for the JVM profiler and its reports the new IPAddresses and UserIds parameters of the WAS Start Application Tracing Take Action command allow you to start application tracing on Web applications initiated from certain IP addresses (for Web browsers) or by certain WebSphere Application Server user IDs support for HP-UX and Linux it is no longer necessary that sites disable the just-in-time compiler when installing the OMEGAMON XE agent for WebSphere Application Server, nor is it still necessary to copy the kweprof.dll file to the WebSphere Application Server \bin directory Numerous changes have been made to the installation/deinstallation of the Best Practices sample application; these include, among others: The supported UNIX platforms now include Linux and HP-UX. Installation now supports WebSphere Application Server V5.0 Network Deployment. The installation batch file/shell script has been renamed from CandleBP to BPInstall. The generated deinstallation batch file/shell script has been renamed from BPUninstall<WASv> to BPUninstall<WASv><nodename>, where <WASv> is the WebSphere Application Server version and <nodename> is the UNIX or Windows node where the Best Practices application was installed. The installation and deinstallation processes have changed so much that Candle strong recommends you reread A Sample WebSphere What s New 45

46 New Features in the Programming Enhancements to Version 110 Application Server Application: Best Practices on page 185 before installing or deinstalling this sample application. Enhanced garbage-collection statistics The 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. 46 OMEGAMON XE for WebSphere Application Server User s Guide, V130

47 New Features in the Programming Enhancements to Version 110 The new WAS Verbose GC Collection Take Action command was added to allow CandleNet Portal users to dynamically start reporting garbage-collection statistics. Support for user-defined workloads The 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. What s New 47

48 New Features in the Programming Enhancements to Version 110 Support deleted for the JVM profiler and its reports Support 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. 48 OMEGAMON XE for WebSphere Application Server User s Guide, V130

49 New Features in Version 110 New Features in Version 110 The Version 110 enhancements include support for WebSphere Application Server V5.0 new attributes that collect workload analysis and application trace data configuration options that enable you to define workload and application traces for which you want to collect data new workspaces that enable you to view workload and application tracing information Take Action commands to manage workload analysis and application tracing new attributes that collect information about databases, HTTP sessions, Java Message Service (JMS) queues, and Java Virtual Machine (JVM) threads new workspaces that enable you to view information about databases, HTTP sessions, JMS queues, and JVM threads a Best Practices application comprising seven samples that illustrate the performance advantages of selected Java coding practices Support for WebSphere Application Server V5.0 Version 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 What s New 49

50 New Features in Version 110 Workload analysis A 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 workloads Version 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 commands This 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 changes Additional 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 50 OMEGAMON XE for WebSphere Application Server User s Guide, V130

51 New Features in Version 110 class loader script to let you define and implement your specific settings for collecting this data. Additional attribute groups The 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 All Workloads Application Trace Application Trace File Datasources HTTP Sessions JMS Summary JVM Threads Longest Running Workloads Selected Workload Delays Use Reports summary data about workloads and areas that are causing the most degradation and delays Shows the flow of method calls within traced applications Reports information about any traces that were performed for the application server Reports database usage information Reports data about active HTTP sessions Reports data about how WebSphere Application Server applications are using JMS and WebSphere MQ messaging Reports data about threads running in the JVMs that are hosting an application server 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 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 What s New 51

52 New Features in Version 110 Additional workspaces The 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 samples Candle 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 OMEGAMON XE for WebSphere Application Server User s Guide, V130

53 New Features in Version 110 Changes in Version 110 Revised configuration information Rather than cover all the various configuration options in one chapter, this guide presents the material in chapters 2 6 in a configuration section. Covering separate configuration topics in separate chapters should make it easier to locate specific configuration information that pertains to the collection of optional data. The first chapter in the section provides an overview of configuration requirements. The remaining chapters cover general agent configuration, configuration requirements and the collection of JVM profiler data, and configuration requirements and the collection of workload analysis and application trace information. WAS Setup Profiler Take Action command replaced This release has replaced the WAS Setup Profiler Take Action command with the WAS Configuration Setup Take Action command; this new command includes controls for the new workload analysis feature. Support for WebSphere Application Server V3.5 dropped from the DB Connection Pools workspace The OMEGAMON XE agent still supports WebSphere Application Server V3.5 via its Container Transactions and EJB Containers workspaces; however support has been dropped for WebSphere Application Server V3.5 from the DB Connection Pools workspace. New chapters and appendixes In addition to updating the existing text where applicable, this User s Guide also contains several new chapters and appendixes. The new sections in the guide group related chapters together. The new appendixes cover the messages that are produced by the OMEGAMON XE agent and a cross-reference for identifying attribute information that you collect for long-term historical information. These new items include Chapter 2, An Introduction to Configuration on page 71 Chapter 3, Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels on page 81 Chapter 4, Collecting JVM Profiler Performance Data on page 93 What s New 53

54 New Features in Version 110 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. 54 OMEGAMON XE for WebSphere Application Server User s Guide, V130

55 1 Overview of the OMEGAMON XE for WebSphere Application Server Product Overview This 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 What is OMEGAMON XE? Components of the environment What is CandleNet Portal? What is the Candle Management Workstation? Further information about the CMW and CandleNet Portal What is OMEGAMON DE? What is OMEGAMON DE Policy Management? PathWAI Performance Analyzer product simplifies trace analysis and workload instrumentation Historical data collection Introducing OMEGAMON XE for WebSphere Application Server What is an OMEGAMON XE agent? What this agent does Workload analysis and application tracing How the agent works Product packages that include this agent Overview of the OMEGAMON XE for WebSphere Application Server Product 55

56 Situations for OMEGAMON XE for WebSphere Application Server Predefined situations How situations work Avoid using negative values Available predefined situations In-depth information about situations Take Action Commands Predefined Take Action commands OMEGAMON XE for WebSphere Application Server User s Guide, V130

57 OMEGAMON XE for WebSphere Application Server Operating Environment OMEGAMON XE for WebSphere Application Server Operating Environment Overview OMEGAMON XE for WebSphere Application Server can help you address the increasing challenges presented by today s technical environment. In this topic, you learn about the operating environment in which the OMEGAMON XE agent resides. What is OMEGAMON XE? OMEGAMON XE is a suite of products that assists you in monitoring your mainframe and distributed systems on a variety of platforms using a variety of workstations. It provides a way to monitor the availability and performance of all the systems in your enterprise from one or several designated workstations. It provides many useful reports you can use to track trends and understand and troubleshoot system problems. You can use OMEGAMON XE to establish your own performance thresholds create situations, which are conditions to monitor create and send commands to systems in your managed enterprise by means of the Take Action feature. Take Action enables you to, for instance, restart a process that is not functioning properly or send a message create comprehensive reports about system conditions monitor for alerts on the systems and platforms you are managing trace the causes leading up to an alert define your own queries, using the attributes provided by OMEGAMON XE for WebSphere Application Server, to monitor conditions of particular interest to you Overview of the OMEGAMON XE for WebSphere Application Server Product 57

58 OMEGAMON XE for WebSphere Application Server Operating Environment Components of the environment The 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 58 OMEGAMON XE for WebSphere Application Server User s Guide, V130

59 OMEGAMON XE for WebSphere Application Server Operating Environment application is downloaded to your system the first time you log on to CandleNet Portal, and, thereafter, only when there are software updates. What is the Candle Management Workstation? When using OMEGAMON XE for WebSphere Application Server, you use the Candle Management Workstation (CMW) for CMS administrative functions that manage work groups and work lists, data items, and managed systems lists. Further information about the CMW and CandleNet Portal For 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. Overview of the OMEGAMON XE for WebSphere Application Server Product 59

60 OMEGAMON XE for WebSphere Application Server Operating Environment 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. 60 OMEGAMON XE for WebSphere Application Server User s Guide, V130

61 OMEGAMON XE for WebSphere Application Server Operating Environment PathWAI Performance Analyzer product simplifies trace analysis and workload instrumentation Among its many other capabilities, Candle s PathWAI Performance Analyzer product allows you to: Import your kweliuser.xml control file, update it to specify the classes and methods to be instrumented for workload analysis, and export the updated file. With PathWAI Performance Analyzer, you can browse the contents of a jar, ear, or war or ear file and select the classes and methods you want instrumented. Analyze application trace data in ways CandleNet Portal never could, including the viewing of vastly greater quantities of trace data. Among its other enhancements, PathWAI Performance Analyzer adds a graphical trace viewer and a tree view of your methods calling parameters. This new capability obviates the previous Application Trace workspace (but not the Application Trace Files workspace or the Take Action commands that let you start or stop application tracing and delete application trace files). For complete information, see the online PathWAI Performance Analyzer User Guide. Historical data collection You 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 Overview of the OMEGAMON XE for WebSphere Application Server Product 61

62 OMEGAMON XE for WebSphere Application Server Operating Environment 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. 62 OMEGAMON XE for WebSphere Application Server User s Guide, V130

63 Introducing OMEGAMON XE for WebSphere Application Server Introducing OMEGAMON XE for WebSphere Application Server What is an OMEGAMON XE agent? The OMEGAMON XE agent for WebSphere Application Server is an intelligent agent that resides on managed distributed systems that use the IBM WebSphere Application Server product. As a monitoring agent, it collects and distributes real-time and historical performance data as needed to a CMS. What this agent does The 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 Overview of the OMEGAMON XE for WebSphere Application Server Product 63

64 Introducing OMEGAMON XE for WebSphere Application Server 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 tracing The 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 64 OMEGAMON XE for WebSphere Application Server User s Guide, V130

65 Introducing OMEGAMON XE for WebSphere Application Server aggregate data on each workload that ran along with detailed information about delays that contributed to the response time of the workload workload exception information that reports response times and delays for individual workloads aggregate data for defined data sources HTTP session data information about transactions running against the CICS Transaction Gateway (CTG) and about JCA transactions (JCA allows J2EE applications to connect to backend enterprise information systems). Java Messaging Service (JMS) data for WebSphere MQ queues accessed by WebSphere Application Server applications To collect this data, the OMEGAMON XE agent uses an instrumentation process, which inserts hooks into application classes and system classes as they are loaded into the JVM. You need to complete several steps to setup this workload analysis feature. These steps include running the setupcandlewaenabler shell script, customizing WebSphere Application Server configuration, and setting up the workload analysis instrumentation file, kweiuser.xml. See Preparing the Instrumentation Control File for Workloads and Application Traces on page 117 for information about defining workload collection parameters in kweiuser.xml and Collecting Workload Analysis, Application Trace, and Heap Data on page 143 for information about running the shell script and collecting workload data. The agent also provides several Take Action commands that let you control the collection of workload analysis data and manage application traces. See The CandleNet Portal Take Action Commands on page 177 for information about these commands. How the agent works Each 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. Overview of the OMEGAMON XE for WebSphere Application Server Product 65

66 Introducing OMEGAMON XE for WebSphere Application Server 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 agent The 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 66 OMEGAMON XE for WebSphere Application Server User s Guide, V130

67 Situations for OMEGAMON XE for WebSphere Application Server Situations for OMEGAMON XE for WebSphere Application Server Predefined situations OMEGAMON 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 work Situations 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 values If 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. Overview of the OMEGAMON XE for WebSphere Application Server Product 67

68 Situations for OMEGAMON XE for WebSphere Application Server Available predefined situations OMEGAMON XE for WebSphere Application Server provides the following predefined situations that you can use to monitor your system. Table 3. Predefined Situations for the OMEGAMON XE Agent Situation WebSphere_Application_Svr_Err WebSphere_Servlets_JSPs_Error WebSphere_Start_AppServer WebSphere_Web_Application_Error WebSphereContainerTransRollBack WebSphereDBConnPoolsThrdTimeOut Function Monitors error messages for WebSphere Application Server Monitors the error count for servlets and JSPs Monitors the status of the WebSphere Application Server and automatically restarts the server if it is stopped Monitors the error count for Web applications Monitors the transaction-roll-back count for global and local transactions for containers Monitors the thread-time-out count for DB connection pools In-depth information about situations For 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. 68 OMEGAMON XE for WebSphere Application Server User s Guide, V130

69 Take Action Commands Take Action Commands Overview The Take Action feature lets you stop or start a process at any system in your network where one or more OMEGAMON XE agents are installed. You can implement Take Action commands from a workspace, from a situation, in an ad hoc mode, or by recalling a saved Take Action command. See the CandleNet Portal online help for using Take Action commands in general. Predefined Take Action commands OMEGAMON 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. Overview of the OMEGAMON XE for WebSphere Application Server Product 69

70 Take Action Commands 70 OMEGAMON XE for WebSphere Application Server User s Guide, V130

71 2 An Introduction to Configuration Overview This 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 Prerequisites When and why do you configure the agent? Configuration Basics About Your Agent Product components Supported WebSphere Application Server Versions and Configurations How are the product components configured? UNIX requirements Applying product maintenance: IBM service packs Restarting the application server An Introduction to Configuration 71

72 Introduction Introduction Chapter goals This 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 Prerequisites This 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. 72 OMEGAMON XE for WebSphere Application Server User s Guide, V130

73 Configuration Basics About Your Agent Configuration Basics About Your Agent Introduction This 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 components Figure 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. An Introduction to Configuration 73

74 Configuration Basics About Your Agent Figure 1. Product Components for OMEGAMON XE for WebSphere Application Server V4 CNP Monitored Node CMS OMEGAMON XE Agent (KWEAGENT) Java Virtual Machine WebSphere Application Server WebSphere Administrative Server Workload Analysis Collector 74 OMEGAMON XE for WebSphere Application Server User s Guide, V130

75 Configuration Basics About Your Agent Figure 2. Product Components for OMEGAMON XE for WebSphere Application Server V5 Base Deployment Configuration CNP Monitored Node CMS OMEGAMON XE Agent (KWEAGENT) WebSphere V5 instance Performance Monitoring Infrastructure Workload Analysis Collector An Introduction to Configuration 75

76 Configuration Basics About Your Agent Figure 3. Product Components for OMEGAMON XE for WebSphere Application Server V5 Network Deployment Configuration CNP Monitored Node WebSphere V5 Node Agent CMS OMEGAMON XE Agent (KWEAGENT) Performance Monitoring Infrastructure Managed Process Workload Analysis Collector 76 OMEGAMON XE for WebSphere Application Server User s Guide, V130

77 Configuration Basics About Your Agent Supported WebSphere Application Server Versions and Configurations Candle s OMEGAMON XE agent supports these WebSphere Application Server versions: WebSphere Application Server V4 Advanced Edition WebSphere Application Server V5 Base Deployment, Network Deployment, and Enterprise Edition OMEGAMON does not support the following WebSphere Application Server versions: WebSphere Application Server V4 Single-Server Edition WebSphere Application Server V5 WSINSTANCE servers A single OMEGAMON XE agent can monitor only one WebSphere Application Server version at a time and only WebSphere application servers running on the same physical machine. Thus, if you have WebSphere Application Server V4 and WebSphere Application Server V5 running on a single system, you must run two instances of the OMEGAMON XE agent to monitor them simultaneously, one for V4 and one for V5. For WebSphere Application Server V5 Network Deployment, all members of the cell running on the same physical node are monitored. Refer to IBM s WebSphere Application Server documentation for more information on these various types of configurations. An Introduction to Configuration 77

78 Configuration Basics About Your Agent How are the product components configured? CNP CMS KWEAGENT 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. Candle workload collector 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. 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. 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. 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. 78 OMEGAMON XE for WebSphere Application Server User s Guide, V130

79 Configuration Basics About Your Agent UNIX requirements The 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 An Introduction to Configuration 79

80 Configuration Basics About Your Agent 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 packs Stop 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 server Whenever 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. 80 OMEGAMON XE for WebSphere Application Server User s Guide, V130

81 3 Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels Overview This 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 Background Chapter goals Configuration parameters Environment variables A Look Inside Your Agent s Configuration Files What are the kwe.xml default parameters? Configuration files for multiple agents Sample parameter defaults Additional configuration parameters Sample definitions for all configuration values Your Agent s Configuration Parameters and XML Tags KWEAGENT MonitorAppServer tag Using Your Agent s Environment Variables What are the environment variables? Variables for OMEGAMON XE for WebSphere Application Server Setting Instrumentation Levels to Collect PMI Data Setting instrumentation levels dynamically via CandleNet Portal Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 81

82 Setting instrumentation levels from the WebSphere administrative console for V Setting instrumentation levels from the WebSphere administrative console for V OMEGAMON XE for WebSphere Application Server User s Guide, V130

83 Getting Started Getting Started Background The 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 goals This 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 parameters The 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 Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 83

84 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 variables The 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. 84 OMEGAMON XE for WebSphere Application Server User s Guide, V130

85 A Look Inside Your Agent s Configuration Files A Look Inside Your Agent s Configuration Files Introduction This 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 agents To 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 Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 85

86 A Look Inside Your Agent s Configuration Files 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 CollectorSessionPort AgentID 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. 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. 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. 86 OMEGAMON XE for WebSphere Application Server User s Guide, V130

87 A Look Inside Your Agent s Configuration Files 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. Sample parameter defaults The 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. Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 87

88 A Look Inside Your Agent s Configuration Files Figure 4. Sample Default Parameters in kwe.xml <?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="" /> Additional configuration parameters The 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. 88 OMEGAMON XE for WebSphere Application Server User s Guide, V130

89 A Look Inside Your Agent s Configuration Files Sample definitions for all configuration values The 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 in C:\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 Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 89

90 A Look Inside Your Agent s Configuration 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> 90 OMEGAMON XE for WebSphere Application Server User s Guide, V130

91 Your Agent s Configuration Parameters and XML Tags Your Agent s Configuration Parameters and XML Tags Introduction This 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. KWEAGENT The 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). Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 91

92 Your Agent s Configuration Parameters and XML Tags 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 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 %COLLECTIONS% %ARRAYS% Meaning Indicates that heap collection should be performed on any instantiated class that implements one of the standard Java collection interfaces. Indicates that heap analysis should be performed on all instrumented array instantiations. 92 OMEGAMON XE for WebSphere Application Server User s Guide, V130

93 Your Agent s Configuration Parameters and XML Tags DefaultCollectHeapLevel Specifies the default level of heap statistics to be collected by workload analysis for all application servers, unless specifically overridden for a particular application server. Possible values are: Value none Low Medium High no heap statistics are collected Meaning the number of objects allocated by each workload are tracked 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 In addition to the data collected by collection level Medium, individual heap objects are also tracked 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: Value NONE ALL PMI WA Verbose GC Heap Lock Meaning No historical data is to be collected. History is to be collected for all data. History is to be collected for PMI data. History is to be collected for workload analysis data. History is to be collected for garbage collection data. History is to be collected for heap analysis data. History is to be collected for lock analysis data. The default value is ALL. Multiple keywords (other than NONE or ALL) can be specified, separated by commas. Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 93

94 Your Agent s Configuration Parameters and XML Tags 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 94 OMEGAMON XE for WebSphere Application Server User s Guide, V130

95 Your Agent s Configuration Parameters and XML Tags collection. An exclusion mask begins with a exclamation point (!) and is followed by a class mask. Workload data for any class that matches an exclusion mask is not collected. For example, DefaultCollectWorkloadClassName="*;!trade*" says workload data should be collected for all classes except for those that match the mask trade*. DefaultCollectWorkloadClassType This keyword specifies the type of workload analysis data that will be collected by default for all application servers. The valid format is an alphabetic string of one or more of the following characters. Each character, shown in the following list, represents a specific type of workload data that should be collected. Value A B C D G I M Q S T Meaning Indicates that all workload data should be collected Indicates that workload data for EJB-related classes should be collected Indicates that workload data for JCA-related classes should be collected Indicates that workload data for SQL-related classes should be collected Indicates that workload data for CTG-related classes should be collected Indicates the workload date of JNDI-related classes should be collected Indicates that workload data for user-defined methods should be collected Indicates that workload data for JMS-related classes should be collected Indicates that workload data for servlet classes should be collected Indicates that workload data for transaction-related classes 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 Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 95

96 Your Agent s Configuration Parameters and XML Tags 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. 96 OMEGAMON XE for WebSphere Application Server User s Guide, V130

97 Your Agent s Configuration Parameters and XML Tags DefaultGCCollect="Y N" This parameter indicates whether or not garbage-collection data is to be collected from the application servers by default. If DefaultGCCollect is set to N, then no garbage-collection statistics are collected, unless an overriding GCCollect value is specified for a particular application server. You may also use the WAS Verbose GC Collection Take Action command to dynamically start collecting garbage-collection data; see the OMEGAMON XE for WebSphere Application Server online help for information. DefaultGCPollFrequency This parameter indicates how frequently, in seconds, the workload analysis component should check the WebSphere Application Server logs for garbage-collection records. DefaultHeapCapturePercent Specifies the default heap capture percentage for all application servers. Only the specified percentage of heap-allocation requests (randomly selected) are measured and reported by workload analysis. This attribute can be overridden for individual application servers with the HeapCapturePercent attribute. Valid values are from 1 to 100; if not specified, the default is 100. DefaultInflightThreshold Specifies the minimum time, in milliseconds, that a workload can run before appearing in the In-flight Workloads Summary workspace. This threshold applies to all application servers, unless specifically overridden for a particular application server. Workloads that have been running for less than the time specified are not reported. The default is 5 (milliseconds). DefaultLockAnalysisLevel This keyword specifies the default level of monitor contention monitoring to be performed for all application servers, unless specifically overridden at the application server level. There are three possible values for this attribute: Disabled Lock Analysis is disabled. This is the default value. Enabled The cost of monitor locking is collected for each involving workload, delay and class method. Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 97

98 Your Agent s Configuration Parameters and XML Tags 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 98 OMEGAMON XE for WebSphere Application Server User s Guide, V130

99 Your Agent s Configuration Parameters and XML Tags will collect data from the application servers only when required. The default value is 60. DefaultWorkloadCapturePercent Specifies the default workload capture percentage for all application servers. Only the specified percentage of executing workloads (randomly selected) are measured and reported by workload analysis. This attribute can be overridden for individual application servers with the WorkloadCapturePercent attribute. Valid values are from 1 to 100; if not specified, the default is 100. DiscoverInterval This parameter specifies how often, in minutes, KWEAGENT will poll WebSphere Application Server to search for newly defined application servers. The default is 15. ExceptionWorkloadHistoricalMax This parameter helps you tailor the collection of exception transactions for each unique workload. It limits the number of exception transactions that are to be saved historically for each historical period. The default is 10 transactions. JavaLogFileName This parameter indicates the file to which the KWEAGENT s Java code writes trace logs. The default is KWERAS1_Java.log. LogScanDateFormat This parameter allows the OMEGAMON XE agent to recognize and process Japanese date formats from the WebSphere Application Server logs. The date must follow one of these formats: dd/mm/yy dd/yy/mm mm/dd/yy mm/yy/dd yy/mm/dd yy/dd/mm Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 99

100 Your Agent s Configuration Parameters and XML Tags 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 100 OMEGAMON XE for WebSphere Application Server User s Guide, V130

101 Your Agent s Configuration Parameters and XML Tags WASHOME/properties/sas.client.props file, where WASHOME is the WebSphere Application Server installation directory. If you do not want to give the agent read-access to this file, then copy the contents of this file to another file, and specify the fully qualified name of this file in the SasClientProps parameter. SasServerProps Applies only to WebSphere Application Server V4.0. This parameter contains the fully qualified path name of the file containing the contents of the WebSphere Application Server sas.server.props file. If this parameter is omitted, the agent will read the contents of the WASHOME/properties/sas.server.props file, where WASHOME is the WebSphere Application Server installation directory. If you do not want to give the agent read-access to this file, then copy the contents of this file to another file, and specify the fully qualified name of this file in the SasServerProps parameter. SOAPClientProps Applies only to WebSphere Application Server V5.0. This parameter contains the fully qualified path name of the WebSphere Application Server soap.client.props file property file, which contains authentication information that allows the OMEGAMON XE agent to access WebSphere Application Server system management functions when WebSphere Application Server global security is on. If this parameter is omitted, the agent reads the WASHOME/properties/soap.client.props file, where WASHOME is the WebSphere Application Server V5.0 installation directory. If you do not want to give the agent read access to this file, then copy this file to another file, and specify this file s fully qualified name in the SOAPClientProps parameter. To create this property file: 1. Copy WASHOME/properties/soap.client.props to either C:\Candle\CMA\logs\kweclient.soap.props (for Windows platforms) or to $CANDLEHOME$/logs/kweclient.soap.props (for UNIX platforms), where $CANDLEHOME is the OMEGAMON XE agent s installation directory. 2. Modify these properties in the new kweclient.soap.props file: com.ibm.soap.securityenabled=true com.ibm.soap.loginuserid= com.ibm.soap.loginpassword= Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 101

102 Your Agent s Configuration Parameters and XML Tags 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 102 OMEGAMON XE for WebSphere Application Server User s Guide, V130

103 Your Agent s Configuration Parameters and XML Tags behavior is to monitor the first version specified in the registry. The WASAppServerRoot parameter must be specified explicitly and uniquely for each agent in order to monitor all versions of WebSphere Application Server. MonitorAppServer tag The 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*. Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 103

104 Your Agent s Configuration Parameters and XML Tags The CollectHeapClasses attribute may contain two special keyword masks: Value %COLLECTIONS% %ARRAYS% Meaning Indicates that heap collection should be performed on any instantiated class that implements one of the standard Java collection interfaces. Indicates that heap analysis should be performed on all instrumented array instantiations. 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: Value none Low Medium High no heap statistics are collected Meaning the number of objects allocated by each workload are tracked 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 In addition to the data collected by collection level Medium, individual heap objects are also tracked This parameter is optional. CollectHistorical Defines which historical data is to be collected by the agent. This attribute overrides the DefaultCollectHistorical attribute specified at the KWEAGENT 104 OMEGAMON XE for WebSphere Application Server User s Guide, V130

105 Your Agent s Configuration Parameters and XML Tags level for the application server associated with this MonitorAppServer tag. (See KWEAGENT on page 91.) Possible values are: Value NONE ALL PMI WA Verbose GC Heap Lock Meaning No historical data is to be collected. History is to be collected for all data. History is to be collected for PMI data. History is to be collected for workload analysis data. History is to be collected for garbage collection data. History is to be collected for heap analysis data. History is to be collected for lock analysis data. 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. Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 105

106 Your Agent s Configuration Parameters and XML Tags 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 A B C D G I M Q Type of Workload Data Indicates that all workload data should be collected Indicates that workload data for EJB-related classes should be collected Indicates that workload data for JCA-related classes should be collected Indicates that workload data for SQL-related classes should be collected Indicates that workload data for CTG-related classes should be collected Indicates the workload data of JNDI-related classes should be collected Indicates that workload data for user-defined methods should be collected Indicates that workload data for JMS-related classes should be collected for Java 106 OMEGAMON XE for WebSphere Application Server User s Guide, V130

107 Your Agent s Configuration Parameters and XML Tags Value S T Type of Workload Data Indicates that workload data for servlet classes should be collected Indicates that workload data for transaction-related classes should be collected 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. Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 107

108 Your Agent s Configuration Parameters and XML Tags ExceptionWorkloadName Optional. This keyword identifies the workloads running on this application server for which exception transactions are to be collected. It contains one or more masks, separated by commas, that identify the class or classes of the workloads for which exception transactions are to be collected. Each mask may contain the asterisk (*) and question mark (?) wildcard characters. If this keyword is omitted, workload exception data is not collected for this application server unless data collection is specified for the KWEAGENT XML tag or by a Set Workload Exception Thresholds Take Action command. Exclude="Yes No" This parameter indicates whether or not the application server should be monitored. If Exclude=Yes is specified, all other MonitorAppServer parameters, with the exception of Name are ignored. If Exclude=No is specified, then it overrides the DefaultExclude=Yes parameter which may have been specified at the agent level. This parameter is optional. GCCollect="Y N" This parameter indicates whether or not garbage-collection data is to be collected from the application server. If GCCollect is set to N, then no garbage-collection statistics are collected. You may also use the WAS Verbose GC Collection Take Action command to dynamically start collecting garbage-collection data; see the OMEGAMON XE for WebSphere Application Server online help for information. This parameter is optional. GCPollFrequency This parameter indicates how frequently, in seconds, the workload analysis component should check the WebSphere Application Server logs for garbage-collection records. The default is 60. This parameter is optional. HeapCapturePercent Specifies the heap capture percentage for this application server. Only the specified percentage of heap-allocation requests (randomly selected) are measured and reported by workload analysis. Valid values are from 1 to OMEGAMON XE for WebSphere Application Server User s Guide, V130

109 Your Agent s Configuration Parameters and XML Tags As an example, you set HeapCapturePercent to 30. This means that workload analysis will only provide detailed measurements on 30% of the heap allocations (chosen randomly) that it saw running. The other 70% of heap allocations are ignored. This parameter is optional. InflightThreshold Specifies the minimum time, in milliseconds, that a workload can run before appearing in the In-flight Workloads Summary workspace. This threshold applies to the current application server. Workloads that have been running for less than the time specified are not reported. The default is 5 (milliseconds). This parameter is optional. LockAnalysisLevel This keyword specifies the level of lock contention monitoring to be performed for the application server referenced by this MonitorAppServer tag. There are three possible values for this attribute: Disabled Lock Analysis is disabled. Enabled The cost of monitor locking is collected for each involving workload, delay and class method. High In addition to the data collected by the Enabled collection level, the sources of monitor contention will be identified. The default value is the value of the DefaultLockAnalysisLevel parameter specified at the KWEAGENT level, or Disabled if the DefaultLockAnalysisLevel parameter was not specified. LogScanInterval This parameter indicates the interval value, in seconds, for scanning the application server s log file to detect error or exception conditions. Periodically, based on the time set by this parameter, the KWEAGENT will open and read any new entries written into the log file for the application server. Any new entries that indicate an error or exception condition are noted in the Application Server Errors table as a pure event. The default for this parameter is 60. This parameter is optional. Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 109

110 Your Agent s Configuration Parameters and XML Tags MinimumSamplingInterval This parameter provides a minimum interval between sample requests for a particular resource or resource type within this application server. This value is meaningful only when either the StatisticInterval paremeter or the DefaultStatisticInterval parameter is set to 0, or when either the CollectorSessionSampleInterval paremeter or the DefaultCollectorSessionSampleInterval parameter is set to 0. This parameter specifies a minimum time value, in seconds, for obtaining updated information from the server when on-demand sampling is active. For example, if MinimumSamplingInterval is set to 15 and if two requests for information for the same resource or resource type are received by the OMEGAMON XE agent within 15 seconds of one another, the second request returns the identical data as the first request. The purpose of this parameter is to avoid too frequent sampling. This parameter is optional. Name This required parameter specifies the name of the WebSphere Application Server to which this tag applies. StatisticInterval This parameter provides the sampling interval for PMI data collected for this application server, in seconds. If this value is nonzero, then the KWEAGENT will collect data from the application server based on the time specified, whether or not the data is requested. If this value is 0, then the agent will collect data from the application server only when required. The default is 60. This parameter is optional. SubnodeAliasName This parameter lets you specify an alias name for this application server for the purpose of creating a Candle Technologies (CT) subnode name representing the server. KWEAGENT normally constructs a subnode name for the server with the following format: <application-server-name>:<node-name>:kweb where <application-server-name> is the name of the application server name, and <node-name> is the name of the system on which the application 110 OMEGAMON XE for WebSphere Application Server User s Guide, V130

111 Your Agent s Configuration Parameters and XML Tags server is running. Because of a 32-character restriction for CT node names, however, either the application server name or the node name or both, can be truncated. This can result in duplicate subnode names if more than one application server running on a system have names prefixed with the same set of characters. The SubnodeAliasName parameter allows you to specify an alias name for this server which will be used as the <application-server-name> portion of the subnode name. This lets you ensure that subnode names can be unique. This parameter is optional. TakeActionAuthUsers This parameter indicates which CandleNet Portal users are authorized to issue Take Action commands for this application server. There can be multiple entries, separated by commas, associated with this parameter. Each entry can be a mask which can include the asterisk (*) and question mark (?) wildcard characters. A CandleNet Portal user is allowed to perform a Take Action on an application server if the user ID matches an entry in either the agent-level or application server level TakeActionAuthUsers list. Note that these CandleNet Portal user IDs are defined within the CMS, and do not necessarily exist on the node on which the KWEAGENT is running. You can also specify this parameter at the agent level. If specified at both the agent and application server level, the mask lists are effectively merged for the application server. WorkloadCapturePercent Specifies the workload capture percentage for this application server. Only the specified percentage of executing workloads (randomly selected) are measured and reported by workload analysis. Valid values are from 1 to 100. As an example, you set WorkloadCapturePercent to 30. This means that workload analysis will only provide detailed measurements regarding user response times and delays on 30% of the workloads (chosen randomly) that it saw running. The other 70% of the workloads are ignored. This parameter is optional. Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 111

112 Using Your Agent s Environment Variables 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 Server The 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. 112 OMEGAMON XE for WebSphere Application Server User s Guide, V130

113 Using Your Agent s Environment Variables KBB_RAS1 This optional variable can be set to turn on tracing. The possible values for this variable are the same as with all CT products. Do not define this parameter unless directed to do so by Candle. KWE_MSG_PATH This variable identifies the directory which contains the kwemsgs file. This file contains all the messages that are issued by the KWEAGENT. This variable is only used in the UNIX environment; on Windows systems, the kwemsgs file is assumed to be located in the directory identified by BinPath. KWE_AGENT_COMPONENT_TRACE This variable indicates whether or not the internal tracing of requests to KWEAGENT should be enabled. This is an internal, wrap-around trace that contains the flow of requests and responses to and from the agent. The default for this variable is YES. KWE_INTERNAL_TRACE This variable indicates whether the internal flow tracing within KWEAGENT should be enabled. This is an internal, wrap-around trace that shows the flow of control through the functions of the agent. KWE_HEAP_DEBUG This variable indicates whether or not the heap debugging option should be enabled for KWEAGENT. The default is NO. KWE_SERVICE_INIT_TIME This variable is only used in the Windows NT or 2000 environment when KWEAGENT is running as a service. This variable specifies the time, in milliseconds, that the agent service should require to initialize itself. The default for this variable is 5000 (5 seconds). KWE_PARM_FILE This variable contains the name of the file that contains the configuration parameters for KWEAGENT. This environmental variable is only used in a Windows environment. The default for this variable is kwe.xml. The file must exist in the directory identified by the BinPath variable. Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 113

114 Using Your Agent s Environment Variables $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. 114 OMEGAMON XE for WebSphere Application Server User s Guide, V130

115 Setting Instrumentation Levels to Collect PMI Data Setting Instrumentation Levels to Collect PMI Data Overview The 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 Portal OMEGAMON XE for WebSphere Application Server provides SetIL Take Action commands to change PMI instrumentation levels; these are listed in Table 5 on page 179. When you execute one of these commands, the monitoring agent changes the WebSphere Application Server configuration on behalf of the targeted application server. See the OMEGAMON XE for WebSphere Application Server online help for instructions on using these Take Action commands. Setting instrumentation levels from the WebSphere administrative console for V4 This procedure explains how to use the WebSphere administrative console to set instrumentation levels to collect performance data for WebSphere Application Server V4. 1. Select the application server that needs to be monitored. 2. Choose the Services tab in the property pane. 3. Select the Performance Monitoring Settings in the service listing. 4. Click the Edit Properties button to bring up the Performance Monitoring Settings pop-up window. Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels 115

116 Setting Instrumentation Levels to Collect PMI Data 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 116 OMEGAMON XE for WebSphere Application Server User s Guide, V130

117 4 Preparing the Instrumentation Control File for Workloads and Application Traces Overview This 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 What are the instrumentation files for the agent? Simplifying the instrumentation process: PathWAI Performance Analyzer Collecting the workload and application trace data Inside the User Instrumentation Control File Sample kweiuser.xml instrumentation control files Keywords for the KWEINSTR tag Keywords for the Class tag Keywords for the Workload tag Keywords for the Workload_Class tag Keywords for the Delay tag Keywords for the Delay_Class tag About data collection Prerequisite for CTG users Preparing the Instrumentation Control File for Workloads and Application Traces 117

118 Instrumentation Basics about Workloads and Tracing Instrumentation Basics about Workloads and Tracing Overview Once 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 118 OMEGAMON XE for WebSphere Application Server User s Guide, V130

119 Instrumentation Basics about Workloads and Tracing the contents of a jar, ear, or war file and select the classes and methods you want instrumented. For complete information, see the online PathWAI Performance Analyzer User Guide. Collecting the workload and application trace data After 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. Preparing the Instrumentation Control File for Workloads and Application Traces 119

120 Inside the User Instrumentation Control File Inside the User Instrumentation Control File Overview This 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 files The 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. 120 OMEGAMON XE for WebSphere Application Server User s Guide, V130

121 Inside the User Instrumentation Control File Sample kweiuser.xml files You can use an unaltered version of one of these sample kweiuser.xml files, customize one of them, or ignore them and create your own.. For a detailed description of their XML tags and keywords, see the definitions that begin on page 124. Figure 6. Sample kweiuser_development.xml Workload Analysis Control File <?xml version="1.0" encoding="utf-8"?> - <KWEINSTR Version="130" CollectCPUTime="true" CollectHTTPSessStats="true" CollectInFlightWorkloads="all" CollectorSessionPort="65535" CtgDelayPlugin="" DisplayEJBAs="EAR:CLASS" DisplayServletWorkloadAs="CLASS" GlobalInstrumentation="all" HeapAnalysisUserClasses="*" InternalTrace="false" LockAnalysisSystemClasses="NONE" LockAnalysisUserClasses="*" LogFileName="kweinstr.log" MaxTrivialMethodInstructions="10" MaxClasses="25000" MeasureHeapDelays="true" NumHeapAnalysisClasses="10000" ShowInternalWorkloads="false" ShowMethodArguments="true" SysInstr="Direct" tostringissafetouse="false"> <Class Name="*" ClassType="user" DepthSensitiveInstrumentation="false" DisplayServletWorkloadAs="CLASS" HeapAnalysis="*" IgnoreTrivialMethods="false" LockAnalysis="true" MethodNames="*" MethodType="SERVLET,EJB,METHODS,PORTLET" /> </KWEINSTR> Preparing the Instrumentation Control File for Workloads and Application Traces 121

122 Inside the User Instrumentation Control File Figure 7. Default kweiuser_certification.xml Workload Analysis Control File <?xml version="1.0" encoding="utf-8"?> - <KWEINSTR Version="130" CollectCPUTime="true" CollectHTTPSessStats="true" CollectInFlightWorkloads="captured" CollectorSessionPort="65535" CtgDelayPlugin="" DisplayEJBAs="EAR:CLASS" DisplayServletWorkloadAs="CLASS" GlobalInstrumentation="all" HeapAnalysisUserClasses="*" InternalTrace="false" LockAnalysisSystemClasses="NONE" LockAnalysisUserClasses="*" LogFileName="kweinstr.log" MaxTrivialMethodInstructions="10" MaxClasses="10000" MeasureHeapDelays="true" NumHeapAnalysisClasses="5000" ShowInternalWorkloads="false" ShowMethodArguments="false" SysInstr="Direct" tostringissafetouse="false"> <Class Name="*" ClassType="user" DepthSensitiveInstrumentation="true" DisplayServletWorkloadAs="CLASS" HeapAnalysis="*" IgnoreTrivialMethods="true" LockAnalysis="true" MethodNames="*" MethodType="SERVLET,EJB,METHODS,PORTLET" /> </KWEINSTR> 122 OMEGAMON XE for WebSphere Application Server User s Guide, V130

123 Inside the User Instrumentation Control File Figure 8. Default kweiuser_production.xml Workload Analysis Control File <?xml version="1.0" encoding="utf-8"?> - <KWEINSTR Version="130" CollectCPUTime="false" CollectHTTPSessStats="false" CollectInFlightWorkloads="captured" CollectorSessionPort="65535" CtgDelayPlugin="" DisplayEJBAs="EAR:CLASS" DisplayServletWorkloadAs="CLASS" GlobalInstrumentation="all" HeapAnalysisUserClasses="" InternalTrace="false" LockAnalysisSystemClasses="" LockAnalysisUserClasses="" LogFileName="kweinstr.log" MaxTrivialMethodInstructions="10" MaxClasses="10000" MeasureHeapDelays="true" NumHeapAnalysisClasses="5000" ShowInternalWorkloads="false" ShowMethodArguments="false" SysInstr="Direct" tostringissafetouse="false"> <Class Name="*" ClassType="user" DepthSensitiveInstrumentation="true" DisplayServletWorkloadAs="CLASS" HeapAnalysis="" IgnoreTrivialMethods="true" LockAnalysis="false" MethodType="SERVLET,EJB,PORTLET" /> </KWEINSTR> Preparing the Instrumentation Control File for Workloads and Application Traces 123

124 Inside the User Instrumentation Control File Keywords for the KWEINSTR tag The 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. 124 OMEGAMON XE for WebSphere Application Server User s Guide, V130

125 Inside the User Instrumentation Control File CollectInFlightWorkloads This keyword indicates whether or not Workload Analysis should capture call stack information for workloads which could potentially appear in the In Flight Workloads workspace. The valid values are: All Collect call stack information for the In Flight Workloads workspace for all workloads, regardless of whether the workload is being measured. None Don t collect In Flight Workload information at all. Captured Only collect call stack information for the In Flight Workloads workspace for workloads that are being measured. If the workload capture percent is less than 100, then call stack information will not be collected for all workloads. The default value is All. CollectorSessionPort This keyword indicates the IP port number to be used for communicating with the agent. It must match the CollectorSessionPort value used in the kwe.xml file. This parameter is ignored if the com.candle.kwe.instrument.agent_parms property is set in the command-line arguments for the application server. In this case, the value for the port is taken from the agent control file identified by the com.candle.kwe.instrument.agent_parms property, which should refer to the same kwe.xml file that the agent is using. If workload analysis cannot obtain the port number from the agent parameter file, then it uses the value of the CollectorSessionPort in kweiuser.xml. The default value is 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). Preparing the Instrumentation Control File for Workloads and Application Traces 125

126 Inside the User Instrumentation Control File 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. 126 OMEGAMON XE for WebSphere Application Server User s Guide, V130

127 Inside the User Instrumentation Control File If a value of all is specified, then the behavior of the product is exactly like the prior product behavior. In other words, Java classes are instrumented based upon the specifications in kweiuser.xml. If a value of none is specified, then no instrumentation at all is performed, regardless of the other specifications in the instrumentation control files. A value of none implies that only garbage collection data will be collected. The default value is all. HeapAnalysisSystemClasses This keyword defines one or more class masks, separated by semicolons, that identify the instantiated system classes (those that are part of WebSphere Application Server iself) whose heap allocations can potentially be measured. Each class mask can contain '*' and '?' wildcard characters. This attribute can be overridden by the HeapAnalysis attribute of the Class tag; see Keywords for the Class tag on page 131. A class mask can begin with an exclamation point (!) character, which indicates that class names matching the mask are to be excluded from data collection. For example, to instrument all classes whose names begin with java.lang except for the java.lang.string class, specify HeapAnalysisSystemClasses="java.lang.*;!java.lang.String. HeapAnalysisUserClasses One or more class masks separated by semicolons that identify the instantiated classes for which heap allocations are to be instrumented. Each class mask can contain '*' and '?' wildcard characters. This attribute can be overridden by the HeapAnalysis attribute of the Class tag; see Keywords for the Class tag on page 131. A class mask can begin with a '!' character, which indicates that class names matching the mask are to be excluded from data collection. InternalTrace This keyword indicates whether or not workload analysis tracing should be enabled and written to a detailed log file. The default value is false. Do not change the default setting unless directed otherwise by Candle Customer Support. Preparing the Instrumentation Control File for Workloads and Application Traces 127

128 Inside the User Instrumentation Control File 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 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. 128 OMEGAMON XE for WebSphere Application Server User s Guide, V130

129 Inside the User Instrumentation Control File MaxTrivialMethodInstructions Indicates the maximum number of Java byte code instructions for a method to be considered trivial (see the description of the IgnoreTrivialMethods on page 134 parameter). The default value is 10. MeasureHeapDelays Indicates whether or not workload analysis should track workload delays due to heap allocations. Valid values are true and false; the default is false. NumHeapAnalysisClasses This keyword defines the maximum number of instantiated classes for which heap allocations can be instrumented. The default is 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. Preparing the Instrumentation Control File for Workloads and Application Traces 129

130 Inside the User Instrumentation Control File 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. Value Direct Indirect Meaning Default. Indicates called system class methods will be instrumented Indicates the system class methods called from the user class will be instrumented 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. 130 OMEGAMON XE for WebSphere Application Server User s Guide, V130

131 Inside the User Instrumentation Control File UserClassPath Applies only to CICS Transaction Gateway (CTG) ECI applications. Candle provides a Java interface that you can use for writing a plugin that extracts COMMAREA information and adds it as the minor delay name in the Selected Workload Delays - Current Interval report (for instructions on building this plugin, see the online help for the OMEGAMON XE agent). This keyword specifies the location of the compiled plugin; use the CtgDelayPlugin keyword to specify its name (see CtgDelayPlugin on page 125). Version This keyword identifies the version of the product for which the parameters were set. It ensures the parameter settings will be interpreted correctly in future releases. The current valid values are 130, 120, or 110. Keywords for the Class tag The 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. Value user system Indicates a user-defined class Meaning Indicates a WebSphere Application Server system class The default value is user. Preparing the Instrumentation Control File for Workloads and Application Traces 131

132 Inside the User Instrumentation Control File 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 132 OMEGAMON XE for WebSphere Application Server User s Guide, V130

133 Inside the User Instrumentation Control File DisplayServletWorkloadAs The presence of this tag indicates that the workload major name for servlets and JSPs is to be constructed from the URL used to invoke the servlet or JSP for servlet classes which match this Class tag. The possible value is a string consisting either of the word class or of two string fields separated by a colon. The first field contains either hostname or null. The second field contains either an asterisk or a number. The default value is the value of the DisplayServletWorkloadAs attribute set at the KWEINSTR level; see Keywords for the KWEINSTR tag on page 124. If the word class is specified, it indicates that servlets and JSPs are to be reported by class and method name. If the first portion of the string contains hostname, then the major name will contain the host name portion of the URL. If the first portion contains "null", then the host name is not included. If the second portion of the string contains a numeric value, then it indicates how many qualifiers within the URL, counting from the right, are included in the major name. If the second portion of the string contains "*", then all of the qualifiers in the URL are included. The "*" does not pertain, however, to the host name portion of the URL, which is included or excluded based upon the first portion of the string. This attribute overrides the value of DisplayServletWorkloadAs specified at the KWEINSTR level. Examples: The application URL is: 1. For DisplayServletWorkloadAs="hostname:*", this major name is displayed: 2. For DisplayServletWorkloadAs="hostname:1", this major name is diplayed: 3. For DisplayServletWorkloadAs="null:1", this major name is displayed: queryaccount 4. For DisplayServletWorkloadAs="hostname:0", this major name is displayed: Preparing the Instrumentation Control File for Workloads and Application Traces 133

134 Inside the User Instrumentation Control File 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. 134 OMEGAMON XE for WebSphere Application Server User s Guide, V130

135 Inside the User Instrumentation Control File To exclude specific methods from instrumentation, preceed the method name with an exclamation point. For example, to instrument all methods except those that begin with get or set, specfiy: MethodNames="*,!get*,!set*" MethodType This keyword indicates the type of methods that should be instrumented with the class or classes. The valid values are shown below. There is no default value. Use commas to separate multiple values for this keyword. Value CTG EJB JCA JMS JNDI JTS METHODS PORTLET SERVLET SOCKET SQL Meaning Indicates that CICS Transaction Gateway-related methods should be instrumented. Indicates that EJB-related methods should be instrumented Indicates that JCA-related methods should be instrumented Indicates that JMS-related methods should be instrumented Indicates that JNDI-related methods should be instrumented Indicates that methods relating to the Java Transaction Service (JTS) should be instrumented Indicates that method names explicitly specified by the MethodNames keyword are to be instrumented Indicates that portlet-related methods should be instrumented. Indicates that servlet-related methods should be instrumented Indicates that socket-related methods should be instrumented Indicates that JDBC-related methods should be instrumented The MethodType keyword must contain the METHODS value in order for the MethodNames keyword to be specified. Preparing the Instrumentation Control File for Workloads and Application Traces 135

136 Inside the User Instrumentation Control File Keywords for the Workload tag The 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 tag Each 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. 136 OMEGAMON XE for WebSphere Application Server User s Guide, V130

137 Inside the User Instrumentation Control File Methods This keyword identifies one or more method name masks separated by commas or semicolons. Each method name mask can contain the asterisk (*) and question mark (?) wildcard characters. Any method name whose class matches the Name attribute and whose method name matches one of the entries in the Methods attribute represents an execution of the workload. Example of the Workload tag <Workload MajorName="StrutsInputAction" MinorName="StrutsApp"> <Workload_Class Name="org.struts.example.StrutsInputAction" Methods="perform,execute"/> </Workload> Keywords for the Delay tag The 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. Preparing the Instrumentation Control File for Workloads and Application Traces 137

138 Inside the User Instrumentation Control File 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 tag Each 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. 138 OMEGAMON XE for WebSphere Application Server User s Guide, V130

139 Inside the User Instrumentation Control File About data collection After 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) Preparing the Instrumentation Control File for Workloads and Application Traces 139

140 Inside the User Instrumentation Control File 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 Specify the location of the CtgDelayPlugin classfile using the UserClassPath keyword for the KWEINSTR tag. For more information, see UserClassPath on page OMEGAMON XE for WebSphere Application Server User s Guide, V130

141 Inside the User Instrumentation Control File Example: CtgDelayPlugin="MyCtgDelayPlugin" UserClassPath="C:/Candle/CMA" Preparing the Instrumentation Control File for Workloads and Application Traces 141

142 Inside the User Instrumentation Control File 142 OMEGAMON XE for WebSphere Application Server User s Guide, V130

143 5 Collecting Workload Analysis, Application Trace, and Heap Data Overview This 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 Background Moving on: the workload analysis Take Action commands Launching the Class Loader Script for Workload Analysis Run the class loader setup script For Windows systems For UNIX systems Changing the WebSphere Application Server Configuration Step 1. Change the application server configuration Manual method: using the WebSphere administrative console for V4 standalone application servers Manual method: using the WebSphere administrative console for V4 cloned application servers Manual method: using the WebSphere administrative console for V4 server groups implementing vertical scaling Manual method: using the WebSphere administrative console for V Examples Dynamic method: using CandleNet Portal Step 2. Recycle the application server Collecting Workload Analysis, Application Trace, and Heap Data 143

144 Collecting Specific Workload Analysis Data for Different Application Servers Background Create separate instrumentation files Modify the WebSphere Application Server command-line settings Creating Specific Agent Control Files for Different Agents Background Create separate agent configuration files Specifying an alternate agent configuration file Dynamic method: using CandleNet Portal Manual method: using the WebSphere administrative console OMEGAMON XE for WebSphere Application Server User s Guide, V130

145 Workload Analysis, Application Traces, and Instrumentation Workload Analysis, Application Traces, and Instrumentation Overview This 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 responsetime 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. Background Follows 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). Collecting Workload Analysis, Application Trace, and Heap Data 145

146 Workload Analysis, Application Traces, and Instrumentation 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. 146 OMEGAMON XE for WebSphere Application Server User s Guide, V130

147 Workload Analysis, Application Traces, and Instrumentation Moving on: the workload analysis Take Action commands See 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 monitorcontention analysis levels and the minimum cost threshold for a particular application server Collecting Workload Analysis, Application Trace, and Heap Data 147

148 Launching the Class Loader Script for Workload Analysis Launching the Class Loader Script for Workload Analysis Overview This 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 script Use 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. 148 OMEGAMON XE for WebSphere Application Server User s Guide, V130

149 Launching the Class Loader Script for Workload Analysis You should see the following message if the setupcandlewaenabler.sh script finishes successfully: ====================================== Candle Workload Analysis setup finished successfully. Please follow the Installation Manual to update your WebSphere Application Server configuration to enable Candle 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. Collecting Workload Analysis, Application Trace, and Heap Data 149

150 Changing the WebSphere Application Server Configuration Changing the WebSphere Application Server Configuration Introduction This 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 configuration To enable workload analysis for the agent, you need to change the WebSphere Application Server configuration. You can use either of the following methods to do this. Dynamic: Use the agent s Configuration Setup Take Action command to modify the WebSphere Application Server configuration parameters. See Dynamic method: using CandleNet Portal on page 156. Candle recommends you use the Configuration Setup Take Action command whenever feasible, as it eliminates much reconfiguration work. Manual: Use one of the methods below to modify the WebSphere Application Server configuration parameters. Manual method: using the WebSphere administrative console for V4 stand-alone application servers Use these steps to modify the configuration setting for a stand-alone application server to enable the collection of workload analysis and trace data. 1. Access the WebSphere administrative console. 2. In the WebSphere administrative console navigation tree, choose the application server you want. 3. Choose the JVM Settings tab and the Advanced JVM Settings button to display the data entry area. 150 OMEGAMON XE for WebSphere Application Server User s Guide, V130

151 Changing the WebSphere Application Server Configuration 4. Locate the Command line arguments field for the application server. Note: Type the command arguments that are described in the following steps on the same line and separate them with a space. See the format for Examples on page 156. A. Next, enter the appropriate information for your OMEGAMON XE agent. Modify the configuration information as indicated by the black text. -Dcom.candle.kwe.instrument.user_control_file=<name of the main instrumentation control file> For Windows, the file name is usually C:\Candle\CMA\<kweiuser.xml> For UNIX, the file name is usually $CANDLEHOME$/config/<kweiuser.xml> where <kweiuser.xml> is a Candle-provided or custom kweiuser.xml file. (See Sample kweiuser.xml files on page 121.) -Dcom.candle.kwe.instrument.agent_parms=<full path name of the kweagent control file> For Windows, the file name is usually C:\Candle\CMA\kwe.xml For UNIX, the file name is usually $CANDLEHOME$/config/kwe.xml B. Add the following configuration information to the Boot classpath (prepend): field on the Advanced JVM Settings dialog. This file was created when you ran the Candle class loader setup script (see Launching the Class Loader Script for Workload Analysis on page 148). For Windows, enter: C:\Candle\CMA\<kwescl.*.jar>;C:\Candle\CMA\kwewa.jar For UNIX systems, enter: $CANDLEHOME$/classes/<kwescl.*.jar>:$CANDLEHOME$/classes/kwewa.jar Note: The name of the kwescl.*.jar file shown above depends upon your site s version of the JDK; the actual JDK version number replaces the asterisk (*). For example, the name of this file in a WebSphere Application Server V4.0.3 environment for Windows is kwescl jar. 5. If you choose to enable collection of garbage-collection statistics, activate the Enable garbage collection verbose mode option. Collecting Workload Analysis, Application Trace, and Heap Data 151

152 Changing the WebSphere Application Server Configuration 6. Click the Apply button. Manual method: using the WebSphere administrative console for V4 cloned application servers Use these steps to modify the configuration setting for an application server that belongs to a server group to enable the collection of workload analysis and trace data. Note: You must follow these steps for horizontally cloned application servers. You may also use these steps to modify configuration setting for a vertical clone. 1. Access the WebSphere administrative console. 2. From the WebSphere administrative console s navigation tree, choose the application server you want. 3. Select the JVM Settings tab, and, within the System Properties pane, press the Add button to define the following two system properties: A. Enter com.candle.kwe.instrument.user_control_file in the Name field. B. Enter <name of the main instrumentation control file> in the Value field. For Windows, the file name is usually C:\Candle\CMA\<kweiuser.xml>. For UNIX, the file name is usually $CANDLEHOME$/config/<kweiuser.xml>. where <kweiuser.xml> is a Candle-provided or custom kweiuser.xml file. (See Sample kweiuser.xml files on page 121.) 4. Press the Add button, and then define the following two additional system properties: A. Enter com.candle.kwe.instrument.agent_parms in the Name field. B. Enter <full path name of the kweagent control file> in the Value field. For Windows, the file name is usually C:\Candle\CMA\kwe.xml. For UNIX, the file name is usually $CANDLEHOME$/config/kwe.xml. 5. Press the Advanced JVM Settings button, and add the following jar files to the Boot classpath (prepend) field: For Windows: C:\Candle\CMA\<kwescl.*.jar>;C:\Candle\CMA\kwewa.jar 152 OMEGAMON XE for WebSphere Application Server User s Guide, V130

153 Changing the WebSphere Application Server Configuration For Unix: $CANDLEHOME/classes/<kwescl.*.jar>:$CANDLEHOME$/classes/kwewa.jar Note: The name of the kwescl.*.jar file shown above depends upon your site s version of the JDK; the actual JDK version number replaces the asterisk (*). For example, the name of this file in a WebSphere Application Server V4.0.3 environment for Windows is kwescl jar. Manual method: using the WebSphere administrative console for V4 server groups implementing vertical scaling Use these steps to modify the configuration setting for a vertical server group to enable the collection of workload analysis and trace data for all the application servers that belong to the group. 1. Access the WebSphere administrative console. 2. From the WebSphere administrative console s navigation tree, select the ServerGroup you want. 3. Press the Advanced JVM Settings button. The Advanced JVM Settings dialog appears. 4. Locate the Command Line Arguments field and enter the appropriate configuration settings for workload analysis and verbose garbage collection: For Windows: -Xbootclasspath/p:C:\Candle\CMA\kwescl.*.jar;C:\Candle\CMA\kwewa.jar -Dcom.candle.kwe.instrument.user_control_file=<name of the main instrumentation control file> -Dcom.candle.kwe.instrument.agent_parms=<full path name of the kweagent control file> -verbosegc On Windows, <name of the main instrumentation control file> is usually C:\Candle\CMA\<kweiuser.xml>, whereas <full path name of the kweagent control file> is usually C:\Candle\CMA\kwe.xml. where <kweiuser.xml> is a Candle-provided or custom kweiuser.xml file. (See Sample kweiuser.xml files on page 121.) Collecting Workload Analysis, Application Trace, and Heap Data 153

154 Changing the WebSphere Application Server Configuration For Unix: -Xbootclasspath/p:$CANDLEHOME$/classes/kwescl.*.jar: $CANDLEHOME$/classes/kwewa.jar -Dcom.candle.kwe.instrument.user_control_file=<name of the main instrumentation control file> -Dcom.candle.kwe.instrument.agent_parms=<full path name of the kweagent control file> -verbosegc where $CANDLEHOME is the OMEGAMON XE agent installation directory. On UNIX, <name of the main instrumentation control file> is usually $CANDLEHOME$/config/<kweiuser.xml>, whereas <full path name of the kweagent control file> is usually $CANDLEHOME$/config/kwe.xml. where <kweiuser.xml> is a Candle-provided or custom kweiuser.xml file. (See Sample kweiuser.xml files on page 121.) Notes: 1. The name of the kwescl.*.jar file shown above depends upon your site s version of the JDK; the actual JDK version number replaces the asterisk (*). This file was created when you ran the Candle class loader setup script; see Launching the Class Loader Script for Workload Analysis on page The -verbosegc parameter is required if your site is accumulating garbage-collection statistics; see Your Agent s Configuration Parameters and XML Tags on page Press the OK button to close the Advanced JVM Settings dialog. 6. Press the Apply button to save and propagate the settings to all clones of this server group. Manual method: using the WebSphere administrative console for V5 Follow these steps to modify the configuration setting for an application server to enable the collection of workload analysis and trace data. 1. Access the WebSphere administrative console. 2. Expand the WebSphere administrative console navigation tree: in the lefthand window, click the + sign. 3. Select Application Servers. 154 OMEGAMON XE for WebSphere Application Server User s Guide, V130

155 Changing the WebSphere Application Server Configuration 4. In the righthand window, choose the application server whose configuration you want to modify. 5. In the resulting screen, select the Configuration tab. 6. From the Additional Properties area, select Process Definition. 7. In the resulting screen, under Additional Properties, select Java Virtual Machine. You must modify these fields in the General Properties area of the next screen: A. The first field you modify is Boot classpath. Add the following configuration information. For Windows, enter: C:\Candle\CMA\<kwescl.*.jar>;C:\Candle\CMA\kwewa.jar For UNIX systems, enter: $CANDLEHOME$/classes/<kwescl.*.jar>:$CANDLEHOME$/classes/kwewa.jar Note: The name of the kwescl.*.jar file shown above depends upon your site s version of the JDK; the actual JDK version number replaces the asterisk (*). For example, the name of this file in a WebSphere Application Server V5 environment for Windows is kwescl jar. This file was created when you ran the Candle class loader setup script; see Launching the Class Loader Script for Workload Analysis on page 148. B. Next, update the Generic JVM arguments field with the appropriate information for your OMEGAMON XE agent, as follows: -Dcom.candle.kwe.instrument.user_control_file=<file name of the main instrumentation control file> For Windows, this file name is usually C:\Candle\CMA\<kweiuser.xml>. For UNIX, this file name is usually $CANDLEHOME$/config/<kweiuser.xml>. where <kweiuser.xml> is a Candle-provided or custom kweiuser.xml file. (See Sample kweiuser.xml files on page 121.) -Dcom.candle.kwe.instrument.agent_parms=<full path name of the kweagent control file> Collecting Workload Analysis, Application Trace, and Heap Data 155

156 Changing the WebSphere Application Server Configuration For Windows, this file name is usually C:\Candle\CMA\kwe.xml For UNIX, this file name is usually $CANDLEHOME$/config/kwe.xml C. If you choose to enable collection of garbage-collection statistics, activate the Verbose garbage collection option. 8. Click the Apply button. 9. To save your updates, click the Save hyperlink. Examples Windows example: -Dcom.candle.kwe.instrument.user_control_file=C:\Candle\CMA\kweiuser_development.xml -Dcom.candle.kwe.instrument.agent_parms=C:\Candle\CMA\kwe.xml UNIX example: -Dcom.candle.kwe.instrument.user_control_file=/candle/config/kweiuser_production.xml -Dcom.candle.kwe.instrument.agent_parms=/candle/config/kwe.xml Dynamic method: using CandleNet Portal Use this procedure to issue the Configuration Setup Take Action command in CandleNet Portal. This command alters the WebSphere Application Server configuration so that the workload analysis feature (including the heap usage and garbage-collection components) will be active in the application server the next time it starts. (You must have previously defined your workloads in kweiuser.xml and run the class loader setup script, setupcandlewaenabler.) 1. In the Navigator, select and then right-click a WebSphere Application Server subnode, and choose Take Action from the pop-up menu. 2. In the Take Action dialog box, scroll through the Name box until you reach the WAS Configuration Setup command. 156 OMEGAMON XE for WebSphere Application Server User s Guide, V130

157 Changing the WebSphere Application Server Configuration 3. Complete the fields in the Edit Argument Values dialog box that opens. Table 4 summarizes these fields. Table 4. Configuration Setup Take Action Command: Edit Argument Values Window Argument Workload_Analysis_Y_or_N=<{Y N}> VerboseGC_Y_or_N=<{Y N}> File=<kweiuser.xml file name> Value Explanation Do you want the server to collect workload analysis data? Type Y for yes or N for no. Do you want the server to collect garbagecollection data? Type Y for yes or N for no. <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 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. Collecting Workload Analysis, Application Trace, and Heap Data 157

158 Changing the WebSphere Application Server Configuration Step 2. Recycle the application server After 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. 158 OMEGAMON XE for WebSphere Application Server User s Guide, V130

159 Collecting Specific Workload Analysis Data for Different Application Servers Collecting Specific Workload Analysis Data for Different Application Servers Background To 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 files Do 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 settings When you want to collect data for an application server that requires an alternate version of the kweiuser.xml instrumentation file, you need to modify the WebSphere Application Server command-line settings to point to this alternative file: 1. Specify the JVM settings: Complete Step 1. Change the application server configuration on page 150 under section Changing the WebSphere Application Server Configuration. 2. Bring up the WebSphere administrative console. Collecting Workload Analysis, Application Trace, and Heap Data 159

160 Collecting Specific Workload Analysis Data for Different Application Servers 3. Modify the statement -Dcom.candle.kwe.instrument.control_file in the JVM Command line arguments field as follows: For Windows systems, enter: -Dcom.candle.kwe.instrument.control_file=C:\Candle\CMA\alternate_kweiuser.xml For UNIX systems, enter: -Dcom.candle.kwe.instrument.control_file=$CANDLEHOME$/config/alternate_kweiuser.xml where alternate_kweiuser.xml is the name you selected for the alternate instrumentation file in step OMEGAMON XE for WebSphere Application Server User s Guide, V130

161 Creating Specific Agent Control Files for Different Agents Creating Specific Agent Control Files for Different Agents Background To 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 files Create 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. Collecting Workload Analysis, Application Trace, and Heap Data 161

162 Creating Specific Agent Control Files for Different Agents 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 162 OMEGAMON XE for WebSphere Application Server User s Guide, V130

163 Creating Specific Agent Control Files for Different Agents Specifying an alternate agent configuration file When you want to customize an OMEGAMON XE agent s kwe.xml configuration file, you need to modify the WebSphere Application Server command-line settings to point to the alternate file. Dynamic method: using CandleNet Portal 1. Use CandleNet Portal s Configuration Setup Take Action command to alter the WebSphere Application Server configuration to support the agent's workload analysis and garbage-collection features: Complete Dynamic method: using CandleNet Portal on page 156 under section Changing the WebSphere Application Server Configuration. Manual method: using the WebSphere administrative console 1. Alter the WebSphere Application Server configuration to support the agent's workload analysis component: Based on your site s WebSphere Application Server version, complete one of the manual methods given in Step 1. Change the application server configuration on page 150 under section Changing the WebSphere Application Server Configuration. 2. Start the WebSphere administrative console. 3. Modify the statement -Dcom.candle.kwe.instrument.agent_parms in either the JVM Command line arguments field (for WebSphere Application Server V4.0) or the Generic JVM arguments field (for WebSphere Application Server V5.0) as follows: For Windows systems, enter: -Dcom.candle.kwe.instrument.agent_parms=C:\Candle\CMA\kwe_<AGENTID>.xml For UNIX systems, enter: -Dcom.candle.kwe.instrument.agent_parms= $CANDLEHOME$/config/kwe_<AGENTID>_##_<HOSTNAME>.xml where <AGENTID> is the agent ID and <HOSTNAME> is the name of the host system. Collecting Workload Analysis, Application Trace, and Heap Data 163

164 Creating Specific Agent Control Files for Different Agents 164 OMEGAMON XE for WebSphere Application Server User s Guide, V130

165 6 Introducing OMEGAMON XE for WebSphere Application Server Information Overview This 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 Using OMEGAMON XE for WebSphere Application Server information Associating table views and charts with attributes Data in the table views and charts Synchronizing data in reports Accessing the OMEGAMON XE for WebSphere Application Server Information. 169 Accessing workspaces Historical Reporting Workspaces with historical data links Requirements for historical data collection OMEGAMON XE for WebSphere Application Server Workspaces Available workspaces Introducing OMEGAMON XE for WebSphere Application Server Information 165

166 OMEGAMON XE for WebSphere Application Server Data OMEGAMON XE for WebSphere Application Server Data Introduction The 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 information OMEGAMON 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 166 OMEGAMON XE for WebSphere Application Server User s Guide, V130

167 OMEGAMON XE for WebSphere Application Server Data Associating table views and charts with attributes There 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 charts The 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 Introducing OMEGAMON XE for WebSphere Application Server Information 167

168 OMEGAMON XE for WebSphere Application Server Data 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 reports You 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. 168 OMEGAMON XE for WebSphere Application Server User s Guide, V130

169 Accessing the OMEGAMON XE for WebSphere Application Server Information Accessing the OMEGAMON XE for WebSphere Application Server Information Accessing workspaces To 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. Introducing OMEGAMON XE for WebSphere Application Server Information 169

170 Accessing the OMEGAMON XE for WebSphere Application Server Information Figure 9. Navigator Items for the OMEGAMON XE for WebSphere Application Server V130 Agent 170 OMEGAMON XE for WebSphere Application Server User s Guide, V130

171 Historical Reporting Historical Reporting Workspaces with historical data links Most 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 collection To 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. Introducing OMEGAMON XE for WebSphere Application Server Information 171

172 OMEGAMON XE for WebSphere Application Server Workspaces OMEGAMON XE for WebSphere Application Server Workspaces Overview The 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 workspaces OMEGAMON 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. 172 OMEGAMON XE for WebSphere Application Server User s Guide, V130

173 OMEGAMON XE for WebSphere Application Server Workspaces All Workloads*: The All Workloads workspace contains information about all workloads that were executed during the interval. Suspected Memory Leaks*: The Suspected Memory Leaks workspace helps you identify workloads consuming excessive memory due to memory leaks in your applications. Heap Usage*: The Heap Usage workspaces provide statistics about attempts by applications running in the Java Virtual Machine to allocate object space on the heap. Garbage Collector Activity*: The JVM Garbage Collector Activity workspace displays garbage collection information for each JVM running an application server and graphic views of the number of garbage collections and percent of CPU used. This workspace monitors the overhead associated with running the garbage collector. Pool Utilization*: The Pool Utilization workspace displays information about the usage of several types of WebSphere Application Server pools, including Web container, ORB, J2C connection, and database connection. In-flight Workloads: The In-flight Workloads allow you to watch applications as they run in the Java Virtual Machine; this can help you isolate workloads that are hung up and consuming excessive CPU time. Longest Running Workloads*: The Longest Running Workloads workspace reports detailed information delay times for the longest running individual workload executions. HTTP Sessions*: The HTTP Sessions workspace reports information about active HTTP sessions for an application server. Datasources*: The Datasources workspace provides database usage information. Lock Analysis: The Lock Analysis workspace displays summary information by class and method regarding resources that have been locked by WebSphere Application Server. CTG Summary: The CTG Summary workspaces provide information about transactions running against the CICS Transaction Gateway, which provides WebSphere Application Server programmers access to legacy CICS applications. Introducing OMEGAMON XE for WebSphere Application Server Information 173

174 OMEGAMON XE for WebSphere Application Server Workspaces 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. 174 OMEGAMON XE for WebSphere Application Server User s Guide, V130

175 OMEGAMON XE for WebSphere Application Server Workspaces Workload Management: The Workload Management workspace displays information about the Workload Management (WLM) server and the client that initiate workload requests. Workload management optimizes the distribution of client processing tasks. Incoming work requests are distributed to the application servers, enterprise beans, servlets, and other objects that process the requests. WebSphere Application Server implements workload management by using clusters, transports, and replication domains. * A history view of this workspace is also supplied. Introducing OMEGAMON XE for WebSphere Application Server Information 175

176 OMEGAMON XE for WebSphere Application Server Workspaces 176 OMEGAMON XE for WebSphere Application Server User s Guide, V130

177 7 The CandleNet Portal Take Action Commands Overview This 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 About Take Action commands Prerequisite Who can issue Take Action commands? Available Take Action commands Initiating Take Action commands Using Take Action Commands in Situations The CandleNet Portal Take Action Commands 177

178 Introduction Introduction About Take Action commands OMEGAMON 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 garbagecollection 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. Prerequisite You 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 178 OMEGAMON XE for WebSphere Application Server User s Guide, V130

179 Introduction See Setting Configuration Parameters, Environmental Variables, and Instrumentation Levels on page 81 for details on these parameters. Available Take Action commands OMEGAMON 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 WAS Start Application Server WAS Stop Application Server WAS Recycle Application Server WAS Configuration Setup WAS SetIL WAS SetIL - All WAS SetIL - Dynamic Cache WAS SetIL - HTTP Session WAS SetIL - JVMMemory WAS SetIL - J2C Pool WAS SetIL - Object Pool Use Start an application server Stop an application server Stop and restart an application server Change an application server s configuration to perform workload analysis and, possibly, collect garbage-collection statistics as well Set instrumentation levels for WebSphere Application Server resources to collect performance data Set a single instrumentation level for all WebSphere Application Server resources Set the PMI instrumentation level for dynamic caching activities Set the instrumentation level for the HTTP sessions for the servlet engine Set the instrumentation level for the Java Virtual Machine running the application server 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 Set instrumentation level for the bean object pool and specify arguments for the instrumentation level, container name, and bean name The CandleNet Portal Take Action Commands 179

180 Introduction Table 5. Take Action Commands for the OMEGAMON XE Agent WAS SetIL - ORB Command WAS SetIL - Orb Thread Pool WAS SetIL - Servlet Sessions WAS SetIL - ThreadPool WAS SetIL - WCThread Pool WAS SetIL - WebApplicationSubModule WAS SetIL - Workload Management Client WAS SetIL - Workload Management Server WAS Dynamic Workload Analysis WAS Set Workload Exception Thresholds WAS Start Heap Collection WAS Verbose GC Collection WAS Set Capture Percent WAS Set In-flight Threshold WAS Set Longest Running Workload Threshold Use Set the PMI instrumentation level for the object request brokers (ORBs) Set the instrumentation level for the ORB thread pools Set the PMI instrumentation level for servlet sessions Set the instrumentation level for the container thread pool Set the instrumentation level for the Web container thread pool Set the instrumentation level for servlets/jsps for a Web application Set the PMI instrumentation level for workload management clients Set the PMI instrumentation level for workload management servers Start or stop collecting workload analysis data Define thresholds for collecting exception transactions Start or stop collecting heap data for a particular application server. Stop and start the collection of garbagecollection statistics Set the percentage of workload and heapallocation invocations the workload analysis component should collect. Define the CPU time threshold below which inflight workloads are not reported. Define the threshold for the collection and reporting of exceptional transaction data 180 OMEGAMON XE for WebSphere Application Server User s Guide, V130

181 Introduction Table 5. Take Action Commands for the OMEGAMON XE Agent Command WAS Set Lock Analysis Level WAS Start Application Tracing WAS Stop Application Tracing WAS Delete Application Tracing Files WAS Dynamic Refresh Instrumentation WAS Discover Servers Use Set monitor-contention analysis levels and the minimum cost threshold for a particular application server Start application tracing. Stop application tracing. Delete application trace files. Force the Workload Analysis component to reread the instrumentation control file, kweiuser.xml Force the agent to discover newly defined application servers prior to the regularly scheduled discovery. (Auto-discovery currently runs every 15 minutes.) The CandleNet Portal Take Action Commands 181

182 Introduction Initiating Take Action commands These 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. 182 OMEGAMON XE for WebSphere Application Server User s Guide, V130

183 Using Take Action Commands in Situations Using Take Action Commands in Situations Introduction You 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. Procedure To 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. The CandleNet Portal Take Action Commands 183

184 Using Take Action Commands in Situations 184 OMEGAMON XE for WebSphere Application Server User s Guide, V130

185 A A Sample WebSphere Application Server Application: Best Practices Introduction Contents This 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. Overview Installing the Best Practices Samples Installation prerequisites DB2 database requirements WebSphere Application Server requirements Performing the installation Step 1. Install the CANDLEBP database Step 2. Define the CandleDS datasource Step 3. Install the Best Practices application Trouble-shooting the Best Practices installation Configuring OMEGAMON XE for WebSphere Application Server for the Best Practices Samples Executing the Best Practices Samples Before you invoke the application Running the Best Practices samples The Best Practices Web interface Uninstalling the Best Practices Samples Step 1. Uninstall the Best Practices application Step 2. Remove the CandleDS datasource Step 3. Remove the CANDLEBP database Appendix A: A Sample WebSphere Application Server Application: Best Practices 185

186 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 AIMBP002 AIMBP004 AIMBP005 Title and Principle Illustrated Better String Concatenation Illustrates the performance advantage of using StringBuffer (rather than the + operator) to concatenate strings. 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. 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 V OMEGAMON XE for WebSphere Application Server User s Guide, V130

187 Overview Table 6. Candle s Best Practices Source Fragments for Java Programming Name AIMBP006 AIMBP011 AIMBP032 AIMBP033 AIMBP036 Title and Principle Illustrated 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. 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. 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. 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. 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. Appendix A: A Sample WebSphere Application Server Application: Best Practices 187

188 Overview Table 6. Candle s Best Practices Source Fragments for Java Programming Name AIMBP039 AIMBP056 Title and Principle Illustrated 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. 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. 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. 188 OMEGAMON XE for WebSphere Application Server User s Guide, V130

189 Installing the Best Practices Samples Installing the Best Practices Samples Installation prerequisites The 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. Appendix A: A Sample WebSphere Application Server Application: Best Practices 189

190 Performing the installation 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 Step 2. Define the CandleDS datasource Step 3. Install the Best Practices application 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 database This 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. 190 OMEGAMON XE for WebSphere Application Server User s Guide, V130

191 Performing the installation 3. To create and populate the CANDLEBP database, invoke the edited SQL file: db2cmd /c /w /i db2 -tf C:\Candle\CMA\samples\j2ee_best_practices\websphere\ database\candlebpinstall.sql Note: The first time you build the database you will receive this error: SQL1013N The database alias name or database name "CANDLEBP" could not be found. SQLSTATE=42705 Ignore this message. Skip to Step 2. Define the CandleDS datasource on page 193. UNIX sites: 1. To set environment variables and enable the DB2 command line processor, invoke this command: <db2home>/<db2instance>/sqllib/db2profile This procedure sets the following environment variables and values change as per your DB2 instance directory: PATH= /home/db2inst1/sqllib/bin:/home/db2inst1/sqllib/adm:/home/db2inst1/sqllib/misc CLASSPATH=/home/db2inst1/sqllib/function:/home/db2inst1/sqllib/java/db2java.zip: /home/db2inst1/sqllib/java/runtime.zip:. DB2INSTANCE=db2inst1 SHLIB_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: aix433 for HP-UX: hp11 for Linux on Intel: li6243 Appendix A: A Sample WebSphere Application Server Application: Best Practices 191

192 Performing the installation for Linux on zseries: ls3223 for 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 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. 192 OMEGAMON XE for WebSphere Application Server User s Guide, V130

193 Performing the installation Step 2. Define the CandleDS datasource This 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. Appendix A: A Sample WebSphere Application Server Application: Best Practices 193

194 Performing the installation Figure 10. Data Source Properties window 4. Fill in this panel as follows: Name: CandleDS JNDI Name: CandleDS <this parameter is case sensitive> Description: To access CANDELBP database databasename: CANDLEBP user: <DB2 user name to access the CANDLEBP database> password: <DB2 password to access the specified user name> 194 OMEGAMON XE for WebSphere Application Server User s Guide, V130

195 Performing the installation 5. Test the new database connection: press the Test Connection button. If this test fails, reenter the database values, and retest the connection. 6. Press the OK button. The CandleDS datasource is created. Continue with Install the Best Practices application on page 203. WebSphere Application Server V5 sites: UNIX users: Before beginning the datasource definition, you must set the proper DB2 environment variables: rerun db2profile from the same prompt where you started WebSphere Application Server; then start or restart the WebSphere Application Server V5 server. db2profile is located in <db2home>/<db2instance>/sqllib/db2profile. Either rerun db2profile whenever you start or restart the WebSphere server, or add this command to your own startup profile so it runs automatically whenever you log in. 1. Open the WebSphere administrative console. 2. Select Environment > Manage WebSphere Variables, and ensure that the DB2_JDBC_DRIVER_PATH variable has a value. This variable must include the path containing the JDBC driver (db2java.zip). If this variable is undefined or doesn t have the proper value, select the DB2_JDBC_DRIVER_PATH link, and enter the location of db2java.zip. This is typically the <db2instancedirectory>\sqllib\java directory (for Windows) or the <db2home>/<db2instance>/sqllib/java12 directory (for UNIX). Notes: 1. UNIX users: Two java directories are available in <db2home>/<db2instance>/sqllib, one for java and one for java12. Both directories contain file db2java.zip (with their own JDBC drivers), so be careful when you set this value. You must use the java12 directory to leverage the Java 2 JDBC drivers. 2. If you are using the Network Deployment console to deploy the application and find that you have two database servers, one in a base server node and the other in a Network Deployment server node, this path should be the database path that communicates with the base server, since the application is deployed in the base server. Appendix A: A Sample WebSphere Application Server Application: Best Practices 195

196 Performing the installation 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: BPAlias User ID: <DB2 user name to access the CANDLEBP database> Password: <DB2 password to access the specified user name> 196 OMEGAMON XE for WebSphere Application Server User s Guide, V130

197 Performing the installation C. Press the Apply button. D. When prompted, save the master configuration. 4. Ensure the JDBC provider has been created: Select Resources > JDBC Providers, and see whether the DB2 JDBC Provider (or, for WebSphere Application Server V5.1, the DB2 Legacy CLI-based Type 2 JDBC Driver) is listed among the DB2 databases in the JDBC Providers section. If it is, skip to part 5. on page 199; if not, you must create it: A. If you are using a Network Deployment console, first set the scope of the base server and its node since you are going to deploy the Best Practices application in the base server rather than Network Deployment server (see Figure 12 on page 198): Appendix A: A Sample WebSphere Application Server Application: Best Practices 197

198 Performing the installation Figure 12. JDBC Providers screen 198 OMEGAMON XE for WebSphere Application Server User s Guide, V130

199 Performing the installation a. Press the Browse Nodes button, and select the appropriate node. b. Press the Browse Servers button, and select the apprpriate server. c. Press the Apply button. B. Press the New button, and select DB2 JDBC Provider (or, for WebSphere Application Server V5.1, the DB2 Legacy CLI-based Type 2 JDBC Driver) from the dropdown list. C. Press the Apply button. The general properties of the DB2 JDBC Provider appear. D. Press the Apply button to create either the DB2 JDBC Provider or the DB2 Legacy CLI-based Type 2 JDBC Driver. E. Save both the local and master configuration. 5. Create the datasource: A. Select Resources > JDBC Providers, and select either the DB2 JDBC Provider or DB2 Legacy CLI-based Type 2 JDBC Driver link. B. Scroll to the bottom of the screen, and select the Data Sources link. C. Press the New button. The datasource parameters screen, shown in Figure 13 on page 200, appears. Appendix A: A Sample WebSphere Application Server Application: Best Practices 199

200 Performing the installation Figure 13. Datasource parameters screen D. Fill in this panel as follows: Name: CandleDS JNDI Name: CandleDS <case sensitive> Container manager persistence: <activate this check box> Description: datasource to access CANDLEBP database 200 OMEGAMON XE for WebSphere Application Server User s Guide, V130

201 Performing the installation Datasource Helper Classname: <accept the default class name com.ibm.websphere.rsadapter.db2datastorehelper; this class name should appear as the default; if not, supply it> Component-managed Authentication Alias: BPAlias Container-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). Appendix A: A Sample WebSphere Application Server Application: Best Practices 201

202 Performing the installation Figure 14. databasename screen C. Press the Apply button. D. Save both the local and master configuration. The CandleDS datasource is created. 202 OMEGAMON XE for WebSphere Application Server User s Guide, V130

203 Performing the installation Step 3. Install the Best Practices application This procedure is separated by WebSphere Application Server version. Version 5 users, see page 208. WebSphere Application Server V4 users: 1. Ensure the WebSphere administrative server is running. 2. Open the WebSphere administrative console. 3. Select the Enterprise Applications tab. 4. Right-click on Enterprise Applications, and select Install Enterprise Application from the pop-up menu. You are prompted to choose an ear file. 5. Press the Install Application (*ear) radio button; then press the Browse button to choose an ear file 6. Locate the BP40.ear file. For Windows, this files in located in: c:\candle\cma\samples\j2ee_best_practices\websphere\was4 UNIX users, look in: $CANDLEHOME$/<platform>/samples/j2ee_best_practices/websphere/ was4 where <platform> is one of: for AIX: aix433 for HP-UX: hp11 for Linux on Intel: li6243 for Linux on zseries: ls3223 for Solaris: sol The Install Enterprise Application Wizard, shown in Figure 15 on page 204, appears. Appendix A: A Sample WebSphere Application Server Application: Best Practices 203

204 Performing the installation 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 OMEGAMON XE for WebSphere Application Server User s Guide, V130

205 Performing the installation Figure 16. Selecting Application Servers screen 10. Select the BPEJB module, and press the Select Server button. The Select a Server or Server Group window, shown in Figure 17 on page 206, appears. Appendix A: A Sample WebSphere Application Server Application: Best Practices 205

206 Performing the installation 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. 206 OMEGAMON XE for WebSphere Application Server User s Guide, V130

207 Performing the installation Figure 18. Completing the Application Installation Wizard screen 14. Press the Finish button. A dialog box appears with message Application code necessary for installation has already been generated. Regenerate code now?. 15. Press the No button. The application is installed; when finished, a dialog box with message Command "EnterpriseApp.install" completed successfully appears. 16. Press the OK button. 17. Restart the default server (or whichever server you specified in part 11. on page 206). The Best Practices application is now installed. Appendix A: A Sample WebSphere Application Server Application: Best Practices 207

208 Performing the installation The CandleBP application is installed. WebSphere Application Server V5 users: 1. Open the WebSphere administrative console. 2. In the Environment > Manage WebSphere Variables screen, ensure environment variable APP_INSTALL_ROOT is set to ${USER_INSTALL_ROOT}/installedApps. 3. Select Applications > Enterprise Applications. 4. Press the Install button. You are prompted to choose an ear file (see Figure 19 on page 209). 208 OMEGAMON XE for WebSphere Application Server User s Guide, V130

209 Performing the installation Figure 19. Preparing for the application installation screen 5. If the ear file resides on the same machine as the browser, press the Local Path radio button, then press the Browse button, and locate the bp50.ear file, as Figure 19 illustrates. On the other hand, if the ear resides on any of the nodes in your cell context, press the Server Path radio button, and enter the path. For Windows this is: C:\Candle\CMA\samples\j2ee_best_practices\websphere\was5\BP50.ear For UNIX this is: $CANDLEHOME$/<platform>/samples/j2ee_best_practices/websphere/ was5/bp50.ear Appendix A: A Sample WebSphere Application Server Application: Best Practices 209

210 Performing the installation where <platform> is one of: for AIX: aix433 for HP-UX: hp11 for Linux on Intel: li6243 for Linux on zseries: ls3223 for Solaris: sol 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. 210 OMEGAMON XE for WebSphere Application Server User s Guide, V130

211 Performing the installation Figure 20. Installation Options installation step Appendix A: A Sample WebSphere Application Server Application: Best Practices 211

212 Performing the installation 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: CandleBP Pre-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. 212 OMEGAMON XE for WebSphere Application Server User s Guide, V130

213 Performing the installation Figure 21. Provide Default Datasource Mapping installation step 6. Press the Next button. 7. Skip the subsequent steps (by pressing the Next button) until you reach the Map Resource References to Resources step (shown in Figure 22 on page 214). 8. At this step and again at the next step, Map Virtual Hosts for Web Modules (shown in Figure 23 on page 215), select the BestPractices module. Appendix A: A Sample WebSphere Application Server Application: Best Practices 213

214 Performing the installation Figure 22. Map Resource References installation step 214 OMEGAMON XE for WebSphere Application Server User s Guide, V130

215 Performing the installation Figure 23. Map Virtual Hosts installation step 9. In the Map Modules to Application Servers step (shown in Figure 24 on page 216), select modules BPEJB and BestPractices, then select server1, and press the Apply button. Appendix A: A Sample WebSphere Application Server Application: Best Practices 215

216 Performing the installation 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. 216 OMEGAMON XE for WebSphere Application Server User s Guide, V130