PathWAI Performance Analyzer, V110publib.boulder.ibm.com/tividd/td/ITPathPAnal/GC32-9341... · 2004. 8. 28. · Tips and Tricks..... 181 Changing Default Instrumentation Set ... PathWAI

Document Number GC32-9341-00

Version 1.3.0

Questions or comments about the User Guide? Let us know [email protected]

Copyright © 2003–2004 Candle Corporation, a Californiacorporation.

International copyrights secured.All rights reserved.

User’s Guide

mailto:[email protected]

PathWAITM Performance Analyzer User’s Guide, V1.3.0

Contents

Getting Started..............................................................................................5

Product Overview..........................................................................................7

Overview...................................................................................................8 Operating Environment ........................................................................... 8 Instrumented IBM Products ..................................................................... 9 Supported Trace File Imports................................................................... 9 Supported Instrumentation Control File Imports and Exports ........................ 9 Feedback .............................................................................................10

PathWAI Products...................................................................................11 What's New? ...........................................................................................14 Printed Documentation ...........................................................................19 Contact Us...............................................................................................20

Views ..........................................................................................................21

Default Perspective .................................................................................22 Customizing PathWAI Performance Analyzer Perspective.............................23

Control Views..........................................................................................24 Profiling Resources ................................................................................25 Profiling Monitor....................................................................................26

Data Views ..............................................................................................28 All Workloads Summary .........................................................................29 Selected Method Summary .....................................................................30 All Objects Summary .............................................................................31 Method Time Eye-catcher .......................................................................33 Workloads............................................................................................36 Method Calls.........................................................................................40 Methods...............................................................................................46 Threads ...............................................................................................52 Objects................................................................................................55 Object References .................................................................................60 Lock Contention ....................................................................................63 Call Tree ..............................................................................................68 Call Graph............................................................................................72

Concepts .....................................................................................................75

Workloads and Workload Analysis ..........................................................75

Copyright © 2003-2004 Candle Corporation, a California Corporation. International copyrights secured. All rights reserved.

Page 2


Using PathWAI Performance Analyzer ....................................................75

Tutorials......................................................................................................78

Tutorial 1: Analyzing a Long-Running Workload......................................79 Step 1. Open the PathWAI Performance Analyzer perspective ......................79 Step 2. Create a simple project ...............................................................79 Step 3. Import the sample trace..............................................................80 Step 4. Examine the trace and identify the problems..................................83

Tutorial 2: Identifying a Memory Leak and Its Cause ..............................86 Step 1. Import the live trace project ........................................................86 Step 2. Examine the object allocations and object references ......................87 Step 3. Following the references to find the root cause ...............................91

Tutorial 3: Looking for a Memory Leak in a Complex Application.............94 Step 1. Import the live trace project ........................................................94 Step 2. Examine the object allocations .....................................................95 Step 3. Examine the object references .....................................................98

Tutorial 4: Lock Contention ...................................................................102

Tasks.........................................................................................................103

Setting Preferences...............................................................................104 Appearance ........................................................................................ 105 Statistics............................................................................................ 106 If You Change Your Mind ...................................................................... 106

Importing and Viewing a Trace File.......................................................108 Importing an OMEGAMON XE Trace ....................................................... 109 Importing an IBM Profiler Trace............................................................. 115

Setting up and Running a Live Trace .....................................................123 Setting up PathWAI Profiling ................................................................. 124 Setting up a Monitor and Instrumenting a Server..................................... 127 Running a Live Trace ........................................................................... 131 Checking PathWAI Profiling................................................................... 135 Tracing a Test Server........................................................................... 137 Removing PathWAI Profiling.................................................................. 139

Managing Instrumentation....................................................................143 Instrumentation Editor......................................................................... 144 Creating and Modifying Instrumentation Sets .......................................... 151 Instrumenting System Classes .............................................................. 159 Importing and Exporting Instrumentation Sets ........................................ 168 Viewing Installed Instrumentation Sets .................................................. 171 Changing Instrumentation on Application Server...................................... 172 Deleting Instrumentation Sets............................................................... 174


Page 3


Troubleshooting ....................................................................................175

If PathWAI Performance Analyzer Becomes Unsynchronized ...................... 176 Dual Monitoring .................................................................................. 177 If Eclipse Runs out of Memory............................................................... 178 Collecting a PathWAI Performance Analyzer Trace.................................... 179

Tips and Tricks ..........................................................................................181

Changing Default Instrumentation Set..................................................182 Effectively Instrumenting System Classes.............................................183 Comparing Traces .................................................................................184 Identifying the Main Cause of a Long-Running Workload......................185 Spotting Contention among Concurrent Method Calls............................186 Spotting Parameter Value Problems......................................................187

Reference..................................................................................................188

Candle® PathWAITM Performance Analyzer ReleaseNotes, Version 1.3.0189 Operating Environment ........................................................................ 189 Instrumented IBM Products .................................................................. 191 Supported Trace File Imports................................................................ 191 Supported Instrumentation Control File Imports and Exports ..................... 191 Warnings and Workarounds .................................................................. 191 Installation Instructions ....................................................................... 192 Online help......................................................................................... 199 Feedback ........................................................................................... 199

Candle Corporation Legal Notices..........................................................200 Candle Corporation Trial and License Agreement(s) .............................203 Trademark Notices ................................................................................219 User Defined Delays Tab's Context Menu, Drag-and-drop and Key Bindings Support...................................................................................221 User Defined Workloads Tab's Context Menu, Drag-and-drop and Key Bindings Support...................................................................................223 Instrumentation Tab's Context Menu, Drag-and-drop and Key Bindings Support .................................................................................................225 Source Browser's Context Menu, Drag-and-drop and Key Bindings Support .................................................................................................227

Index ........................................................................................................229


Page 4


Getting Started PathWAITM Performance Analyzer is a performance testing and tuning tool that provides workload analysis facilities for WebSphere application developers, testers, and tuners.

What can I do with PathWAI Performance Analyzer v130? PathWAI Performance Analyzer allows you to collect and analyze the application

trace data from J2EE applications deployed in a WebSphere Application Server.It also helps you understand the applications behavior and performance early indevelopment, so that you can find and fix problems quickly and easily. ReadOverview to know more about the product. Also, read Concepts to understandthe concepts and various components of PathWAI Performance Analyzer.

How is Performance Analyzer v130 different from v100?

PathWAI Performance Analyzer v130 is an enhanced version of v100 equipped with additional value-added features. Read What’s New? to know more about this new release. Must Read! Instrumentation Editor Must Read! Instrumenting System Classes Must Read! Lock Contention Must Read! Advanced Import Filtering

How do I get started with PathWAI Performance Analyzer?

If you prefer to learn new software by exploring it, start PathWAI PerformanceAnalyzer and take a look at the various views. Read Default Perspective andViews for details about the control views, bar chart views, tabular views, andother graphical and tree views.

As stated above, PathWAI Performance Analyzer allows you to analyze theapplication trace data using the trace files. Before you step into importing tracefiles and analyzing them, learn to identify or create a project. Follow the steps given below to create a new project:

1. From the File > New menu, select Project.

2. Select Simple, then click Next.

3. In the Project Name field, type the name you want to use for the tracefile project.

4. Click Finish.

After creating a project, as a first step, you may import and analyze the sampletrace file CandleBankSample1.trc before you run your own traces. For thispurpose, follow the instructions given in Tutorial 1. By going through thistutorial based on the sample trace, you will see how PathWAI PerformanceAnalyzer can help you to analyze the flow of a J2EE application and pinpoint themethods where significant amounts of time are being spent.


Page 5


Now that you understand how to analyze the trace file, go ahead and use thetrace files to identify memory leaks and its causes. For this purpose, follow theinstructions given in Tutorial 2 and Tutorial 3. Also, to analyze the trace file andknow more about the synchronization events occurring on Java objects duringthe trace period, see Tutorial 4.

To run live traces, you need to define instrumentation sets, set up a monitorand instrument a server, and create a new trace.

Read Creating and Modifying Instrumentation Sets to create a newinstrumentation set. Additionally, you may read ManagingInstrumentation to know more about the instrumentation.

Read Setting up PathWAI Profiling to know how to set up a monitor thatinstruments the server for trace data collection.

Read Running a Live Trace to know how to run live traces.

Note that the results of the trace are based on the preferences set in PathWAIPerformance Analyzer. You may customize the perspective by changing thesettings to your own preferences. Read Setting Preferences for details aboutchanging the overall appearance of PathWAI Performance Analyzer. You may also read Tips and Tricks to find useful information about howPathWAI Performance Analyzer can be effectively used.

Where can I get some help?

If you need help, you may access this comprehensive online user guide fromPathWAI Performance Analyzer. The online user guide is split into six logicalparts, each focusing on fundamental as well as advanced features of PathWAIPerformance Analyzer. For those who cannot work without printed manual,access Printed Documentation to download and print the whole online userguide.

The conventions used in the online user guide include:

Note

Tips

Questions

If you need a brief description of the features and widgets in the user interface,simply place the focus on the widget and press the F1 key. This key actiondisplays a small window with context-sensitive help and links to related helptopics for the widget.


Page 6


Product Overview This section of the User Guide provides an overview of PathWAI Performance Analyzer, highlights the new features added to v130, gives details of other PathWAI products of Candle Corporation, and furnishes the contact information for contacting Candle Corporation for comments, suggestions and questions.


Page 7


Overview

PathWAITM Performance Analyzer is a performance testing and tuning tool that provides workload analysis facilities for WebSphere application developers, testers, and tuners.

These facilities allow you to:

collect and analyze the application trace data from J2EE applications deployed in a WebSphere Application Server

understand your applications behavior and performance early in development, so that you can find and fix problems quickly and easily

Thus, PathWAI Performance Analyzer helps minimize the risk of deploying less stable J2EE applications that might inhibit the systems performance. By using PathWAI Performance Analyzer, you can resolve performance problems early and avert costly disruptions in later stages of development.

PathWAI Performance Analyzer is built on the Eclipse framework and packaged as a set of Eclipse plug-ins. Its profiling perspective represents data graphically in bar charts, pie charts, and tree views for ease of use and quick recognition of problems.

PathWAI Performance Analyzer includes context menus, hot links from graphical to tabular views, tool tips, context-sensitive info-pops, and a complete online User Guide.

For more information on other Candle PathWAI products, see PathWAI Products.

Operating Environment

Hardware Requirements

Pentium 200Mhz, 64 Mb RAM, 100 Mb of free hard drive space.

Software Requirements

Windows 32/2000/XP/2003.

WebSphere Studio Application Developer (Application Developer) Release v5.1 users:

Application Developer is based on Eclipse and includes all prerequisites.

Eclipse Integrated Development Environment (IDE) users:

Java Runtime Environment (JRE) 1.3.1 or 1.4.

Eclipse Release 2.1.2 running on Windows 2000 or XP


Page 8


(http://www.eclipse.org).

Eclipse Modeling Framework (EMF) Eclipse feature set Release 1.1.1 (http://www.eclipse.org/emf).

Graphical Editing Framework (GEF) 2.1.2. (http://www.eclipse.org/gef)

Adobe Reader (http://www.adobe.com)

Eclipse 2.1.2, EMF 1.1.1 and GEF 2.1.2 are included on the PathWAIPerformance Analyzer product CD. If you are installing PathWAI PerformanceAnalyzer from the CD, you can use the installation wizard option to installEclipse, EMF and GEF during the product installation. You can also installPathWAI Performance Analyzer into an existing instance of Eclipse 2.1.2 or intoApplication Developer V5.1, which runs on an Eclipse 2.1.2 base. PathWAIPerformance Analyzer can coexist with any version of Eclipse or ApplicationDeveloper in a separate directory.

Instrumented IBM Products

Given below are the IBM products instrumented by PathWAI Performance Analyzer for trace collection:

WebSphere Application Server (WAS) V4.0 Advanced Edition, if installed on the same machine as PathWAI Performance Analyzer.

WAS V5.0 Base Deployment or Network Deployment, if the instrumented node is installed on the same machine as PathWAI Performance Analyzer.

WAS V5.0 (not V4.0) Base and Express Test Servers, if PathWAI Performance Analyzer is running within WSAD V5.1.

Supported Trace File Imports

Given below are the Trace File Imports supported by PathWAI Performance Analyzer:

Candle OMEGAMON® XE for WebSphere Application Server, V110 or V120

WSAD Profiler V4, V5, or V5.1

Eclipse Hyades Profiler (http://www.eclipse.org/hyades).

Supported Instrumentation Control File Imports and Exports

The Instrumentation Control File Imports and Exports supported by PathWAI Performance Analyzer include only Candle OMEGAMON XE for WebSphere Application Server, V120.

For detailed information about OMEGAMON XE for WebSphere ApplicationServer, see the documentation for that product.


Page 9

http://www.eclipse.org/

http://www.eclipse.org/emf

http://www.eclipse.org/gef

http://www.adobe.com/

http://www.eclipse.org/hyades


Feedback

Candle welcomes your comments. Please feel free to submit suggestions and requests, or report any problems with PathWAI Performance Analyzer. Email: [email protected]

Web: http://www.candle.com/performanceanalyzer


Page 10


http://www.candle.com/performanceanalyzer


PathWAI Products

PathWAI products from Candle Corporation provide industrial-strength tools designed to optimize the performance of your WebSphere applications. These products deliver the software foundation for Candle's PathWAI solutions - covering the entire Web application development life cycle.

PathWAI Performance Analyzer

PathWAI Performance Analyzer is a powerful Eclipse-basedtool that aids your J2EE application development, testing anddeployment efforts by providing key performance metrics in aseries of dynamic, intuitive charts and tables.

PathWAI XE for WebSphere Application Server

PathWAI XE for WebSphere Application Server (also knownas OMEGAMON® XE for WebSphere Application Server)provides valuable statistics and information to customerslooking to monitor IBM WebSphere Application Server. Themetrics collected provide developers, testers and productionspecialists with critical information about performance,availability and reliability of the environment.

PathWAI XE for WebSphere MQ Monitoring and Configuration

PathWAI XE for WebSphere MQ Monitoring and Configuration(also known as OMEGAMON XE for WebSphere MQ Monitoringand Configuration), is the industry-leading WebSphere MQsystems management solution. PathWAI XE for WebSphereMQ Monitoring and Configuration translates performance andavailability data into valuable information for managing yourWebSphere networks and applications.

PathWAI XE for WebSphere Integration Brokers

PathWAI XE for WebSphere Integration Brokers (also knownas OMEGAMON XE for WebSphere Integration Brokers), is adedicated performance, management and availability monitorfor WebSphere Integration Brokers. It's a powerful analytical


Page 11


tool for detecting and correcting problems in the brokers ormessage flows. PathWAI XE for WebSphere Integrationexpands Candle's commitment to the WebSphere MQ familyand support for the e-business infrastructure with enterprisesystems management solutions.

PathWAI SQL Expert PathWAI SQL Expert, the only SQL performance assuranceproduct that offers problematic SQL detection, automatedSQL optimization and benchmarking provides developers, QAand DBA teams with a powerful tool to create and optimizeSQL throughout the application life cycle. Developers cancode for both performance and functionality while QA andDBA teams can optimize performance before productionrollout. Users are empowered to achieve only optimallyperforming SQL — the first time and every time.

PathWAI DE Keep tabs on all the critical systems of your Webinfrastructure with PathWAI DE for distributed systems andOS/390 (also known as OMEGAMON DE for distributedsystems and OS/390). PathWAI DE provides the ability tointegrate various PathWAI XE monitors into a unified portal-like view, including monitors for IBM WebSphere ApplicationServer, WebSphere MQ, back-end databases, your server OS,etc. With this ability, you can not only view the performancemetrics but also the relationships between the performanceof your overall environment — all from a single paneof glass.

PathWAI Web Segment Analyzer

PathWAI Web Segment Analyzer measures the response timeof each path segment in a server's back-end components. Asa transaction flows across a server through a complex set ofcomponents, Web Segment Analyzer builds a profile showingwhere slowdowns occur.

PathWAI Web Response Monitor

PathWAI Web Response Monitor provides the ability to seethe performance real end users are actually experiencing.Web Response Monitor captures response times and otherperformance information about Web pages, Web graphicobjects, JavaScript, applets, network traffic, cache and otherWeb entities. This performance information is measured fromthe Web Server operating system and sees the end userbrowser.

PathWAI Web Availability Monitor

PathWAI Web Availability Monitor is an active, synthetic, orrobotic, monitoring tool that is deployed in front of the Webinfrastructure to monitor and develop metrics concerning theavailability and reliability of a specific web infrastructure.

PathWAI Secure for WebSphere MQ

Maximize business data protection with Candle's award-winning MQSecure®. By providing vital security forWebSphere MQ applications, MQSecure ensures that valuablebusiness information can't be tampered with or read.

PathWAI Editor for Messages

If you are looking to maximize your organization'sinvestment in IBM WebSphere MQ, get your applications upand running fast, and simplify the tasks of loading messages


Page 12


and testing program functionality, consider PathWAI Editorfor Messages — a powerful solution from CandleCorp. that empowers you to do all of this and more.

PQEdit for WebSphere MQ

PQEdit® is a unique application development tool that speedsapplications into production. A component of PathWAI TuningWorkbench for WebSphere Business Integration, PQEdit canalso be obtained as a stand-alone product.

Candle Application Services Pac

The Candle Application Services Pac software suite enhancesapplication development for IBM's WebSphere MQ. It helpsWebSphere MQ developers reduce development time, lowercosts and simplify maintenance. It not only provides labor-saving development utilities but it also enables developers tocreate robust WebSphere MQ applications without beingexperts.

Universal Agent Universal Agent is a flexible, general-purpose OMEGAMON XEMonitoring Agent® that may be customized to acceptperformance information from a variety of sources. It can beconfigured to monitor almost any application or deviceconnected to a TCP/IP network. Universal Agent may beintegrated with any system that supports standard networkprotocols.

For updated information and additional details about the products, please visit www.candle.com/performanceanalyzer.


Page 13



What's New?

PathWAI Performance Analyzer v130 is an enhanced version of v100 equipped with additional value-added features.

Given below are some significant features added to the 130 release of PathWAI Performance Analyzer:

Instrumentation Editor

Instrumentation Editor is an in-built, full page, form-based, multi-tabbed editor for modifying the contents of the KWE user instrumentation file (kweiuser.xml).

The Instrumentation Editor provides support for all parameters, entry of free-form text, and browsing of external archive files and Eclipse projects. You can use this editor to create an instrumentation set that specifies the classes, methods, and objects for which application server trace data will be collected. See Creating and Modifying Instrumentation Sets for more details.


Page 14


Call Graph

Call Graph view is a graphical representation of application sequence flow with method and timing annotations.

The Call Graph view has a vertical histogram bar that provides a proportionally sized timing representation of each method. It depicts the sequential timing of the method’s self time and it’s immediate child cumulative time. The Call Graph view is synchronized with Method Time Eye-catcher, Call Tree view, and the methods listed in Workloads tabs, Monitor Contention tab, and Method Calls tab. See Call Graph for more details. Advanced Import Filtering

Advanced Import Filtering is an additional feature included in the Import Wizard to facilitate range selection based on line counts and time duration, workload selection (applicable only to OMEGAMON Application Trace Files) and trace constraints selection.


Page 15


This advanced feature enables selection of areas of interest from Application Trace files in excess of 100M bytes of data. See Importing an OMEGAMON XE Trace for more details.

Lock Contention

Lock Contention tab gives you detailed information about the synchronizationevents, which are monitor events occurring on Java objects.

This view gives you details such as the names of the threads accessing theobjects, the methods that initiate the thread’s access to objects, thewaiting time of the threads to access the monitors or objects, etc. See LockContention for more details.

Additional Table Columns

The tabular views of PathWAI Performance Analyzer v130 are updated withaddition columns to display more useful information about the trace. For example,the Workloads table has additional columns such as Method, Type, Start Time, EndTime, Remaining Objects, Remaining Objects Size, Total Objects, and TotalObjects Size.

Hierarchical View and Flat View

PathWAI Performance Analyzer v130 provides a Toggle Table View toolbar button

in some of the tabular views that allows you to switch between Hierarchicalview and Flat view.

Hierarchical view displays the complete structure and hierarchy of an item and Flatview displays only the lowest level items. You can also flatten the table structureto a chosen level by using the drop-down selection of the Toggle Table View

toolbar button .


Page 16


Table Content Filtering

PathWAI Performance Analyzer v130 provides a Table Content Filter toolbar button

that allows you to filter the tables based on the filter criterion. The ContentFilter dialog has three components, mainly Table Column menu, Filter Conditionmenu, and Content Filter field.

The Table Content Filter toolbar button also provides a drop-down selection that lists the previous searches performed on the current table.

Tutorial for Lock Contention

PathWAI Performance Analyzer v130 provides an additional tutorial for collectingand analyzing Lock Contention data. See Tutorial 4 for more details.

Printed Documentation

PathWAI Performance Analyzer v130 provides a softcopy online user guide as wellas a printed documentation of the same. You can print all the contents provided inthe help system. See Printed Documentation for more details.

Constraint Sets

PathWAI Performance Analyzer v130 provides a new Reusable Constraint Setfunctionality to effectively manage Constraint sets for performing live tracing ofapplications. The new functionality helps you define reusable and modifiableconstraint sets that can be used when

1. Performing Heap Analysis to retrace the applications by extending theconstraints set to

Add Object Reference collection of specified objects

Add additional method collection for allocating methods that might havebeen excluded

2. Investigating Lock Contention to retrace the application by extending theconstraints set to

Add additional method collection for contending methods that mighthave been excluded


Page 17


The Reusable Constraint Sets help you run a simple Live Trace creating newdefault constraints, re-trace using existing constraints, run a Live Trace withconstraints modified from an existing set, filter a Trace import using a newconstraint set, and filter a Trace re-import using an existing constraint set. SeeRunning a Live Trace for more details.


Page 18


Printed Documentation

PDF Version of PathWAI Performance Analyzer's User Guide

The User Guide provides an overview of PathWAI Performance Analyzer, details about its concepts and views, and some tutorials that help you perform common and important tasks with the product.


Page 19


Contact Us

Candle welcomes your comments. Please feel free to submit suggestions and requests, or report any problems with PathWAI Performance Analyzer at [email protected].

For questions or comments about the online help, you can reach us at [email protected].

Candle customers, especially those who have obtained PathWAI Performance Analyzer with OMEGAMON XE for WebSphere Application Server, can have access to a variety of easy-to-use online support resources. Visit www.candle.com for direct links to a variety of support tools that include the following services:

eSupport Allows you to create and update service requests opened with CustomerService and Satisfaction (CSS).

eDelivery Allows you to download products, documentation, and maintenance 24hours a day, 7 days a week.

eNotification

Notifies you of product updates and new releases.

The Candle Web site also provides information about how to contact the Customer Support Service team by telephone or email. Visit www.candle.com support section and choose the link to Support Contacts to locate your regional support center.

For more information on other Candle PathWAI products, visit www.candle.com/performanceanalyzer.


Page 20



http://www.candle.com/




Views

This section of the User Guide describes:

the default PathWAI Performance Analyzer perspective

the control views you can use for running live traces and importing existing traces and instrumentation sets

the data views you can use for displaying and analyzing trace data


Page 21


Default Perspective

Given below is the default PathWAI Performance Analyzer perspective:

The default perspective includes the following views:

View Tab Description

Profiling Resources

Allows imported or live traces to be examined andanalyzed, and instrumentation sets to be used inrunning live traces.

Control View

Profiling Monitor Allows enabling and running of WebSphere ApplicationServer traces.

Instrumentation Editor An in-built, full page, form-based, multi-tabbed editorfor modifying the contents of the KWE userinstrumentation file (kweiuser.xml).

Bar Charts View

All Workloads Summary

Displays the 10 longest-running workloads for aselected trace.


Page 22


View Tab Description

Selected Method Summary

Displays the 10 longest-running children of a selectedmethod.

All Objects Summary

Displays the top 10 objects (in terms of aggregate sizeand number of instances) remaining on the Java heapfrom the selected trace.

Tabular View Provides detailed information about Workloads,Method Calls, Methods, Threads, Objects, ObjectReferences, and Lock Contention.

Method Time Eye-catcher A pie chart to help you visualize the overhead of eachmethod and its children in terms of their portion of theoverall application workload.

Call Tree Provides detailed information about each individualmethod call.

Tree View

Call Graph Provides a graphical representation of the applicationsequence flow with method and timing annotations.

Customizing PathWAI Performance Analyzer Perspective

You can customize the PathWAI Performance Analyzer perspective by setting preferences.

To set display preferences specific to the Performance Analyzer, select Window > Preferences > PathWAI Performance Analyzer.

To set general Eclipse display preferences, select Window > Customize Perspective.

To reset the perspective, select Window > Reset Perspective. This action resets the perspective and hides the Instrumentation Editor view.

Related Topics Setting Preferences


Page 23


Control Views

This section of the User Guide describes the Profiling Resources and Profiling Monitors tabs of the PathWAI Performance Analyzer perspective. You can use these tabs for setting up, running, importing, and exporting traces; and for importing, editing, and exporting PathWAI Monitor instrumentation control files.


Page 24


Profiling Resources

The Profiling Resources tab shows imported or live traces to be viewed and analyzed, and instrumentation sets to be used in running live traces.

The projects listed here can be simple projects created to hold imported trace data, or Java projects you are developing. You can also use this view for starting a live trace, setting up instrumentation for live traces, and importing and exporting PathWAI Monitor instrumentation control files.

Related Topics

Importing an OMEGAMON XE Trace

Importing an IBM Profiler Trace

Running a Live Trace

Checking PathWAI Profiling

Creating and Modifying Instrumentation Sets


Page 25


Profiling Monitor

Use the Profiling Monitor tab for

setting up Admin Server monitors

instrumenting WebSphere Application Servers for live traces

checking on the status of the monitors, servers, and instrumentation

Interpreting Application Server Icon

Icon Description

Status is unknown. Right-click the icon, select Discover Status, andwait for a connection.

Status is unknown, and an error has occurred. Right-click the icon, selectProperties > Info, and review any error messages shown under LastError.

Application server is stopped.

Application server is stopped and instrumentation is pending, or an errorhas occurred. Start the application server to apply the instrumentation;or right-click the icon, select Properties > Info, and review any errormessages shown under Last Error.

Application server is running but is not instrumented for trace collection.

Application server is running but is not instrumented for trace collection,and an error has occurred. Right-click the icon, select Properties >Info, and review any error messages shown under Last Error.

Application server is running and instrumented, but needs to be recycledto activate instrumentation changes.

Application server is running and instrumented for trace collection.

Application server is running and instrumented, and a trace is occurring.


Page 26


In Case of Trouble...

If you encounter problems with instrumenting the application server, you can find information about the error by right-clicking the application server icon and selecting Properties > Info.

If the application server icon is gray, you can attempt to start it by right-clicking the icon and selecting Discover Status.

Related Topics

Setting up PathWAI Profiling




Page 27


Data Views

This section of the User Guide describes the views you can use for displaying and analyzing trace data.


Page 28



The All Workloads Summary bar chart displays the 10 longest-running workloads for the selected trace.

When you hover the cursor on a bar, flyover text gives more information about the workload the bar represents. This information includes two time measurements:

Time Self: time spent in this method, excluding child methods

Time Cumulative: time spent in this method and in all child methods

For more detailed information about each workload, you can examine the Workloads tab directly below the All Workloads Summary. To highlight a workload’s method in the Workloads tab, double-click the bar that represents the workload.

Related Topics

Workloads


Page 29



The Selected Method Summary bar chart displays the 10 longest-running children of the selected method.

To access the Selected Method Summary chart:

1. Select a method from the Workloads tab or Method Calls tab.

2. Click on the Selected Method Summary tab.

To determine which child method is represented by each bar, hover the cursor on the bar. Flyover text gives this and other information about the method.

The yellow bars represent Time Cumulative: time spent in the method represented by the bar, and in all its child methods.

The cyan bars represent Time Self: time spent in the method represented by the bar, excluding its child methods.

For more detailed information about each method, you can examine the Method Time Eye-catcher pie chart, the various tabular views (tabs), and the Call Tree and Call Graph views. To highlight a method in the Method Calls tab, double-click the bar that represents the method.

Related Topics

Method Time Eye-catcher

Methods

Call Tree


Page 30


All Objects Summary

The All Objects Summary bar chart shows the top 10 Java objects (in terms of aggregate size or number of instances) allocated during a trace. For each of these objects, the view shows total allocations and objects remaining on the heap at the completion of the trace.

To determine which object is represented by each bar, hover the cursor on the bar. Flyover text gives this and other information.

The green bars represent all objects allocated. The blue bars represent the objects remaining on the heap after the trace.

For more detailed information about each object, you can examine the Objects tab and Object References tab directly below the All Objects Summary. To highlight an object's class in the Objects tab, double-click the bar that represents the object.

By default:

the chart shows the largest objects by aggregate size, rather than by number of instances

the display is sorted by the size of objects remaining on the Java heap, rather than the size of all objects allocated

To change the display, click the arrow on the title bar and select the desired options from the menu that appears.


Page 31


Related Topics

Objects

Object References


Page 32



The Method Time Eye-catcher is a pie chart that helps you visualize the overhead of each method and its children in terms of their portion of the overall application workload.

The cyan section of the pie chart represents Time Self; that is, time spent in the selected method, excluding child methods. The other sections represent calls to child methods. To find out which method is represented by each section, hover your cursor on it. Flyover text gives you detailed information.


Page 33


You can choose to arrange the pie chart by the proportion of time spent by each method (as shown above), or in sequential order of calls to each method.

The sequential, or distributed, view starts at 12:00 and moves clockwise around the circle. Note that in the distributed view, the cyan section that represents Time Self has been divided into several segments, to show the sequential order of calls. The notches in the cyan segments indicate zero-time child calls that bound contiguous Time Self segments.

The flyover text for the distributed view identifies the child calls that bound each Time Self segment.


Page 34


To toggle between proportional and sequential views, click the menu arrow and select Show Proportional Time or Show Distributed Time.

You can also toggle between Show Time Self and Children and Show CPU Time Self and Children.

To move down the call tree, double-click a method's section of the pie chart. A call depth gauge indicates how far you have navigated down the call tree, in proportion to the maximum call depth of the thread.

To navigate back up the call tree, click the arrow at the top of the call depth gauge.

Related Topics



Page 35


Workloads

The Workloads tab gives you detailed performance information about each invocation of the selected workload.

You can drill down from this view to each method called. When you select a method, data in the Method Time Eye-catcher, Selected Method Summary, Call Tree and Call Graph reflect the selection.

Given below are the columns available for display in Workloads table:

Column Title

Description

Workload User Defined Workload, Servlet, Java Server Page or Enterprise JavaBean method whose response time directly reflects the response timethe end user perceives. The workload column also displays the majorname and minor name if defined in the instrumentation set.

Method Name of the method.

Type Type of workload e.g. Servlet, Java Server Page or Enterprise JavaBean.

Start Time Time when the workload began processing. Default format:HH:MM:SS.mmm YYYY-MM-DD. You can change the date format byselecting Window > Preferences > PathWAI PerformanceAnalyzer > Appearance.

End Time Time when the workload ended processing. Default format:HH:MM:SS.mmm YYYY-MM-DD. You can change the date format byselecting Window > Preferences > PathWAI PerformanceAnalyzer > Appearance.

Time Duration of the workload's processing. By default, time values aredisplayed in milliseconds. You can change the unit to seconds byselecting Window > Preferences > PathWAI PerformanceAnalyzer > Appearance.


Page 36


Column

Title Description

Status Status of the workload at the time of the trace. Valid values areComplete and Incomplete.

User ID ID of the user who initiated the workload. If the user ID cannot bedetermined, the value is Unknown.

User IP IP address (if it can be determined) of the browser that initiated therequest.

Input Parameters

String representation of the parameters passed to the method.

Return Parameter

String representation of the object returned by the method.

Thread Name of the thread used by the workload.

Total Objects

Total number of objects created by the selected workload.

Total Objects Size

Estimated size in bytes of all the objects created by the selectedworkload.

Remaining Objects

Number of objects created by the selected workload that are remainingon the heap. These are the objects that were not garbage-collected.

Remaining Objects Size

Estimated size in bytes of the objects created by the selected workloadthat are remaining on the heap.

*The term "Lock" is equivalent to the term"Monitor" in other descriptions.

To sort the data in the table, click on the heading of the column whose values you want to use as the basis of the sort.

You can also customize the view by selecting the columns to be displayed. To do this, select Window > Preferences > PathWAI Performance Analyzer > Statistics > Workloads.

Context Menus

If you right-click an item of interest in the table, a Show in...context menu lets you select another table that gives performance information about the item.

When you make a selection, you navigate directly to the same item in the selected table. If the selected target table has a filter and/or a different flat view applied, then a message informing you about the same is displayed along with an option to remove the applied filter.


Page 37


Click Yes to remove the applied filter or No to retain the applied filter. You can check "Always remove filter if selection is not visible" to always remove the applied filter. You can also enable this option in the Preferences page of PathWAI Performance Analyzer by selecting Windows >Preferences.

If you are developing your application in Eclipse or WebSphere Studio Application Developer (Application Developer), you can select View Source to open a Java editor and seethe source code for the highlighted method.

If you select Copy from the context menu, the text in the table cell where your cursor is positioned will be copied to the Clipboard. You can then paste the text from the Clipboard into any application that accepts text pastes.

Toggle

You can toggle between shortened names and fully qualified names by clicking the name toggle button .


You can switch between Hierarchical view and Flat view by using the Toggle Table

View toolbar button . Hierarchical view displays the complete structure and hierarchy of an item and Flat view displays only the lowest level items. By default, the display format for Flat view is packagename.classname.methodname. Note that the Toggle Table View toolbar button is disabled (grayed out) when Flat view is applied to the table.

Table Content Filters

You can filter the tables based on the filter criterion by using the Table Content Filter

toolbar button . On clicking this toolbar button, the following dialog appears:


Page 38


The Content Filter dialog has three components, mainly Table Column menu, Filter Condition menu, and Content Filter field. The Table Column and Filter Condition drop-down menus are read-only controls. Table Column menu lists the currently visible columns in the table and Filter Condition menu lists the filter conditions applicable for each of the table columns. The Content Filter field is an editable control that allows you to enter a filter criterion or select an existing criterion from the list. The menu provides a history of previous 10 content filter strings, which are global across all tables. The table title is suffixed with the content filter applied to the table.

The Content Filter field becomes read-only when "Status" or "Deadlock" column isselected from the Table Column menu and provides standard filter options likeComplete, InComplete, Locked Holding, Locked Waiting and Locked Both.

The Table Content Filter toolbar button also provides a drop-down selection . The drop-down selection lists all the previous searches performed on the current table. Select "No Filter” option to remove all filters.

The filter is based on the preferences set in the Appearance dialog of PathWAI Performance Analyzer (Window >Preferences > PathWAI Performance Analyzer > Appearance) e.g. Time Format, Date Format and Time Zone. Hence, the results of the applied filter are based on these preferences set. Also, when a date filter has to be applied, ensure that you enter the date in the format as set in the Appearance dialog e.g. (hh:mm:ss.sss) YYYY-MM-DD. The date entered in any other format is not accepted. See Setting Preferences for details.

If the trace is reopened, the table views are reset to default settings. In this case, the applied filters are removed and you may have to reapply the filter to the tables.

Related Topics


Setting Preferences


Page 39


Method Calls

The Method Calls tab gives you detailed performance information about each invocation of all methods for each package.

You can drill down from this view to each method called. When you select a method, data in the Method Time Eye-catcher, Selected Method Summary, and Call Tree reflect the selection.

Given below are the columns available for display in Method Calls table:

Column Title

Description

Name Name of the method.

Times Called

Number of times the selected method was called.

Start Time Time when the method began processing. Default format:HH:MM:SS.mmm YYYY-MM-DD. You can change the date format byselecting Window > Preferences > PathWAI PerformanceAnalyzer > Appearance.

End Time Time when the method ended processing. Default format:HH:MM:SS.mmm YYYY-MM-DD. You can change the date format byselecting Window > Preferences > PathWAI PerformanceAnalyzer > Appearance.

Time Time spent in the selected method and in all its child methods. Bydefault, time values are displayed in milliseconds. You can change theunit to seconds by selecting Window > Preferences > PathWAIPerformance Analyzer > Appearance.

Time Self Time spent in the selected method, excluding child methods.

CPU Time CPU time consumed during execution of the selected method and of allits child methods. Note: The CPU times collected on Windows systemswith Intel hardware are only accurate to increment in units of 15625micro seconds.

CPU Time CPU time consumed during execution of the selected method, excluding


Page 40


Column

Title Description

Self child methods.

Avg Time Average amount of time the selected method and all its child methodsran during all its calls.

Avg TimeSelf

Average amount of time the selected method, excluding child methods,ran during all its calls.

Avg CPUTime

Average CPU time consumed during execution of the selected methodand of all its child methods during all of its calls.

Avg CPUTime Self

Average CPU time consumed during execution of the selected method,excluding child methods, during all its calls.

Max Time Maximum amount of time the selected method and all its child methodsran during all its calls.

Max TimeSelf

Maximum amount of time the selected method, excluding childmethods, ran during all its calls.

Max CPUTime

Maximum CPU time consumed during execution of the selected methodand of all its child methods during all of its calls.

Max CPUTime Self

Maximum CPU time consumed during execution of the selected method,excluding child methods, during all its calls.

Min Time Minimum amount of time the selected method and all its child methodsran during all its calls.

Min TimeSelf

Minimum amount of time the selected method, excluding childmethods, ran during all its calls.

Min CPUTime

Minimum CPU time consumed during execution of the selected methodand of all its child methods during all of its calls.

Min CPUTime Self

Minimum CPU time consumed during execution of the selected method,excluding child methods, during all its calls.

Input Parameters


Thread Name set on the thread object. The thread names appear only at theMethod Call level.

Return Parameter


Locks Requested

Number of requests made by the threads from the method to acquirethe object's lock.

Status The situation when two or more threads get blocked while trying toaccess an object's lock. The status could be:

Complete Workload/Method entered and exited normally.

Incomplete Workload/Method entered but no exit recorded.

Locked Holding Workload/Method entered but no exit recordedand this method/thread is holding a lock.

Locked Waiting Workload/Method entered but no exit recordedand this method/thread is waiting for a lock.


Page 41


Column

Title Description

Locked Both Workload/Method entered but no exit recorded andthis method/thread is both holding and waiting for a lock.

Exception Not Caught Workload/Method entered and exited viaa Java exception that was not caught within the method.

Completed with Exceptions Workload/Method entered andexited normally but one or more child method calls exited via aJava exception that was not caught.

Total LockDelay

Total waiting time of all the threads to acquire the object's lock.

Max LockDelay

Maximum waiting time of a thread to acquire the object's lock.

Average Lock Delay

Average waiting time of a thread to acquire the object's lock.

Total Objects Self

Total number of objects created by the selected method.

Total Objects SizeSelf

Estimated size in bytes of all the objects created by the selectedmethod.

Remaining Objects Self

Number of objects created by the selected method that are remainingon the heap. These are the objects that were not garbage-collected.

Remaining Objects SizeSelf

Estimated size in bytes of the objects created by the selected methodthat are remaining on the heap.

*The term "Lock" is equivalent to the term “Monitor" in other descriptions.


You can also customize the view by selecting the columns to be displayed. To do this, select Window > Preferences > PathWAI Performance Analyzer > Statistics > Method Calls.

Context Menus

If you right-click an item of interest in the table, a Show in...context menu lets you select another table that gives performance information about the item.


Page 42



Click Yes to remove the applied filter or No to retain the applied filter. You can check "Always remove filterif selection is not visible" to always remove the applied filter. You can also enable this option in the Preferences page of PathWAI Performance Analyzer by selecting Windows >Preferences.

However, when you run a trace without instrumenting a method, the results displayed in the table include the fabricated methods and the context menu allows you to navigate only to Lock Contention table.



Toggle



Page 43




View toolbar button . Hierarchical view displays the complete structure and hierarchy of an item and Flat view displays only the lowest level items. By default, the display format for Flat view is packagename.classname.methodname. Note that the Toggle Table View toolbar button is disabled (grayed out) when Flat views applied to the table.

You can flatten the table structure to a chosen level by using the drop-down

selection of the Toggle Table View toolbar button . The drop-down selection provides options to flatten the table structure to all levels offered in the table e. g. Only Packages, Only Classes, Only Methods, Only Method Calls.






Page 44


The Content Filter field becomes read-only when "Status" or "Deadlock" columnis selected from the Table Column menu and provides standard filter options likeComplete, InComplete, Locked Holding, Locked Waiting and Locked Both.


In Hierarchical view, the filter is applied only to the lowest level itemi.e. child. In case of aggregate columns, where the child level has no data or has same data for all children, the filter is applied to one level higher than the child level item.



Related Topics

Setting Preferences


Page 45


Methods

The Methods tab gives you detailed performance information about all invocations of each method.

If you double-click a method, the Method Calls tab opens.

Given below are the columns available for display in Methods table:

Column Title Description

Method Name Name of the selected method.

Times Called Number of times the selected method was called.

Time Time spent in the selected method and in all its child methods. Bydefault, time values are displayed in milliseconds. You can changethe unit to seconds by selecting Window > Preferences >PathWAI Performance Analyzer > Appearance.


CPU Time CPU time consumed during execution of the selected method andof all its child methods. Note: The CPU times collected onWindows systems with Intel hardware are only accurate toincrement in units of 15625 micro seconds.

CPU Time Self CPU time consumed during execution of the selected method,excluding child methods.

Avg Time Average amount of time the selected method and all its childmethods ran during all its calls.

Avg Time Self Average amount of time the selected method, excluding childmethods, ran during all its calls.

Avg CPU Time Average CPU time consumed during execution of the selectedmethod and of all its child methods during all of its calls.

Avg CPU Time Self

Average CPU time consumed during execution of the selectedmethod, excluding child methods, during all its calls.


Page 46



Time Variance Deviation in Time values for the selected method. The higher thisvalue, the wider the deviation. High values can indicate methodsthat are suffering intermittent poor performance from factors suchas contention or parameter-data-value-triggered delays, forexample, in accessing external resources such as databases.

Time Self Variance

Deviation in Time Self values for the selected method.

CPU Time Variance

Deviation in CPU Time values for the selected method.

CPU Time Self Variance

Deviation in CPU Time Self values for the selected method.

Max Time Maximum amount of time the selected method and all its childmethods ran during all its calls.

Max Time Self Maximum amount of time the selected method, excluding childmethods, ran during all its calls.

Max CPU Time Maximum CPU time consumed during execution of the selectedmethod and of all its child methods during all of its calls.

Max CPU Time Self

Maximum CPU time consumed during execution of the selectedmethod, excluding child methods, during all its calls.

Min Time Minimum amount of time the selected method and all its childmethods ran during all its calls.

Min Time Self Minimum amount of time the selected method, excluding childmethods, ran during all its calls.

Min CPU Time Minimum CPU time consumed during execution of the selectedmethod and of all its child methods during all of its calls.

Min CPU Time Self

Minimum CPU time consumed during execution of the selectedmethod, excluding child methods, during all its calls.

Locks Requested Number of requests made by the threads from the method toacquire the object's lock.




Locked Holding Workload/Method entered but no exitrecorded and this method/thread is holding a lock.

Locked Waiting Workload/Method entered but no exitrecorded and this method/thread is waiting for a lock.

Locked Both Workload/Method entered but no exitrecorded and this method/thread is both holding andwaiting for a lock.

Exception Not Caught Workload/Method entered and exitedvia a Java exception that was not caught within themethod.


Page 47



Completed with Exceptions Workload/Method entered andexited normally but one or more child method calls exitedvia a Java exception that was not caught.

Total Lock Delay Total waiting time of all the threads to acquire the object's lock.

Max Lock Delay Maximum waiting time of a thread to acquire the object's lock.

Average Lock Delay


Total Objects Self


Total Objects Size Self

Estimated size in bytes of all the objects created by the selectedmethod.


Number of objects created by the selected method that areremaining on the heap. These are the objects that were notgarbage-collected.

Remaining Objects Size Self

Estimated size in bytes of the objects created by the selectedmethod that are remaining on the heap.



You can also customize the view by selecting the columns to be displayed. To do this, select Window > Preferences > PathWAI Performance Analyzer > Statistics > Methods.

Context Menus

If you right-click an item of interest in the table, a Show in...context menu lets you select Method Calls table that gives detailed performance information about each invocation of the methods for each package.



Page 48





Toggle






Page 49



The Content Filter field becomes read-only when "Status" or "Deadlock" column isselected from the Table Column menu and provides standard filter options likeComplete, InComplete, Locked Holding, Locked Waiting and Locked Both.


The filter is based on the preferences set in the Appearance dialog of PathWAI Performance Analyzer (Window >Preferences > PathWAI Performance Analyzer > Appearance) e.g. Time Format, Date Format and Time Zone. Hence, the results of the applied filter are based on these preferences set.



Page 50


Related Topics

Setting Preferences


Call Tree


Page 51


Threads

The Threads tab gives you performance statistics about each thread.

Given below are the columns available for display in Threads table:

Column Title

Description

Thread ID Name set on the thread object.

Start Time Time when the thread was created or first began processinginstrumented methods. Default format: HH:MM:SS.mmm YYYY-MM-DD.You can change the date format by selecting Window > Preferences> PathWAI Performance Analyzer > Appearance.

End Time Time when the thread was terminated. Default format:HH:MM:SS.mmm YYYY-MM-DD. You can change the date format byselecting Window > Preferences > PathWAI PerformanceAnalyzer > Appearance.

Total CPUTime

Total CPU time consumed by instrumented method processing on thisthread. Note: The CPU times collected on Windows systems with Intelhardware are only accurate to increment in units of 15625 microseconds.

Max StackDepth

Maximum call stack depth that was reached in processing instrumentedmethods on this thread.

Group Name

Name set on the Java thread group of which the thread is a member.





Locked Waiting Workload/Method entered but no exit recorded


Page 52


Column

Title Description

and this method/thread is waiting for a lock.




Total LockDelay




You can customize the view by selecting the columns to be displayed. To do this, select Window > Preferences > PathWAI Performance Analyzer> Statistics > Threads.

Context Menus

If you right-click an item of interest in the table, a Show in... context menu lets you select Monitor Contention table that gives detailed information about the synchronization events, which are lock events occurring on Java objects.



You can filter the contents of the tables based on the filter criterion by using the

Table Content Filter toolbar button . On clicking this toolbar button, the following screen appears:


Page 53



The Content Filter field becomes read-only when "Status" or "Deadlock"column is selected from the Table Column menu and provides standard filteroptions like Complete, InComplete, Locked Holding, Locked Waiting andLocked Both.




Related Topics

Setting Preferences


Page 54


Objects

The Objects tab gives you information about the objects allocated to the Java heap from the selected trace.

Given below are the columns available for display in Objects table:

Column Title

Description

Object Class name of the allocated object, and an instance identifier shownafter the @ symbol. Example: com.candle.beans.CustomerAccount@1

Total Instances

Total number of instances of the object allocated during the trace.

Remaining Instances

Number of instances of the object remaining on the heap at the end ofthe trace. These are the instances that were not garbage-collected.They do not necessarily indicate a memory leak. Their references mayhave been freed, but the garbage collector may not have beenactivated to reclaim them. Also, they may have been in use at the endof the trace period. For information about looking for memory leaks,see the tutorial section of this User Guide.

Instance Size

Estimated size in bytes of the instance of the object.

Allocated At Time when the object was allocated. Default format: HH:MM:SS.mmmYYYY-MM-DD. You can change the date format by selecting Window >Preferences > PathWAI Performance Analyzer > Appearance.

Collected At Time when the object was garbage-collected.

Allocated byMethod

The method that made the request to allocate storage on the heap forthe object.

Allocated onThread

The thread on which the object was allocated.



Page 55



You can also customize the view by selecting the columns to be displayed. To do this, select Window > Preferences > PathWAI Performance Analyzer > Statistics > Objects.

Context Menus

The Show in... context menu depend son the selection of a particular level in the Objects table. At the package and class level, the Show in...context menu lets you select Method Calls table that gives you detailed performance information about each invocation of the methods for the package.

At the objects level, the Showin... context menu lets you select other tables that give performance information about the item.



However, when you run a trace without instrumenting a method, the results displayed in the table include the fabricated methods and the context menu provides only three tables to navigate, mainly Thread table, Method Calls table and Lock Contention table.


Page 56




Toggle




View toolbar button . Hierarchical view displays the complete structure and hierarchy of an item and Flat view displays only the lowest level items. By default, the display format for Flat view is packagename.classname.methodname. Note that the Toggle Table View toolbar button is disabled (grayed out) when Flat view is applied to the table.


selection of the Toggle Table View toolbar button . The drop-down selection provides options to flatten the table structure to all levels offered in the table e. g. Only Packages, Only Classes, Only Objects.





Page 57



The Table Content Filter toolbar button also provides a drop-down selection . The drop-down selection lists all the previous searches performed on the current table and the options for showing all objects or remaining objects. The content filter can be applied to all objects or remaining objects. To remove all filters, select "No Filter" option from the drop-down selection.

In Hierarchical view, the filter is applied only to the lowest level itemi.e. child. In case of aggregate columns, where the child level has no data or has same data for all children, the filter is applied to one level higher than the child level item.




Page 58


Related Topics

All Objects Summary

Object References

Tutorial 2:Identifying a Memory Leak and Its Cause

Tutorial 3:Looking for a Memory Leak in a Complex Application


Page 59


Object References

The Object References tab gives you information about inbound references to the remaining objects on the Java heap at the end of the trace.

Note that the object references are available only while performing a live trace and are not available while importing trace files. The objects whose inbound references are required must be explicitly set when you initiate alive trace. Since collecting object references greatly increases the memory and disk space required for the trace and can degrade system performance, it is recommended that this feature be used only for a small set of classes that you have identified as possible causes for memory leaks. For information about looking for memory leaks, see the tutorial section of this User Guide.

Given below are the columns available for display in Object References table:

Column Title

Description

Object Class name of the allocated object, and an instance identifier shownafter the @ symbol. Example: com.candle.beans.CustomerAccount@1

Allocation Time

Time when the object was allocated. Default format: HH:MM:SS.mmmYYYY-MM-DD. You can change the date format by selecting Window >Preferences > PathWAI Performance Analyzer >Appearance.

Allocated byMethod

The method that made the request to allocate storage on the heap forthe object.

Reference Type

Type of reference to the object. Valid values are Another Object, StaticField, Java Collection, and Object Array.

Size Estimated size in bytes of the instance of the object.

Instance Count

Number of instances of the object remaining on the heap at the end ofthe trace.

Reference Count

Number of inbound references (number of objects holding a referenceto the object instance of interest). Expanding the node shows thedetails of the object instances that are holding the reference.


Page 60




You can also customize the view by selecting the columns to be displayed. To do this, select Window > Preferences > PathWAI Performance Analyzer > Statistics > Object References.

Context Menus

The Show in... context menu depend son the selection of a particular level in the Object References table. At the class level, the Show in... context menu lets you select Method Calls table that gives you detailed performance information about each invocation of the methods for the package.

At the object reference level, the Showin... context menu lets you select other tables that give performance information about the item.



However, when you run a trace without instrumenting a method, the results displayed in the table include the fabricated methods and the context menu provides only two tables to navigate, mainly Thread table and Method Calls table.


Page 61




Toggle


Related Topics

All Objects Summary

Objects

Tutorial 2:Identifying a Memory Leak and Its Cause

Tutorial 3:Looking for a Memory Leak in a Complex Application


Page 62


Lock Contention

The Lock Contention tab gives you detailed information about the synchronization events occurring on Java objects during the trace period. This view gives you details of the synchronized objects such as the accessing threads, the methods from which the thread accessed, threads status, the waiting time of the threads to access the objects lock, etc.

Given below are the columns available for display in Lock Contention table:

Column Title

Description

Lock The inaccessible internal lock that is associated with every Java Objectincluding Class objects (for static object synchronization).

Thread Name of the thread that requires access to an object.

Status The situation when two or more threads get blocked while trying toaccess an object. The status could be:








Total Delay Total waiting time of all the threads to acquire the object's lock.

Max Delay Maximum waiting time of a thread to acquire the object's lock.


Page 63


Column Title

Description

Average Lock Delay


Request Time

Time when a thread requested for acquiring the object's lock.

Acquire Time

Time when a thread acquired the object's lock.

Release Time

Time when a thread released the object's lock, so that other threadscan access this lock.

Request ByMethod

Method that initiated the threads request, acquire, or release of a lock.

Total Requests

Total number of requests made by threads for a given object's lock.

Max Contenders

Number of threads waiting to acquire the object's lock, when anotherthread was holding/acquiring its lock or accessing the object.

Average Contenders

Average number of threads waiting to acquire the object's lock, whenanother thread was holding/acquiring its lock or accessing the object.



You can also customize the view by selecting the columns to be displayed. To do this, select Window > Preferences> PathWAI Performance Analyzer > Statistics > Lock Contention.

Context Menus

The Show in... context menu depends on the selection of a particular level in the Lock Contention table. At the package and class level, the Showin... context menu lets you select Method Calls table that gives you detailed performance information about each invocation of the methods for the package.

At the lock level, the Show in...context menu lets you select other tables that give performance information about the item.


Page 64




However, when you run a trace without instrumenting a method, the results displayed in the table include the fabricated methods and the context menu provides only two tables to navigate, mainly Method Calls table and Objects table.

The method calls in Method Calls table do not have any time value (i.e. blank cell or 0.00 value) and are not synchronized with other tables or views. The context menu based on the selected method calls in Method Calls Table allows you to navigate only to Lock Contention Table, thus highlighting the need for instrumentation of those methods.

If you are developing your application in Eclipse or WebSphere Studio Application Developer, you can select View Source to open a Java editor and see the source code for the highlighted method.


Toggle



Page 65




View toolbar button . Hierarchical view displays the complete structure and hierarchy of an item and Flat view displays only the lowest level items. By default, the display format for Flat view ispackagename.classname.methodname. Note that the Toggle Table View toolbar button is disabled (grayed out) when Flat view is applied to the table.


selection of the Toggle Table View toolbar button . The drop-down selection provides options to flatten the table structure to all levels offered in the table e. g. Only Packages, Only Classes, and Monitor Instance Table.






Page 66


The Content Filter field becomes read-only when "Status" or "Deadlock" columnis selected from the Table Column menu and provides standard filter options likeComplete, InComplete, Locked Holding, Locked Waiting and Locked Both.


In Hierarchical view, the filter is applied only to the lowest level item i.e. child. In case of aggregate columns, where the child level has no data or has same data for all children, the filter is applied to one level higher than the child level item.



Related Topics

Setting Preferences

Tutorial 4 : Analyzing an Application Impacted by Monitor Contention


Page 67


Call Tree

The Call Tree view gives you detailed performance information about each call of each method. This view is synchronized with the Method Time Eye-catcher and the methods listed in the Workloads and Method Calls tabs.

Given below are the columns available for display in Call Tree View:

Column Title

Description

Method Name

Name of the selected method.

Time Time spent in the selected method and in all its child methods. Bydefault, time values are displayed in milliseconds. You can change theunit to seconds by selecting Window > Preferences > PathWAIPerformance Analyzer > Appearance.


CPU Time CPU time consumed during execution of the selected method and of allits child methods. Note: The CPU times collected on Windows systems with Intelhardware are only accurate to increment in units of 15625 microseconds.

CPU TimeSelf

CPU time consumed during execution of the selected method, excludingchild methods.

Avg Time Average amount of time the selected method and all its child methodsran during all its calls.

Avg TimeSelf

Average amount of time the selected method, excluding child methods,ran during all its calls.

Avg CPUTime

Average CPU time consumed during execution of the selected methodand of all its child methods during all of its calls.

Avg CPUTime Self

Average CPU time consumed during execution of the selected method,excluding child methods, during all its calls.

Max Time Maximum amount of time the selected method and all its child methodsran during all its calls.


Page 68


Column

Title Description

Max TimeSelf

Maximum amount of time the selected method, excluding childmethods, ran during all its calls.

Max CPUTime

Maximum CPU time consumed during execution of the selected methodand of all its child methods during all of its calls.

Max CPUTime Self

Maximum CPU time consumed during execution of the selected method,excluding child methods, during all its calls.

Min Time Minimum amount of time the selected method and all its child methodsran during all its calls.

Min TimeSelf

Minimum amount of time the selected method, excluding childmethods, ran during all its calls.

Min CPUTime

Minimum CPU time consumed during execution of the selected methodand of all its child methods during all of its calls.

Min CPUTime Self

Minimum CPU time consumed during execution of the selected method,excluding child methods, during all its calls.

Input Parameters


Return Parameter


Locks Requested

Number of requests made by the threads from the method to acquirethe object's lock.









Total LockHold

Total hold time of the locks acquired by the method call.

Total LockDelay


Total Objects Self


Total Estimated size in bytes of all the objects created by the selected


Page 69


Column

Title Description

Objects SizeSelf

method.


Number of objects created by the selected method that are remainingon the heap. These are the objects that were not garbage-collected.

Remaining Objects SizeSelf

Estimated size in bytes of the objects created by the selected methodthat are remaining on the heap.

Total Objects

Total number of objects created by the selected method call and thesub-methods of the selected method call.

Total Objects Size

Estimated size in bytes of the objects created by the selected methodcall and the sub-methods of the selected method call.

Remaining Objects

Number of objects created by the selected method call and the sub-methods of the selected method call that are remaining on the heap.These are objects that were not garbage-collected.

Remaining Objects Size

Estimated size in bytes of the objects created by the selected methodcall and the sub-methods of the selected method call that are remainingon the heap. These are objects that were not garbage-collected.



You can also customize the view by selecting the columns to be displayed. To do this, select Window > Preferences > PathWAI Performance Analyzer > Statistics > Call Tree.

Context Menus

If you right-click an item of interest in the table, a Show in...menu lets you select another table that gives performance information about the item. When you make a selection, you navigate directly to the same item in the selected table.

If you are developing your application in Eclipse or WebSphere Studio Application Developer (Application Developer), you can select View Source to open a Java editor and see the source code for the highlighted method.


Page 70



Toggle


Related Topics

Setting Preferences



Page 71


Call Graph

The Call Graph view is a graphical representation of application sequence flow with method and timing annotations.

The call graph view has a vertical histogram bar that provides a proportionally sized timing representation of each method. It depicts the sequential timing of the methods self time and its immediate child cumulative time. The child calls that consume negligible time are actually shown as vertical timing bars of a minimum size that enable viewing and mouse over.

The Call Graph view is synchronized with Method Time Eye-catcher, Call Tree view, and the methods listed in Workloads tabs, Monitor Contention tab, and Method Calls tab. When you select a method in any of these tabular views, the Call Graph view shows the application sequence flow of the selected method and provides a graphical display of the method calls.


Page 72


You can hover your mouse over a time sequence block to see its child method and connection highlighted or over a method block to see its time sequence and connection highlighted. While hovering over the method blocks or time sequence blocks, the flyover text provides all details of the method.

You can expand or collapse the method call structure using the and + icons placed adjacent to the methods. Use+ to expand and to collapse the tree structure.

You can use the keyboard keys to perform the navigation in Call Graph view. Note that cursor navigation works only if a method is selected.

Key Description

Left ArrowKey

Moves to the parent method call. No change to the tree expansion.

Right ArrowKey

Moves to the first child of current node and expands the current node, ifrequired.

Down ArrowKey

Moves to the next method call. No change to tree expansion.

Up ArrowKey

Moves to the previous method call, if there is one, else moves to theparent method call. No change to tree expansion.

Enter Key Moves to the Package table that shows the details of the target methodCall object.

Space Key Moves to the child with largest cumulative time.

If you select a method and right-click on the Call Graph view, a Show in... context menu lets you select call tree or another table that gives performance information about the methods.


Page 73


The context menu provides the following actions:

Context MenuItem

Action

Show In » WorkloadTable

Moves focus to the Workload table, selects and highlights thetarget method Call object in the table.

Show In » PackageTable

Moves focus to the Package table, selects and highlights thetarget method Call object in the table.

Show In » MethodTable

Moves focus to the Method table, selects and highlights thetarget method Call object in the table.

Show In » ThreadTable

Moves focus to the Thread table, selects and highlights thetarget method Call object in the table.

Show In » Call Tree Moves focus to the Call Tree, selects and highlights the targetmethod Call object in the table.

View Source Invokes the java search engine, and displays the selectedmethod Call in the local editor if the source is found.

Expand All Expands all the children of the current method Call under thecursor. If no method Call is under the cursor, then the entiregraph is expanded.

Collapse All Collapses all the children of the current method Call under thecursor. If no method Call is currently under the cursor then theentire graph is collapsed.

You can scroll left, right, up and down the entire Call Graph view by simply holding the mouse left-click and moving the mouse cursor in any direction. Once you left-

click, a ( ) symbol appears and allows you to scroll the view.

You can use the drop-down selection of the toolbar button to toggle between Show Time Self and Children and Show CPU Time Self and Children.

Related Topics

Setting Preferences


Call Tree

Workloads

Lock Contention

Method Calls


Page 74


Concepts

Workloads and Workload Analysis

A workload is an entry point or method call in the application whose processing or response time the end user perceives. In J2EEapplications, the workloads are generally servlets, JavaServer Pages (JSPs),struts framework actions, or Enterprise Java Beans (EJB) methods.

Workload analysis is an application tracing (profiling) technique that allows you to see how often a workload runs, how much CPU time it consumes, and what factors about the workload degrade its performance. Additionally, PathWAI Performance Analyzer's workload analysis enables you to spot, in the individual invocations of the workloads, irregularities that might be caused by resource contentions or performance issues triggered by data values.

Using PathWAI Performance Analyzer

You can start by:

going through the product tutorials, which cover the steps of:

importing a sample trace provided with the product, and examining it to determine the cause of a long-running workload

analyzing object allocations and finding memory leaks during a live trace

importing one of your trace files collected by OMEGAMON XE for WebSphere Application Server or by IBM Profiler

running a live trace of WebSphere Application Server

The default Eclipse view of the PathWAI Performance Analyzer perspective gives you a graphical summary of the longest-running workloads and the worst-performing methods.


Page 75


You can examine a specific workload, and drill down to view and analyze the time or CPU costs of slow performance or frequently called methods, packages, or threads. A Method Time Eye-catcher helps you navigate (using mouse clicks) and visualize the overhead of each method and its children in terms of their portion of the overall application workload.

Then you can pinpoint the source of the performance problem in the call tree, and use the context menu to view the source code if it is available in a Java project.

In addition, the All Objects Summary view highlights potential performance issues associated with the Java heap.


Page 76


This view shows the objects with the highest number of instances or largest size allocated during a live trace and remaining on the heap at after the trace. By examining statistics for the objects remaining on the heap, you can identify potential memory leaks. You can also use Object Reference collection and display to investigate and identify the indirect cause of memory leaks.

To improve performance, the application team can begin early in the development cycle to look at the workloads with the most frequently called methods showing the worst response time. In these early stages of development, performance problems can be eliminated quickly and easily. In the following weeks, the team can compare past and present trace results to determine the performance improvements between builds. This work benefits not only the current application project, but also future projects that use common components.

Related Topics



Call Tree

All Objects Summary


Page 77


Tutorials

PathWAI Performance Analyzer includes sample traces that you can review until you run your own traces. This section of the User Guide contains tutorials for using these traces to perform some common and important tasks you can accomplish with PathWAI Performance Analyzer:

analyzing a long-running workload

identifying a memory leak and its cause in a simple application

looking for a possible memory leak in a more complex application


Page 78


Tutorial 1: Analyzing a Long-Running Workload

You can import and analyze the sample trace fileCandleBankSample1.trc before you run your own traces. The sample trace reflects a short multi-user load-testing session against an Internet banking application. By going through this tutorial based on the sample trace, you will see how PathWAI Performance Analyzer can help you to analyze the flow of a J2EE application and pinpoint the methods where significant amounts of time are being spent.

Step 1. Open the PathWAI Performance Analyzer perspective

From the Window > Open Perspective menu, select PathWAI Performance Analyzer. If PathWAI Performance Analyzer does not appear in the Open Perspective menu, do this:

1. From the Window > Open Perspective menu, select Other....

2. Select PathWAI Performance Analyzer.

The next time you start Eclipse, PathWAI Performance Analyzer willappear in the Window > Open Perspective menu.

Step 2. Create a simple project

Create a simple project to contain the sample trace:



3. In the Project Name field, type the name you want to use for the trace file project.

More than one trace file can be imported into a project.

4. Click Finish.


Page 79


Step 3. Import the sample trace

1. Import the sample trace file into the project.

2. In the Profiling Projects list, right-click the name of the project you just created, and select Import... from the menu that appears.

The PathWAI Trace File dialog is displayed.

3. In the From trace file field, select or browse to the sample trace:

<eclipse_location>\eclipse\plugins\com.candle.khe.help_0.0.1\samples\CandleBankSample1.trc

4. Select the project folder from the Into Project drop-down menu.

5. (Optional) Check Overwrite existing resources without warning if you want to overwrite the existing trace files, which were imported, without any warning.

If you did not check the Overwrite existing resources without warning box and an existing trace matches the trace you selected, this dialog is displayed.


Page 80


Click Replace existing to import the trace and overwrite the existing import,

then click OK to confirm the deletion of the existing import.

6. (Optional) Provide a meaningful description for the import.

7. Click Next

The Select Trace Import Range dialog appears:

The Select Trace Import Range dialog provides filtering selection and has four

panes, mainly "Import Range", "Workload Select", "Trace Constraints", and "Lock Contention".

8. By default, the Select line is selected and based on the trace file (*.trc), the Import from and Import to text fields are populated with the first and last line of the trace file. The Import from and Import to text fields are also


Page 81


complemented with sliders that can be used for selecting the line range. Change the line range using the text fields or the sliders.

To filter the trace files based time scales, select Select time. The Import from and Import to text fields are populated with the start and end time the trace file. You can change the time scale using the text fields or the sliders.

9. Check the Workload Select option to enable the Modify button that allows selection of different workloads to import. Click Modify to display the workload selection dialog:

The dialog displays the Workloads, Start and end time, Start and end events.

Select the workloads of your choice by one of the following methods:

manually check the workloads to be imported

click Select All to select all the workloads

click Deselect All to deselect all the workloads and manually check the ones that need to be imported

manually check the workloads that need not be imported and click Invert Selection to select the other workloads to be imported

After selecting the workloads of your choice, click OK to accept the changes and return to the previous dialog. Click Cancel to cancel the operation.

10. Check the Trace Constraints option to enable the New button, which allows you to create new trace constraints, and drop-down combo menu, which


Page 82


allows selection of existing trace constraints.

On the New Trace Constraint dialog appears, if you want to select an existing trace constraint, pull down the drop-down combo box and select the one that is required.

11. If you want to filter lock analysis data, check Exclude.

12. Click Finish to complete the import.

The newly imported trace is automatically opened and its data displayed in the views of the PathWAI Performance Analyzer perspective.

Step 4. Examine the trace and identify the problems

You will find a number of workloads grouped under doGet and doPost.

1. Expand the doPost workload tree and sort the Time column in descending

sequence to see the longest-running workloads at the top. Alternatively, you could sort the Start column in ascending sequence to see an ordered flow of the test session.

2. Click the toggle icon so that you see the class and the method name (in this example, UpdateCustInfo.doPost).

3. Select the longest-running instance of UpdateCustInfo.doPost.

4. In the Method Time Eye-catcher, double-click the pie chart repeatedly to drill down the call tree to the method with the highest Time Self value; that is, the method that fills the pie chart with cyan (in this example, executeUpdate).


Page 83


5. In the Call Tree tab, right-click the highlighted instance of the

executeUpdate method and select Show in Method Calls Table.

You can maximize any Eclipse view by double-clicking its title bar. Dothis in the All Packages view to see all of the executeUpdate methods.Double-click the title bar again to return to the previous view state.

In the Method Calls view, you can see that similar executeUpdate calls (retrieving a database result) to the same data source take widely divergent times. Interestingly, the problematic executeUpdate call was highlighted on the very first screen, as you can see if you hover the cursor on the longest cyan bar in the Selected Method Summary view.


Page 84


Return to the Call Tree, right-click executeUpdate, and select Show in Method Table. Sort by descending Time Self Variance and maximize the window.

You can see that next() has been used a lot, that it takes a long time to complete, and that its processing time varies from the average (Time Self Variance) by more than any other method's. Given that these next() methods are internally generated by CMP Beans, something is wrong with the way in which this application was built, is configured, or is being used.

The root of the problem can be found in the Workloads view, which shows the same account transfer being processed concurrently by five different threads, generating contention when the same account record is accessed in update mode by more than one thread. If the application had been designed differently, it might have prevented concurrent use for security or data integrity reasons.

PathWAI Performance Analyzer also highlights a possible problem in the test case, which seems not to reflect normal use of the application: the same account transfer is not normally processed concurrently four times in the same two-second period.

Use PathWAI Performance Analyzer to continue to explore the trace file and find other problems to analyze.

Related Topics

Default Perspective


Page 85


Tutorial 2: Identifying a Memory Leak and Its Cause

This tutorial uses a simple application containing a coding mistake that has caused a memory leak. Here, you will look at the objects allocated by the application and identify the reason for its memory leak.

Live traces of WAS applications can include object allocation, collection, and reference information; imported trace files can include object allocation and collection information, but not object references. Therefore, for this tutorial you will import a live trace project and examine its data.

Step 1. Import the live trace project

Import the PPAMemoryTutorial project into PathWAI Performance Analyzer.

1. In Windows Explorer or My Computer, find and unzip this file:

<eclipse_location>\eclipse\plugins\com.candle.khe.help_0.0.1\samples\PPAMemoryTutorial.zip

to the location of your Eclipse projects. In general, this is either <eclipse_location>\eclipse\workspace or the workspace directory you chose when starting WSAD.

2. In Eclipse or WSAD, select File > Import > Existing project into workspace and click Next.

3. Browse to select the PPAMemoryTutorial subdirectory created when you unzipped file PPAMemoryTutorial.zip into the Eclipse or WSAD workspace directory.



Page 86


Step 2. Examine the object allocations and object references

Open the trace in the project, and examine the object allocations for evidence of a memory leak.

1. In the Profiling Resources view of the PathWAI Performance Analyzer perspective, expand the PPAMemoryTutorial project.

The project contains two live traces of a WebSphere4 application server (CandleBank, for Tutorial 3), and one live trace of a WAS5 test server (server1, for this tutorial).

2. Double-click the trace server1_1070904735812 to open it.

3. Right-click the trace and select Properties > Trace Constraints.

This trace includes all class-level workloads and objects, as well as object references for the small set of objects used by our application.

Typically you would identify a memory leak by first running a trace withoutobject references, examining the All Objects Summary bar chart and AllObjects tabular view, and reviewing the remaining instances of object classes;then you would run a new trace to collect the references to those objects. Inthis case, the application is so small that tracing all object references is notlikely to overburden the system. Therefore, a single trace run collecting boththe object allocations and the references to the objects was made.

Now look at the Info tab in the Properties dialog.

It shows that the trace duration is set at 60 seconds, a sufficient time for several garbage collection cycles to occur.


Page 87


Close the Properties dialog, and look at the All Workloads table and the Call Tree.

The application is a JSP that calls a doCreateSchool2() method, which returns a School object. The JSP has been run three times.

The next few steps assume that you know the application data model and thereforethe root object that holds references to the data. A procedure will follow, for use inthe case where you do not know the structure of the application data model.

Select the All Objects Summary view. Use the pull-down arrow to select Show Instance Count and Sort by Remaining Objects.

If you hover the cursor over the bars in the chart. you can see the details of the objects allocated during the trace and review those remaining on the heap.


Page 88


Select the All Objects tab. Use the pull-down arrow to select Show Remaining Objects.

This view presents the details that were highlighted by the bar chart All Objects Summary view. Various objects remain on the heap at the end of the trace. You can see these from the objects names they are part of the in-memory data model representing a School built by the JSP.

You will note that one Schoolobject remains on the heap. You know that the objects will be not be garbage-collected if the root of the data model (the com.candle.test.university.School object) is still present, as it is the top of the model it will hold references to objects that will in turn hold references to the leaf objects in the model.

Viewing the JSP source, you can see that the developer has taken the correct step of setting the School object reference to null to ensure it is dereferenced and can be collected and removed from the heap.

<%!

MyUtil myUtilInstance == null;

School school == null;

%>

<%

if ( myUtilInstance == null ) {

myUtilInstance = new MyUtil();

}

school = myUtilInstance.doCreateSchool2();

%>

<p>

Created School Object: <%= school %>

<p>

<%

school = null;

%>


Page 89


In spite of this precaution, an instance of the School object still remains on the heap.

Select the Object References tab, and expand the tree under the School object .

The Object References view shows only objects remaining at the end of the trace and provides details of any references to those instances that have been traced.

The instance School@3 is referenced by MyUtil@0. The @0 informs us that this reference is not associated with a particular instance of the object but is due to a class static defined in com.candle.test.util.MyUtil, and this is confirmed by the reference type being Static.

At this point you would examine the source code for the method doCreateSchool2() that allocated the School@3.

The source code, which is not provided within the project, shows the cause of the problem: while the JSP is dropping the references to the returned School object, the MyUtil class is keeping a static reference.

public class MyUtil {

private static School stat_school_ref;

// ...

public School doCreateSchool2() {

School stat_school_ref = new School();

// ..code to build School data model..

return stat_school_ref;

}


Page 90


Step 3. Following the references to find the root cause

If you did not know the data model back in Step 2.6, and therefore you didn’t know the root object, you would need to go through this procedure to follow the leaked objects back to the root object and identify the reference to it that is causing the objects not to be collected.

Picking up from Step 2.6, where you selected the All Objects Summary view

1. If you hover the cursor over the bars in the chart. you can see that String is the most used object class, as might be expected in a Java application; but this particular application is not leaving a large number of String objects on the heap. However, 7 of 12 ArrayList objects have been left on the heap.

2. Select the Object References tab, and double-click the title bar of the table to

maximize it. Click the column heading Allocation Time to sort in descending order of the time the object was allocated.

The times are presented in the desktop time zone, so you may need to adjustthe times shown to your time zone. The times stored in the trace data are inUniversal Time Coordinated (UTC), but the screen shots displayed here werecaptured from a copy of Eclipse running in PST (-8hrs).


Page 91


There are two batches of ArrayList objects, which coincide with the last two runs of the application. This informs us that the objects are taking two garbage collection runs to clear, and one set is not cleared.

By looking at the oldest (longest time on the heap) object in each batch, you can follow the chain of references and identify the cause.

For each object, expand the tree and examine the objects that are holding references to the object and hence preventing it from being collected in the garbage collection cycle.

1. ArrayList@12 is referenced by Grade@6, which is referenced by ClassRoom@6 and Subject@6.

2. ClassRoom@6 is referenced by ArrayList@10, which is referenced by Wing@3.

3. Expanding Wing@3, you notice ArrayList@9, which in turn is referenced by School@3, the object we can see the JSP requesting and correctly setting to null after using it.

The tree you have followed now looks like this:

On examination you will see that the School@3 is referenced by a static in MyUtil.

At this point you would examine the source code for the doCreateSchool2() method that allocated the School@3 object.

As shown back in Step 2.10 the cause is that this method is leaving a reference to the created object in a class level static.

The objects in the second batch are not yet collected because they contain two-way references to each other. Only on the second garbage collector run can the system spot that there is no external reference to the objects. Then they can be collected.

By examining the pattern of remaining objects with regard to the number of runs of the application, you can identify whether a leak is cyclic or is a one-time-only occurrence.


Page 92


Related Topics

Tutorial 3: Looking for a Memory Leak in a Complex Application

All Objects Summary

Objects

Object References


Page 93


Tutorial 3: Looking for a Memory Leak in a Complex Application

This tutorial uses the same CandleBank application that provided the sample trace you examined in Tutorial 1. In that tutorial, you identified the methods that caused a long-running workload. Here, you will look at the objects allocated by the application and try to identify memory leaks. Excessive memory usage is a key inhibitor to performance in any Java application, and memory leaks will eventually result in application server outages.

Live traces of WAS applications can include object allocation, collection, and reference information; imported trace files can include object allocation and collection information, but not object references. Therefore, for this tutorial you will import a live trace project and examine its data.

Step 1. Import the live trace project

If you already imported the PPAMemoryTutorial project while going through Tutorial 2, you can skip this step. Otherwise, import the PPAMemoryTutorial project into PathWAI Performance Analyzer.

1. In Windows Explorer or My Computer, find and unzip this file:

<eclipse_location>\eclipse\plugins\com.candle.khe.help_0.0.1\samples\PPAMemoryTutorial.zip

to the location of your Eclipse projects. In general, this is either <eclipse_location>\eclipse\workspace or the workspace directory you chose when starting WSAD.

2. In Eclipse or WSAD, select File > Import > Existing project into workspace and click Next.

3. Browse to select the PPAMemoryTutorial subdirectory created when you unzipped file PPAMemoryTutorial.zip into the Eclipse or WSAD workspace directory.



Page 94


Step 2. Examine the object allocations

Open the first trace in the project, and examine the object allocations for evidence of a memory leak.

1. In the Profiling Resources view of the PathWAI Performance Analyzer perspective, expand the PPAMemoryTutorial project.

The project contains two live traces of a WebSphere4 application server (CandleBank, for this tutorial), and one live trace of a WAS5 test server (server1, for Tutorial 2).

2. Double-click the first CandleBank trace (CandleBank_1070015702264) to open it.


This trace is a wide-ranging one that includes all class-level workloads and

objects, but no object references.

4. Now look at the Info tab in the Properties dialog.

It shows that the trace duration is set at 60 seconds, generally a sufficient time for several garbage collection cycles to occur.

5. Close the Properties dialog and select the All Objects Summary view. Use the triangular menu pull-down to select Show Instance Count and Sort by All Objects.

6. If you hover the cursor over the longest bars in the chart. you can see

immediately that String and StringBuffer are the most used object classes, as might be expected in a Java application.


Page 95


7. Double-click the top bar of the All Objects Summary chart to highlight the

StringBuffer class data in the All Objects table. Maximize this view by double-clicking on its title bar, then click the Collected At column heading to sort the instances of the object in descending order of the time when the object was collected from the Java heap.

The instance at the top of the list was collected by the last garbage collection that occurred during the trace run. Make a note of this time (02:36:56:729), as you will need it later.

The times are presented in the desktop time zone, so you may need to adjust thetimes shown to your time zone. The times stored in the trace data are in UniversalTime Coordinated (UTC), but the screen shots displayed here were captured from acopy of Eclipse running in PST (-8hrs).

Now scroll down the list and count the other times that garbage collection took place.

The reason for doing this is to ensure that enough garbage collection cycles took place during the trace run. If there were only one or two cycles, the trace run was probably too short or the initial free heap too large for you to be able to find any memory leaks.

02:36:56.719

02:36:56.689

02:36:54.235

02:36:54.225

02:36:49.829

02:36:44.291

02:36:42.278

02:36:42.268

02:36:33.756

There appear to be plenty of garbage collection cycles in the trace run.


Page 96


As you scroll down the list, you will start to see object instances with no collection time. Note that these have a Remaining Instance count of 1 because they have not yet been collected.

Click the Allocated At column heading twice to sort in ascending order of the time when the object was allocated. Use the triangular menu pull-down to show only the remaining objects.

Look for instances that were allocated before the last garbage collection time but were not collected.

Several instances remain on the heap, but all were allocated after the last garbage collection time. Therefore, the paths of the application traced here contain no leaked StringBuffer objects.

Collapse the StringBuffer object class in the All Objects table, and expand the String object class. (String was the second most used object class in the trace.) Use the triangular menu pull-down to show all objects.


Page 97


The String class shows the same results as StringBuffer, but Integer shows a different pattern.

The Integer class shows gaps where objects were allocated early in the trace run but were never collected, despite the fact that many garbage collection cycles took place later in the trace run. Understanding why these objects were not collected by any of the garbage collection cycles is the key to tracking memory leaks.

The JRE implements reference counting for all objects allocated on the heap. The object is marked ready for collection when no other objects or active code sections have an active reference to the object. Therefore, if an object persists across a number of garbage collection cycles, there must be outstanding references to it. Such outstanding references sometimes indicate memory leak.

Step 3. Examine the object references

Examine the outstanding references to the Integer object class for evidence of a memory leak.

1. At the top right of the All Objects table, click the toggle icon so that you see the fully qualified names of the object classes.

2. Determining object references is a CPU-hungry operation, so PathWAI Performance Analyzer requires that object references to be collected in live


Page 98


traces be specified by their fully qualified names, without wildcards. The fully qualified name of the Integer object class is java.lang.Integer.

You can copy the object class name (or the contents of any other cellin any PathWAI Performance Analyzer table) into the Clipboard for laterpasting into another field. To do so, right-click the cell and select Copyfrom the context menu.

3. Double-click the title bar of the All Objects table to return it to its default size in the perspective.

4. In the Profiling Resources view, double-click the second CandleBank trace (CandleBank_1070016155045) to open it.


This trace includes collection of outstanding references to the object class java.lang.Integer at the end of the trace period.

6. Close the Properties dialog and select the Object References tab.

7. Click the toggle icon to show fully qualified names.

8. Click the Reference Count column heading to sort in descending order of the number of outstanding references to the object class.

This view shows 17 references to the 65 remaining instances of java.lang.Integer.

9. Expand the object class java.lang.Integer and expand its first few instances.


Page 99


The Integer objects are referred to by instances of ContactauditKey and TransactionKey, both classes from the com.candle.ejb.entity package. The reason for the uncollected objects is now clear. They were allocated in the ebjCreate methods for the CMP entity beans used by the application. Pools of entity beans are allocated on first use and returned to the pool when no longer required for use by other transactions. Any object references associated with these beans therefore persist for the lifetime of the bean; that is, until the application server terminates.

If you look at the Size column, you will see that the size of each instance of the Integer object class is quite small, so no severe consequences are likely to result from the persistent objects.

Even though you did not find a memory leak, you did find a potential problem. The aggregate size of the Integer object associated with the entity beans is not large, but if the application code created a large data structure in the ebjCreate method, this could becomes an issue. In any case, the fragmentation could result in increased heap size, more paging activity, and more work for the garbage collector.

This kind of analysis leads to greater understanding of your application and your J2EE system. The next time you see similar patterns of apparently leaked objects, you will be equipped to analyze them and determine whether they reflect normal system behavior or a memory leak that will affect your application.


Page 100


Related Topics

Tutorial 2: Identifying a Memory Leak and Its Cause

All Objects Summary

Objects

Object References


Page 101


Tutorial 4: Lock Contention


Page 102


Tasks

The main tasks you can perform with PathWAI Performance Analyzer are:

importing and analyzing trace files collected by OMEGAMON XE for WebSphere Application Server or by IBM Profiler

running a live trace of WebSphere Application Server, and then analyzing it

importing, editing, and exporting OMEGAMON XE instrumentation control files for monitoring WebSphere Application Server

This section of the User Guide explains how to perform those tasks, aswell as how to:

set preferences to customize the PathWAI Performance Analyzer perspective

troubleshoot problems with running PathWAI Performance Analyzer itself


Page 103


Setting Preferences

You can customize the PathWAI Performance Analyzer perspective by setting preferences.

To set general Eclipse display preferences, select Window > Customize Perspective.

See the online Eclipse Workbench User Guide for information on customizing perspectives.

To set display preferences specific to PathWAI Performance Analyzer, select Window > Preferences > PathWAI Performance Analyzer.

The General Properties dialog allows you to change the TCP port number used by PathWAI Performance Analyzer to communicate with the monitor installed into the instrumented application servers. After you set the port number, click Apply to save the change.

Before you can change the port number, you must delete all existingAdmin Server monitors. After changing the port number, you will needto recreate the monitors.

From the Preferences menu, you can select Appearance or Statistics to change the format or content of the data displayed in the PathWAI Performance Analyzer perspective.

To reset PathWAI Performance Analyzer perspective, select Window > Reset Perspective.

You can also change the location of the views in the current perspective by moving and docking it. See the Eclipse Workbench User Guide for information on working with views and editors.


Page 104


Appearance

Appearance dialog deals with the overall appearance of PathWAI Performance Analyzer. The dialog allows you to set the date format, time format and time zone, which is used to display all dates and times in the PathWAI Performance Analyzer perspective.

Use the Appearance dialog to change the:

time unit used in reporting performance i.e. seconds or milliseconds. The default format is milliseconds.

format of the dates displayed i.e. MM-DD-YYYY, DD-MM-YYYY, or YYYY-DD-MM. The default format is yyyy-mm-dd.

time zone to display all dates and times.

By default, the time zone drop-down box displays the current system time zone as the current selection. Pull down the drop-down box and select the time zone of your choice.

filter preference.

By default, filter preference is not checked, thus allowing the existing filters to be applied to the tables. Check "Always remove filter" to always remove the filters applied to the tables without prompting.

After you change the settings, click Apply to accept and apply the changes to PathWAI Performance Analyzer.


Page 105


Statistics

Statistics dialog deals with the appearance options for statistic tablesof PathWAI Performance Analyzer e.g. All Workloads, All Packages, All Methods, etc.

Each tab in the dialog represents a statistic table. The tabs list the columns that can be displayed in the tabular views. The dialog also allows you to control the display order of the table columns.

Check the columns that have to be displayed in the statistic tables. Select the column (s) and use the Up/Down buttons to modify its display order. You can select multiple columns by simply holding down the shift key and clicking the desired columns.

Note that the display order of the first column or the key column of the table cannot be changed and hence, the same is not visible in the list.

After you change the settings, click Apply to accept and apply the changes to the views.

When you have set all the preferences (Appearance and Statistics) to your liking, click OK to close the Preferences dialog.

The changes to the following preferences are not applied to views that are alreadyopen. The column selections are applied the next time the views are opened.

If You Change Your Mind

If you want to return to the default perspective, open the Preferences dialog and click Restore Defaults on each settings tab.


Page 106


Related Topics

Default Perspective




Page 107


Importing and Viewing a Trace File

This section of the PathWAI Performance Analyzer User Guide gives instructions for:

importing and viewing trace data from OMEGAMON XE for WebSphere Application Server

importing and viewing trace data from WebSphere Studio Application Developer (WSAD) or Eclipse Hyades Profiler

Object references are not contained in imported trace files; they are collectedand stored in the PathWAI Performance Analyzer Eclipse project resources onlyduring live traces configured to collect them.


Page 108



Follow these steps to begin using PathWAI Performance Analyzer to import, view, and analyze trace data from OMEGAMON XE for WebSphere Application Server.

Step 1. Open PathWAI Performance Analyzer perspective

From the Window > Open Perspective menu, select PathWAI Performance Analyzer. If PathWAI Performance Analyzer does not appear in the Open Perspective menu, do this:

1. From the Window > Open Perspective menu, select Other....

2. Select PathWAI Performance Analyzer.


Step 2. Identify or Create a Project

PathWAI Performance Analyzer application trace data can be stored in any Eclipse project type. If you are developing your application in Eclipse, you may find it convenient to use the same project to hold PathWAI Performance Analyzer resources. Alternatively, you can create a simple project in Eclipse to contain PathWAI Performance Analyzer resources.

To create a simple project:





4. Click Finish.

Step 3. Import a Trace File

Now you will import an OMEGAMON XE trace file into the project.

1. Perform one of these actions:

In the Profiling Projects list, right-click the name of the project you just created, and select Import from the menu that appears.


Page 109


Select File > Import.

Click the icon for the Import tool.


2. Click Browse to open the file selection dialog, so that you can navigate to the right location and select the trace file (*.trc).

If the trace file is located on a remote machine, you can specify an FTP location when you browse to find the file.

For anonymous FTP, specify ftp://hostname. For user-authorized FTP, specify

ftp://username:password@hostname.

3. Select the project from the Into Project drop-down menu.


Page 110


4. (Optional) Check Overwrite existing resources without warning if you

want to overwrite the existing trace files, which were imported, without any warning.

If you have not checked the Overwrite existing resources without warning box and an existing trace matches the trace you selected, a message, similar to the one given below, is displayed.

Click Replace existing to import the trace and overwrite the existing import,

then click OK to confirm the deletion of the existing import.


6. Click Next.

The Select Trace Import Range dialog appears:


Page 111


The Select Trace Import Range dialog provides filtering selection and has four

panes, mainly "Import Range", "Workload Select", "Trace Constraints", and "Lock Contention".

7. By default, the Select line is selected and based on the trace file (*.trc), the Import from and Import to text fields are populated with the first and last line of the trace file. The Import from and Import to text fields are also complemented with sliders that can be used for selecting the line range. Change the line range using the text fields or the sliders.

To filter the trace files based time scales, select Select time. The Import from and Import to text fields are populated with the start and end time the trace file. You can change the time scale using the text fields or the sliders. While using the text fields, ensure that you enter time as "hh:mm:ss.sss YYYY-MM-DD".

8. Check the Workload Select option to enable the Modify button that allows selection of different workloads to import. Click Modify to display the workload selection dialog:

The dialog displays the Workload names, Start and end time, Start and end events. You can click the columns to sort the data in alphabetical order. To identify the incomplete workloads i.e. workloads with no end time set, sort the data by End Time column. All such incomplete workloads have an empty cell in the End Time column, thus indicating the incomplete status of workloads.


Page 112


Select the workloads of your choice by one of the following methods:

manually check the workloads to be imported

click Select All to select all the workloads

click Deselect All to deselect all the workloads and manually check the ones that need to be imported

manually check the workloads that need not be imported and click Invert Selection to select the other workloads to be imported

After selecting the workloads of your choice, click OK to accept the changes and return to the previous dialog. Click Cancel to cancel the operation.

9. Check the Trace Constraints option to enable the New button, which allows you to create new trace constraints, and drop-down menu, which allows selection of existing trace constraints.

On the New Trace Constraint dialog, if you want to select an existing trace constraint, pull down the drop-down menu and select the one that is required.

10. If you want to filter lock analysis data, check Exclude.


The newly imported trace is automatically opened and its data displayed in the views of the PathWAI Performance Analyzer perspective. You can drill down to find the problem. For descriptions of the information available in each view to help you debug your application code, see the Views section of the online User's Guide.

If you have opened an editor view of a file, and it takes up too much space in thePathWAI Performance Analyzer perspective, you can remove it with menu optionWindow > Hide Editors.

You can find more details about the trace file by selecting the trace file, right-clicking and selecting Properties from the context menu. The following Properties dialog appears:

The dialog provides general information about the trace file and details of trace


Page 113


constraints and workload ID sets. The Info option provides general information such as name and description of the trace file, start and end time, actual events and duration, selected trace start event, and maximum events and maximum duration. The Trace Constraints option provides details about the trace constraints set for the trace file. The Workload ID Sets option provides details about the workload names and the details are displayed only for *.trcxmi or *.xmi trace files i.e. while importingXML4Profiling trace files.

Related Topics

Default Perspective


Tutorial 1: Analyzing along-Running Workload


Page 114



Follow these steps to begin using PathWAI Performance Analyzer to import, view, and analyze trace data from WebSphere Studio Application Developer(WSAD) and Eclipse Hyades Profiler.

Step 1. Set up Profiler Trace Files

Do one of these:

Set the Profiler to write to a file with the extension .xmi (WSAD) or .trcxmi (Hyades).

Set up your project launch with these JVM args:

-XrunpiAgent:server=standalone,file=MyTrace01.trcxmi,mode=full,filters=MyFilter01.txt

where

MyTrace01.trcxmi is the file the Profiler will write to, and hence the file you will select when importing the trace.

MyFilter01.txt contains the Profiler class filters that determine which classes will be recorded. Refer to the IBM Profiler documentation for details of the syntax of this file, or obtain on-line help by executing this command:

java -XrunpiAgent:HELP

Step 2. Generate Trace Data

Run the application and generate the profile data.

Step 3. Open PathWAI Performance Analyzer Perspective

1. If Eclipse is not already started, start it now.

2. From the Window > Open Perspective menu, select PathWAI Performance Analyzer.

If PathWAI Performance Analyzer does not appear in the Open Perspective menu, select Other..., then select PathWAI Performance Analyzer.



Page 115


Step 4. Identify or Create a Project

PathWAI Performance Analyzer application trace data can be stored in any Eclipse project type. If you are developing your application in Eclipse, you may find it convenient to use the same project to hold PathWAI Performance Analyzer resources. Alternatively, you can create a simple project in Eclipse to contain PathWAI Performance Analyzer resources.

To create a simple project:





Click Finish.

Step 5. Import Trace Data

1. Take one of these actions:

In the Profiling Projects list, right-click the name of the project you just created, and select Import from the menu that appears.

Select File > Import.

Click the icon for the Import tool.


Page 116



2. Click Browse to open the file selection dialog, so that you can navigate to the

right location and select the trace file (*.trcxmi or *.xmi).

If the trace file is located on a remote machine, you can specify an FTP location when you browse to find the file.

For anonymous FTP, specify ftp://hostname. For user-authorized FTP, specify

ftp://username:password@hostname.

3. Select the project from the Into Project drop-down menu.

4. (Optional) Check Overwrite existing resources without warning if you want to overwrite the existing trace files, which were imported, without any warning.


6. Click Next.


Page 117


The Define Workload Entry Points dialog appears:

7. Select an existing workload set from the drop-down menu or click New to

create a new one by providing the workload entry point set name. Once you have created a workload set in this manner, you can reselect it for subsequent imports.

A workload is a type of work whose response time directly reflects the response time the end user perceives. The PathWAI profilers automatically identify the application entry points that represent the start of execution of the workloads. When importing traces from other profilers, you need to define workloads in terms of their Java package.class.method. The syntax is equivalent to the Java language import statement.

PathWAI Performance Analyzer does not allow two workload sets to bepresent with the same entry point set name. If a new workload set iscreated with an existing entry point set name, a warning message aboutthe duplicate workload ID set name appears.

If you skip the step of tagging entry points as workloads, the profilingdata will still be imported, and you will be able to view the data in allviews except the workload views.


Page 118


If an existing workload set is selected, the available workload entry points are displayed in the Workload Entry Points area as shown below. If a new one is created, the Workload Entry Points area is blank and the workload entry points can be added with the context menu.

8. To modify the existing workload entry points, select the available entry point,

right-click on it to access the context menu, and choose Modify or Delete.

9. On clicking Modify, the modify workload entry point dialog appears as shown below allowing you to modify the entry point.

10. Modify the workload entry point and click OK to accept the changes. Click

Cancel to cancel the operation.

11. On clicking Delete, the workload entry point is deleted permanently.

12. To add the workload entry points for a new workload set, right-click in the "Workload Entry Points" pane to access the context menu and select New, Browse, or Add From.

13. On clicking New, the New Workload Entry dialog appears as shown below

allowing you to enter a fully qualified workload entry point. Note that no


Page 119


wildcards are permitted in this entry. Enter the workload entry point and click OK to create. Click Cancel to cancel the operation.

14. On clicking Browse, the Define a Workload Entry Point dialog appears as

shown below allowing you to select the packages, classes, methods from a project or archive browser.


Page 120


The Packages, Classes, Methods pane provides a single-context menu action. When the user has navigated to a method, the context menu action to Add as workload is enabled. The action will add the selected method to the Workload ID set. A double-click on a method should invoke the same action.

15. The Workload Set pane shows a list of workloads in the current workload set and its context menu provides the following menu actions:

16. On clicking New, the New Workload Entry dialog appears allowing you to

enter a fully qualified workload entry point. Note that no wildcards are permitted in this entry.

17. On clicking Modify, the modify workload entry point dialog appears allowing you to modify the entry point.

18. On clicking Delete, the workload entry point is deleted permanently.

19. After selecting the packages, classes, and methods, click OK to add the workload entry point for a new workload set. Click Cancel to cancel the operation.

20. On clicking Add From, the Add Workload Entry Point dialog appears allowing you to add workload entry points from another workload set.


Page 121


21. Select an existing workload ID set from the drop-down menu. On selecting the workload ID, the related workload entry points are displayed.

22. Select the existing workload entry point (s) and click OK to add them to the new workload set. Click cancel to cancel the operation.

23. Note that the changes made to the Workload ID set being added from (e.g. modifications, new entries, deletions) are applied only to a temporary in-memory copy of the original workload ID set and not saved to the original workload ID set.

24. The context menu provides the menu actions New, Modify and Delete and the descriptions for the same are given above. These actions act only on the temporary copy of the existing workload ID set.

25. After defining the workload entry points, Click Finish to import the trace data based on the defined workload entry points. Click Back to return to the previous screen or Click Cancel to cancel the operation.

26. The newly imported trace is automatically opened and its data displayed in the views of the PathWAI Performance Analyzer perspective. You can drill down to find the problem. For descriptions of the information available in each view to help you debug your application code, see the Views section of the online User's Guide.

Related Topics

Default Perspective




Page 122


Setting up and Running a Live Trace

This section of the PathWAI Performance Analyzer User Guide gives instructions for:

setting up PathWAI profiling (application tracing)

running a live trace of a J2EE application

checking and changing PathWAI profiling

tracing a WSAD test server

removing PathWAI profiling


Page 123



In addition to importing traces collected by OMEGAMON XE or IBM Profiler, you can use PathWAI Performance Analyzer itself for profiling, or collecting live trace data while your WebSphere Application Server is running. To do this, you need to set up a monitor that instruments the server for trace data collection.

How profiling works

Four components are involved in PathWAI profiling:

PathWAI Profiler operates within the monitored WebSphere Application Server to obtain detailed information from the Java Virtual Machine (JVM) executing your J2EE applications. It reports on the performance of workloads (application transactions) running in the application server and captures information to identify what is causing performance degradation.

PathWAI Profiler uses a technique called dynamic object code instrumentation, or byte code instrumentation, to modify the Java object code for WebSphere and application classes as they are being loaded into the JVM. These dynamic modifications insert hooks into the Java methods so that the time spent executing the methods can be measured. Hooks can also be inserted to track the allocation and collection of Java objects from the heap. The process of inserting measurement hooks is referred to as installing instrumentation.

PathWAI Performance Analyzer provides you with dialogs for installing the PathWAI Profiler into WebSphere and defining the set of methods (by package or class through class filters, or specifically though method filters) and object allocations (through object filters) that will have instrumentation hooks inserted. The result is a set of instrumentation filters.

The hooks are inserted automatically when the classes and objects are loaded into the WebSphere Application Server. Thus, if Instrumentation is subsequently changed, it is necessary to recycle the Application Server.

Once you have created or imported instrumentation sets, you can selectively enable them for a live trace run, so that they capture detailed information on only the classes, objects, and methods you are specifically interested in.

PathWAI Profiler instrumentation sets can apply to both PathWAIPerformance Analyzer and OMEGAMON XE for WebSphere ApplicationServer. PathWAI Performance Analyzer provides wizards and propertiesdialogs that make instrumentation easier to set up. Thus, you can usePathWAI Performance Analyzer to configure instrumentation and thento generate and export an OMEGAMON XE instrumentationconfiguration file (kweiuser.xml).

Collector gathers live traces from the PathWAI Profiler. You do not need to


Page 124


do anything to set up the Collector. It will do its job when the other components are set up.

The Collector uses a TCP port to connect to the PathWAI Profiler. If you encounter a port conflict, you can change the port number in the Collector Properties dialog. (Right-click the Collector icon in the Profiling Monitor view, then select Properties.)

If you change the port number, you must delete and recreate allAdmin Server monitors.

If PathWAI Performance Analyzer is running in WSAD 5.1, the Collector automatically detects the creation and deletion of test servers, and automatically creates a monitor for each test server.

Admin Server monitor tracks the running status of the application servers in a WebSphere instance.

The Admin Server monitor communicates with the WebSphere V4 Admin Server service or the WebSphere V5 management server, so the appropriate one of these must be operational.

If PathWAI Performance Analyzer is running in WSAD 5.1, the monitor tracks the running status of the test servers though the WSAD environment. The test servers need not provide a management service.

In all cases, PathWAI Performance Analyzer needs to monitor the application servers to synchronize with the current process identifier (PID) of the Java Virtual Machine (JVM) the application servers associate with it. When running, the Admin Server monitor automatically adds new application servers that are created in the admin server.

Application servers can have instrumentation installed by the PathWAI Profiler from an instrumentation set that determines which classes, objects, and methods are to be traced. For the application classes to be instrumented as they are loaded, PathWAI Performance Analyzer must modify the JVM arguments and the application server must be recycled.

Requirements

Requirements for setting up and running live traces vary.

WebSphere V4: The WebSphere Administration Service must be started before you set up live tracing. Otherwise, the New Monitor wizard (see step 2 below) will fail to complete and you will have to rerun it after starting the Administration Service.

The Admin Server monitor is required for stopping and starting the application server, and for tracking its status. Once PathWAI Performance Analyzer has started the application server, the Admin Server monitor can be stopped, and only the Collector needs to be running for live traces to occur. The next time PathWAI Performance Analyzer is started, only the Collector is required, if the application server has not been stopped and restarted outside of PathWAI Performance Analyzer's control.

If you want to control access to the Admin Server, each user must have a


Page 125


valid user ID and password. PathWAI Performance Analyzer requires these credentials in a SAS properties file. (See the WebSphere Administrators Guide for instructions.)

WebSphere V5: Before you set up live tracing, it is recommended that you start the application server that provides the WebSphere administration service. Otherwise, the New Monitor wizard (see step 2 below) will complete, but you will need to use the context menu of the application server icon to start the application server.

The Admin Server monitor is not required to be running when the application server is started and stopped by the controls of PathWAI Performance Analyzer. However, if the application server is started and stopped outside of PathWAI Performance Analyzer, the Admin Server monitor is required for tracking the application server's current status.

If you want to control access to the Admin Server, each user's login ID must have write access to the server's log and config directories.

WSAD test servers: You do not need to set up live traces of WSAD test servers. If PathWAI Performance Analyzer is installed into WSAD 5.1 and you start the Collector in the Profiling Monitor tab, PathWAI Performance Analyzer automatically detects the creation or deletion of WSAD test servers, and adds or deletes the test servers in the Profiling Monitor tab. PathWAI Performance Analyzer creates an Admin Server monitor icon and an application server icon for each test server. If the Admin Server monitor is started, the application sServer icon tracks the status of the WSAD test server.

To create a test server, use the WSAD J2EE perspective. PathWAI Performance Analyzer cannot be used to start, stop, or recycle the test servers. They must be controlled from the J2EE Servers navigator. The test servers cannot be monitored and instrumented by PathWAI Performance Analyzer until they have been published in WSAD. See Tracing a Test Server for instructions.

Once you have set up monitoring, your configuration settings are saved and are automatically restored when you restart the Eclipse/WSAD IDE. The instrumentation installed into the WebSphere application servers remains in place until you remove it.

To run a trace using the instrumentation you have already installed, you need only start the Collector, assuming the application servers have not been recycled since PathWAI Performance Analyzer last monitored them. If the application servers have been recycled, the Admin Server monitors must be started to enable PathWAI Performance Analyzer to synchronize with the current status of the application servers.

Important security note

PathWAI profiling traces capture the values of parameters that are passed by the applications being traced. Therefore, please ensure that suitable security measures are put in place to preserve the sensitivity and privacy of data. PathWAI Performance Analyzer honors the security of the WebSphere Application Server, and instrumentation will not be installed onto a secured WebSphere instance.


Page 126


Setting up a Monitor and Instrumenting a Server

Follow these steps to set up an Admin Server monitor and instrument an application server for live tracing of WAS V4 or V5.

These instructions do not apply to WSAD test servers. For information ontracing WSAD test servers, see Tracing a Test Server.

1. Select the Profiling Monitor tab in the Navigator section of the PathWAI Performance Analyzer perspective.

The Collector icon is red; this means that no trace is enabled.

2. Right-click the Collector, and select New > Monitor.

The Connect to WebSphere dialog is displayed.

3. Specify the full pathname of the directory where WebSphere Application


Page 127


Server is installed, or click Browse... and locate it. Make sure that the correct version of WebSphere is selected. If the node name is not already filled in, specify it. If applicable for WebSphere V5, specify the cell name as well.

4. (WebSphere V4 only) If the Admin Server port number is not already filled in, specify it. If applicable, check Use Security and browse to the location of the security credentials provided in a SAS properties file. (See the WebSphere Administrators Guide for instructions.) Make sure the WebSphere Admin Server service is running before you go on to the next step.

5. Click Detect Application Servers....

The Select Application Server(s) dialog is displayed, with a list of the application servers installed on the machine.

6. Select the application server(s) you want to instrument for trace data

collection, and click OK, then click Next on the Connect to Websphere dialog.

The Select Instrumentation Filters dialog is displayed.

7. Do one of these:

Use the drop-down list to select an existing instrumentation filter set.

To create a new instrumentation filter set, click New..., then type a name for the instrumentation set and click OK.

Default filters (inclusive *, to trace all classes, methods, and objects) are provided for the new instrumentation set.

You will be able to choose a different instrumentation set later, by usingthe Properties dialogs associated with the application server icon; andyou will be able to modify the filters of each instrumentation set, by


Page 128


using the Properties dialogs in the Profiling Resources view. (SeeCreating and Modifying Instrumentation Sets.)

8. Click Finish.

The instrumentation set is saved under Instrumentation Sets in the Profiling Resources view.

The Collector and Admin Server monitor start; their icons in the Profiling Monitor view turn green. The icon representing the application server is gray with a yellow exclamation mark, meaning that the server is not started and instrumentation is pending. For the instrumentation to become active, it must be installed on the application server, and the application server must be recycled.

9. To start the application server, right-click the icon representing the server,

and select Start Application Server.

The Pending Instrumentation Changes dialog is displayed.

10. Click Yes, then wait for the server icon to turn green and for cogs to appear

on the icons for the Collector, Admin Server monitor, and application server. The cogs mean that the application server is instrumented and ready to trace.

Because the instrumentation hooks are being installed during application server startup, this process will now take additional time, depending on your instrumentation filter definition.

If after several minutes the icons have failed to turn green and the cogs have failed to appear, right-click the application server icon and select Properties > Info for more information.

When the icons are green with cogs, you are ready to run a trace and view its data.

For more information about the status indicators, see Interpreting the application server icon.


Page 129


Related Topics



Managing Instrumentation

Changing Default Instrumentation Set

Profiling Monitor

Removing PathWAI Profiling

Tracing a Test Server


Page 130



Before running a live trace from PathWAI Performance Analyzer, read the information and complete the steps in Setting up PathWAI Profiling. Make sure that you have set up profiling and started the instrumented application server, and that the PathWAI Profiler and Collector have connected (icons are green with cogs; see Interpreting the application server icon).

Follow these steps to run a trace.

1. Select the Profiling Resources tab in the Navigator section of the PathWAI Performance Analyzer perspective.

2. If you have not already created a simple project to hold your traces, do so now. See Importing an OMEGAMON XE Trace for instructions.

3. Right-click a project, and select New > Trace.

Selecting New > Trace removes any existing live traces in the project.If you want to keep existing live traces when you run a new trace withthe same instrumentation, right-click the trace icon and selectRetrace. If you want to change the instrumentation and then run anew trace without deleting the existing trace, you must save theexisting trace to a different Eclipse project folder before selecting New> Trace.

The Create a New Trace dialog is displayed.


Page 131


4. Select the instance of WebSphere, the application server you want to trace,

and the project where you want the generated trace to be saved for viewing; provide a label for the trace (optional only); then click Next.

5. On the Define Trace Constraints dialog, specify the length of the trace in seconds and the maximum number of lines in the trace, and click Next.

The minimum trace duration is 5 seconds, and the minimum number of lines is 500. You can set the duration and number of lines as high as you wish. However, if the trace exceeds the limits of memory and disk space, the trace will fail.

6. On the Constrain Filters and Collect Object References dialog, you can select the instrumentation filters to be enabled from the instrumentation set installed on the application server. You can also specify the object references to be collected during the trace. If you want to gather lock analysis data, check Collect Lock Analysis Data.


Page 132


Including object references in your trace greatly increases thememory and disk space required for the trace. Also, objectreferences are collected after the rest of the trace is complete.Therefore, including object references in a trace increases the timeof the trace beyond the specified duration.

7. When the trace is constrained to your liking, click Finish.

The trace begins immediately.

8. Expand the tree of the trace's project.

The icon representing the instrumented application server in the Profiling Resources view should be amber, to indicate that tracing is underway; and a running trace icon appears under the instrumented server icon.

9. If you want to stop the trace while it is running, right-click the icon and select

Stop tracing from the context menu.

10. When the trace has finished, the icon turns green and the trace is added to

the list.

11. The trace is now ready to be opened and viewed.

12. To rerun a trace with the same settings, right-click the trace icon in the Profiling Resources view and select Retrace from the menu that appears.

When you select Retrace, the repeated trace will use the sametrace constraints you specified for the selected item. However, whileattempting to rerun an existing live trace in the project when thetrace file (*.trc) is already opened and locked by an external editor,the live trace process terminates and displays an error in the PDEruntime error log. The description of this error is also displayed inthe properties dialog of the trace.

13. To delete a trace, right-click the trace icon and select Delete from the menu.

When you select Delete, the trace is deleted permanently.

14. To rename the trace, right-click the trace icon, select Rename from the menu and edit the title of the trace.


Page 133


You can view details of the server (agent) by right-clicking the icon that represents the instrumented application server and selecting Properties from the context menu. The Properties dialog displays details such as name, type, version, status, number of traces, details of last trace file and the last error.

The last error describes when and why the trace process terminated. Typically, while attempting to rerun an existing live trace in the project when the trace file (*.trc) is already opened and locked by an external editor, the live trace process terminates and a description of this error is displayed in the PDE runtime error log and the Properties dialog of the trace.

Related Topics




Profiling Monitor



Page 134



Once you have set up PathWAI profiling, you can check on its status, correct any problems, and change the instrumentation sets applied to each application server instance.

Checking Application Server Status

If you find the application server icon gray (unknown status), you can check on its status and attempt to restart it:

1. In the Profiling Monitor view, right-click the application server icon and select Discover Status from the context menu.

If possible, PathWAI Performance Analyzer starts the application server with

profiling instrumentation. After a few minutes, the icons in the Profiling Monitor view should turn green with cogs, to indicate that the application server is running and instrumented.

2. If the application server icon remains gray or turns red, right-click the Admin

Server monitor icon and select Properties from the context menu. Do the same with the application server icon.

On the Info properties dialog, examine the Status and Last Error fields for information about the problem.


Page 135


You might need to restart the Admin Server, apply pending instrumentation,

or recycle the application server.

3. If you are still unable to start the application server with instrumentation, perform a PathWAI Performance Analyzer trace.

Checking Trace Properties

To check on the filters applied for a trace, right-click the trace in the Profiling Resources view, then select Properties > Trace Constraints.

If you want to change the filters, you need to modify the instrumentation set. For descriptions of the icons used in instrumentation and trace properties dialogs, see Creating and Modifying Instrumentation Sets.

Related Topics





Profiling Monitor


Collecting a PathWAI Performance Analyzer Trace


Page 136


Tracing a Test Server

PathWAI Performance Analyzer can instrument and trace WebSphere Application Server V5 Base or Express test servers. These test servers are configured in the WebSphere Studio Application Developer (WSAD) workspace, which runs on an Eclipse base. If you install PathWAI Performance Analyzer into WSAD 5.1 and then start the Collector in the Profiling Monitor tab, PathWAI Performance Analyzer automatically detects the creation or deletion of WSAD test servers, and adds or deletes the test servers in the Profiling Monitor tab. PathWAI Performance Analyzer creates an Admin Server monitor icon and an application server icon for each test server. If the Admin Server monitor is started, the application server icon tracks the status of the WSAD test server.

To create a test server, use the WSAD J2EE perspective. PathWAI Performance Analyzer cannot be used to start, stop, or recycle the test servers. They must be controlled from the J2EE Servers navigator.

1. Open the WSAD J2EE Perspective.

2. Select Server > New > Server and Server Configuration.

3. Select WebSphere 5 > Test Environment. (You can select Express Test Environment instead of Test Environment, but the Express Test Environment does not support Enterprise Java Beans (EJB).)

4. Open the PathWAI Performance Analyzer perspective.

5. In the Profiling Monitor tab, select Collector > Start Collector.

PathWAI Performance Analyzer automatically detects the test server and creates an Admin Server monitor for it. For PathWAI Performance Analyzer to instrument the test server, the Admin Server monitor must be started.

6. To install instrumentation, right-click the application server icon and select Properties > Pending Instrumentation, then select an instrumentation set. (To create a new instrumentation set, see the instructions in Creating and Modifying Instrumentation Sets.)

7. Recycle the application server to install the instrumentation set.

8. In the WSAD Server - Servers view, start the test server, then select Add and remove projects to add EJB or servlet J2EE applications to the test server.

The first time you do this, the application server icon in the PathWAI Performance Analyzer Profiling Monitor tab shows an error. If you right-click the icon and select Properties, an error message explains that the server has not yet been published. If you start the test server from the J2EE view, it will be published, and you can then right-click the application server icon in the Profiling Monitor tab and select Start Application Server.

PathWAI Performance Analyzer does not support WSAD with WebSphereApplication Server V4 Single Server. If you attempt to instrument aWSAD V4 test server, all attempts to start monitoring result in an error.Also, if you set up monitoring for the runtimes directory, the attemptwill fail. You can find an explanation by right-clicking the application


Page 137


server icon and selecting Properties > Info.

Related Topics


Profiling Monitor


Page 138



When you no longer wish to instrument and monitor applications in a WebSphere instance, you can remove PathWAI profiling.

Removing All Instrumentation

If you want to keep the Admin Server monitor and application server icons in the Profiling Monitor view, but you want to remove installed and pending instrumentation, follow these steps:

1. In the Profiling Monitor view, right-click the application server icon and select Remove Instrumentation from the context menu.

2. Click OK on the confirmation dialog.

3. After a few minutes, you can verify that instrumentation has been removed. To do this, right-click the application server icon and select Properties > Info from the context menu.

The Properties dialog should look like this:

Removing instrumentation does not delete the instrumentation sets youhave defined or imported. It simply removes them from the applicationserver.

Removing Installed Instrumentation Only

To remove installed instrumentation but retain pending instrumentation:

1. In the Profiling Monitor view, right-click the application server icon and select Properties > Installed Instrumentation from the context menu.

2. Click Remove Installed, then click OK to confirm removal of the installed instrumentation.

3. On the pop-up that appears, click Restart Now or Restart Later.

The application server must be restarted from within PathWAI Performance Monitor to complete removal of the instrumentation. When the application server is restarted, a pop-up asks whether you want to install the pending instrumentation.


Page 139


Removing Pending Instrumentation Only

To remove pending instrumentation:

1. In the Profiling Monitor view, right-click the application server icon and select Properties > Pending Instrumentation from the context menu.

2. Click Remove Pending, then click OK to confirm.

The pending instrumentation set (that is, the instrumentation set that has been assigned to the application server but has not yet been installed) is removed.

Removing All of PathWAI Profiling

If you want to remove all of PathWAI profiling, including the Admin Server monitor and application server icons, do this:

1. If you have been monitoring WebSphere V5, go on to the next step.

If you have been monitoring WebSphere V4, make sure the WebSphere Admin Server service is running before you go on to the next step.

2. In the Profiling Monitor view, right-click the Admin Server monitor icon and select Delete Admin Server Monitor from the context menu.


This action uninstalls the instrumentation and the PathWAI Profiler from that WebSphere instance. The instrumentation files you have defined are saved and will be available for selection if you reinstall instrumentation later.

If PathWAI Performance Analyzer is unable to complete its automatic removal of PathWAI profiling, you will receive a message instructing you to complete the process manually. In that case, follow the instructions given below for your version of WebSphere.

Manual Removal of PathWAI Profiling: WebSphere V4

If the automatic removal procedure fails, follow these steps to complete uninstallation of PathWAI Profiler and instrumentation from a WebSphere V4instance.

1. Start the Admin Server.

2. Start the Administrative Console.

3. Select the relevant application server.

Tree view

WebSphere Administration domain

Nodes

<Your node>


Page 140


Application Servers

<Relevant Application Server>

4. Select JVM Settings > Advanced JVM Settings to open the Advanced JVM Settings dialog.

5. In the Advanced JVM Settings dialog:

1. Edit the Command line arguments to remove these:

-Dcom.candle.kwe.instrument.control_file=<Eclipse plug-in path>\kweinstr.xml

-Dcom.candle.kwe.workanalysis.kweprof.filename=<Eclipse plug-in path>\kweInstr\kweprof.dll

-Dsun.boot.library.path=<Eclipse plug-in path>\kweInstr;<WAS path>\bin;<WAS path>\java\jre\bin

where

<Eclipse plug-in path> is the path to the Candle plug-in in your Eclipse/WSAD installation

<WAS path> is the path to your WebSphere installation

2. Edit Boot classpath (prepend) to remove this:

<Eclipse plug-in path>\kweInstr\KWESCL~1.JAR;<Eclipse plug-in path>\kweInstr\kwewa.jar

3. Click OK, then click Apply to make your changes take effect.

6. Recycle the application server.

Manual Removal of PathWAI Profiling: WebSphere V5

If the automatic removal procedure fails, follow these steps to complete uninstallation of PathWAI Profiler and instrumentation from a WebSphere V5instance.

1. Start the Management Server.

2. Start the Administrative Console.

3. Select Servers > Application Servers > <relevant_application_server>.

4. Select Configuration > Additional Properties > Process Definition > Additional Properties > Java Virtual Machine.

5. In the General Properties table:

1. Edit the Generic JVM Arguments to remove these:

-Dcom.candle.kwe.instrument.control_file=<Eclipse plug-in path>\kweinstr.xml

-Dcom.candle.kwe.workanalysis.kweprof.filename=<Eclipse plug-in path>\kweInstr\kweprof.dll

style="color: #FF5F00">-Dsun.boot.library.path=<Eclipse plug-in path>\kweInstr;<WAS path>\bin;<WAS path>\java\jre\bin

-Xbootclasspath/p;<Eclipse plug-in


Page 141


path>\kweInstr\KWESCL~1.JAR;<Eclipse plug-in path>\kweInstr\kwewa.jar

where

<Eclipse plug-in path> is the path to the Candle plug-in in your Eclipse/WSAD installation

<WAS path> is the path to your WebSphere installation

Unless you have other special settings, the Candle settings will be theonly ones in Generic JVM Arguments.

2. Click Apply > Save > Save to make your changes take effect.

6. Recycle the application server.

Related Topics




Profiling Monitor


Page 142


Managing Instrumentation

This section of the PathWAI Performance Analyzer User Guide provides an overview of the Instrumentation Editor and gives instructions for:

creating and modifying instrumentation sets for live traces

instrumenting system classes

importing and exporting PathWAI Monitor instrumentation control files

viewing installed instrumentation sets

changing instrumentation on the application server

deleting instrumentation sets


Page 143



PathWAI Performance Analyzer provides an in-built, full page, form-based, multi-tabbed editor for modifying the contents of the KWE user instrumentation file (kweiuser.xml). The Instrumentation Editor provides support for all parameters, entry of free-form text, and browsing of external archive files and Eclipse projects.

The Instrumentation Editor comprises three tabs, mainly:

Column Title

Description

Instrumentation

Provides a source browser, and a tabbed view onto the configured classmasks, heap allocation and monitor contention classes.

Source Provides a syntax coloring and validating text editor for the underlyingkweiuser.xml source.

Advanced Provides access to the majority of attributes contained on theKWEINSTR element.

The Instrumentation tab and Advanced tab are synchronized with the Sourceeditor view and hence, the modifications to the source are immediatelyreflected in the other two views.


Page 144


Instrumentation Tab

The Instrumentation tab has two composites, mainly

Instrumentation view containing the tabbed views for displaying the configured class masks, user defined workloads and delays.

Source view containing the source-browser that offers tabbed tree views onto the various supported sources.

The Instrumentation View has the following tabs:

Instrumentation tab providesa tree-view of Packages, Classes,Methods, ObjectInstrumentation, and LockContention settings withmappings to the underlying XML.

Instrumentation tab providescontext menu, drag-and-dropand key bindings support. Clickhere for details.

User Defined Workloads tabprovides a tree-view of thedefined workloads with mappingsto the underlying XML.

User Defined Workloads tabprovides context menu, drag-and-drop and key bindingssupport. Click here for details.

User Defined Delays tabprovides a tree-view of thedefined delays with mappings tothe underlying XML.

User Defined Delays tab providescontext menu, drag-and-dropand key bindings support. Clickhere for details.


Page 145


The Source View or Source Browser has the following tabs:

Project tab allows you to select the packages, classes, methods from a project browser.

Archive tab allows you to select the packages, classes, methods from an archive browser.

Instrumentation tab provides a view of existing instrumentation sets to enable concatenation from existing into a new set.

Trace tab provides a tree view of the currently opened trace file, allowing you to choose specific packages, classes and methods from that trace for inclusion in the instrumentation set being edited.

The Source browser provides context menu, drag-and-drop and key bindings support. Click here for details. Note that the Source browser context menus adapt depending on the currently active tabbed-view in the Instrumentation View.


Page 146


Source Tab

The Source tab provides a syntax coloring and validating text editor for the underlying kweiuser.xml source. The tab provides facilities for syntax highlighting and an annotation model for inline highlighting of syntax and content errors. The changes made in this source tab editor are reflected in the Instrumentation tab, User Defined Workloads tab and User Defined Delays tab.

The following are the levels of syntax highlighting supported by the editor:

Brown : XML Comments & Processing Instructions

Blue : XML Tags

Green : XML Values

The editor provides ruler and text annotations. These annotations highlight errors in the XML file to flag problems with either the syntax or the content. The following shows examples of both ruler and text annotation as provided in a simple Java editor.


Page 147


By hovering over either the text or ruler annotation marker, a tool-tip is displayed to indicate the nature of the error.

You can right-click on the editor and access the context menu to Undo, Revert, Cut, Copy, Paste, and Save.

Advanced Tab

The Advanced tab provides access to all known attributes in the KWEINSTR tag of the kweiuser.xml file.

Given below is the list of attributes and their description:

Attribute Description

Collect CPUTime

Indicates whether or not workload analysis should collect CPU timinginformation i.e. the CPU time consumed by each workload, as well asthe total length of time the workload takes to complete processing.

Show InternalWorkloads

Indicates whether or not workloads invoked by other workloadsshould be tracked as separate workloads, or whether they shouldappear as delays to the original invoking workload.

Workloads Indicates the maximum number of classes that can be instrumented


Page 148



and Methods

Heap Analysis Indicates the maximum number of classes that should be tracked bythe Heap Analysis feature.

Show MethodArguments

Indicates whether or not workload analysis should collect thearguments that are passed to instrumented methods. This attributecan be overridden for specific classes in the Class tag.

Always UsetoString()

Indicates whether it is safe or unsafe to call the toString() method forany object. This attribute has two possible values: "Direct" or"Indirect".

"True' indicates that it is safe to call the toString() method forany object.

"False" indicates that toString() is not generally safe to useand calling it may have some unintended side effects.

Define ClassActivation Variable

Indicates whether workload analysis should define the ClassActivation field within each instrumented class. Defining this field canimprove performance, but may cause problems for certain classeswhich are serialized by Java. This attribute can be overridden forspecific classes in the Class tag.

Measure HeapDelays

Indicates whether or not workload analysis should track workloaddelays due to heap allocations.

Collect InFlight Workloads

Indicates whether or not Workload Analysis should capture call stackinformation for workloads that could potentially appear in the InFlight Workloads workspace. This attribute has three possible values:"All", "None", or "Capture".

All: Collect call stack information for the In Flight Workloadsworkspace for all workloads, regardless of whether theworkload is being measured.

None: Dont collect In Flight Workload information at all.

Capture: Only collect call stack information for the In FlightWorkloads workspace for workloads that are being measured.If the workload capture percent is less than 100, then callstack information will not be collected for all workloads.

System ClassInstrumentation

Indicates how instrumentation will be performed on system classes.It is recommended to have the default value of "Direct".

CTG DelayPlugin ClassName

Indicates the name of the customer-provided plugin class which iscalled in order to determine the major and minor names of delaysdue to the CICS Transaction Gateway. This class must be found onthe class path specified by the UserClassPath attribute. If thisattribute is not specified, then the plugin class is not called, anddelays due to CTG are assigned default major and minor names.

User ClassPath

Specifies a class path for locating customer-provided plugin classes(such as the CTGDelayPlugin class). This value must contain one ormore path names or JAR file names, separated by the standard pathseparator character for the platform. If this parameter is omitted,


Page 149



then no plugin classes can be located.

Log File Name Identifies the name of the Workload Analysis log file. The process idof the application server is inserted into the log file name.

Write Configuration File

Indicates whether or not the contents of the instrumentation controlfiles are to be written to a log file at startup time by workloadanalysis. This attribute has three possible values: "No", "Java ", or"Log".

No: Don’t write the contents of the control file.

Java: Write the contents of the control file to the standardJava (WebSphere) log file.

Log: Write the contents of the control file to the workloadanalysis log file.

Internal Trace Indicates whether or not workload analysis tracing should beenabled. This attribute has ten possible values:

True: Enables all tracing.

False: Disables all tracing.

All: Enables all tracing (except Integrity Check).

Background Thread: Traces the workload analysis backgroundthread.

Socket Interface: Traces the socket interface (to see flow ofdata to the monitoring agent).

Collector: Trace the collector component.

Instrumenter: Trace the instrumenter component.

Exceptions: Trace exceptions that are caught.

Integrity Check: Causes workload analysis to check theintegrity of the Instrumented Method Stack for each methodentry and exit. This is a very expensive trace that should onlybe enabled at the direction of R&D or Level 3.

Heap: Traces the heap analysis component.

Related Topics


Instrumenting System Classes


Page 150



Follow these steps to create an instrumentation set that specifies the classes, methods, and objects for which application server trace data will be collected:

1. In the Profiling Resources tab of the PathWAI Performance Analyzer perspective, right-click Instrumentation Sets and select New > Instrumentation... from the context menu.

2. On the New Instrumentation Set dialog, type a name for the instrumentation

set, and click OK.

The new instrumentation set is added to the list in the Profiling Resources tab and the Instrumentation Editor view is displayed.

3. On the instrumentation Editor, select the User Defined Workloads tab. On the User Defined Workloads tab, right-click and select New > Workload.

The New Workload Entry dialog appears:

4. Enter the major and minor name and click OK. No wildcards are permitted in

this entry.

5. You can use the context menu to define a new class mask and method name. Learn more about User Defined Workloads tab's context menu options here.


Page 151


Alternatively, you can use the source view of the Instrumentation Editorto define a new workload. You may use Project tab, Archive tab,Instrumentation tab, or Trace tab to define a new workload from projectbrowser, archive browser, existing instrumentation set, or currentlyopened trace file respectively. For example, on the Archive tab of thesource view, select a *.jar, *.war, or *.ear file to list the packages,classes and methods. Right-click the package, class or method and selectNew > Workload.

The User Defined Workloads tab also provides a drag-and-drop supportfrom the Source view of the Instrumentation Editor. In addition, theUser Defined Workloads tab supports the key bindings, over and abovedefault key bindings provided with the SWT controls. Click here fordetails.

6. On the instrumentation Editor, select the Instrumentation tab. The Instrumentation tab provides default filters i.e. inclusive * to trace all classes, methods, and objects.

Right-click on the Instrumentation tab and select New > Class Filter.


Page 152


In the General tab, specify the Java package.class of the classes to be instrumented. The syntax is equivalent to the Java import statement, with two wildcard characters supported: * (multi-character wild card) and ? (single-character wild card). You can use Exclusive filters to disable subsets of classes that would otherwise be instrumented by a more global Inclusive filter. To trace application data from all classes in any package, specify the filter * and select Inclusive.

The Advanced tab provides access to attributes in the KWEINSTR tag of the kweiuser.xml file. Select the advanced parameters as required.

Select New > Method Filter... to define a new method name.


Page 153


In this dialog, specify the child methods of the parent class filter to be included or excluded in the trace. If you do not define a method filter for the class filter, all child methods are included.

Select New > Object Filter... to define a new heap allocation mask.

In this dialog, specify the object allocations to be instrumented. You can use wildcards to include or exclude groups of objects. To trace all objects allocated during the trace, specify the filter * and select Inclusive.

You can define object filters at two levels: global, or child of a class filter. For example, this instrumentation set has two inclusive object filters.

The global object filter (highlighted in the example) specifies that all allocations of objects from com.candle.* packages in any user code will be


Page 154


traced. The second inclusive object filter restricts tracing of allocations of the commonly used java.lang.StringBuffer object to methods in the com.candle.* packages.

Select New > Lock Filter... to define a new lock contention mask.

In this dialog, specify the lock objects that will be instrumented. You can use wildcards to include or exclude groups of lock objects.

You can use the context menu to modify or delete a class mask, method name, object mask, or lock filter. Learn more about Instrumentation tab's context menu options here.

Alternatively, you can use the source view of the InstrumentationEditor to define a new method, object or lock. You may use Project tab,Archive tab, Instrumentation tab, or Trace tab to define a new methodfrom project browser, archive browser, existing instrumentation set, orcurrently opened trace file respectively. For example, on the Archivetab of the source view, select a *.jar, *.war, or *.ear file to list thepackages, classes and methods. Right-click the package, class ormethod and select Include Methods, Exclude Methods, IncludeObjects, Exclude Objects, Include Objects Allocated By, orExclude Objects Allocated By.


Page 155


In addition to context menu, the Instrumentation tab provides a drag-and-drop support from the Source Browse and supports key bindings,over and above default key bindings provided with the SWT controls.Click here for details.

7. On the instrumentation Editor, select the User Defined Delays tab. On the User Defined Delays tab, right-click and select New > Delay.

The New Delay Entry dialog appears:

8. Enter the major and minor name and click OK. Note that no wildcards are

permitted in this entry.

9. You can use the context menu to define a new class mask and method name. Learn more about User Defined Delays tab's context menu options here.

Alternatively, you can use the source view of the InstrumentationEditor to define a new delay name. You may use Project tab, Archivetab, Instrumentation tab, or Trace tab to define a new delay namefrom project browser, archive browser, existing instrumentation set,or currently opened trace file respectively. For example, on theArchive tab of the source view, select a *.jar, *.war, or *.ear file tolist the packages, classes and methods. Right-click the package, classor method and select New > Delay.


Page 156


The User Defined Delay tab also provides a drag-and-drop supportfrom the Source view of the Instrumentation Editor. In addition, theUser Defined Delay tab supports the key bindings, over and abovedefault key bindings provided with the SWT controls. Click here fordetails.

10. On the Instrumentation Editor, select the Advanced tab and set the required attributes.

The Advanced tab provides access to all known attributes in the KWEINSTR tag of the kweiuser.xml file. Click here to learn more about the descriptions of the attributes.

When you have created the desired instrumentation filters, select File > Save.

You also have the option of using the Source tab of Instrumentation Editor tomanually edit the source code of an instrumentation control (XML) file. On theInstrumentation Editor, select Source tab to reach the source code editor andedit the XML file as required. For more details, see Instrumentation Editor.

The instrumentation set is made available to the application server. To apply the instrumentation set to the application server, follow the instructions in Checking and Changing PathWAI Profiling.


Page 157


Instrumentation Icons

Icon Description

Inclusive filter

Exclusive filter

Inclusive child method filter

Inclusive object references filter

Method instrumentation

Object instrumentation

Object references

Lock Contention

Related Topics




Tips: Changing Default Instrumentation Set

Tips: Effectively Instrumenting System Classes


Page 158



PathWAI Performance Analyzer is designed to support instrumenting those Application Server System Classes that are invoked through the execution of a User Application.

System classes are those classes that belong to the Application Server, for example javax.InitialContext etc. In general, system classes are those that are loaded from the Application Servers lib directory.

The application trace starts recording the method, object and other events after it is "triggered" by a method call, which maps to a workload entry point instrumented by the user. These workload entry points are user methods, which are typically implemented using JSP pages or Servlets in web based java applications, and EJB method calls in J2EE server applications.

Since the System Classes can be traced only after a user workload is detected for tracing by matching a User Class filter, it is important that at least one User Class filter exists in addition to the System Class filter in the instrumentation set.

In addition, you must realize the impact of instrumenting System Classes:

System Classes are invoked by all user applications and hence, the overheads of instrumentation is present in all applications.

There are innumerous System Classes and hence, instrumentation of System Classes with a wild card filter has a massive impact on the performance of the system.

During the start of an application server, System Classes are instrumented before User Classes. Note that there is a limit to the number of classes that will be instrumented and it is possible for this limit to get exhausted before any User Classes are loaded resulting in no trace data being collected, as it is the User Classes that include the workload entry points.

To effectively instrument System Classes and obtain the best possible results, it is recommended that you instrument system classes for specific packages. If you want to instrument system classes for all packages, create different application traces with constraints resulting in the selection of specific packages for each trace.


Page 159


Given below is the step-by-step procedure for instrumenting system classes. The instructions consider javax.*packages and com.ibm.* application, which is supplied along with Websphere, as examples to demonstrate how system classes are instrumented:

1. In the Profiling Resources tab of the PathWAI Performance Analyzer perspective, right-click Instrumentation Sets and select New > Instrumentation from the context menu.

2. On the New Instrumentation Set dialog, type a name for the instrumentation set, and click OK. The new instrumentation set is added to the list in the Profiling Resources tab.

3. Double-click the name of the new instrumentation set to open the

Instrumentation Editor.

When the instrumentation Editor appears, select the Instrumentation tab.

The Instrumentation page provides default filters i.e. inclusive * to trace all

classes, methods, and objects.

4. Delete the default filters i.e. inclusive *.


Page 160


5. Right-click on the Instrumentation view and select New > Class Filter

The Define a Class Filter dialog appears:

6. In Class Filter field, specify the com.ibm.*

7. Select User to be the Classloader Type and retain the other default settings.

8. Click OK to accept the changes and return to the Instrumentation tab.

9. On the source view, select the Archive tab and select or browse to the sample *.jar file: <websphere_location>\lib\j2ee.jar


Page 161


The Archive tab displays all the packages, classes, and methods of this j2ee.jar file as shown below:

10. Right-click the following packages and select Include Methods from the

context menu:

Java.ejb

Java.ejb.spi

Javax.jms

Javax.net

Javax.resource

Javax.servlet

Javax.servlet.http

Javax.servlet.jsp

Javax.sql

Org.w3c.dom

Org.xml.sax


Page 162


The updated instrumentation tab displays the included methods:

11. On the Instrumentation tab, right-click each of these packages and select

Modify from the context menu.

The Modify a Class Filter dialog appears:

12. Select System to be the Class loader Type and retain the other default

settings for each of these packages.


Page 163


13. Click OK to accept the changes and return to the instrumentation tab.

14. On the Instrumentation tab, right-click Object Instrumentation and select New > Object Filter to display the Define an Object Filter dialog.

15. In the Object Filter field, enter java.ejb.* and click OK.

16. Repeat step 14 and step 15 to define the following object filters:

>Java.ejb.spi.*

Javax.jms.*

Javax.net.*

Javax.resource.*

Javax.servlet.*

Javax.servlet.http.*

Javax.servlet.jsp.*

Javax.sql.*

Org.w3c.dom.*

Org.xml.sax.*

The updated instrumentation tab displays the defined object filters.

17. After specifying the classes, methods and objects, select File > Save to save the instrumentation set.

The instrumentation set is now made available to the application server.


Page 164


Once the instrumentation set is created for instrumenting system classes, you can apply this pending instrumentation to an Application Server. See Checking PathWAI Profiling for details. However, ensure that you select SampleAddressBookSystemClass. When prompted for restart of the server, click Restart Now to install the instrumentation and start the application server.

When an instrumentation set is applied to an Application Server, only a copy ofthe actual instrumentation set is applied. So, when you change theinstrumentation set in the Profiling Resources view, ensure that you reapply it tothe Application Server and recycle the Application Server. You can recycle theApplication Server by right-clicking the application server icon in the ProfilingMonitor view and selecting Recycle Application Server.

During the start of an application server, System Classes are instrumented before User Classes. Note that there is a limit to the number of classes that will be instrumented and it is possible for this limit to get exhausted before any User Classes are loaded resulting in no trace data being collected, as it is the User Classes that include the workload entry points. This limit to the number of classes that will be instrumented is defined in the kweiuser.xml file, which is an instrumentation control file provided to the user for specifying which user-defined classes should be instrumented. The kweiuser.xml file is located in<eclipse_workspace_location>\.metadata\.plugins\com.candle.khe.model.agent\<instrumented_applicationserver_name>

E.g. c:\eclipse\workspace\.metadata\.plugins\com.candle.khe.model.agent\server1-1256096860

In order to support instrumentation of additional number of classes, a manual editing of the kweiuser.xml file is required to increase the values of MaxClassesattribute and NumHeapAnalysisClassesattribute.

Perform the following steps to edit the kweiuser.xml file and support instrumentation of additional number of classes:

While applying the pending instrumentation set to an Application Server, when you are prompted for restart of the server, click Restart Later.

On the Profiling Resources view, right-click on the Instrumentation and select Import to import the kweiuser.xml file.

Select or browse to the kweiuser.xml file.

Provide a suitable title for the file and select the project where this file should reside.


Page 165


Check Overwrite existing.... if you want to overwrite the existing resources

with this file.

Click Finish.

On the Profiling Resources view, double-click the kweiuser.xml file to open the same in Instrumentation Editor.

On the Instrumentation Editor, select Advanced tab and make changes for the following attributes of the Maximum Classes instrumented:

Workloads and Methods indicates the number of system and user classes that will be instrumented and is set with a default value of 1000. Set a high value for this attribute e.g. 5000.

Heap Analysis indicates the number of object allocations and is set with a default value of 5000. Set a high value for this attribute e.g. 15000.

Select File > Save and close the Instrumentation Editor.

Return to the Profiling Monitor view of PathWAI Performance Analyzer and recycle the Application Server.

Note that you will experience a much longer delay in the Application Server startup due to the extra time spent instrumenting all these classes.

After applying the instrumentation set to an Application Server, run alive trace to view the results in the tables. Before running live traces, ensure that you have set up profiling and started the instrumented application server, and that the PathWAI Profiler and Collector have connected (icons are green with cogs). See Setting up PathWAI Profiling for details on setting up PathWAI profiling. See Running a Live Trace for details on running live traces. While running the live trace, access any IBM application that is provided along with WebSphere Application Server e.g. BMP - Address Book, CMP 2.0 - Movie Review, etc. application from the sample gallery. Once the live trace is complete, the table view displays the results based on the instrumented system classes.


Page 166


Given below is the table view that displays the results based on the instrumented system classes on the BMP - Address Book application:

Instrumentation Icons

Icon Description

Inclusive filter

Exclusive filter

Inclusive child method filter

Inclusive object references filter

Method instrumentation

Object instrumentation

Object references

Related Topics




Creating and Modifying Instrumentation Set

Tips: Changing Default Instrumentation Set


Page 167


Importing and Exporting Instrumentation Sets

You can import instrumentation control files from OMEGAMON XE for WebSphere Application Server V120, edit them, and export them for use in monitoring. The OMEGAMON XE instrumentation control files are named kweiuser.xml. (For detailed information about OMEGAMON XE for WebSphere Application Server, see the documentation for that product.)

You can also use PathWAI Performance Analyzer's wizards and propertiesdialogs to set up instrumentation and then to generate and export anOMEGAMON XE instrumentation configuration file. For instructions on settingup instrumentation, see Setting up PathWAI Profiling. For instructions onexporting the configuration file, see step 6 below.

Given below are the steps to be followed for importing instrumentation control files:

1. In the Profiling Resources tab of the PathWAI Performance Analyzer perspective, right-click Instrumentation Sets and select Import... from the context menu.

The PathWAI Instrumentation Control File Import dialog appears.

2. Browse to the location of the kweiuser.xml file you want to import.

Alternatively, you can pull down the drop-down menu and select the location of the file. The drop-down selection lists the locations browsed in the past.

3. In the Save as field, specify a name for the instrumentation set.

4. Select the project from Project drop-down menu.

5. (Optional) Check Overwrite existing resources... if you want to overwrite the existing files without any warning.

6. Click Finish to import the file.

7. Edit the instrumentation set as desired. See the related topics listed below for instructions.


Page 168


Given below are the steps to be followed for exporting instrumentation control files:

1. To export the edited instrumentation set, right-click its name in the Profiling Resources tab and select Export... from the context menu.

The PathWAI Instrumentation Control File Export dialog appears.

The Select Instrumentation Set pane lists all the projects and the

instrumentation sets that were created.

2. Browse to the location to which you want to export the kweiuser.xml file.

Alternatively, you can use the drop-down list to select the instrumentation set you want to export.

The Export File Path specified must end with the file name.

3. In the JVM Profiling Port field, specify the TCP port number used by the OMEGAMON XE instrumentation.

This port number generally defaults to 65535. For further information, see the documentation for OMEGAMON XE for WebSphere Application Server.

4. (Optional) Check Overwrite existing file... if you want to overwrite the existing files without any warning.

5. Click Finish to export the file.


Page 169


Related Topics


Viewing Installed Instrumentation Sets



Page 170



You can view the currently installed instrumentation set that specifies the classes, methods, and objects for which application server trace data will be collected.

To view the installed instrumentation set, right-click the application server icon in the Profiling Monitor view and select Properties > Installed Instrumentation from the context menu.

The PPA Application Server Property Page provides a read-only view of the installed Instrumentation Set.

Related Topics



Deleting Instrumentation Sets

Changing Instrumentation on Application Server


Page 171



Changing Instrumentation Applied to an Application Server

To change the instrumentation applied to an application server, do one of the following:

Remove the installed instrumentation by right-clicking the application server icon in the Profiling Monitor view and selecting Properties > Installed Instrumentation > Remove Installed. (See Removing PathWAI Profiling for instructions.) Then select and apply a pending instrumentation set to the application server.

Modify the instrumentation set in the Profiling Resources view, and then reapply the instrumentation set to the application server.

Any new trace that you run on the reinstrumented application server willdelete existing traces from the project. If you want to change theinstrumentation and then run a new trace without deleting the existing trace,you must save the existing trace to a different Eclipse project folder beforerunning a new trace.

Applying Pending Instrumentation to an Application Server

You can apply pending instrumentation to the application server. Instrumentation is said to be pending rather than active, when instrumentation has been assigned to the application server but has not yet been installed.

Perform the following steps to apply pending instrumentation:

1. In the Profiling Monitor view, right-click the application server icon and select Properties > Pending Instrumentation.


Page 172


2. From the drop-down combo box, select the instrumentation set you want to

apply to the application server, and click Apply.

A message instructing you to restart the application server appears:

3. Click Restart Now to install the instrumentation and start the application

server.

4. Click OK to exit the Properties dialog.

Related Topics




Page 173


Deleting Instrumentation Sets

To delete an instrumentation set:

1. In the Profiling Resources tab, right-click the instrumentation set you want to delete.

2. Select Delete from the context menu.


Related Topics



Importing and Exporting Instrumentation Sets




Page 174


Troubleshooting

This section of the User Guide gives information about:

correcting unsynchronization of PathWAI Performance Analyzer monitoring

dual monitoring

increasing the memory available to Eclipse

running a diagnostic trace of PathWAI Performance Analyzer


Page 175


If PathWAI Performance Analyzer Becomes Unsynchronized

If PathWAI Performance Analyzer has been used for installing instrumentation and running traces, and the product is then reinstalled, you may find problems with starting the instrumented application server from the Profiling Monitor tab. If you right-click the Application Server icon and select Properties, you will find one of these as the Last Error:

Cannot be instrumented. PPA has become unsynchronized with JVM settings.

Cannot be instrumented. Another PathWAI instance has instrumentation enabled.

You need to remove instrumentation manually. Follow the instructions in Removing PathWAI Profiling.


Page 176


Dual Monitoring

If you attempt to install PathWAI Performance Analyzer instrumentation on an application server that is already instrumented by OMEGAMON XE for WebSphere Application Server or by another instance of PathWAI Performance Analyzer, the instrumentation request fails. You can find information about the error by right-clicking the application server icon and selecting Properties > Info.

If the WebSphere instance is already instrumented by OMEGAMON XE for WebSphere Application Server, it must be removed before installing the instrumentation from PathWAI Performance Analyzer . For instructions on removing the OMEGAMON XE instrumentation, see the documentation for OMEGAMONXE for WebSphere Application Server.


Page 177


If Eclipse Runs out of Memory

If you find that Eclipse is running out of memory (for example, during imports of very large trace files) you can try a startup procedure like this example to increase the memory available to Eclipse:

start eclipse -vmargs -Xms256m-Xmx512m

In the example, 256MB is the minimum JVM memory size and 512MB is the maximum JVM virtual memory size. To use this startup procedure, substitute appropriate minimum and maximum virtual memory sizes for those used in the example.


Page 178


Collecting a PathWAI Performance Analyzer Trace

If you encounter problems using PathWAI Performance Analyzer to import, run, display, or delete traces, you can run a diagnostic trace of PathWAI Performance Analyzer itself.

1. Identify the set of actions that exhibit the problem in a reproducible manner.

2. From the PathWAI Performance Analyzer perspective, select Window > Close Perspective.

3. Exit Eclipse

4. Start Eclipse, but do not open the PathWAI Performance Analyzer perspective.

5. Import external plug-ins:

1. Select File > Import.

2. On the Import dialog, select External Plug-ins and Fragments, then click Next.

3. On the first page of the Import Plug-ins and Fragments dialog, click Next to accept the default selections.

4. Select com.candle.khe.ui and click Add required plug-ins, then click Finish.

Eclipse creates a number of projects in the workspace.

6. Select Window > Open Perspective > Plug-in Development.

7. Set up the trace.

1. Select Run > Run....

2. Select Runtime Workbench and click New.

3. (Optional) Assign a name to the trace (for example, PPA_Trace).

4. On the Tracing tab, select Enable tracing.

5. Select com.candle.model.agent (0.0.1) from the list of plug-ins that support tracing.

6. Select the debug property and set it to true.

7. Set the other properties as desired. For example, if you set tracetofile to true, the trace is written to this file: <eclipse_root>\eclipse\runtime-workspace\comCandleKheTrace.log

8. Click Apply, then click Run

An additional instance of Eclipse will open and will launch the trace. This is the instance where you will reproduce the problem.

8. In the tracing instance of Eclipse, select Window > Open Perspective > PathWAI Performance Analyzer.

The tracing instance of Eclipse has a separate workspace (<eclipse_root>\eclipse\runtime-workspace), so your existing workspace projects will not appear in it.

9. If your existing workspace projects are required to reproduce the problem, follow these steps in the tracing instance of Eclipse.


Page 179


1. Select Window > Open Perspective > Resource.

2. Select File > Import > Existing Project into Workspace and click Next.

3. Browse to <eclipse_root>\eclipse\workspace, select the relevant project, and click Finish.

10. Make sure you are working in the tracing instance of Eclipse, and perform the steps to reproduce the problem.

Capture any screen shots that help visualize the problem.

11. Exit the tracing instance of Eclipse.

In the original instance of Eclipse, a Console view will have opened, displaying PathWAI Performance Analyzer and Eclipse trace output.

12. Select Edit > Select all, and copy and paste the Console trace output to a text file. If you set the trace to write to a file, add the contents of this file to your text file:

<eclipse_root>\eclipse\runtime-workspace\comCandleKheTrace.log

13. Save the text file as PPA_<your name>_<date>.txt.

14. Create a zip file containing these files:

1. PPA_<your name>_<date>.txt

2. all files named *.khe* in <eclipse_root>\eclipse\runtime-workspace

15. Include the zip file in the problem documentation you send to Candle.


Page 180


Tips and Tricks

This section of the User Guide gives tips for using PathWAI Performance Analyzer more effectively.


Page 181



The default instrumentation set that PathWAI Performance Analyzer provides for live traces is the most inclusive one possible; it captures trace data for all classes, methods, and objects. Running traces with these settings requires a great deal of memory and disk space and can degrade system performance. If many object references are added when the trace is enabled, the performance impact of the trace is even greater.

Here are some recommendations for setting up instrumentation to collect the trace data you need, without unnecessarily burdening your system.

1. Run your application once with the default instrumentation set enabled.

2. Examine the trace to see the application's flow and to identify the workloads and objects of interest.

3. Refine the filters to limit traces to specific classes of interest.

4. Now you can run the application under load for further traces, without paying the unnecessary overhead of excessive instrumentation.

Related Topics






Page 182


Effectively Instrumenting System Classes

PathWAI Performance Analyzer is designed to support instrumenting those Application Server System Classes that are invoked through the execution of a User Application. See Instrumenting System Classes for more details.

However, the System Classes can be traced only once a user workload has been detected for tracing by matching a User Class filter. Hence, it is important to have at least one User Class filter in addition to the System Class filter in the instrumentation set.

In addition, you must realize the impact of instrumenting System Classes:

System Classes are invoked by all user applications and hence, the overheads of instrumentation is present in all applications.

There are innumerous System Classes and hence, instrumentation of System Classes with a wild card filter has a massive impact on the performance of the system.

During the start of an application server, System Classes are instrumented before User Classes. Note that there is a limit to the number of classes that will be instrumented and it is possible for this limit to get exhausted before any User Classes are loaded resulting in no trace data being collected, as it is the User Classes that include the workload entry points.

To effectively instrument System Classes and obtain the best possible results, it is recommended that you instrument system classes for specific packages. If you want to instrument system classes for all packages, create different application traces with constraints resulting in the selection of specific packages for each trace.

Related Topics



Page 183


Comparing Traces

You can open two instances of PathWAI Performance Analyzer simultaneously, to show two traces side -by-side and compare them. This technique is a handy way to see the results of the changes you make to your application code.

1. Open the PathWAI Performance Analyzer perspective in Eclipse.

2. Import or run a trace.

3. Make changes to the application you are coding.

4. Run and trace the application. If you trace the application with IBM Profiler rather than with PathWAI Performance Analyzer, import the new trace.

5. From the PathWAI Performance Analyzer perspective, select Window > New Window.

Eclipse opens a second PathWAI Performance Analyzer perspective in a new window.

6. Examine the two windows side-by-side and compare the data.

If you import or run new traces, both windows will show the new traces in the Profiling Resources and Profiling Monitor tabs.

Related Topics

Default Perspective





Page 184


Identifying the Main Cause of a Long-Running Workload

To pinpoint the cause of a slow workload:

1. In the All Workloads bar chart, double-click the longest bar (which represents the longest-running workload).

The method of interest will be highlighted in the All Workloads table.

2. Left-click the highlighted method to select it.

The method shows up in the Method Time Eye-catcher pie chart.

3. Select the Selected Method Summary tab.

This bar chart shows the children of the selected method that have the highest Time Self.

4. Review the Method Time Eye-catcher pie chart and the Selected Method Summary bar chart, and navigate down the call tree to investigate the main causes of the slow response. You can navigate down the call tree in either of these ways:

In the Method Time Eye catcher, double-click the largest pie chart segment until you arrive at a method that is all or mostly cyan.

In the Selected Method Summary tab, double-click the longest bar, and the method of interest will be highlighted in the All Packages table. Left-click that method to select it, and it will show up in the Method Time Eye-catcher pie chart.

The method that is the main cause has a high Time Self value and represents a large percentage of the workload, as shown by the gauge at the bottom of the Method Time Eye-catcher.

5. Switch the display of the Method Time Eye-catcher from Proportional to Distributed by clicking the menu arrow in the Eye-catcher's title bar and selecting Show Distributed Time.

6. Use this sequential view to determine where in the method the time is being spent.

Related Topics





Page 185


Spotting Contention among Concurrent Method Calls

By reviewing the Methods table, you may notice method invocations with higher-than-average cumulative time values but average CPU time values. This pattern indicates that the method invocations are blocked from progressing through their normal processing. The block may be the result of contention caused by synchronized access to a particular code section, or by queued or blocking asynchronous access to an external resource.

To identify contention among concurrent method calls, enable the Start Time column in the Method Calls table. To do this:

1. Select Window > Preferences > PathWAI Performance Analyzer > Statistics > Method Calls.

2. Check the Start Time box.

3. Click Apply, then click OK.

4. Examine the All Packages table to see whether the long cumulative times occur in the method invocations that have nearly concurrent start times. If so, you have confirmed contention.

Related Topics

Setting Preferences

Method Calls


Page 186


Spotting Parameter Value Problems

If some invocations of a particular method or workload take much longer than other invocations, examine the parameters for possible patterns of data-sensitive loading.

Example: In a commercial Web site where customers can store preferences while they shop, method getPreferences("<user-name>")retrieves the stored settings from a database. If response time varies greatly among users, the cause might be problematic lookup of a linked record when a user has set a particular option.


Page 187


Reference

This section of the User Guide provides legal information, trademark notices, and instructions for installing and uninstalling PathWAI Performance Analyzer.


Page 188


Candle® PathWAITM Performance Analyzer ReleaseNotes, Version 1.3.0

PathWAI Performance Analyzer is a set of Eclipse plug-ins that provides workload analysis facilities for WebSphere application developers.

Operating Environment

Hardware Requirements

Pentium 200 Mhz, 64 Mb RAM, 100 Mb of free hard drive space.

System Requirements

Windows 32/2000/XP/2003.

WebSphere Studio Application Developer (Application Developer) Release v5.1 users:

Application Developer is based on Eclipse and includes all prerequisites.

Eclipse Integrated Development Environment (IDE) users:

Java Runtime Environment (JRE) 1.3.1 or 1.4.

Eclipse Release 2.1.2 running on Windows 2000 or XP (http://www.eclipse.org).

Eclipse Modeling Framework (EMF) Eclipse feature set Release 1.1.1 (http://www.eclipse.org/emf).

Graphical Editing Framework (GEF) 2.1.2. (http://www.eclipse.org/gef)

Adobe Reader (http://www.adobe.com)

Eclipse 2.1.2, EMF 1.1.1 and GEF 2.1.2 are included on the PathWAI Performance Analyzer product CD. If you are installing PathWAI Performance Analyzer from the CD, you can use the installation wizard option to install Eclipse, EMF and GEF during the product installation. You can also install PathWAI Performance Analyzer into an existing instance of Eclipse 2.1.2 or into Application Developer V5.1, which runs on an Eclipse 2.1.2 base. PathWAI Performance Analyzer can coexist with any version of Eclipse or Application Developer in a separate directory.

Eclipse 2.1.2, EMF 1.1.1 and GEF 2.1.2are not included in the complimentary web download runnable InstallShield, which can be downloaded from the Candle web site for installing PathWAI Performance Analyzer. If you are installing PathWAI Performance Analyzer using this InstallShield and if you do not have Eclipse 2.1.2, EMF 1.1.1 and GEF 2.1.2, you can download them from their respective websites.


Page 189



http://www.eclipse.org/gef

http://www.adobe.com/


To download the required Eclipse prerequisite:

Access http://www.eclipse.org and select Downloads from the menu.

On the Eclipse Project Downloads page, select an appropriate download site depending on your location. You will be redirected to the Project Downloads Page for that location.

On the Eclipse Project Downloads page, select 2.1.2 build name from the "Latest Releases" table.

On the Release Build: 2.1.2 page, you will see Windows 98/ME/2000/XP platform name in the "Eclipse SDK" table. Click "http" to download the file eclipse-SDK-2.1.2-win32.zip.

Ensure that your system meets the Eclipse prerequisite for a JAVA JRE, as detailed in the Eclipse 2.1.2 SDK download page.

Unzip the contents of this ZIP file to create your Eclipse install.

Navigate to the location where the contents were unzipped and double-click eclipse.exe file to start Eclipse.

To download the required Eclipse EMF prerequisite:

Access http://www.eclipse.org/emf and click Download Page from the "Developer Resources" table.

On the EMF Downloads page, you will see Version 1.1.1 Build 20031020_1612WL in the "Latest Releases" table. Select EMF Runtime and click emf_1.1.1_20031020_1612WL.zip.

PPA requires EMF Release 1.1.1. The build level (Build20031020_1612WL) quoted above is correct at the time of writingbut may get updated when Eclipse introduces maintenance for EMFRelease 1.1.1.

Unzip the contents of this ZIP file to your "eclipse" install directory.

To download the required GEF prerequisite:

Access http://www.eclipse.org/emf and click GEF 2.1.2 from the Downloads section.

On the Release Build: 2.1.2 page, click GEF-runtime-I20031015.zip from the "GEF Runtime" table.

Unzip the contents of this ZIP file to your "eclipse" install directory.

To download the required Acrobat prerequisite:

Access http://www.adobe.com/products/acrobat/ and click the .

On the Download Adobe Reader page, choose your language, platform, and connection speed.

Click Download.


Page 190




http://www.adobe.com/products/acrobat/


Instrumented IBM Products

Given below are the IBM products instrumented by PathWAI Performance Analyzer for trace collection:

WebSphere Application Server (WAS) V4.0 Advanced Edition, if installed on the same machine as PathWAI Performance Analyzer.

WAS V5.0 Base Deployment or Network Deployment, if the instrumented node is installed on the same machine as PathWAI Performance Analyzer.

WAS V5.0 (not V4.0) Base and Express Test Servers, if PathWAI Performance Analyzer is running within WSAD V5.1.

Supported Trace File Imports

Given below are the Trace File Imports supported by PathWAI Performance Analyzer:

Candle OMEGAMON® XE for WebSphere Application Server, V110 or V120.

WSAD Profiler V4, V5, or V5.1.

Eclipse Hyades Profiler (http://www.eclipse.org/hyades).

Supported Instrumentation Control File Imports and Exports

The Instrumentation Control File Imports and Exports supported by PathWAI Performance Analyzer include only Candle OMEGAMON XE for WebSphere Application Server, V120.

For detailed information about OMEGAMON XE for WebSphere ApplicationServer, see the documentation for that product.

Warnings and Workarounds

1. The InstallShield Wizard explicitly tests for EMF 1.1.1. If you are installing PathWAI Performance Analyzer into an existing copy of Eclipse 2.1.2 that is installed with EMF 1.1.1, the InstallShield Wizard will still wish to install EMF 1.1.1. This can be done safely and it does not back-level your EMF, as Eclipse feature / plug-in versioning ensures that the higher version of EMF is run.

2. While instrumenting WAS V5.0 Base Deployment, PathWAI Performance Analyzer concurrently instruments and traces only one application server (PRS SR Reference No. - 1-41424571).

3. If Eclipse runs out of memory, you can try a startup procedure explained in the online User Guide. For more information, select Help > Help Contents > PathWAI Performance Analyzer User Guide > Tasks > Troubleshooting.


Page 191

http://www.eclipse.org/hyades


Installation Instructions

Candle customers purchasing PathWAI solution packages receive a complimentary CD containing an InstallShield wrapper and all prerequisites for installing PathWAI Performance Analyzer. Candle also provides a complimentary web download runnable InstallShield that can be downloaded from the Candle web site after accepting the download agreement terms.

If you already have PathWAI Performance Analyzer v100 and you are migrating to v130, it is recommended that you understand the implications of such upgrades and then execute the InstallShield. Given below are the implications of such upgrades and recommendations to salvage the existing instrumentation sets and other data.

Implication Recommendation

Existing applicationtrace file import agentsand imports will nolonger be available inthe upgraded version.

Re-import the original "<OMEGAMON XE for WASApplication trace>.trc" or " <Hyades / WSADProfiler>.trcXmi" files into the upgraded version to viewand analyze the trace data.

Existing instrumentation setswill no longer beavailable in theupgraded version.

Before upgrading, export all the instrumentation sets.

Upgrade the version of PathWAI PerformanceAnalyzer.

Import the instrumentation sets into the upgradedversion.

Existing applicationserver monitors will nolonger be available.

Use "New Monitor" Wizard to reconnect PathWAIPerformance Analyzer to an Application Server. However, nomanual operation is required for Application Developer TestServers. PathWAI Performance Analyzer automaticallycreates a new monitor for the test servers.

Existing live trace datawill no longer beavailable.

PathWAI Performance Analyzer creates only one *.trc filefor storing the data of the live traces and every time a livetrace is run, the created *.trc is overwritten with the dataof the recently run live trace. Hence, during an upgrade, it isnot possible to recreate the data of all the live tracesexecuted in the previous version of PathWAI PerformanceAnalyzer. However, the data of the last run live trace can beused to view and analyze the trace.

Import the *.trc file, which has the data of the lastrun live trace, into the upgraded version of PathWAIPerformance Analyzer. Note that, in such cases,Object Reference data is not recreated in the import.

Re-run the traces.

Existing <filename>.khe?[n]Xmi files are notrequired for theupgraded version.

Before you upgrade to a newer version, you are advised totake a back up of the existing <filename>.khe?[n]Xmi files.To take a back up of these files, highlight the projects inProfiling Resources view, select File > Export and chooseZip File from the Export dialog to export the files to a Zip


Page 192


file on the local file system.

After the back up is taken, delete all old<filename>.khe?[n]Xmi files. Search for files named "*khe*Xmi" in the "workspace" and delete them.

Follow the appropriate install instructions for your media:

Using CD to Install or Upgrade PathWAI Performance Analyzer

If you are upgrading PathWAI Performance Analyzer v100 that was installed using the Web Download Feature ZIP installation Kit, you have to manually uninstall PathWAI Performance Analyzer v100 and reinstall the plug-in. See Uninstall instructions for details. Before you upgrade to PathWAI Performance Analyzer v130, it is recommended that you understand the implications of such upgrades (given above) and then execute the InstallShield.

Given below are the instructions for upgrade or installation of PathWAI Performance Analyzer v130:

1. If PathWAI Performance Analyzer is already installed on your machine, close the PathWAI Performance Analyzer perspective.

2. If you are installing PathWAI Performance Analyzer into an existing copy of Eclipse 2.1.2 or Application Developer V5.1, and if that copy is running, exit from it now.

3. On the PathWAI Performance Analyzer CD, navigate to \Windows, and double-click the file HDv130I1.exe. If one or more instances of this application is already installed on your system, the InstallShield detects the same and offers to maintain or upgrade the existing instance or install a completely new instance. Select one of the following options and click Next.

Select Maintain or update the instance.. to update an existing instance of PathWAI Performance Analyzer. The PathWAI Performance Analyzer Setup Maintenance screen appears and allows you to modify the current installation. Click Repair to reinstall all program features or click Remove to remove the existing instance. When prompted with a message, click Yes to complete remove the selected application and all of its features.

Select Install a new instance.. to install a new instance of PathWAI Performance Analyzer.

4. On the Welcome dialog, click Next to proceed.

The InstallShield informs you about the changes made to the resources for enabling the technical advances in this latest version of PathWAI Performance Analyzer.

5. Click Next to proceed or click Launch Readme to read the Release Notes.

6. Read the license agreement and accept it, then click Next.

The InstallShield identifies the older versions of PathWAI Performance Analyzer installed on your system and lists the same for upgrade.

7. Select one or more listed versions for upgrade and Click Next. If you prefer to proceed without upgrading, click Next without selecting any of the older versions.


Page 193


If Application Developer is installed on your system, the InstallShield detects

the same and offers to install PathWAI Performance Analyzer to this instance of Application Developer. The InstallShield also offers to install PathWAI Performance Analyzer to an existing Eclipse location or create a new Eclipse-based installation.

8. Select an installation option based on your requirement and click Next.

The Installation Location dialog is displayed.

In case you choose to create a new installation or install to an existing Eclipse location, the default installation directory displayed is C:\Program Files\Eclipse unless Application Developer 5.1 is installed; in that case, the default installation directory is the Eclipse directory under the Application Developer root.

In case you choose to install to Application Developer, the InstallShield detects the location of the existing Application Developer and by default displays the same drive for installing PathWAI Performance Analyzer in a directory titled "CandlePPA".

9. To accept the default location, click Next. To change the location, click Browse and select another installation directory, then click Next.

In case of new installation or installation to an existing Eclipse location, provide the Eclipse root directory where you would like to install PathWAI Performance Analyzer.

The installer validates the presence of Eclipse, EMF and GEF and does not allow you to proceed if the selected directory does not contain the prerequisites. Also, the InstallShield explicitly tests for Eclipse 2.1.2, EMF 1.1.1 and GEF 2.1.2. If the selected directory does not contain the required versions of the Eclipse, EMF and GEF, the following message appears. Click Yes to view the README file or No to select another installation directory that contains the required versions of Eclipse, EMF and GEF.

In case of installation to Application Developer, PathWAI Performance

Analyzer must be installed on the same drive as Application Developer, but not in the same directory structure. By default, the InstallShield detects the drive where Application Developer is installed and offers to install PathWAI Performance Analyzer to the same drive in a folder titled CandlePPA.

10. On the Select Features dialog, select the features you want to install and click Next.

PathWAI Performance Analyzer Plug-In

Eclipse v2.1.2

EMF Plug-In v1.1.1


Page 194


GEF Plug-In v2.1.2

Acrobat Documentation for PathWAI Performance Analyzer Plug-In

11. The InstallShield prompts for creating desktop and start menu shortcut for PathWAI Performance Analyzer. Click Yes to create a shortcut or click No to skip this option of shortcut.

12. Provide a new folder name or select one from the existing folders list to add program icons and click Next.

13. Click Install to install the selected features.

14. Once the installation is complete, the InstallShield Complete dialog is displayed. By default, the boxes are checked for launching PathWAI Performance Analyzer or Application Developer (based on the installation option selected) and the README file. Check or uncheck the boxes according to your need and then click Finish to complete the installation.

Using the Web Download Runnable InstallShield

1. If PathWAI Performance Analyzer is already installed on your machine, close the PathWAI Performance Analyzer perspective.

2. If you are installing PathWAI Performance Analyzer into an existing copy of Eclipse 2.1.2 or Application Developer V5.1, and if that copy is running, exit from it now.

3. Double-click the HDv130I1.exe. If one or more instances of this application is already installed on your system, the InstallShield detects the same and offers to maintain or upgrade the existing instance or install a completely new instance. Select one of the following options and click Next.

Select Maintain or update the instance.. to update an existing instance of PathWAI Performance Analyzer. The PathWAI Performance Analyzer Setup Maintenance screen appears and allows you to modify the current installation. Click Repair to reinstall all program features or click Remove to remove the existing instance. When prompted with a message, click Yes to complete remove the selected application and all of its features.

Select Install a new instance.. to install a new instance of PathWAI Performance Analyzer.

4. On the Welcome dialog, click Next to proceed.

5. Read the license agreement and accept it, then click Next.

If Application Developer is installed on your system, the InstallShield detects the same and offers to install PathWAI Performance Analyzer to this instance of Application Developer. The InstallShield also offers to install PathWAI Performance Analyzer to an existing Eclipse location or create a new Eclipse-based installation.

6. Select an installation option based on your requirement and click Next.

The Installation Location dialog is displayed.

In case you choose to create a new installation or install to an existing Eclipse location, the default installation directory displayed is C:\Program


Page 195


Files\Eclipse unless Application Developer 5.1 is installed; in that case, the default installation directory is the Eclipse directory under the Application Developer root.

In case you choose to install to Application Developer, the InstallShield detects the location of the existing Application Developer and by default displays the same drive for installing PathWAI Performance Analyzer in a directory titled "CandlePPA".

7. To accept the default location, click Next. To change the location, click Browse and select another installation directory, then click Next.

In case of new installation or installation to an existing Eclipse location, provide the Eclipse root directory where you would like to install PathWAI Performance Analyzer.

The installer validates the presence of Eclipse, EMF and GEF and does not allow you to proceed if the selected directory does not contain the prerequisites. Also, the InstallShield explicitly tests for Eclipse 2.1.2, EMF 1.1.1 and GEF 2.1.2. If the selected directory does not contain the required versions of the Eclipse, EMF and GEF, the following message appears. Click Yes to view the README file or No to select another installation directory that contains the required versions of Eclipse, EMF and GEF.

In case of installation to Application Developer, PathWAI Performance

Analyzer must be installed on the same drive as Application Developer, but not in the same directory structure. By default, the InstallShield detects the drive where Application Developer is installed and offers to install PathWAI Performance Analyzer to the same drive in a folder titled CandlePPA.

8. On the Select Features dialog, select the features you want to install and click Next.

PathWAI Performance Analyzer Plug-In

Acrobat Documentation for PathWAI Performance Analyzer Plug-In

9. The InstallShield prompts for creating desktop and start menu shortcut for PathWAI Performance Analyzer. Click Yes to create a shortcut or click No to skip this option of shortcut.

10. Provide a new folder name or select one from the existing folders list to add program icons and click Next.

11. Click Install to install the selected features.

12. Once the installation is complete, the InstallShield Complete dialog is displayed. By default, the boxes are checked for launching PathWAI Performance Analyzer or Application Developer (based on the installation option selected) and the README file. Check or uncheck the boxes according


Page 196


to your need and then click Finish to complete the installation.

When Eclipse or Application Developer starts, it runs a configuration update for the PathWAI Performance Analyzer feature and plug-ins. Accept the configuration changes by clicking Finish, then click Yes to restart Eclipse or Application Developer.

To open the PathWAI Performance Analyzer perspective, select Window > Open Perspective > PathWAI Performance Analyzer. If PathWAI Performance Analyzer is not shown in the Open Perspective menu, select Window >Open Perspective > Other... > PathWAI Performance Analyzer.

You can find instructions for using PathWAI Performance Analyzer in the online User Guide. Select Help > Help Contents > PathWAI Performance Analyzer User Guide.

Eclipse Feature Set Distribution ZIP File

1. If PathWAI Performance Analyzer Technology Preview evaluation (PPA v0.0.1) is already installed on your machine, it is recommended that you uninstall it by deleting all the trace files and removing all the monitored WebSphere instances. See Uninstallation Instructions for details.

2. Eclipse or Application Developer must be stopped before installing the Eclipse feature set distribution ZIP file.

3. Install PathWAI Performance Analyzer using the ZIP file downloaded from the Candle web site. The ZIP file contains features, plugins, and readme directories.

For installing PathWAI Performance Analyzer into Eclipse, unzip the entire contents of the ZIP file to \eclipse directory.

For installing PathWAI Performance Analyzer into WSAD, unzip the entire contents of the ZIP file to \WebSphere Studio\Application Developer\vX.X\eclipse directory (vX.X is the version of WSAD e.g. v5.1).

The PathWAI Performance Analyzer is installed to the \eclipse\features, \eclipse\plugins, and \eclipse\readme subdirectories by WinZIP unpack.

4. Restart Eclipse or Application Developer. When it starts, it runs a configuration update for the PathWAI Performance Analyzer feature and plug-ins and a pop-up dialog announces the pending configuration changes.

5. Click Finish to accept the configuration changes.

6. Click Yes to restart Eclipse or Application Developer.

When Eclipse or Application Developer restarts, the PathWAI Performance Analyzer welcome page is displayed.

7. To access the PathWAI Performance Analyzer perspective in Eclipse or Application Developer, select Windows > Open Perspective > PathWAI Performance Analyzer menu or click the perspective tool bar button.


Page 197


8. To access the PathWAI Performance Analyzer online user guide, select Help >

Help Contents menu or use the "F1" key within the PathWAI Performance Analyzer perspective and dialogs.

Uninstallation Instructions

Perform the following steps for uninstalling PathWAI Performance Analyzer that has been installed from a CD:

1. Select Window > Close Perspective to close the PathWAI Performance Analyzer perspective.

2. Exit Eclipse or Application Developer.

3. Select Start > Settings > Control Panel > Add/Remove Programs > Candle PathWAI Performance Analyzer.

4. If you have more than one installed copy of PathWAI Performance Analyzer and want to make sure you are deleting the correct copy, click support information and examine the Comments section of the Support Information pop-up for information about the location of the installed product.

Otherwise, go on to the next step.

5. Click Change/Remove.

6. Select Remove, click Next, then click Yes to confirm.

7. Click Finish.

Perform the following steps for uninstalling PathWAI Performance Analyzer that has been installed using the web download installer or Eclipse feature set distribution ZIP file:

1. Start Eclipse or Application Developer and open PathWAI Performance Analyzer perspective.

2. In the Profiling Resources view, right-click each trace file and select Delete from the context menu. Click OK when you are prompted to confirm the deletion.

Before deleting the trace files, ensure that there are no live traces running. If there are live traces running, stop them and then delete the trace files.

3. If you have been monitoring WAS V5.0, go on to the next step. If you have been monitoring WAS V4.0, make sure the WebSphere Admin Server service is running before you go on to the next step.

4. In the Profiling Monitor view, right-click each monitor icon and select Delete AdminServer Monitor from the context menu. Click OK when you are prompted to confirm the deletion.

If PathWAI Performance Analyzer is unable to complete its automatic removal of PathWAI profiling, you will receive a message instructing you to complete the process manually. In that case, follow the instructions given in the online help topic "Removing PathWAI Profiling".


Page 198


5. Select Window > Close Perspective to close the PathWAI Performance

Analyzer perspective.

6. Exit Eclipse or Application Developer.

7. Delete the PathWAI Performance Analyzer feature and plug-in subdirectories:

For Eclipse \eclipse\features\candle.com.khe.feature_X.X.X \eclipse\plugins\candle.com.khe_X.X.X \eclipse\plugins\candle.com.khe.help_X.X.X \eclipse\plugins\candle.com.khe.model.agent_X.X.X

For WSAD \WebSphere Studio\Application Developer\vX.X\eclipse\features\candle.com.khe.feature_X.X.X \WebSphere Studio\Application Developer\vX.X\eclipse\plugins\candle.com.khe_X.X.X \WebSphere Studio\Application Developer\vX.X\eclipse\plugins\candle.com.khe.help_X.X.X \WebSphere Studio\Application Developer\vX.X\eclipse\plugins\candle.com.khe.model.agent_X.X.X

\WebSphere Studio\Application Developer\vX.X is the rootinstall directory of your Application Developer install.

\candle.com.khe.*_X.X.X is the existing version of PathWAIPerformance Analyzer currently installed on your system.

Online help

Instructions for using PathWAI Performance Analyzer are in the online User Guide. From the copy of Eclipse or Application Developer in which you have installed PathWAI Performance Analyzer, select Help > Help Contents> PathWAI Performance Analyzer User Guide.

Feedback

Candle welcomes your comments. Please feel free to submit suggestions and requests, or report any problems with PathWAI Performance Analyzer. Email: [email protected]

Web: http://www.candle.com/performanceanalyzer


Page 199




Candle Corporation Legal Notices

April 21, 2004

PRODUCT: PathWAITM Performance Analyzer Version1.3.0

Copyright © 20032004, Candle Corporation, a California corporation. All rights reserved. International copyright secured.

Candle Corporation ("Candle") licenses the Product above to a user that has accepted the terms and conditions in the license agreement between user and Candle ("License"). The media containing the Product includes Candle confidential and proprietary software and other material that is licensed for the users internal use only or as stated in the terms of the License, and may not be reproduced, used, or disclosed except as authorized by the License or separate written agreement with Candle. Any unauthorized use, duplication, or disclosure is unlawful.

All software and documentation are subject to export and import laws of the U.S. and, if applicable, the country to which the Product is shipped, and any related federal, state or local laws. The Product may not be exported or reexported outside the territory stated in the License or to any persons or countries prohibited by United States law. For any import or reexport allowed under the License, Licensee will act as importer and/or exporter of record for purposes of record keeping, reporting, licensing, and clearance.

The Product may contain encryption code. Contact your Candle customer support representative for any information regarding export classification by the U.S. Department of Commerce.

All software and documentation are provided with RESTRICTED RIGHTS. Use, duplication or disclosure by the U.S. government is subject to restrictions in the License and/or Government Data Rights Clause(s), as applicable(including but not limited to DFARS 252.227-7013(C)(ii) and FAR52.227-19(a)(d). Unpublished--All rights reserved under United States Copyright laws. Manufacturer is Candle Corporation, 100 Sepulveda Blvd., ElSegundo, CA 90245.

The Product media may include Eclipse Platform 2.1.2, EMF 1.1.1, and GEF2.1.2, the source code of which is distributed by Eclipse.org and available at http://www.eclipse.org. The software is distributed subject to the Common Public License, version 1.0 (http://www.eclipse.org/legal/cpl-v10.html)(see below). Eclipse Platform includes the object and/or source code of International Business Machines (IBM), Apache Foundation, and other contributors to Eclipse.org, which are identified in the Product about files with copyright notices and are publicly available subject to the Apache Software License v.1.1 (http://www.apache.org/licenses/LICENSE)and/or IBM Public License 1.0 (http://oss.software.ibm.com/developerworks/opensource/license10.html),as


Page 200


http://www.eclipse.org/legal/cpl-v10.html

http://www.apache.org/licenses/LICENSE

http://oss.software.ibm.com/developerworks/opensource/license10.html


specified in the about file.

CONTRIBUTORS TO ECLIPSE.ORG (A) DISCLAIM ALL WARRANTIES AND CONDITIONS,EXPRESS AND IMPLIED, INCLUDING WARRANTIES OF CONDITIONS OR TITLE ORNON-INFRINGEMENT, AND IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABLILITYAND FITNESS FOR A PARTICULAR PURPOSE. THE CONTRIBUTORS EXCLUDE ALL LIABILITYFOR DAMAGES, INCLUDING DIRECT, INDIRECT, SPECIAL, INCIDENTIAL ANDCONSEQUENTIAL DAMAGES, SUCH AS LOST PROFITS. ANY WARRANTY OR LIMITATION OFLIABILITY IN THE CANDLE LICENSE AGREEMENT THAT DIFFER FROM THE ABOVE IS MADEON BEHALF OF CANDLE ALONE AND NOT BY ANY OTHER PARTY.

The Product includes software developed by the Apache Software Foundation(http://www.apache.org/), which is available at http://jakarta.apache.org/log4j/docs/index.html (Log4J software) and http://jakarta.apache.org/bcel/ (BCEL). Copyright (c) 2000. The Apache Software Foundation. All rights reserved. Apache software is distributed subject to the following Apache Software License, Version 1.1:

Apache Software License, Version 1.1:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, must include the following acknowledgement: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgement may appear in the software itself, if and wherever such third-party acknowledgements normally appear.

4. The names "The Jakarta Project", "Tomcat", and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected].

5. Products derived from this software may not be called "Apache" nor may "Apache" appear in their names without prior written permission of the Apache Group.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIEDWARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NOEVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FORANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIALDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS ORSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVERCAUSED AND ON ANY THEORY


Page 201

http://www.apache.org/

http://jakarta.apache.org/log4j/docs/index.html

http://jakarta.apache.org/bcel/


OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USEOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


Page 202


Candle Corporation Trial and License Agreement(s)

April 21, 2004

PRODUCT: PathWAITM Performance Analyzer Version1.3.0

Copyright © 20032004, Candle Corporation, a California corporation. All rights reserved. International copyright secured.

PLEASE READ THIS LICENSE AGREEMENT ("AGREEMENT") CAREFULLY BEFORE OPENINGTHE PACKAGE OR DOWNLOADING, INSTALLING OR USING THE PRODUCT. DOING THESETHINGS INDICATES YOUR ACCEPTANCE OF THIS AGREEMENT. IF YOU DO NOT AGREE WITHTHIS AGREEMENT, EITHER HALT INSTALLATION AND RETURN THIS PACKAGE TO YOURSUPPLIER WITHIN THIRTY (30) DAYS OR HALT THE DOWNLOAD PROCESS.

YOU CERTIFY THAT ALL INFORMATION PROVIDED TO CANDLE IN THE REGISTRATIONFORM IS TRUE AND ACCURATE.

You certify that (a) You are not a person or entity prohibited by U.S. Export Administration Regulations (EAR); (b) You are not located in, nor a citizen or national of Cuba, Iran, Iraq, Libya, North Korea, Sudan, or Syria,(b) You will not export, re-export, or in any way provide the Software to any persons or countries prohibited by the EAR and related laws, Including but not limited to, prohibited persons or entities or to any citizen or national of the countries in Sections 6(b), and (c) You will not use the Software, directly or indirectly, in connection with activities related to proliferation of nuclear, chemical or biological weapons or missiles.

The license for this Product is a perpetual license subject to the terms of Sections B and C below. The license is for a complimentary edition of the Product that contains a time limitation feature that will disable certain Product functionality on April 1, 2005. At that time, Candle will make available an updated version of the Product. Please contact Your Candle sales representative for further information. You may continue to use this limited-functionality version of the Product after April 1, 2005, pursuant to the terms of the Agreement.

Please note that this may include third party vendor ("TPV") code ("Code")that is confidential and proprietary copyrighted information, as specified in the "Candle Corporation Legal Notices". Unless otherwise specified, (i)title to all copies of any such Code is retained by the specified TPV and/or its licensors, (ii) the TPVs are direct and intended beneficiaries of this Agreement and may enforce it directly against You, (iii) only the right to use the run-time version of the TPV Code is granted, and (iv) You may use the TPV Code only in conjunction with the Product and only so long as You are an authorized licensee of the TPVs related base software.

Definitions for All Licenses

1. Definitions

"Behavior Module" means a software module that defines how the ETEWatchProduct


Page 203


collects and measures transaction level end-to-end response time information for the one business software application specified by name on the Order Document.

"Candle" means Candle Corporation, the licensor of the Product(s).

"Capacity Unit" is a capacity measurement, as determined by Licensor's then-current Capacity Unit Calculator, which determines the number of CPU's(based on quantity of processors) on which the OMEGAMON XE for MQSeriesIntegrator and OMEGAMON DE for MQSeries Integrator products listed herein maybe used.

"Concurrent User" means the sum total of user sessions accessing the CandleNet Portal Server at the same time.

"Copy" and "Processor" means one physical or logical copy of the Product for use by one Licensed User or on one server, one workstation, one application server, one customer application or a single physical CPU(regardless of Processor quantity) on the platform(s) specified in the Order Document.

"CPU" means any central processing unit, including its associated peripheral units, described herein (including the model and serial number).

"Intellectual Property Rights" means copyright, trade secret, trademark and/or patent rights.

"Licensed Capacity" means the number of Capacity Units, Concurrent Users, Copies, Monitored Items, MIPS, Processors, Sessions or Workstations of a Product licensed hereunder and on the Order Document.

"Licensed Territory" means either the country in which You, the licensee, have your corporate headquarters or in which You download the Product, or as otherwise specified in any Order Document.

"Licensed User(s)" or "Single User(s)" means one (1) person with the limited license right to use only one copy of the software on a single terminal connected to a single computer. Each person desiring to use a Licensed or Single User Product must have a user license.

"Mainframe MIPS" or "MIPS", means the sum total of MIPS, as published by Gartner Group, for each CPU Complex at the Designated Site(s). The MIPS ratings are based on the entire CPU Complex, not a physical or logical partition, or PR/SM and include MIPS added to the CPU by CMOS or other technologies, hardware or software products.

"Monitored Item" means one data source monitored by and providing data to the Candle Universal Agent Product, including without limitation each hardware device, application server or database.

"Non-Partitioned Copy" means one copy of the Product for use on one physical CPU (regardless of the number of processors) that is running a single Lotus Notes/Domino server software application.

"Notes Server Instance" means one Lotus Notes/Domino server software application ("Notes Server") running on a CPU.

"Order Document" means a purchase order generated by You and accepted by Candle or an invoice or other document, electronic or otherwise, generated by Candle, in conjunction with Your order of the accompanying Product(s) and specifying the Licensed Capacity, Licensed Territory, and Maintenance and Enhancement Plan (if any) purchased by You.

"Partitioned Copy" means one copy of the Product for use on one physical CPU (regardless of the number of processors) that is running multiple Lotus


Page 204


Notes/Domino server software applications.

"Product" means the machine readable code version of one or more proprietary computer software programs accompany this Agreement, the user manuals/documentation associated with them, this Agreement, any published specifications, and any copies, modifications, updates or fixes provided under a Maintenance and Enhancement Plan.

"Sessions" means the concurrent number of Citrix clients.

"Version(s)" are designated by a change in the number to the left of the first decimal point of the number appearing after the Product name, while “Release(s)" are designated by a change in such number to the right of the first decimal point. If there are any "Maintenance Release(s)", such numbers are designated by a change in the number following a decimal point to the right of the Release number. Candle is the sole determiner of the availability and designation of an update as a Version, Release, or Maintenance Release update and the contents and/or features of such update. New Versions exclude software updates that are designated by Candle in its sole discretion as new products.

"Workstation" means a terminal or computer with one workstation address at which a user can perform or access application(s).

PRODUCT SPECIFIC TERMS

For the OMEGAMON XE" and OMEGAMON DE" Products specified in the Order Document and classified as "Workgroup Hardware", "Departmental Hardware", "Enterprise 1 Hardware", or "Enterprise 2 Hardware", CPUs (single and multi-processor) shall be based on Candles then-current price list and use of those Products is restricted to use on such classification of CPUs as described therein.

The OMEGAMON XE Management Pac for MQSeries and OMEGAMON DE Management Pac for MQSeries include the Candle Management Server for MQSeries, OMEGAMON Monitoring Agent for MQSeries, Configuration Manager for MQSeries, and PQ Edit (excluding Tandem and AS/400) for the designated operating system.

"OMEGAMON XE" and "OMEGAMON DE" include the associated licensed Candle agents for the platforms or applications specified herein and all Candle Management Server(s) and Candle Management Workstation(s) (or equivalent functionality through the separate licensing of a CandleNet Portal Server) generally available to Licensors commercial customers of those Products.

For CBT and ETEWatch Customizer (Single User edition), Products licensed hereunder, Copy means a single Licensed User or Single User.

For the ETEWatch Starter Kit and ETEWatch-Citrix MetaFrame Starter Kit Products licensed hereunder, Copy means the number of Workstations or Citrix Sessions specified in the Order Document. These Products may be installed on an unlimited number of servers. Each Workstation or Citrix Session monitored by one of these Products must have its own license, but each may monitor an unlimited number of applications.

The ETEWatch and eBA*Service Monitor Product(s) licensed herein do not include the optional software, eBA*Reporter. This optional software is available for download on the Candle website [www.candle.com] or may be available on the media on which ETEWatch and/or eBA*Service Monitor are provided. eBA*Reporter is subject exclusively to the license agreement terms


Page 205



and conditions provided during installation of that software.

For CandleNet ETEWatch Enterprise Edition includes: (i) the CandleNet ETEWatch Starter Kit, (ii) unlimited use of the Central Control feature, (iii) all Networked Behavior Modules that are available to Licensees general customer base, (iv) unlimited use of the Omegamon Monitoring Agent for eBA Solutions, (v) unlimited use of the ETEWatch Connection Pack for HP/ITO, and (vi) the number of ETEWatch Workstations corresponding to the number of Workstations for which the CandleNet ETEWatch Enterprise Edition is licensed in this Agreement.

For the ETEWatch 3270 and ETEWatch Connection Pack for HP/ITO Products, Copy means one physical copy of the Product licensed in conjunction with, and monitoring those, workstations and behavior modules licensed for ETEWatch for Networked Applications. This Product may not be used without a valid license for ETEWatch for Networked Applications.

For ETEWatch Customizer, Enterprise License means an unlimited number of Licensees employees are allowed to use the Product in any or all of Licensees geographic locations within the Territory, to customize behavior modules for use with other ETEWatch Products. Candles Maintenance and Enhancement Plan is available for the ETEWatch Customizer Product only, and does not cover any customizations or code created by the Product. Licensor shall not be responsible for the quality, performance or functionality of any customizations or code created by Licensee using any Products and Licensee bears all risk therein.

For IntelliWatch for Lotus Notes/Domino Products licensed hereunder, Copy means per Notes Server Instance, per Non-Partitioned Copy, or per Partitioned Copy, as specified on the Order Document, on the platforms specified therein.

For OMEGAMON XE Web Pulse and OMEGAMON DE Web Pulse, for those Copies of the Product monitoring 51 or more URLs, "Copy" means one physical or logical copy of the Product for use on a single physical server for each set of 50 URL's (or portion thereof) it is monitoring.

A. Trial License Terms

The trial version of the Product contains a time limitation feature that limits use of the product to a thirty (30) day period from the date of initial installation. If, at any point, you would like to purchase the product, please contact your local Candle Sales representative at www.candle.com for pricing and licensing information, and for information on how to disable the time limitation feature, and to download the latest version of the Product.

1. License. You, the evaluator and user ("You") of the accompanying software and/or documentation ("Product") are granted a free non-exclusive non-transferable license (the "License") to use one machine readable object code copy of the Product, for non-commercial evaluation and experimental purposes only, for a period of thirty (30) days ("Trial Period") from the date of initial installation of the Product. Your use of the Product is limited to the Licensed Territory. Other than this grant of a limited License, Candle retains all right, title and interest in the Product.

2. Trial Terms and Conditions. The Trial Period will commence upon downloading or installation of the Trial Product and will cease at the end of the Trial Period. The Product contains valuable, confidential information and trade secrets


Page 206



which you agree to protect. You shall not reverse assemble or reverse compile the Product or in any way attempt to obtain the source code for the Product (except as allowed by Governing Law in the European Union), and this Agreement shall automatically terminate in the event of such action or attempted action. You may not use the Product to design, create, develop or test software or other products competitive with the Product. You may not release the results of any performance or functional evaluation or benchmarking of the Product to any third party without prior written approval of Candle for each such release.

3. Limitations. YOU UNDERSTAND AND AGREE THAT CANDLE IS PROVIDING THE PRODUCT TO YOU "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT (EXCEPT AS OTHERWISE REQUIRED BY GOVERNING LAW). THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PRODUCT IS WITH YOU, AND YOU AGREE TO HOLD CANDLE HARMLESS AGAINST ANY AND ALL CLAIMS RELATING THERETO. IN NO EVENT WILL CANDLE BE LIABLE FOR ANY DIRECT, INDIRECT OR CONSEQUENTIAL DAMAGES RELATING TO USE OF THE PRODUCT.

4. Termination of the Trial. At the end of the Trial Period, You may elect to enter into a License Agreement with Candle for this Product. If You do not choose to enter into a license, You agree to delete the Product from all CPUs and from any computer storage device or medium on which You have placed the Product.

B. Full Product License Terms

If You have a trial version of the Product, the Trial Period will expire thirty (30) days after the Product is first installed. To enable the full version of the Product, You will need to obtain a key from Candle, which maybe obtained upon payment of appropriate license fees, and to agree to the terms of the following full product license:

1. License. Candle grants you, the licensee ("You"), a non-exclusive, non-transferable, perpetual license to use machine readable object code copies of the accompanying Product: (i) In the Licensed Capacity and in the Licensed Territory, (ii) for Your own internal use and benefit only, and (iii) not for providing data processing services to third parties.

2. Licensed Capacity. The Licensed Capacity shall be as specified on the Order Document.

3. Upgrades in Licensed Capacity. You may increase Your Licensed Capacity by obtaining additional licenses from Candle, to be governed by this Agreement. Upon payment of an upgrade fee, Candle may send You a file to expand Your use to the new Licensed Capacity or may otherwise enable or authorize the additional Licensed Capacity. For each license You obtain to the Product, You may make a reasonable number of backup copies. You may not otherwise copy or modify the Product.

4. Term and Termination. Your Product license commences on the effective date stated on the Order Document, and remains effective until terminated, unless otherwise specified on the Order Document. You may terminate this Agreement by notifying Candle. Candle may terminate this Agreement if You breach any of the terms and conditions. Upon termination for any reason, You


Page 207


shall either return the Product to Candle or delete or destroy all copies of the Product and certify such in writing to Candle. All provisions of this Agreement relating to payment obligations, disclaimers of warranties, limitation of liability, remedies or damages, and Candle's proprietary rights shall survive termination of this Agreement for any reason.

5. Limited Warranty. Unless the Product is provided at no cost or is a trial or field test version, Candle warrants at the time of delivery, and for a period of ninety (90) days from the license commencement ("Performance Warranty Period"), the Product will substantially conform to the technical reference manual. If the Product does not conform due to Licensor's fault, Licensor will undertake good faith efforts to cure the defect. If the Product is provided at no cost or is a trial or field test version, CANDLE PROVIDES THE PRODUCT "AS IS" AND MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. In all cases, Candle does not warrant that: (i) the Product functions will meet Your requirements; or (ii) the Product operates uninterrupted or error-free. Licensor shall not be responsible for the quality, performance or functionality of any customizations or code created by You using any Products and You bear all risk therein. Candle does warrant that the media on which the Product is furnished will be free from defects in material and workmanship under normal use for a period of thirty (30) days from the delivery date (or such other minimum period as may be required by Governing Law) ("Media Warranty Period"). Candle warrants no other software or hardware furnished with or accompanying the Product. Your exclusive remedy under this limited Media Warranty is the replacement of any defective physical media on which the Product is furnished, by returning the defective media to Your supplier ("Supplier") during the Media Warranty Period with proof of payment.

EXCEPT AS PROVIDED ABOVE, CANDLE MAKES NO WARRANTIES EITHER EXPRESS OR IMPLIED AS TO ANY MATTER WHATSOEVER, INCLUDING, WITHOUT LIMITATION, THE PRODUCT CONDITION, ITS MERCHANTABILITY, ITS FITNESS FOR ANY PARTICULAR USE, OR NON-INFRINGEMENT. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE IS WITH YOU. SOME JURISDICTIONS DO NOT ALLOW LIMITATIONS ON THE LENGTH OF AN IMPLIED WARRANTY, OR THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU. THIS WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS, AND YOU MAY ALSO HAVE OTHER RIGHTS WHICH VARY FROM JURISDICTION TO JURISDICTION.

6. LIMITATION OF LIABILITY. EXCEPT AS SPECIFIED IN SECTION B5, CANDLES SOLE OBLIGATION OR LIABILITY UNDER THIS LICENSE AGREEMENT IS THE REPLACEMENT OF DEFECTIVE MEDIA ACCORDING TO THE LIMITED WARRANTY ABOVE. IN NO EVENT WILL CANDLE BE LIABLE FOR ANY CONSEQUENTIAL, INCIDENTAL, OR INDIRECT DAMAGES, INCLUDING WITHOUT LIMITATION, ANY LOSS OF DATA OR PROFITS, OR LOST SAVINGS, ARISING OUT OF THE USE, OR INABILITY TO USE THE PRODUCT, EVEN IF CANDLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR FOR ANY CLAIM BY ANY THIRD PARTY. CANDLE'S LIABILITY TO YOU FOR ACTUAL DAMAGES FOR ANY CAUSE WHATSOEVER AND REGARDLESS OF THE FORM OF THE ACTION (WHETHER IN CONTRACT, TORT, PRODUCT RELIABILITY OR OTHERWISE) WILL BE LIMITED TO THE LICENSE FEE PAID.


Page 208


THIS LIMITATION WILL NOT APPLY TO CLAIMS FOR BODILY INJURY OR DAMAGES TO REAL OR TANGIBLE PERSONAL PROPERTY FOR WHICH CANDLE MAY BE LEGALLY LIABLE. SOME JURISDICTIONS DO NOT ALLOW FOR THE LIMITATION OF LIABILITY, SO THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU. THIS LIMITATION WILL NOT APPLY TO CLAIMS FOR BODILY INJURY OR DAMAGES TO REAL OR TANGIBLE PERSONAL PROPERTY FOR WHICH CANDLE MAY BE LEGALLY LIABLE.

7. Maintenance and Enhancement Plan ("Plan"). If a Plan is specified on the Order Document, Candle will: (i) Supply Code Corrections to correct substantial Product deviations from specifications of the current applicable technical reference manual. If You have modified the Product, Candle at its discretion may require You to demonstrate that any deviation of the Product was not caused by Your modification; (ii) Supply improvements, extensions and other changes to the Product which Candle, at its discretion, deems to be logical improvements or extensions; and (iii) Supplying a reasonable amount of consulting assistance by e-mail or telephone in the event of problems with the Product. If on-site assistance is required, Candle's standard consulting rates for such services will be applicable. There will be no additional charge for maintenance and support during the Performance Warranty Period for the initial license of a Product. Licensee will not receive a Performance Warranty Period for subsequently licensed Copies of a previously licensed Product, and maintenance and support charges will be due immediately at the time of licensing such additional Copies. The Plan does not cover any customizations or code created by the Product.

You may subscribe to Candles Plan for the Product by paying Candle the Plan fee. The Plan Term shall commence upon receipt of such payment, and extend for the period of time defined in the Order Document from that date. All Plan services for the Product shall be governed by this Agreement. For each year after the initial Plan Term, Candle will provide You with maintenance and support services, provided You pay Candle in advance the annual Plan fee then in effect. Candle's obligation to provide Plan services and Your obligation to pay the Plan fee then in effect shall be automatically renewed on the anniversary date of the commencement of the Plan Term for the first license under this Agreement, unless either Candle or You has given the other at least 30 days prior written notice canceling the Plan. If annual Plan fees increase over the preceding year, You may cancel by giving Candle written cancellation notice within 30 days of receipt of Candle's invoice showing such increase. You may cancel Your subscription in the Plan effective as of the next anniversary date by written notice to Candle received prior to the anniversary date. You may reinstate maintenance at a later time by paying the Plan fee in effect at the time of renewal plus a reinstatement fee equal to the Plan fees for the years the Plan was canceled or $2,500 (as varied by Candle from time to time), whichever is less.

Candle is only obligated to provide maintenance and support services for the current Release of the Product and the previous Release. Licensor may drop support of any Product, or one or more Releases of any Product, upon six (6) months written notice. In addition, when a third party vendor no longer supports a specific release or version of its software product for its general customer base, Candles support of its Product, with respect to such third party vendor software release or version, shall also be terminated.

Any separate maintenance and enhancement agreement entered into by the


Page 209


parties for the Product(s) licensed hereunder, on or after the license commencement date, shall supersede the terms of this section.

C. All License Terms

1. Title and Risk of Loss. All rights to and in the Product, including but not limited to Intellectual Property Rights belong to Candle and Candle holds title to the Intellectual Property Rights in each Product copy. Beneficial and legal title, ownership and right to possession of the tangible medium containing the Products (whether magnetic tape, disk or cartridge; CD-ROM; or any other medium), and risk of loss or damage to the copies shall pass to You upon physical delivery to the Your place of business. If the tangible medium is lost or damaged, Candle will provide a replacement copy to You upon Your request and Your proof of loss or damage. You shall pay only a handling fee and any shipping charges for the replacement.

2. Nondisclosure. You shall not disclose, transfer or distribute the Product to others, except as allowed herein. This Agreement shall automatically terminate in the event of such disclosure, transfer or distribution. Such prohibition on disclosure shall not apply to disclosures by You to Your agents, contractors or employees, provided (i) such disclosures are reasonably necessary to Your authorized use of the Product, and (ii) You take reasonable steps to ensure that the Product is not disclosed by Your agents, contractors or employees in contravention of this Agreement. You shall not reverse assemble or reverse compile the Product or in any way attempt to obtain the source code for the Product, and this Agreement shall automatically terminate in the event of such action or attempted action. You may not use the Product to design, create, develop or test software or other products competitive with the Product. You may not release the results of any performance or functional evaluation or benchmarking of the Product to any third party without prior written approval of Candle for each such release. You agree not to disclose the pricing and any other terms of this Agreement to any third parties and to use the same degree of care a reasonable business person uses to protect its own confidential information.

3. Your Obligations. You are exclusively responsible for the supervision, management and control of Your use of the Product, including: (i) assuming proper machine configuration, Product installation and operating methods; (ii) establishing back-up plans; and (iii) implementing adequate procedures to satisfy requirements for restart and recovery in the event of malfunction.

4. Third Party Software. This Product may include third party vendor ("TPV") code ("Code") that is confidential and proprietary copyrighted information, as specified in the "Candle Corporation Legal Notices". Unless otherwise specified, (i) title to all copies of any such Code is retained by the specified TPV and/or its licensors, (ii) the TPVs are direct and intended beneficiaries of this Agreement and may enforce it directly against You, (iii) only the right to use the run-time version of the TPV Code is granted, and (iv) You may use the TPV Code only in conjunction with the Product and only so long as You are an authorized licensee of the TPVs related base software.

THE CODE IS PROVIDED "AS IS", WITHOUT A WARRANTY OF ANY KIND. ALL EXPRESS OR IMPLIED REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, REGARDING THE CODE ARE EXCLUDED. NEITHER CANDLE NOR THE TPV OR ITS LICENSORS SHALL


Page 210


BE LIABLE FOR ANY DAMAGES SUFFERED BY YOU OR ANY THIRD PARTY AS A RESULT OF USING THE CODE.

The OMEGAMON XE for Sybase and OMEGAMON DE for Sybase Product(s), if licensed on the Order Document, includes SQL Server Monitor API software owned exclusively by Sybase, Inc., its subsidiaries or suppliers, and sublicensed by Candle for relicensing to You. You shall not release the result of any benchmark of any SQL Server Monitor API included with the Product to any third party without the prior written approval of Candle.

The Product(s) are not intended and may not be used for life support systems, online aircraft control, air traffic, aircraft navigation or communications, rocket or ballistic missile systems or space vehicles, in the design, construction operation or maintenance of any nuclear or chemical processing facility, or related in any way to chemical or biological weapons, missiles, or explosives. The software contains valuable, confidential information and trade secrets which you agree to protect. Also, the reproduction, transfer, assignment, decompilation, disassembly or reverse engineering of the software is prohibited.

5. ADDITIONAL SOFTWARE. THE MEDIA ON WHICH THIS PRODUCT IS DELIVERED MAY INCLUDE ADDITIONAL SOFTWARE FOR WHICH YOU ARE NOT LICENSED. A PORTION OF THIS NON-LICENSED SOFTWARE MAY, AS A RESULT OF THE INSTALLATION PROCESS, RESIDE ON YOUR HARDWARE. YOU SHALL NOT ACCESS, USE, OR ALLOW ANY THIRD PARTIES TO ACCESS OR USE THE NON-LICENSED SOFTWARE. IN ADDITION, YOU AGREE THAT YOUR NONDISCLOSURE AND CONFIDENTIALITY OBLIGATIONS REGARDING THE PRODUCT(S) SHALL ALSO APPLY TO THE NON-LICENSED SOFTWARE. IN NO EVENT SHALL CANDLE BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY DAMAGES WHATSOEVER ARISING FROM THE USE AND/OR ACCESS TO THE NON-LICENSED SOFTWARE.

6. Site Inspection. To assist Candle in protecting its proprietary rights, You agree to allow Candle, or its representatives, upon reasonable notice, during normal business hours, and subject to Your reasonable security requirements, to inspect Your systems to verify that the Product is used consistent with this Agreement.

7. Restricted Rights. Where the United States Government or a U.S. government agency is a licensee or end user hereunder, the following additional terms apply: The Product is provided with RESTRICTED RIGHTS. Use, duplication or disclosure by the Government is subject to these restrictions and/or by Government Rights in Data Clause(s), as applicable (including but not limited to DFARS 252.227-7013(c)(ii) and FAR 52.227-19(a)-(d)). Unpublished--All rights reserved under United States Copyright laws. Manufacturer is Candle Corporation,201 North Douglas, El Segundo, CA 90245.

8. Export Control. You acknowledge the Products originate in the United States and You agree to comply with any applicable U.S. laws, regulations, rulings and executive orders on exportation (including without limitation the export and destination control regulations of the United States Commerce and State Departments and the anti-boycott regulations of the United States Commerce and Treasury Departments) and with all other applicable laws, including without limitation, laws on import or marketing of the Products. You further agrees that the Products shall not be exported or re-exported: (i) to any countries included in prohibited Country Groups of the U.S. Export


Page 211


Administration Regulations, (ii) as prohibited under such Regulations at the time of export or re-export, (iii) or delivered to national citizens of such prohibited Country Groups, or (iv) in violation of this Agreement. You warrant and represent that You have no intention of exporting or re-exporting any of the Products outside the Licensed Territory. Candle may terminate this Agreement in the event that the Agreement violates U.S. export regulations or related laws. This section shall survive termination, expiration or cancellation of this Agreement or any license hereunder.

9. General. If there is a local Candle subsidiary in the country in which the Product was obtained, the local law of the subsidiary shall govern this License (unless otherwise specified in Section D). Otherwise, this Agreement shall be governed and interpreted under the laws of the State of California, United States of America, without regard to conflicts of law provisions, and excluding the United Nations Convention for Contracts for the International Sale of Goods. You may not transfer or assign this Agreement, except to the successor or assignee of all or substantially all of Your business or substantially all of Your assets upon liquidation, which successor, assignee or purchaser expressly assumes the relevant obligations of this Agreement. Any assignment in derogation of the foregoing shall be void. The Product is not intended for use in online control of aircraft, air traffic, aircraft navigation, aircraft communications, rocket or ballistic missile systems or space vehicles, in the design, construction, operation or maintenance of any nuclear or chemical processing facility, or related in any way to chemical or biological weapons, missiles, or explosives, and You warrant You will not use the Product for such purposes. You agree that the following is made a part of any purchase order that You may use in conjunction with this Agreement: "The terms and conditions set forth in the Candle Agreement are made a part of this purchase order and are in lieu of all terms and conditions, express or implied, in this purchase order. The terms and conditions set forth in the Candle Agreement are applicable for all renewals of this order." You shall comply with all applicable laws of the Licensed Territory regarding Your business, including, without limitation, recording this Agreement with the appropriate government agencies, if required.

D. Country Specific Legal Terms

The following terms apply only to Licensed Products that are licensed for use in the referenced country, where the referenced country is also the Governing Law:

Argentina, Chile and Peru. All references to Licensed Territory shall mean Argentina, Chile or Peru (as appropriate) unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of the Licensed Territory, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately. In Chile and Peru, You agree to pay Candle a penalty in an amount sufficient to compensate Candle for loss of its trade secrets in the Program for any violation by You or your employees, agents, subsidiaries of affiliates of Section C2 of this Agreement.

Any dispute about the Agreement must be submitted to arbitration by a panel of three (3) arbitrators to be selected, one by each party and the third by the two previously selected arbitrators. The arbitrators may not be related to either of the parties or any of their affiliates, or have been employed or have had substantial contact with either party. The arbitration will be held in the capital city of the


Page 212


Licensed Territory, or any other location mutually agreed upon by the parties, in Spanish and subject to the rules and regulations of UNCITRAL in force at the time the Product is licensed. The costs of arbitration will be divided equally between the parties. In no event shall the decision affect the payment of punitive damages. Any additional costs, fees or expenses incurred from the execution of the arbitrators decision will be the responsibility of the party that requested them. Any competent tribunal can order the enforcement of the arbitrators decision, or either of the parties can solicit from said tribunal a judicial recognition of said decision or an order of execution of the same, depending on the case.

Australia. All references to Licensed Territory shall mean all States in Australia unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of the State of New South Wales, Australia, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately. All references to "Sections" shall be changed to references to “Clauses". All references to "attorneys fees" shall be changed to references to "legal fees".

Except as specifically provided in Clauses A3 or B5, Candle makes no warranties either express or implied as to any matter whatsoever, including, without limitation, the condition of the Product, its merchantability, or its fitness for any particular use. This Agreement includes terms implied by any statute, which cannot be lawfully excluded, including those implied by Division 2 of the Trade Practices Act and equivalent State and Territory legislation. However, in relation to the supply of goods or services which are not of a kind ordinarily acquired for personal, domestic or household use or consumption, Candle's liability for breach of those terms (other than section 69 of the Trade Practices Act) will be limited, at its option, to anyone or more of: (a) in the case of goods, the replacement, repair or payment of the cost of replacement or repair of the goods; and (b) in the case of services, respelling the services or payment of the cost of having the services resupplied.

Subject to the limitation in Clauses A3 and B6, to the maximum extent allowable by law Candle will not be liable to You or any other party for monetary damages in excess of the amounts paid for the license or for any loss, direct or indirect, including good will and consequential, incidental and special damages, which may arise from the use, operation or modification of the Product or otherwise out of or in relation to this Agreement. Nothing in this Agreement is intended to prejudice, or have the effect of prejudicing, any rights Candle may have under Australian law or of the States of Australia which cannot legally be excluded or restricted and the terms of this Agreement must be read accordingly.

Austria, Germany and Switzerland. The limitations and exclusions specified in sections A3, B5 and B6 in the Agreement will not apply to damages caused by Candle with intentional or gross negligence. Candle is liable for assured characteristics. The limitation on bringing a legal action is not applicable in case of tort by either Candle or You, or Candles agents.

Canada. All references to Licensed Territory shall mean all provinces in Canada unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of the Province of Ontario, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately.

China, Peoples Republic of. All references to Licensed Territory shall mean the


Page 213


Peoples Republic of China unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of the Peoples Republic of China, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately.

You acknowledge and agree that You have not been induced to enter into this Agreement by any representations or warranties other than those contained in this Agreement and shall not claim any loss or damage resulting from any such representations or warranties made by Candle before the signing of this Agreement against Candle. All banking charges incurred in the Peoples Republic of China shall be borne by You and those incurred outside the Peoples Republic of China shall be borne by Candle.

Colombia. All references to Licensed Territory shall mean Colombia unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of Colombia, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately. Nothing in Sections A3 or B5 of this Agreement shall affect the statutory right of consumers regarding implied warranties under the Colombian Consumer Protection Law, D.E.3466/82.

Hong Kong Special Administrative Region of the Peoples Republic of China ("Hong Kong"). All references to Licensed Territory shall mean Hong Kong unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of Hong Kong, excluding the United Nations Convention for Contracts for the International Sale of Goods. The terms and conditions of the Agreement may be amended or modified by Candle from time to time by giving 30 days prior written notice to You and all such amendments and modifications shall take effect and be binding on You on the expiration of the said 30 days notice. You acknowledge and agrees that You have not been induced to enter into this Agreement by any representations or warranties other than those contained in this Agreement and therefore shall not claim any loss or damage resulting from any such representations or warranties made by Candle before the signing of this Agreement against Candle.

India. All references to Licensed Territory shall mean India unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of India, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately.

Indonesia. All references to Licensed Territory shall mean Indonesia unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of Singapore, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately. Notices shall in all instances be required within five (5) business days.

To the extent necessary to implement the termination provisions of this Agreement, each of the parties hereby waives any right or obligation, it or the other party may have under any applicable law or regulation, including without limitation Article 1266 of the Indonesian Civil Code, to request or obtain the approval, order, decision or judgment of any court to terminate this Agreement.

Ireland. All references to Licensed Territory shall mean Ireland unless otherwise specified in the Order Document. All references to Governing Law shall mean the


Page 214


laws of the United Kingdom, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately. No statement in this Agreement shall affect the statutory right of consumers.

Israel. All references to Licensed Territory shall mean Israel unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of Israel, excluding the United Nations Convention for Contracts for the International Sale of Goods. The limitation on bringing a legal action will be according to the law of limitation provided notification concerning the cause of action was sent no more than 2 years after the cause of action arose or became known to plaintiff.

Japan. All references to Licensed Territory shall mean Japan unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of Japan, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of consumption or similar assessments, taxes or duties which will be invoiced to You separately. In addition to Candle's express disclaimers of liability in the Agreement, Candle is not liable for damages arising through special circumstances. Section C8 is modified as follows: You warrant that the Products shall not be used, exported or re-exported in violation of the Japanese Foreign Exchange and Foreign Trade Law, and its enforcement orders and regulations.

Either party may terminate this Agreement immediately in the event of the other partys insolvency. A party is deemed insolvent if: (i) it has ceased to pay a substantial portion of its debts in the ordinary course of business or cannot pay its debts as they become due, or in the event of declaration of dishonor or suspension of checks, whether written, guaranteed, underwritten or endorsed, whether or not a petition for bankruptcy has been filed, and whether or not insolvent within the meaning of the Territorys bankruptcy laws; (ii) there has been a petition filed to have a party declared bankrupt (hasan), to commence corporate reorganization(kaisha kosei), reorganization under the Commercial Code (seiri), composition(wagi), special liquidation (tokubetsu seisan); (iii) an interim receiver(hozen kanrinin) has been appointed for a party; (iv) voluntary arrangement(nin-ii-seiri) is commenced by a party; (v) its assets become subject to attachment, provisional attachment, provisional disposition, tax collection proceedings or any other administrative actions; or (vi) in the event of dissolution of a party.

EXCEPT AS SPECIFICALLY PROVIDED IN SECTIONS A3, B5 OR C4, CANDLE MAKES NOWARRANTIES EITHER EXPRESS OR IMPLIED AS TO ANY MATTER WHATSOEVER, INCLUDING,WITHOUT LIMITATION, THE CONDITION OF THE PRODUCT, OR IMPLIED WARRANTY UNDERTHE JAPANESE CIVIL CODE AND THE JAPANESE COMMERCIAL CODE(kashi-tampo-sekinin, etc.).

South Korea. All references to Licensed Territory shall mean South Korea unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of South Korea, excluding the United Nations Convention for Contracts for the International Sale of Goods. In addition to Candle’s express disclaimers of liability in the Agreement, Candle is not liable for damages arising through special circumstances.

Malaysia. All references to Licensed Territory shall mean Malaysia unless otherwise specified in the Order Document. All references to Governing Law shall mean the


Page 215


laws of Malaysia, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately.

Mexico. All references to Licensed Territory shall mean Mexico unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of Mexico, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately.

The limitation of liability in this Agreement will not apply to claims for death or personal injury, or to physical damage to Your tangible property caused by gross negligence or willful misconduct on the part of Candle.

Middle Eastern Countries. (Bahrain, Kuwait, Oman, Qatar, and UAE) This Agreement is governed by the law and jurisdiction of Bahrain, excluding the United Nations Convention for Contracts for the International Sale of Goods.

New Zealand. All references to Licensed Territory shall mean New Zealand unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of New Zealand, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately.

Except as specifically provided in Sections A3 or B5, Candle makes no warranties either express or implied as to any matter whatsoever, including, without limitation, the condition of the Product, its merchantability, or its fitness for any particular use. This Agreement includes the terms implied by any statute which cannot be lawfully excluded, including those implied by the Consumer Guarantees Act 1993 and equivalent legislation. However, in relation to the supply of goods or services which are not of a kind ordinarily acquired for personal, domestic or household use or consumption, or where Partner is a consumer under the Consumer Guarantees Act and is acquiring, or holding itself out as acquiring, the goods for a business purpose, the Consumer Guarantees Act will not apply and Candle's liability for breach of those terms will be limited, at its option, to any one or more of (a) in the case of goods, the replacement, repair or payment of the cost of replacement or repair of the goods; and (b) in the case of services, resupplying the services or payment of the cost of having the services resupplied.

Philippines. All references to Licensed Territory shall mean the Philippines unless otherwise specified in the Order Document. All references to Governing Law shall mean the laws of the Philippines, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately. By use of this Product, You agree to waive any right to decompile or reverse engineer the Product(s) under Sec. 185.1 of Republic Act No. 8293.

Software developed for the mass market: (a) In the event that the Product(s) licensed herein are not considered as "software developed for the mass market" as such term is defined by Sec. 4.2 of Republic Act ("R.A.") No.8293 and Sec. 1 (1) (g) of the Intellectual Property Office Guidelines to Implement Chapter IX, Part II of the Intellectual Property Code on Voluntary Licensing, by any court or administrative agency, then the provisions specified in Section (b) shall automatically be deemed as


Page 216


an integral part of this Agreement. (b) The following provisions are applicable only to Products not considered as "software developed for the mass market": (i) Any provision herein that is considered as a "Prohibited Clause" under Sec. 87 of R.A. No.8293 shall be deemed ineffective and shall not in any manner affect the validity or enforceability of the other provisions, unless an exemption is granted by the Philippine Intellectual Property Office in respect of the “Prohibited Clause" in accordance with R.A. No. 8293. (ii) The laws of the Philippines shall govern the interpretation of this Agreement and in the event of litigation, the venue shall be proper court in the place where the You has its principal office. (iii) Continued access to improvements in techniques and processes related to the technology shall be made available during the period of this Agreement. (iv) If the parties agree to arbitration, the Procedure of Arbitration of the Arbitration Law of the Philippines or the Arbitration Rules of the United Nations Commission on International Trade Law (UNCITRAL) or the Rules of Conciliation and Arbitration of the International Chamber of Commerce (ICC) shall apply and the venue of arbitration shall be the Philippines or any neutral country; and(v) Philippine taxes on all payments relating to this Agreement shall be borne by the Candle.

Russian Federation. This Agreement is governed by the material laws of Austria, and any disputes arising hereunder shall be instituted in Austria, and You consent to the jurisdiction of the Austrian courts.

Singapore. All references to Licensed Territory shall mean Singapore unless otherwise specified in the Order Document. All references to Governing Law shall mean Singapore law, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of goods and services tax and customs duties which will be invoiced to You separately. THE PARTIES AGREE TO THE ALLOCATION OF LIABILITY RISK SET FORTHIN SECTIONS A3 and B6 AND AGREE THAT IT IS FAIR AND REASONABLE IN THECIRCUMSTANCES.

United Kingdom. All references to Licensed Territory shall mean the United Kingdom unless otherwise specified in the Order Document. All references to Governing Law shall mean English law, excluding the United Nations Convention for Contracts for the International Sale of Goods. All prices are exclusive of VAT, customs duties, sales and use taxes, and/or goods and services taxes which will be invoiced to You separately.

The limitation of liability in this Agreement will not apply to claims for death or personal injury or physical damage to Your tangible property caused by the negligence of Candle or to any breach of Candle's obligations implied by Section C12 of the Sales of Goods Act 1979 or Section 2 of the Supply of Goods and Services Act 1982, and liability for defective products arising under Part 1 of the Consumer Protection Act 1987. EXCEPT AS SPECIFICALLYPROVIDED IN SECTIONS A3 OR B5, ALL OTHER WARRANTIES OR CONDITIONS, WHETHEREXPRESS OR IMPLIED, AS TO ANY MATTER WHATSOEVER, INCLUDING WITHOUTLIMITATION, THE CONDITION OF THE PRODUCT, ITS CORRESPONDENCE TO DESCRIPTION,ITS MERCHANTABLE QUALITY OR ITS FITNESS FOR ANY PURPOSE ARE HEREBYEXCLUDED.

Except as specified in this Agreement and required by U.K. Laws and statutes, Candle shall not be liable for any loss or damage which may arise in connection with the furnishing or use by You of the Product or performance of the Product. The remedies set forth in this Agreement are Your sole and exclusive remedies for any breach of Candle's obligations. IN NO EVENT WILLCANDLE BE LIABLE TO YOU OR ANY OTHER PARTY FOR MONETARY DAMAGES IN EXCESS OFTHE FEES PAID BY YOU FOR THE PRODUCT IN QUESTION OR FOR ANY LOSS, DIRECT ORINDIRECT,


Page 217


INCLUDING GOOD WILL AND CONSEQUENTIAL DAMAGES, WHICH MAY ARISE FROMTHE USE, OPERATION OR MODIFICATION OF THE PRODUCT BY YOU.

Neither party will be liable for delays in performance due to circumstances beyond its reasonable control. A party whose performance is prevented, restricted, or interfered with due to causes beyond its reasonable control, including a Force Majeure condition, shall be excused from such performance, on a day-for-day basis to the extent of such cause or condition, so long as such party provides the other party with prompt written notice describing the cause or Force Majeure condition and takes all reasonable steps to avoid or remove such causes or conditions of nonperformance, minimize the consequences thereof, and immediately continues performance whenever and to the extent such causes or conditions are removed.

YOU WARRANT THAT YOU ARE DULY AUTHORIZED TO BIND YOURSELF AND/OR YOURPRINCIPAL OR EMPLOYER TO THIS AGREEMENT, AND THAT YOU HAVE THE LEGAL CAPACITYTO ENTER INTO BINDING AGREEMENTS. YOU ACKNOWLEDGE THAT YOU HAVE READ ANDUNDERSTAND THIS AGREEMENT AND YOU AGREE TO BE BOUND BY ITS TERMS. YOU FURTHERAGREE THAT THIS AGREEMENT IS THE COMPLETE AND EXCLUSIVE STATEMENT OF THEAGREEMENT BETWEEN YOU AND CANDLE AND SUPERSEDES ANY PROPOSAL OR PRIORAGREEMENT, ORAL OR WRITTEN, AND ANY OTHER COMMUNICATIONS RELATING TO THESUBJECT MATTER OF THIS LICENSE AGREEMENT.

September 2001


Page 218


Trademark Notices

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 Electronic CustomerSupport, Candle logo, Candle Management Server, Candle ManagementWorkstation, CandleLight, CandleNet, CandleNet Command Center, CandleNeteBusiness 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/AdvancedNotification, AF/PERFORMER, Alert Adapter, Alert Adapter Plus, Alert Emitter,AMS, Amsys, AutoBridge, AUTOMATED FACILITIES, Availability ManagementSystems, Business Services Composer, Candle Alert, Candle Business PartnerLogo, Candle Command Center/SentinelManager, Candle CommandPro, CandleeDelivery, Candle eSupport, Candle Insight, Candle InterFlow, Candle Managingwhat matters most, Candle Service Suite, Candle Technologies, CandleNet,CandleNet 2000, CandleNet Conversion, CandleNet eBP, CandleNet eBP Access forS.W.I.F.T., CandleNet eBP Administrator, CandleNet eBP Broker Access forMercator or MQSI, CandleNet eBP Configuration, CandleNet eBP Connector,CandleNet eBP File Transfer, CandleNet eBP Host Connect, CandleNet eBP ObjectAccess, CandleNet eBP Object Browser, CandleNet eBP Secure Access, CandleNeteBP Service Directory, CandleNet eBP Universal Connector, CandleNet eBPWorkflow Access, CandleNet eBusiness Assurance, CandleNet eBusiness Exchange,CandleNet eBusiness Platform Administrator, CandleNet eBusiness PlatformConnector, CandleNet eBusiness Platform Connectors, CandleNet eBusinessPlatform Powered by Roma Technology, CandleNet eBusiness Platform ServiceDirectory, 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, eBusinessat the speed of light, eBusiness at the speed of light logo, eBusinessExchange, eBX, End-to-End, eNotification, ENTERPRISE, Enterprise CandleCommand Center, Enterprise Candle Management Workstation, Enterprise ReporterPlus, ER+, ERPNet, ETEWatch Customizer, HostBridge, InterFlow, CandleInterFlow, Lava Console, Managing what matters most, MessageMate, MessagingMastered, Millennium Management Blueprint, MMNA, MQADMIN, MQEdit,


Page 219


MQEXPERT,MQMON, NBX, NC4, NetGlue, NetGlue Extra, NetMirror, NetScheduler, New Times,New Team, New Readiness, OMA, OMC Gateway, OMC Status Manager, OMEGACENTERBridge, OMEGACENTER Gateway, OMEGACENTER Status Manager, OMEGAMON/e, OMEGAMONManagement Center, OSM, PathWAI, PC COMPANION, Performance Pac, Powered byRoma Technology, PowerQ, PQConfiguration, PQScope, Roma Application Manager,Roma Broker, Roma BSP, Roma Connector, Roma Developer, Roma FS/A, RomaFS/Access, RomaNet, Roma Network, Roma Object Access, Roma Secure, RomaWF/Access, Roma Workflow Access, RTA, RTN, SentinelManager, Somerset,Somerset Systems, Status Monitor, The Millennium Alliance, The MillenniumAlliance logo, The Millennium Management Network Alliance, Tracer, UnifiedDirectory Services, WayPoint, and ZCopy.

Trademarks and registered trademarks of other companies: AIX, DB2,MQSeries and WebSphere are registered trademarks of International Business Machines Corporation. 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 are trademarks or registered trademarks of their respective companies.

Copyright © 20032004 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.


Page 220


User Defined Delays Tab's Context Menu, Drag-and-drop and Key Bindings Support

The context menu options provided by the User Defined Delays tab include the following:

Context Menu Item

Description

New » Class Filter To define a new class mask.

New » Method Filter To define a new method name.

New » Delay Filter To define a new workload delay.

Remove To delete the selected item.

Modify To edit the selected item.

For the context menu options New > Class Filter and New > Method Filter,you are allowed only to edit the names.

The User Defined Delays Tab also provides a drag-and-drop support, as described below, from the Source Browser:

Drag Selection

Drop Target Action

Empty space New delay

Delay Add new delay class to target delay

Delay / Class Mask Add new delay class to targets parentdelay

Package, ClassOr Method

Delay / Class Mask /Method

Add new delay class to targets parentdelay

Multiple Selection

As above First pass adds each selection using rulesabove. Second pass removes duplication(e.g. for a drag selection of two methods,pass one will add two delay classes, eachwith a single method name; pass two willremove one delay class, and append amethod name to the remaining)

Instrumentation (Delay)

Any Copy


Page 221


The User Defined Delays Tab also supports the following key bindings, over and above default key bindings provided with the SWT controls:

Key Binding Action

Cursor Keys Tree Navigation

Enter or double-click Opens the modify dialog on the selected item

Delete Removes the selected items


Page 222


User Defined Workloads Tab's Context Menu, Drag-and-drop and Key Bindings Support

The context menu options provided by the User Defined Workloads tab include the following:

Context Menu Item

Description

New » Workload Filter To define a new workload.



Remove To delete the selected item.


For the context menu options New > Class Filter and New > Method Filter,you are allowed only to edit the names.

The User Defined Workloads Tab also provides a drag-and-drop support, as described below, from the Source Browser:

Drag Selection

Drop Target Action

Empty space New Workload

Workload Add new Workload class to target Workload

Workload / ClassMask

Add new Workload class to targets parentWorkload

Package, Class OrMethod

Workload / ClassMask / Method

Add new Workload class to targets parentWorkload

Multiple Selections

As Above First pass adds each selection using rules above.Second pass removes duplication (e.g. for a dragselection of two methods, pass one will add twoWorkload classes, each with a single methodname; pass two will remove one Workload class,and append a method name to the remaining)

Instrumentation (Workload)

Any Copy


Page 223


The User Defined Workloads Tab also supports the following key bindings, over and above default key bindings provided with the SWT controls:

Key Binding Action





Page 224


Instrumentation Tab's Context Menu, Drag-and-drop and Key Bindings Support

The context menu options provided by the Instrumentation tab include the following:

Context Menu Item Description



New » Object Filter To define a new object mask.

New » Lock Filter To define a new lock contention mask.

Inclusive To make the selected mask an inclusive filter.

Exclusive To make the selected mask an exclusive filter.

Delete To delete the selected item.


The Instrumentation tab also provides a drag-and-drop support, as described below, from the Source View:

Drag Selection (From Source

View)

Drop Target (To

Instrumentation View)

Action

Empty space Creates new class mask (check for existingone)

Class Mask Creates new class mask (check for existingone)

Class Mask/ObjectInstrumentation

Adds package or class as heap analysisattribute in target class mask

Object Instrumentation

Adds package or class as heap analysisattribute in KWEINSTR tag

Package or class

Monitor Contention Adds package or class as contentionmonitoring attribute


Page 225


Drag Selection (From Source

View)

Drop Target (To

Instrumentation View)

Action

Empty space Creates new class mask & method name(check for existing class mask)

Class Mask Creates new class mask & method name(check for existing class mask)

Class Mask / ObjectInstrumentation

No action

Object Instrumentation

No action

Method

Monitor Contention No action

Multiple Selections

As above First pass adds each selection using rulesabove. Second pass removes duplication.

Instrumentation Any Copy

The Instrumentation tab also supports the following key bindings, over and above default key bindings provided with the SWT controls:

Key Binding Action





Page 226


Source Browser's Context Menu, Drag-and-drop and Key Bindings Support

The Source browser context menus adapt depending on the currently active tabbed-view in the Instrumentation View. The context menu options include the following:

Active Target View

Selected Item(s)

Context Menu Item

Action

Include Methods

Add inclusive class mask for package or class.

Exclude Methods

Add exclusive class mask for package or class.

Include Objects

Add global inclusive heap analysis class mask for package or class.

Exclude Objects

Add global exclusive heap analysis class mask for package or class.

Include Objects Allocated By »

Provides dynamic list of existing class-masks, adds targets as inclusive heap analysis attribute.

Exclude Object Allocated By »

Provides dynamic list of existing class-masks, adds targets as exclusive heap analysis attribute.

Include Monitor

Adds selection as inclusive contention monitor user class.

Package or Class

Exclude Monitor

Adds selection as exclusive contention monitor user class.

Instrumentation

Method Include Methods

Adds class mask and inclusive method name for selection.


Page 227


Active Target View

Selected Item(s)

Context Menu Item

Action

Exclude Methods

Adds class mask and inclusive method name for selection.

New Delay

Creates a new delay for the current selection. Major and minor name are defaulted from the first element of the selection, making allowances for possible clashes with existing delays.

User Defined Delays

Package, Class or Method

Add to » Provides a dynamic list of existing delays to which the selection can be added.

New Workload

Creates a new workload or the current selection. Major and minor name are defaulted from the first element of the selection, making allowances for possible clashes with existing delays.

User Defined Workloads

Package, Class or Method

Add to » Provides a dynamic list of existing workloads to which the selection can be added.

In addition to content menus, the Source Browser provides drag-and-drop support, so that selections of packages, classes and methods, as well as instrumentation from an existing set can be dragged out of the Source Browser and dropped into the target view i.e. Instrumentation View.


Page 228


Index Acrobat 190, 195, 196 Additional Table Columns 16 Admin Server 26, 104, 125, 126, 127, 128, 129, 135, 136,

137, 139, 140, 198 Advanced Import Filtering 5, 15 Advanced tab 144, 148, 153, 157, 166 Advanced Tab 148 Agreement 4, 203, 205, 206, 207, 209, 210, 211, 212, 213,

214, 215, 216, 217 All Objects Summary 2, 23, 31, 59, 62, 76, 77, 87, 88, 89, 91, 93,

95, 96, 101 All Workloads Summary 2, 22, 29, 39, 77, 185 Apache 200, 201 Appearance 3, 36, 39, 40, 45, 46, 50, 52, 54, 55, 58, 60,

67, 68, 104, 105, 106 application 5, 8, 11, 12, 13, 14, 15, 17, 23, 26, 27, 33, 38,

43, 49, 53, 57, 62, 65, 70, 71, 72, 75, 76, 77, 78, 79, 85, 86, 87, 88, 91, 92, 94, 95, 97, 100, 104, 109, 113, 115, 116, 118, 122, 123, 124, 125, 126, 127, 128, 129, 131, 132, 133, 134, 135, 136, 137, 139, 140, 141, 142, 143, 150, 151, 153, 157, 159, 160, 164, 165, 166, 167, 171, 172, 173, 176, 177, 182, 183, 184, 189, 191, 192, 193, 195, 204, 205

Application Server 3, 11, 26, 124, 128, 129, 135, 137, 141, 159, 165, 166, 168, 171, 172, 174, 176, 177, 183, 192

Application servers 125 application tracing 75, 123 archive files 14, 144 attributes 144, 148, 153, 157, 166 authorized 110, 117, 200, 203, 210 Call Graph 2, 15, 23, 30, 36, 72, 73, 74 call graph view 72 Call Tree 2, 15, 23, 30, 36, 40, 51, 68, 70, 72, 74, 77,

84, 85, 88 class 31, 56, 61, 64, 83, 87, 90, 91, 92, 95, 96, 97,

98, 99, 100, 115, 118, 124, 144, 145, 149, 151, 152, 153, 154, 155, 156, 221, 223, 225, 226, 227, 228

classes 14, 60, 87, 95, 98, 100, 115, 120, 121, 124, 125, 128, 143, 144, 146, 148, 149, 151, 152, 153, 155, 156, 159, 160, 162, 164, 165, 166, 167, 171, 182, 183, 221, 223, 228

Collector 124, 125, 126, 127, 129, 131, 137, 150, 166 columns 16, 36, 37, 39, 40, 42, 44, 45, 46, 48, 50, 52,

53, 54, 55, 56, 58, 60, 61, 63, 64, 66, 67, 68,


Page 229


70, 106, 112

comments 20 complimentary 189, 192, 203 Concepts 2, 5, 75 Constrain Filters 132 Constraint Sets 17 Contact Us 2, 20 Contention 4, 15, 53, 67, 72, 186, 225, 226 context menu 37, 38, 42, 43, 48, 49, 53, 56, 57, 61, 62, 64,

65, 71, 73, 74, 76, 99, 113, 119, 121, 122, 126, 133, 134, 135, 139, 140, 145, 146, 148, 151, 155, 156, 160, 162, 163, 168, 169, 171, 174, 198, 221, 223, 225, 227

Context Menus 37, 42, 48, 53, 56, 61, 64, 70 cursor 29, 30, 31, 33, 38, 43, 49, 53, 57, 62, 65, 71,

73, 74, 84, 88, 91, 95 customize 5, 23, 37, 42, 48, 53, 56, 61, 64, 70, 103, 104,

206 cyan bars 30 data model 88, 89, 90, 91 default 17, 21, 22, 31, 36, 38, 39, 40, 44, 45, 46, 50,

54, 57, 58, 66, 67, 68, 75, 81, 99, 105, 106, 112, 149, 152, 156, 157, 160, 161, 163, 166, 179, 182, 194, 195, 196, 222, 224, 226

Default 2, 4, 5, 22, 36, 40, 52, 55, 60, 85, 107, 114, 122, 128, 130, 134, 136, 158, 167, 182, 184

Default Perspective 2, 5, 22, 85, 107, 114, 122, 184 descending 83, 85, 91, 96, 99 dialog 17, 38, 39, 44, 45, 49, 50, 54, 57, 58, 66, 67,

80, 81, 82, 83, 87, 88, 95, 99, 104, 105, 106, 110, 111, 112, 113, 117, 118, 119, 120, 121, 125, 127, 128, 129, 131, 132, 133, 134, 135, 139, 140, 141, 151, 154, 155, 156, 160, 161, 163, 164, 168, 169, 173, 174, 179, 192, 193, 194, 195, 196, 197, 222, 224, 226

Discover Status 26, 27, 135 drag-and-drop 145, 146, 152, 156, 157, 221, 223, 225, 228 duration 15, 87, 95, 114, 132, 133 Eclipse 4, 8, 9, 11, 14, 23, 38, 43, 49, 57, 62, 65, 70,

75, 79, 84, 86, 91, 94, 96, 104, 108, 109, 115, 116, 126, 131, 137, 141, 142, 144, 172, 175, 178, 179, 180, 184, 189, 190, 191, 193, 194, 195, 196, 197, 198, 199, 200

editor 14, 22, 38, 43, 49, 57, 62, 65, 70, 74, 113, 133, 134, 144, 147, 148, 157

EMF 9, 189, 190, 191, 194, 196, 200 encounter problems 27, 179 entity beans 100 entry point 75, 118, 119, 121, 122, 159 examine 29, 30, 31, 76, 86, 87, 90, 92, 94, 95, 135,

187, 198 Examine 3, 83, 87, 95, 98, 182, 184, 186


Page 230


Feedback 10 filters 39, 45, 50, 54, 58, 67, 105, 115, 124, 128, 132,

136, 152, 153, 154, 157, 160, 164, 182 Flat View 16, 38, 44, 57, 66 garbage collection 87, 92, 95, 96, 97, 98 garbage-collected 37, 42, 48, 55, 70, 89 GEF 9, 189, 190, 194, 195, 196 Getting Started 2, 5 graphical representation 15, 23, 72 Hardware 8, 189, 205 heap 23, 31, 37, 42, 48, 55, 60, 70, 76, 77, 88, 89,

90, 91, 92, 96, 97, 98, 100, 124, 144, 149, 150, 154, 225, 227

help 4, 5, 6, 17, 19, 20, 23, 79, 80, 86, 94, 113, 115, 122, 180, 198, 199

Hierarchical View 16, 38, 44, 57, 66 histogram bar 15, 72 hover 29, 30, 31, 33, 73, 84, 88, 91, 95 IBM Profiler 3, 25, 75, 103, 114, 115, 124, 184 identify 3, 5, 77, 83, 86, 87, 91, 92, 94, 112, 118, 124,

182, 186 import 5, 17, 79, 81, 82, 83, 86, 94, 109, 111, 112,

113, 115, 117, 118, 122, 153, 165, 168, 179, 184, 192, 200, 211

Import 3, 5, 15, 80, 81, 82, 86, 94, 109, 110, 111, 112, 116, 165, 168, 179, 180, 184, 192

Info tab 87, 95 installed 9, 104, 125, 126, 128, 129, 132, 139, 140, 143,

171, 172, 191, 193, 194, 195, 196, 197, 198, 199, 205, 207

InstallShield 189, 191, 192, 193, 194, 195, 196 instance 9, 55, 60, 83, 84, 90, 96, 100, 125, 126, 132,

135, 139, 140, 176, 177, 179, 180, 189, 193, 194, 195

instances 23, 31, 55, 60, 77, 87, 90, 96, 97, 99, 100, 184, 193, 195, 197, 214

instructions 5, 108, 123, 126, 127, 128, 131, 137, 140, 143, 157, 160, 168, 172, 176, 177, 188, 193, 197, 198

instrumentation 5, 14, 21, 22, 24, 25, 26, 36, 65, 103, 124, 125, 126, 128, 129, 131, 132, 135, 136, 137, 139, 140, 141, 143, 144, 146, 149, 150, 151, 152, 154, 155, 156, 157, 158, 159, 160, 163, 164, 165, 166, 167, 168, 169, 171, 172, 173, 174, 176, 177, 182, 183, 192, 228

Instrumentation 2, 3, 4, 5, 9, 14, 22, 23, 25, 124, 128, 129, 130, 134, 136, 137, 139, 140, 143, 144, 145, 146, 147, 149, 150, 151, 152, 155, 156, 157, 158, 160, 161, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 182, 191, 221, 223, 225, 226, 227, 228

Instrumentation Editor 3, 5, 14, 22, 23, 136, 143, 144, 151, 152, 155,


Page 231


156, 157, 160, 166

instrumentation set 125, 128, 132, 137, 140, 157, 160, 165, 172 Instrumented IBM Products 2, 4, 9, 191 instrumenting 26, 27, 43, 56, 61, 65, 143, 159, 160, 165, 166,

183, 191 Interpreting Application Server Icon 26 J2EE 5, 8, 11, 79, 100, 123, 124, 126, 137, 159 Java 5, 8, 16, 23, 25, 31, 36, 38, 41, 43, 47, 49, 52,

53, 55, 57, 60, 62, 63, 65, 69, 70, 75, 76, 91, 94, 95, 96, 118, 124, 125, 137, 141, 147, 149, 150, 153, 162, 164, 189

key bindings 145, 146, 152, 156, 157, 222, 224, 226 KWEINSTR 144, 148, 153, 157, 225 kweiuser.xml 14, 22, 124, 144, 147, 148, 153, 157, 165, 166,

168, 169 last error 134 leak 55, 78, 86, 87, 92, 95, 98, 100 Legal Notices 4, 200, 203, 210 lib directory 159 License 4, 200, 201, 203, 206, 207, 210, 212 licensing 200, 205, 206, 209 live trace 3, 25, 60, 75, 77, 86, 87, 94, 95, 103, 123,

124, 131, 133, 134, 166, 192 Lock Contention 2, 3, 5, 16, 17, 23, 43, 56, 63, 64, 65, 74, 81,

102, 112, 145, 158 major and minor name 151, 156 Manual Removal 140, 141 maximize 12, 84, 85, 91 memory 5, 55, 60, 75, 77, 78, 86, 87, 89, 94, 95, 96,

98, 100, 122, 132, 133, 175, 178, 182, 191 Memory 3, 4, 59, 62, 86, 93, 94, 101, 178 memory leaks 5, 55, 60, 75, 77, 94, 96, 98 Method Calls 2, 4, 15, 23, 30, 40, 42, 44, 46, 48, 56, 61, 64,

65, 68, 72, 74, 84, 186 Method Time Eye-catcher 2, 15, 23, 30, 33, 36, 40, 51, 68, 71, 72, 74,

76, 77, 83, 185 methods 5, 14, 15, 16, 17, 29, 30, 33, 40, 41, 43, 46,

47, 48, 52, 56, 61, 63, 64, 65, 68, 69, 70, 72, 73, 75, 76, 77, 79, 82, 84, 85, 94, 100, 113, 120, 121, 124, 125, 128, 146, 149, 151, 152, 154, 155, 156, 159, 160, 162, 163, 164, 171, 182, 210, 221, 223, 228

Modify 82, 112, 119, 121, 122, 163, 172, 221, 223, 225

mouse over 72, 73 My Computer 86, 94 navigate 35, 37, 43, 48, 56, 61, 65, 70, 76, 110, 117,

185, 193 Notices 4, 214, 219 object references 3, 60, 86, 87, 94, 95, 98, 100, 132, 133, 158,

167, 182 Object References 2, 23, 31, 32, 59, 60, 61, 90, 91, 93, 99, 101,


Page 232


132

objects 5, 12, 14, 16, 17, 23, 31, 37, 42, 48, 53, 55, 56, 58, 60, 63, 69, 70, 77, 86, 87, 88, 89, 90, 91, 92, 94, 95, 97, 98, 100, 124, 125, 128, 151, 152, 154, 155, 160, 164, 171, 182

Objects 2, 16, 23, 31, 32, 37, 42, 48, 55, 56, 57, 59, 62, 65, 69, 70, 76, 77, 87, 88, 89, 91, 93, 95, 96, 97, 98, 99, 101, 155, 227

OMEGAMON XE 3, 9, 11, 13, 16, 20, 25, 75, 103, 108, 109, 122, 124, 131, 168, 169, 177, 184, 191, 192, 204, 205, 206, 211

Operating Environment 2, 4, 8, 189 package 40, 48, 56, 61, 64, 100, 118, 124, 152, 153,

155, 156, 225, 227 PathWAI Performance Analyzer 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 14, 16, 17, 19, 20,

21, 22, 23, 24, 36, 37, 38, 39, 40, 42, 43, 45, 46, 48, 49, 50, 52, 53, 54, 55, 56, 58, 60, 61, 64, 65, 67, 68, 70, 75, 78, 79, 83, 85, 86, 87, 94, 95, 98, 99, 103, 104, 105, 106, 108, 109, 113, 115, 116, 118, 122, 123, 124, 125, 126, 127, 131, 135, 136, 137, 140, 143, 144, 151, 159, 160, 166, 168, 175, 176, 177, 179, 180, 181, 182, 183, 184, 186, 188, 189, 191, 192, 193, 194, 195, 196, 197, 198, 199

PathWAI Products 11 PathWAITM Performance Analyzer 4, 5, 8, 189, 200, 203 Pending 129, 137, 140, 172, 220 pie chart 23, 30, 33, 34, 35, 83, 185 Preferences 3, 5, 23, 36, 37, 38, 39, 40, 42, 43, 45, 46, 48,

49, 50, 51, 52, 53, 54, 55, 56, 58, 60, 61, 64, 65, 67, 68, 70, 71, 74, 104, 106, 186

Printed Documentation 2, 6, 17, 19 problems 3, 5, 8, 10, 11, 20, 77, 83, 85, 103, 135, 147,

149, 176, 199, 209 Product Overview 2, 7 Profiler 9, 108, 115, 124, 125, 131, 140, 141, 166, 191,

192 profiling 8, 75, 118, 123, 124, 126, 131, 135, 139, 140,

166, 198 Profiling Monitor 2, 22, 26, 125, 126, 127, 129, 130, 134, 135,

136, 137, 138, 139, 140, 142, 165, 166, 171, 172, 176, 184, 198

Profiling Resources 2, 22, 24, 25, 87, 95, 99, 128, 129, 131, 133, 136, 151, 160, 165, 166, 168, 169, 172, 174, 184, 192, 198

Properties 26, 27, 87, 88, 95, 99, 104, 113, 125, 128, 129, 134, 135, 136, 137, 139, 140, 141, 171, 172, 173, 176, 177

Recycle 137, 141, 142, 165 Reference 4, 17, 60, 77, 99, 188, 191, 192 references 3, 55, 60, 87, 88, 89, 90, 91, 92, 98, 99, 108,

133, 158, 167, 212, 213, 214, 215, 216, 217


Page 233


restart 126, 135, 136, 165, 173, 197, 210 Restart 139, 165, 173, 197 Right-click 26, 87, 95, 99, 125, 127, 131, 152, 155, 156,

161, 162 Runnable 195 runtime error log 133, 134 sample trace 3, 5, 75, 79, 80, 94 scroll 74, 96, 97 Selected Method Summary 2, 23, 30, 35, 36, 40, 84, 185 Setting up 3, 5, 27, 107, 123, 124, 127, 131, 134, 136,

138, 142, 158, 166, 167, 168, 170, 182 Show in 37, 42, 48, 53, 56, 61, 64, 70, 73, 84, 85 sort 37, 42, 48, 53, 56, 61, 64, 70, 83, 91, 96, 97,

99, 112 Source Tab 147 Spotting 4, 186, 187 Statistics 3, 37, 42, 48, 53, 56, 61, 64, 70, 104, 106, 186 String 37, 41, 69, 91, 95, 97, 98 suggestions 20 Supported Trace File Imports 2, 4, 9, 191 synchronized 15, 63, 65, 68, 72, 144, 186 synchronized objects 63 syntax coloring 144, 147 System 3, 4, 5, 149, 150, 158, 159, 163, 165, 171, 183,

189, 220 System Classes 3, 4, 5, 150, 158, 159, 165, 171, 183 Table Content Filtering 17 Table Content Filters 38, 44, 49, 53, 57, 66 Table of Contents 2 test servers 125, 126, 127, 137, 192 Threads 2, 23, 52, 53 Time Cumulative 29, 30 Time Self 29, 30, 33, 34, 35, 40, 41, 46, 47, 68, 69, 74,

83, 85, 185 Tips 4, 5, 6, 158, 167, 181 toggle 35, 38, 43, 49, 57, 62, 65, 71, 74, 83, 98, 99 Toggle 16, 38, 43, 44, 49, 57, 62, 65, 66, 71 toolbar button 16, 17, 38, 39, 44, 45, 49, 50, 53, 54, 57, 58,

66, 67, 74 trace 3, 5, 8, 9, 14, 15, 16, 17, 21, 22, 23, 25, 26,

28, 29, 31, 37, 39, 43, 45, 50, 54, 55, 56, 58, 60, 61, 63, 65, 67, 75, 77, 79, 80, 81, 82, 83, 85, 86, 87, 88, 89, 90, 91

Trace 2, 3, 4, 5, 9, 15, 16, 17, 25, 27, 80, 81, 82, 83, 87, 95, 99, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 122, 123, 130, 131, 132, 136, 142, 146, 150, 152, 155, 156, 158, 166, 167, 179, 182, 184, 191

Trademark 4, 219 troubleshoot 103 Tutorial 3, 5, 17, 59, 62, 67, 79, 86, 87, 93, 94, 95,

101, 102, 114, 122, 185


Page 234


Uninstallation 197, 198 Unsynchronized 4, 176 upgrading 192, 193 User Defined Delays 4, 145, 147, 156, 221, 222, 228 User Guide 7, 8, 19, 21, 24, 28, 55, 60, 78, 103, 104, 108,

123, 143, 175, 181, 188, 191, 197, 199 Views 2, 5, 21, 24, 28, 113, 122 WAS 9, 86, 94, 127, 141, 142, 191, 192, 198 Web Download 193, 195 WebSphere 5, 8, 9, 11, 12, 13, 20, 22, 26, 38, 43, 49, 57,

62, 65, 70, 75, 103, 108, 109, 115, 124, 125, 126, 127, 128, 132, 137, 139, 140, 141, 142, 150, 166, 168, 169, 177, 189, 191, 197, 198, 199, 220

WebSphere Application Server 5, 8, 9, 11, 12, 20, 22, 75, 103, 108, 109, 124, 126, 128, 137, 166, 168, 169, 177, 191

What's New 14 Windows Explorer 86, 94 Workbench 13, 104, 179, 219 workload 5, 8, 15, 23, 29, 33, 36, 37, 75, 76, 78, 82, 83,

94, 112, 114, 118, 119, 121, 122, 148, 149, 150, 152, 159, 165, 183, 185, 187, 189, 221, 223, 228

Workload 2, 3, 4, 36, 41, 47, 52, 63, 69, 74, 75, 79, 81, 82, 112, 114, 118, 119, 120, 121, 122, 149, 150, 151, 152, 185, 223, 228

Workloads 2, 4, 15, 16, 22, 23, 29, 30, 36, 37, 39, 68, 72, 74, 75, 77, 82, 85, 88, 106, 145, 147, 148, 149, 151, 152, 166, 185, 223, 224, 228

WSAD 9, 86, 94, 108, 115, 123, 125, 126, 127, 137, 141, 142, 191, 192, 197, 199

yellow bars 30 ZIP File 197


Page 235

Documents

PathWAI Performance Analyzer, V110publib.boulder.ibm.com/tividd/td/ITPathPAnal/GC32-9341... · 2004. 8. 28. · Tips and Tricks..... 181 Changing Default Instrumentation Set ... PathWAI