Perform A Sure UserGuide

PerformaSure
Users Guide
Version 3.5
TM
J2EE performance diagnosis
World Headquarters 8001 Irvine Center Drive Irvine, CA 92618 www.quest.com email: info@quest.com US and Canada: 949.754.8000 Fax: 949.754.8999
June 2004
Part No: STPSUSER350
Copyright Quest Software, Inc. 2001-2004. All rights reserved. This guide contains proprietary information, which is protected by copyright. The software described in this guide is furnished under a software license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of the applicable agreement. No part of this guide may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording for any purpose other than the purchasers personal use without the written permission of Quest Software, Inc. Warranty The information contained in this document is subject to change without notice. Quest Software makes no warranty of any kind with respect to this information. QUEST SOFTWARE SPECIFICALLY DISCLAIMS THE IMPLIED WARRANTY OF THE MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Quest Software shall not be liable for any direct, indirect, incidental, consequential, or other damage alleged in connection with the furnishing or use of this information. Trademarks PerformaSure is a trademark of Quest Software, Inc. Other trademarks and registered trademarks used in this guide are property of their respective owners. See License Credits for a list that includes third-party products included in PerformaSure. World Headquarters 8001 Irvine Center Drive Irvine, CA 92618 www.quest.com e-mail: info@quest.com U.S. and Canada: 949.754.8000 Please refer to our Web site for regional and international office information.
Contents
Preface .........................................................................1
About Quest ....................................................................................................2 About Quests Java and J2EE Products ..................................................2 Overview of the Manual ................................................................................5 Assumptions ..............................................................................................7 Conventions Used in this Manual...........................................................7 Related Documents ........................................................................................8 The PerformaSure Documentation Suite ...............................................8 Suggested Reading....................................................................................9 To Contact PerformaSure Support .......................................................10 Product Feedback and Announcements...............................................11
Part I: Structure and Workflow

Chapter 1 Introducing PerformaSure ................................................. 15
Introducing PerformaSure ...........................................................................16 Key PerformaSure Concepts and Terms..............................................16 PerformaSure at a Glance ......................................................................17 Using PerformaSure .....................................................................................20 What Does PerformaSure Do? ..............................................................21 What Approach Does PerformaSure Take?.........................................23 Who Uses PerformaSure? ......................................................................23 How Does PerformaSure Fit In With Your Infrastructure and Tools?......................................................24
What Do PerformaSures Browsers Do? ..............................................25 How does PerformaSure Define a Service Request? ..........................26 How does PerformaSure Show a Service Request? ............................26 PerformaSures Components.......................................................................27 PerformaSure Agents..............................................................................27 PerformaSure Nexus ..............................................................................30 PerformaSure Workstation ....................................................................33 Security ....................................................................................................34 Interaction with Foglight..............................................................................35 Interaction with Spotlight ............................................................................35 Interaction with Load-Testing Tools ..........................................................35 Interaction with Quest Database Tools......................................................36
Chapter 2 Starting PerformaSure ......................................................37

Installing and Configuring PerformaSure ..................................................37 Integrating PerformaSure in Your Environment.................................38 Running PerformaSure ................................................................................39 Starting the Nexus ..................................................................................39 Ensuring that the Agents Are Running ................................................47 Starting the Workstation ........................................................................51
Chapter 3 Recording a Session ........................................................59

Recording a Session .....................................................................................59 Poor Performance Culprits ....................................................................60 Recording Levels ....................................................................................61 Including and Excluding Classes ..........................................................65 How the Nexus Categorizes Service Requests ....................................68 Load Levels .............................................................................................69 Service Request Sampling......................................................................70 Service Request Separation ...................................................................71 Service Request Filtering .......................................................................73 Session Acquisition .................................................................................74
ii PerformaSure: Users Guide
Acquiring a Session ......................................................................................76 ConfigurationOverview .......................................................................76 Load Testing............................................................................................79 Collecting Your First Session.................................................................79 Recording a Session FAQ............................................................................81
Chapter 4 Analyzing Sessions.......................................................... 83

Methodology .................................................................................................83 Navigating the Project Window ..................................................................85 Opening Large Session Files..................................................................85 Selecting Another Project or Session ....................................................86 Customizing the Project Window .........................................................86 Using the Browsers .......................................................................................90 Customizing the Browsers......................................................................91 Using the Time Control Panel...............................................................91 Using the Request Time Browser..........................................................96 Using the SQL Browser....................................................................... 104 Using the Request Tree Browser........................................................ 108 Using the Metrics Browser.................................................................. 118 Using the Network Traffic Browser ................................................... 121 Using the Thresholds Browser............................................................ 125 Integration with the Quest Software Suite for Further Analysis ................................................................................... 127 JProbe Integration................................................................................ 127 Foglight Integration ............................................................................. 131 Spotlight Integration ............................................................................ 131 Integration with Quest Database Tools ............................................. 131 Analyzing Sessions FAQ........................................................................... 132
Chapter 5 Isolating Performance Problems ........................................135

A Strategy for Finding Performance Problems....................................... 135
iii
Part II: The PerformaSureWorkstation

Chapter 6 PerformaSure Workstation ............................................... 139
Starting the Workstation ............................................................................140 Logging In .............................................................................................140
Chapter 7 PerformaSure Projects ................................................... 155

New Project Wizard ...................................................................................156 New Project WizardSummary ..........................................................156 New Project WizardFull Detail .........................................................157 The Project Window ..................................................................................159 Menus and ToolbarSummary ...........................................................160 Menus and ToolbarFull Detail..........................................................163 The Session Label.................................................................................171 Browsers Area .......................................................................................172 PerformaSure Projects FAQ ......................................................................175
Chapter 8 Recording Control Window and nexusctl................................................................ 177

Recording Control Window......................................................................179 Recording Control WindowSummary.............................................179 Recording Control WindowFull Detail............................................180 Recording Settings Dialog .........................................................................183 Recording Settings DialogSummary ................................................184 Recording Settings DialogFull Detail ...............................................186 Advanced Sampling Dialog.......................................................................195 Advanced Sampling DialogSummary..............................................195 Advanced Sampling DialogFull Detail ............................................196 Recording with nexusctl ............................................................................198 nexusctlSummary ...............................................................................199 nexusctlFull Detail..............................................................................201 Equivalent Recording Control Options ...................................................209
iv PerformaSure: Users Guide
Chapter 9 Edit Options Dialog.........................................................215 Chapter 10 Time Control Panel.........................................................219

Time Control Panel ................................................................................... 219 Components in the Time Control Panel ........................................... 219 Related Controls .................................................................................. 222
Chapter 11 Request Time Browser.....................................................225

Request Time Browser .............................................................................. 226 Request Time Browser Modes ........................................................... 227 Menus and ToolbarSummary .......................................................... 227 Menus and ToolbarFull Detail ......................................................... 230 Time Control Panel ............................................................................. 237 Request Time Browser Control PaneSummary ............................. 238 Request Time Browser Control PaneFull Detail ............................ 239 Request Time Browser Graph PaneSummary ............................... 244 Request Time Browser Graph PaneFull Detail .............................. 244 Request Time Browser Detail Pane ................................................... 250 Request Time Browser FAQ .................................................................... 255
Chapter 12 SQL Browser.................................................................257

SQL Browser.............................................................................................. 257 Menus and ToolbarSummary .......................................................... 259 Menus and ToolbarFull Detail ......................................................... 262 Time Control Panel ............................................................................. 268 SQL Browser Control PaneSummary ............................................. 268 SQL Browser Control PaneFull Detail............................................ 269 SQL Browser Graph PaneSummary ............................................... 271 SQL Browser Graph PaneFull Detail .............................................. 272 SQL Browser Detail Pane ................................................................... 278 SQL Browser FAQ .................................................................................... 282
Chapter 13 Request Tree Browser .................................................... 283

Request Tree Browser................................................................................283 Saving Browser Settings .......................................................................284 Menus and ToolbarSummary ...........................................................285 Menus and ToolbarFull Detail..........................................................289 Time Control Panel ..............................................................................302 Request Tree Browser Graph PaneSummary .................................303 Request Tree Browser Graph PaneFull Detail ................................307 Request Tree Browser Detail Pane .....................................................327 Creating a JProbe Launcher File.........................................................332 Request Tree Browser FAQ ......................................................................333
Chapter 14 Metrics Browser ........................................................... 335

Metrics Browser..........................................................................................335 Metric Types .........................................................................................336 Menus and ToolbarSummary ...........................................................337 Menus and ToolbarFull Detail..........................................................340 Time Control Panel ..............................................................................345 Metrics Browser Navigation Pane.......................................................345 Metrics Browser Graph PaneSummary ...........................................347 Metrics Browser Graph PaneFull Detail ..........................................348 Metrics Browser FAQ ................................................................................355
Chapter 15 Network Traffic Browser ................................................. 357

Network Traffic Browser ...........................................................................357 Menus and ToolbarSummary ...........................................................359 Menus and ToolbarFull Detail..........................................................362 Time Control Panel ..............................................................................368 Filter Machines Dialog .........................................................................368 Network Traffic Browser Graph PaneSummary.............................369 Network Traffic Browser Graph PaneFull Detail............................369 Network Traffic Browser Detail Pane.................................................371
vi PerformaSure: Users Guide
Network Traffic Browser FAQ................................................................. 373
Chapter 16 Thresholds Browser ........................................................375

Thresholds Browser................................................................................... 375 Menus and ToolbarSummary .......................................................... 377 Menus and ToolbarFull Detail ......................................................... 380 Time Control Panel ............................................................................. 386 Thresholds Browser Graph PaneSummary .................................... 386 Thresholds Browser Graph PaneFull Detail ................................... 387 Thresholds Browser Detail Pane ........................................................ 390 Threshold Editor........................................................................................ 392 Using the Threshold Editor ................................................................ 393 Setting Thresholds ............................................................................... 394 Thresholds Browser FAQ ......................................................................... 395
Chapter 17 PerformaSure Reports .....................................................397

PerformaSure Reports ............................................................................... 397 Generated Reports............................................................................... 398 Request Time Report .......................................................................... 403 SQL Report .......................................................................................... 404 Request Tree Report ........................................................................... 404 Metric Report ....................................................................................... 406 Network Traffic Report ....................................................................... 407 Threshold Report................................................................................. 407 PerformaSure Reports FAQ ..................................................................... 407
Part III: Reference Appendices

Appendix A Configuring PerformaSure ................................................411
The Configuration File Hierarchy ........................................................... 411 Configuring Agents ................................................................................... 411 The Parameters in agent.config............................................................. 412
vii
Plug-ins...................................................................................................415 Configuring the Nexus...............................................................................417 The Parameters in nexus.config .............................................................418 Configuring Nexus Clients ........................................................................424 The Parameters in rmiclient.config ........................................................424 Configuration Lookup Sequence ..............................................................426 Logging........................................................................................................427 The Parameters in log.config .................................................................427 Instrumentation ..........................................................................................431 Application Methods in Full Detail ....................................................433 Component Instrumentation ...............................................................433 The Parameters in instrumentation.config .............................................438 Configuration FAQ ....................................................................................443
Appendix B Metrics in PerformaSure ................................................. 445

The Metric Hierarchy ................................................................................446 Request Metrics ....................................................................................446 SQL Statement Metrics ........................................................................448 Application Metrics ..............................................................................449 Application Server Metrics ..................................................................450 Machine Metrics ...................................................................................452 Metrics in PerformaSure FAQ ..................................................................453
Appendix C Lexicon ...................................................................... 455 Appendix D Regular Expressions....................................................... 473

How Regular Expressions are Scanned ...................................................476 Typical Regular Expression Patterns..................................................477 Using Regular Expressions in PerformaSure.....................................480
Appendix E License Credits ............................................................ 483

License Credits ...........................................................................................484
viii PerformaSure: Users Guide
Adobe Acrobat..................................................................................... 484 Ant ......................................................................................................... 484 Apache .................................................................................................. 484 BEA WebLogic Server ........................................................................ 484 BCEL..................................................................................................... 485 Hewlett-Packard................................................................................... 485 IBM WebSphere .................................................................................. 485 JBoss ...................................................................................................... 485 Linux ..................................................................................................... 485 Mercury Interactive ............................................................................. 485 Microsoft ............................................................................................... 486 Netscape................................................................................................ 486 Oracle.................................................................................................... 486 Quest Software ..................................................................................... 486 Sun Microsystems ................................................................................ 487 Tomcat .................................................................................................. 487 UNIX .................................................................................................... 487 WinPcap................................................................................................ 487
Index .........................................................................489
ix
x PerformaSure: Users Guide
Preface
Its a good bet that you are reading this Users Guide because you are responsible for a J2EE application that must live up to its design standards regarding throughput. Performance problems can stall your project during QA, or your application can underperform when it is deployed. Why? Because in a multifaceted, distributed application, its hard to pinpoint the biggest contributors to performance degradation. Although tracking down the source of J2EE performance problems isnt easy, Quest Software offers a comprehensive performance assurance solution to help you achieve end-user response-time goals while minimizing hardware and infrastructure costs. When thousands of users are depending on your application, performance is mission critical. This manual is all about PerformaSure. Integration, quality assurance, preproduction, and production teams use PerformaSure to follow service requests through your application. (See How does PerformaSure Define a Service Request? on page 26.) Youll be able to track service requests through every machine that participated in servicing them, seeing how much time on average was spent in each. Perhaps more important, youll be able to measure round trip service request times and see a request tree of all the methods involved. In addition, with PerformaSure you have a performance analysis tool that collects information on the native platform, the Java runtime environment, and the Web servers and application servers that host the J2EE application. With PerformaSures AutoCapture feature, you can monitor your deployed application with Foglight and have it launch PerformaSure when it detects a problem. You can even monitor and drill right into the Java code for your applications using our companion product, Quest Central for J2EE, which includes Foglight for J2EE and JProbe. This chapter includes the following topics:

About Quests Java and J2EE Products Overview of the Manual Related Documents
About Quest
Quest Software, Inc. (NASDAQ: QSFT) is a leading provider of application management solutions. Quest provides customers with Application Confidencesm by delivering reliable software products to develop, deploy, manage, and maintain enterprise applications without expensive downtime or business interruption. Targeting high availability, monitoring, database management and Microsoft infrastructure management, Quest products increase the performance and uptime of business-critical applications and enable IT professionals to achieve more with fewer resources. Headquartered in Irvine, Calif., Quest Software has offices around the globe and more than 18,000 global customers, including 75% of the Fortune 500. For more information on Quest Software, visit www.quest.com.
About Quests Java and J2EE Products

Quest Software provides software analysis and performance assurance tools that have dramatically improved the performance and reliability of Java applications. As well, its set of data visualization components provides award-winning, off-theshelf solutions for your graphical user interface (GUI) development needs. Quest Software also offers robust and highly scalable Java deployment solutions that allow IT groups to deploy mission-critical, frequently-updated applications to thousands of users in the multi-site enterprise.
Big Brother
Use Big Brother for Systems Availability Monitoring. With multiple servers making up the backbone of your IT environment, it is important to efficiently manage these machines for optimal performance and continuous availability. Its crucial to properly monitor an environment comprised of multiple servers. However, high cost and complexity make management frameworks an impractical method for monitoring the availability of file, print, development and test servers.
Foglight
Many of todays complex Web applications are designed around J2EE application server technologies. Ensuring the availability and performance of your mission-critical Web-based applications is key to your business success. Foglight has the ability to monitor the complex architecture of application
2 PerformaSure: Users Guide
server technology, providing detailed information for analysis and reporting, alerting you about performance-related problems and guiding you to determine the root cause of the problem. With Foglight, you can be assured that your applications will be running at the levels that your users require. Using PerformaSures AutoCapture facility, you can automatically launch PerformaSure if Foglight triggers an outage. There are Foglight Cartridges for Oracle9i Application Server, for BEA WebLogic Server and for IBM WebSphere Server.
Spotlight
Spotlight on Web Servers lets you examine your Web servers with one glance. No other diagnostic tool graphically displays, in real time, the actual server processes and flow of data in your Web-based environment. Spotlight allows you to quickly identify, diagnose and resolve bottlenecks before they seriously impact the end-users experience. Spotlight on databases (DB2, Oracle, SQL Server, and Sybase ASE) enables administrators to anticipate and correct availability and performance issues prior to a negative impact on business processes, assuring the integrity of your business initiatives and service level agreements.
PerformaSure
PerformaSure is the fastest way to isolate and fix a performance problem for a clustered n-tier J2EE application. In production mode, you can monitor your deployed systems performance to ensure that it is meeting its response-time specification. If it isnt, PerformaSure helps you find the trouble spot. During QA, before you go live, PerformaSure works with a load simulator or your own custom stress tester to help you find the root cause of performance problems for n-tier systems with multiple application servers, databases, and Web servers. It does this by providing details of a service request and correlating performance metrics to end-user response times, giving you the fastest way to solve these complex problems. With a load simulator and PerformaSure, you can measure request times for systems under heavy load, and you can use PerformaSures sophisticated browsers to get organized, detailed views of all the data that was collected.
Preface 3
JProbe
The suite of JProbe Java profiling and testing tools has become an industry standard because in enterprise-wide applications, performance, scalability, and reliability are no luxury. JProbe is an unmatched tool for measuring your Java codes performance right down to the line level. JProbe Profiler with Memory Debugger, JProbe Threadalyzer, and JProbe Coverage are available in one conveniently integrated suite. It is everything that you need to ensure that your client- or server-side Java applications perform at peak. We recommend using these products early and often. Performance tuning tools in the JProbe family:

JProbe Profiler JProbe Memory Debugger JProbe Threadalyzer JProbe Coverage Also available from Client Services: JProbe Training
Figure 1
Figure 1
Quests place in monitoring Java performance
Figure 1 shows how Quests performance assurance solutions cover every aspect of your J2EE application stack, from the machines that house them to the code that runs on them.
JClass
Our JClass family is the worlds leading collection of 100% Pure Java client-side and server-side high-performance, certified JavaBeans for data visualization. The JClass family of Java components is designed to help developers accelerate
application development by allowing them to build robust, enterprise-class interfaces cost-effectively and in record time. JClass Desktop Views provides components for client-side GUIs, such as charts, tables, data-aware fields, and many other components. JClass ServerViews brings easy-to-use interactive charting and report generation to your Web server and J2EE application server environments.
DeployDirector
Once the application is built and tested, DeployDirector completes the cycle by providing a reliable and scalable deployment solution. DeployDirector provides a new solution for Java application distribution and management. It is specifically designed for the management and configuration of enterprise Java applications. Application version control and management give IT staff the ability to deploy applications in their entirety or as selective class-level updates.
Overview of the Manual
The manual presents instructions for using PerformaSure in your preproduction or production environment, including step-by-step procedures for configuring, running, and analyzing test scenarios. Section I: Users Guide gives you an overview of PerformaSures browsers and components. The chapters in this section also provide you with an installation checklist and basic configuration information and guide you through the initial stages of data collection and session analysis. Introducing PerformaSure describes the problems that the PerformaSure suite is designed to help you overcome and introduces you to PerformaSures components, browsers, and tools. Starting PerformaSure provides information on how to integrate PerformaSure with your environment, basic configuration instructions, and steps that you can follow to begin running PerformaSure. See the Installation and Configuration Guide for details on installing PerformaSure. Recording a Session suggests ways of planning your data-collection phase and instructions for recording your first session. Analyzing Sessions discusses strategies for using PerformaSures capabilities to analyze session data and introduces you to the browsers features. Isolating Performance Problems suggests a strategy for isolating your current performance problems.
Preface 5
Section II: Workstation Reference gives you a more detailed look at the browsers, windows, and tools that you access through the PerformaSure Workstation. PerformaSure Workstation is the first chapter in Section II that discusses in detail the the graphical user interface (GUI) to PerformaSure with which you manage users, record new sessions, and explore and analyze existing sessions with the help of data browsers. This chapter covers topics like starting the Workstation, logging in, and user management. PerformaSure Projects takes an in-depth look at Projects, PerformaSures central point of control. This chapter covers topics like using the New Project Wizard, which you can use to open a session in a new Project, and configuring the Project window. Recording Control Window and nexusctl describes the Recording Control window and nexusctl, which are used to configure recording settings and collect session data. This chapter covers topics like navigating the Recording Settings dialog and using nexusctl. Edit Options Dialog discusses the Edit Options dialog. From the various panes of this dialog, you can adjust themes and customize PerformaSure Reports as well as set properties for Request Tree and Metrics browsers. Time Control Panel discusses the components in the Time Control panel as well as the related time controls located elsewhere in the browsers. Request Time Browser discusses the Request Time browser. SQL Browser discusses the SQL browser. Request Tree Browser discusses the Request Tree browser. Metrics Browser discusses the Metrics browser. Network Traffic Browser discusses the Network Traffic browser. Thresholds Browser discusses the Thresholds browser. PerformaSure Reports describes the reports that you can generate from PerformaSures browsers. Section III: Appendices Configuring PerformaSure describes PerformaSures configuration files and the configuration options in these files. The topics discussed in this chapter are The Configuration File Hierarchy, Configuring Agents, Configuring the Nexus, Configuring Nexus Clients, Configuration Lookup Sequence, Logging, and Instrumentation. Metrics in PerformaSure discusses the broad categories of metrics that PerformaSure collects and calculates and describes the metric hierarchy. Lexicon contains brief descriptions of the terms relating to performance monitoring, including terms specific to PerformaSure. Regular Expressions provides an overview of regular expressions, including some examples of the use of regular expressions in PerformaSure. License Credits lists the trademark owners for materials used or referenced by PerformaSure.
Assumptions
This manual assumes that you have some experience with the Java programming language. Before proceeding with this manual, you should have a basic understanding of object-oriented programming and Java programming concepts (such as classes, methods, and packages) and elements of J2EE technology as well as of the supported application servers listed in the Installation and Configuration Guide.
Conventions Used in this Manual

Typewriter Font
Java language source code and examples of file contents PerformaSure and Java classes, objects, methods, properties, constants, and events HTML documents, tags, and attributes Commands that you enter on the screen Pathnames, filenames, URLs, and programs Names of the components, such as browsers, dialogs, and windows in PerformaSure, and to emphasize important words Figure and table titles The names of other documents referenced in this manual, such as Java in a Nutshell Keyboard key names, clickable objects, and menu references. In general, any user action with mouse or keyboard First mention of a key term or component A variable whose value you are required to supply. For example, <performasure_home> is the PerformaSure home directory.
Italic Text
Bold
Bold Italic
<value>
Preface 7
Symbols
Caution: Alerts you to some pitfall that may catch you unaware. Topics introduced by this symbol suggest ways of avoiding the problem, or ways of working around some unwanted but unavoidable condition. Example: Introduces a suggested course of action for using PerformaSure.
Important: Introduces material of special importance.
Tip: Anticipates some action that you may want to take and suggests a direction you might take to accomplish it.
Troubleshooting: Suggests a corrective action if you encounter the problem described.
Related Documents
The PerformaSure Documentation Suite
The readme
The readme file is in HTML format, and is called readme.html. It contains: A list of supported platforms, Web servers, application servers, A synopsis of the installed directories, Notes and a list of known problems,
And late-breaking news about issues that occurred just as the product was
being shipped. Consult this document first because it may contain modifications to some procedures described in this manual.
Installation and Configuration Guide

The Installation and Configuration Guide contains information about setting up and configuring PerformaSure to work with your Web servers and application servers. All installation and configuration procedures are covered in this guide.
PerformaSure Users Guide

The Users Guide (this manual) contains detailed information about running PerformaSure. This information can be accessed by clicking one of the help buttons or help menu items in PerformaSure. The Users Guide should be consulted for a complete discussion of PerformaSures architecture and functioning, the user interface, and specific procedures for collecting data and analyzing results. Not included in PerformaSure manuals: Database-specific issues, such as setting up your database software, caching, resource pooling, and designing efficient database tables. Consult your database vendors manuals for these topics.
Setting up and configuring your Web server and application server software. However, additional instructions for configuring the servers to work with PerformaSure are provided. Internal efficiency issues in Java and EJB environments.
Suggested Reading
J2EE Patterns: http://developer.java.sun.com/developer/technicalArticles/J2EE/patterns/ J2EE Articles: http://developer.java.sun.com/developer/technicalArticles/ebeans/ EJB Tutorial: http://developer.java.sun.com/developer/onlineTraining/Beans/EJBTutorial/index.html
Preface 9
To Contact PerformaSure Support

Quest Softwares world-class support team is dedicated to ensuring successful product installation and use for all Quest Software solutions.
PerformaSure Technical Support SupportLink
www.quest.com/support For PerformaSure technical support information, select the J2EE Solutions product family and then select PerformaSure. You can start a new case from the SupportLink login page or by selecting New Case from the PerformaSure page. support@quest.com 800-663-4723 (toll free in North America) or 416-933-5000 (Toronto office: Available Monday Friday, 9:00 a.m. to 8:00 p.m. EST) 416-933-5001 Email: support@quest.com Telephone: +31 (0)20 510-6700 Fax: +31 (0)20 470-0326 Available Monday Friday, 9:00 a.m. to 5:00 p.m. CET www.quest.com/support To access the Frequently Asked Questions section, select J2EE Solutions > PerformaSure.
E-mail
Telephone Fax European Customers Contact Information PerformaSure FAQs
You can use SupportLink to do the following:

Create, update, or view support requests Search the knowledge base Access FAQs Download patches
Any request for support must include your PerformaSure product serial number. Supplying the following information will help us serve you better:

Your name, email address, telephone number, company name, and country. The product version and serial number, found in the license file. The JDK and server versions that you are using. The type and version of the operating system you are using. Your development environment and its version. A full description of the problem, including any error messages and the steps required to duplicate it.
All relevant log files. See the Installation and Configuration Guide for the location of these files.
Product Feedback and Announcements

We are interested in hearing about how you use PerformaSure as well as any problems you encounter or any additional features that you would find helpful. Many enhancements to PerformaSure products are the result of customer requests. Please send your comments to: Quest Software Inc. World Headquarters 8001 Irvine Center Drive Irvine, CA 92618 www.quest.com email: info@quest.com US and Canada: 949.754.8000 Fax: 949.754.8999
Preface 11
Part Structure and Workflow
Chapter 1
Introducing PerformaSure
Many J2EE system developers and production specialists need a J2EE analysis tool because their application is not meeting specific performance requirements an unfortunate but common phenomenon in the world of enterprise solutions. PerformaSure is designed to help you diagnose and solve performance issues. With AutoCapture, it even allows you to launch a session automatically when a problem has been detected by Foglight. PerformaSure enables performance investigation teams to plan ways to correct performance problems in pre-production J2EE environments and can also be used once an application is deployed to ensure that planned capacity goals are met. PerformaSures rich user interface and reporting mechanism present data in a format that allows you to correlate the timing and request-based information with your defined business cases. This chapter introduces you to the PerformaSure environment and provides information that will help you start working within the PerformaSure environment comfortably and efficiently. The following topics are covered in this chapter:

Introducing PerformaSure Using PerformaSure PerformaSures Components PerformaSure Agents PerformaSure Nexus PerformaSure Workstation Security Interaction with Foglight Interaction with Spotlight Interaction with Load-Testing Tools Interaction with Quest Database Tools
15
Introducing PerformaSure
This section provides basic information about PerformaSures terminology and components. For a more detailed discussion about how PerformaSure works, see Using PerformaSure on page 20.
Key PerformaSure Concepts and Terms

This section contains a short list of terms used to describe concepts and components specific to PerformaSure. See Lexicon on page 455 for a more complete list of terms relating to load testing and performance analysis.
Term Browser Definition The data collected in a session can be examined using a PerformaSure browser. PerformaSure has six browsers, each of which are designed to help you isolate different types of performance problems. The browsers are Metrics, Network Traffic, Request Time, Request Tree, SQL, and Thresholds. The software that instruments the platform or the server. These software sensors collect low-level events, do some preliminary processing, and send data to the Nexus over a TCP/IP connection. In this manual, Agent is used as a synonym for PerformaSure Agent. The central data-organizing component of PerformaSure. Agents connect through TCP/IP to the PerformaSure Nexus to report their data The Nexus filters, organizes, and stores the grouped information so that it can respond to queries from a PerformaSure Workstation. In this manual, Nexus is used as a synonym for PerformaSure Nexus. PerformaSure Workstation A PerformaSure Workstation is a controller for initiating data collection. It is also a GUI-based viewer for the data collected by PerformaSure Agents and organized by the PerformaSure Nexus. It permits the data to be viewed from various perspectives, called browsers, so that a drill-down approach may be followed. In this manual, Workstation is used as a synonym for PerformaSure Workstation.
PerformaSure Agent
PerformaSure Nexus
Term service request
Definition PerformaSures Tag and Follow technology defines a service request as anything that enters the Agent-instrumented system, like a HTTPbased request, an RMI call, a JMS call, a direct method call, or a defined interface. By giving you the ability to follow an average request as it progresses through the various containers in your distributed application, you can address the problems that give your end-users a less than perfect perception of your application. A session refers to the act of collecting performance data and to the collected data itself, which is stored in a session file.
session
Tag and Follow PerformaSures Tag and Follow technology instruments the J2EE environment so that service requests can be followed from inception to completion. The full execution path can be seen in the Request Tree browser. time slice The granularity of data collection is determined by setting this parameter. As data is collected, it is lumped into buckets whose duration is set by the time slice parameter. The shorter the time slice, the finer the resolution will be. The increase in accuracy comes with a price: the size of the data file and the load on the machines in the test environment will be higher.
PerformaSure at a Glance
This section provides a brief overview of PerformaSure and its three components:

PerformaSure Agentswhere data is collected PerformaSure Nexuswhere storage and reduction of all collected data takes place PerformaSure Workstationswhere data is displayed for analysis
Background: Distributed Systems

Large business applications are usually spread across distributed systems, often using the standard 3-tier deployment model. Such systems may consist of a hardware or software load-balancer front end that forwards requests to a Web tier consisting of one or more HTTP servers. If the request is for a servlet or a JSP, it is processed in the application servers servlet container. The servlets and JSPs will likely call EJBs (collectively called the middle tier), which in turn retrieve data from a backend database. In many cases the application servers are clustered, which means that there are many possible execution paths through the system.
Introducing PerformaSure 17
Figure 2
Figure 2
A typical 3-tier system configuration
This type of system comes with an imposing list of items that demand management. As you drill down into the operation of your system, you are likely to require accurate information about many aspects of system performance, such as:
Request times: the time that requests spend in various containers. PerformaSures ability to track a request through a distributed application helps you focus on the important resource spongesthe ones that contribute most to performance loss from the end-users perspective. Network traffic: the number of bytes transferred between machines. Being able to measure the traffic between machines may alert you to an excessive amount of data transfer, some of which may be unnecessary. Operating system metrics: for example, CPU utilization, physical memory use, page faults, processor queue length, and virtual memory use. Java Virtual Machine (JVM) metrics: heap information. Application server metrics: among many others, these include Servlet/JSP metrics: response times, number of Servlet/JSP instances RMI invocations EJB metrics JDBC metrics
JMS bytes transferred
PerformaSure can measure all the quantities listed above and has presentation tools that allow you to make sense out of the collected data. This helps you to isolate the parts of your application that are contributing to overly-long processing times.
Figure 3
Figure 3
A 3-tier system instrumented with PerformaSure
An Overview of PerformaSures Components

PerformaSures three main components are its PerformaSure Agents, the PerformaSure Nexus, and the PerformaSure Workstation. Figure 4 shows a typical configuration. The Nexus resides on its own machine because of its need to process and store large amounts of data. Agents are the lightweight, configurable software sensors that instrument the Web servers and application servers in your test environment or in your production environment. There is a Service Request Agent for each Web server (called a Web Server Agent) and application server (called an Application Server Agent). A System Agent is installed on each machine. It is recommended that you install System Agents on your database machines and
(during QA testing) on the machine hosting your load generator. That way, youll be able to rule out performance problems that originate outside your application itself. In addition to Service Request and System Agents, the two basic types of Agents, there is also PerformaSures X-Agent, which can be used to instrument standalone Java applications and Java application servers other than Apache Tomcat, BEA WebLogic Server, IBM WebSphere Application Server, JBoss Application Server, Oracle 9iAS, and Oracle Application Server 10g. One or more PerformaSure Workstations allow you and members of your team to analyze collected session data. For details about PerformaSures components, see PerformaSure Agents on page 27, PerformaSure Nexus on page 30, and PerformaSure Workstation on page 139.
Figure 4
Figure 4
PerformaSures three types of components
Using PerformaSure
This section describes PerformaSure in more detail by answering the following questions:

What Does PerformaSure Do? What Approach Does PerformaSure Take? Who Uses PerformaSure?
How Does PerformaSure Fit In With Your Infrastructure and Tools? What Do PerformaSures Browsers Do? How does PerformaSure Define a Service Request? How does PerformaSure Show a Service Request?
What Does PerformaSure Do?

If you are developing transactional J2EE e-business systems, PerformaSure will help you to isolate performance problems in your pre-production J2EE environment. Low-level, system-wide performance data that doesnt focus on end-user response times isnt enough; its just too much raw data that has to be sifted, checked, backtracked, and sifted again. PerformaSure is efficient because it relates system performance metrics to service requests, which directly affect how end-users perceive responsiveness. PerformaSure has tools for viewing request snapshots for critical time periods and provides supporting metrics for solving performance problems quickly. Because you can relate performance data to use-case scenarios, PerformaSure helps you achieve planned capacity by finding the major contributors to the system degradation that your customers experience. Even better, it provides you with hard data to document how system bottlenecks occur, so your development team knows exactly where to focus its efforts. You can use PerformaSure to measure a configurable number of performance metrics:
Operational metrics. This group includes statistics on how the operating system is performing, how many resources the Java virtual machine requires, and resource usage by the application server. Network traffic metrics. Here, you can determine the number of bytes transferred between machines in your system. The time requests and SQL statements spend in each machine in your system. The call tree for a service request. Tag and Follow technology is used to track the request-response cycle through a complete sequence of calls from the moment of its generation by a URL (HTTP request), RMI call (RMI request), through data retrieval, and back to the end-user.
Figure 5
Figure 5
Reconstruction of the true execution path using Tag and Follow
PerformaSure has a customer use case focus: it takes performance data, including network usage, CPU utilization, memory usage, server statistics, and other metrics, and breaks down the data by request so that you can look at the performance data piece by piece within a unit of work. It organizes system performance data so that you can improve performance for a specific kind of request or a specific type of complaint. PerformaSure uses Tag and Follow technology to label service requests and to follow them through your system. PerformaSure can be used by production specialists, QA teams, and network administrators and their staff to:
Investigate the average behavior of a systems activity organized by requests: PerformaSure collects, correlates and unifies data from any number of distributed servers using Tag and Follow technology. Use browsers to view the data that they need to find the context in which a problem has occurred. See a request decomposition for critical time periods and view the associated metrics to help solve performance problems quickly. PerformaSure provides a high-level view of actual service requests, as well as the ability to drill down to the offending system component. It also monitors request times and helps you track down non-responsive requests. Perform time correlation: PerformaSure allows you to isolate problems that occur at a specific time or over a specific time period. PerformaSure shows you the data that you need for the critical time periods and lets you browse the time periods leading up to the problem.
Measure load balancing across application servers. Measure EJB performance. Track Servlet and JSP response times. Drill down to the level of method invocations and display them in a Request Tree. Measure and display network activity as server clusters interact with one another.
What Approach Does PerformaSure Take?

PerformaSure instruments the business logic level of your n-tier application, including the ability to track database calls. PerformaSure gives you a tool that lets you attack the problem as follows:

Isolate the service request that is taking too long. Find the time period when the slowdown happens. Analyze the service request and identify the tier where the problem is located. Identify the component, which might be a Java class, the network, the database, the Web server, the application server, or the underlying hardware. Call in the functional expert, knowing that the problem has been isolated.
Who Uses PerformaSure?

Lead architects, QA professionals, load testers, database administrators, production performance engineers, integration engineers, and functional testers all benefit from PerformaSures ability to provide snapshots of the average behavior of the system. Lead architects and developers can:

View application architecture on a per-request basis View all method-level timing and determine the relationship to end-user response times Use integration with JProbe to drill down to the Java code line
Database administrators can:

Identify slow SQL statements or inefficient ResultSet processing Count database calls to see if caching would be more efficient Determine when poor database performance is due to inefficiencies within the EJB application.
Drill down into Spotlight to monitor real-time database performance. Drill down into Quest Central to analyze the performance of a selected SQL query.
Application server and system administrators can:

Use PerformaSure to help tune application server resources Tune operating system parameters Uncover those situations where hardware limitations really are the root to the problem Reduce unnecessary hardware costs by finding key inefficiencies and by getting the most out of the infrastructure currently in place
Quality assurance teams can:
Use existing load tools with PerformaSure to provide in-depth Tag and Follow data Identify pre-production problems early Ensure production readiness by shortening the DetectDiagnoseRepair cycle
Production performance engineers can:

Use component instrumentation to capture the overall system behavior. Adjust PerformaSures sampling rate to control the overhead it places on the application while still collecting enough data to detect trouble spots. Select requests of special interest for increased attention. Use PerformaSures AutoCapture to automatically capture a session when Foglight detects a suspicious event.
Because PerformaSures projects and reports encapsulate the troubleshooting process in sharable resources, all groups with the performance and production teams can work together to resolve problems.
How Does PerformaSure Fit In With Your Infrastructure and Tools?

PerformaSure works with your existing infrastructure and tools; it is designed specifically to integrate with industry-leading tools and infrastructure, including Benchmark Factory, Foglight, Spotlight, Mercury Interactive LoadRunner, Oracle 9iAS, Oracle Application Server 10g, Apache Tomcat, JBoss Application Server, BEA WebLogic Server, IBM WebSphere Application Server, and the Quest JProbe product line. As well, it is designed to work with
most load-testing tools, including custom implementations, but in this case there is no integrated mechanism for launching a load test. When you deploy your application, PerformaSures component instrumentation mode and its sampling capabilities keep its overhead down while providing enough monitoring to keep tabs on its operation.
PerformaSures Overhead is Controllable

Theres a trade-off between the amount of data collected by a monitoring system and the overhead imposed. PerformaSure was designed to be lightweight and configurable, meaning that you can substantially decrease the overhead. See A Note on Sampling on page 188 for details.
What Do PerformaSures Browsers Do?

A PerformaSure project may have a number of browsers, each capable of providing insight into your systems performance. Request Time Browser: Enables you to view the response times that requests spend in various containers. Use this browser to check for such things as excessive times spent in JDBC calls. SQL Browser: Helps you identify global database problems by taking a highlevel view of the SQL statements used in your J2EE application. Use this browser to investigate the overall performance of SQL statements used in your application in comparison to the overall response time of all SQL statements in the system. Request Tree Browser: Provides a detailed call tree for each type of service request. Use this browser to view the caller-callee relationships among method invocations and to see performance information on a per-method basis. Both the time spent in the method itself and in all of its children are reported as well as other information. Metrics Browser: Displays performance metrics. All metrics are time-correlated to show you the metrics as they occurred. Metrics are the primary diagnostic measurements of system performance; they provide critical insight into the problem. Thresholds Browser: Provides an overview of your systems behavior, showing metric charts and threshold violations. By definition, a problem is a time period during which a metric lies outside the minimum or maximum thresholds that
have been set for it. The Thresholds browser shows the times during which the metrics thresholds were exceeded. Network Traffic Browser: Enables you to view the traffic between machines for any interval during the session and to see the volume of traffic between machines. The Network Traffic browser displays a traffic matrix, so the volumes of incoming and outgoing traffic between any machine and every other machine are measured and displayed.
How does PerformaSure Define a Service Request?

PerformaSure instruments Web servers and application servers. End-users send these applications HTTP requests, or possibly RMI and JMS calls, as the starting points of a request for service. These initiate a chain of events, probably invoking numerous EJB methods and database calls, before returning a result in the form of an HTML page. PerformaSure defines the entire related chain of events as a service request, or simply as a request. Because many end-users may be sending the same, or very similar, requests to your application almost simultaneously, PerformaSure reports aggregated information for the requests events.
How does PerformaSure Show a Service Request?

PerformaSure breaks request timing down by tier for actual end-user request types, allowing you to isolate problems quickly with the distributed Request Tree browser, which shows logical execution paths, timings, and network usage. To refine your view of service requests and their constituent events, PerformaSures time control functionality lets you isolate any period of time. Use the Zonar to find the time period where a problem occurred. See Time Control Panel on page 219 for more information about the Zonar and the other components of the Time Control panel. If you wish, all other views can be displayed for the same selected time interval, allowing you to focus on symptoms leading up to big problems.
PerformaSures Components
PerformaSure Agents
What is an Agent?
PerformaSure Agents are the performance data collection objects in the PerformaSure architecture. They attach themselves to application servers and Web servers, and they collect metrics from the host operating systems, Java virtual machines, and servers. For complete coverage, System Agents can be placed on the database machine and on the machines hosting your load generator. PerformaSures unique Tag and Follow technology is used to track service requests.
What does an Agent do?

An Agent collects performance information from individual Web servers, application servers, and their host operating systems and passes this data to the Nexus. At the application level, Service Request Agents use byte-code instrumentation to measure method-level performance information. At the server level, Agents monitor the J2EE application server metrics through vendorprovided interfaces. At the Java virtual machine level, Agents monitor various JVM metrics; at the operating system level, they monitor platform-level metrics.
Types of Agents
There are two main types of Agents:
System Agents, which measure operating system, network, and JVM metrics, and Service Request Agents, which track service request information and instrument application servers and Web servers. There are two types of Service Request Agents: Application Server Agents and Web Server Agents.
PerformaSure also features the X-Agent, which can be used to instrument standalone Java applications and Java application servers other than JBoss, Oracle 9iAS, Oracle 10g, Tomcat, WebLogic, and WebSphere. See X-Agent on page 28 for details.
Some Agents run inside an applications Java virtual machine ( JVM), others run as separate processes in their own JVM. When the Agent monitors data for an application running inside a JVM, the Agent runs inside that same JVM. When the application is native, the Agent runs as a separate process. There is only one Agent per JVM and one Agent per monitored application on a given machine. Specifically, if there is more than one monitored application server running on a given machine, there will be an Agent attached to each of those application servers, and hence there will be two or more Agents running on that machine. Agents are instantiated from command files or Shell scripts, usually as part of launching the server itself. See the Installation and Configuration Guide for details. X-Agent If you are not using Oracle 9iAS, Oracle Application Server 10g, JBoss Application Server, Tomcat, WebLogic Server, or WebSphere Application Server, the X-Agent enables you to use PerformaSure to collect performance information about your application server. The X-Agent is a generic PerformaSure Agent that provides the flexibility to instrument any Java class using PerformaSures unique Tag and Follow technology. Although the X-Agent does not provide all of the functionality of standard PerformaSure Agents it does collect:

OS-level metrics such as disk, CPU, and physical memory Data from the JVM such as heap, Servlets, EJBs, method detail, and thirdpary classes
The X-Agent needs to be configured by Quests Client Services team. For more information about customizing the X-Agent and modifying the startup sequence of the application server or standalone Java application that you want to instrument, contact your Quest sales representative.
What Do Agents Do?

Service Request Tag and Follow Merely timing methods does not provide the full picture. A method that takes a very long time to complete may be called only once, or may be part of a rarelyinvoked function. Its important to know the context in which the method executes, how many times it gets called, and what objects it calls. PerformaSures Tag and Follow technology lets you see the tree of method calls, which gives you a true picture of your applications operation. Web Tier metric collection Native plug-ins are required for non-Java Web servers such as iPlanet or Apache . In this case, custom DLLs or libraries are used.
Application Server metric collection If PerformaSure helps you uncover a problem within the application server itself, you may be able to improve performance by adjusting one of the application servers parameters, such as a cache setting or a pool size. On the other hand, if you uncover problems in your J2EE application, you can examine the code and remove the inefficiency. Operating System metric collection To determine the root cause of under-performance, you may want to look at operating system metrics. They can tell you if the machines running your system are red-lining or not. If they are in a constant state of overload, you probably need to increase their processing power. But if they exceed acceptable operating limits only infrequently, knowing when they exceed their thresholds may give you a hint that leads to an improperly tuned part of your application.
How Do They Do It?

Byte code instrumentation Quest Software has had considerable experience with byte code instrumentation, starting before Sun introduced its JVM profiling interface, JVMPI. Beginning with its JProbe suite of products, Quest Software developers have designed a profiling interface with built-in hooks that allow JProbe products to collect data on how your program executes within a JVM. PerformaSures developers have continued the practice by providing instrumentation hooks for Web servers and application servers. Taking this approach enables you to monitor operation details that would otherwise be invisible. Tag and Follow technology Tag and Follow technology functions by instrumenting Web and application servers. This technology facilitates the detailed views furnished by the browsers in a PerformaSure Workstation. Operating system APIs and Application Server Metric Interfaces Rather than instrumenting the operating systems themselves, the rich APIs provided by operating systems allow PerformaSure to collect all the data it needs. Similar APIs are made available by application servers, and these are used by PerformaSure to collect metric data. See Metrics in PerformaSure on page 445 for the kinds of metrics that can be collected in this way.
Which JVM do Agents Use?

Important: Application Server Agents use the same Java Virtual Machine ( JVM) as the application server they are monitoring; you do not need to make any JVM changes. This means that PerformaSure will be monitoring the same environment that your production system uses. Some Web Server Agents require their own JVM. This should be transparent to you and will not impact the system in any way. Since Agents perform various instrumentation tasks, they need the close cooperation of the underlying JVM and Java Runtime Environment ( JRE). When you install an Agent on a target machine using the installer, the JVM/JRE needed by that Agent is installed as well. See the Installation and Configuration Guide for more information on ensuring that the correct JRE is installed. In most environments, the fact that PerformaSure installs its own virtual machine along with its Agents should be transparent to you. In most cases, you do not need to set any configurable parameters.
PerformaSure Nexus
A running PerformaSure application has multiple System and Service Request Agents and one or more Workstations but only one PerformaSure Nexus. It reconstructs the full application-level execution path and it provides information to a Workstation by organizing the collected data into service requests using Tag and Follow technology. See Tag and Follow on page 468 for a definition. The PerformaSure Nexus is the hub of the PerformaSure architecture. It receives data collected from the Agents, then combines and converts the collected data into a cohesive information setthe service requests in a sessionthat can be queried and presented graphically by a PerformaSure Workstation.
What is the Nexus?

The Nexus is essential to the data management and presentation facilities of PerformaSure. Its major functions are to collect information from all communicating Agents, process the information by converting Agent-based event information into coherent service requests, and reply to any PerformaSure Workstation queries. In effect, the Nexus plays three central roles in the
PerformaSure environment: it is the central manager, the data-store component, and the analysis engine that responds to queries from the Workstation. The Nexus central analytical engine correlates data sent from multiple Agents, restores and preserves the temporal order of events across all servers, and provides other basic analysis of the data. Data collection mode The Nexus has two modes of operation, data collection and data analysis. In data collection mode, the Workstation is used to start and stop recording a new session. You have the option of starting to record a session before you start your application, but you may choose to have the application in operation before you begin to record data. It all depends on the scenario that you want to investigate. Tip: It is preferable to collect data first and analyze it later. Running the Nexus in data collection and data analysis mode simultaneously may cause an unexeptable load on your system, especially when analyzing large sessions.
Figure 6
Figure 6
Sample scenario for PerformaSure with the Nexus in data collection mode
Data analysis mode In data analysis mode, the Nexus communicates with a Workstation.
Figure 7
Figure 7
Sample scenario for PerformaSure with the Nexus in data analysis mode
The Workstation is primarily a presentation tool, although you can use it to start and stop sessions and perform other management functions. It does not access the stored data itself, but instead relies on the Nexus to respond to its queries for particular pieces of data.
Session Storage
The data-store component of the Nexus collects data sent from the Agents and provides facilities to store that data. It also constructs replies to queries sent by Workstations. The data-store compresses the data and saves it to disk. The session stores extra information as metadata, which is shown in the New Project Wizard. The metadata provides summary information about performance data, PerformaSure recording settings, and user-specific data. The metadata fields are listed below. Metadata fields
Name
Version
Changed by
Nexus
Description
This value is set to the version number of when the session is created. It is changed when a session is upgraded to a newer version. The time when recording started.
Start Time End Time
Fixed Nexus
The current time (if recording is ongoing), the timestamp of the last data written to the session, or the time at which session recording stopped. The recording detail level setting when the session started recording. Levels are Full and Component. The time slice size that was set when the session started recording.
The name of the session.
Detail Level Time Slice Size Name Created By Comment
Fixed Fixed User Fixed User
The user that initiated the session.

Comments provided by the user.
Nexus Performance
The Nexus may be asked to handle a flood of data. To handle this potentially overwhelming amount of data, it sends messages to PerformaSure Agents telling them how much data it can accept. This may result in some requests being excluded from monitoring. See Recording Levels on page 61 for more
information about recording levels and sampling as well as strategies for reducing overhead.
The Nexus Console

As shown in Figure 8, a console contains log messages associated with an active Nexus.
Figure 8
Figure 8
Messages in the Nexus console
Messages are categorized according to their severity. A description of the message types is given in Log Levels on page 431.
PerformaSure Workstation
The Workstation connects to the Nexus to retrieve information for analysis, which it displays using a rich set of GUI presentation options. You can run as many Workstations as you are licensed for, allowing various team members to record and analyze sessions. The Workstations functions include:

Managing users (with administrator privileges) Managing PerformaSure Projects Initiating a session and collecting data Choosing which session to view Setting thresholds for metric data Using Metrics, Network Traffic, Request Time, Request Tree, SQL and Thresholds browsers to track down performance problems
Generating reports in CSV, PDF, or XML format Exporting a JProbe launcher file Launching Spotlight on DB2, Spotlight on Oracle, Spotlight on WebLogic Server, Spotlight on WebSphere, SQLab Vision for Oracle or SQL Tuning for DB2. See Interaction with Spotlight and Interaction with Quest Database Tools below for more details.
For more information about the Workstation, please see Section II of the Users Guide.
Security
With one exception, anyone in possession of a login name and password for PerformaSure has the same privileges. The exception is that new users must be created using the administrators account. User management is performed in the Workstation. See User Management on page 149 for details on adding new users, removing registered users, and changing passwords.
Figure 9
Figure 9
The Workstations User Management dialog
Once users have been authenticated, they may use all of PerformaSures functionality, including initiating new sessions. Because the operating system is responsible for managing its user base, the session is owned by its initiator. Each person who creates a new set of measurement data is therefore responsible for managing the file permissions on that data so that others can also use it. Any user may choose to terminate a session, even one begun by someone else. If you do stop a session, that information is logged along with your user name.
Network Security
Administrators concerned about network-layer security should security block the port used by the PerformaSure Nexus from the outside network.
Interaction with Foglight

You can configure an action in Foglight that automatically starts a PerformaSure session when a threshold violation is detected. For more information, please see the Foglight Getting Started Guide for your cartridge.
Interaction with Spotlight

There are several ways to launch Spotlight from PerformaSure:
You can launch Spotlight on DB2, Spotlight on Oracle, Spotlight on WebLogic, or Spotlight on WebSphere from the Tools menu of the Project window or any browser (Tools > Performance Diagnostics) and from the toolbar of any browser. You can launch Spotlight on DB2 or Spotlight on Oracle by selecting a JDBC node in the Request Tree browser or a SQL statement in the detail pane of the SQL browser, right-clicking on that node or statement, and choosing Performance Diagnostics > Spotlight on DB2 or Spotlight on Oracle from the contextual menu.
Interaction with Load-Testing Tools

PerformaSure has been created to work well with load-testing tools. Since PerformaSure measures loads but doesnt generate any, it relies on you to stress the system in the way that you choose. Load-testing tools can be used to provide a model of system behavior and performance by emulating users on your system. PerformaSure complements load simulators, collecting request-based data for later analysis: a load-testing tool generates a load (black box) and PerformaSure gives you a detailed breakdown (white box) on all the parts of the systemdown to the EJB method, Servlet method, network traffic metric, or database query time. By investigating the average and maximum times for these requests you can determine whether there are times when your system is behaving suspiciously.
Interaction with Quest Database Tools

There are several ways to launch Quest database tools from PerformaSure:
You can launch SQLab Vision for Oracle or SQL Tuning for DB2 from the Tools menu of the Project window or from any browser (Tools > SQL Tuning) and from the toolbar of any browser. You can launch SQLab Vision for Oracle or SQL Tuning for DB2 by selecting a JDBC node in the Request Tree browser or a SQL statement in the detail pane of the SQL browser, right-clicking on that node or statement, and choosing SQL Tuning > SQLab Vision for Oracle or SQL Tuning for DB2 from the contextual menu.
Chapter 2
Starting PerformaSure
A full account of installing and configuring PerformaSure for its supported environments is given in the Installation and Configuration Guide. This chapter contains a brief overview of the general procedure. By following the steps outlined in this chapter and in the next two chapters (Recording a Session and Analyzing Sessions), you will be:
1.
Installing PerformaSure on each target machine using the PerformaSure Installer, which allows you to choose which specific components should be installed. Editing your servers initialization file so that PerformaSure starts when the server is started. Sample scripts are provided for this purpose. Editing agent.config (in the PerformaSure root directory on each instrumented machine) to specify the location of the PerformaSure Nexus. Starting the PerformaSure Nexus. Starting the application server or servers. Starting a PerformaSure Workstation. Beginning to collect data andif you are using a load testing toolusing it to apply a test scenario. Setting up Projects and analyzing the performance data that you have collected using PerformaSures browsers.
2.
3.
4. 5. 6.
7.
Installing and Configuring PerformaSure

Youll find detailed installation and configuration instructions in the Installation and Configuration Guide. Consult it for information on:
37
Supported platforms. PerformaSure instruments a variety of Web servers and application servers. The complete list of supported servers and supported operating systems is found in the Installation and Configuration Guides introductory chapter. Installing PerformaSure. You install PerformaSure on every machine that hosts a server that you want to instrument. Instructions for running the installer are found in the Installation and Configuration Guides Installing PerformaSure chapter. Configuring PerformaSure. Because PerformaSure works with different servers and different operating systems, it needs to be integrated with your environment. The information for configuring your servers to work with PerformaSure is found in the Installation and Configuration Guides Configuring PerformaSure chapter. After installing PerformaSure and configuring your servers to work with it, you are ready to measure your systems performance. Initial instructions for running PerformaSure are found in the Installation and Configuration Guides chapter on Running PerformaSure. The Users Guide (this manual) assumes that the previous steps have been performed. It describes the general organization of PerformaSure, and it contains information on more advanced configuration issues as well as describing the details of the rich user interface.
Integrating PerformaSure in Your Environment

Because PerformaSure works so closely with your application servers and Web servers, they need to be launched using startup scripts that contain PerformaSure modifications. Ensure that your startup scripts have been modified as described in the Installation and ConfigurationGuide before running PerformaSure.
Running PerformaSure
Starting the Nexus
Agents and Workstations need to communicate with the Nexus, so normally it is started first. Important: The first time that you start PerformaSure you must start the Nexus first. Agents need to access the Nexus to configure their initial settings, which they write to state files. See the Installation and Configuration Guide for details. Follow the instructions in the Installation and Configuration Guide for installing the Nexus; see Configuring the Nexus on page 417 for information about the Nexus and about editing its configuration file, <performasure_home>/config/ nexus.config. Once it is installed, you can start the Nexus by clicking its icon in the program group or by double-clicking its icon found in the bin directory. Since the Nexus runs many resource- and data-intensive processes, Quest Software recommends that you dedicate a machine to it alone.
Note:
Do not adjust the system clock while the Nexus is running. Doing so can invalidate timing information between all Agents and the Nexus. Request times reported by the Workstation will be invalidated.
If you run the Nexus on a multi-CPU machine, the number of processing threads is automatically adjusted for you.
Running the Nexus as a Service

You can install and run the Nexus as a Windows service; see the Installation and Configuration Guide for installation instructions. By default, this services startup type is set to automatic. Use Services (Start > Control Panel > Administrative Tools > Services) to start, stop, configure, and view the properties of the PerformaSure Nexus service.
Launching the Nexus from a Script

It is possible to launch the Nexus from a script called nexusctl.sh (Unix) or nexusctl.cmd (Windows) from the <performasure_home>/scripts directory. See Using nexusctl below for a description of the parameters in nexusctl.
Starting PerformaSure 39
A similar mechanism can be used by Foglight to start a PerformaSure session when it detects a threshold violation. For more information, please see the Foglight Getting Started Guide for your cartridge.
Using nexusctl
The nexusctl utility accepts a number of command options (also called flags) to control its mode of operation. The options for nexusctl are listed below. Basic Options
nexusctl start Starts the Nexus. You can specify -X or -D parameters. Example usage: nexusctl start -Xms768m -Xmx768m -Dperformasure.debug=1
nexusctl stop Properly shuts down the Nexus. Example usage: nexusctl stop -user lisa -pwd oboe789
Nexus Version Options
nexusctl version -r NEXUSURI Retrieves the version number of a remote
Nexus. For example:

nexusctl version -r your.remote.host.com:42705
The version number of the remote Nexus is retrieved in the form of a string, such as 3.5.
nexusctl version Retrieves the version number of a local Nexus in the form of a string, such as 3.5. nexusctl version -b Retrieves the build number of a local Nexus in the form of a string, such as PAS_350-20040506-0700.
Recording Options
start-recording Starts recording a new session. The name given to the session is Nexus <timestamp>, and the time slice for data-collection is one minute. The message appears in the console window that was used to start the Nexus initially. This option permits a number of additional optional parameters. See Parameters for start-recording below for a list of the parameters permitted by start-recording. stop-recording Stops recording the current session. There is one optional parameter: -r URI Set the connection URI for a remote Nexus. For example: -r your.remote.host.com:42705
Use this flag when the Nexus is on another machine than the one in which the nexusctl script is located. Important: The nexusctl script must not be moved from the directory in which it was installed.
Parameters for start-recording The option start-recording permits a number of additional parameters. Login Parameters
-user username Overrides the default username with username. This parameter is optional for all nexusctl options except start (which starts the
Nexus), where it is not required. If you do not specify a username, PerformaSure will assume a default username of user. -pwd password Specifies a password. This parameter is optional for all nexusctl options except start (which starts the Nexus), where it is not required. If you do not specify a password, PerformaSure will assume that an empty password is associated with your username. Caution: The password that you specify is entered in plain text on the command line, but it is encrypted before being sent to the Nexus for user authentication. Basic Recording Parameters
-n NAME Specifies the session name. Specifying this parameter overrides the default session name with NAME. It is recommended that you always place
double quotes around the name parameter. They are required if the name you choose for your session contains one or more spaces. -a Appends the time when recording begins to the filename. -com COMMENTS Allows you to supply comments about the session that you are recording or are about to record. Tip: Surround your comments with quotation marks to protect from shell escape confusion.
Agent Parameters
-ad AGENTNAME Specifies which Agents are to be disabled. AGENTNAME is
a unique name given to each Agent, which you can specify in agent.config.
You only need to provide a list of Agents to be disabled using -ad AGENTNAME. Unless they are specified to be disabled, PerformaSure will record from any Agents connected to the Nexus. You can specify multiple -ad entries for a single nexusctl command. Tip: Surround Agent names with quotation marks to protect from shell escape confusion.
Session Parameters
-i Records indefinitely. To stop recording, issue a stop-recording
command later on. -l nnn Sets the duration of the session. The format for specifying the time is nnns for seconds, nnnm for minutes, or nnnh for hours. Thus, to record for 1 hour, you could use 3600s, 60m, or 1h. Note: You cannot record a session that is shorter than 10 seconds. If you attempt to record a session that is shorter than 10 seconds, PerformaSure will issue a WARN log message in the Nexus console and automatically record for 10 seconds. -t nnn Sets the time slice for the session. Use this option to change the default setting for the time slice, which sets the time granularity for the session. The time slice size determines how finely you can time events. The time slice size that you set when initiating a session is the smallest increment of time achievable for analysis after the data has been recorded. The format for specifying the time slice size is the same as the format for specifying the duration of a session. -irt nnn Sets the incomplete request timeout value, the length of time after which a request will be considered incomplete. The format for specifying the incomplete request timeout is the same as the format for specifying the duration of a session. Sampling Parameters
-c Records at component detail level. Key J2EE components are recorded,
which gives you an overall picture of the application. See Component Instrumentation on page 433 for the list of interfaces that are instrumented at this level of detail. This is the default setting. -f Records at full detail level. If this flag is not present, recording will be at the component level. -s nn Sets the service request sampling percentage. The range for nn is 1 to 100. By default, the Nexus collects as many samples as possible. You can reduce overhead by choosing to sample fewer service requests than the maximum allowable. For example, by setting nn to 50, you are instructing the Nexus to collect half as many samples as it could in each sampling interval.
-swr nnn expression Sets advanced sampling weights using regular
expressions. For example:

-swr 0.43 estore/portal-.*\.jsp The range for nnn is 0.00 to 1.00; the number that you enter represents the
sampling weight. The sum of all advanced sampling entries cannot be more than 1.00, but does not have to equal 1.00. The remaining sampling weight will be applied to all other requests. When you use this parameter, the expression will be evaluated as a case-sensitive regular expression and will match on partial strings. You can specify multiple -swr entries for a single nexusctl command. -swl nnn expression Sets advanced sampling weights using a literal expression. Important: A literal string is a string of characters that is interpreted literally, without any substitutions based on regular expression pattern-matching. Literal strings will be referred to as literal expressions in the Users Guide. See Regular Expressions on page 473 for more information about how regular expressions are used in PerformaSure. For example:
-swl 0.32 estore/do The range for nnn is 0.00 to 1.00; the number that you enter represents the
sampling weight. The sum of all advanced sampling entries cannot be more than 1.00, but does not have to equal 1.00. The remaining sampling weight will be applied to all other requests. When you use this parameter, the expression will be evaluated as a case-sensitive literal string and will match on partial strings. You can specify multiple -swl entries for a single nexusctl command. Tip: Surround the expressions that you use to set sampling weights with quotation marks to protect from shell escape confusion.
Request Separation Parameters

-srr URIregex PARAM Separates requests using regular expressions.
For example:
-srr estore/portal-.*\.jsp country You can specify multiple -srr entries for a single nexusctl command, but be
aware that the order of the entries is significant. PerformaSure will interpret this order as an indication of priority. -srl URIliteral PARAM Separates requests using literal expressions. For example:
-srl estore/do PARAM You can specify multiple -srl entries for a single nexusctl command, but be
aware that the order of the entries is significant. PerformaSure will interpret
this order as an indication of priority. Tip: Surround the expressions that you use to separate requests with quotation marks to protect from shell escape confusion.
-sl nn Sets the maximum length for a value used in request separation. The range for nn is 1 to 512; the default value is 32. This is a global entry
that will be applied to all request separation entries. Filtering Parameters Tip: If you have specified request separation on a parameter by entering a nexusctl request separation flag, you can filter requests on that parameter by using request filtering options.
Important: Requests for CSS, GIF, JPEG, JS, and PNG files are excluded by default. Specify -fir or -fir options if you want to include any of these requests.
-fir expression Filters requests for inclusion using regular
expressions. For example:

-fir \.[Gg][Ii][Ff]($|\?)/
Important: The dollar sign ($) is a shell metacharacter in Unix. If you are running PerformaSure on a Unix system and want to include the dollar sign as a metacharacter in a regular expression, surround the expression with single quotes. For example:
-fir \.[Gg][Ii][Ff]($|\?)/
You can specify multiple -fir entries for a single nexusctl command, but be aware that the order of the entries is significant. PerformaSure will interpret this order as an indication of matching priority. -fil expression Filters requests for inclusion using literal expressions. For example:
-fil .JPG
You can specify multiple -fil entries for a single nexusctl command, but be aware that the order of the entries is significant. PerformaSure will interpret this order as an indication of matching priority. -fxr expression Filters requests for exclusion using regular expressions. You can specify multiple -fxr entries for a single nexusctl
command, but be aware that the order of the entries is significant. PerformaSure will interpret this order as an indication of matching priority. -fxl expression Filters requests for exclusion using literal expressions. You can specify multiple -fxl entries for a single nexusctl command, but be aware that the order of the entries is significant. PerformaSure will interpret this order as an indication of matching priority. Tip: Surround the expressions that you use to filter requests with quotation marks to protect from shell escape confusion.
-ia Includes all other requests. -xa Excludes all other requests. Note: If you do not specify either -ia or -xa, -ia will be applied by default. Only one of either -ia or -xa can be used, not both.
Connection Parameters
-r URI Set the connection URI for a remote Nexus. For example: -r your.remote.host.com:42705
Recording Settings File

-o /path/to/filename.ext Loads nexusctl settings that you have saved
to a file. Rather than having to specify a long list of options every time you want to record, you can enter the flags into a text file that specifies recording settings. An example path string is:
nexusctl start-recording -o /usr/performasure/nexusctloptions.txt
A recording settings file should consist of one flag per line; two entries cannot exist on the same line. Tip: Surround path strings with quotation marks to protect from shell escape confusion.
To override a recording settings file:
A recording settings file acts as a base template for nexusctl commands. You
can enter additional options to override this file. For example:

nexusctl start-recording -t 10s -s 100 -srl estore/do product -o usr/performasure/nexusctloptions.txt
Showing Connections to the Nexus
nexusctl show-connections Shows all connections to the Nexus. This command lists all connected servers and Workstation users as well as the status of PerformaSure Agents. Alongside the column in which the Agents are listed is a column that contains entries indicating whether Agents are connected or disconnected. The three parameters listed below are optional. -user Your PerformaSure login username. -pwd Your PerformaSure login password (if you have set oneotherwise omit this parameter). -r Sets the connection URI for a remote Nexus. Example usage: nexusctl show-connections -user lisa -pwd oboe789 -r your.remote.host.com:42705
Note: The list of Agents is sorted so that enabled Agents are listed first and
disabled Agents last. Among the enabled Agents, connected Agents are listed first and disconnected Agents last. Resetting the Agent List
nexusctl reset-agent-list Resets the list of Agents. This command removes the entries for Agents that have been disconnected from the showconnections list so that only currently connected Agents are listed. Issuing the command nexusctl reset-agent-list will internally call showconnections after removing the disconnected Agents so that you can see which Agents remain. The three parameters listed below are optional. -user Your PerformaSure login username. -pwd Your PerformaSure login password (if you have set oneotherwise omit this parameter). -r Sets the connection URI for a remote Nexus. Example usage: nexusctl show-connections -user lisa -pwd oboe789 -r your.remote.host.com:42705
Use this flag when the Nexus is on another machine than the one in which
the nexusctl script is located. Important: The nexusctl script must not be moved from the directory in which it was installed.
Ensuring that the Agents Are Running

Agents run either within an application server or on their own. When running in an application server, the Agent is started first, then it is responsible for starting the application server; see Agent Startup on page 48. See Running A System Agent as a Service on page 51 for information about running a System Agent as a Windows service.
Nexus-Managed Agent Configuration

This section describes how you view and track the status of PerformaSure Agents through the Nexus or through the Workstation. It also details those elements in nexus.config that Agents use as additional information during their configuration. For information about launching Agents, see Agent Startup on page 48. PerformaSure tracks the status of all Agents that have connected to the Nexus throughout execution of the Nexus and between exectutions. When the Nexus starts, it will provide information about the status of any Agents that had connected previously. When new Agents connect, the Nexus tracks the status of those Agents for the duration of its execution and between executions. Through the Workstation or nexusctl, you can use the Nexus to enable or disable Agents when you begin recording. If an Agent connects to the Nexus for the first time during recording, that Agent is enabled by default. When an Agent is initialized, it attempts to communicate with the Nexus. If it is successful, as part of its registration process it sends information to the Nexus about which type of Agent it is. The Agent sends a string identifying itself to the Nexus that contains, for example, AgentType=weblogic. ApplicationVersion=6.0. The Nexus scans the files in config\client\agent-type\ for a match to this information. Using the same example, the Nexus would match this information with config\client\agent-type\weblogic-61.config.
Viewing Agent Status Information

The Nexus provides information about PerformaSure Agents (ID, name, type, and connected state) to the Workstation. Before applying load or starting to record a session, you can view the status of Agents in the Workstation or through nexusctl show-connections.
To ensure that the desired Agents are operatingWorkstation instructions:
1. 2.
Open the Recording Control window and check the list of Agents. Ensure that the Enabled checkbox is checked and that the State column lists connected in the row corresponding to each desired Agent.
To ensure that the desired Agents are operatingnexusctl instructions:

1.
Open a command shell, navigate to the PerformaSure home directory, then to the scripts subdirectory, and issue the command:
nexusctl show-connections
Tip: If you have PerformaSure installed on several servers in a cluster, use the Recording Control window or nexusctl show-connections to view the status of Agents and enable or disable certain Agents. By doing so, you can collect performance information more selectively. Naming Agents Normally, Agents are given a unique default name. This is the case even when there are multiple instances of an application server running simultaneously on the same machine, and therefore multiple Agents. Each is given a distinguishing name. You can change an Agents name if you wish by using the AgentName element in agent.config. Important: If two or more Agents anywhere within the monitored environment have the same name, the Nexus will not prevent Agents with duplicated names from connecting. However, it will append numeric identifiers to duplicated Agent names.
Agent Startup
1.
Agents are launched in a variety of ways. System and Service Request Agents usually are started in the following ways: Using a custom startup script for JBoss, which automatically starts a JBoss Service Request Agent.
Using a custom startup script for Tomcat, which automatically starts a
Tomcat Service Request Agent.

An Oracle Application Server Service Request Agent is launched by Oracle
Enterprise Manager after you have integrated Oracle 9iAS or Oracle 10g with PerformaSure. Using a custom startup script for WebLogic, which automatically starts a WebLogic Service Request Agent. Using PerformaSures Integration Manager for WebSphere. This command-line tool facilitates the configuration of WebSphere to work with PerformaSure and assists you in setting the parameters required for the integration of PerformaSure and WebSphere. It is located in PerformaSures scripts subdirectory. On your load simulator or RDBMS machines, the stand-alone System Agents are started using an executablesystemagent (Unix) or systemagent.exe (Windows)on each machine that requires instrumentation. A System Agent is not started automatically on the machine that hosts the Nexus. You have to edit LaunchNexusSystemAgent in nexus.config to enable a System Agent on the Nexus machine. See the note in nexus.config for instructions. All application server and web server machines require System Agents; the Nexus will automatically tell the Service Request Agents on each of these machines to start a System Agent. It is recommended that you place System Agents on your load generator machine as well. The iPlanet Service Request Agent is launched by iPlanet when it starts. As it starts, it reads a specially-modified obj.conf file that instructs it to use the PerformaSure-iPlanet.dll.
Important: System Agents are the only Agents responsible for collecting operating system metrics and network metrics. The Nexus ensures that a single System Agent is started on each machine where Service Request Agents (Web Server Agents and/or Application Server Agents) exist and where a System Agent is required. If multiple System Agents are started on a single machine, the Nexus ensures that duplicate System Agents are shut down. For debugging or other situations, Web Server Agents and Application Server Agents can be configured to ignore the Nexus command to start a System Agent. See the Installation and Configuration Guide for configuration details.
2.
The Agent loads the file agent.config, which includes information on how to connect to the Nexus. You may need to edit agent.config to set the location of the Nexus in your environment. The Agent sends an authentication request to the Nexus. If there is an authentication problem, an error message is written to the Nexus and Agent consoles and to the log files. Consult the error messages in the Nexus log file
3.
and in the Agent log files to see what went wrong. If the Agent cannot connect to the Nexus, it retries the connection periodically. The pause between retries is set in NexusRetryInterval in the agent.config file. A disconnected Agent has no performance impact.
4.
The Nexus checks the license number for the Agent and responds with the message, Authentication approved. The Agent sends a message indicating that it acknowledges the Nexus authentication approval. The Agent asks the Nexus to send the configuration file appropriate for the type of Agent (for example, the WebLogic 6.1 Agent requests agenttype/weblogic-61.config) and waits for a reply. The Nexus searches the files in <performasure_home>/config/client for a match and sends the result to the Agent. The Agent saves the result locally in <performasure_home>/state/<userID>/config-cache. This file contains a list of plug-ins that determine how the Agent collects performance data, which should not be changed. The Agent asks the Nexus to send the file instrumentation.config, which determines how Java applications are instrumented. The Agent also saves this locally in <performasure_home>/state/<userID>/config-cache. If, when it starts, an Agent cannot connect to the Nexus, it tries to load these two configuration files from <performasure_home>/state/<userID>/config-cache. If these files cannot be loaded from <performasure_home>/state/<userID>/config-cache, the Agent finally tries to load them locally from <performasure_home>/config/client. If the Nexus becomes available later on, the Agent does not reload these two files because some properties can only be set at startup time. If these two configuration files have been changed on the Nexus, the Agent must be restarted and be able to connect to the Nexus for it to be properly configured.
5.
6.
7.
8.
Note:
Caution: The <performasure_home>/state directory does not contain any user-editable files. Do not edit any of the files in the /state directory or in any of its subdirectories. See Configuration Lookup Sequence on page 426 for more information.
Running A System Agent as a Service

You can install and run a System Agent as a Windows service; see the Installation and Configuration Guide for installation instructions. By default, this services startup type is set to automatic. Use Services (Start > Control Panel > Administrative Tools > Services) to start, stop, configure, and view the properties of the PerformaSure Systemagent service.
Starting the Workstation

The Workstation: Your Window on PerformaSure
The Workstation performs two distinct functions. It permits you to record new sessions and it is your view on the data that has been collected during any one of these performance tests. A test run may have taken minutes, hours, or even days. Once you have amassed this data, you must sift through it to find signs of a performance bottleneck or perhaps many performance bottlenecks. PerformaSures job is to help you track them down with the aid of the GUI-based analysis tools. The principal views are a Project window and a series of problem investigation windows called browsers that help you to analyze the behavior of your system. The names of PerformaSures browsers are: Metrics, Network Traffic, Request Time, Request Tree, SQL and Thresholds. You can have multiple versions of all of these browsers open simultaneously. For more details about these browsers and their features, see Using the Browsers on page 90. As you become a practiced user of PerformaSure, you will create Projects and configure them based on your experience. Initially, you can use one of the default Projects and begin your search with the Request Time browser, then from there progress to the other browsers as you search for problem areas in your distributed application. You will almost always use the Workstation to invoke PerformaSures functionality. The exceptions to this general rule are:
Installing and configuring PerformaSure, which must be done before being able to use the Workstation. See the Installation and Configuration Guide for detailed instructions. Setting properties in nexus.config, an operation that requires restarting the Nexus and its Agents.
Using nexusctl.sh or nexusctl.cmd to perform tasks like starting the Nexus from a script, retrieving the build and version number of the Nexus, showing connections to the Nexus, recording sessions, and configuring recording settings. See Using nexusctl on page 40 for details.
Using the Workstation

The tasks that you can perform in the Workstation include:
Defining the location of the Nexus that you are about to use. See Define Nexus DialogQuick Start on page 56 for more information. Logging in to PerformaSure, so you can have access to the rest of its functions. See Logging InQuick Start on page 52 for instructions on how to log in. Managing your account or that of other users (if you have administrator privileges). See User Management on page 149 for details. Recording a session. See Recording a Session on page 59 for more information. Viewing the status of a session. See Status on page 181 for details. Opening an existing session to begin an investigation, using the Project window to organize your work, and using the browsers to find problem areas in your application. See Analyzing Sessions on page 83 for more information. Launching Spotlight to check the entire application server or to detect database problems. See Spotlight Integration on page 131 for more information. Launching SQLab Vision for Oracle or SQL Tuning for DB2 to improve database performance. See Integration with Quest Database Tools on page 131 for more information.
Logging InQuick Start

There are three windows in the startup sequence. 1. PerformaSure Workstation Splash Screen When you launch PerformaSure, a Splash screen appears. A progress meter indicates that the application is loading.
Figure 10
Figure 10
The splash screen for the PerformaSure Workstation
2. PerformaSure Login Window To run the Workstation, you must first successfully log in using the password assigned to you by your system administrator. If you do not specify a password, PerformaSure will assume that an empty password is associated with your username. Passwords are sent to the Nexus in encrypted format for user authentication. When you log in to the Workstation, you also need to choose the location of the Nexus that you would like to use for this session.
Figure 11
Figure 11
Login window for the Workstation
Enter your user name and password in the User Name and Password fields, then use the Nexus drop-down menu to select a Nexus instance, or click on the Define... button to create or modify an instance that does not appear in the list. See Define Nexus DialogQuick Start on page 56 for more information. Once you have entered all the information, click Login. If you click Exit, you will close PerformaSure. See Login Errors on page 141 for a description of login errors that you might encounter.
Note:
You must have administrator privileges to add user names to the login database.
3. Startup Window Navigating the PerformaSure Workstation Startup window is the last step in the startup sequence. From this window, select the button that corresponds to your needs.
Figure 12
Figure 12
PerformaSure Startup window showing the Tools menu choices
Record New Session Select this radio button and click OK to open the Recording Control window. See Recording Control Window on page 179 for details about the fields and controls available in this window and for information about using the Recording Settings dialog and the Advanced Sampling dialog. Open Recent Project Recent Projects are listed in the text area directly below the Open Recent Project button. Select this button and a recent Project and then click OK to open a Project from the most-recently-used list. Open Existing Project Select the Open Existing Project button and then click OK to display the Open file chooser. Open Session in New Project Select the Open Session in New Project button and then click OK to launch the New Project Wizard. Opening a session in a new Project causes a session file to be read. The following alert appears while the session file is being scanned:
Figure 13
Figure 13
This alert appears while the session file is loading
The Project window appears once you have opened a Project by following one of these steps. The general form of a PerformaSure Project is shown in Figure 14. See The Project Window on page 159 for more details.
Figure 14
Figure 14
The Project window
The main part of the project window is described in Browsers Area on page 172. Tools menu The Tools menu is located at the bottom of the Startup window (see Figure 12). This menu contains five options:
Session Management... Opens a dialog where you can edit or delete a session. See Session Management Dialog on page 151 for details.
Change Password... Opens a dialog where users can change their own passwords.
Figure 15
Figure 15
The Change Password dialog
User Administration... Opens a dialog where you can add new users and assign passwords. Only the Admin user has access to this choice. See User Management on page 149 for more information about the User Management dialog. Performance Diagnostics Displays a submenu with two options: Spotlight on WebSphere and Spotlight on WebLogic Server. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select one of these options, Spotlight is launched to check the entire application server. Logout Returns to the login screen.
To exit PerformaSure without selecting any of these options, click Exit. For more information about selecting a session or an existing project, see Opening Large Session Files on page 85 and Opening an Existing Project on page 146.
Define Nexus DialogQuick Start

The Define Nexus dialog allows you to edit, add, or remove a Nexus instance from your PerformaSure Project. You can access it by clicking Define in the Login window (Figure 11). See Define Nexus Dialog on page 142 for more details.
Figure 16
Figure 16
The Define Nexus dialog
Edit Nexus Dialog The Edit Nexus dialog is launched when you click Edit... in the Define Nexus dialog. It allows you to change the properties of an existing Nexus instance.
Figure 17
Figure 17
The Edit Nexus dialog
The fields that you can edit in this dialog are listed below. Alias Contains the display name of the Nexus you are editing. This is the name by which the Nexus is known in the Define Nexus dialog. Address The IP address for the machine hosting the Nexus. Port The port on which this Nexus listens. Add Nexus Dialog The Add Nexus dialog is launched when you click Add... in the Define Nexus dialog. It allows you to define properties for a new Nexus instance.
Figure 18
Figure 18
The Add Nexus dialog
The fields that you can edit in this dialog are listed below.
Alias When you launch the Add Nexus dialog, this field contains a default name such as Nexus 1. You can edit this field to specify a new display name for the Nexus; this is the name by which the Nexus is known in the Define Nexus dialog. Address The IP address for the machine hosting the Nexus. Port The port on which this Nexus listens. For more information about using the Workstation to perform tasks like logging in and managing sessions and users, see PerformaSure Workstation on page 139.
Chapter 3
Recording a Session
The following topics are discussed in this chapter:
Recording a Session Poor Performance Culprits Recording Levels Including and Excluding Classes How the Nexus Categorizes Service Requests Load Levels Service Request Sampling Service Request Separation Service Request Filtering Session Acquisition Acquiring a Session ConfigurationOverview Load Testing Collecting Your First Session Recording a Session FAQ
Recording a Session
This chapter offers suggestions about planning a session based on the J2EE performance investigation strategy of Detect, Diagnose, Resolve. It discusses PerformaSures recording levels and outlines parameters and recording settings that affect data collection. This chapter also discusses how to record a session so that the diagnosis phase is most likely to expose a problem in a way that is easily detectable. The next chapter, Analyzing Sessions, discusses ways of analyzing a
59
PerformaSure sessionthe diagnosis phase. Resolution of the problem can take many forms depending on its source.
Poor Performance Culprits

The majority of poor performance in J2EE applications can be traced to:
Applications that dont scale excessive RMI-based invocations that access individual EJB attributes. RDBMS interaction excessive or inefficient SQL statements. Application server configuration insufficient database connections, incorrect thread pools, and incorrect cache sizes.
Effective diagnosis demands that you have a complete, end-to-end view of the application and the interaction pathways. This includes a true method-level service request execution path over your distributed environment and the ability to tie metrics from the underlying J2EE stack back to your application, so that machine loading can be correlated to application server activity. PerformaSures recording capabilities and its set of rich GUI views provide you with the powerful J2EE performance diagnosis tools you need. PerformaSure instruments your application, tagging key elements such as system load parameters, database queries, Java method invocations by J2EE components, RMI calls, and more, so that it can monitor a test run that you have defined, perhaps through the use of a load-testing tool. The test session provides you with raw data that is organized and analyzed in the Nexus for display by the Workstation. Because the display is request-oriented, performance problems may be related to specific use-case scenarios.
General Guidelines for J2EE Performance Testing:

Test early and often. Take a case-centric investigative approach. Create a realistic model of user behavior and emulate it with a load-testing tool. Increase the load systematically: Single machine, single request Single machine, incremental load Clustered machines, low load scenario Clustered machines, high load scenario Use a pre-production QA environment for testing the complete system.
Collect System Metrics to know the load on the Operating system Java runtime environment J2EE application server Database machine Collect Application Server Metrics to know the servers Responsiveness Capacity: number of concurrent users Throughput in user sessions per unit time Time-consuming service requests and methods
Recording Levels
In general, there is no upper limit to the number of classes and methods in a J2EE application. As a result, request trees can, and frequently do, contain thousands of nodes. This information may be invaluable during the QA phase of product development, but collecting it places a heavy load on the system. For production systems, a less intrusive solution is required. Fortunately, J2EE applications have well-defined interfaces that provide natural points at which to focus the collection of performance data. Collecting data at these points has the benefit of reducing the amount of data collectedand hence the overhead. It also provides you with an architectural view of each service request; this high-level view can highlight problems that may not be as evident using the view that results from full instrumentation. The term used to describe this recording level is component detail. PerformaSure defines a default set of interfaces and classes for this level. The other recording level (full instrumentation) is called full detail. When you record a session at this detail level, PerformaSure collects overall timing information and detailed statistics on all classes and methods involved in processing a service request. PerformaSure also offers an intermediate solution that allows you to include other parts of your application in the high-level view while imposing less overhead than recording at the full detail level. In addition to implementing Servlet, JSP, EJB, and JDBC component-level recording, PerformaSure can extend the componentlevel view to include custom components. See Custom Component Instrumentation on page 63 for instructions on using this approach. See Component Instrumentation on page 433 for a list of packages and classes that are included in PerformaSures concept of its component-only view of J2EE resources.
Recording a Session 61
Component or Full Detail?

PerformaSure can run in a production environment or in a pre-production test environment. In a production environment, overhead must be as low as possible. One way of reducing the Tag and Follow overhead in PerformaSure is to collect less data for each service request. Since the performance overhead of Tag and Follow is directly proportional to the number of called methods on which performance data is collected, choosing a smaller set of methods on which to collect performance data can significantly reduce overhead. Choosing a select few of these methodsby recording at the component level or by extending the component level to include custom componentsensures that the number of instrumented points is limited. Component detail is PerformaSures default recording level. Its a good idea to begin a new investigation by recording a session at this level. After obtaining a high-level view of your application, you can switch to full detail and collect another session. With it, you can drill down to the root cause while being guided by the component level view. You can change the recording level in the Sampling tab of the Recording Settings dialog or by using the command-line utility nexusctl. See Standard ComponentLevel Instrumentation on page 62 and Full Detail Recording Level on page 64 for more information.
Component-Level Instrumentation
Standard Component-Level Instrumentation There are two ways of recording a session with component-level detail: by selecting Component Detail Recording Level in the Sampling tab of the Workstations Recording Settings dialog or by entering the nexusctl command nexusctl start-recording -c.
To set the recording level to component detailWorkstation instructions:
1.
Open the Recording Control window by selecting Record New Session from the PerformaSure Startup window and then clicking OK. You can also open the Recording Control window by clicking its icon in the Project windows toolbar or by selecting Tools > Recording Control Window from the menu bar of the Project window or any browser. Click the Settings... button in the Recording Control window. The Recording Settings dialog will appear. Click on the Sampling tab. Select Component Detail Recording Level and click OK.
2.
3. 4.
To set the recording level to component detailnexusctl instructions:

1.
When you are ready to record a new session, enter the command nexusctl start-recording -c. PerformaSure will record a new session at the component detail level. Component detail is the default recording level.
Custom Component Instrumentation Editing the configuration section CustomComponents in <performasure_home>/config/client/instrumentation.config allows you to extend the default set of J2EE components that are included when you record a session at the component detail level. CustomComponents also sets the default behavior if none of the conditions are met to include or exclude a node. Tip: Use custom component instrumentation when your distributed application uses third-party technologies that arent part of PerformaSures default list of items, but which you want to be included in the component-only view. Youll only have to edit CustomComponents once to include these technologies.
Note:
A set of common custom components is pre-defined in instrumentation.config. See the instructions in this file for details.
To configure custom componentsWorkstation instructions:

1.
Set the recording level to component detail by following steps 14 above (To set the recording level to component detailWorkstation instructions:). Open <performasure_home>/config/client/instrumentation.config in a text editor and scroll to the bottom of the section on Custom Components. Configure PerformaSure to collect performance data on custom components by editing CustomComponents. Specify the name of each component in a method list, either by entering the name or by forming a regular expression that matches the name or pattern. Enter the include element before each item in the list. For example:
CustomComponents = { "MQSeries": MethodList(include /com\.ibm\.mq\..*/), "TopLink": MethodList(include "oracle.toplink."), "Globex": MethodList( include "com.globex.plan.DominateWorld", include "com.globex.pocket.Sugar", include "com.globex.cypresscreek.HammockHut.sit", ) };
2.
3.
When PerformaSure matches method names to the methods in a list, it interprets them as custom components.
4.
After editing instrumentation.config, ensure that this file is read by restarting the Agents and the instrumented application servers.
To view the methods in the Request Tree browser, follow the steps above and then record a new session. PerformaSure will instrument entry points into the custom components that you specified. See Collecting Your First Session on page 79 for instructions on using the Workstation to record a new session.
To configure custom componentsnexusctl instructions:
1. 2.
Follow steps 24 above. When you are ready to record a new session, enter the command nexusctl start-recording -c. View the methods in the Request Tree browser.
3.
See Customizing Component-Level Data Collection on page 442 for more information about configuring custom components.
Full Detail Recording Level

When you set the recording level to full detail, all classes and methods involved in processing a service request are instrumented unless InstrumentAtComponentLevel is set to false in <performasure_home>/config/client/instrumentation.config. In this case, component detail will be the recording level no matter what the setting is in the Workstation. See Forcing the Component-Only Mode on page 441 for more information. UserClasses lists some packages or classes alongside exclude elements in instrumentation.config. Any packages or classes thus listed will be excluded from instrumentation. See Including and Excluding Classes on page 65 and UserClasses on page 438 for more information. RecursionLimit is set to its default setting (5) in instrumentation.config. In this case, only the method and its first five recursive calls are shown, and a symbol is added to the last node to indicate that more recursive calls were made. To obtain data on each of the recursive calls separately, set RecursionLimit to a number larger than the expected recursion depth. See Recursion Limit below for details. Important: You must restart the Agents and your instrumented application servers after making changes to instrumentation.config. You do not need to restart the Nexus.
To set the recording level to full detailWorkstation instructions:

1.
Follow steps 13 in To set the recording level to component detail Workstation instructions: on page 62. Select Full Detail Recording Level in the Sampling tab of the Recording Settings dialog and click OK.
2.
To set the recording level to full detailnexusctl instructions:

1.
When you are ready to record a new session, enter the command nexusctl start-recording -f. PerformaSure will record a new session at full detail.
Recursion Limit By default, PerformaSure tracks recursive calls five levels deep when recording in full detail.
Figure 19
Figure 19
A recursive call path
The terminal node is marked with the recursion symbol ( ) to denote the fact that there are more calls in the chain that are not shown. If you want to show more or fewer recursive calls, edit RecursionLimit in <performasure_home>/config/client/instrumentation.config. See Setting the Recursion Limit on page 440 for more information.
Including and Excluding Classes

This section discusses ways of modifying the list of classes that PerformaSure includes in its Tag and Follow mechanism.
Choosing Classes for Instrumentation

PerformaSure groups classes into two types: user classes and server classes. It fully instruments user classes and for the most part it ignores server classes. If server classes were included, much more data would be collected and displayed, yet it is doubtful if any of the additional data would be useful to you. Worse, the additional clutter might make it more difficult for you to pick out what would otherwise be an obvious trouble spot. Even some user classes fall into the category of noise, and you might prefer that they were not recorded and displayed. Editing the UserClasses configuration section in <performasure_home>/config/client/instrumentation.config allows you to
specify which classes or entire packages you want to be included for full instrumentation by PerformaSure or excluded from instrumentation. Tip: Configure user classes to exclude a class when it causes excessive load on the Agent or Nexus to instrument it.
To include classes or packages for instrumentation:

1.
Open <performasure_home>/config/client/instrumentation.config in a text editor and scroll to the bottom of the section on User Classes. Edit UserClasses to include certain classes for instrumentation and exclude others. Specify the name of each class in a class list, either by entering the name or by forming a regular expression that matches the name or pattern. Enter the include element before each class in the list. For example:
UserClasses = ClassList( include com.globex.plan.DominateWorld, include com.globex.pocket.Sugar );
2.
As shown in this example, multiple include elements can appear in this configuration section. In this case, both com.globex.plan.DominateWorld and com.globex.pocket.Sugar would be included. Tip: What you enter in the class list is treated as a regular expression. If you want to include a single class, the best approach is to type in the complete, fully-qualified name.
3.
To exclude a class or package from instrumentation:

1.
Open <performasure_home>/config/client/instrumentation.config in a text editor and scroll to the bottom of the section on User Classes. Edit UserClasses to exclude classes from instrumentation. Specify the name of each class in a class list, either by entering the name or by forming a regular expression that matches the name or pattern. Enter the exclude element before each name in the list. For example:
UserClasses = ClassList( exclude com.globex.plan.DominateWorld, exclude com.globex.scheme. );
2.
In this example, the class com.globex.plan.DominateWorld would be excluded, as well as all classes in the package com.globex.scheme. Tip: What you enter in the class list is treated as a regular expression. If you want to exclude a single class, the best approach is to type in the complete, fully-qualified name.
3.
Including and Excluding Multiple Classes Multiple include and exclude elements can appear together in the list of classes, but it is the first element that matches that will control the outcome.
To include and exclude classes:
1.
Open <performasure_home>/config/client/instrumentation.config in a text editor and scroll to the bottom of the section on User Classes. Edit UserClasses to include and exclude classes. Specify the name of each class in a class list, either by entering the name or by forming a regular expression that matches the name or pattern. Enter the include or exclude element before each name in the list. For example:
UserClasses include exclude include ); = ClassList( com.globex.plan.DominateWorld, /(\.|^)globex\./, com.globex.pocket.Sugar
2.
In this case, the class com.globex.plan.DominateWorld would be included, but the class com.globex.pocket.Sugar would actually be excluded since it matched the exclude pattern on the second line. Also, any classes in net.globex. package or the root globex. package would be excluded since they match the regular expression corresponding to the exclude element.
3.
Caution: You must edit the same UserClasses configuration section to both include and exclude classes. Any UserClasses sections in instrumentation.config after the first are ignored.
How the Nexus Categorizes Service Requests

Complete Requests
Complete requests are requests that have been fully reconstructed by the Nexus. In general, all service requests should qualify as complete requests unless an error occurs.
Incomplete Requests
Given the definition of a service request and the fact that a session lasts for a finite time, some requests may not complete within the time during which the session was recorded. An incomplete request is one in which the session ends before the response to the request is recorded. PerformaSure also tracks requests that do not complete within a specified time, called the incomplete request timeout period. The duration of this period can be set in the Session tab of the Recording Settings dialog. See Session Tab on page 186 for more information. Tip: When system throughput is poor, keeping track of incomplete requests helps you to determine which component is to blame.
Unmatched Requests
It is also possible to have unmatched requests. Unmatched requests are service requests whose parts become cut off from each other because some intermediate process fails to complete. These are converted to fragmented requests by PerformaSure. Even when PerformaSure deems a request to have been completed, some parts of it may not have reported back, possibly because that part was being processed by an uninstrumented server. To prevent fragmented data from being confused with good data, fragmented requests are not stored in the session. Instead, they are output to the log file with an explanation and a possible solution. However, a service request still occurred and that information is saved. If the service request type can be identified, the not sampled count of the root node is incremented each time a fragmented request is seen.
Note:
The most probable cause of fragmented requests is that the timeouts set in <performasure_home>/config/nexus.config are too short. When fragmented requests are detected, a warning message appears notifying
you that the timeouts should be increased. See Service Request Timeout Thresholds below for details. Service Request Timeout Thresholds The CommitTimeout configuration section in <performasure_home>/config/nexus.config controls how long, in milliseconds, the Nexus will wait before committing a service request to the session file. For example, the default setting in nexus.config is CommitTimeout = 4000, meaning that the timeout is set to 4 seconds. In effect, this means that you are telling the Nexus that you expect all service requests to take 4 seconds or less to complete. Reconstructing service requests is very memory intensive. By reducing the timeout, the Nexus will wait for a shorter period of time before writing reconstructed transactions to disk, and hence use less memory. If you reduce the value of CommitTimeout to too low a number, however, you risk having fragmented requests. Tip: If you begin to see fragmented requests, try increasing the value of CommitTimeout by 1 second (1000 milliseconds) at a time to ensure that transactions are not written to disk before all of the tag and follow messages have been received.
Important: Always restart the Nexus after editing nexus.config to ensure that this file is read.
Load Levels
The PerformaSure Nexus is designed to resist becoming overloaded. It accomplishes this by automatically switching to sampling mode whenever the number of service requests that enter the system during the sampling interval can potentially overload the Nexus. It sends a message to its Agents instructing them to reduce the number of service requests that will be Tagged and Followed in the next sampling interval. If the Nexus cant keep up even after entering its lowest sampling regime, it sends stop tag and follow messages to its Agents so that it can clear its backlog. The Nexus continues to update its count of non-sampled requests while clearing its backlog. This ensures that all requests are counted and statistical accuracy is maintained. A
small amount of data is collected even for requests that are not sampled. This data still takes time to process, though not nearly as much time as it takes to process the data collected for fully-sampled requests. After the backlog is cleared, the Nexus informs its Agents that they can resume collecting and forwarding data. Requests are sampled based on how much data the Nexus can process: the Nexus asks for as much data as it can handle, but no more. Thus, you may see cases in which the Nexus asks for fewer samples in a certain time period because it had to deal with much more data from requests that were not sampled. Because the Nexus must collect some data from non-sampled requests, it is possible to saturate it at extremely high request rates with non-sampled requests alone. If this happens, you will need to run the Nexus on a more powerful machine. It is possible to instruct the Nexus to sample even fewer requests than the limit it has set for itself by using the controls in the Sampling tab of the Recording Settings dialog or by using nexusctl. This way, you can reduce the overhead PerformaSure places on your system. See Service Request Sampling below for more information. Caution: Both recording a session and analyzing a session can place a heavy load on the Nexus, especially when you are asking the Nexus to collect as many samples as possible. Using the Workstation to analyze data while recording a new session may result in fewer samples being taken.
Service Request Sampling

In performance tests of long duration, or very high load, there is little need to Tag and Follow every service request; a sample of the incoming load is sufficient to determine the source of the performance bottleneck. On the other hand, service requests that arrive infrequently may be among the most important from your applications point of view. PerformaSure makes sure that these infrequent requests are measured, even in low-overhead sampling situations. By default, PerformaSure tracks as many service requests as it can, but you may encounter situations where sampling gives you essentially the same information at much less cost. If the PerformaSure Nexus is unable to keep up with the incoming service requests, it adjusts the sampling rate. You can allow the Nexus to set the sampling rate, or you can adjust the sampling rate yourself. Since every system is different, it will take a bit of experimentation to find the optimum setting.
To configure service request sampling in the Workstation:

1.
Open the Recording Control window by selecting Record New Session from the PerformaSure Startup window and then clicking OK. You can also open the Recording Control window by clicking the Recording Control Window button in the Project windows toolbar or by selecting Tools > Recording Control Window from the menu bar of the Project window or any browser. Click the Settings... button in the Recording Control window. The Recording Settings dialog will appear. Click on the Sampling tab. Select Collect Fewer Samples to Reduce Overhead and adjust the Few Samples ... Many Samples slider. No matter what the setting, PerformaSure reliably samples infrequent requests. Check the rest of the settings in this tab (such as the session time slice size), and if they are what you want, click OK. The Recording Settings dialog will close but the Recording Control window will remain open, allowing you to begin recording when you choose by clicking Record. You can also use the options available in the nexusctl command-line utility to adjust the service request sampling rate. See Sampling Parameters on page 204 for more information.
2.
3. 4.
5.
Note:
Setting Sampling Weights

In sampling mode, PerformaSure Tags and Follows requests in proportion to their invocation frequency. You can override the default sampling weights that PerformaSure assigns to requests. See Advanced Sampling Dialog on page 195 for more information.
Service Request Separation

PerformaSure allows you to use separators to separate requests with the same base URL into separate request types based on the requests query and post parameters. By allowing service request separation, PerformaSure gives you the option of treating each parameter value as if it were a separate request.
Service Request Separation and J2EE MVC Application
Architectures
A popular architectural design pattern at the J2EE presentation level is the Model / View / Controller architecture (used, for example, in the Jakarta Struts framework). One servlet serves as the controller, which delegates requests to Action objects, which in turn respond with the appropriate JSP-based views. By default, PerformaSure treats invocations of this central servlet controller as one service request, whereas the performance investigator would actually treat the application load directed to this central servlet as a series of distinct requests. For example, a retail application that lets users log in, perform queries, and order items might have the following URLs:
http://www.acme.com/controller?cmd=login http://www.acme.com/controller?cmd=query http://www.acme.com/controller?cmd=order
Because the base URL is the same, the default action of PerformaSure is to consider all these invocations as part of the same service request and to amalgamate the information collected for all three URLs into one request tree in the Request Tree browser.
To configure service request separation in the Workstation:
1.
Open the Recording Control window by selecting Record New Session from the PerformaSure Startup window and then clicking OK. You can also open the Recording Control window by clicking the Recording Control Window button in the Project windows toolbar or by selecting Tools > Recording Control Window from the menu bar of the Project window or any browser. Click the Settings... button in the Recording Control window. The Recording Settings dialog will appear. Click on the Separators tab. Adjust the controls found in this tab to configure service request separation. See Separators Tab on page 190 for detailed instructions. Check the rest of the settings in this tab (such as the maximum length of the value used for request separation), and if they are what you want, click OK. The Recording Settings dialog will close but the Recording Control window will remain open, allowing you to begin recording when you choose by clicking Record. You can also use the options available in the nexusctl command-line utility to configure service request separation. See Request Separation Parameters on page 205 for more information.
2.
3. 4.
5.
Note:
Service Request Filtering

Filtering allows you to configure PerformaSure to reduce traffic between Agents and the Nexus, which decreases both overhead and storage requirements. Filtering can be configured to include some requests and exclude others. Regular expression pattern matching is used to determine which requests are included and which are excluded. You can also match requests using literal strings. Many types of requests can safely be ignored once you have determined that they have no costly effects on performance. This category includes image files that are loaded via individual HTTP requests, and other static files whose loading times can be assumed to be constant. After you have measured the request times for these objects and you are satisfied that there are no problems with them, you can use service request filtering to remove them from view. Turning on request filtering doesnt change how your application is processed. The filtered requests are not Tagged, and as a result they do not appear in the session file. Tip: If you have specified request separation on a parameter in the Separators tab, you can filter requests on that parameter in the Filters tab.
To configure service request filtering in the Workstation:

1.
Open the Recording Control window by selecting Record New Session from the PerformaSure Startup window and then clicking OK. You can also open the Recording Control window by clicking the Recording Control Window button in the Project windows toolbar or by selecting Tools > Recording Control Window from the menu bar of the Project window or any browser. Click the Settings... button in the Recording Control window. The Recording Settings dialog will appear. Click on the Filters tab. Adjust the controls found in this tab to configure service request filtering. See Filters Tab on page 193 for detailed instructions. Check the rest of the settings in this tab (such as the drop-down menu that controls whether all other requests are included or excluded), and if they are what you want, click OK. The Recording Settings dialog will close but the Recording Control window will remain open, allowing you to begin recording when you choose by clicking Record.
2.
3. 4.
5.
Note:
You can also use the options available in the nexusctl command-line utility to configure service request filtering. See Filtering Parameters on page 206 for more information.
Session Acquisition
Tag and Follow
A typical session-acquisition flow is illustrated in Figure 20. First, whatever filters you have defined are applied. Next, the non-filtered requests may be arriving at a rate that is rapid enough for the Nexus to switch to its sampling mode. If this is the case, the Service Request Agents are told how many requests of each type they should Tag and Follow during the next sampling interval. If the request arrival rate is low enough, they will all be monitored. Once a service request has passed the filtering and sampling gates, these actions occur:
The request is Tagged upon entry into your PerformaSure-instrumented J2EE environment, The Agents integrated within the elements of your environment emit events to the Nexus as the service request is Followed, then The Nexus reconstructs the full execution path for the service request.
Figure 20
Figure 20
The session acquisition pipeline
Service requests that are Tagged are Followed to completion are aggregated into the time slice in which they complete (see Figure 21) and the data is stored in the session file.
Session Time Slice Size

Service requests that have been Tagged and Followed to completion are aggregated into the time slice in which they complete. The width of the time slice defines the finest granularity of time that you can analyze with PerformaSures browsers.
Figure 21
Figure 21
How service requests are aggregated
A request is associated with a time slice based on when it completes. Thus, in Figure 21, only the requests numbered 1 and 2 completed during the time slice (shown as a grey bar). If the Zonar were shrunk to just this time slice, only requests 1 and 2 would be shown in the browsers. The others would be visible if the Zonar were expanded to include the time slices in which they completed. Setting the Session Time Slice The time slice size is defined in the Session tab of the Recording Control window, and it defines the narrowest time window to which you can drill down during session analysis. For example, if you record a session with the default time slice size (one minute), all events occurring within one minute intervals are assumed to have happened at the same time for presentation purposes. Adjusting the time slice size can be helpful when you are trying to pinpoint transient performance problems by, for example, correlating changes in thread counts and queue lengths with changes in response times.
Guidelines for setting the time slice size:
Use narrow time slice values for relatively short runs (< 10 min) and wide time slice values for relatively long runs (> 10 min). Set narrow time slice values when you want to have more accurate information about when requests end. To determine when they start, subtract the cumulative time (available in the Request Time and Request Tree browsers).
Acquiring a Session
ConfigurationOverview
The Workstations Recording Control window and Recording Settings dialog and certain configuration files allow you to define parameters for the new session that you are about to record. This section describes the parameters, fields, and controls that are available through the Workstation and in certain files in the <performasure_home>/config/ directory and that allow you to adjust basic recording settings. You can also use nexusctl to perform actions like starting and stopping session recording, naming a session, supplying comments about a session, and adjusting recording settings. See Recording Control Window and nexusctl on page 177 for more information about the controls available in the Recording Control window, in the Recording Settings dialog, and through nexusctl.
Recording Control Window

Session Name A default name is supplied, which is a combination of your username and the current date. Its a good idea to change it to a more meaningful name that gives an indication of the reason why the session is being recorded. Comments You can elaborate on the reason why the session is being recorded in the comments field. Record Starts recording a new session. Tip: You can automate session recording by means of the nexusctl command-line utility. See Launching the Nexus from a Script on page 39 for details.
Recording Settings DialogSession Tab

Limit Session Length You can set the duration of the session by selecting the Limit Session Length checkbox and using the editable spin boxes. Alternatively, you can stop recording the session manually using the Stop button in the Recording Control window. Time Slice Size The time slice size can be adjusted using the Time Slice Size drop-down menus. The time slice size determines the granularity of the data in the session. Each time slice contains the requests that have completed during its span. The default time slice is one minute, which means that (for presentation purposes) all events occurring within one minute intervals are assumed to have happened at the same time. If you set a new time slice size, that size is remembered until you change it. When you generate a new session, the time slice size that you set previously is used unless you set it again for the current session.
Recording Settings DialogSampling Tab

Collect as Many Samples as Possible/Collect Fewer Samples to Reduce Overhead By selecting one of these radio buttons, you tell the Nexus to collect as many samples as possible or to collect fewer samples to reduce overhead. Selecting Collect Fewer Samples to Reduce Ovehead enables the Few Samples ... Many Samples slider, which you can use to adjust the number of samples collected. Component Detail Recording Level/Full Detail Recording Level You can collect data on key J2EE components by selecting the Component Detail Recording Level radio button, or you can collect data on all classes and methods involved in processing a service request by selecting the Full Detail Recording Level radio button.
Setting Parameters in agent.config and nexus.config
Important: Always restart the Agents and your instrumented application servers after editing <performasure_home>/config/agent.config. Always restart the Nexus after editing nexus.config. You will also need to restart the Agents and your instrumented application servers after editing AgentListenHost and AgentListenPort in nexus.config. See AgentListenHost and AgentListenPort on page 419 for more information. Host name and port number for the Nexus Before starting the Agents, you must edit NexusHost and NexusPort in <performasure_home>/config/agent.config on each Agent machine to specify the host name and port number of the machine hosting the Nexus. See the Installation and Configuration Guide for details. Location of the session file The default location of all session files in PerformaSures sessions subdirectory (<performasure_home>/sessions). To change the location where the Nexus stores sessions, edit SessionDirectory in nexus.config. If you supply a relative pathname, it is relative to PerformaSures home directory. Important: The sessions subdirectory, where the Nexus stores the data reported by PerformaSure Agents, must be on a local drive. The Nexus cannot be run from a network mounted drive using protocols such as NFS (Network Filesystem) or SMB (Server Message Block). Timeouts You can change the default setting of various timeouts by editing <performasure_home>/config/agent.config and <performasure_home>/config/nexus.config and by adjusting the settings in the Session tab of the Recording Settings dialog. See Setting the Authentication Timeout on page 414, Changing the Commit Timeout Setting on page 422, and Incomplete Request Timeout on page 187 for details.
Setting Parameters in log.config

General operational information, warnings and errors encountered by the Nexus and its Agents are written to log files. In <performasure_home>/config/log.config, you
can configure properties like the level at which messages are logged, the language in which they are displayed, and the places where the logs appear. See The Parameters in log.config on page 427 and the instructions in log.config for more information. Important: You must restart the Nexus, the Agents, and your instrumented application servers after editing log.config.
Load Testing
PerformaSure works well with load-testing tools like Quest Benchmark Factory and Mercury Interactive LoadRunner. These tools can be used to provide a model of system behavior and performance by emulating users on your system. See Interaction with Load-Testing Tools on page 35 for more information about how PerformaSure interacts with load-testing tools. Consult your load-testing tools manuals for product-specific details about installation, configuration, and use.
Collecting Your First Session

Factors That Affect the Size of a Session File
A number of factors affect the size of a session file. For example, there is a direct relationship between the length of time over which the session was recorded and the size of the session file. The following table lists factors that affect the size of a session file:
Factor Session duration Time slice size Recording level Request mixture Code complexity Larger session Long Small Full detail Many different kinds Complex Smaller session Short Large Component detail Few request types Simple
If it is your first time using PerformaSure, its better to start with a smaller session before using all of PerformaSures capabilities to conduct an in-depth performance investigation. These suggestions will help you collect a comfortablysized initial session:

Use a time slice of 1 minute or greater. Begin by recording at the component detail level. Only switch to the full detail level once success has been achieved recording at the component detail level. On WebSphere, set the PMI level to High or lower. On WebSphere, do not use the JVMPI option (-XrunpmiJvmpiProfiler). Minimize the number of application server metrics being gathered. Arrange your load-testing scenario so that your application server is not heavily loaded.
Tip: Before recording a session from a system under heavy load, consult the detailed information on request separation, filtering, and sampling in the chapter Recording Control Window and nexusctl on page 177.
Pre-Recording Checklist Before you start recording, ensure that:
The Nexus is running. See Starting the Nexus on page 39 for more information. You have specified the correct host name and port number for the Nexus in <performasure_home>/config/agent.config. See Host name and port number for the Nexus on page 78 for more information. The Agents are running. See Ensuring that the Agents Are Running on page 47 for more information. The Workstation is running and you are logged in (if you want to use the Workstation to record a session). See Logging InQuick Start on page 52 for instructions on logging in to the Workstation. You can also use the options available in the nexusctl command-line utility to record a session. See Recording with nexusctl on page 198 for more information.
To record a new sessionWorkstation instructions:

1.
Once you have logged in to the Workstation, select Record New Session from the PerformaSure Startup window. Click OK. The Recording Control Window will appear. Choose an appropriate name for your session in the Name field. Enter comments about why you are recording the session in the Comments field.
2. 3. 4.
5.
Click the Settings... button. The Recording Settings dialog should open to the Session tab. In the Session tab, make sure that Time Slice Size is set to 1 minute (the default setting). If you want to limit the duration of the session, check the Limit Session Length checkbox and set the session length in hours, minutes, and seconds using the editable spin boxes. Click on the Sampling tab. Make sure that the Component Detail Recording Level radio button is selected. Click OK. The Recording Settings dialog will close, leaving the Recording Control window open. Make sure that the Open Session When Recording Completes checkbox is checked.
6.
7.
8.
9.
10. Press Record. 11. Send requests to your instrumented application server. 12. If you have not set the duration of the session in the Recording Settings dialog,
click Stop when you want to stop recording. A new PerformaSure Project window and Request Time browser will open, allowing you to begin analyzing your new session right away.
Note:
You can also record a new session using nexusctl. See Recording with nexusctl on page 198 for more information.
Recording a Session FAQ

What request rate can the Nexus handle? A Nexus residing on a one-processor, midrange commodity machine should be able to handle 200 or more requests per minute. The actual number may be much higher. How do I change the directory in which session files are stored? You can change the directory where you place your session files, but you will have to edit SessionDirectory in nexus.config so that PerformaSure knows where to find the files. See Location of the session file on page 78 for more information.
Chapter 4
Analyzing Sessions
This chapter discusses a methodology for analyzing the data that you collected using PerformaSure and provides instructions for using the Project window, the Time Control panel, and the browsers. The following topics are covered in this chapter:

Methodology Navigating the Project Window Using the Browsers Using the Time Control Panel Integration with the Quest Software Suite for Further Analysis Analyzing Sessions FAQ
Methodology
This section presents general recommendations to help you get started as you begin analyzing sessions. For more detailed information about analyzing sessions in the PerformaSure Workstation, see Navigating the Project Window on page 85 and Using the Browsers on page 90. See Integration with the Quest Software Suite for Further Analysis on page 127 for information about integrating PerformaSure with JProbe, Foglight, Spotlight, and Quest database tools. The guidelines in this section have been developed based on the assumption that you just completed recording a session by following the instructions in the previous chapter, Recording a Session. If this is not the case, before you proceed, ensure that:
83
The Nexus is running. See Starting the Nexus on page 39 for more information. The Workstation is running and you are logged in. See Logging InQuick Start on page 52 for login instructions. You have collected session data. See Collecting Your First Session on page 79 for instructions. You have opened a session in a new PerformaSure Project. To do so: 1. Select Open Session in New Project from the PerformaSure Startup window and click OK. The New Project Wizard will open. 2. Choose a session from the list and click OK. For more information about the fields and controls in the New Project Wizard, see New Project Wizard on page 156. You can open sessions recorded with version 3.0 of PerformaSure and convert sessions recorded using version 2.0, 2.1, 2.2, or 2.3 for use with PerformaSure 3.5, but sessions recorded using version 1.1, 1.5, 1.6, or 1.7 of PerformaSure are obsolete and cannot be converted. The error dialog shown in Figure 22 will appear if you attempt to open an obsolete session. See Converting a Session on page 148 for more information.
Figure 22
Note:
Figure 22
This dialog appears if you attempt to open or convert an obsolete session
General Guidelines for Analyzing a Session

Because each persons methodology for tracking down performance problems is unique, you may want to follow a different sequence than the one outlined here. However, it is suggested that you begin by following these steps while developing your own preferred approach: 1. Select the session that you want to analyze and open it in a new PerformaSure Project. When you open a new Project based on the Default template, the Request Time browser opens automatically. This browser is a good place to begin your performance investigation by identifying the service requests that are taking the most time. See Request Time Browser on page 225 for detailed information about this browser. 2. Switch to the SQL browser. This browser allows you to take a high-level view of the SQL statements used in your J2EE application and investigate their overall performance. See SQL Browser on page 257 for detailed information about this browser. 3. Investigate the time-consuming requests that you identified using the Request Time browser by opening the Request Tree browser. In it, time84 PerformaSure: Users Guide
consuming methods are highlighted in a hot color. By knowing which methods contribute to long request times, you can concentrate your optimization efforts on them. See Request Tree Browser on page 283 for detailed information about this browser. 4. Open the Network Traffic browser to check for unusually large amounts of network traffic, or unbalanced traffic within clustered machines. See Network Traffic Browser on page 357 for detailed information about this browser. 5. Open the Metrics and Thresholds browsers to get a picture of how the various system metrics correlate with service request processing. A request that is taking a long time might be caused by the overuse of some resource, such as the CPUs, the Java heap size, the size of connection pools or other cache parameters. PerformaSure allows you to correlate these metrics with request metrics. See Metrics Browser on page 335 and Thresholds Browser on page 375 for detailed information about these browsers.
Navigating the Project Window

Opening Large Session Files
If a recorded session becomes too large, an attempt to open it for viewing in the Workstation may cause an Out of Memory error in the Java runtime. This may occur because it requires more memory than is initially allocated to the Java heap. This situation can be addressed by increasing the size of the Java heap.
To increase the amount of memory needed to open large sessions in the Project window:
1.
Note the size of the session file in MB and add 128 MB. For example, if the session file is 500 MB, the size parameter is 628 MB. Unix or Windows: Launch the Nexus from a command file or script that passes the size parameter to increase the heap size. For example, for a 500 MB session file, you would enter nexus -Xmx628m. Windows: Launch the Workstation from a DOS console or command file that passes a size parameter to increase the heap size. For example:
workstation -Xmx512m
2.
3.
Unix: Edit the file <performasure_home>/bin/workstation.lax to change the memory option setting. Example:
lax.nl.java.option.additional=-Xms128m -Xmx512m -Dperformasure.debug=0
Analyzing Sessions 85
The size parameter for the Workstation is not directly related to the size of the session. It is a function of the size, but it depends more directly on the size and complexity of the request trees that are stored in the session.
Selecting Another Project or Session

Once you have a Project window open, you have the option of opening another Project or opening another session in a new Project.
To open an existing Project:
1.
Select Project > Open Project... from the menu bar to launch the Open file chooser. From the list of PerformaSure Project files (files with the .sure extension), double-click on a file or select one and then click Open.
2.
To open a session in a new Project:

1.
Click the Open Session in New Project button in the Project windows toolbar or select Project > Open Session in New Project... from the menu bar to launch the New Project Wizard. Select a session from the Choose session list. In the details area, information about the selected session will appear in the following fields: Session Name, Version, Created by, Start date, End date, Length, Time slice, and Detail level. See Details Area on page 158 for more information about these fields. Select a template from the Template drop-down menu. If you do not select a template, the new Project will automatically use either the Default template or the template that was last selected from this menu. See Template on page 159 for more information about Project templates. Click OK. The Project window appears. At this point, the Project has not been saved. Select Project > Save Project or Project > Save Project As... to launch the Save file chooser. If you do not supply an extension for the Project filename, the extension .sure is automatically appended.
2. 3.
4.
5.
Customizing the Project Window

PerformaSures Project window is the control panel for your Project. This window is highly configurable: you can select the browsers that give the best indication of
underperformance in your system and add them to the Project; organize browsers into folders in the navigation pane of the Project windows Browsers area; and add comments to browsers, folders, and the Project as a whole that can be displayed in the details pane.
Figure 23
Figure 23 A Project window: browser icons have been organized into named folders and comments have been added to the Project
Adding Browsers
When you create a new Project using the Default template, the navigation pane contains a Request Time browser that opens automatically, giving you a starting point for your investigation. You can add as many other browsers of each type as you want to your Project and adjust their settings to focus on the performance problems that you have discovered. When you save the Project, browser settings are also saved. The next time you open this Project, the browsers that you added to it are ready to be used again.
To add a browser to your Project:

1.
Click the left-hand side of the New Browser... button in the Project windows toolbar or select Project > New Browser... from the menu bar. The New Browser dialog will open. Select the type of browser that you want from the Browser Type drop-down menu. The other fields and controls in this dialog allow you to assign a name to the browser, add comments to it, or configure it to open automatically when you open the Project. Click OK. The dialog will close and a new browser of the type you selected will open. Click the Add New Browser to Project button in the browsers toolbar or select Browser > Add New Browser To Project from the menu bar. The browser will be added to your Project and an icon for this browser will appear at the bottom of the navigation pane in the Browsers area of the Project window. From the Project window, click the Save Project button in the toolbar or select Project > Save Project from the menu bar. If it is your first time saving this Project, the Save file chooser will open. Provide a descriptive name for your Project in the File Name field and click Save. To open a new browser, you can also click the right-hand side of the New Browser... button to display a drop-down menu from which you can choose the type of browser that you want. Select one of the options in this menu to cause a new browser of that type to open automatically. You can then follow steps 4 and 5 above to add it to your Project.
2.
3.
4.
5.
Note:
Organizing the Navigation Pane

Every time you add a browser to your Project, a browser icon for that type of browser appears in the navigation pane of the Browsers area. You can organize the contents of the navigation pane into folders (see Figure 23). To add folders to this pane, select Project > New Folder... from the menu bar. Tip: Organize browsers into folders according to the type of analysis for which you are using that set of browsers. Provide a name for each folder that identifies the investigative tasks for which you will use the browsers in that folder. See Figure 23 for examples of folder names.
Adding Comments
You can add comments to the Project, to a folder, or to a browser using the Properties dialogs available from the Project window. The comments added to a folder or to a browser appear in the details pane when that folder or browser is selected. When no items are selected, the details pane displays information and comments about the Project (see Figure 23).
To add comments to a Project:
1.
Select Project > Project Properties... from the menu bar. The Project Properties dialog will open. Add comments to the Project. For example, your comments might explain why the data was collected or suggest what may be causing the observed behavior. Click OK to save your comments and close the dialog. From the Project window, click the Save Project button in the toolbar or select Project > Save Project from the menu bar. If it is your first time saving this Project, the Save dialog will open. Provide a descriptive name for your Project in the File Name field and click Save.
2.
3. 4.
To add comments to a folder:

1.
Select the folder and click the Properties button in the toolbar or rightclick the folder icon and select Edit Properties... from the contextual menu that appears. The Folder Properties dialog will open. Add comments to the folder. For example, your comments might describe the types of browsers that you put in this folder or the performance problems that they helped you discover. Click OK to save your comments and close the dialog. From the Project window, click the Save Project button in the toolbar or select Project > Save Project from the menu bar. If it is your first time saving this Project, the Save dialog will open. Provide a descriptive name for your Project in the File Name field and click Save.
2.
3. 4.
To add comments to a browser:

1.
Select the browser and click the Properties button in the toolbar or rightclick the browser icon and name and select Edit Properties.. from the contextual menu that appears. The Browser Properties dialog will open.
2.
Add comments to the browser. For example, your comments might describe the performance problems that you expect to isolate using this browser. Click OK to save your comments and close the dialog. From the Project window, click the Save Project button in the toolbar or select Project > Save Project from the menu bar. If it is your first time saving this Project, the Save dialog will open. Provide a descriptive name for your Project in the File Name field and click Save. You can also access the Browser Properties dialog from individual browsers. Click the Properties button in a browsers toolbar or select Browser > Properties... from its menu bar to launch the Browser Properties dialog.
3. 4.
Note:
Tip: To name or rename a folder or browser, follow the instructions above for adding comments to a folder or browser. When you have opened the appropriate Properties dialog, simply edit the Folder Name or Browser Name field and click OK.
Using the Browsers

PerformaSure has six browsers: Metrics, Network Traffic, Request Time, Request Tree, SQL and Thresholds. You can have multiple versions of all of these browsers open simultaneously. PerformaSures browsers give you detailed information about the minimum, average, and maximum times for platform and system metrics and about the time your application takes to process requests. Although the layout of each browser is different, all six browsers do have common features, such as the menu bar, the toolbar, and the Time Control panel. The Time Control panel is identical in all PerformaSure browsers, but the controls available in the menu bar and the toolbar vary significantly from browser to browser. This section describes what PerformaSures browsers do and how they can help you analyze sessions. It also provides basic steps that you can follow to become familiar with the fields and controls in each browser. For detailed information about the browsers and their features, see Section II of this manual.
Customizing the Browsers

Configuring a Browser to Open Automatically
The Default Project template is pre-configured to launch the Request Time browser when you open the Project window, but you can configure any browser that you have added to your Project to open automatically.
1.
Open the browser that you want to configure by double-clicking its icon in the Browsers area. Click the Properties button in the toolbar of that browser or select Browser > Properties... from its menu bar. The Browser Properties dialog will open. Check the Automatically open this browser when project is opened checkbox and click OK. From the Project window, click the Save Project button in the toolbar or select Project > Save Project from the menu bar. If it is your first time saving this Project, the Save dialog will open. Provide a descriptive name for your Project in the File Name field and click Save.
2.
3.
4.
Edit Options Dialog

You can open the Edit Options dialog by selecting Tools > Options... from the menu bar of any browser. This dialog allows you to customize themes and configure certain aspects of your Project, the Request Tree browser, the Metrics browser, and PerformaSure Reports. See Edit Options Dialog on page 215 for more information.
Using the Time Control Panel

The Time Control panel is common to all of the browsers in PerformaSure. It contains controls that allow you to adjust the span of time for which you view session data in a browser.
Figure 24
Figure 24
The Time Control panel
Using the Time Control Panel

Navigating the Timeline The Timeline represents the total period of time during which the session was recorded (see Figure 24). You can select portions of the Timeline with the Zonar. There are major and minor tick marks on the Timeline that correspond to time slice boundaries. Use these tick marks as a guide when positioning the Zonar. Interpreting the Timeline Labels There are several labels on the Timeline. These labels can help you keep track of the total duration of the session, position the Zonar, and understand the exact time span covered by the Zonar.
Figure 25
Figure 25
Timeline labels and the Zonar Offset and Duration label
Session Start Time Label and Session End Time Label The session start time label and the session end time label display the start time and end time for the current session. These labels appear at the far left and far right of the Timeline when the whole Timeline is visible. The time is displayed in bold in these two Timeline labels, helping you distinguish them from the labels over major tick marks within the Timeline.
Note:
The labels over major tick marks, the session start time label, and the session end time label all display the absolute time, not the time relative to the start of the session.
Zonar Offset and Duration Label The Zonars offset from the start of the session and the length of time currently spanned by the Zonar are displayed in the Zonar offset and duration label at the top of the Time Control panel. The information displayed in this label is helpful when you are moving the Zonar or adjusting its length. The information in this label updates continuously as you move the Zonar or adjust the length of time that it spans. This helps you keep track of the Zonars position relative to the start of the session and the length of time that you have adjusted it to cover. Checking for Data Availability The blue line under the Timeline is called the Data Availability Indicator. It indicates the presence of session data that can be displayed in the browser for one or more time slices. As you change the configuration of certain browsers, interruptions in the Data Availability Indicator may appear or be filled in. For example, deselecting the Show Response Time for All Statements checkbox in the SQL browser can cause this indicator to appear under fewer time slices. In the browsers that contain metric charts (the Request Time, SQL, Metrics, and Thresholds browsers), a gap in the Data Availability Indicator that is the length of one time slice is charted in the graph pane as a dashed line (in Default and Overlap charts). This line spans the gap between two points in the chart for which there is session data available. Using the Zonar The Zonar controls the interval of time for which data is viewed in a browser (see Figure 24). You can adjust the length of the Zonar or move it to a different part of the Timeline to cause the browser to display data for that period only. When you perform one of these actions, the session is queried and data is returned only for the interval that the Zonar spans. You can cause the Zonar to span all or part of the Timeline. The instructions below describe how to adjust the length of the Zonar or to change its location within the Timeline.
Note:
The ends of the Zonar snap to time slice boundaries. You cannot position either end of the Zonar in the middle of a time slice.
To change the length of time spanned by the Zonar:

1.
Click and drag the left side of the Zonar to set a new starting point for the interval for which data will be displayed in the browser. The offset portion of the Zonar offset and duration label will display the amount of time that this end of the Zonar is offset from the start of the session.
2.
Click and drag the right side of the Zonar to set a new end point for the interval for which data will be displayed in the browser. The duration portion of the Zonar offset and duration label will display the total length of time spanned by the Zonar.
Tip: Cover a smaller portion of the Timeline with the Zonar if you want to isolate a part of the session in which problems occur and obtain a more detailed picture of the system during that period of time.
To move the Zonar to a different location within the Timeline:

1. 2.
Click the middle of the Zonar. Drag it to the portion of the Timeline that you want to it to span.
Tip: Move the Zonar by clicking and dragging it when you want it to cover a different range of time with the same length.
To cause the Zonar to expand to fill the whole Timeline:
Double-click the Zonar.
Zooming the Timeline You can adjust how much of the Timeline is displayed (and in how much detail) by clicking the More Zone Detail (zoom in) button or the Less Zone Detail (zoom out) button (see Figure 24). When you zoom out, more of the Timeline becomes visible, allowing you to adjust the Zonar to span a longer period of time, but the Timeline is displayed in less detail. When you zoom in, less of the Timeline becomes visible, but this portion is displayed in greater detail, allowing you to position the ends of the Zonar with greater accuracy.
Note:
Clicking the More Zone Detail button zooms in to the portion of the Timeline spanned by the Zonar.
To zoom in to the Timeline:

1. 2.
Adjust the Zonar so that it spans the length of time in which you are interested. Click and hold the More Zone Detail button until the Timeline is displayed with the desired level of detail. You can zoom in until the period of time spanned by the Zonar fills the visible Timeline.
To zoom out from the Timeline:
Click and hold the Less Zone Detail button until the desired amount of the Timeline is displayed. You can zoom out until the Timeline represents the session from the start time to the end time.
Using Related Time Controls

There are certain controls that are related to the Time Control panel but are not located within it. These controls are described below. Using the Sightline Although it is linked to the Zonar, the Sightline is located in the graph pane of the Request Time, SQL, Metrics, and Thresholds browsers, not in the Time Control Panel itself. You can adjust the position of the Sightline using the Sightline slider. In the Request Time, SQL, and Thresholds browsers, this slider is located at the top of the graph pane. In the Metrics browser, there is a Sightline and a Sightline slider for each metric chart that you open in the graph pane. The Sightline is a broken line that extends downwards from the slider (see Figure 26). The sliders offset from the leftmost point on the charts x-axis is displayed next to the slider, along with the size of the time slice and the value charted at the point in the graph intersected by the Sightline. The range of time through which you can move the Sightline along the charts xaxis reflects the range currently spanned by the Zonar. When you move the Sightlines slider, it snaps to time slice boundaries imposed by the Zonar.
Figure 26
Figure 26
The Sightline and its slider in the Metrics browser
PerformaSure draws a horizontal dashed line from the y-axis to the Sightlines current position in the chart along the x-axis. This allows you to accurately determine the measured quantitys ordinate. The point at which these two lines intersect is marked by small square colored by the active metric.
Linking the Browsers Time Controls There is a button in the toolbar of every PerformaSure browser that allows you to toggle whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. Click the Link Browsers to Use Same Zone button to link the browsers Time Control panels. When linked, the Zonar and (where applicable) the Sightline in each browser are in the same state as the browser in which the button was clicked. Using the controls in the Time Control panel of one browser will impact all other browsers as well. If a problem occurs during a specific interval spanned by the Zonar, linking the browsers can help you track this problem across different browsers. Click the Break Link Between Browsers button to return the browsers Time Control panels to an unlinked state. This allows each browsers Zonar and Sightline to function independently.
Using the Request Time Browser

The recommended starting place for your investigation is the Request Time browser because it helps you identify the most time-consuming requests.
Figure 27
Figure 27
The Request Time browser
What does the Request Time browser do?

The Request Time browser provides a list of service requests that entered the instrumented system during the interval spanned by the Zonar, displays response time data for these requests, and allows you to view response time metrics for requests broken down by tier or by component technology. You can also use this browser to drill down into a single request to examine many different metrics for that request over time. The Request Time browser functions in two modes: All Requests mode and Single Request Investigation mode. See Using the Browser in All Requests Mode and Using the Browser in Single Request Investigation Mode below for more information about these modes. How this helps: The Request Time browser helps you investigate performance metrics related to service requests over time, including the total time spent servicing each individual
request. It allows you to determine which service request took the longest to complete, and where the majority of the requests time was spent.
Using the Request Time BrowserQuick Start

Using the Browser in All Requests Mode In All Requests mode, you can compare the metrics for the requests listed in the detail pane. The table in this pane can be sorted by name or by one of the metrics, allowing you view response time metrics for a specific request or to isolate the most expensive request based on a certain metric. When you select a request in the detail pane, response time metrics are charted for that request in the graph pane. In All Requests mode, you have the option of charting the aggregate response time for all requests with the metrics for the selected request. Setting the Display Mode You can cause the browser to display response time metrics in the graph pane and in the bar charts in the detail pane broken down either by tier or by component technology. Displaying response time metrics broken down by tier allows you to distinguish the tiers of your application in the graph pane and in the response time metric bar charts in the detail pane.PerformaSure consistently assigns one color to each tier and one for each application server cluster. Select Tier to investigate response time by tier for the request that you selected and for the requests listed in the detail pane. When you select this option, the segments in the chart in the graph pane and in the bar charts in the detail pane are grouped in terms of the following tiers: web server, application server cluster(s), and database. Displaying response time metrics broken down by component technology allows you to distinguish component types in the graph pane and in the response time metric bar charts in the detail pane. PerformaSure consistently assigns one color to each standard and custom component. When you select this option, the segments in the chart are grouped based on J2EE component technology. The component technology segments are: HTTP, Servlet, EJB, [Custom Components], RMI, URL, JNDI, JMS, and JDBC.
To change the display mode:
1.
Click the Display By drop-down menu in the toolbar or select View > Display by... from the menu bar to display a submenu from which you can select one of two options: Tier or Component Technology. Tier is selected by default. Click the radio button associated with either Tier or Component Technology.
2.
Isolating Requests in the Detail Pane The detail pane is only available when the browser is in All Requests mode. The Request Time browsers detail pane presents a list of requests and of response time metrics for these requests in tabular form. See Detail Pane Columns on page 250 for more information. If you are interested in specific metrics listed in the detail pane, you can cause only the columns that correspond to those metrics to be displayed. By allowing you to sort the requests listed in the detail pane based on the values listed in one of the metric columns, the Request Time browser helps you isolate the most expensive request based on a particular metric.
To toggle the display of the detail pane columns:
1.
Select View > Show/Hide Columns... from the menu bar or right-click anywhere in the detail pane to make a contextual menu appear from which you can select Show/Hide Columns.... The Show/Hide Columns dialog will open. If you only want to hide one column, simply right-click on it and select Hide Column from the contextual menu that appears. If you want to cause that column to be displayed again, you will need to use the Show/Hide Columns dialog.
2.
If you do not want certain metrics to be displayed, uncheck the checkboxes that correspond to those metrics. If you want to deselect all items in this dialog so that only the Name column is displayed in the detail pane, click None. To select all items in the dialog so that all columns are displayed in the detail pane, click All. Click OK to apply these settings and close the dialog.
3.
To isolate an expensive request in the detail pane:

1.
Select the display mode for the detail pane bar charts. See Setting the Display Mode on page 98 for details. Click on the header for a metric column once to sort the requests in descending order based on that metric or twice to sort the requests in ascending order. An arrow indicating the order in which the requests are sorted will appear in the header.
2.
Figure 28
Figure 28
Sorting requests by Avg Cumulative Time in the detail pane
Charting Response Time Metrics For a Request Once you have isolated a request of interest in the detail pane, simple click its entry in the table to cause a metric chart to be displayed in the graph pane for that request. Depending on the option that you chose from the Display by drop-down menu, response time metrics for the selected request will be charted in the graph pane broken down either by tier or by component technology. See Setting the Display Mode on page 98 for details. See Request Time Browser Graph Pane Full Detail on page 244 for information about the controls, tooltips, and contextual menus available in the graph pane. Charting the Aggregate Response Time Metric Leave the Show Response Time for All Requests checkbox selected (the default setting) to display aggregate response time data for all requests listed in the detail pane. Deselect this checkbox if you do not want this data to be charted in the graph pane.
Figure 29
Figure 29
The aggregate response time of all requests charted in the graph pane
As shown in Figure 29, the chart segment for the overall response time of the system is identified as Response Time in the graph pane. Tip: Leave Show Response Time for All Requests checked to examine the request you selected in comparison to the overall response time of the system. Charting the aggregate response time of all requests provides you with a point of reference for your investigation into an expensive request. Investigating a Single Request After isolating an expensive request in the detail pane and viewing response time metrics for it in the graph pane, you can continue your investigation by drilling down into the request. In All Requests mode, three Request Investigation actions are available in the browsers control pane (Figure 30). Click the arrow icon or the action text to perform an action. When you perform an action, the browser will switch into Single Request Investigation mode. Depending on the action that you perform, response time metrics for the selected request will be broken down by tier, component technology, or server and displayed in the graph pane. See Request Investigation on page 240 for more information about the drill-down actions available in the browser in All Requests mode.
Figure 30
Figure 30
The Request Time browsers control pane in All Requests mode
Investigating a Request in Other PerformaSure Browsers In All Requests mode, two actions are available in the control pane that allow you to continue your investigation in other PerformaSure browsers: View call tree of selected request and View related metrics of selected request. Click the arrow icon or the action text to perform an action. See Further Investigation on page 241 for more information about these actions.
Using the Browser in Single Request Investigation Mode When you find a request of interest, you can switch the browser into Single Request Investigation mode by drilling down into the request to investigate response time by tier, component technology, or server. The drill-down actions that you can perform once you have switched the browser into Single Request Investigation mode are described below. See Request Time Browser Graph PaneFull Detail on page 244 for information about the controls, tooltips, and contextual menus available in the graph pane.
Figure 31
Figure 31
The Request Time browsers control pane in Single Request Investigation mode
Tracking the Drill-Down Levels The Current Drill Down History section of the control pane displays the drill-down history for the request that you are currently investigating, allowing you to keep track of the request investigation actions that you have performed. The entries for previous drill-down levels function like request investigation actions. Click the entry for a previously-selected action to drill up a level. Click Request to cause the browser to return to All Requests mode. Hover the cursor over the entry for a previous drill-down level to make a tooltip appear in which the specific value for that level is displayed.
Figure 32
Figure 32
A drill-down history tooltip
Selecting the Next Drill-Down Level The drill-down actions that you can perform vary depending on the current drilldown level. Click Next Drill Down to display a menu that lists the available drill-down options. See Next Drill Down on page 242 for more information about the options in this menu. Investigating a Request in Other PerformaSure Browsers In Single Request Investigation mode, two actions are available in the control pane that allow you to continue your investigation in other PerformaSure browsers: View call tree of selected request and View related metrics of selected request. Click the arrow icon or the action text to perform an action. See Further Investigation on page 243 for more information about these actions. Linking Time Control Panels You can link the Time Control panels of all existing and newly created browsers. When the browsers are linked, using the controls in the Time Control panel of one browser will impact all other browsers as well. See Linking the Browsers Time Controls on page 96 for more information. Request Time Browser Reports Click the Export Report button in the browsers toolbar or select Browser > Export Report... from the menu bar to begin the process of creating a report in CSV, PDF, or XML format. See Choosing the Report Option on page 398 for more information about generating a report. See Request Time Report on page 403 for details about the information included in a report generated from the Request Time browser.
Using the SQL Browser

Figure 33
Figure 33
The SQL browser
What does the SQL browser do?

The SQL browser displays performance information for SQL statements aggregated across multiple requests. It provides you with a high-level view of the SQL statements used in your application, helping you identify and diagnose database problems. You can use this browser to chart SQL response time metrics for a particular statement broken down by operation and compare the metrics for that statement with the aggregate response time of all statements. As your performance investigation progresses, you can configure the browser to chart metrics in the graph pane for specific SQL operations. How this helps: The SQL browser helps you diagnose database performance problems effectively by providing you with detailed information about the SQL statements that are used in your application.
Using the SQL BrowserQuick Start

Isolating SQL Statements in the Detail Pane The SQL browsers detail pane presents a list of SQL statements and of response time metrics for these statements in tabular form. See Detail Pane Columns on page 278 for more information. If you are interested in specific metrics listed in the detail pane, you can cause only the columns that correspond to those metrics to be displayed. By allowing you to sort the statements listed in the detail pane based on the values listed in one of the metric columns, the SQL browser helps you isolate inefficient SQL statements.
1.
Select View > Show/Hide Columns... from the menu bar or right-click anywhere in the detail pane to make a contextual menu appear from which you can select Show/Hide Columns.... The Show/Hide Columns dialog will open. If you only want to hide one column, simply right-click on it and select Hide Column from the contextual menu that appears. If you want to cause that column to be displayed again, you will need to use the Show/Hide Columns dialog.
2.
If you do not want certain metrics to be displayed, uncheck the checkboxes that correspond to those metrics. If you want to deselect all items in this dialog so that only the Name column is displayed in the detail pane, click None. To select all items in the dialog so that all columns are displayed in the detail pane, click All. Click OK to apply these settings and close the dialog.
3.
To isolate an inefficient statement in the detail pane:
Click on the header for a metric column once to sort the statements in descending order based on that metric or twice to sort the statements in ascending order. An arrow indicating the order in which the statements are sorted will appear in the header.
Figure 34
Figure 34
Sorting statements by Avg Response Time in the detail pane
Charting Response Time Metrics For a SQL Statement Once you have isolated a statement of interest in the detail pane, simple click its entry in the table to cause a metric chart to be displayed in the graph pane for that statement. See SQL Browser Graph PaneFull Detail on page 272 for details about the controls, tooltips, and contextual menus available in the graph pane. Charting the Aggregate Response Time Metric Leave the Show Response Time for All Statements checkbox selected (the default setting) to display aggregate response time data in the graph pane for all SQL statements listed in the detail pane; the chart segment for this data is identified as Total Response Time in the graph pane. Deselect this checkbox if you do not want this data to be charted in the graph pane.
Figure 35
Figure 35
The aggregate response time of all SQL statements charted in the graph pane
Charting the Total Response Time provides you with a point of reference for your performance investigation by allowing you to examine the response time metrics for a particular statement in comparison to the overall response time of all SQL statements. Using the SQL Browsers Control Pane The SQL browsers control pane contains controls for configuring the display of response time data in the graph pane and actions that you can take to continue your performance investigation in other PerformaSure browsers.
Figure 36
Figure 36
The SQL browsers control pane
Showing Selected SQL Operations The checkboxes in the SQL Statement Investigation area control the display of response time data for the SQL operations charted in the graph pane. All three options (Prepare, Execute, and Retrieve) are selected by default. You can deselect the checkboxes that correspond with the operations that you do not want to show. Investigating a Statement in Other PerformaSure Browsers Two actions are available in the SQL browsers control pane that allow you to continue your investigation in other PerformaSure browsers: View call tree of related request and View related metrics of selected statement. Click the arrow icon or the action text to perform an action. See Further Investigation on page 271 for more information about these actions. Linking Time Control Panels You can link the Time Control panels of all existing and newly created browsers. When the browsers are linked, using the controls in the Time Control panel of one browser will impact all other browsers as well. See Linking the Browsers Time Controls on page 96 for more information. SQL Browser Reports Click the Export Report button in the browsers toolbar or select Browser > Export Report... from the menu bar to begin the process of creating a report in CSV, PDF, or XML format. See Choosing the Report Option on page 398 for more information about generating a report. See SQL Report on page 404 for details about the information included in a report generated from the SQL browser.
Using the Request Tree Browser

Figure 37
Figure 37
The Request Tree browser
What does the Request Tree browser do?

The Request Tree browser provides a graphical view of service requests in its graph pane. Each request is illustrated in a request tree. A request tree starts with the requests invocation as it enters the system and progresses through the various method and database calls. For example, as a request progresses, it may call one or more Servlets, which in turn call one or more EJBs, and so on, until the request is complete. Request trees can be displayed in the graph pane with component-, class-, or method-level detail. Each request tree is comprised of one entry-point node (also called a root node) and multiple group nodes. An entry-point node can represent an HTTP or an RMI request. Group nodes represent components in your J2EE application, Java classes, or JDBC calls that contributed to the completion of that request. Group
nodes are comprised of method nodes, which are displayed as rectangular boxes within group nodes.
Figure 38
Figure 38
Elements in the Request Tree browsers graph pane
One of the purposes of the Request Tree browser is to help you find the critical path within a request: the one taking the most time. Request trees can be colored and sorted, allowing you to easily identify the most expensive service request or the most expensive node in a request tree based on the active metric that you select. The Request Tree browser also includes a detail pane that provides an explorer view of the requests that are illustrated in the graph pane. The detail pane displays information including method names, cumulative times, and call counts. You can configure the detail pane to display this information in list or in a tree view that preserves calling relationships.
Figure 39
Figure 39
The detail pane of the Request Tree browser with the display set to Tree
How this helps: The Request Tree browser allows you to examine in greater detail the timeconsuming requests that you identified in the Request Time browser. Once you have identified an expensive request in the Request Time browser, you can cause it to be displayed in the Request Tree browser. Simply right-click on the request in the graph pane of the Request Time browser and select View Call Tree from the contextual menu that appears. Multiple selections are allowed. The Request Tree browser provides a wealth of information about the requests in your application. By deconstructing a service request into its constituent parts and displaying them in a request tree, this browser enables you to follow the nested set of calls that are made as the request progresses. A request tree shows the relationship between all componentssuch as Servlets, EJBs, and JDBC callsthat contributed to the completion of a service request.
Using the Request Tree BrowserQuick Start

This section provides steps that you can follow to become more familiar with using the Request Tree browser. For detailed descriptions of all of the fields and controls in this browser, see Request Tree Browser on page 283. Navigating the Graph Pane Zooming the graph pane A typical request tree displays a considerable amount of information, and it is not likely that it will fit in the graph pane unless you reduce its scale. You can use the Zoom Control slider (see Figure 38) to reduce the scale of the request trees displayed in the graph pane by as much as 90%, allowing you to get an overall impression of events. Scrolling through the graph pane To scroll through the graph pane more easily, you can use the panner. The panner opens in its own window. As shown in Figure 40, the panner window contains a scaled-down view of the graph pane. The highlighted rectangle in the panner window represents the current view area.
Figure 40
Figure 40
The panner window
To display and use the panner:

1.
Click the Show Panner button in the toolbar or open the View menu and check the checkbox associated with the Show Panner menu item. The panner will open in its own window. Click and drag the highlighted rectangle to reposition the view area within the graph pane. To enlarge or reduce the highlighted area, zoom in to or out of the request tree using the Zoom Control slider. If the Panner Updates Graph While Dragging checkbox is selected in the Request Tree pane of the Edit Options dialog (Tools > Options...), the view area in the graph pane will update continuously. If it is not selected, the view area will update only when you release the mouse button.
2.
Note:
Coloring Request Trees Coloring tree nodes The nodes in a request tree can be color-coded. The hotter the color of a node, the more expensive that node is in relation to other nodes based on the active metric. By default, the tree is colored by Avg Cumulative Time, the average amount of time taken by each method (and its children) during the interval spanned by the Zonar. You can recolor the request trees in the graph pane based on one of thirteen active metrics. For example, you could change the active metric from its default setting to Avg Call Count, the number of times each method was called (per request) during the interval spanned by the Zonar.
To change the active metric to Avg Call Count:
1.
Click on Active Metric in the toolbar to display a drop-down menu with the active metric options or select View > Active Metric from the menu bar to display a submenu with these options.
2.
Select Avg Call Count. The Methods in each request tree will be recolored based on the new active metric.
See Active Metric on page 292 for a complete list of the metrics from which you can choose. Coloring the Identifier bars You can also color the Identifier bar found on the left side of each node (see Figure 38) by Tier or Component Technology. Tier is selected by default. The color of each Identifier bar represents a different tier or component technology, helping you distinguish between the tiers in your application or between component types.
To change the display mode of the Identifier bars to Component Technology:
1.
Select View > Display by from the menu bar to display a submenu with two options: Tier and Component Technology. Select Component Technology. The Identifier bars in the request trees will change color. You can now distinguish each standard and custom component in your J2EE application based on the unique color that it is assigned.
2.
Using and Customizing the Color Scale The Color Scale Toggle button toggles the display of a color-based legend called the Color Scale (see Figure 38). The hot color is displayed at the top of this scale. This color is used to identify the most expensive nodes based on the active metric. The cold color at the bottom of the scale is used to mark nodes that are the least expensive based on the active metric. Clicking the Color Scale Toggle button causes the Color Scale to appear or disappear. You can choose different hot and cold colors in the Edit Options dialog. The intermediate colors are interpolated from the hot and cold colors.
To select custom colors for the Color Scale:
1.
Select Tools > Options... from the menu bar. The Edit Options dialog will open. Select Themes on the left-hand side of the dialog. The Themes pane will be displayed on the right-hand side. This pane contains four options boxes and a drop-down menu with the choices White, Black, and Custom. Select Custom from the drop-down menu. The Color Scale options box contains two color rectangles, which are used to set the extreme hot and cold colors in the Request Tree and Network Traffic
2.
3. 4.
browsers. Click on a color rectangle to launch the Select Color chooser. There are three ways of specifying a new color: color swatches, HSB, or RGB.
5.
After selecting new hot and cold colors, click Apply to update the colors used in the Request Tree browsers Color Scale and then click OK to close the dialog. You can use the controls in the Themes pane to customize many of the colors used in the browsers. See Edit Options Dialog on page 215 for more information.
Note:
Sorting Request Trees After recoloring the request trees in the graph pane by selecting a new active metric, you can sort the trees based on that metric. Sorting a request tree causes nodes with higher values of the active metric to appear above nodes with lower values. To sort the request trees, select View > Sort Tree from the menu bar. See Sort Tree on page 291 for more information about how request trees are sorted. Tooltips in the Graph Pane There are several tooltips associated with each node in a request tree. The information displayed in these tooltips changes based on how you have configured the Request Tree browser. For example, changing the display mode of the Identifier bars from Tier to Component Technology (View > Display by) also changes the tooltip for these bars. After changing the display mode, hover the cursor over an Identifier bar to cause the new tooltip to appear.
Figure 41
Figure 41
The tooltip for an Identifier bar when Component Technology is selected
The format of the tooltips for entry-point, group, and method nodes changes depending on whether Per Request or Per Call is selected from the Metric Display submenu. Per Request is selected by default; this setting causes request averages to be displayed in tooltips and in the detail pane. To change the display setting so that call averages are displayed in tooltips and in the detail pane, select View > Metric Display > Per Call from the menu bar or click Metric Display in the toolbar and select Per Call from the drop-down menu that appears. When you hover the cursor over the header for a group node, a tooltip appears displaying metrics for the whole group.
Figure 42
Figure 42
Tooltip in the Request Tree Browser showing per request statistics
When you hover the cursor over a method node, a tooltip with a similar format is displayed. This tooltip has an extra line in the header that contains the method name. Hovering the cursor over an entry-point node (like an RMI or HTTP node) causes a different type of tooltip to appear. The tooltips for entry-point nodes contain extra fields, such as Total Cumulative Time and Sampled Requests (listed as a percentage). See Request Tree Tooltips on page 312 for more information about the tooltips associated with the various types of nodes. There is also tooltip associated with each section of the Color Scale. Hover the cursor over a section of the Color Scale to make this type of tooltip appear (see Figure 43). If the scale is not visible, click the Color Scale Toggle button to make it appear. This type of tooltip displays the name of the active metric and the metric range spanned by that color. This range is listed on a per request or per call basis, depending on the option that you selected from the Metric Display submenu.
Figure 43
Figure 43
The tooltip for a section of the Color Scale
Bundling The different bundling modes available in the Request Tree browser allow you to change the level of detail at which the request trees are displayed. Componentlevel bundling displays key J2EE classes and methods in each request tree, giving you an overview of your applications behavior. Class-level bundling displays both J2EE and user classes, presenting a slightly more complex tree. However, when you select class-level bundling, method calls to other methods within the
same class are not displayed but are bundled together as a single node, labeled by the method that starts the string of calls. Method-level bundling displays all classes and method calls, presenting the most detailed request tree. Important: PerformaSures default bundling mode is Component. That means that even if you collected your session at full detail, only the key J2EE components are shown if you do not change the bundling mode from its default setting. It is recommended that you begin your performance investigation with the bundling mode set to Component. As your investigation progresses, you can switch to one of the other modes to expose more details about your applications behavior.
To change the bundling mode from its default setting:
1.
Select View > Bundling Mode from the menu bar to display a submenu with the different bundling options (Component, Class, and Method) or click Bundling Mode in the toolbar to display a drop-down menu with these options. Depending on the level of detail at which you want the request trees to be displayed, select either Class or Method. The new setting will take effect immediately, but you may need to wait a few moments while PerformaSure updates the view in the graph pane.
2.
Pruning and Isolating Request Trees Nodes that are very expensive based on the active metric can overshadow nodes that are less expensivebut still problematic. The Prune and Isolate options available from the contextual menus in the graph pane allow you to hide certain request tree nodes. The range of values for the active metric does not include values from pruned nodes or nodes that are excluded when you select one of the Isolate options. Thus, when you prune or isolate a node, a new maximum value can be used. This changes how the nodes are colored and allows you to pinpoint problem areas that were previously overshadowed. Selecting one of the Prune or Isolate options can cause certain nodes to appear as ghosted. All pruned nodes or nodes that have been excluded when you select one of the Isolate options will appear as ghosted if you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (Tools > Options... > Request Tree). Certain nodes will always display as ghosted when you prune them because they must remain in place to maintain the request trees structure. For example, pruning a node in the path between two unpruned nodes will cause that node to display as ghosted. If you prune an entry-point node, it will also display as ghosted, allowing you to un-prune it later.
The action performed when you select one of the Prune or Isolate options can vary depending on the contextual menu from which you select it. See Contextual Menus in the Graph Pane on page 316 for more information. Request Tree Browser Detail Pane The metrics that appear in the tooltips for the request tree nodes are also listed in tabular form in the detail pane (see Figure 39). This table also lists the Agents that collected the data, the URLs that were called during the interval spanned by the Zonar, and the methods that were called. See Detail Pane Columns on page 328 for details. Tip: Double-click a node in the request tree to transfer focus to the corresponding item in the Request Tree detail pane. You dont have to spend time searching for the item. The process works in reverse as well. Double-click an item in the Request Tree detail pane to transfer focus to the corresponding node in the request tree. Because multiple methods of one type may exist in the tree, the most expensive one is selected based on the active metric. There are two settings for viewing this information, Item and Tree. Item is the default setting. When Item is set, all the methods that were called are listed in a simple tabular format underneath the request. When Tree is selected, items are arranged in a tree hierarchy underneath the request. Tree format causes the calling relationships between the nodes illustrated in the graph pane to be mirrored in the detail pane.
Figure 44
Figure 44
Items listed in the detail pane (with Tree selected)
To change the detail table mode to Tree:

1.
Select View > Detail Table Mode from the menu bar and select Tree or click the item/tree toggle button ( ) at the far right of the detail pane. The way the lines are drawn inside the button does not indicate the current view but the view that will appear when you click on the button.
2.
Double-click the URL name to expose the methods that were called.
There may be metrics or other types of information that you dont want to see in the detail pane while analyzing a session. You can remove these items from view by hiding the column in which they are listed.
1.
Select View > Show/Hide Columns... from the menu bar or right-click anywhere in the detail pane to make a contextual menu appear from which you can select Show/Hide Columns.... The Show/Hide Columns dialog will open. Note: If you only want to hide one column, simply right-click on it and select Hide Column from the contextual menu that appears. If you want to cause that column to be displayed again, you will need to use the Show/Hide Columns dialog. If you do not want the name of the Agent that collected the data to be displayed, uncheck the Agent checkbox. If you do not want certain metrics to be displayed, uncheck the checkboxes that correspond to those metrics. If you want to deselect all items in this dialog so that only the Name column is displayed in the detail pane, click None. To select all items in the dialog so that all columns are displayed in the detail pane, click All. Click OK to apply these settings and close the dialog.
2.
3.
Linking Time Control Panels You can link the Time Control panels of all existing and newly created browsers. When the browsers are linked together, using the controls in the Time Control panel of one browser will impact all other browsers as well. See Linking the Browsers Time Controls on page 96 for more information. Exporting a JProbe Launcher File PerformaSure can generate a configuration ( JPL) file for deeper analysis with JProbe Profiler. See JProbe Integration on page 127 for more information. Request Tree Browser Reports Click the Export Report button in the browsers toolbar or select Browser > Export Report... from the menu bar to begin the process of creating a report in CSV, PDF, or XML format. See Choosing the Report Option on page 398 for more information about generating a report. See Request Tree Report on page 404 for details about the information included in a report generated from the Request Tree browser.
Using the Metrics Browser

Figure 45
Figure 45
The Metrics browser
What does the Metrics browser do?

The Metrics Browser provides a full list of available metrics organized in a collapsible tree hierarchy in its navigation pane. You can open each metric in its own chart in the graph pane or visually correlate multiple metrics in the same chart; multiple charts can be opened simultaneously. Charting metrics allows you to compare the trend of related metrics, to see if certain metrics exceed the minimum or maximum thresholds you have set for them, to observe the duration of threshold violations, and to check for any anomalous behavior. The Metrics browser also provides access to the Threshold Editor, the dialog in which you set metric thresholds. See Threshold Editor on page 392 for more information about setting thresholds. How this helps: Metrics whose thresholds were exceeded can be viewed in a format that allows their correlation with other metrics. The Metrics browsers navigation pane provides you with a list of all metrics available in the session that you recorded.
Charting metrics in the graph pane allows you to view these metrics throughout the history of the session, helping you pinpoint problem areas. The Sightlines are linked in all charts that you open in a Metrics browser, allowing you to correlate an event in one chart with that in another.
Using the Metrics BrowserQuick Start

Exploring the Tree Hierarchy The navigation pane contains a list of metrics organized in a tree hierarchy. All the metrics available for the session that you are currently analyzing are listed in this pane. The metrics available in a session will vary depending on several factors, such as the application server(s) that you are instrumenting. See The Metric Hierarchy on page 446 for a description of the structure of the metric hierarchy that is displayed in the navigation pane.
To expose the next level in the metric hierarchy:
Double-click a node in the tree or click the square ( ) to the left of the node.
To navigate the metric hierarchy using your keyboard:

Move from node to node using the up and down arrow keys. Expand or close folders using the right and left arrow keys. Select or deselect entries in the tree by pressing the spacebar.
Selecting Metrics For Display There are several ways that you can select metrics from the tree hierarchy for presentation in the graph pane.
To open a metric chart:
Select a metric in the tree and press Enter or double-click a metric. You can also click and drag a metric from the navigation pane to a blank space in the graph pane or to the edge of a chart in the graph pane. Performing any one of these actions causes the metric to be displayed in its own chart.
To add a metric to an existing chart:
Click on the metric in the tree hierarchy and drag it to a chart in the graph pane.
Tip: Charting a metric in the same chart as another makes it easier to compare the trend of several metrics.
To open a chart with multiple metrics:

Ctrl-click or Shift-click the metrics in the navigation pane and press Enter Ctrl-click or Shift-click the metrics in the navigation pane and right-click on the selected metrics to cause a contextual menu to appear. This menu contains three options: Open, Open in Overlap Mode, Open in Stacked Mode. When you select Open, the metrics are charted together in Default mode. See Changing the Chart Type on page 350 for more information about chart types.
To reposition a metric chart within the graph pane:
Click the top portion of the chart and drag it to another spot in the graph pane.
To remove a metric chart from the graph pane:
Click the Close Chart button or right-click below the top portion of the chart and select Close Chart from the contextual menu that appears.
Charting Metrics in the Graph Pane By following the instructions in Selecting Metrics For Display, you can open a collection of charts in the Metrics browsers graph pane. Each chart that you open illustrates the history of one or more metrics during the interval spanned by the Zonar. The metrics that are available for display in the graph pane are listed in the tree hierarchy in the navigation pane. See Metrics Browser Graph PaneFull Detail on page 348 for details about the tooltips and contextual menus available in each chart that you open in the graph pane; this section also contains information about applying functions to metrics and using the Chart Type chooser and the Plot Type chooser. Metrics Browser Reports Click the Export Report button in the browsers toolbar or select Browser > Export Report... from the menu bar to begin the process of creating a report in CSV, PDF, or XML format. See Choosing the Report Option on page 398 for
more information about generating a report. See Metric Report on page 406 for details about the information included in a report generated from the Metrics browser.
Using the Network Traffic Browser

Figure 46
Figure 46
The Network Traffic browser
What does the Network Traffic browser do?

The Network Traffic browser displays the volume of network traffic sent from one network interface to another. This information can be displayed in a twodimensional or three-dimensional chart. The data is arranged in a grid of x, y pairs in the graph panes network interaction chart (see Figure 47). The senders are listed along the y-axis and the machines to which they transfer data over the network are listed along the x-axis, making the sources of outgoing traffic distinguishable from the destination interfaces. Important: The Network Traffic browser only graphs sent traffic, not received traffic.
Figure 47
Figure 47
Elements in the Network Traffic browsers graph pane
How this helps: The Network Traffic browser provides information about network-based data transfers, allowing a user to initiate investigative effort on bandwidth overhead.
Using the Network Traffic BrowserQuick Start

Viewing Charts in 2D and in 3D The network interaction chart displays a grid of machines for which traffic has been logged. The x-axis and y-axis labels are the machine names; network activity is shown in the grid on the x-y plane. When you select Display as 3D Chart, the
z axis measures the amount of data transferred per second (listed in the detail pane as the metric Data Volume). 2D Chart When you open a new Network Traffic browser, the network interaction chart is displayed in 2D mode. In this mode, the volume of data sent from one machine to another is shown by coloring sections of the grid. See Color Scale Toggle Button on page 370 for details about color coding in the chart. 3D Chart By selecting View > Display as 3D Chart from the menu bar, you can view the chart in 3D mode. In this mode, the volume of data sent from one machine to another is displayed as a colored columnar bar at each grid intersection. Each color represents a range within the metric Data Volume for the interval spanned by the Zonar. In the 3D chart, the height of each bar is proportional to the metric value charted at that grid intersection for the interval spanned by the Zonar.
To rotate the 3D chart:
Hold down the Ctrl key while dragging on the graph.
Zooming the Network Interaction Chart When a network interaction chart illustrates traffic from many machines, it might not fit in the graph pane unless you reduce its scale. You can use the Zoom Control slider (see Figure 47) to reduce the scale of the chart displayed in the graph pane. The scale of the 3D chart can be reduced by as much as 75% and the scale of the 2D chart can be reduced by as much as 90%. Tooltips in the Graph Pane Machine Name Label Tooltips Hover the cursor over a machine name label in the chart to cause a tooltip to appear that displays the corresponding IP address.
Figure 48
Figure 48
A machine name label tooltip in the graph pane
Grid Section/Columnar Bar Tooltips Hover the cursor over a section of the grid (in the 2D chart) or a columnar bar (in the 3D chart) to cause a tooltip to appear that shows the volume of data sent from one machine to another.
Figure 49
Figure 49
A grid section tooltip in the graph pane
Network Traffic Browser Detail Pane The Network Traffic browsers detail pane (Figure 50) provides an explorer view of the machines in your network. You can expand the nodes in the Name column to see exactly how many bytes or kilobytes of data were sent per second from one network interface to another; the volume of data sent over the network to each receiver is listed in the Data Volume column. See Network Traffic Browser Detail Pane on page 371 for more information.
Figure 50
Figure 50
The detail pane in the Network Traffic browser
Network Traffic Browser Reports Click the Export Report button in the browsers toolbar or select Browser > Export Report... from the menu bar to begin the process of creating a report in CSV, PDF, or XML format. See Choosing the Report Option on page 398 for more information about generating a report. See Network Traffic Report on page 407 for details about the information included in a report generated from the Network Traffic browser.
Using the Thresholds Browser

Figure 51
Figure 51
The Thresholds browser
What does the Thresholds Browser do?

The Thresholds browser displays information about metrics with threshold violations. All metrics that have exceeded their threshold settings during the interval spanned by the Zonar are listed in the browsers detail pane; you can view a chart for each metric in the graph pane. How this helps: The Thresholds browser can help you identify problem areas that should be investigated further. Once you have pinpointed intervals in the session during which metric thresholds were exceeded, you can continue your investigation in other PerformaSure browsers to determine the cause of these threshold violations.
Using the Thresholds BrowserQuick Start

Selecting a Metric For Display The Thresholds browsers detail pane provides an explorer view of the metrics with threshold violations. Metric properties are displayed in the detail pane in tabular form. See Detail Pane Columns on page 390 for more information. You can isolate a metric of interest by sorting the columns in the detail pane. For example, by sorting by Total Duration, you can find the metric that exceeded its threshold settings for the longest period of time during the interval spanned by the Zonar.
To isolate a metric in the detail pane:
Click on the header for a column once to sort the metrics in descending order based on the values listed in that column or twice to sort the metrics in ascending order. An arrow indicating the order in which the metrics are sorted will appear in the header.
Figure 52
Figure 52
Sorting metrics by Total Duration in the detail pane
Charting Metrics in the Graph Pane Once you have isolated a metric of interest in the detail pane, simple click its entry in the table to cause it to be charted in graph pane. The chart will show a diagonally striped, rectangular strip at the right-hand edge of the chart. This strip indicates the range on the y-axis in which the metric exceeds its normal bounds; a threshold line is drawn across the chart to indicate the threshold boundary (see Figure 51). See Thresholds Browser Graph PaneFull Detail on page 387 for details about the controls and tooltips available in the graph pane. Setting Thresholds Metric thresholds are set in the Threshold Editor. You can access the Threshold Editor by clicking the Edit Thresholds button that is located at the bottom right-hand corner of the graph pane when you are viewing a metric in a Default or Overlap chart. See Threshold Editor on page 392 for more information.
Thresholds Browser Reports Click the Export Report button in the browsers toolbar or select Browser > Export Report... from the menu bar to begin the process of creating a report in CSV, PDF, or XML format. See Choosing the Report Option on page 398 for more information about generating a report. See Threshold Report on page 407 for details about the information included in a report generated from the Thresholds browser.
Integration with the Quest Software Suite for Further Analysis

PerformaSure is designed to work with JProbe, a low-level profiling tool, as well as with load testers, application servers, and Web servers. The following topics are covered in this section:

JProbe Integration Foglight Integration Spotlight Integration Integration with Quest Database Tools
JProbe Integration
JProbe Profiler is the ideal tool for profiling the internals of Java classes. Its a good idea to look over the documentation for JProbe so that youll be aware of all its features and terminology and be comfortable using it. PerformaSure provides a handy tool to make coordination with JProbe even easier. This section describes the functions available from PerformaSures Export JProbe Launcher File menu choice. This option is available in the Request Tree browser.
Figure 53
Figure 53
Export JProbe Launcher File menu choice
Using the Integration Tool

The .jpl file contains settings to start the application server under JProbe Profiler, either from a command line or from JProbes LaunchPad, and to collect performance data on the classes and methods that you select in PerformaSures Request Tree browser. Caution: Use the Options dialog to select the version of JProbe that you are using, otherwise the jpl file that is created will not be compatible with your version of JProbe.
To generate a JPL file:
1.
Select one or more nodes in the call tree displayed in the Request Tree browsers graph pane. These serve to specify the packages and classes you want to profile with JProbe. Select a class by clicking on the first item (the class name) in the node. Select a method by clicking on any of the other items. If you choose a node that does not represent a class or method, it will be ignored when producing the JPL file. To select more than one node, press the Control key in combination with a mouse click on each desired node. To profile the selected item or items, JProbe must be installed on a machine that is running the same software as that used when the PerformaSure data for the selected item or items was collected. Ideally, this would be the same machine as the one used for recording the PerformaSure session. In the File menu, or by right-clicking on one of the selected nodes, choose Export JProbe Launcher File. PerformaSure gives you the ability to specify the scope of your JProbe analysis. You can track data in either the entire package (or set of packages) represented by the class(es) and/or method(s) you have selected, or just the class(es) represented by your selection(s).1 To track data in all methods in the package represented by each selected class or method, choose Profile Selected Package(s). If you have selected
2.
3.
multiple classes and/or methods, all packages represented by your selections are marked for tracking. To track data in all methods in the selected classes (or classes represented by selected methods), choose Profile Selected Class(es).
To use the JPL file generated by PerformaSure:
1. 2.
Ensure that JProbe is installed on a machine as described in step 2 above. Complete the JPL by loading the JPL file into the JProbe LaunchPad and selecting your application server and Integration ID. Even though a server and integration may be selected automatically when you open the JPL file in the LaunchPad, they may be either incomplete or incorrect because this can only be done properly from the LaunchPad on the machine where JProbe is installed. Therefore, it is vital that you verify that you have selected a valid and working configuration for your applicaion server and integration.
3.
Run JProbe Profiler using the generated JPL file along with the chosen integration. You can run JProbe from either the command line or from the console. Refer to the JProbe documentation for details. Since the key elements of the JPL file are filters, and these are generated by PerformaSure based on the nodes you have selected, it is possible to use the JPL files to profile your software on machines other than the ones used to collect PerformaSure metrics, for example, a developers workstation or a test environment running the same application server and deployed software.
Note:
JPL File Details To begin using JProbe, select nodes and generate the JPL file. If you need to delve deeper, this section contains advanced material that uses JProbe-specific terminology and assumes familiarity with JProbe and its use. If you are new to JProbe, refer to the JProbe Profiler Developers Guide for a complete description of the application. The default analysis type is Performance profiling, and the user-specified timing method is used (elapsed/cpu). Recording from start (Record Performance from Program Start in JProbe 5.0, Start Use Case at JVM Launch in JProbe 5.2) is enabled, except for in JProbe 4.x, where a resume recording trigger is set upon entry to the first method included in one of the selected classes that is executed on the server during the request. As required by JProbe, this trigger will be on a method that is within the scope of the filternot one that has been filtered out. Filters are configured as follows: all methods in all classes are encapsulated (for JProbe 4.x
1. If you selected methods, the classes containing these methods will be profiled.
they are tracked and invisible), followed by filters for each class or package selected using the user-specified detail level (method/line). After recording starts, the filters cause data to be collected during the execution of any methods within the selected classes or packages1. No triggers are set to either pause recording or take snapshots; it is up to the JProbe user to do this when desired. Take snapshot on exit is also disabled because the exit of the application server is not necessarily something that will occur during the performance analysis session. All other options are disabled. The difference between profiling packages and classes is in the filters. The class mask used for the filters under package profiling uses the package name of each of the selected nodes and class name *; whereas under class profiling, the class name of the node is left intact. The table below outlines the differences in filters for various selection combinations. Type of profiling based on selections and menu choice The following table summarizes what will be profiled depending on which items are selected and which menu choice is made:
Selected Items Single node Multiple nodes from same class Multiple nodes from multiple classes in same package Menu Choice: Profile Selected Package(s) The nodes package result = 1 filter The nodes package result = 1 filter The nodes package result = 1 filter Menu Choice: Profile Selected Class(es) The nodes class result = 1 filter The nodes class result = 1 filter The nodes classes result = 1 filter per selected class - no duplicates The nodes classes result = 1 filter per selected class - no duplicates
Multiple nodes from multiple classes in multiple packages
The nodes packages result = 1 filter per selected package - no duplicates
1. Consult the JProbe documentation for more information on the function of triggers and filters and how they work together.
Foglight Integration
You can configure an action in Foglight that automatically starts a PerformaSure session when a threshold violation is detected. For more information, please see the Foglight Getting Started Guide for your cartridge.
Spotlight Integration
There are several ways to launch Spotlight from PerformaSure to check the entire application server or to check database problems more closely:
You can launch Spotlight on DB2, Spotlight on Oracle, Spotlight on WebLogic, or Spotlight on WebSphere from the Tools menu of the Project window or any browser (Tools > Performance Diagnostics) and from the toolbar of any browser. You can launch Spotlight on DB2 or Spotlight on Oracle by selecting a JDBC node in the Request Tree browser or a SQL statement in the detail pane of the SQL browser, right-clicking on that node or statement, and choosing Performance Diagnostics > Spotlight on DB2 or Spotlight on Oracle from the contextual menu.
Integration with Quest Database Tools

You can launch SQLab Vision for Oracle or SQL Tuning for DB2 to investigate how to improve database performance. There are several ways to launch these Quest database tools from PerformaSure:
You can launch SQLab Vision for Oracle or SQL Tuning for DB2 from the Tools menu of the Project window or from any browser (Tools > SQL Tuning) and from the toolbar of any browser. You can launch SQLab Vision for Oracle or SQL Tuning for DB2 by selecting a JDBC node in the Request Tree browser or a SQL statement in the detail pane of the SQL browser, right-clicking on that node or statement, and choosing SQL Tuning > SQLab Vision for Oracle or SQL Tuning for DB2 from the contextual menu.
Analyzing Sessions FAQ

I recorded a session from Oracle 9iAS with JMS and Message Driven Beans. When I view the session data in the Request Tree browser, related JMS calls and calls to the MDBs onMessage(...) method appear on different branches of the request tree. Why are the calls displayed this way? In PerformaSure 3.5, there is no context flow from JMS nodes to Message Driven Beans in sessions recorded from Oracle 9iAS. The reason for this is that, in Oracle 9iAS, there is no direct call chain from a JMS method to the Message Driven EJB that is displayed in the call tree. Instead, Oracle 9iAS implementation has a special thread (MessageDrivenHome.run()) that first calls javax.jms.MessageConsumer.receive(), gets the message, processes it, and then calls the MDBs onMessage(...) method. As a result, the related JMS calls and calls to the MDBs onMessage(...) method appear on separate branches of the call tree. In this case, there is no possible or meaningful context flow. I would like to be able to modify the existing templates, or create my own project templates. How can I do this? The Project templates that ship with PerformaSure are not hard-coded. In fact, it's easy to create your own Project templates. There may be many different reasons you want to do this, for example:
When youre working on a specific problem and recording a series of sessions with the same application servers, you frequently want to look at the same requests or metrics for each new session you record, without having to repeat the same selection process in the Request Time and Metrics browsers. Youve become comfortable with your own workflow and want to create a Project template to support it and that can be used with any session. You want to communicate your findings to other members of the organization and make it easy for them to navigate to the problem youve uncovered.
To create your own Project template:

1.
Open one of your sessions in a new Project. Select None from the Template drop-down menu in the New Project Wizard. In the Project, create and configure the browsers that you want to appear by default in the Project window. This Project will become your new template. For example, in a Metrics browser, open charts for the metrics that you want, but remember that metrics that are specific to one session may not show up in other sessions. Save the Project in the <performasure_home>/config/templates directory.
2.
3.
The next time you open a session in a new Project, you will be able to select that template from the drop-down menu in the New Project Wizard. Do the JPL files created by PerformaSure 3.5 work with the latest version of JProbe? The JPL file formats available in PerformaSure 3.5 are JProbe 4.x, JProbe 5.0, and JProbe 5.2. See Creating a JProbe Launcher File on page 332 for instructions on selecting a JPL file format and creating a JPL file.
Chapter 5
Isolating Performance Problems

Performance problems pop up in unexpected places. One might exist on your main page as a result of populating a choice box from fields in a database table. This could cause a slowdown for all end users even though most of them dont choose the option responsible for the slowdown. By observing that too many database calls are occurring, or by timing the inefficient SQL query, you can improve your main pages performance. But how do you determine which servlets are responsible? This section presents some general guidelines to help you isolate performance problems.
A Strategy for Finding Performance Problems

A performance team will generally approach a problem by following these steps. At each stage, profile your application with PerformaSure to see if problems arise as the application attempts to service the selected requests.
1.
Apply a load test that simulates a single user making a request. You can test, one by one, the common types of requests your application is designed to handle. At this stage, you may be able to detect requests that result in too many database calls or overly-long requests. Perform a load test using a single application server on a multi-processor machine. At this stage, you may be able to detect threading and serialization issues. Perform a load test on a cluster. At this stage, you may be able to test the operation of your application in a scenario that shouldnt be too far removed from your production system.
2.
3.
135
Part
II
The PerformaSure Workstation
Chapter 6
PerformaSure Workstation
The Workstation is PerformaSures graphical user interface (GUI). With it, you manage users, collect data, and explore and analyze sessions with the help of PerformaSures browsers (Request Time, SQL, Request Tree, Metrics, Network Traffic and Thresholds). The browsers give you detailed information about the minimum, average, and maximum times for platform and system metrics, and the time your application takes to process requests. As long as your system resources are sufficiently powerful, the licensed members of your team can run several Workstations simultaneously. You can use the Workstation to collect data and then hunt for performance problems by examining this data. PerformaSures browsers help expose the most time-consuming service requests as well as the critical paths of method calls within these requests, simplifying the task of analyzing the sessions you collect.
You use the Workstation to view historical data, not real-time events. If you are collecting new session data at the same time as you are viewing a previouslycollected session, the Nexus must process queries from the Workstation as well as receive and process data from Agents. You may find that the Nexus increases its sampling interval in this case. It is recommended that you separate the tasks of collecting data and of viewing sessions.
The Workstation displays the data as service requests, which you can follow through the various containers in your distributed application. If you load your system with hundreds of users, youll be able to measure the systems average behavior and compare it to the maximum request times that are also collected. The Workstation is not used for tasks like configuring your application server to work with PerformaSure or other setup tasks that require hand tooling. Configuration files are provided for this purpose; these files include sample configuration sections as comments. See the Installation and Configuration Guide for instructions on setting up your environment to work with PerformaSure.
139
Starting the Workstation

Logging In
There are three windows in the PerformaSure startup sequence.
1. PerformaSure Workstation Splash Screen

When you launch PerformaSure, a Splash screen appears. A progress meter indicates that the application is loading.
Figure 54
Figure 54
The splash screen for the PerformaSure Workstation
2. PerformaSure Login Window

To run the Workstation, you must first successfully log in through the Login window.
Figure 55
Figure 55
Login window for the Workstation
In the User Name and Password fields, enter your user name and the password assigned to you by your system administrator. If you do not specify a password, PerformaSure will assume that an empty password is associated with your username. Passwords are sent to the Nexus in encrypted format for user authentication.
Note:
You must have administrator privileges to add user names to the login database.
In addition to entering your username and password, you also need to choose the location of the Nexus that you would like to use for this session. Use the Nexus drop-down menu to select a Nexus instance, or click the Define... button to create or modify an instance that does not appear in the list. See Define Nexus Dialog on page 142 for details. Once you have entered all the information, click Login. If you click Exit, you will close PerformaSure. Login Errors If you see the login Error dialog, check that you have entered your user name and password exactly as it was assigned. Your user name is case sensitive, as is your password. If you continue to have difficulties logging on, ask your PerformaSure administrator for assistance.
Figure 56
Figure 56
The logon Error alert
If you see the Not Responding error dialog, check that the Nexus is running, that its address and port number are correct, and that the network connections are functioning.
Figure 57
Figure 57
Failure to connect to the Nexus results in this alert
PerformaSure Workstation 141
If you are running the Workstation on RedHat AS 3.0, the Workstation may be unable to connect to a remote Nexus and will log an error like the following:
2004-05-06 07:08:09.010 [Login Thread] ERROR com.sitraka.pas.workstation.login.LoginManager - Could not communicate with Nexus RMI server java.rmi.ConnectException: Connection refused to host: 127.0.0.1
This error occurs if RedHat AS 3.0 has installed localhost entries in the /etc/hosts file. Check this file for an entry like
127.0.0.1 localhost lrh4 where lrh4 is your machine name. If you see an entry like this, remove the
machine name from the line and then restart the Nexus and the Workstation. Using the same example, after editing this entry, the line should appear as follows:
127.0.0.1 localhost
Define Nexus Dialog The Define Nexus dialog (Figure 58) allows you to edit, add, or remove a Nexus instance. You can access it by clicking Define in the Login window (Figure 55).
Figure 58
Figure 58
The Define Nexus dialog
Define Nexus Dialog

Control
Nexus instances
Type
Table
Default Value
N/A
Description
Lists the Nexus instances that have been defined. This table has three columns: Alias, Address, and Port. See Nexus Instance Table below for more information. This button is enabled when you select a Nexus instance from the list. Click this button to launch the Edit Nexus dialog. Launches the Add Nexus dialog. This button is enabled when you select a Nexus instance from the list. Click it to remove that instance.
Edit... Add... Remove
Button Button Button
Disabled Enabled Disabled
Nexus Instance Table This table contains three columns:

Alias Lists the names that you chose for the Nexus machines. Address Lists the addresses for the Nexus machines. Port Lists the port numbers that the Agents use to transfer session data to the Nexus machines.
Edit... Select an instance from the list and click Edit... to launch the Edit Nexus dialog, which you can use to edit the properties of the instance that you selected. See Edit Nexus Dialog below for more information. Add... If the instance you would like to use does not appear in the list, click Add... to launch the Add Nexus dialog. You can use this dialog to add a Nexus instance to the list. See Add Nexus Dialog on page 144 for more information. Remove If there are items in the list that are no longer applicable, select the instance you want to delete from the list and click Remove. Edit Nexus Dialog The Edit Nexus dialog allows you to change the properties of an existing Nexus instance.
Figure 59
Figure 59
The Edit Nexus dialog
The fields that you can edit in this dialog are listed below. Alias Contains the display name of the Nexus you are editing. This is the name by which the Nexus is known in the Define Nexus dialog.
Address The IP address for the machine hosting the Nexus. Port The port on which this Nexus listens. Add Nexus Dialog The Add Nexus dialog allows you to define properties for a new Nexus instance.
Figure 60
Figure 60
The Add Nexus dialog
The fields that you can edit in this dialog are listed below. Alias When you launch the Add Nexus dialog, this field contains a default name such as Nexus 1. You can edit this field to specify a new display name for the Nexus; this is the name by which the Nexus is known in the Define Nexus dialog. Address The IP address for the machine hosting the Nexus. Port The port on which this Nexus listens.
3. Startup Window
Navigating the PerformaSure Workstation Startup window is the last step in the startup sequence. From this window, select the radio button that corresponds to your needs and then click OK. To exit PerformaSure, click Exit.
Figure 61
Figure 61
PerformaSure Startup window showing the Tools menu choices
Startup Window
Control
Record New Session Open Session in New Project Open Existing Project Open Recent Project Tools OK Exit
Type
Radio button Radio button Radio button Radio button and project list Drop-down menu Button Button
Default Value
Selected Not selected Not selected Not selected Enabled Enabled Enabled
Description
Opens the Recording Control window. Launches the New Project Wizard. Launches the Open file chooser. Opens the PerformaSure Project that you select from the project list. Displays a drop-down menu with four options. See Tools below for more information. Confirms your selection and opens the appropriate window or dialog. Closes the Startup window and exits PerformaSure.
Record New Session Select this radio button and click OK to open the Recording Control window. See Recording Control Window and nexusctl on page 177 for details about the fields and controls available in this window and for information about using the Recording Settings dialog and the Advanced Sampling dialog.
Open Session in New Project Select this radio button and click OK to launch the New Project Wizard, which allows you to create a new PerformaSure Project based on a previously-recorded session. You can open sessions recorded with version 3.0 and convert sessions recorded using version 2.0, 2.1, 2.2, or 2.3 for use with PerformaSure 3.5, but sessions recorded using version 1.1, 1.5, 1.6, or 1.7 of PerformaSure are obsolete and cannot be converted; see Converting a Session on page 148 for more information. See New Project Wizard on page 156 for details about creating a new Project. Open Existing Project Select this radio button and click OK to launch the Open file chooser.
Note:
An error dialog will appear if you attempt to open a Project associated with a session that was recorded using version 1.1, 1.5, 1.6, or 1.7 of PerformaSure. A session recorded with one of these versions of PerformaSure cannot be converted for use with PerformaSure 3.5.
Opening an Existing Project If you choose to open an existing Project, you must previously have saved a PerformaSure Project file (.sure) that you created with the help of the New Project Wizard. The Open file chooser allows you to navigate to the directory in which you saved the Project. By default, Projects are saved in the PerformaSure root directory.
Figure 62
Figure 62 Note:
Existing projects listed in the Open file chooser
Opening a Project causes a session file to be read. The following progress dialog appears while the session file is being scanned:
Figure 63
Figure 63
This alert appears while the session file is loading
When you try to open an existing Project, the Session Error dialog (Figure 64) will appear if there is no session currently associated with the Project that you have chosen, if the session cannot be found, or if the session is obsolete. See Converting a Session below for more information about obsolete sessions. If you see this error and there is another session that you wish to associate with the Project, click Yes to launch the Session Chooser dialog. If you click No, you will return to the Startup window (), from which you can create a new Project, record a new session, or open another existing Project.
Figure 64
Figure 64
The Session Error dialog
Troubleshooting: You may see the Session Error dialog if you have changed the location of the session files but have not updated the SessionDirectory configuration section in nexus.config.
To re-associate a Project with a session file that has been moved:
1. 2.
Click No to close the Session Error dialog. Shut down the Workstation (click Exit in the Startup window) and stop the Nexus. Open nexus.config. This file is located in PerformaSure3.5\config (Windows) or PerformaSure3.5/config (Solaris). Edit SessionDirectory to point the Nexus to the folder in which you are storing session files. See Changing the Sessions Directory on page 418 for more information. Save and close nexus.config. Restart the Nexus and the Workstation.
3.
4.
5. 6.
Converting a Session If you have upgraded to PerformaSure 3.5 from version 2.0, 2.1, 2.2, or 2.3 the Convert Session dialog (Figure 65) will appear when you try to open a session recorded with one of these versions of PerformaSure. This alert informs you that the session file format has changed and gives you the option of converting the session to the current format. Unless you plan to use the session in the earlier version as well as in the current version, you should convert it. If you have upgraded to PerformaSure 3.5 from version 1.1, 1.5, 1.6, or 1.7, you will not be able to open a session recorded with one of these versions of PerformaSure or convert it for use with PerformaSure 3.5. An error dialog will appear if you try to open an obsolete session in a new Project or if you try to open an existing Project associated with an obsolete session.
Figure 65
Figure 65
The Convert Session dialog
Open Recent Project Select this radio button and click OK to open the Project that you chose from the most-recently-used list. The available choices for recent Projects are shown in the text area directly below the button. Tools Click Tools to display a drop-down menu with five options (see ). The options in this menu are listed below. Session Management... Choose this option to open a dialog in which you can delete a session or edit its properties. See Session Management Dialog on page 151 for more information.
Change Password... Choose this option to open a dialog in which you can change your password. See Change Password Dialog on page 151 for more information. User Administration... Choose this option to open a dialog in which you can add new users and assign passwords. This option is disabled if you do not have administrator privileges. See User Management on page 149 for more information. Performance Diagnostics Choose this option to display a submenu with two options: Spotlight on WebSphere and Spotlight on WebLogic Server. Each choice is enabled if the corresponding Spotlight cartridge is installed. Logout Returns you to the Login window. User Management If you have administrator privileges, you can manage users through the User Management dialog. You open this dialog by selecting User Administration from the Tools drop-down menu in the Startup widow (). This menu item is disabled if you do not have administrator privileges.
Figure 66
Figure 66
The User Management dialog
User Management Dialog

Control
User Name
Type
Text field
Default Value
N/A
Description
Lists the users authorized to use PerformaSure. This text area is not editable: it simply displays a list of all the users authorized to use PerformaSure. For security reasons, only individuals with administrator privileges can add new users. The list of registered users (with their passwords) is kept in nexus-security.config. Opens the New User dialog. Deletes the selected user (after confirmation). This button is enabled when you select an entry in the User Name text field. Opens the Change Password dialog.
New User... Delete User... Change Password...
Button Button Button
Enabled Disabled Enabled
New User Dialog The New User dialog contains three required text fields in which you enter information about a new user: User Name, Password, and Confirm Password. The Password and Confirm Password fields must contain the same password. Type the user name that you would like to add in the User Name text field.
Figure 67
Figure 67
The Create New User window
Delete User Alert The Delete User alert allows an administrator to confirm the deletion of a registered user name from the system.
Figure 68
Figure 68
The Delete User alert
Change Password Dialog The Change Password dialog allows an administrator to change the password of any registered user; it also allows registered users to change their own passwords. You can access this dialog by selecting Tools > Change Password... from the Startup window.
Figure 69
Figure 69
The Change Password dialog
The fields and controls in the Change Password dialog are listed below.
Note:
Passwords are sent to the Nexus in encrypted format for user authentication.
User Name The User Name text area lists the registered name for the user whose password is being changed. Old Password Type the password that you want to change in the Old Password text field. New Password Type the new password in the New Password text field. Confirm Password Confirm the new password by retyping it in the Confirm Password text field. This text field must contain the same password as the New Password text field. Session Management Dialog Click the Session Management button in the toolbar of the Project window or select Tools > Session Management... from the Startup window, from the menu bar of the Project window, or from the menu bar of any browser to open the Session Management dialog.
Figure 70
Figure 70
The Session Management dialog
The fields and controls in this dialog are listed below. Edit Launches the Edit Session Properties dialog, which contains two editable text fields, Session Name and Comments. You can change the name of the session, add comments to the session, or edit any comments that were entered earlier.
Figure 71
Figure 71
The Edit Session Properties dialog
Delete Displays a Warning dialog asking you to confirm the deletion of the selected session. Click the Delete button to confirm deletion, or click Cancel to close the dialog without making any deletions.
Figure 72
Figure 72
The Delete Session alert
Upgrade If the selected session was recorded using version 2.0, 2.1, 2.2, or 2.3 of PerformaSure, you can click Upgrade to cause the session to be converted for use with PerformaSure 3.5. Converting a session results in faster operation of PerformaSure.
Chapter 7
PerformaSure Projects
Projects are PerformaSures central point of control. One important function of a Project is to choose a set of browsers that you use to view a sessions data. Each time you make a change to your distributed application, you will want to retest its functionality by collecting data about its behavior under load, or to see how it handles a particular type of request. One set of browsers may be appropriate for one session, while another set may work better for another session. Sometimes its even advisable to define two different scenarios for the same session. In each case, you use Projects to define the set of browsers associated with a session. Almost all aspects of a Project and its browsers that are user-configurable are saved to and restored from the Project file. This means that you can add as many browsers of each type as you want to your Project, adjust their settings to focus on the problems you have discovered, and when you reload the Project, the saved browsers are ready to be used again. If you make changes to any of these settings, you will be asked if you wish to save them when you close the Project. If you want to make a particular configuration global, save the Project as a template and use it each time you create a new Project. Besides associating browsers with a session, the Project window allows you to access several other windows and dialogs including the Recording Control window, from which you can start recording a new session, the New Project Wizard, which you can use to open a session in a new Project, and the Edit Options dialog, in which you can edit settings for the current Project, for the browsers, and for PerformaSure reports.
155
New Project Wizard

The New Project Wizard has two main areas: a Choose Session list, which lists the sessions available to the Nexus, and a details area, which provides information about the selected session.
Figure 73
Figure 73
The New Project Wizard
New Project WizardSummary

Control
Choose session Details area
Type
Selectable list List
Default Value
N/A N/A
Description
Lists the sessions available to the Nexus. Contains information about the selected session: Session Name, Version, Created by, Start date, End date, Length, Time slice, Detail level, and Comments. The Comments text area is scrollable when the comments added to the session do not fit in the details area. Permits you to order the list of available sessions by End Date or by Name.
Order By
Drop-down menu
End Date

Control
Template
Type
Drop-down menu
Default Value
Default
Description
Allows you to choose a template. The two static choices are None and Default. Any custom templates that you store in the config/templates subdirectory will also appear in this list.
New Project WizardFull Detail

Creating a New Project
To start the process of creating a new Project, select Open Session in New Project from the PerformaSure Startup window and then click OK. The New Project Wizard will be launched. Tip: Click the Open Session in New Project button in the Project windows toolbar or select Project > Open Session in New Project from the menu bar anytime you want to launch the New Project Wizard.
The New Project Wizard allows you to create a new, unnamed Project. You can add folders and browsers to your new Project, organize the browsers into folders, and rename folders and browsers or delete ones that you dont need. Projects are the best way to organize the information contained in session files. You can use Projects to share results with other members of your team and to archive results once a trouble spot has been identified.
Note:
New Projects are not saved automatically. To save a new Project, select Project > Save Project or Project > Save Project As.... If you do not supply an extension for the Project filename, PerformaSure will append the extension .sure.
The fields and controls in the New Project Wizard are described below. Choose Session Lists the recorded sessions that are available to the Nexus. Sessions can be listed by name or by the date and time the session stopped recording. See Order by below.
PerformaSure Projects 157
Details Area Information about the selected session is displayed in the details area. The fields in this area are described below. Session Name Lists the name assigned to the session. The name that you assign to a session in the Recording Control window is stored in the session file. The name is then modified to remove illegal and inconvenient characters, and this modified name is used as the session filename. Unless you rename the file, PerformaSure will continue to display the unmodified name stored in the session, rather than the filename, as the name of the session. The modified name appears in a listing of the sessions directory. Version Lists the version of PerformaSure that was used to record the session. Created by Lists the username under which the session was initiated. Start date Lists the date on which recording began for the selected session. The time at which recording began and the time zone are also listed in this field. End date Lists the date on which the session stopped recording. The time at which recording ended and the time zone are also listed in this field. Length Lists the total length of the session. Time slice Lists the time granularity of the collected data. Detail level Lists the detail level at which the session was collected (component or full).
Comments Lists any user-supplied description of the session. This text area is scrollable when the comments added to the session do not fit in the details area. Order by The Order by drop-down menu lets you sort the list of sessions by name or by the date and time at which the session stopped recording. Choices are by End Date or by Name. Template The Template drop-down menu allows you to select a sample Project. Sample Projects are kept in the config/templates subdirectory. Since these sample files have the same structure as any PerformaSure Project file, you can add your own template files to this directory. Any Project files that you add to the templates subdirectory will appear as available choices in the Template drop-down menu. The two static options in this menu are listed below. Default Select Default to create a Project using the Default template. The new Project will contain a Request Time browser that opens automatically, providing you with a starting point for your investigation. None Select None to create a Project without using a template. The Browsers area in the new Project will be empty.
The Project Window

The Project window (Figure 74) consists of a menu bar, a toolbar, a Session label, and a Browsers area. The Browsers area contains two panes, the navigation pane and the details pane. The Project windows menu bar and toolbar are described first.
Figure 74
Figure 74
The Project window
Menus and ToolbarSummary

Menu Bar
The Project windows menu bar is located along the top of the Project window. The following tables describe the controls available from the different menus in the menu bar. Project Window Menu BarProject Menu
Control
New Browser New Folder
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Opens the New Browser dialog. Use this dialog to choose the type of browser you want to launch. Launches the Add Folder dialog. Use this dialog to add a new folder to the Project and give it a name.
Project Window Menu BarProject Menu

Control
Open Session in New Project Open Project Close Save Project Save Project As Open Selected Items Delete Selected Items Edit Properties of Selected Item Project Properties Exit PerformaSure
Type
Menu item Menu item Menu item Menu item Menu item Menu item Menu item Menu item
Default Value
Enabled Enabled Enabled Enabled Enabled Disabled Disabled Disabled
Description
Opens the New Project Wizard. See New Project Wizard on page 156 for more information. Launches the Open file chooser. Use this file chooser to select the Project that you want to open. Closes the Project window. Saves the Project with its current settings. If you have never saved the Project, selecting this option launches the Save dialog. Launches the Save file chooser. Use this file chooser to save the Project and give it a name. Opens the selected browser windows. Deletes the selected browsers and/or folders from the Project. Opens the Browser Properties dialog or the Folder Properties dialog. See Edit Properties of Selected Item on page 166 for more information. Launches the Project Properties dialog. See Project Properties on page 167 for details. Closes all open Projects and browsers and shuts down the Workstation.
Menu item Menu item
Enabled Enabled
Project Window Menu BarTools Menu

Control
Recording Control Window Session Management Thresholds Change Password User Administration Performance Diagnostics
Type
Menu item Menu item Menu item Menu item Menu item Menu item
Default Value
Enabled Enabled Enabled Enabled Disabled N/A
Description
Launches the Recording Control window. Opens the Session Management dialog. Launches the Threshold Editor. Opens the Change Password dialog. Launches the User Management dialog. This menu item is enabled if you have administrator privileges. Displays a submenu from which you can select one of four options. See Performance Diagnostics on page 168 for more information. Displays a submenu with two choices. See SQL Tuning on page 168 for more information.
SQL Tuning
Menu item
N/A
Project Window Menu BarTools Menu

Control
Options
Type
Menu item
Default Value
Enabled
Description
Launches the Edit Options dialog.
Project Window Menu BarWindows Menu

Control
Bring All To Front [Switch to a Project window] [Switch to a browser]
Type
Menu item Menu item Menu item
Default Value
Enabled Enabled Enabled
Description
Ensures that all open PerformaSure windows have a higher stacking order than non-PerformaSure windows. Switches to the Project window that you select. Each menu item of this type will display the name of an open Project. Switches to the open browser that you select. Each menu item of this type will display the name of an open PerformaSure browser.
Request Time Browser Menu BarHelp Menu

Control
Help About
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Launches context-sensitive help. Opens a new window that displays product information about PerformaSure.
Toolbar
Under the Project windows menu bar is a toolbar with controls for performing actions like opening new PerformaSure browsers or launching the New Project Wizard, the Recording Control window, or the Session Management dialog. The following table describes the controls available from the toolbar. Project Window Toolbar
Control
New Browser
Type
Button and drop-down menu
Default Value
Enabled
Description
Clicking on the left-hand side of this button launches the New Browser dialog. See New Browser on page 163 for details. Clicking on the right-hand displays a dropdown menu from which you can choose the type of new browser that you want to open. See New Browser on page 169 for details.
Project Window Toolbar

Control
Save Project
Type
Button
Default Value
Enabled
Description
Saves the Project with its current settings. If you have never saved the Project, selecting this option launches the Save dialog. Launches the Project Properties dialog. See Project Properties on page 167 for details. Launches the Recording Control window. Opens the New Project Wizard. See New Project Wizard on page 156 for more information. Opens the Session Management dialog.
Properties Recording Control Window Open Session in New Project Session Management
Button Menu item Menu item Menu item
Enabled Enabled Enabled Enabled
Menus and ToolbarFull Detail

Menu BarProject
New Browser Select New Browser... to launch the New Browser dialog (Figure 75), which allows you to select and open a new browser of a specific type and give it a name. Keyboard accelerator: Ctrl-B.
Figure 75
Figure 75
The New Browser dialog
The new browser that you open using this dialog is not automatically added to the Project or listed in the Project window. See Adding Browsers on page 87 for more information about adding browsers to a Project. Tip: Add multiple browsers to a Project while you are using it to investigate a problem, then close the Project without saving it to avoid cluttering it with temporary browsers when they are no longer needed.
New Folder The New Folder... menu item launches the Add Folder dialog, which allows you to create and name a new folder and, if desired, add a description of the folders contents. Keyboard accelerator: Ctrl+Shift-N.
Figure 76
Figure 76
The Add Folder dialog
Click OK to add the folder to the Browsers area of the Project window. Tip: You can move an item to another folder by dragging. To place a newlyadded folder in an existing folder, drag the folders icon over the target folders icon. The cursor changes shape to indicate that a dragging operation is occurring: . Open Session in New Project The Open Session in New Project... menu item launches the New Project Wizard. See Creating a New Project on page 157 to learn how to create a new Project. Keyboard accelerator: Ctrl-N. Open Project Selecting Open Project... in the Project menu causes the Open file chooser to appear. You can use this file chooser to select the Project that you want to open. All PerformaSure Project files have a .sure extension. The default location for Project files is the PerformaSure3.5 directory, but they can be stored in any directory of your choice. Keyboard accelerator: Ctrl-O. Close The Close menu item closes the Project; the Workstation will remain open. Keyboard accelerator: Ctrl-W.
Save Project Select Save Project to save the Projects state, including the settings in all browsers that have been added to the Project. If you have never saved the Project, selecting this menu item launches the Save file chooser. Keyboard accelerator: Ctrl-S. Important: By default, Projects are saved in the PerformaSure3.5 directory. Browser settings are stored on a per-Project basis: they are saved with the Project to which the browser has been added. If you open a Project and then open a browser, that browser will have the same settings it had when the Project was last saved. If you open a Project and change a browsers settings, do not save the Project unless you want to replace the saved settings with the current ones. Save Project As Select Save Project As... to save a copy of the Project under a different name. When you select this option, the Save file chooser opens automatically, allowing you to navigate to the directory where you would like to save the Project. You provide a name for the Project in the File Name text field. If you dont supply it, PerformaSure will add the .sure extension to the Project filename. After you have clicked Save to save the new Project, you continue to work in that Project. The original Project is saved as it was at the time that you clicked Save Project As..., and any changes you make are saved in the new Project. Caution: If you enter a name in the File Name text field that is already taken by another Project in that directory, a warning dialog opens. If you choose Yes, you overwrite the previously saved version. Open Selected Items The Open Selected Items menu item is disabled until you select one or more browser icons (by clicking, shift-clicking, or control-clicking them) in the Browsers area. Selecting this menu item causes all selected browsers to be opened. Selecting a folder has no effect; to open browsers contained in a folder, first double-click the folder to show its contents and then select the browsers that you want to open.
Delete Selected Items The Delete Selected Items menu item removes the selected browsers or folders from the Project. Caution: Selecting a folder for deletion removes all browsers and subfolders contained in that folder from the Project.
Edit Properties of Selected Item Depending on the item that you selected in the Browsers area, selecting the Edit Properties of Selected Item... menu item launches either the Browser Properties dialog or the Folder Properties dialog. The changes that you make in these dialogs are saved when you save the Project. Browser Properties Dialog The Browser Properties dialog (Figure 77) allows you to rename the selected browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project.
Figure 77
Figure 77
The Browser Properties dialog
Folder Properties Dialog The Folder Properties dialog (Figure 78) allows you change the name of the selected folder and add comments about the types of browsers that it contains.
Figure 78
Figure 78
The Folder Properties dialog
Project Properties Select Project Properties... to open the Project Properties dialog, which allows you to add comments about the Project. You can use the Comments field in this dialog to describe the conditions under which session data was collected or to record your observations about this data. These comments are saved when you save the Project.
Figure 79
Figure 79
The Project Properties window
Exit PerformaSure Choose Exit PerformaSure to close all open Projects and browsers and shut down the Workstation. When you select this menu item, you may be prompted to save the Projects that are open or add new browsers to these Projects before closing the application.
Menu BarTools
Recording Control Window Select Recording Control Window... to launch the Recording Control window. See Recording Control Window on page 179 for more information about using the controls in this window.
Session Management Select Session Management... to open the Session Management dialog. See Session Management Dialog on page 151 for more information about using this dialog. Thresholds Select Thresholds... to launch the Threshold Editor. See Threshold Editor on page 392 for more information. Change Password Select Change Password... to open the Change Password dialog. See Change Password Dialog on page 151 for more information about using this dialog. User Administration Select User Administration... to launch the User Management dialog. See User Management on page 149 for details about using this dialog.
Note:
This menu item is disabled if you do not have administrator privileges.
Performance Diagnostics When you select the Performance Diagnostics menu item, a submenu is displayed from which you have four choices: Spotlight on Oracle, Spotlight on DB2, Spotlight on WebSphere, and Spotlight on WebLogic Server. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select Spotlight on WebSphere or Spotlight on WebLogic Server, Spotlight is launched to check the entire application server. When you select Spotlight on Oracle or Spotlight on DB2, Spotlight is launched to check database problems more closely. SQL Tuning When you select the SQL Tuning... menu item, a submenu is displayed from which you have two choices: SQLab Vision for Oracle, and SQL Tuning for DB2. Each choice is enabled if the corresponding cartridge is installed. Options Selecting the Options... menu item launches the Edit Options dialog. See Edit Options Dialog on page 215 for details about using this dialog.
Menu BarWindows
The Windows menus one static choice is Bring All To Front, which ensures that all open PerformaSure windows have a higher stacking order than nonPerformaSure windows. The other items in the Windows menu allow you to switch from one open Project window or browser to another. In addition to Bring All To Front, the Windows menu will always contain at least one item (for the Project window).
Menu BarHelp
Help The Help... menu item launches context-sensitive help for the Project window. About The About... menu item opens a new window in which product information about PerformaSure is displayed.
Toolbar
The Project windows toolbar is located directly below the menu bar.
Figure 80
Figure 80
The toolbar in the Project window
New Browser The New Browser... button has two parts. Click on the left-hand side of this button to launch the New Browser dialog, from which you can select the type of browser that you want and assign it a name; see New Browser on page 163 for more information about the New Browser dialog. Click on the right-hand side of the New Browser... button to display a drop-down menu from which you can choose the type of browser that you want. The options in the New Browser... drop-down menu (Figure 81) are listed below.
Figure 81
Figure 81
The options in the New Browser drop-down menu
New Request Time Browser Select New Request Time Browser to launch a new Request Time browser. New SQL Browser Select New SQL Browser to launch a new SQL browser. New Request Tree Browser Select New Request Tree Browser to launch a new Request Tree browser. New Metrics Browser Select New Metrics Browser to launch a new Metrics browser. New Network Traffic Browser Select New Network Traffic Browser to launch a new Network Traffic browser. New Thresholds Browser Select New Thresholds Browser to launch a new Thresholds browser. Save Click the Save button to save the Projects state, including the settings in all browsers that have been added to the Project. If you have never saved the Project, the Save file chooser will open when you click this button. See Save Project on page 165 for more information about saving Projects.
Recording Control Window Click the Recording Control Window button to launch the Recording Control window. See Recording Control Window on page 179 for more information about using the controls in this window. Open Session in New Project Click the Open Session in New Project button to launch the New Project Wizard. See Creating a New Project on page 157 to learn how to create a new Project. Session Management Click the Session Management button to open the Session Management dialog. See Session Management Dialog on page 151 for more information about using this dialog. Properties Click the Properties button to launch the Project Properties dialog. See Project Properties on page 167 for more information about using this dialog.
The Session Label

Next to the Session label is the name of the session currently associated with the Project.
Changing the Name of a Session

To change the name of a session:
1.
In the Project window, click the Session Management button in the toolbar or select Tools > Session Management... from the menu bar. The Session Management dialog will appear. Select a session from the Choose session list and click the Edit button. The Edit Session Properties dialog will appear. Edit the Session Name field in the Edit Session Properties dialog and click OK. Click Close in the Session Management dialog.
2.
3. 4.
Browsers Area
The Browsers area (Figure 82) has two parts: the navigation pane and the details pane. The navigation pane contains the browsers that are currently associated with the Project and the folders into which they are organized. The details pane displays information about the Project or about the browser or folder that is currently selected in the navigation pane.
Figure 82
Figure 82
The Browsers area in the Project window
Tip: You can reposition items in the navigation pane by clicking and dragging them. For example, to place a newly-added browser in an existing folder, drag the browsers icon to the folder icon. The cursor changes shape to indicate that a dragging operation is occurring: . All the browsers that you have added to your Project are listed in the navigation pane; you can open more browsers and add them to your Project at any time. See Adding Browsers on page 87 for instructions on launching a new browser and adding it to the Project. See Organizing the Navigation Pane on page 88 for instructions on adding folders to the Project and organizing the contents of the navigation pane. Tip: You can navigate the navigation pane using your keyboard. To select a different folder or browser in the navigation pane, use the up and down arrow keys. To expand and collapse folders, use the right and left arrow keys.
Contextual Menus in the Browsers Area

You can right-click anywhere in the navigation pane of the Browsers area to make a contextual menu appear. The items in this menu will differ depending on where you right-click with the mouse. Right-clicking in the navigation pane Right-click anywhere on the blank space in the navigation pane (when no folders or browsers are selected) and a menu containing three options will appear. The options in this menu are listed below. New Browser Select New Browser... to launch the New Browser dialog. See New Browser on page 163 for more information about using this dialog. New Folder Select New Folder... to launch the Add Folder dialog. See New Folder on page 164 for more information about using this dialog. Project Properties Select Project Properties... to launch the Project Properties dialog. See Project Properties on page 167 for more information about using this dialog. Right-clicking on a folder Right-click on a folder (or anywhere in the blank space in the navigation pane when a folder is selected) and a menu containing three options will appear. The options in this menu are listed below. New Folder Select New Folder... to launch the Add Folder dialog. See New Folder on page 164 for more information about using this dialog. Delete When you select Delete, a dialog appears asking you to confirm the deletion of the selected Project item.
Figure 83
Figure 83
An attempt to delete a Project item produces this dialog
Edit Properties Select Edit Properties... to launch the Folder Properties dialog. See Folder Properties Dialog on page 166 for more information about using this dialog. Right-clicking on a browser Right-click on a browser (or anywhere in the blank space in the navigation pane when a browser is selected) and a menu containing three options will appear. The options in this menu are listed below. Open Select Open to open the selected browser. Delete See Delete above. Edit Properties Select Edit Properties... to launch the Browser Properties dialog. See Browser Properties Dialog on page 166 for more information about using this dialog.
Session log dialog

If you see the icon at the left of the session name in the Project window, there are errors in the log file that was written when the data was collected. Click the icon to see a dialog containing the error messages.
Figure 84
Figure 84
The Session log dialog containing Nexus log file messages
PerformaSure Projects FAQ

How do I delete a Project? You can delete a session using the Session Management dialog. To delete a Project, you have to remove it using an operating system utility.
Chapter 8
Recording Control Window and nexusctl

You can use the Recording Control window to see which Agents are enabled, configure recording settings, and collect session data. It can be opened from the Startup window, from the Tools menu in the Project window, or in any browser.
Figure 85
Figure 85
The Recording Control window
The Recording Control window includes configuration controls for:
Setting the name for the session and adding descriptive comments. See Session Name on page 180 and Comments on page 181 for more information. Enabling or disabling Agents and resetting the list of Agents. See Agents Table on page 182 for more information.
177
Starting to record a session and issuing a stop command. See Record on page 183 and Stop on page 183 for more information.
The tabs in the Recording Settings dialog include configuration controls for:
Setting a duration for the session. See Limit Session Length on page 186 and Time on page 187 for more information. Setting the Time Slice Size. See Setting the Session Time Slice on page 75 and Time Slice Size on page 187 for more details about defining a Time Slice. Setting the Incomplete Request Timeout. See Incomplete Request Timeout on page 187 for more details about this setting. Selecting an option that requests confirmation before a recording session is stopped. See Confirm Before Stopping Recording on page 188 for more information. Selecting whether fewer than the maximum possible samples should be taken. See Service Request Sampling on page 70, A Note on Sampling on page 188, Collect As Many Samples as Possible on page 189, and Collect Fewer Samples to Reduce Overhead on page 189 for more information. Choosing whether to collect data at the component detail level or at the full detail level. See Component Detail Recording Level on page 190 and Full Detail Recording Level on page 190 for more information. Specifying URL expressions and parameters for request separation. See Service Request Separation on page 71 and Separators Tab on page 190. Setting filters for including or excluding requests. See Service Request Filtering on page 73 for details.
The Advanced Sampling dialog includes configuration controls for:
Setting sampling weights. See Changing Sampling Weights on page 196 for details.
The recording controls listed above are also available in the the command-line utility nexusctl. See Recording with nexusctl on page 198 and Equivalent Recording Control Options on page 209 for details.
Recording Control Window

Recording Control WindowSummary
The Recording Control window (Figure 85) has the following settings: Recording Control Window
Control Session Name Append Date and Time to Session Name Comments Time Slice Size Detail Level Settings... Status Elapsed Time Of Type Text field Checkbox Default Value User name Checked Description Edit this field to give the session a descriptive name. When checked, a full date string is appended to the Session Name.
Text field Info only Info only Button Info only Info only Info only
Blank 1 minute Component Always enabled Idle Blank Blank
Use this field to record reminders about the purpose of the session. Shows the value of the time slice. Use the Recording Settings dialog (Session tab) to change the value. Shows the value of the recording level. Use the Recording Settings dialog (Sampling tab) to change the value. Launches the Recording Settings tabbed dialog. The settings are described in Recording Settings DialogSummary. Shows the value of the recording status. The status changes when you start or stop recording. Shows the elapsed time when recording a session. Shows the session recording length specified in the Recording Settings dialog or the estimated amount of time remaining for PerformaSure to save the session. See Of below for more details. Shows the session recording progress if the length of the session was specified in the Recording Settings dialog. This bar is disabled when the recording status is Idle. Has these fields: Enabled, Agent Name, Hostname, Type, Version, and State. When checked, the sessions Project window opens as soon as recording stops, allowing you to begin your investigation right away. Resets the Agent list. This button is disabled during recording.
Status Bar
Progress bar Table Checkbox
Disabled
Agents table Open Session When Recording Completes Reset Agent List
Empty Checked
Button
Enabled
Recording Control Window and nexusctl 179
Recording Control Window (Continued)

Control Record Stop Type Button Button Default Value Enabled when not recording Enabled when recording Description Initiates recording. Messages are sent to all enabled Agents instructing them to send data to the Nexus. Stops recording.
Recording Control WindowFull Detail

Using the Recording Control Window
All fields in the Recording Control window except Session Name and Comments are saved between executions. The next time you invoke the Recording Control window, the parameters will have the values that you last set. The fields and controls in the Recording Control window are described below. Session Name The name of the session appears in this editable text field. By default, the name of the current user of the Workstation appears. The full name of the session depends on whether Append Date and Time to Session Name is checked. If it is, a full date string is appended to the content of this field. Choose a name that describes the purpose of the test, and let the date portion act as an index that distinguishes this session from other similiarly-named sessions. The file on disk has an extension psdat. Example:
LongRunningExample_2003-Oct-14_11-34-36.psdat
Attempting to overwrite an existing session The system compares the name in the Session Name text box with existing sessions. If that name exists, PerformaSure adds a suffix to the new file name to ensure that its name is different from the existing file. Append Date and Time to Session Name Use this checkbox to control whether a date string is appended to the session filename. This string contains the date and time at which recording began.
Comments You can record reminders about the purpose of the session in the Comments text area. Time Slice Size This area shows the value of the time slice that will be used when you begin recording. The default value of the time slice is 1 minute. To change this value, navigate to the Session tab of the Recording Settings dialog by selecting Settings ... > Session. See Session Tab on page 186 for details about the configuration settings in this tab and Setting the Session Time Slice on page 75 for more information about setting time slice values. Detail Level This area shows the value of the recording level. The default setting is Component. To change this value, navigate to the Sampling tab of the Recording Settings dialog by selecting Settings ... > Sampling. See Sampling Tab on page 188 for details. Settings This button launches the Recording Settings dialog. This dialog has four tabs Session, Sampling, Separating, and Filtersfrom which you can change the default values displayed in the Recording Control window and set custom recording settings. Status This area shows the recording status. Its default value is Idle; this area can also display Recording or Saving Session. The status changes when you start or stop recording. Elapsed Time When you are recording a session, this field shows the elapsed time. It is blank when the value displayed in the Status area is Idle. Of This area displays either the session recording length that you specified in the Recording Settings dialog or the estimated amount of time remaining for PerformaSure to save the session. If the session length is not specified, this area will display (Unlimited). If the estimated amount of time required to save the session is not known, this field will display (Unknown). If the estimated amount of time required to save a session is known, this field will display that amount of
time followed by (Estimate). This field is blank when the value displayed in the Status area is Idle. Status Bar If you specify the length of the session in the Recording Settings dialog, the Status Bar shows the sessions recording progress. The Status Bar is disabled and reset when the value displayed in the Status area is Idle. Agents Table You can use this text area to view which Agents are active and connected and control whether they are enabled. For each entry, the text area lists the Agent name and whether it is enabled, the host machine name, the type of Agent, and its state.
Note:
If the checkbox is selected next to an Agent, it is enabled. Deselect the checkbox to disable an Agent.
The Agent type can be: Server, in which case the type of server is shown. System, indicating a System Agent is installed on the machine so that operating system and network traffic metrics can be collected. The Agent version and state: Versionthe version number of the Agent. For example, 3.5. Statewhether the Agent is connected or disconnected. Open Session When Recording Completes This checkbox is selected by default. When it is selected, the sessions Project window opens (using the last selected Project template) and the Recording Control window closes as soon as recording stops. This occurs both when a user has clicked the Stop button and when the session has stopped recording automatically because it was set for a specified length. This configuration setting allows you to begin your investigation right away. Reset Agent List By clicking this button, you cause the Nexus to reset the Agent list. When this occurs, all Agents that are not connected are removed from the Agent list. This button is disabled during recording.
Record This button causes PerformaSure to start collecting session data. Clicking Record initiates recording by sending messages to all enabled Agents instructing them to send data to the Nexus. This button is disabled when you are recording. Stop This button causes PerformaSure to stop collecting session data. Stop Recording Dialog If you have checked the Confirm Before Stopping Recording checkbox in the Session tab of the Recording Settings dialog, the dialog shown in Figure 86 appears when the Stop button is clicked. When this dialog appears, click Yes to stop recording or No to continue collecting session data. See Confirm Before Stopping Recording on page 188 for more information.
Figure 86
Figure 86
This dialog may appear when you click the Stop button
Recording Settings Dialog

The tabs in the Recording Settings dialog (Figure 87, Figure 88, Figure 89, and Figure 90) contain fields and controls for configuring the recording settings for a new session.
Recording Settings DialogSummary

Recording Settings dialogSession tab
Control Limit Session Length Time Time Slice Size Type Checkbox Editable spinners Dropdown menus Editable spinners Checkbox Default Value Not selected Disabled 1 minute Description When checked, the Time spin boxes are enabled. Used to set the duration of the session in hours, minutes, and seconds. Used to set PerformaSures aggregation interval. See Setting the Session Time Slice on page 75 for more details. Used to set the incomplete request timeout, the time after which the Nexus no longer waits before classifying a request as incomplete. See Incomplete Request Timeout below for details. If checked, an Alert pops up when the Stop button in the Recording Control window is clicked. This alert does not appear if you have selected Limit Session Length and set the duration of the session.
Incomplete Request Timeout Confirm Before Stopping Recording
2 minutes
Enabled
Recording Settings dialogSampling tab

Control Collect as Many Samples as Possible Choose Fewer Samples to Reduce Overhead Type Radio button Radio button Default Value Selected Description Inform the Nexus that it should attempt to collect as many samples as it can. Choosing this setting places a load on the running system that can be diminished by choosing to collect fewer samples. Enables the Few Samples...Many Samples slider when selected. Fewer samples means less overhead on the system, but requests of a given type that complete during the time slice are sampled at least once. There is no scale on the slider because many factors influence how many samples are taken. See A Note on Sampling below. Reduces overhead and simplifies the call trees in the Request Tree browser by collecting data only on bellwether J2EE classes and methods. This is a useful setting for reducing overhead. See Recording Levels on page 61 and for more information. Selecting this recording level means that all classes and methods involved in processing a service request will be instrumented unless certain configuration settings have been set in nexus.config. See Full Detail Recording Level on page 64 for more information.
Not selected
Component Detail Recording Level
Radio button
Selected
Full Detail Recording Level
Radio button
Not selected
Recording Settings dialogSampling tab

Control Use Advanced Sampling Methods Advanced... Type Checkbox Default Value Not selected Description Allows you to override the sampling weights that PerformaSure assigns to requests. When this checkbox is selected, the sampling weights set in the Advanced Sampling dialog are used. Clicking this button opens the Advanced Sampling dialog. See Advanced Sampling Dialog below for details.
Button
Enabled
Recording Settings dialogSeparators tab

Control Separate HTTP requests that match, in order Add new entry Remove selection Move selection up Move selection down Maximum length of value used for separation Type Table Default Value Empty Description Has these fields: URL Expression, Type, and Parameters. Contains descriptions of HTTP requests that should be separated based on Query or Post arguments. See Separators Tab below for details. Adds a new entry to the list. Removes the selected entry from the list. Moves the selected entry up the list. Moves the selected entry down the list. Allows you to set the maximum parameter value length used for performing request separation. This value is used for all parameters. Its default value is 32; it can be set to any value between 1 and 512
Button Button Button Button Spinner box
Enabled Disabled Disabled Disabled Disabled
Recording Settings dialogFilters tab

Control Include or exclude requests that match, in order Add new entry Remove selection Move selection up Move selection down Type Table Default Value Empty Description Contains filters that describe conditions under which requests should be either included or excluded. See Include or exclude requests that match, in order below for details. Adds a new entry to the list. Removes the selected entry from the list. Moves the selected entry up the list. Moves the selected entry down the list.
Button Button Button Button
Enabled Disabled Disabled Disabled
Recording Settings dialogFilters tab

Control All other requests should be Type Dropdown menu Default Value Included Description Allows you to select whether service requests that do not match the entries in the table are included or excluded. The options are Included or Excluded.
Recording Settings DialogFull Detail

The button bar at the bottom of the dialog contains an OK button to commit any changes and close the dialog, a Cancel button to exit the dialog without commiting changes, and a Help button to launch context-sensitive help. This button bar appears at the bottom of every tab in the dialog.
Session Tab
Figure 87
Figure 87
The Recording Settings dialog showing the Session tab
Limit Session Length The Limit Session Length checkbox enables the Time spin boxes. This checkbox is not selected by default.
Time Time has three associated spin boxes that you can use to specify the duration of the session (hours, minutes, and seconds). You can also edit each of these values by typing in the appropriate text field. Time Slice Size Time Slice Size has two associated drop-down menus for setting the granularity of the collected data. The default time slice is one minute, which means that all events occurring within one minute intervals are assumed to have happened at the same time for presentation purposes. If you set a new time slice size that size is remembered. When you generate a new session, the previous value of the time slice becomes the current setting. The time slice size determines how finely you can time events. When you are analyzing a session, you can zoom in to or out of a browsers Timeline or change the length of the Timeline that is spanned by the Zonar. These changes affect how a time slice is displayed in a browsers Time Control panel and (where applicable) alter the size of the space between time slices on the x-axis of metric charts, but they are display changes only. The time slice size you set when initiating a session is the smallest increment of time achievable for analysis after the data has been recorded. Incomplete Request Timeout You can use the Incomplete Request Timeout editable spinner boxes to set the time after which the Nexus will no longer wait before classifying a request as incomplete. PerformaSure classifies any request that has not completed within the period defined in Incomplete Request Timeout as incomplete. Performance timing is not recorded for an incomplete service request, but enough information is provided to help you identify what the request was doing when PerformaSure stopped tracking it. You can easily find and highlight incomplete requests in the Request Tree browser. It is important to understand that a request may have completed after the timeout period has ended. Because most requests typically complete very quickly, incomplete requests may indicate performance problems depending on the length of time defined in Incomplete Request Timeout.
The default setting for Incomplete Request Timeout is 2 minutes. This may be adjusted depending on the expected length of time for your application to complete requests. Example: In some cases, an application may be expected to have very long request-completion times, in which case you could adjust the value to an appropriately high number, such as 5 minutes.
Confirm Before Stopping Recording The Confirm Before Stopping Recording checkbox is selected by default. When this checkbox is selected, the dialog shown in Figure 86 will appear when you click the Stop button in the Recording Control window. When this dialog appears, you will need to enter confirmation (by clicking OK) before recording is stopped.
Note:
This alert does not appear if you have selected Limit Session Length and set the duration of the session using the Time spin boxes.
Sampling Tab
Figure 88
Figure 88
The Recording Settings dialog showing the Sampling tab
A Note on Sampling You can choose to sample fewer service requests rather than letting the Nexus sample as many as it can. This is particularly important when you are stresstesting your system and the number of requests per second becomes large. In that
case, the Nexus may collect fewer samples, yet be able to provide accurate statistical data. One solution is to further decrease the sample rate by adjusting the Few Samples ... Many Samples slider in the Sampling tab. Moving the slider to the left tells PerformaSure to collect fewer samples per unit of time. This is a means of reducing overhead, yet it permits useful data to be collected. If you are attempting to trace an intermittent problem, you may have to lengthen the time of your session to ensure that a statistically significant number of samples is taken. If you suspect a certain request is the cause, you can use the Advanced Sampling dialog to increase its sampling weight as an alternative to extending the time over which data is collected. See Advanced Sampling Dialog below for details.
Note:
Sampling is based on a particular requests frequency of occurrence. If a certain request R occurs 100 times during the sampling period, and there are a total of 1000 requests of all types in the same interval, the Nexus assigns a frequency of 10% to request R. Assume that the Nexus decides that it can collect complete Tag and Follow information on 50 requests during the sampling interval. It sends a message to its Agents to monitor 5 instances of the request R. The Agents monitor the 5 requests, spacing them uniformly throughout the sampling interval. Also, PerformaSure guards against omissions that might be introduced by strict random sampling. It adjusts its sampling behavior so that infrequent requests are sampled at least once.
Collect As Many Samples as Possible Choose Collect as Many Samples as Possible when you want PerformaSure to collect as much data as possible. When you select this option, requests will be sampled at 100% of the Nexus ability. When your test system is heavily loaded, Tagging and Following each request may not be feasible because PerformaSure logs an enormous amount of data for each request. In this case, the Nexus will adjust the sample rate to keep data collection within manageable bounds. Collect Fewer Samples to Reduce Overhead Choose Collect Fewer Samples to Reduce Overhead when you want to further reduce the number of requests that will be Tagged and Followed during the sampling interval. This lessens the overhead that PerformaSure places on your system while still providing diagnostic information. Sampling within the interval is random; this eliminates the possibility of overlooking some cyclic effect. PerformaSure makes this adjustment to strict random sampling: every request that enters the system during the sampling interval is measured at least once. Selecting this option enables the Few Samples ... Many Samples slider. When you move the slider to the extreme left, the fewest samples possible will be
collected during the sampling interval. When you move the slider to the extreme right, requests will be sampled at 100% of the Nexus ability, just like when you select Collect As Many Samples as Possible. Component Detail Recording Level Choose Component Detail Recording Level to collect data on key J2EE classes. See Component Instrumentation on page 433 for a description and a list of the J2EE components that are Tagged and Followed when using this option. Full Detail Recording Level Choose Full Detail Recording Level to fully instrument your application. Use Advanced Sampling Settings Selecting this checkbox allows you to override the sampling weights that PerformaSure assigns to requests. When this checkbox is checked, the sampling weights that you set in the Advanced Sampling dialog are used. Advanced Clicking on this button opens the Advanced Sampling dialog. Use this dialog to set sampling weights that override the weights that PerformaSure assigns to requests. See Advanced Sampling Dialog on page 195 for details.
Separators Tab
Figure 89
Figure 89
The Recording Settings dialog showing the Separators tab
Separate HTTP requests that match, in order The Separate HTTP requests that match, in order table contains contains descriptions of HTTP requests that should be separated based on Query or Post parameters. The order of this list is significant: PerformaSure will attempt to match service requests beginning at the top and will then move down the list. Expressions are case sensitive, will always match on partial strings and will match against the base URL of the request. You can edit entries in the table itself.
Note:
To enter or text in the entry that you have selected, double-click in the space that corresponds with the appropriate column (Expression or Parameters).
The first column contains checkboxes that you can select or deselect to enable or disable the separator entries to which they correspond. For a new entry, the checkbox is selected by default. No checkboxes are visible when the table is empty. The URL Expression column allows you to enter text and edit it in the table itself. The text that you enter into the table can be either a regular expression or a literal expression that is used to match requests that should be separated. For new entries, this column is empty by default. Important: A literal string is a string of characters that is interpreted literally, without any substitutions based on regular expression pattern-matching. Literal strings will be referred to as literal expressions in the Users Guide. See Regular Expressions on page 473 for more information about how regular expressions are used in PerformaSure. The Type column specifies the type of expression, either Literal or RegEx. In both cases, expressions are case sensitive and will match on partial strings. For new entries, this column specifies Literal by default. The Parameters column allows you to enter text and edit it in the table itself. Parameters are entered as a list of comma-separated values. The parameters that you specify are used to separate requests based on both Query and Post parameters. For new entries, this column is empty by default. Add New Entry The Add new entry button adds a new entry to the list. By default, each new entry is enabled and the columns URL Expression, Type, and Parameters contain the default values specified above.
Remove Selection The Remove selection button removes the selected entry from the list. This button is disabled until you select an entry. Move Selection Up The Move selection up button moves the selected entry up the list. This button is disabled until you select an entry. Move Selection Down The Move selection down button moves the selected entry down the list. This button is disabled until you select an entry. Maximum length of value used for separation The Maximum length of value used for separation spinner box allows you to set the maximum parameter value length used for performing request separation. This value is used for all parameters. It is set to 32 by default but can be set to any value between 1 and 512. Guidelines for Sevice Request Separation Standard J2EE practice includes the case of a single JSP or Servlet that contains arguments which it forwards to the appropriate processor. Normally, PerformaSure groups all requests that have the same base URL into a single request and provides aggregate statistics for it. In some cases, such as a Servlet that forwards requests to different processors based on URL parameters, treating them as separate requests can make analysis easier. You can use the controls in the Separators tab to split requests based on the URLs parameter.
Example uses:
You can apply a request separation pattern to URLs passed to WebLogic, WebSphere, Apache, and iPlanet servers. The pattern is applied to the parameter part of the URL that enters the system and forms the beginning of a request. For example, there may be a URL for a small business that lets qualified users log in, perform queries, and order stock. The URLs for these three operations are:
http://www.co.com/littlebusiness.jsp?cmd="login" http://www.co.com/littlebusiness.jsp?cmd="query" http://www.co.com/littlebusiness.jsp?cmd="order"
Because the base URL is the same, PerformaSure considers all these as part of the same request. The information collected for all three URLs is amalgamated into
one graph in its Request Tree browser. Because the three URLs perform different tasks, it makes sense to regard them as three separate requests.
Filters Tab
Tip: If you have specified request separation on a parameter in the Separators tab, you can filter requests on that parameter in the Filters tab.
Important: Requests for CSS, GIF, JPEG, JS, and PNG files are excluded by default. If you want to include any of these requests, specify the requests that should be included in the Include or exclude requests that match, in order table.
Figure 90
Figure 90
The Recording Settings dialog showing the Filters tab
Include or exclude requests that match, in order The Include or exclude requests that match, in order table contains filters that describe conditions under which requests should be either included or excluded. The order of this list is significant: PerformaSure will attempt to match filters beginning at the top and will then move down the list. Expressions are case sensitive, will always match on partial strings and will match against the name of the request. You can edit entries in the table itself.
Note:
To enter or text in the entry that you have selected, double-click in the space that corresponds with the appropriate column (Expression or Parameters).
The first column contains checkboxes that you can select or deselect to enable or disable the filter entries to which they correspond. For a new entry, the checkbox is selected by default. No checkboxes appear when the table is empty. The Action column contains a drop-down menu that allows you to specify either Exclude or Include. For new entries, this column specifies to Exclude by default. The Expression column allows you to enter text and edit it in the table itself. The text that you enter into the table can be either a regular expression or a literal expression that is used to match requests that should be filtered. For new entries, this column is empty by default. The Type column specifies the type of expression, either Literal or RegEx. In both cases, expressions are case sensitive and will match on partial strings. For new entries, this column specifies Literal by default. Add New Entry The Add new entry button adds a new entry to the list. By default, each new entry is enabled and the columns Action, Expression, and Type contain the default values specified above. Remove Selection The Remove selection button removes the selected entry from the list. This button is disabled until you select an entry. Move Selection Up The Move selection up button moves the selected entry up the list. This button is disabled until you select an entry. Move Selection Down The Move selection down button moves the selected entry down the list. This button is disabled until you select an entry.
All Other Requests Should Be The All other requests should be drop-down menu allows you to select whether service requests that do not match the entries in the table are included or excluded. The options are Included or Excluded; the menu specifies Included by default.
Advanced Sampling Dialog

Advanced Sampling DialogSummary
The Advanced Sampling dialog (Figure 91) opens when you click Advanced... in the Sampling tab of the Recording Settings dialog. You can use this dialog to set sampling weights that override those automatically set by PerformaSure. Advanced Sampling Dialog
Control Set sampling weights for requests that match, in order All other requests should be Add new entry Remove selection Move selection up Move selection down Type Table Default Value Empty Description Has these fields: Expression, Type, and Percent. Contains entries describing sampling weight overrides. See Set Sampling Weights For Requests That Match, In Order below for details. Shows the sampling weight remaining for all other requests. Adds a new entry to the table. Removes the selected entry from the table. Moves the selected entry up the list. Moves the selected entry down the list.
Info only Button Button Button Button
1.00 Enabled Disabled Disabled Disabled
Advanced Sampling DialogFull Detail

Figure 91
Figure 91
The Advanced Sampling dialog
Changing Sampling Weights

The Nexus maintains a table of historical data for the frequency of each service request that it processes. It uses this information to tell the Agents how many samples to take during the current sampling interval. In this way, the Nexus ensures that a weighted average of samples is taken. However, you may want to set the weights yourself. The Advanced Sampling dialog is useful when, in high volume situations, you want to adjust the sample ratios from their default values. Example: If the Nexus decides that it can comfortably track 150 requests per second from a certain Agent, and the current request frequency is 1500 requests per second, the Nexus directs the Agent to Tag and Follow every tenth request. Normally, there will be a mix of different request names, such as commitorder, enterstore, and so on. The Nexus records the frequency of occurence of each type and prorates them among the 150 measured ones. Let us say that commitorder accounts for 10% of the requests, so that 15 requests are actually followed. If you wanted to focus on this request, you could cause it to be weighted more than its natural frequency. To do so, in the Advanced Sampling dialogs Set sampling weights for requests that match, in order table, enter commitorder in the Expression column, select RegEx from the drop-down menu in the Type column, and enter 0.3 into the Weight column.
Tip: Entering 0 in the Weight column (of the Set sampling weights for requests that match, in order table) is not the same thing as filtering out the request. Any request matching the regular expression or literal expression that you enter into the table will be counted, but it wont be Tagged and Followed, so you wont be able to see any other information about it. The Request Tree browser shows only the root node of the request. If you want to filter out requests, use the configuration settings in the Filters tab of the Recording Settings dialog to do so. See Filters Tab for details. Set Sampling Weights For Requests That Match, In Order In the Set sampling weights for requests that match, in order table, you can enter text and select values in order to set sampling weight overrides. The entries can be edited in the table itself.
Note:
To enter or edit text in an entry that you have selected, double-click in the space that corresponds with the appropriate column (Expression or Weight).
The Expression column allows you to enter text and edit it in the table itself. The text that you enter can be either a regular expression or a literal expression that is used to match requests that should be weighted more than their natural frequency. Expressions are case sensitive and will always match on partial strings and match against the name of the request. For new entries, this column is empty by default. The Type column specifies the type of expression, either Literal or RegEx. In both cases, the expression is case sensitive and will match on partial strings. For new entries, this column specifies Literal by default. The Weight column allows you to enter a numerical value between 0.00 and 1.00 and edit it in the table itself. If the total of all entries is greater than 1.00 when you click OK (or click elsewhere in the table), a warning message will appear indicating that the values cannot total more than 1.00. PerformaSure will then normalize the entries to add up to 1.00 or less. If the values add up to exactly 1.00, a message will appear informing you that no other types of requests will be sampled. For the first entry in this table, the Weight column displays a value of 1.00 by default.
Weight of All Other Requests The text area Weight of all other requests shows the remaining sampling weight as a fraction of 1. This fractional percentage represents the sampling weight that will be applied to all requests not listed in the table. When there are no entries in the table or they are all set to 0.00, this area displays a value of 1.00. If there is only one entry in the table and you have not changed its weight from 1.00, then this area displays a value of 0.00. Add New Entry The Add new entry button adds a new entry to the list. By default, each new entry is enabled and the columns Expression, Type and Weight contain the default values specified above. Remove Selection The Remove selection button removes the selected entry from the list. This button is disabled until you select an entry. Move Selection Up The Move selection up button moves the selected entry up the list. This button is disabled until you select an entry. Move Selection Down The Move selection down button moves the selected entry down the list. This button is disabled until you select an entry.
Recording with nexusctl

You can use the options available in the nexusctl command-line utility to start and stop session recording, enable or disable Agents, and adjust settings for recording a session, sampling, request separation, and request filtering. This section discusses the options available in nexusctl that are analagous to the controls in the Workstations Recording Control window, Recording Settings dialog, and Advanced Sampling dialog. See Equivalent Recording Control Options on page 209 for a chart that details the corresponding recording controls in nexusctl and in the
Workstation. See Launching the Nexus from a Script on page 39 for a complete list of control options available in nexusctl.
nexusctlSummary
Recording Options in nexusctl
Option nexusctl startrecording nexusctl stoprecording Type Recording option Recording option Default Value Records with 1 minute time slice N/A Description Starts recording a new session, which is given the default name Nexus <timestamp>. Stops recording the current session.
Parameters for nexusctl start-recording

Parameter -n NAME Type Basic recording parameter Basic recording parameter Basic recording parameter Agent parameter Session parameter Session parameter Session parameter Sampling parameter Default Value Username Description Overrides the default session name with the name that you specify. See -n NAME below for details. Appends the time at which recording began to the sessions filename.
-a
Not set
-com COMMENTS -ad AGENTNAME -i -l nnn -t nnn -c
Not set
Allows you to supply comments about the session.
Not set Not set Not set 1 minute Set
Specifies which Agents are to be disabled. See -ad AGENTNAME below for details. Allows you to record indefinitely. Sets the duration of the session. See -l nnn below for details. Sets the time slice for the session. Records at component detail level.
Parameters for nexusctl start-recording

Parameter -f -s nn -swr nnn expression -swl nnn expression -srr URIregex PARAM -srl URIliteral PARAM -sl nn Type Sampling parameter Sampling parameter Sampling parameter Sampling parameter Request separation parameter Request separation parameter Request separation parameter Filtering parameter Filtering parameter Filtering parameter Filtering parameter Filtering parameter Filtering parameter Connection parameter Recording settings parameter Default Value Not set 100 Not set Description Records at full detail level. If you do not enter this parameter, PerformaSure will record at the component level. Sets the service request sampling percentage. Sets advanced sampling weights using regular expressions. See -swr nnn expression below for details about the format for setting sampling weights. Sets advanced sampling weights using literal expressions. See -swl nnn expression on page 204 for more information about literal expressions. Separates requests using regular expressions. See -srr URIregex PARAM below for details. Separates requests using literal expressions. See -srl URIliteral PARAM below for details. Sets the maximum length for a value used in request separation. The range for nn is 1 to 512. Filters requests for inclusion using regular expressions. See -fir expression below for details. Filters requests for inclusion using literal expressions. See -fil expression below for details. Filters requests for exclusion using regular expressions. See -fxr expression below for details. Filters requests for exclusion using literal expressions. See -fxl expression below for details. Includes all other requests (after filtering certain requests). Excludes all other requests (after filtering certain requests). Sets the connection URI for the Nexus when it is on another machine than the nexusctl script. Loads nexusctl settings that you have saved to a file. See Using A Recording Settings File below for details on using and overriding a recording settings file.
Not set
Not set
Not set
32
-fir expression -fil expression -fxr expression -fxl expression -ia -xa -r URI -o /path/to/ filename.ext
Not set Not set Not set Not set Set Not set Not set N/A
Parameters for nexusctl stop-recording

Parameter -r URI Type Connection parameter Default Value Not set Description Sets the connection URI for the Nexus when it is on another machine than the nexusctl script.
Options for Showing Connections to the Nexus

Option nexusctl showconnections nexusctl resetagent-list Type Display option Display option Default Value N/A N/A Description Shows all connections to the Nexus. Resets the list of Agents, removing the entries for Agents that have been disconnected. This command is disabled during recording.
nexusctlFull Detail
Recording Options
nexusctl start-recording The start-recording option allows you to start recording a new session. When you use this flag, a message appears in the console window that was used to start the Nexus initially. The name given to the session is Nexus <timestamp>. The default time slice for data-collection using start-recording is one minute like it is in the Recording Settings dialogs Session tab. See -t nnn below and Setting the Session Time Slice on page 75 for more information about the time slice size. This option permits a number of additional optional parameters. See Parameters for nexusctl start-recording below. nexusctl stop-recording The stop-recording control stops recording the current session.
This option stop-recording permits one optional parameter, -r URI. This parameter sets the connection URI for the Nexus. For example:
-r your.remote.host.com:42705
Use this flag when the Nexus is on another machine than the one on which the nexusctl script is located. Note that the script must not be moved from the directory in which it was installed. Parameters for nexusctl start-recording Basic Recording Parameters
-n NAME
The parameter -n NAME allows you to provide a customized name for the session. Specifying this parameter overrides the default session name with NAME. It is recommended that you always place double quotes around the name parameter. They are required if the name you choose for your session contains one or more spaces.
-a
The parameter -a appends the time at which recording began to the filename.
-com COMMENTS
The parameter -com COMMENTS allows you to supply comments about the session that you are recording or are about to record. Tip: Surround your comments with quotation marks to protect from shell escape confusion.
Agent Parameters
-ad AGENTNAME
The parameter -ad AGENTNAME specifies which Agents are to be disabled. AGENTNAME is a unique name given to each Agent, which you can specify in agent.config. You only need to provide a list of Agents to be disabled using -ad AGENTNAME. Unless they are specified to be disabled, PerformaSure will record
from any Agents connected to the Nexus. You can specify multiple -ad entries for a single nexusctl command. Tip: Surround Agent names with quotation marks to protect from shell escape confusion.
Session Parameters
-i
The parameter -i allows you to record indefinitely. To stop recording, issue the command nexusctl stop-recording later on.
-l nnn
The parameter -l nnn sets the duration of the session. The format for specifying the time is nnns for seconds, nnnm for minutes, or nnnh for hours. Thus, to record for 1 hour, you could use 3600s, 60m, or 1h.
Note:
You cannot record a session that is shorter than 10 seconds. If you attempt to record a session that is shorter than 10 seconds, PerformaSure will issue a WARN log message in the Nexus console and automatically record for 10 seconds.
-t nnn
The parameter -t nnn sets the time slice for the session. Use this option to change the default setting for the time slice, which sets the time granularity for the session. The time slice size determines how finely you can time events. The time slice size that you set when initiating a session is the smallest increment of time achievable for analysis after the data has been recorded. The format for specifying the time slice size is the same as the format for setting the duration of a session.
-irt nnn
The parameter -irt nnn sets the incomplete request timeout value, the length of time after which a request will be considered incomplete. The format for specifying the incomplete request timeout is the same as the format for specifying the duration of a session.
Sampling Parameters
-c
The parameter -c allows you to record at component detail level. Key J2EE components are recorded, which gives you an overall picture of the application. See Component Instrumentation on page 433 for the list of interfaces that are instrumented at this level of detail. Recording at the component detail level is the default setting.
-f
The parameter -f allows you to record at full detail level. If this flag is not present, recording will be at the component level.
-s nn
The parameter -s nn sets the service request sampling percentage. The range for nn is 1 to 100. By default, the Nexus collects as many samples as possible. You can reduce overhead by choosing to sample fewer service requests than the maximum allowable. For example, by setting nn to 50, you are instructing the Nexus to collect half as many samples as it could in each sampling interval.
-swr nnn expression
The parameter -swr nnn expression sets advanced sampling weights using a regular expression. For example:
-swr 0.43 estore/portal-.*\.jsp
The range for nnn is 0.00 to 1.00. The sum of all advanced sampling entries cannot be greater than 1.00, but does not have to equal 1.00. The remaining fractional percentage represents the sampling weight that will be applied to all other requests. When you use this parameter, the expression will be evaluated as a case-sensitive regular expression and will match on partial strings. You can specify multiple -swr entries for a single nexusctl command.
-swl nnn expression
The parameter -swl nnn expression sets advanced sampling weights using a literal expression. Important: A literal string is a string of characters that is interpreted literally, without any substitutions based on regular expression pattern-matching. Literal strings will be referred to as literal expressions in the Users Guide. See Regular Expressions on page 473 for more information about how regular expressions are used in PerformaSure.
For example:
-swl 0.32 estore/do
The range for nnn is 0.00 to 1.00. The sum of all advanced sampling entries cannot be greater than 1.00, but does not have to equal 1.00. The remaining fractional percentage represents the sampling weight that will be applied to all other requests. When you use this parameter, the expression will be evaluated as a case-sensitive literal expression and will match on partial strings. You can specify multiple -swl entries for a single nexusctl command.
Tip: Surround the expressions used to set sampling weights with quotation marks to protect from shell escape confusion.
Request Separation Parameters

-srr URIregex PARAM
The parameter -srr URIregex PARAM separates requests using a regular expression. For example:
-srr estore/portal-.*\.jsp country
You can specify multiple -srr entries for a single nexusctl command, but be aware that the order of the entries is significant. PerformaSure will interpret this order as an indication of priority.
-srl URIliteral PARAM
The parameter -srl URIliteral PARAM separates requests using a literal expression. For example:
-srl estore/do PARAM
You can specify multiple -srl entries for a single nexusctl command, but be aware that the order of the entries is significant. PerformaSure will interpret this order as an indication of priority.
Tip: Surround the expressions used to separate requests with quotation marks to protect from shell escape confusion.
-sl nn
The parameter -sl nn sets the maximum length for a value used in request separation. The range for nn is 1 to 512; the default value is 32. This is a global entry that will be applied to all request separation entries. Filtering Parameters Tip: If you have specified request separation on a parameter by entering a nexusctl request separation flag, you can filter requests on that parameter by using request filtering options.
Important: Requests for CSS, GIF, JPEG, JS, and PNG files are excluded by default. Specify -fir or -fir options if you want to include any of these requests.
-fir expression The parameter -fir expression filters requests for inclusion using a regular expression. For example:
-fir \.[Gg][Ii][Ff]($|\?)/
Important: The dollar sign ($) is a shell metacharacter in Unix. If you are running PerformaSure on a Unix system and want to include the dollar sign as a metacharacter in a regular expression, surround the expression with single quotes. For example:
-fir \.[Gg][Ii][Ff]($|\?)/
You can specify multiple -fir entries for a single nexusctl command, but be aware that the order of the entries is significant. PerformaSure will interpret this order as an indication of matching priority.
-fil expression
The parameter -fil expression filters requests for inclusion using a literal expression. For example:
-fil .JPG
You can specify multiple -fil entries for a single nexusctl command, but be aware that the order of the entries is significant. PerformaSure will interpret this order as an indication of matching priority.
-fxr expression
The parameter -fxr expression filters requests for exclusion using a regular expression. You can specify multiple -fxr entries for a single nexusctl command, but be aware that the order of the entries is significant. PerformaSure will interpret this order as an indication of matching priority.
-fxl expression
The parameter -fxl expression filters requests for exclusion using a literal expression. You can specify multiple -fxl entries for a single nexusctl command, but be aware that the order of the entries is significant. PerformaSure will interpret this order as an indication of matching priority.
Tip: You can surround the expressions used to filter requests with quotation marks to protect from shell escape confusion.
-ia
The parameter -ia includes all other requests.

-xa
The parameter -xa excludes all other requests.

Note:
If you do not specify either -ia or -xa, -ia will be applied by default. Only one of either -ia or -xa can be used, not both.
Connection Parameters
-r URI Sets the connection URI for the Nexus. For example: -r your.remote.host.com:42705
Use this flag when the Nexus is on another machine than the one in which the nexusctl script is located. Using A Recording Settings File
-o /path/to/filename.ext
The parameter -o /path/to/filename.ext loads nexusctl settings that you have saved to a file. Rather than having to specify a long list of options every time you want to record, you can enter the flags into a text file that specifies recording settings. An example path string is:
nexusctl start-recording -o /usr/performasure/nexusctloptions.txt
A recording settings file consists of one option per line; two entries cannot exist on the same line. Tip: You can surround path strings with quotation marks to protect from shell escape confusion.
To override a recording settings file:
A recording settings file acts as a base template for nexusctl commands. You can enter additional options to override this file. For example:
nexusctl start-recording -t 10s -s 100 -srl estore/do product -o usr/performasure/nexusctloptions.txt.
Showing Connections to the Nexus

nexusctl show-connections Shows all connections to the Nexus. This command lists all connected servers and Workstation users as well as the status of PerformaSure Agents. Alongside the column in which the Agents are listed is a column that contains entries indicating whether Agents are connected or disconnected. The three parameters listed below are optional.

-user Your PerformaSure login username. -pwd Your PerformaSure login password (if you have set oneotherwise omit
this parameter).
-r Sets the connection URI for a remote Nexus. Example usage: nexusctl show-connections -user lisa -pwd oboe789 -r your.remote.host.com:42705
Note:
The list of Agents is sorted so that enabled Agents are listed first and disabled Agents last. Among the enabled Agents, connected Agents are listed first and disconnected Agents last.
Resetting the Agent List

nexusctl reset-agent-list Resets the list of Agents. This command removes the entries for Agents that have been disconnected from the show-connections
list so that only currently connected Agents are listed. Issuing the command nexusctl reset-agent-list internally calls show-connections after removing disconnected Agents so that you can see which Agents remain. The three parameters listed below are optional.

-user Your PerformaSure login username. -pwd Your PerformaSure login password (if you have set oneotherwise omit
this parameter).
-r Sets the connection URI for a remote Nexus.
Example usage:
nexusctl show-connections -user lisa -pwd oboe789 -r your.remote.host.com:42705
Equivalent Recording Control Options

This table lists the equivalent recording controls in nexusctl and the Workstation. They are listed alphabetically by the first letter of the nexusctl option or parameter. See the appropriate sections above for more detailed descriptions of these controls. Recording controls in the Workstation and nexusctl
Action Append the time at which recording began to the session filename. nexusctl -a Workstation Append Date and Time to Session Name (checkbox) How to use nexusctl: enter this parameter with the startrecording option. Workstation: select this checkbox in the Recording Control window.
Recording controls in the Workstation and nexusctl

Action Specify which Agents are to be enabled or disabled. nexusctl -ad AGENTNAME Workstation Enabled (column in Agents table) How to use nexusctl: enter this parameter and specify an Agent name with the start-recording option only if you want to disable an Agent. Workstation: if you want to enable an Agent, select the checkbox in this column of the table in the Recording Control window; if you want to disable an Agent, deselect the checkbox. nexusctl: enter this parameter with the startrecording option. Workstation: click on this radio button in the Sampling tab of the Recording Settings dialog. nexusctl: enter this parameter and comments with the start-recording option. Workstation: enter comments in this text field in the Recording Control window. nexusctl: enter this parameter with the startrecording option. Workstation: click on this radio button in the Sampling tab of the Recording Settings dialog. nexusctl: enter this flag and the literal expression with the start-recording option. Workstation: in the table in the Filters tab of the Recording Settings dialog, select Include from the Action dropdown menu, check the checkbox, enter the literal expression, select Literal from the drop-down menu in the Type column and click OK. nexusctl: enter this flag and the regular expression with the start-recording option. Workstation: in the table in the Filters tab of the Recording Settings dialog, select Include from the Action dropdown menu, check the checkbox, enter the regular expression, select RegEx from the drop-down menu in the Type column and click OK.
Record at the component detail level.
-c
Component Detail Recording Level (radio button) Comments (text field)
Supply comments about a session.
-com COMMENTS
Record at the full detail level.
-f
Full Detail Recording Level (radio button)
Filter requests for inclusion using literal expressions.
-fil expression
Filters tab of the Recording Settings dialog
Filter requests for inclusion using regular expressions.
-fir expression

Action Filter requests for exclusion using literal expressions. nexusctl -fxl expression Workstation Filters tab of the Recording Settings dialog How to use nexusctl: enter this flag and the literal expression with the start-recording option. Workstation: in the table in the Filters tab of the Recording Settings dialog, select Exclude from the Action dropdown menu, check the checkbox, enter the literal expression, select Literal from the drop-down menu in the Type column and click OK.. nexusctl: enter this flag and the regular expression with the start-recording option. Workstation: in the table in the Filters tab of the Recording Settings dialog, select Exclude from the Action dropdown menu, check the checkbox, enter the regular expression, select RegEx from the drop-down menu in the Type column and click OK.. nexusctl: enter this parameter with the startrecording option. Workstation: deselect this checkbox in the Session tab of the Recording Settings dialog. nexusctl: enter this parameter with the startrecording option along with a parameter for filtering requests. Workstation: select Included from the dropdown menu in the Filters tab of the Recording Settings dialog. nexusctl: enter this parameter with the startrecording option and specify the session length. Workstation: select this checkbox and use the spin boxes in the Session tab of the Recording Settings dialog to customize the session length. nexusctl: enter this option. Workstation: press this button in the Recording Control window. nexusctl: enter this option. Workstation: Review the entries listed in this table.
Filter requests for exclusion using regular expressions.
-fxr expression
Record indefinitely
-i
Limit Session Length (checkbox)
Include all other requests (after filtering certain requests).
-ia
All other requests should be (drop-down menu)
Set the length of the session.
-l nnn
Limit Session Length (checkbox) and Time (editable spin boxes)
Reset the list of Agents so that only currently connected Agents are listed. Show all connections to the Nexus.
nexusctl resetagent-list
Reset Agent List
nexusctl showconnections
Agents table

Action Start recording a new session. Stop recording the current session. Specify the name for a session. nexusctl nexusctl startrecording nexusctl stoprecording -n NAME Workstation Record (button) How to use nexusctl: enter this option. Workstation: press this button in the Recording Control window. nexusctl: enter this option. Workstation: press this button in the Recording Control window. nexusctl: enter this parameter with the startrecording option and specify a session name. Workstation: enter a new name for the session in the text field in the Recording Control window. nexusctl: enter this parameter with the startrecording option and specify the sampling percentage. Workstation: in the Sampling tab of the Recording Settings dialog, select the Collect as Many Samples as Possible radio button or select the Collect Fewer Samples to Reduce Overhead radio button and set the position of the Few Samples ... Many Samples slider. nexusctl: enter this parameter with the startrecording option and specify a value. Workstation: in the Separators tab of the Recording Settings dialog, enter the maximum value in the box or set it using the spinner. nexusctl: enter this flag, the literal expression and PARAM with the start-recording option. Workstation: in the table in the Separators tab of the Recording Settings dialog, enter the literal expression, select Literal from the dropdown menu in the Type column, specify the parameters (param) and click OK. nexusctl: enter this flag, the regular expression, and the parameters with the startrecording option. Workstation: in the table in the Separators tab of the Recording Settings dialog, enter the regular expression, select RegEx from the drop-down menu in the Type column, specify the parameters and click OK.
Stop (button)
Session Name (text field)
Set the service request sampling percentage.
-s nn
Collect as Many Samples as Possible (radio button) or Collect Fewer Samples to Reduce Overhead (radio button) and Few Samples ... Many Samples (slider)
Set the maximum length for a value used in request separation.
-sl nn
Maximum length of value used for separation (editable spin box)
Separate requests using literal expressions.
-srl URIregex PARAM
Separators tab of the Recording Settings Dialog.
Separate requests using regular expressions.
-srr URIregex PARAM
Separators tab of the Recording Settings Dialog.

Action Set advanced sampling weights using literal expressions. nexusctl -swl nnn expression Workstation Use Advanced Sampling Settings (checkbox), Advanced (button), and Advanced Sampling dialog How to use nexusctl: enter this parameter with the startrecording option, specify a sampling weight, and enter the literal expression. Workstation: select this checkbox in the Sampling tab of the Recording Settings dialog and click on the Advanced... button. In the table in the Advanced Sampling dialog, enter the literal expression, set the sampling weight, select Literal from the drop-down menu in the Type column and click OK. nexusctl: enter this parameter with the startrecording option, specify a sampling weight, and enter the regular expression. Workstation: select this checkbox in the Sampling tab of the Recording Settings dialog and click on the Advanced... button. In the table in the Advanced Sampling dialog, enter the regular expression, set the sampling weight, select RegEx from the drop-down menu in the Type column and click OK. nexusctl: enter this parameter with the startrecording option and specify the time slice size. Workstation: use the associated drop-down menus to set the granularity of collected data. nexusctl: enter this parameter with the startrecording option along with a parameter for filtering requests. Workstation: select Excluded from the dropdown menu in the Filters tab of the Recording Settings dialog.
Set advanced sampling weights using regular expressions.
-swr nnn expression
Use Advanced Sampling Settings (checkbox), Advanced (button), and Advanced Sampling dialog
Set the time slice for the session.
-t nnn
Time Slice Size (associated drop-down menus)
Exclude all other requests (after filtering certain requests).
-xa
All other requests should be (drop-down menu)
Chapter 9
Edit Options Dialog

Selecting Options... from the Tools menu displays the Edit Options dialog.
Figure 92
Figure 92
The panes in the Edit Options dialog
215
From the appropriate pane in this dialog, you can customize themes, adjust certain properties of your Project, and configure aspects of the Request Tree browser, the Metrics browser, and PerformaSure Reports. Choose which pane is displayed by clicking on one of the following nodes in the tree view:
When you set options and click the Apply button, some settings take effect on the next browser you open. They are not applied to the current browser.
Browserscontains the Do not ask to add new browsers to project on closing of new browser or project checkbox. This checkbox controls whether or not PerformaSure will prompt you to add a new browser to your Project when you attempt to close that browser or the entire Project. Request Treecontains two checkboxes (Panner Updates Graph While Dragging and Hide Pruned Sub-Trees) and three options boxes (FastFind, JProbe Integration, and Open New Browser With These Settings). The checkbox Panner Updates Graph While Dragging is checked by default (update mode is automatically selected). If you choose not to use the update mode by deselcting this option, then the view in the graph pane will wait until you have released the mouse button before updating. Hide Pruned Sub-Trees is not checked by default. Selecting this option hides the pruned sub-trees completely; if this option is not selected, then pruned sub-trees will be greyed out. In the FastFind options box, you can choose how many of the top critical paths or nodes to expose. Use the drop-down menu in the JProbe Integration box to select a JPL file format. This menu allows you to specify which version of JProbe you are using. The options box Open New Browser With These Settings contains a drop-down menu that you can use to select which bundling mode is displayed in the tree view of a new Request Tree browser. The default bundling mode is Component; the other options are Class and Method. Metricsthis pane contains the checkbox Automatically Create New Columns When Adding Charts, which is checked by default. Reportsthis pane contains one box, PDF Report Logo, in which you can change the header information in PerformaSure generated reports. This box contains four options: Default PerformaSure Image: selected by default. Image: choose this option if you want to specify an image to use in the header. This button is accompanied by a text field and a browse button that invokes the file chooser. Text: choose this option if you want to customize the header text. This button is accompanied by a text field in which you can specify text. None: click on this button if you do not want to include a header in the report. Themesthis pane contains a drop-down menu with the choices Custom, White, and Black and four options boxes (Graphs, Metrics, Color Scale (Network & Tree Browsers), andRequest Tree Graph). Click on a color rectangle to launch the Select Color chooser. There are three ways of specifying the new color: color swatches, HSB, or RGB. If you click Apply after selecting new colors,
the themes are immediately updated in the browsers to which the settings apply. The options in the Graphs box are: Background, Text, Fill, Outline, and Highlight. In the Metrics box, you can set the color for the average metric. The Color Scale options box contains two color rectangles, which are used to set the extreme Hot and Cold colors in the Request Tree and Network Traffic browsers. Use the color rectangles in the Request Tree Graph box to set the Pruned Background and Pruned Foreground colors for the tree view.
Edit Options Dialog 217
Chapter 10
Time Control Panel

The following topics are covered in this chapter:

Time Control Panel Components in the Time Control Panel Related Controls
Time Control Panel

The Time Control panel consists of the components directly under the toolbar of every browser. The controls in this panel allow you to adjust the span of time for which you view the data in the session you recorded.
Components in the Time Control Panel

Figure 93
Figure 93
The Time Control Panel
The Time Control panel contains several elements, which are described below.
219
Timeline
The Timeline represents the total period of time during which the session was recorded. You can adjust how much of the Timeline is displayed (and in how much detail) by clicking the More Zone Detail (zoom in) button or the Less Zone Detail (zoom out) button. See More Zone Detail and Less Zone Detail below for more information. You can select portions of the Timeline with the Zonar, causing the browser that you are using to display data for that period only. There are major and minor tick marks on the Timeline that you can use as a guide when positioning the Zonar. Major tick marks correspond to time slice boundaries; they are labeled with the absolute time, not the time relative to the start of the session. Minor tick marks indicate the time slice boundaries between major tick marks. A unique tick mark with the date above it indicates midnight.
Zonar
The Zonar controls the interval of time for which data is viewed in a browser. When you move the Zonar or adjust its length, the session is queried and data is returned only for the interval that it spans. Covering a smaller portion of the Timeline with the Zonar can help you isolate a part of the session in which problems occur and obtain a more detailed picture of the system during that period of time. The Zonar can span all or part of the Timeline. Adjusting the position of its ends (by clicking and dragging them) changes the amount of time that is selected. By clicking the middle of the Zonar and dragging it, you can reposition it to cover a different range of time with the same length. Double-clicking the Zonar causes it to expand to fill the whole Timeline.
Note:
The ends of the Zonar snap to time slice boundaries. You cannot position either end of the Zonar in the middle of a time slice.
Data Availability Indicator

The Data Availability Indicator is the blue line located directly below the Timeline (see Figure 93). This line indicates the presence of data within the visible Timeline. In the Request Time, SQL, and Thresholds browsers, the Data Availability Indicator shows the presence of data in the graph pane. In the Metrics browser, it shows the
presence of data in the graph that is selected. In the Request Tree and Network Traffic browsers, it shows the presence of data based on the current filter settings.
More Zone Detail

The More Zone Detail button is located on the right-hand side of the Time Control panel. This button allows you to zoom in to the interval of the session spanned by the Zonar. If the visible Timeline includes more than one time slice, you can reduce the size of the Zonar to span a smaller portion of the Timeline and then click the More Zone Detail button to zoom in to that portion.
Note:
You can only zoom in when more than one time slice worth of Timeline is visible and when the Zonar is smaller than the visible Timeline. When you have zoomed in to the Timeline, it will display an arrow at one or both of its ends to indicate that the session extends beyond the visible time line.
Less Zone Detail

The Less Zone Detail button is located on the right-hand side of the Time Control panel. This button allows you to zoom out from a sub-interval of the session. Showing more of the Timeline allows you to adjust the Zonar to select a longer time span.
Timeline Labels
When the whole Timeline is visible, the session start time label (at the far left of the Timeline) and the session end time label (at the far right of the Timeline) display the start time and end time for the current session. The time is displayed in bold in these two Timeline labels, distinguishing them from the labels over major tick marks within the Timeline.
Figure 94
Figure 94
The Timeline labels and the Zonar Offset and Duration label in the Time Control panel
The Zonars offset from the start of the session and the length of time currently spanned by the Zonar are displayed in the Zonar offset and duration label at the top of the Time Control panel.
Time Control Panel 221
Related Controls
Certain controls in PerformaSures browsers are associated with the Time Control panel but are not located in it. These controls are described below.
Sightline
The Sightline is only available in the Request Time, SQL, Metrics, and Thresholds browsers. Although it is linked to the Zonar, it is located in the graph pane of these browsers, not in the Time Control Panel itself. The Sightlines slider is located at the top of the graph pane in the Request Time, SQL, and Thresholds browsers. In the Metrics browser, there is a Sightline and a Sightline slider for each graph. As shown in Figure 95, the Sightline is a broken line that extends downwards from the slider. The time to which a point in the graph corresponds is displayed next to the slider, along with the value charted at that point. The range of time through which you can move the Sightline reflects the range currently spanned by the Zonar. When you move the Sightlines slider, it will snap to time slice boundaries imposed by the Zonar.
Figure 95
Figure 95
The Sightline and its slider in the Metrics browser
PerformaSure draws a horizontal dashed line from the y-axis to the Sightlines current position in the chart along the x-axis. This allows you to accurately determine the measured quantitys ordinate. The point at which these two lines intersect is marked by small square colored by the active metric.
Link Browsers to Use Same Zone/Break Link Between Browsers

There is a button in the toolbar of every browser that allows you to toggle whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only.
Click the Link Browsers to Use Same Zone button to link the browsers Time Control panels. When linked, the Timeline, Zonar, and (where applicable) the Sightline of these browsers are in the same state as the browser in which the button was clicked. Using the controls in the Time Control panel of one browser will impact all other browsers as well. If a problem occurs during a specific interval spanned by the Zonar, linking the browsers can help you track this problem across different browsers. Click the Break Link Between Browsers button to return the browsers Time Control panels to an unlinked state. This allows each browsers Timeline, Zonar, and Sightline to function independently.
Query Progress Bar and Cancel Query Button

When you adjust the position of the Zonar, a query is sent to the Nexus to retrieve the data to be displayed in the browsers graph pane for the portion of the Timeline that you have selected. Queries can take some time. The Query Progress bar informs you that activity is going on, and you can interrupt the process by clicking the red Cancel Query button to the right of the Query Progress Bar.
Figure 96
Figure 96
The Query Progress Bar in its active state
Time Control Panel 223
Chapter 11
Request Time Browser

Request Time Browser Request Time Browser Modes Menus and ToolbarSummary Menus and ToolbarFull Detail Time Control Panel Request Time Browser Control PaneSummary Request Time Browser Control PaneFull Detail All Requests Mode Single Request Investigation Mode Request Time Browser Graph PaneSummary Request Time Browser Graph PaneFull Detail Charts in the Graph Pane Tooltips in the Graph Pane Contextual Menus in the Graph Pane Request Time Browser Detail Pane Detail Pane Columns Bar Charts in the Detail Pane Bar Chart Tooltips Contextual Menus in the Detail Pane Request Time Browser FAQ
225

The Request Time browser helps you identify expensive service requests. You use this browser to investigate performance metrics related to service requests over time, including the total time spent servicing each individual request. You can drill down to investigate a single request by tier, by component technology, or by server. You can also select a particular request and view its call tree or the metrics related to it. The Request Time browser launches automatically when you open a new PerformaSure Project, enabling you to start your investigation right away by isolating the request that is consuming the most time. Once you have identified an expensive request, you can launch a Request Tree browser browser to see all the methods and database calls in the request. Expensive calls are shown in a hot color in this browser, making it easy to identify time-consuming methods. If a cursory walkthrough of the methods code doesnt reveal the problem, use JProbe to profile the methods execution.
Figure 97
Figure 97
The Request Time browser
Request Time Browser Modes

The Request Time browser allows you to view response time data in All Requests mode or in Single Request Investigation mode. In All Requests mode, you can analyze requests in comparison to the overall response time of the system. When you find a request of interest, switch the browser into Single Request Investigation mode by drilling down into that request to investigate response time by tier, server, component technology, or component. Drilling down into a request in Single Request Investigation mode allows you to examine a number of different request metrics over time, helping you diagnose performance problems. For more information about using the Request Time browser its two investigation modes, see All Requests Mode on page 239 and Single Request Investigation Mode on page 242.

Menu Bar
The Request Time browsers menu bar is located along the top of the browser window. The following tables describe the controls available from the different menus in the menu bar. Request Time Browser Menu BarBrowser Menu
Control
New Browser Add New Browser To Project Export Report Properties Close Exit PerformaSure
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Opens the New Browser dialog. Use this dialog to choose the type of browser you want to launch. Adds the browser to your PerformaSure Project. A Request Time browser icon will appear in the Browsers area of the Project window. Begins the process of generating a print version of the browser suitable for inclusion in a report. Launches the Browser Properties dialog. See Properties on page 231 for details. Closes the browser. Closes all open Projects and browsers and shuts down the Workstation.
Menu item Menu item Menu item Menu item
Request Time Browser 227
Request Time Browser Menu BarView Menu

Control
Display By
Type
Menu item
Default Value
Tier
Description
Displays a submenu from which you can select either Tier or Component. Selecting one of these options changes the display mode of the charts in the graph and detail panes. Resizes the width of all columns in the table so that all values within each column are visible. Opens a dialog containing a group of checkboxes. Select or deselect these checkboxes to toggle the display of certain metrics in the detail pane. Opens a dialog containing a group of checkboxes. Select or deselect these checkboxes to toggle the display of certain bar charts in the detail pane columns. Toggles the display of the Filter Requests Bar at the bottom of the graph pane. See Show Filter Bar on page 232 for more information about the Filter Requests Bar.
Auto-Fit All Columns Show/Hide Columns
Menu item Menu item
Enabled Enabled
Show/Hide Bar Charts Show Filter Bar
Menu item
Enabled
Menu item with checkbox
Selected
Request Time Browser Menu BarTools Menu

Control
Type
Default Value
Description
Launches the Recording Control window. Opens the Session Management dialog. Launches the Threshold Editor. Opens the Change Password dialog. Launches the User Management dialog. This menu item is enabled if you have administrator privileges. Displays a submenu from which you can select one of four options. See Performance Diagnostics on page 233 for more information. Displays a submenu with two choices. See SQL Tuning on page 234 for more information. Launches the Edit Options dialog.
SQL Tuning Options
Menu item Menu item
N/A Enabled
Request Time Browser Menu BarWindows Menu

Control
Type
Default Value
Description
Request Time Browser Menu BarHelp Menu

Control
Help About
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Launches context-sensitive help for this browser. Opens a new window that displays product information about PerformaSure.
Toolbar
Under the Request Time browsers menu bar is a toolbar with controls for opening new PerformaSure browsers, launching Spotlight and Quest database tools, controling the view in the Request Time browsers graph and detail panes, and performing other actions like exporting a report. The following table describes the controls available from the toolbar. Request Time Browser Toolbar
Control
New Browser
Type
Default Value
Enabled
Description
Clicking on the left-hand side of this button launches the New Browser dialog. See New Browser on page 163 for details. Clicking on the right-hand displays a dropdown menu from which you can choose the type of new browser that you want to open. See New Browser on page 235 for details. Adds the browser to the Project. This button is disabled if you have already added the browser to the Project. Begins the process of generating a print version of the browser suitable for inclusion in a report.
Add New Browser To Project Export Report
Button Button
Enabled Enabled
Request Time Browser Toolbar

Control
Properties Performance Diagnostics SQL Tuning
Type
Button Button and drop-down menu Button and drop-down menu Button
Default Value
Enabled N/A
Description
Launches the Browser Properties dialog. See Properties on page 236 for details. Displays a drop-down menu with four choices. See Performance Diagnostics on page 236 for more information. Displays a drop-down menu with two choices. See SQL Tuning on page 236 for more information. Toggles whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. See Link Browsers to Use Same Zone/Break Link Between Browsers on page 237 for more information. Toggles the display of the detail pane.
N/A
Link Browsers To Use Same Zone/Break Link Between Browsers Show Detail/Hide Detail
Enabled
Button
Enabled

Menu BarBrowser Menu
New Browser Choose New Browser... to launch the New Browser dialog, which allows you to select and open a new browser of a specific type. The new browser is not automatically added to the Project or listed in the Project window. Keyboard accelerator: Ctrl-B. Add New Browser To Project The Add New Browser To Project menu item is enabled if you have not yet added this browser to the Project. Click this item to add the browser to the Project. A new Request Time browser icon will appear in the Browsers area of the Project window. Keyboard accelerator: Ctrl-A. Export Report Select Export Report... to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file
chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Keyboard accelerator: Ctrl-R. Properties Choose Properties... to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Close Select the Close menu item to close the browser but leave the Project open. Keyboard accelerator: Ctrl-W. Exit PerformaSure Choose Exit PerformaSure to close all open Projects and browsers and shut down the Workstation. When you select this menu item, you may be prompted to save the Projects that are open or add new browsers to these Projects before exiting PerformaSure.
Menu BarView
Display By Choose Display by... to display a submenu from which you can select one of two options: Tier or Component Technology. Tier is selected by default. Click the radio button associated with either Tier or Component Technology to change the display mode. Tier Coloring by tier allows you to distinguish the tiers of your application in the graph pane and in the response time metric bar charts in the detail pane. PerformaSure consistently assigns one color to each tier and one for each application server cluster. Component Technology Coloring by component technology allows you to distinguish component types in the graph pane and in the response time metric bar charts in the detail pane.
Components include HTTP, Servlets, EJBs, custom components, RMI, URL, JNDI, JMS, and JDBC. PerformaSure consistently assigns one color to each standard and custom component technology. Auto-Fit All Columns Click Auto-Fit All Columns to resize the width of all columns in the table so that all values within each column are visible. Show/Hide Columns You can choose whether or not to display certain metrics in the detail pane. Select Show/Hide Columns... to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated metric in a column in the detail pane. Show/Hide Bar Charts You can choose whether or not to display certain bar charts in the detail pane columns. Select Show/Hide Bar Charts to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated bar chart. Show Filter Bar Select or deselect the checkbox associated with the menu item Show Filter Bar to toggle the display of the Filter Requests bar at the bottom of the graph pane. You can enter a literal string or a regular expression in the Filter Requests bars Filter Requests text field. When you click the Apply button, the string or expression that you entered is matched against the service request names listed in the detail pane; only the requests that match are displayed in the graph pane and in the detail pane. By default, the Filter Requests text field contains an empty literal string so that all service requests are selected. Tip: If you enter a regular expression in the Filter Requests text field, ensure that the Use Regular Expression checkbox is selected before you click Apply.
Menu BarTools
Recording Control Window Select Recording Control Window... to launch the Recording Control window. See Recording Control Window on page 179 for more information about using the controls in this window. Session Management Select Session Management... to open the Session Management dialog. See Session Management Dialog on page 151 for more information about using this dialog. Thresholds Select Thresholds... to launch the Threshold Editor. See Threshold Editor on page 392 for more information. Change Password Select Change Password... to open the Change Password dialog. See Change Password Dialog on page 151 for more information about using this dialog. User Administration Select User Administration... to launch the User Management dialog. See User Management on page 149 for details about using this dialog.
Note:
This menu item is disabled if you do not have administrator privileges.
Performance Diagnostics When you select the Performance Diagnostics menu item, a submenu is displayed from which you have four choices: Spotlight on Oracle, Spotlight on DB2, Spotlight on WebSphere, and Spotlight on WebLogic. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select Spotlight on WebSphere or Spotlight on WebLogic Server, Spotlight is launched to check the entire application server. When you select Spotlight on Oracle or Spotlight on DB2, Spotlight is launched to check database problems more closely.
SQL Tuning When you select the SQL Tuning... menu item, a submenu is displayed from which you have two choices: SQLab Vision for Oracle, and SQL Tuning for DB2. Each choice is enabled if the corresponding cartridge is installed. Options Selecting the Options... menu item launches the Edit Options dialog. See Edit Options Dialog on page 215 for details about using this dialog.
Menu BarWindows
The Windows menus one static choice is Bring All To Front, which ensures that all open PerformaSure windows have a higher stacking order than nonPerformaSure windows. The other items in the Windows menu allow you to switch from one open Project window or from one open browser to another. In addition to Bring All To Front, the Windows menu will always contain at least two items: one for the Project window and one for this browser.
Menu BarHelp
Help The Help... menu item launches context-sensitive help for this browser. About The About... menu item opens a new window in which product information about PerformaSure is displayed.
Toolbar
The Request Time browsers toolbar is located directly below the menu bar.
Figure 98
Figure 98
The toolbar in the Request Time browser
Figure 99
Figure 99
The options in the New Browser drop-down menu
New Request Time Browser Select New Request Time Browser to launch a new Request Time browser. New SQL Browser Select New SQL Browser to launch a new SQL browser. New Request Tree Browser Select New Request Tree Browser to launch a new Request Tree browser. New Metrics Browser Select New Metrics Browser to launch a new Metrics browser. New Network Traffic Browser Select New Network Traffic Browser to launch a new Network Traffic browser. New Thresholds Browser Select New Thresholds Browser to launch a new Thresholds browser.
Add New Browser to Project The Add New Browser to Project button is enabled if you have not yet added this browser to the Project. Click this button to add the browser to the Project. A new Request Time browser icon will appear in the Browsers area of the Project window. Export Report Click the Export Report button to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Properties Click the Properties button to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Performance Diagnostics The Performance Diagnostics button displays a drop-down menu from which you have four choices: Spotlight on Oracle, Spotlight on DB2, Spotlight on WebSphere, and Spotlight on WebLogic. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select Spotlight on WebSphere or Spotlight on WebLogic Server, Spotlight is launched to check the entire application server. When you select Spotlight on Oracle or Spotlight on DB2, Spotlight is launched to check database problems more closely. SQL Tuning The SQL Tuning button displays a drop-down menu from which you have two choices: SQLab Vision for Oracle, and SQL Tuning for DB2. Each choice is enabled if the corresponding cartridge is installed.
Link Browsers to Use Same Zone/Break Link Between Browsers Every PerformaSure browser contains a button that allows you to toggle whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. Click the Link Browsers to Use Same Zone button to link the browsers Time Control panels. When linked, the Zonar and (where applicable) the Sightline in each browser are in the same state as the browser in which the button was clicked. Using the Zonar or (where applicable) the Sightline in one browser will impact all other browsers as well. If a problem occurs during a specific interval spanned by the Zonar, linking the browsers can help you track this problem across different browsers. Click the Break Link Between Browsers button to return the browsers Time Control panels to an unlinked state. This allows each browsers Zonar and Sightline to function independently. Hide/Show Detail The Hide/Show Detail button browsers detail pane. Display By The Display By drop-down menu contains two options: Tier and Component Technology. See Display By on page 231 for more information. toggles the display of the Request Time
Time Control Panel

The Time Control panel is located directly below the Request Time browsers toolbar. This panel has the same controls in all PerformaSure browsers. See Time Control Panel on page 219 for a detailed description of its controls.
Request Time Browser Control PaneSummary

The following table describes the configuration controls and actions available from the control pane in All Requests mode. Request Time Browser Control PaneAll Requests Mode
Control/Action
Show Response Time for All Requests Tier
Type
Checkbox
Default Value
Checked
Description
Toggles the display of aggregate response time data in the graph pane for all requests listed in the detail pane. Switches the browser into Single Request Investigation mode. Response time data broken down by tier is displayed in the graph pane for the request that you selected. Switches the browser into Single Request Investigation mode. Response time data broken down by component technology is displayed in the graph pane for the request that you selected. Switches the browser into Single Request Investigation mode. Response time data broken down by server is displayed in the graph pane for the request that you selected. Launches a new Request Tree browser based on the request that is currently selected. Launches a new Metrics browser based on the metrics for the request that is currently selected.
Action
Enabled
Component Technology Server
Action
Enabled
Action
Enabled
View call tree of selected request View related metrics of selected request
Action Action
Enabled Enabled
The following table describes the features and actions available from the control pane in in Single Request Investigation mode. Request Time Browser Control PaneSingle Request Investigation Mode
Feature/Action
Current Drill Down History Next Drill Down
Type
Drill-down history/ actions Drop-down menu and button
Default Value
N/A
Description
Displays the drill-down history for the request that you are currently investigating. The entries for previous drilldown levels function like request investigation actions. Clicking the drop-down menu displays the drill-down options that are currently available. Select an option and click the View button to display response time data in the graph pane broken down by that option. See Next Drill Down on page 242 for more information. Returns the browser to All Requests mode. Launches a new Request Tree browser based on the request that you are currently investigating.
Enabled
Choose another request View call tree of selected request
Action Action
Enabled Enabled
Request Time Browser Control PaneSingle Request Investigation Mode

Feature/Action
View related metrics of selected request
Type
Action
Default Value
Enabled
Description
Launches a new Metrics browser based on the metrics for the request that you are currently investigating.
Request Time Browser Control PaneFull Detail

The Request Time browser operates in two performance investigation modes: All Requests mode and Single Request Investigation mode. In each of these modes, different configuration controls, features, and actions appear in the control pane. The two sets of options available from this pane are described below.
Figure 100
Figure 100 The control pane in All Requests mode (left) and Single Request Investigation mode (right)
All Requests Mode

Show Response Time for All Requests When the Show Response Time for All Requests checkbox is selected (its default setting), aggregate response time data is displayed in the graph pane for all requests listed in the detail pane. Deselect this checkbox if you do not want this data to be charted in the graph pane.
Figure 101
Figure 101 The aggregate response time of all requests charted in the graph pane
As shown in Figure 101, the chart segment for the overall response time of the system is identified as Response Time in the graph pane. Tip: Leave Show Response Time for All Requests checked to examine the request you selected in comparison to the overall response time of the system. Charting the aggregate response time of all requests provides you with a point of reference for your performance investigation. Request Investigation In All Requests mode, three drill-down actions are available in the control pane. Click the arrow icon or the action text to perform an action. Tier Select Tier to investigate response time by tier for the request that you selected. Performing this action causes the browser to switch into Single Request Investigation mode and chart response time data broken down by tier in the graph pane. When you perform this action, the segments in the chart are grouped in terms of the following tiers:

Web server Application server cluster(s) Database
Component Technology Select Component Technology to investigate response time by component technology for the request that you selected. Performing this action causes the browser to switch into Single Request Investigation mode and chart response time data broken down by component technology in the graph pane. When you perform this action, the segments in the chart are grouped based on J2EE component technology. The component technology segments are:

HTTP Servlet EJB [Custom Components] RMI URL JNDI JMS JDBC
Server Select Server to investigate response time by server for the request that you selected. Performing this action causes the browser to switch into Single Request Investigation mode and chart response time data broken down by server in the graph pane. When you perform this action, the segments in the chart are grouped in terms of application servers. Further Investigation In All Requests mode, two actions are available in the control pane that allow you to continue your investigation in other PerformaSure browsers. Click the arrow icon or the action text to perform an action. View call tree of selected request Select View call tree of selected request to launch a new Request Tree browser based on the request that you selected in the detail pane. View related metrics of selected request Select View related metrics of selected request to launch a new Metrics browser based on the request that you selected in the detail pane.
Single Request Investigation Mode

Current Drill Down History As shown in Figure 102, in Single Request Investigation mode, this section of the control pane displays the drill-down history for the request that you are currently investigating, allowing you to keep track of the request investigation actions that you have performed. The entries for previous drill-down levels function like request investigation actions. Click the entry for a previously-selected action to drill up a level. Click Request to cause the browser to return to All Requests mode. Tip: Hover the cursor over the entry for a previous drill-down level to make a tooltip appear that displays the specific value for that level.
Figure 102
Figure 102
A drill-down history tooltip
Next Drill Down Click Next Drill Down to display a drop-down menu with the drill-down options that are available from the current drill-down level. The options available from this menu are described below. Component Technology Select Component Technology to drill down and investigate response time by component technology for the request that you are currently analyzing. When you select this option, response time data broken down by component technology will be charted in the graph pane. At the Component Technology drill-down level, the segments in the chart are grouped based on J2EE component technology. The component technology segments are:

HTTP Servlet EJB [Custom Components] RMI URL JNDI JMS
JDBC This option is available from the Tier and Server drill-down levels.
Note:
Server Select Server to drill down and investigate response time by server for the request that you are currently analyzing. When you select this option, response time data broken down by server will be charted in the graph pane. At the Server drill-down level, the segments in the chart are grouped in terms of application servers.
Note:
This option is available from the Tier, Component Technology, and Component drill-down levels.
Component Select Component to drill down and investigate response time by component for the request that you are currently analyzing. Response time data for the selected component will be charted in the graph pane.
Note:
This option is available from the Component Technology drill-down level.
Further Investigation In Single Request Investigation mode, there are three Further Investigation actions available in the control pane: one action causes the browser to return to All Requests mode, and the other two actions allow you to continue your investigation in other PerformaSure browsers. Click the arrow icon or the action text to perform an action. Choose another request Select Choose another request to cause the Request Time browser to switch back to All Requests mode. View call tree of selected request Select View call tree of selected request to launch a new Request Tree browser based on the request that you are currently investigating. View related metrics of selected request Select View related metrics of selected request to launch a new Metrics browser based on the request that you are currently investigating.
Request Time Browser Graph PaneSummary

The following tables describe the controls and the contextual (right-click) menus available in the graph pane. Request Time Browser Graph Pane
Control
Chart header Function Set chooser Plot Type chooser Sightline slider Legend entries Chart Type chooser Edit Thresholds
Type
Drop-down menu Drop-down menu Drop-down menu Slider Metric Indicators Drop-down menu Button
Default Value
Enabled Enabled Enabled Enabled Enabled Enabled Enabled
Description
Displays the name of the active response time metric. Click it to display a menu from which you can select a different metric. Displays a menu from which you can select the function applied to the response time metrics charted in the graph pane. Displays a menu from which you can select the plot type applied to the active response time metric. Changes the position of the Sightline. Clicking an Indicator changes the active response time metric. See Using the Legend on page 246 for more information. Displays a menu from which you can select the chart type. Opens the Threshold Editor for the active response time metric. See Threshold Editor on page 392 for more information.
Request Time Browser Graph PaneContextual Menus

Control
Function for Selected Metric Apply [Plot Type] Plot Type To All View Call Tree View Related Metrics
Type
Drop-down menu Menu item Menu item Menu item
Description
Displays a menu from which you can select the function applied to the metric on which you right-clicked. Applies the plot type applied to the active metric to all items in the chart. Launches a new Request Tree browser based on the request that is currently selected. Launches a new Metrics browser based on the metrics for the request that is currently selected.
Request Time Browser Graph PaneFull Detail

The Request Time browsers graph pane includes several elements.
Figure 103
Figure 103 Elements in the Request Time browsers graph pane in All Requests mode; the Chart Type is set to Overlap and the Plot Type is set to Line.
Charts in the Graph Pane

In the Request Time browser graph pane, you can view a response time chart for every request that entered the instrumented system during the interval spanned by the Zonar. To view the chart for a request in the graph pane, click on the entry for that request in the detail pane. In All Requests mode, the chart displays response time data for the request that you selected segmented by tier or component technology, depending on the option that you selected from the Display By drop-down menu (View > Display By or from the toolbar). When the Show Response Time for All Requests checkbox is checked in the control pane, the aggregate response time of all requests is also displayed in the chart. Displaying this data allows you to examine the request that you selected in comparison to the overall response time of all requests that entered the instrumented system during the interval spanned by the Zonar. In Single Request Investigation mode, you can drill down into a single request, progressively breaking down response time into more detailed parts. You can drill
down to investigate response time data for a request by tier, server, component technology, and component. A new chart is displayed at each drill-down level. Tip: In both All Requests mode and Single Request Investigation mode, you can hold down the Shift key and drag the mouse between two points in the graph pane to cause the Zonar to zoom in to a smaller portion of the Timeline. When you perform this action, the response time data displayed in the graph pane will be for the new interval spanned by the Zonar. Changing the Display Mode In All Requests mode, you can change the display mode of the charts in the graph pane. When you change the display mode, response time data for the request that you selected is broken down and colored by tier or by component technology. To change the display mode, select Tier or Component Technology from the Display By drop-down menu (View > Display By or from the toolbar). See Display By on page 231 for more information about these display options. Using the Response Time Drop-Down Menu The chart header displays the name of the response time metric that is currently selected in the chart. Click this header to display a drop-down menu from which you can select a new active metric. Tip: Hover the cursor over the chart header to make a tooltip appear that displays the full name of the active response time metric.
Using the Legend As shown in Figure 103, the graph pane legend contains a group of Metric Indicators. Click a Metric Indicator to select a new active response time metric. A dark square appears around the Metric Indicator that corresponds to the active metric. Changing the Chart Type The header for the Chart Type chooser displays the chart type that is currently selected. Click this header to display a drop-down menu from which you can select a new chart type. The options available in this menu are described below.
Default When you select the Default chart, all response time metrics for the selected request are charted using a single y-axis. Tip: Select the Default chart if you want to compare multiple response time metrics with similar ranges.
Overlap When you select the Overlap chart, a separate y-axis is used to graph each response time metric for the selected request; a Metric Indicator appears next to the Chart Type chooser to indicate to which response time metric the current yaxis applies. Select a metric in the chart or click its corresponding Indicator in the legend to cause the range of values for that metric to be shown on the y-axis. Tip: Select the Overlap chart when you want to compare the trend of two response time metrics with very different ranges.
Example: Two response time metrics are charted in the graph pane for the request that you chose to investigate. For the interval spanned by the Zonar, Response Time Metric A has a range of 2,500 to 8,500 milliseconds and Response Time Metric B has a range of 50 to 150 milliseconds. Because of the disparity between their ranges, displaying both metrics in a Default chart causes Response Time Metric B to be shown as a nearly flat line near 0. If you use an Overlap chart instead, Response Time Metric A can be charted with a y-axis range of approximately 0 to 10 seconds and Response Time Metric B can be charted with a y-axis range of approximately 0 to 200 milliseconds. The scale shown on the y-axis will thus correspond more closely to the values for each metric. As a result, Response Time Metric B can be charted a way that provides you with a better visual indication of its trend. Stacked When you select the Stacked chart, the response time metrics for the request that you selected are displayed as additive metrics and are charted using a single y-
axis. In this type of chart, the broken line that extends horizontally from the y-axis and intersects the Sightline is aligned with the top (the sum) of the stacked metrics. Tip: Select the Stacked chart when you want to compare the total of multiple response time metrics and to compare the relative breakdown of this total on a per-metric basis.
Changing the Function Set Click the Function Set chooser icon to display a drop-down menu from which you can select the function applied to the response time metrics charted in the graph pane. The options listed in this menu are the functions that exist for the active response time metric. When you select a new function using the Function Set chooser, however, this function is applied to all metrics in the chart. Tip: Hover the cursor over the Function Set chooser icon to make a tooltip appear that displays the function currently applied to the active response time metric.
Note:
To change the function applied to a single response time metric, rightclick the metric to cause a contextual menu to appear. You can then select a new function from the Function submenu.
Changing the Plot Type Click the Plot Type chooser icon to display a drop-down menu from which you can select the plot type. When Default or Overlap is selected from the Chart Type chooser, the options available in this menu are Line, Bar, and Area and the plot type that you select is applied to the active response time metric. When Stacked is selected from the Chart Type chooser, the options available in this menu are Stacked Bar and Stacked Area and the plot type that you select applies to the entire chart. Tip: Hover the cursor over the Plot Type chooser icon to make a tooltip appear that displays the plot type that is currently applied either to the active response time metric or to the entire chart.
Edit Thresholds Button Click the Edit Thresholds... button to launch the Threshold Editor for the active response time metric. See Threshold Editor on page 392 for details about the Threshold Editor. See Thresholds Browser FAQ on page 395 for information about the availability of the Edit Thresholds button.
Tooltips in the Graph Pane

Indicator Tooltips Hover the cursor over a Metric Indicator to cause a tooltip to appear in which the name of the corresponding response time metric and the function applied to that metric are displayed.
Figure 104
Figure 104 The tooltip for a Metric Indicator
Chart Tooltips Hover the cursor over a data point in the chart to cause the x- and y-axis values charted at that point to appear in a tooltip. The tooltip will also include the Metric Indicator for that metric.
Figure 105
Figure 105 The tooltip for a data point
Contextual Menus in the Graph Pane

You can right-click anywhere in the graph pane to make a contextual menu appear. Function for Selected Metric Select this menu item to cause a submenu to appear from which you can select the function applied to the response time metric on which you right-clicked.
Apply [Plot Type] Plot Type To All Select this menu item to apply the plot type that is applied to the active metric to all items charted in the graph pane. See Changing the Plot Type on page 248 for more information about the options available from the Plot Type Chooser. View Call Tree Click View Call Tree to launch a Request Tree browser based on the request that is selected in the detail pane. View Related Metrics Click View Related Metrics to launch a Metrics browser based on the metrics for the request that is selected in the detail pane.
Request Time Browser Detail Pane

The Request Time browsers detail pane provides an explorer view of the requests that are charted in the graph pane. Information like statistics on incomplete requests, call counts, and exceptional exits are displayed in the detail pane in tabular form. Tip: Selecting a row in the detail table and putting it in the operating systems copy buffer allows for further processing. (Select the row in Unix, or Ctrl-C in Windows.) After the row is copied, you can paste it into another application, such as a spreadsheet.
Figure 106
Figure 106 The detail pane in the Request Time browser
Detail Pane Columns

The columns in the detail pane are described below.
Figure 107
Figure 107 The column headers in the Request Time browsers detail pane
Name The Name column lists the names of the root requests that entered the instrumented system during the interval spanned by the Zonar. Each separate HTTP request, JMS call, or RMI call is shown. Tip: Hover the cursor over an entry in the Name column to display the full name of the root request.
Call Count The Call Count column lists the number of times the request was completed during the interval spanned by the Zonar. Avg Cumulative Time The Avg Cumulative Time is the Total Cumulative Time divided by the Call Count. It is the average time spent by each sampled request in each container during the interval spanned by the Zonar. The Avg Cumulative Time is displayed in seconds. Max Cumulative Time The Max Cumulative Time column lists the longest time taken for a sampled request to complete during the interval spanned by the Zonar. The Max Cumulative Time is displayed in seconds. Total Cumulative Time The Total Cumulative Time column lists the total time (in seconds) taken by all requests that completed during the interval spanned by the Zonar. PerformaSure counts all requests, but it may not measure all requests that are handled by the system. If requests were sampled at less than 100% of the Nexus ability, Total Cumulative Time is an extrapolated value. See Sampling Tab on page 188 and Sampling Parameters on page 204 for more information about setting the sampling rate using the Recording Settings dialog or nexusctl. Avg Exceptional Exits The Avg Exceptional Exits column lists the average number times the request left the container due to an uncaught exception during the interval spanned by the Zonar. PerformaSure counts all requests, but it may not measure all requests that are handled by the system. However, PerformaSure does sample enough requests to
be able to estimate how many times each container is used to process requests of a given type. If requests were sampled at less than 100% of the Nexus ability, the number listed in the Avg Exceptional Exits column is an estimate. See Sampling Tab on page 188 and Sampling Parameters on page 204 for more information about setting the sampling rate using the Recording Settings dialog or nexusctl. Example: In a certain session the JDBC call count is 21234 and the number of JDBC exceptional exits is 12234. The large number of exceptions means that unnecessary time is being spent servicing them. Data validation before a database call is almost always more efficient than passing bad data and catching an exception. Incomplete Requests (%) The Incomplete Requests (%) column lists the percentage of incomplete service requests that occurred over the requests that completed during the interval spanned by the Zonar. PerformaSure considers a request incomplete if some of the events that make up the request are unpaired and the request has remained in that state with no other events coming into the Nexus by the end of the session or for the duration of the incomplete request timeout period. See Incomplete Request Timeout on page 187 and Session Parameters on page 203 for more information about setting the incomplete request timeout using the Workstation or nexusctl. Sampled Requests (%) The Sampled Requests (%) column lists the percentage of service requests that were Tagged and Followed during the interval spanned by the Zonar.
Bar Charts in the Detail Pane

Depending on the option that you selected from the Display By drop-down menu (View > Display By or from the toolbar), the bar charts in the Avg Cumulative Time and Total Cumulative Time columns in the detail pane display request metrics segmented either by Tier or by Component Technology. When the display mode is set to Tier, the segments of the bar charts are grouped by following tiers:

Web server Application Server Cluster(s) Database
When the display mode is set to Component Technology, the segments of the bar charts are grouped based on J2EE component technology:
HTTP Servlet EJB [Custom Components] RMI URL JNDI JMS JDBC
The HTTP segment includes both the web server and the HTTP portion of the application server. J2EE component technology segments span all application servers in the system, regardless of cluster. The Servlet segment includes both JSPs and Servlets. Bar Chart Tooltips The segments of the bar charts in the Avg Cumulative Time and Total Cumulative Time columns correspond to the amount of time a request spent in each of the containers that had a part in handling the request. Hover the cursor over a segment of one of the bar charts to make a tooltip appear that displays the percentage of the Avg Cumulative Time or Total Cumulative Time spent by that request in a particular container and the number of times that object was called per request during the interval spanned by the Zonar.
Contextual Menus in the Detail Pane

You can right-click anywhere in the detail table to make a contextual menu appear. The items in these menus are described below.
Figure 108
Figure 108 A contextual menu in the detail pane
Auto-Fit Column Click Auto-Fit Column to resize the width of that column so that all values within the column are visible. Auto-Fit All Columns Click Auto-Fit All Columns to resize the width of all columns in the table so that all values within each column are visible. Hide Column Click Hide Column if you do not want the column on which you right-clicked to be displayed in the table. Show/Hide Columns... You can choose whether or not to display certain metrics in the detail pane. Select Show/Hide Columns... to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated metric in a column in the detail pane. Hide Bar Chart Click Hide Bar Chart if you do not want bar charts displayed in that column. Show/Hide Bar Charts... You can choose whether or not to display certain bar charts in the detail pane columns. Select Show/Hide Bar Charts to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated bar chart. View Call Tree Select View Call Tree to launch a new Request Tree browser based on the request that is currently selected. This item is disabled when you right-click on a column header. View Related Metrics Select View Related Metrics to launch a new Metrics browser based on the metrics for the request that is currently selected. This item is disabled when you right-click on a column header.
Request Time Browser FAQ

When drilling down several levels into a request, I sometimes lose track of the exact value of previous drill-down levels. Is there a way to display these values in the browser? You can hover the cursor over the entry for a previous drill-down level to make a tooltip appear that displays the specific value for that level.
Figure 109
Figure 109 The tooltip for a previous drill-down level
Chapter 12
SQL Browser

SQL Browser Menus and ToolbarSummary Menus and ToolbarFull Detail Time Control Panel SQL Browser Control PaneSummary SQL Browser Control PaneFull Detail SQL Browser Graph PaneSummary SQL Browser Graph PaneFull Detail Charts in the Graph Pane Tooltips in the Graph Pane Contextual Menus in the Graph Pane SQL Browser Detail Pane Detail Pane Columns Bar Charts in the Detail Pane Contextual Menus in the Detail Pane SQL Browser FAQ
SQL Browser
Many performance problems are related to database accesses. In order to diagnose database performance problems effectively, you will need to view detailed information about the SQL statements that are being used in your application.
257
The SQL browser provides you with performance information for SQL statements aggregated across multiple requests. This provides you with a highlevel view of the SQL statements used in your application, allowing you to identify and diagnose database problems with greater ease and accuracy.
Figure 110
Figure 110 The SQL browser

Menu Bar
The SQL browsers menu bar is located along the top of the browser window. The following tables describe the controls available from the different menus in the menu bar. SQL Browser Menu BarBrowser Menu
Control
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Opens the New Browser dialog. Use this dialog to choose the type of browser you want to launch. Adds the browser to your PerformaSure Project. A SQL browser icon will appear in the Browsers area of the Project window. Begins the process of generating a print version of the browser suitable for inclusion in a report. Launches the Browser Properties dialog. See Properties on page 262 for details. Closes the browser. Closes all open Projects and browsers and shuts down the Workstation.
SQL Browser Menu BarView Menu

Control
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Resizes the width of all columns in the table so that all values within each column are visible. Opens a dialog containing a group of checkboxes. Select or deselect these checkboxes to toggle the display of certain metrics in the detail pane. Opens a dialog containing a group of checkboxes. Select or deselect these checkboxes to toggle the display of certain bar charts in the detail pane columns. Toggles the display of the Filter Bar at the bottom of the graph pane. See Show Filter Bar on page 263 for more information about using the controls in the Filter Bar.
Menu item
Enabled
Selected
SQL Browser 259
SQL Browser Menu BarTools Menu

Control
Type
Default Value
Description
SQL Tuning Options
Menu item Menu item
N/A Enabled
SQL Browser Menu BarWindows Menu

Control
Type
Default Value
Description
SQL Browser Menu BarHelp Menu

Control
Help About
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Toolbar
Under the SQL browsers menu bar is a toolbar with controls for opening new PerformaSure browsers, launching Spotlight and Quest database tools, controling the view in the SQL browsers graph and detail panes, and performing other actions like exporting a report. The following table describes the controls available from the toolbar. SQL Browser Toolbar
Control
New Browser
Type
Default Value
Enabled
Description
Clicking on the left-hand side of this button launches the New Browser dialog. See New Browser on page 163 for details. Clicking on the right-hand displays a dropdown menu from which you can choose the type of new browser that you want to open. See New Browser on page 266 for details. Adds the browser to the Project. This button is disabled if you have already added the browser to the Project. Begins the process of generating a print version of the browser suitable for inclusion in a report. Launches the Browser Properties dialog. See Properties on page 267 for details. Displays a drop-down menu with four choices. See Performance Diagnostics on page 267 for more information. Displays a drop-down menu with two choices. See SQL Tuning on page 267 for more information. Toggles whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. See Link Browsers to Use Same Zone/Break Link Between Browsers on page 268 for more information. Toggles the display of the detail pane.
Add New Browser To Project Export Report Properties Performance Diagnostics SQL Tuning
Button Button Button Button and drop-down menu Button and drop-down menu Button
Enabled Enabled Enabled N/A
N/A
Enabled
Button
Enabled
SQL Browser 261

New Browser Choose New Browser... to launch the New Browser dialog, which allows you to select and open a new browser of a specific type. The new browser is not automatically added to the Project or listed in the Project window. Keyboard accelerator: Ctrl-B. Add New Browser To Project The Add New Browser To Project menu item is enabled if you have not yet added this browser to the Project. Click this item to add the browser to the Project. A new SQL browser icon will appear in the Browsers area of the Project window. Keyboard accelerator: Ctrl-A. Export Report Select Export Report... to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Keyboard accelerator: Ctrl-R. Properties Choose Properties... to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Close Select the Close menu item to close the browser but leave the Project open. Keyboard accelerator: Ctrl-W. Exit PerformaSure Choose Exit PerformaSure to close all open Projects and browsers and shut down the Workstation. When you select this menu item, you may be prompted to
save the Projects that are open or add new browsers to these Projects before exiting PerformaSure.
Menu BarView
Auto-Fit All Columns Click Auto-Fit All Columns to resize the width of all columns in the table so that all values within each column are visible. Show/Hide Columns You can choose whether or not to display certain metrics in the detail pane. Select Show/Hide Columns... to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated metric in a column in the detail pane. Show/Hide Bar Charts You can choose whether or not to display certain bar charts in the detail pane columns. Select Show/Hide Bar Charts... to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated bar chart. Show Filter Bar Select or deselect the checkbox associated with the menu item Show Filter Bar to toggle the display of the SQL browsers Filter Statements bar at the bottom of the graph pane. You can enter a literal string or a regular expression in the Filter Statements bars Filter Statements text field. When you click the Apply button, the string or expression that you entered is matched against the SQL statements listed in the detail pane; only the statements that match are displayed in the graph pane and in the detail pane. By default, the Filter Statements text field contains an empty literal string so that all statements are selected. Tip: If you enter a regular expression in the Filter Statements text field, ensure that the Use Regular Expression checkbox is selected before you click Apply.
SQL Browser 263
Menu BarTools
Note:
This item is greyed out if you do not have administrator privileges.
Menu BarWindows
Menu BarHelp
Toolbar
The SQL browsers toolbar is located directly below the menu bar.
Figure 111
Figure 111 The toolbar in the SQL browser
SQL Browser 265
Figure 112
Figure 112 The options in the New Browser drop-down menu
Add New Browser to Project The Add New Browser to Project button is enabled if you have not yet added this browser to the Project. Click this button to add the browser to the Project. A new SQL browser icon will appear in the Browsers area of the Project window. Export Report Click the Export Report button to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Properties Click the Properties button to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Performance Diagnostics The Performance Diagnostics button displays a drop-down menu from which you have four choices: Spotlight on Oracle, Spotlight on DB2, Spotlight on WebSphere, and Spotlight on WebLogic. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select Spotlight on WebSphere or Spotlight on WebLogic Server, Spotlight is launched to check the entire application server. When you select Spotlight on Oracle or Spotlight on DB2, Spotlight is launched to check database problems more closely. SQL Tuning The SQL Tuning button displays a drop-down menu from which you have two choices: SQLab Vision for Oracle, and SQL Tuning for DB2. Each choice is enabled if the corresponding cartridge is installed.
SQL Browser 267
Link Browsers to Use Same Zone/Break Link Between Browsers Every PerformaSure browser contains a button that allows you to toggle whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. Click the Link Browsers to Use Same Zone button to link the browsers Time Control panels. When linked, the Zonar and (where applicable) the Sightline in each browser are in the same state as the browser in which the button was clicked. Using the Zonar or (where applicable) the Sightline in one browser will impact all other browsers as well. If a problem occurs during a specific interval spanned by the Zonar, linking the browsers can help you track this problem across different browsers. Click the Break Link Between Browsers button to return the browsers Time Control panels to an unlinked state. This allows each browsers Zonar and Sightline to function independently. Hide/Show Detail The Hide/Show Detail button detail pane. toggles the display of the SQL browsers
Time Control Panel

The Time Control panel is located directly below the SQL browsers toolbar. This panel has the same controls in all PerformaSure browsers. See Time Control Panel on page 219 for a detailed description of its controls.
SQL Browser Control PaneSummary

The following table describes the configuration controls and actions available from the control pane. SQL Browser Control Pane
Control/Action
Show Response Time for All Statements
Type
Checkbox
Default Value
Checked
Description
Controls whether aggregate response time data is displayed in the graph pane for all SQL statements listed in the detail pane.
SQL Browser Control Pane

Control/Action
Prepare Execute Retrieve View call tree of related request View related metrics of selected statement
Type
Checkbox Checkbox Checkbox Action Action
Default Value
Checked Checked Checked Enabled Enabled
Description
Controls whether response time data for the Prepare portion of the selected SQL statement is displayed in the graph pane. Controls whether response time data for the Execute portion of the selected SQL statement is displayed in the graph pane. Controls whether response time data for the Retrieve portion of the selected SQL statement is displayed in the graph pane. Launches a new Request Tree browser based on the request related to the SQL statement that you selected. Launches a new Metrics browser in which metrics associated with the selected SQL statement are graphed.
SQL Browser Control PaneFull Detail

Components in the Control Pane
The SQL browsers control pane contains controls for configuring the display of response time data in the graph pane and actions that you can take to continue your performance investigation in other PerformaSure browsers.
Figure 113
Figure 113 The SQL browsers control pane
SQL Browser 269
Show Response Time For All Statements When the Show Response Time for All Statements checkbox is selected (its default setting), aggregate response time data is displayed in the graph pane for all SQL statements listed in the detail pane; the chart segment for this data is identified as Total Response Time in the graph pane.
Figure 114
Figure 114 The aggregate response time of all SQL statements charted in the graph pane
Charting the Total Response Time provides you with a point of reference for your performance investigation by allowing you to examine the response time metrics for a particular statement in comparison to the overall response time of all SQL statements. Example: You may want to deselect Show Response Time for All Statements if the range of values for the Total Response Time is very different from the ranges for the response time metrics for the statement that you selected; if the metrics for this statement have similar ranges; and if you no longer need to compare these metrics to the Total Response Time. If you deselect this checkbox and select Default from the Chart Type chooser, all response time metrics for this statement will be charted using the same yaxis and the scale shown on the y-axis may correspond more closely to the range for these metrics, thus providing you with a better visual indication of each metrics trend. See Changing the Chart Type on page 274 for more information about the chart types available in the graph pane. SQL Statement Investigation When you select a SQL statement listed in the detail pane, response time data broken down by operation is charted in the graph pane for that statement. The checkboxes in the SQL Statement Investigation area control the display of response
time data for the SQL operations charted in the graph pane. All three options (Prepare, Execute, and Retrieve) are selected by default. Further Investigation Two actions are available that allow you to continue your investigation in other PerformaSure browsers. Click the arrow icon or the action text to perform an action. View call tree of related request Select View call tree of related request to launch a new Request Tree browser based on the request related to the SQL statement that you selected in the detail pane. View related metrics of selected statement Select View related metrics of selected statement to launch a new Metrics browser in which metrics associated with the selected SQL statement are graphed.
SQL Browser Graph PaneSummary

The following tables describe the controls and the contextual (right-click) menus available in the graph pane. SQL Browser Graph Pane
Control
Chart header Function Set chooser Plot Type chooser Sightline slider Legend entries
Type
Drop-down menu Drop-down menu Drop-down menu Slider Metric Indicators
Default Value
Enabled Enabled Enabled Enabled Enabled
Description
Displays the name of the active SQL response time metric. Click it to display a menu from which you can select a different metric. Displays a menu from which you can select the function applied to the SQL response time metrics charted in the graph pane. Displays a menu from which you can select the plot type applied to the active SQL response time metric. Changes the position of the Sightline. Clicking an Indicator changes the active SQL response time metric. See Using the Legend on page 274 for more information. Displays a menu from which you can select the chart type.
Chart Type chooser
Drop-down menu
Enabled
SQL Browser 271
SQL Browser Graph Pane

Control
Edit Thresholds
Type
Button
Default Value
Enabled
Description
Opens the Threshold Editor for the active SQL response time metric.
SQL Browser Graph PaneContextual Menus

Control
Function for Selected Metric Apply [Plot Type] Plot Type To All View Call Tree View Related Metrics
Type
Drop-down menu Menu item Menu item Menu item
Description
Displays a menu from which you can select the function applied to the SQL response time metric on which you right-clicked. Applies the plot type applied to the active metric to all items in the chart. Launches a new Request Tree browser based on the statement that is currently selected. Launches a new Metrics browser based on the metrics for the statement that is currently selected.
SQL Browser Graph PaneFull Detail

The SQL browsers graph pane includes several elements.
Figure 115
Figure 115 Elements in the SQL browsers graph pane; the Chart Type is set to Overlap and the Plot Type is set to Line.

Response time metrics for the selected statement are charted in the graph pane. If the Show Response Time for All Statements checkbox is checked, aggregate response time data for all SQL statements listed in the detail pane is displayed as well. Tip: Hold down the Shift key and drag the mouse between two points in the graph pane to cause the Zonar to zoom in to a smaller portion of the Timeline. When you perform this action, the SQL response time data displayed in the graph pane will be for the new interval spanned by the Zonar.
SQL Browser 273
Using the Total Response Time Drop-Down Menu The chart header displays the name of the SQL response time metric that is currently selected in the chart. Click this header to display a drop-down menu from which you can select a new active metric. Tip: Hover the cursor over the chart header to make a tooltip appear that displays the full name of the active SQL response time metric.
Using the Legend As shown in Figure 115, the graph pane legend includes a group of Metric Indicators. Click a Metric Indicator to select a new active SQL response time metric. A black square appears around the Metric Indicator that corresponds to the active metric. Changing the Chart Type The header for the Chart Type chooser displays the chart type that is currently selected. Click this header to display a drop-down menu from which you can select a new chart type. The options available in this menu are described below. Default When you select the Default chart, all SQL response time metrics are graphed using a single y-axis. Tip: Select the Default chart if you want to compare multiple SQL response time metrics with similar ranges.
Overlap When you select the Overlap chart, a separate y-axis is used to graph each SQL response time metric; a Metric Indicator appears next to the Chart Type chooser to indicate to which response time metric the current values on the y-axis apply. Select a metric in the chart or click its corresponding Indicator in the legend to cause the range of values for that metric to be shown on the y-axis. Tip: Select the Overlap chart when you want to compare the trend of two SQL response time metrics with very different ranges.
Example: Two response time metrics are charted in the graph pane for the SQL statement that you chose to investigate. As a point of comparison, you also decide to chart the aggregate response time for all SQL statements listed in the detail pane. For the interval spanned by the Zonar, Response Time Metric A (Prepare) has a range of 0 to 65 milliseconds, Response Time Metric B (Execute) has a range of 30 to 75 milliseconds, and the Total Response Time for all statements has a range of 500 to 3500 milliseconds. Because of the disparity between the first two metrics ranges and range of the aggregate response time metric, displaying all three metrics in a Default chart causes Metric A (Prepare) and Metric B (Execute) to be shown as nearly flat lines near 0. If you use an Overlap chart instead, Metric A (Prepare) can be charted with a y-axis range of 0 to 70 milliseconds, Metric B (Execute) can be charted with a y-axis range of approximately 20 to 80 milliseconds and the Total Response Time can be charted with a y-axis range of approximately 0 to 4 seconds. The scale shown on the y-axis will thus correspond more closely to the values for each metric. As a result, Metric A (Prepare) and Metric B (Execute) can be charted a way that provides you with a better visual indication of each metrics trend. Stacked When you select the Stacked chart, the response time metrics for the SQL statement that you selected are displayed as additive metrics and are charted using a single y-axis. In this type of chart, the broken line that extends horizontally from the y-axis and intersects the Sightline is aligned with the top (the sum) of the stacked metrics. Tip: Select the Stacked chart when you want to view the total of multiple response time metrics and examine the breakdown of this total on a per-metric basis.
SQL Browser 275
Changing the Function Set Click the Function Set chooser icon to make a drop-down menu appear that displays the function applied to the SQL response time metrics charted in the graph pane. This menu lists one option: Value. Tip: Hover the cursor over the Function Set chooser icon to make a tooltip appear that displays the function applied to the SQL response time metrics.
Changing the Plot Type Click the Plot Type chooser icon to display a drop-down menu from which you can select the plot type. When Default or Overlap is selected from the Chart Type chooser, the options available in this menu are Line, Bar, and Area and the plot type that you select is applied to the active SQL response time metric. When Stacked is selected from the Chart Type chooser, the options available in this menu are Stacked Bar and Stacked Area and the plot type that you select applies to the entire chart. Tip: Hover the cursor over the Plot Type chooser icon to make a tooltip appear that displays the plot type that is currently applied either to the active SQL response time metric or to the entire chart.
Edit Thresholds Button Click the Edit Thresholds... button to launch the Threshold Editor for the active SQL response time metric. See Threshold Editor on page 392 for details about the Threshold Editor. See Thresholds Browser FAQ on page 395 for information about the availability of the Edit Thresholds button.

Indicator Tooltips Hover the cursor over a Metric Indicator to cause a tooltip to appear in which the name of the corresponding SQL response time metric and the function applied to that metric are displayed.
Figure 116
Figure 117

You can right-click anywhere in the graph pane to make a contextual menu appear. Function for Selected Metric Select this menu item to cause a submenu to appear from which you can select the function applied to the SQL response time metric on which you right-clicked. Apply [Plot Type] Plot Type To All Select this menu item to apply the option that is applied to the active metric to all items charted in the graph pane. See Changing the Plot Type on page 276 for more information about the options available from the Plot Type Chooser. View Call Tree Click View Call Tree to launch a new Request Tree browser based on the request related to the selected SQL statement.
SQL Browser 277
View Related Metrics Click View Related Metrics to launch a new Metrics browser in which metrics associated with the selected SQL statement are graphed.
SQL Browser Detail Pane

The SQL browsers detail pane provides an explorer view of the statements that are charted in the graph pane. Information is displayed in the detail pane in tabular form. Tip: Selecting a row in the detail table and putting it in the operating systems copy buffer allows for further processing. (Select the row in Unix, or Ctrl-C in Windows.) After the row is copied, you can paste it into another application, such as a spreadsheet.
Figure 118
Figure 118 The detail pane in the SQL browser
Detail Pane Columns

Figure 119
Figure 119 The column headers in the SQL browsers detail pane
SQL Statement The SQL Statement column lists the SQL statements used in your application. Tip: Hover the cursor over an entry in the SQL Statement column to display the full SQL statement.
Execute Count The Execute Count column lists the number of times the SQL statement was executed during the interval spanned by the Zonar. The Execute Count does not include prepare or retrieve call counts. Max Execute Time The Max Execute Time column lists the longest execute time of the SQL statement during the interval spanned by the Zonar. The Max Execute Time is displayed in seconds per execution. Avg Response Time The Avg Response Time is the Total Response Time divided by the Execute Count. It is the average execution time of the SQL statement during the interval spanned by the Zonar. The Avg Response Time is displayed in seconds per execution. Total Response Time The Total Response Time is the aggregate of all prepare, execute, and retrieval times of the SQL statement during the interval spanned by the Zonar. The Total Response Time is displayed in seconds.

The bar charts in the Avg Response Time and Total Response Time columns in the detail pane display response time metrics segmented by execution stage (Prepare, Execute, and Retrieve). Bar Chart Tooltips The segments of the bar charts in the Avg Response Time and Total Response Time columns correspond to the amount of time spent in a particular operation. Hover the cursor over a segment of one of the bar charts to make a tooltip appear that displays the percentage of the Avg Response Time or Total Response Time spent in the corresponding operation.
Figure 120
Figure 120 A tooltip in the detail pane
SQL Browser 279

You can right-click anywhere in the detail table to make a contextual menu appear. The items in this menu are described below.
Figure 121
Auto-Fit Column Click Auto-Fit Column to resize the width of the column on which you rightclicked so that all values within the column are visible. Auto-Fit All Columns Click Auto-Fit All Columns to resize the width of all columns in the table so that all values within each column are visible. Hide Column Click Hide Column if you do not want the column on which you right-clicked to be displayed in the table. Show/Hide Columns You can choose whether or not to display certain metrics in the detail pane. Select Show/Hide Columns... to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated metric in a column in the detail pane. Hide Bar Chart Click Hide Bar Chart if you do not want bar charts displayed in that column.
Show/Hide Bar Charts You can choose whether or not to display certain bar charts in the detail pane columns. Select Show/Hide Bar Charts... to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated bar chart. View Call Tree Select View Call Tree to launch a new Request Tree browser based on the request related to the SQL statement that is currently selected. This item is disabled when you right-click on a column header. View Related Metrics Select View Related Metrics to launch a new Metrics browser in which metrics related to the selected SQL statement are graphed. This item is disabled when you right-click on a column header. Performance Diagnostics The menu item Performance Diagnostics is enabled when you click on the entry for a SQL statement in the detail table. When you select the Performance Diagnostics menu item, a submenu is displayed from which you have two choices: Spotlight on Oracle and Spotlight on DB2. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select Spotlight on WebSphere or Spotlight on WebLogic Server, Spotlight is launched to check the entire application server. When you select Spotlight on Oracle or Spotlight on DB2, Spotlight is launched to check database problems more closely. SQL Tuning The menu item SQL Tuning is enabled when you click on the entry for a SQL statement in the detail table. When you select the SQL Tuning... menu item, a submenu is displayed from which you have two choices: SQLab Vision for Oracle, and SQL Tuning for DB2. Each choice is enabled if the corresponding cartridge is installed.
SQL Browser 281
SQL Browser FAQ

SQL statements are sometimes truncated in the SQL Statement column in the detail pane. If I right-click on this column and select Auto-Fit Column from the contextual menu, I need to scroll through the detail pane to see the values listed in the other columns. Is there another way of displaying the whole statement without adjusting the size of the columns? You can hover the cursor over an entry in the SQL Statement column to display the full SQL statement.
Chapter 13
Request Tree Browser


Request Tree Browser Menus and ToolbarSummary Menus and ToolbarFull Detail Time Control Panel Request Tree Browser Graph PaneSummary Request Tree Browser Graph PaneFull Detail Request Trees Request Tree Tooltips Contextual Menus in the Graph Pane Zooming the Request Tree Request Tree Browser Detail Pane Detail Pane Columns Creating a JProbe Launcher File Request Tree Browser FAQ

The Request Tree browser shows a graphical representation of a request from its invocation as it enters the system and progresses through the various method and database calls. As the request progresses, it may call one or more Servlets, which in turn call one or more EJBs, and so on, until the request is complete. You can choose to display request trees with component-, class-, or method-level detail. One of the purposes of the Request Tree browser is to help you find the critical path within a request: the one taking the most time. Requests are sorted alphabetically,
283
with the most expensive request in focus. The call tree for each request is sorted as well. Time-consuming paths are drawn above those that take less time. Note that the way the tree is sorted is dependent on which metric is chosen. Choosing a new metric does not cause the tree to be resorted immediately since this operation usually necessitates redrawing the tree, which you might not want to do. The window consists of a menu bar, a toolbar, a Time Control panel, a Request Tree graph pane containing a call tree, and a Request Tree detail pane containing a table of numerical values for the metrics that have been collected.
Figure 122
Figure 122 The Request Tree browser
Saving Browser Settings

Almost all aspects of the Request Tree browser that are user-configurable (including detail table column visibility and width) are saved to and restored from the Project file as part of the browsers state. If you make changes to any of these aspects, you will be asked if you wish to save the Project when you close it.

Menu Bar
The Request Tree browsers menu bar is located along the top of the browser window. The following tables describe the controls available from the different menus in the menu bar. Request Tree Browser Menu BarBrowser Menu
Control
New Browser Add New Browser To Project Export Report Export JProbe Launcher File
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Opens the New Browser dialog. Use this dialog to choose the type of browser you want to launch. Adds the browser to your PerformaSure Project. A Request Tree browser icon will appear in the Browsers area of the Project window. This menu item is disabled if you have already added the browser to the Project. Begins the process of generating a print version of the browser suitable for inclusion in a report. Creates and exports a JProbe launcher file that you can use to run JProbe Profiler. Choose this option after selecting expensive nodes in the request tree. See Export JProbe Launcher File on page 289 for more information. Launches the Browser Properties dialog. See Properties on page 290 for details. Closes the browser. Closes all open Projects and browsers and shuts down the Workstation.
Menu item Menu item
Enabled Disabled
Properties Close Exit PerformaSure
Request Tree Browser Menu BarView Menu

Control
Display By
Type
Menu item
Default Value
Tier
Description
Displays a submenu from which you can select either Tier or Component Technology. Selecting one of these options colors the tree nodes Identifier bars accordingly. Exposes the n most expensive nodes in the request tree (based on the active metric) and scrolls the most expensive node into view.
FastFind
Menu item
Enabled
Request Tree Browser 285
Request Tree Browser Menu BarView Menu

Control
Sort Tree
Type
Menu item
Default Value
Enabled
Description
Redraws the request tree after a new active metric has been selected. See Sort Tree on page 291 for more information. Displays a submenu from which you can select either Per Request or Per Call. Select one of these options to cause either request averages or call averages to be displayed in tooltips and in the detail pane. Displays a list of metrics in a submenu. Select one of these options to recolor the request tree accordingly. See Active Metric on page 292 for details. Displays a submenu from which you can select Component, Class, or Method. Select either Class or Method to display a more detailed request tree. See Bundling Mode on page 294 for more information. Displays a submenu from which you can select either Item or Tree. Select one of these options to change how the metrics in the detail pane are displayed. Toggles the display of the panner window. Use the panner to scroll through the graph pane more easily. Opens a dialog containing a group of checkboxes. Select or deselect these checkboxes to toggle the display of metrics and Agent information in the detail pane. Resizes the width of all columns in the table so that all values within each column are visible. Toggles the display of the Filter Bar at the bottom of the graph pane. See Show Filter Bar on page 296 for more information about using the controls in the Filter Bar.
Metric Display
Menu item
Per Request
Active Metric
Menu item
Avg Cumulative Time Component
Bundling Mode
Menu item
Detail Table Mode
Menu item
Item
Show Panner Show/Hide Columns
Menu item with checkbox Menu item
Not selected Enabled
Auto-Fit All Columns Show Filter Bar
Menu item Menu item with checkbox
Enabled Selected
Request Tree Browser Menu BarTools Menu

Control
Recording Control Window Session Management Thresholds Change Password User Administration
Type
Menu item Menu item Menu item Menu item Menu item
Default Value
Enabled Enabled Enabled Enabled Disabled
Description
Launches the Recording Control window. Opens the Session Management dialog. Launches the Threshold Editor. Opens the Change Password dialog. Launches the User Management dialog. This menu item is enabled if you have administrator privileges.
Request Tree Browser Menu BarTools Menu

Control
Performance Diagnostics
Type
Menu item
Default Value
N/A
Description
Displays a submenu from which you can select one of four options. See Performance Diagnostics on page 298 for more information. Displays a submenu with two choices. See SQL Tuning on page 298 for more information. Launches the Edit Options dialog.
SQL Tuning Options
Menu item Menu item
N/A Enabled
Request Tree Browser Menu BarWindows Menu

Control
Type
Default Value
Description
Request Tree Browser Menu BarHelp Menu

Control
Help About
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Toolbar
Under the Request Tree browsers menu bar is a toolbar with controls for opening new PerformaSure browsers, launching Spotlight and Quest database tools, controling the view in the Request Tree browsers graph and detail panes, and
performing other actions like exporting a report. The following table describes the controls available from the toolbar. Request Tree Browser Toolbar
Control
New Browser
Type
Default Value
Enabled
Description
Clicking on the left-hand side of this button launches the New Browser dialog. See New Browser on page 163 for details. Clicking on the right-hand displays a dropdown menu from which you can choose the type of new browser that you want to open. See New Browser on page 299 for details. Adds the browser to the Project. This button is disabled if you have already added the browser to the Project. Begins the process of generating a print version of the browser suitable for inclusion in a report. Launches the Browser Properties dialog. See Properties on page 290 for details. Displays a drop-down menu with four choices. See Performance Diagnostics on page 300 for more information. Displays a drop-down menu with two choices. See SQL Tuning on page 301 for more information. Toggles whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. See Link Browsers to Use Same Zone/Break Link Between Browsers on page 301 for more information. Toggles the display of the detail pane. Toggles the display of the panner. Clicking the Show Panner button causes the panner to appear in its own window. Provides two metric display options: Per Request and Per Call. See Metric Display on page 301 for a description of these options. Provides a list of options from which you can choose a new active metric. See Active Metric on page 292 for a description of these options. Exposes the top n expensive nodes in the request tree (based on the active metric) and scrolls the most expensive node into view.
N/A
Link Browsers To Use Same Zone/Break Link Between Browsers Show Detail/Hide Detail Show Panner/Hide Panner Metric Display
Enabled
Button Button
Enabled Enabled
Drop-down menu Drop-down menu Button
Per Request
Active Metric
Avg Cumulative Time Enabled
FastFind
Request Tree Browser Toolbar

Control
Bundling Mode
Type
Drop-down menu
Default Value
Component
Description
Provides three bundling mode options: Component, Class, and Method. See Bundling Mode on page 294 for a description of these options.

New Browser Choose New Browser... to launch the New Browser dialog, which allows you to select and open a new browser of a specific type. The new browser is not automatically added to the Project or listed in the Project window. Keyboard accelerator: Ctrl-B. Add New Browser To Project The Add New Browser To Project menu item is enabled if you have not yet added this browser to the Project. Click this item to add the browser to the Project. A new Request Tree browser icon will appear in the Browsers area of the Project window. Keyboard accelerator: Ctrl-A. Export Report Select Export Report... to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Keyboard accelerator: Ctrl-R. Export JProbe Launcher File After using the Request Tree browser to identify expensive nodes, you may want to examine the internal behavior of certain methods. To do so, select one or more expensive nodes in the request tree (by clicking or control-clicking them), choose Browser > Export JProbe Launcher File, and then select either Profile Selected Package(s)... or Profile Selected Class(es). Selecting one of these options begins the process of creating and exporting a JProbe launcher ( JPL) file
that you can use to run JProbe Profiler. See Creating a JProbe Launcher File on page 332 for more information about creating this type of file. See JProbe Integration on page 157 for hints about how to configure JProbe once you have the JPL file. Properties Choose Properties... to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Close Select the Close menu item to close the browser but leave the Project open. Keyboard accelerator: Ctrl-W. Exit PerformaSure Choose Exit PerformaSure to close all open Projects and browsers and shut down the Workstation. When you select this menu item, you may be prompted to save the Projects that are open or add new browsers to these Projects before exiting PerformaSure.
Menu BarView
Display By Choose Display by... to display a submenu from which you can select one of two options: Tier or Component Technology. Tier is selected by default. Click the radio button associated with either Tier or Component Technology to color the request tree nodes Identifier bars accordingly. Selecting one of these options will not interfere with your ability to color the tree nodes based on the active metric. For example, you can color the request tree by Component and by Call Count simultaneously. Tier Coloring by tier allows you to distinguish the tiers of your application in the request tree. PerformaSure consistently assigns one color to each tier and one for each application server cluster.
Component Technology Coloring by component technology allows you to distinguish component types in the request tree. Components include HTTP, Servlets, EJBs, custom components, RMI, URL, JNDI, JMS, and JDBC. PerformaSure consistently assigns one color to each standard and custom component. Any node that represents a class that does not belong to a standard or custom component technology is colored grey. FastFind Select FastFind to expose the top n expensive nodes in the request tree (based on the active metric) and scroll the most expensive node into view. Keyboard accelerator: Ctrl-F.
To use the FastFind feature from the Menu bar:
1.
Set the active metric by selecting View > Active Metric and then selecting a metric listed in the submenu. Select View > FastFind. The top n expensive nodes will be exposed and the most expensive node will be scrolled into view.
2.
Sort Tree Choose Sort Tree to redraw the request tree after you change the active metric. Tip: Select Sort Tree if you want a node with a higher value of the active metric to appear above a node with a lower value.
Requests are always sorted alphabetically, so their order is fixed. Within a request, each nodes children and the members of each group node are sorted in descending order based on the active metric; non-pruned nodes always precede pruned nodes. Metric Display You can select one of two options from the Metric Display drop-down menu: Per Request and Per Call. Per Request Select Per Request to cause request averages to be displayed in tooltips and in the detail tables.
Per Call Select Per Call to causes call averages to be displayed in tooltips and in the detail tables. Active Metric Select Active Metric to make a submenu appear from which you can select one of thirteen options: Avg Cumulative Time, Max Cumulative Time, Min Cumulative Time, Avg Exclusive Time, Avg Call Count, Avg Parameter Data Serialized, Max Parameter Data Serialized, Min Parameter Data Serialized, Avg Return Data Serialized, Max Return Data Serialized, Min Return Data Serialized, Avg Exceptional Exits, and Incomplete %. See below for more information about these options. Click the radio button associated with a metric to recolor the request tree based that metric. Nodes with the highest values of a certain metric are assigned the hottest color. Tip: If you change the active metric, the nodes are recolored based on the new metric but the request tree is not redrawn. This makes it easier for you to observe the change in color while keeping the same node in view. Select Sort Tree to redraw the tree.
Figure 123
Figure 123 The View menu showing the choices listed in the Active Metric submenu
The metrics described below are not only used to color the nodes in the request tree; they also appear in the detail pane and in the tooltips available in the graph pane. See Detail Pane Columns on page 328 for more information about these metrics.
Avg Cumulative Time The average cumulative time for the selected node (and all its children) is used to color the node. Min Cumulative Time The minimum cumulative time taken by the selected node (and all its children) is used to color the node. Max Cumulative Time The maximum cumulative time for the node (and all its children) is used to color the node. Avg Exclusive Time The average exclusive time spent in just this node is used to color the node. Avg Call Count The average call count for this item is used to color the node. Avg Parameter Data Serialized The average amount of data sent to the network when this objects parameters were serialized is used to color the node. Max Parameter Data Serialized The maximum amount of data sent to the network when this objects parameters were serialized is used to color the node. Min Parameter Data Serialized The minimum amount of data sent to the network when this objects parameters were serialized is used to color the node. Avg Return Data Serialized The average amount of data received from the network when a serialized object was returned is used to color the node.
Max Return Data Serialized The maximum amount of data received from the network when a serialized object was returned is used to color the node. Min Return Data Serialized The minimum amount of data received from the network when a serialized object was returned is used to color the node. Avg Exceptional Exits The average number of exceptional exits caused by this object is used to color the node, that is, the number of uncaught exceptions thrown in this node per request or per call, depending on whether Per Request or Per Call is the active selection under Metric Display. Incomplete % The percentage of incomplete calls to the method that occurred (per request or per call, depending on the Metric Display mode) is used to color the node. A service request is incomplete when an Agent has been processing it for longer than the incomplete request timeout period. This timeout can be set in the Session tab of the Recording Settings dialog or using nexusctl; see Incomplete Request Timeout on page 187 and -irt nnn on page 203 for details. When the timeout occurs, a request is considered incomplete whether or not it is active. Bundling Mode Select Bundling Mode to display a submenu with the choices Component, Class, and Method. Component-level bundling displays key J2EE classes and methods in the request tree, giving you an overview of your applications behavior. Class-level bundling displays both J2EE and user classes in the tree, but method calls to other methods within the same class are not displayed. Method-
level bundling displays all classes and method calls, presenting the most detailed request tree. Important: PerformaSures default bundling mode is Component (see Component Instrumentation on page 54 for the meaning of this term). That means that even if you collected your session at full detail, only the key J2EE components are shown if you do not change the bundling mode from its default setting. It is recommended that you begin your performance investigation with the bundling mode set to Component. As your investigation progresses, you can switch to one of the other modes to expose more details about your applications behavior. Detail Table Mode Selecting Detail Table Mode displays a submenu with the choices Item or Tree. Item is selected by default. Item When the radio button associated with Item is selected, the metrics in the detail pane are displayed in the form of a table. All components belonging to a given request are arranged in a single column under the request. Tree When the radio button associated with Tree is selected, the metrics in the detail pane are displayed the form of a tree. All components belonging to a given request are arranged in a tree structure underneath the request. Show Panner Check the checkbox associated with the Show Panner menu item to launch the panner in its own window. You can use the panner to scroll through the graph pane more easily. The rectangular highlighted area in the panner window represents the current view displayed in the graph pane (see Figure 124). Drag this rectangle to reposition the view area within the graph pane. If the Panner Updates Graph While Dragging checkbox is selected in the Request Tree pane of the Edit Options dialog (Tools > Options...), the view area in the graph pane will update continuously. If it is not selected, the view area will update only when you release the mouse button. To enlarge or reduce the highlighted area, zoom in to or out of the request tree using the Zoom Control slider. Keyboard accelerator: Ctrl-Shift-P.
Figure 124
Figure 124
The Show Panner menu item and the panner window
Show/Hide Columns There is a lot of information associated with each item in the request tree which is also listed in the detail pane. In addition to all of the metrics listed in the Active Metric drop-down menu (View > Active Metric or from the toolbar), information about the Agent that collected the data and the metrics Call Count and Total Cumulative Time are also displayed in the detail pane. You can choose whether or not to display Agent information or one or more of these metrics in the detail pane. Select Show/Hide Columns... to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the Agent information or the associated metric. Auto-Fit All Columns Click Auto-Fit All Columns to resize the width of all columns in the table so that all values within each column are visible. Show Filter Bar Select or deselect the checkbox associated with the menu item Show Filter Bar to toggle the display of the Filter Requests bar at the bottom of the graph pane. You can enter a literal string or a regular expression in the Filter Requests bars Filter Requests text field. When you click the Apply button, the string or expression that you entered is matched against the text in the tree nodes to select service requests; the service requests that are selected are displayed in the graph pane. Service requests are selected based on a match with any node in the request
tree, even if that node isnt displayed in the graph pane because of the current bundling mode. If you select the Apply To Root Nodes Only checkbox, the filter will be applied only to entry-point (root) nodes. By default, the Filter Requests text field contains an empty literal string so that all service requests are selected. Tip: If you enter a regular expression in the Filter Requests text field, ensure that the Use Regular Expression checkbox is selected before you click Apply.
Menu BarTools
Note:
Performance Diagnostics When you select the Performance Diagnostics menu item, a submenu is displayed from which you have four choices: Spotlight on Oracle, Spotlight on DB2, Spotlight on WebSphere, and Spotlight on WebLogic. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select Spotlight on WebSphere or Spotlight on WebLogic Server, Spotlight is launched to check the entire application server. When you select Spotlight on Oracle or Spotlight on DB2, Spotlight is launched to check database problems more closely. SQL Tuning When you select the SQL Tuning... menu item, a submenu is displayed from which you have two choices: SQLab Vision for Oracle, and SQL Tuning for DB2. Each choice is enabled if the corresponding cartridge is installed. Options Selecting the Options... menu item launches the Edit Options dialog. See Edit Options Dialog on page 215 for details about using this dialog.
Menu BarWindows
Menu BarHelp
Toolbar
The Request Tree browsers toolbar is located directly below the menu bar.
Figure 125
Figure 125 The toolbar in the Request Tree browser
Figure 126
New Request Time Browser Select New Request Time Browser to launch a new Request Time browser. New SQL Browser Select New SQL Browser to launch a new SQL browser. New Request Tree Browser Select New Request Tree Browser to launch a new Request Tree browser. New Metrics Browser Select New Metrics Browser to launch a new Metrics browser.
New Network Traffic Browser Select New Network Traffic Browser to launch a new Network Traffic browser. New Thresholds Browser Select New Thresholds Browser to launch a new Thresholds browser. Add New Browser to Project The Add New Browser to Project button is enabled if you have not yet added this browser to the Project. Click this button to add the browser to the Project. A new Request Tree browser icon will appear in the Browsers area of the Project window. Export Report Click the Export Report button to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Properties Click the Properties button to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Performance Diagnostics The Performance Diagnostics button displays a drop-down menu from which you have four choices: Spotlight on Oracle, Spotlight on DB2, Spotlight on WebSphere, and Spotlight on WebLogic. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select Spotlight on WebSphere or Spotlight on WebLogic Server, Spotlight is launched to check the entire application server. When you select Spotlight on Oracle or Spotlight on DB2, Spotlight is launched to check database problems more closely.
SQL Tuning The SQL Tuning button displays a drop-down menu from which you have two choices: SQLab Vision for Oracle, and SQL Tuning for DB2. Each choice is enabled if the corresponding cartridge is installed. Link Browsers to Use Same Zone/Break Link Between Browsers Every PerformaSure browser contains a button that allows you to toggle whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. Click the Link Browsers to Use Same Zone button to link the browsers Time Control panels. When linked, the Zonar and (where applicable) the Sightline in each browser are in the same state as the browser in which the button was clicked. Using the Zonar or (where applicable) the Sightline in one browser will impact all other browsers as well. If a problem occurs during a specific interval spanned by the Zonar, linking the browsers can help you track this problem across different browsers. Click the Break Link Between Browsers button to return the browsers Time Control panels to an unlinked state. This allows each browsers Zonar and Sightline to function independently. Hide/Show Detail The Hide/Show Detail button browsers detail pane. Show Panner The Show Panner button causes the panner to appear in its own window. See Show Panner on page 295 for more information about using the panner. Metric Display You can select one of two options from the Metric Display drop-down menu: Per Request and Per Call. Per Request Select Per Request to cause request averages to be displayed in tooltips and in the detail tables. toggles the display of the Request Tree
Per Call Select Per Call to causes call averages to be displayed in tooltips and in the detail tables. Active Metric Select one of the options in the Active Metric drop-down menu to recolor the nodes in the request tree. The nodes are recolored based on which ones are the most expensive relative to the metric you have chosen. Nodes with the highest values are assigned the hottest color. See Active Metric on page 292 for more information. FastFind Click the FastFind button to expose the top n most expensive nodes and scroll the most expensive node into view. Bundling Mode Select one of the options in the Bundling Mode drop-down menu to change the level of detail with which the request tree is displayed. The choices are Component, Class, and Method. See Bundling Mode on page 294 for more information.
Time Control Panel

The Time Control panel is located directly below the Request Tree browsers toolbar. This panel has the same controls in all PerformaSure browsers. See Time Control Panel on page 219 for a detailed description of its controls.
Request Tree Browser Graph PaneSummary

The following table describes the controls available in the graph pane. See Request Trees on page 308 and Request Tree Tooltips on page 312 for information about request trees, tree nodes, and tooltips in the graph pane. Request Tree Browser Graph Pane
Control
Resize Sliders Disclosure Triangles Show/Hide Child Node Buttons Color Scale Toggle Button Zoom Control
Default Value
Minimum column width Turned for expansion in group nodes Show Child Node Enabled 100%
Description
Control the width of the columns in which the tree nodes are displayed. Toggle the display of method nodes within group nodes. Toggles the display of child nodes. This button does not cause child nodes to be collapsed or expanded. Toggles the display of the color chart on the left side of the graph pane. Moving the slider to the right causes the graph pane to zoom in to the request tree; moving it to the left causes it to zoom out.
The following tables describe the options available from the contextual (rightclick) menus in the graph pane. Request Tree Browser Graph PaneContextual Menu: Entry-Point Node
Control
Expand All Children
Type
Menu item
Description
Displays the complete set of method nodes in the group nodes. This option is available if any of the group nodes in a request tree have been collapsed. Hides the child nodes for the request in their current state. This option is available if any of the child nodes are visible. Displays the child nodes for a request in the state in which they were hidden. This option is available if the child nodes are hidden. Collapses and hides the child nodes for a request. This option is available if any of the child nodes are visible. Isolates the entry-point node and its sub-tree, recoloring them accordingly. The display of other entry-point nodes and sub-trees after this option is selected can vary. See Isolate Sub-Tree on page 317. Prunes the entry-point node, causing all trees in the graph pane to be recolored accordingly. The nodes un-pruned sub-trees will remain unpruned. This node will display as ghosted, allowing it to be un-pruned.
Hide Children Show Children Collapse All Children Isolate Sub-Tree
Prune Node
Menu item
Request Tree Browser Graph PaneContextual Menu: Entry-Point Node

Control
Prune Sub-Tree
Type
Menu item
Description
Prunes the entry-point node and its sub-tree, causing all trees in the graph pane to be recolored accordingly. This node will display as ghosted, allowing it to be un-pruned; the display of the sub-tree can vary. See Prune Sub-Tree on page 318. Un-prunes the entry-point node and its sub-tree, causing all trees in the graph pane to be recolored accordingly. This item is disabled if none of this nodes sub-trees have been pruned. Un-prunes all request trees, causing them to be recolored accordingly. This item is disabled if no nodes or sub-trees have been pruned. Allows you to paste class names, method names, or SQL queries into other applications. Launches a new Request Time browser based on the request to which the node belongs. Enabled in the entry-point nodes of request trees that include one or more JDBC node. Select this option to display a submenu with two choices. See View SQL Response Times on page 319 for more information. Launches a new Metrics browser based on metrics associated with the entry-point node. See View Related Metrics on page 319 for more information. Disabled in entry-point nodes. Disabled in entry-point nodes. Disabled in HTTP nodes but enabled in other entry-point nodes.
Un-Prune Sub-Tree
Menu item
Un-Prune All Copy Node Name View Response Times View SQL Response Times
View Related Metrics
Menu item
Performance Diagnostics SQL Tuning Export JProbe Launcher File
Request Tree Browser Graph PaneContextual Menu: Group Node

Control
Hide Group Items Show Group Items Isolate Sub-Tree
Type
Description
Hides the method nodes. This item is available if the method nodes are displayed. Displays the method nodes. This item is available if the method nodes are hidden. Isolates the group node and (if applicable) its sub-trees, causing all trees in the graph pane to be recolored accordingly. The display of other nodes and sub-trees after this option is selected can vary. See Isolate SubTree on page 320.
Request Tree Browser Graph PaneContextual Menu: Group Node

Control
Prune Node
Type
Menu item
Description
Prunes the group node, causing all trees in the graph pane to be recolored accordingly. The nodes un-pruned sub-trees will remain unpruned. The display of pruned group nodes can vary. See Prune Node on page 321. Prunes the group node and (if applicable) its sub-trees, causing all trees in the graph pane to be recolored accordingly. The display of pruned group nodes and their sub-trees can vary. See Prune Sub-Tree on page 321. Un-prunes the group node and (if applicable) its sub-trees, causing all trees in the graph pane to be recolored accordingly. This item is disabled if neither this node nor its sub-trees have been pruned. Un-prunes all request trees, causing them to be recolored accordingly. This item is disabled if no nodes or sub-trees have been pruned. Allows you to paste class names, method names, or SQL queries into other applications. Launches a new Request Time browser based on the request to which the node belongs. Enabled in JDBC group nodes and in all group nodes in request trees that include one or more JDBC node. Select this option to display a submenu with two choices. See View SQL Response Times on page 322 for more information. Launches a new Metrics browser based on metrics associated with the group node. See View Related Metrics on page 322 for more information. Enabled in JDBC group nodes. Each option in the Performance Diagnostics submenu is enabled if you have installed the corresponding Spotlight cartridge. Enabled in JDBC group nodes. Each option in the SQL Tuning submenu are enabled if you have installed SQLab Vision for Oracle or SQL Tuning for DB2. Disabled in the contextual menus for JDBC group nodes but enabled in other group nodes. See Creating a JProbe Launcher File on page 332 for more information.
Prune Sub-Tree
Menu item
Un-Prune Sub-Tree
Menu item
View Related Metrics
Menu item
Performance Diagnostics
Menu item
SQL Tuning
Menu item
Export JProbe Launcher File
Menu item
Request Tree Browser Graph PaneContextual Menu: Method Node

Control
Expand All Children
Type
Menu item
Description
Expands and displays the methods child nodes. This option is only available in the contextual menus of method nodes with collapsed child nodes. Hides the methods child nodes in their current state. This option is only available in the contextual menus of method nodes with visible child nodes. Displays the methods child nodes in the state in which they were hidden. This option is only available in the contextual menus of method nodes with hidden child nodes. Collapses and hides a methods child nodes. This option is only available in the contextual menus of method nodes with visible child nodes. Isolates the method node and (if applicable) its sub-tree, recoloring them accordingly. The display of other nodes and sub-trees after this option is selected can vary; see Isolate Sub-Tree on page 324. Prunes the method node, causing all trees in the graph pane to be recolored accordingly. If it is the only member of a group node, then the group node is pruned. When pruned, a method node/group node that is in the path between two unpruned nodes will be displayed as ghosted. The display of pruned method nodes/group nodes can vary; see Prune Node on page 324. Prunes the method node and (if applicable) its sub-tree, causing all trees in the graph pane to be recolored accordingly. If it is the only member of a group node, then the group node is pruned. The display of pruned methods nodes/group nodes/sub-trees can vary; see Prune Sub-Tree on page 325. Un-prunes the method node and (if applicable) its sub-tree, causing all trees in the graph pane to be recolored accordingly. This item is disabled if none of the method nodes sub-trees have been pruned. Un-prunes all request trees, causing them to be recolored accordingly. This item is disabled if no nodes or sub-trees have been pruned. Allows you to paste class names, method names, or SQL queries into other applications. Launches a new Request Time browser based on the request to which the node belongs. Enabled in members of JDBC group nodes and in all method nodes in request trees that include one or more JDBC group node. Select this option to display a submenu with two choices. See View SQL Response Times on page 326 for more information.
Hide Children
Menu item
Show Children
Menu item
Collapse All Children Isolate Sub-Tree
Menu item Menu item
Prune Node
Menu item
Prune Sub-Tree
Menu item
Un-Prune Sub-Tree
Menu item
Request Tree Browser Graph PaneContextual Menu: Method Node

Control
View Related Metrics Performance Diagnostics
Type
Menu item Menu item
Description
Launches a new Metrics browser based on metrics associated with the node. See View Related Metrics on page 322 for more information. Enabled in members of JDBC group nodes. Each option in the Performance Diagnostics submenu is enabled if you have installed the corresponding Spotlight cartridge. Enabled in members of JDBC group nodes. Each option in the SQL Tuning submenu are enabled if you have installed SQLab Vision for Oracle or SQL Tuning for DB2. Enabled in the contextual menus for all method nodes. See Creating a JProbe Launcher File on page 332 for more information.
SQL Tuning
Menu item
Export JProbe Launcher File
Menu item
Request Tree Browser Graph PaneFull Detail

The Request Tree browsers graph pane includes several elements.
Figure 127
Figure 127 Elements in the Request Tree browsers graph pane
Request Trees
The request trees in the Request Tree browsers graph pane diagram requests from end to end. These trees are comprised of nodes. Method nodes are displayed as rectangular boxes within group nodes. Important: Static methods may appear as root nodes in the graph pane since they are not considered part of a component: they can be called outside the component context, even if their class is not deployed in any way. This is also the reason why static methods will not have deployed names.
Resize Sliders
The Resize Sliders at the top of the graph pane control the width of the nodes in their respective columns. A slider marks the right-hand edge of the column it controls. If a column is not wide enough, the information displayed in the nodes in that column may have to be abbreviated. Drag the Resize Slider to expose more or less text in the nodes. Double-click on a Resize Slider to display the full text in the nodes.
Request Tree Display

Coloring and Sorting By default, the nodes in the request tree are colored by Avg Cumulative Time. The nodes can be recolored by selecting a different metric from the Active Metric submenu (View > Active Metric) or from the Active Metric drop-down menu in the toobar. See Active Metric on page 292 for more information. After recoloring the trees, you can sort it based on the new metric by choosing View > Sort Tree. Bundling To reduce the complexity of the tree, some information is hidden in the graph pane when you select Component or Class from the Bundling Mode dropdown menu (View > Bundling Mode or from the toolbar). If you have selected one of these options, methods that call one or more methods belonging to the same class are displayed bundled together as a single node in the request tree, labeled by the method that starts the string of calls.
Figure 128
Figure 128 Actual call graph and its representation in the Request Tree
To understand why some methods are not shown in the Request Tree when Class or Component bundling is selected, look at the situation diagrammed in Figure 128. Method a1() in class A calls methods b1() and b2() in class B. These method calls appear in the Request Tree representation as expected. But method b1() also calls within class B to b3(), which in turn calls b4(). Because these method calls have the same parent class (they do not leave one class and enter another) they are not graphed. The Request Tree browsers representation of the actual request tree doesnt show b3() or b4(), but it does show c2(), even though the hidden method b4() calls it. That is because the call originated in one class and its target was in another. This does not mean that the methods cant be seen at all. You can display internally-called methods by choosing Method from the Bundling Mode dropdown menu (View > Bundling Mode or in the toolbar). In addition, selecting this option allows you to look at the metrics for these methods in tooltips.
Request Tree Nodes

The nodes in the request tree have different shapes to make it easy to distinguish them by function. A basic group node is shown in Figure 129. Detailed information about the nodes contents is available in tooltips. Hover the cursor over the header for a group node or over the method nodes in a group to make the appropriate tooltip appear. See Request Tree Tooltips on page 312 for more information. Contextual menus are also available when you right-click on various parts of a request tree. See Contextual Menus in the Graph Pane on page 316 for details.
Figure 129
Figure 129 A basic group node
Basic group nodes are used for JSPs, Servlets, EJBs and other user-defined classes, but not for JDBC, JNDI, or JMS calls. An entry-point node that represents an HTTP or an RMI call looks like a method node except that it has an Identifier bar (see Identifier Bars below). An HTTP request may be handed off to the HTTP server in the application server. That node will have the same appearance as an entry-point HTTP node.
Figure 13 0
Figure 130 An entry-point node representing an HTTP request
Entry-point nodes can also represent, for example, EJBs, JDBC calls, or JMS calls. Entry-point EJB, JDBC, and JMS nodes have the same appearance as EJB, JDBC and JMS group nodes, respectively. These types of entry-point nodes contain one or more method nodes, an Identifier bar, and a Disclosure Triangle. As mentioned above, basic group nodes are used for EJBs. JDBC and JMS group nodes are described below. A request tree can have a root node that represents a class that does not belong to a standard or custom component technology. This type of entry-point node will have the same appearance as a basic group node. When the display mode is set to Component Technology (View > Display By), the Identifier bar for this type of entry-point node will be colored grey and the tooltip for this nodes Identifier bar will identify it as Other. A node representing a JDBC call is shown in Figure 131.
Figure 131
Figure 131 A JDBC group node
As shown in Figure 131, JDBC group nodes have a cylindrical shape. If the information is available, the header of a JDBC group node lists the connection pool it is using (or the datasource name if the session was recorded with Oracle 9iAS), the URL, and the SQL statement to which all methods in the group are related. If none of this information is available, the group node will be identified simply as JDBC. Nodes that represent JMS or JNDI calls look like the node shown in Figure 132. JMS or JNDI group nodes have the shape of a truncated diamond.
Figure 132
Figure 132 A JMS or JNDI group node
The shape of JDBC, JMS, and JNDI group nodes makes them easily distinguishable from basic group nodes or from entry-point nodes, even when you have zoomed out from the request tree. Identifier Bars A colored vertical bar called an Identifier bar appears on the left side of every entry-point and group node. The color of each Identifier bar represents a different tier or component technology, helping you distinguish between the tiers in your application or between component types. Each Identifier bar provides a tooltip distinct from that of the header of the group node. When you hover the cursor over an Identifier bar, a tooltip will provide the name of the corresponding tier or component technology. Important: PerformaSure always instruments constructors, initializers, and static methods as generic methods regardless of their classs component technology. As a result, they will be identified as generic methods in the request tree. For example, when the display mode is set to Component Technology (View > Display By), the Identifier bar on a node that represents a constructor of a message EJB would be colored grey and the tooltip for this nodes Identifier bar would identify it as Other.
Color Scale Toggle Button

Click this button to display a color scale on the left side of the graph pane. You can compare this scale with the background color of the method nodes in the request trees. Each color represents a range within a metric count based on the active metric. Each change in color represents a proportional change in the metric count. The hot color at the top of the chart is used to mark the most expensive methods. When the color chart is visible, its tooltips show the metric range spanned by each color.
Zoom Control Slider

A typical request tree displays a considerable amount of information, and it is not likely that it will fit in the graph pane unless you reduce its scale. You can use the Zoom Control slider to reduce the scale of the request trees displayed in the graph pane by as much as 90%, allowing you to get an overall impression of events.
Request Tree Tooltips

Two tooltips are associated with every group node and with every method node within a group node: one tooltip appears when Per Request is selected from the Metric Display drop-down menu (View > Metric Display or from the toolbar) and the other appears when Per Call is selected. These tooltips display metrics for the group or method node over which you hover the cursor. Important: There may be a discrepancy between the figure displayed in the tooltip for the group node and the sum of the call counts displayed in the tooltips for the method nodes in that group. The reason for this disparity is that the call count is rounded differently for individual method nodes and for the group node. This discrepancy increases with the number of method nodes in a group. Based on the way the call counts are rounded, the call count for the group node may provide a more accurate figure than the sum of the rounded call counts for the method nodes. Each tooltips header contains the name of the part of the node over which you hover the cursor followed on the next line by the tier name. Tooltip for an HTTP node Each tooltip for an HTTP node includes Time and Counts sections and a Sampled Requests (%) field. The metrics listed in the Time and Counts sections are
accumulated for all sampled requests. A dash (-) indicates that a metric is unavailable. Important: The tooltips for HTTP nodes do not provide distinguishing labels for HTTPS nodes.
The Total Cumulative Time field shows the total time taken by all requests of this type that completed during the interval spanned by the Zonar. The Call Count field shows the total number of requests of this type that completed during the interval spanned by the Zonar. The Sampled Requests field allows you to calculate how many of these requests were Tagged and Followed. Only root nodes display the Sampled Requests field. As shown in Figure 133 and Figure 134, per-request and per-call metrics are the same in the tooltips for an HTTP node. This is because request counts and call counts are the same for root nodes.
Figure 133
Figure 133 Tooltip for an HTTP node when Per Request is selected
Figure 134
Figure 134 Tooltip for an HTTP node when Per Call is selected
Tip: Only completed requests are included in the tooltips time statistics. Thus if for a certain request, its counts are: Sampled Call Count: 5 Incomplete Call Count: 7 Not Sampled Call Count: 1 For this case, even though only one request was not sampled, the incomplete requests are made part of the Not Sampled Call Count, resulting in a statistic for Sampled Requests of: Sampled Requests: 5/13 = 38.5% Even though requests that do not complete are not included in the time statistics, the execution location when the incomplete timeout occurrred is recorded. Tooltips for group and method nodes The tooltips for group and method nodes (such as, for example, EJB nodes) display Time and Counts sections; they do not include Total Cumulative Time or Sampled Requests fields since the information listed in these fields pertains only to a service request as a whole. Depending on whether Per Request or Per Call is selected, both cumulative and exclusive times can be different in an EJB tooltip, for example. This is because an EJB can be called multiple times in one service request. In the tooltips for group and method nodes, the call count depends on which type of averages are being displayed. When Per Request is selected, the call count in the tooltip for a method node represents the number of times the object was called per request. For example, a method that was called 50 times in a sample of 20 requests shows a request-averaged call count of 2.5. When Per Call is selected, the call count in the tooltip for a method node shows the total number of times that the object was called. If the root node shows that sampling was at 100%, the call count is exact, otherwise it is extrapolated.
Figure 13 5
Figure 135 Tooltip for a method node in an EJB group node when Per Request is selected
If you compare Figure 135 to Figure 136, you can see that the per-request tooltip shows how many times the EJB was called per request, while the per-call tooltip shows the number of times the EJB was called overall.
Figure 136
Figure 136 Tooltip for a method node in an EJB group node when Per Call is selected
In the per-request tooltip, an Avg Call Count of 1 indicates that the EJB was called once in every request. If this number is less than 1, internal logic in the application must be determining if the EJB needs to be called. If the number is much greater than 1, the applications logic is making multiple calls in every request. This is often an indication of a performance problem that can be eliminated by, for instance, calling the EJB once and caching some information. Exceptional exits can be greater than 1 in the per-request tooltip, again because of calling the EJB multiple times in every request. In the per-call tooltip however, exceptional exits cannot exceed 1 because an EJB can cause at most one exceptional exit each time it is called. Other types of group nodes include Class, Servlet, JDBC, JNDI, and JMS nodes. The format of these nodes tooltips is the same as the format of the tooltips for EJB group nodes. Tooltips for an RMI node A tooltip for an RMI node is shown in Figure 137. It contains extra fields in which the volume of traffic for passing method parameters and for receiving returned data is displayed.
Figure 137
Figure 137 Tooltip for an RMI node when Per Request is selected

You can right-click anywhere on or around the request trees to make a contextual menu appear. The items in this menu will differ depending on where you rightclick with the mouse. Right-clicking outside the Request Trees Right-click anywhere on the blank space outside the request trees and a menu containing the item Un-Prune All appears. This item is disabled if no nodes or sub-trees in the request trees have been pruned. If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting this option will cause all pruned nodes and sub-trees to no longer display as ghosted. Right-clicking an Entry-Point Node Right-click on an entry-point node and additional choices become available in the contextual menu (Figure 138).
Figure 138
Figure 138 The contextual menu for an entry-point node
Expand All Children If any of an entry-point nodes children have been hidden or collapsed (so that the method nodes are hidden), the choice Expand All Children is available. Select this option to display the child nodes in their entirety. Hide Children If any of an entry-point nodes children are visible, the choice Hide Children is available. Select this option to hide the child nodes without collapsing them. Show Children If an entry-point nodes children have been hidden, the choice Show Children is available. Select this option if you want to display the child nodes in the state in which they were hidden. Collapse All Children If an entry-point nodes children are showing, the choice Collapse All Children is available. Select this option to hide and collapse the requests child nodes. Isolate Sub-Tree Click Isolate Sub-Tree to isolate the entry-point node and its sub-tree. Selecting this option recolors this node and its sub-tree accordingly: the range of values for the active metric that you selected does not include values from pruned nodes.
Depending on whether or not you checked the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), this nodes previously pruned sub-trees will either remain hidden or continue to display as ghosted when you select Isolate Sub-Tree. If you did not check the Hide Pruned SubTrees checkbox in the Edit Options dialog, selecting Isolate Sub-Tree will cause the other (non-isolated) entry-point nodes and their sub-trees to display as ghosted. Prune Node Click Prune Node to prune an entry-point node. It will display as ghosted, allowing you to un-prune it. This nodes un-pruned sub-trees will remain unpruned. Un-Prune Node Click Un-Prune Node to un-prune an entry-point node. Selecting this option will cause the node to no longer display as ghosted. Prune Sub-Tree Click Prune Sub-Tree to prune an entry-point node and its sub-tree. The entrypoint node will display as ghosted, allowing you to un-prune it. If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting this option will cause this nodes sub-tree to display as ghosted. Un-Prune Sub-Tree Click Un-Prune Sub Tree to un-prune an entry-point node and its sub-tree. This item is disabled if none of the nodes sub-trees have been pruned. If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting this option will cause this node and its subtree to no longer display as ghosted. Un-Prune All Click Un-Prune All to un-prune all nodes and sub-trees. This item is disabled if no nodes or sub-trees have been pruned. Copy Node Name Click Copy Node Name if you want to be able to paste class names, method names, or SQL queries into another application, such as a spreadsheet.
View Response Times Click View Response Times to launch a new Request Time browser based on the request to which the node on which you right-clicked belongs. View SQL Response Times The menu item View SQL Response Times is enabled in the root nodes of request trees that include one or more JDBC group node. Select this option to display a submenu with two choices: For All Statements in Request and For Selected Statements. Select For All Statements in Request to launch a new SQL browser based on this request. Select For Selected Statements to launch a new SQL browser based on the statements that you selected. The option For Selected Statements is only enabled in JDBC nodes with statements. View Related Metrics Select this option to launch a new Metrics browser based on metrics associated with the entry-point node on which you right-clicked. The specific metrics graphed in the new browser will depend on the nodes component type, but will include response time metrics for the request and for the component technology within that request. Performance Diagnostics The menu item Performance Diagnostics is disabled in entry-point nodes. SQL Tuning The menu item SQL Tuning is disabled in entry-point nodes. Export JProbe Launcher File The option Export JProbe Launcher File menu item is disabled in HTTP nodes and JDBC group nodes but enabled in the contextual menus for other group nodes and for all method nodes. See Creating a JProbe Launcher File on page 332 for more information. Right-clicking the Header of a Group Node Right-click on the header of a group node to make a contextual menu appear for that node (Figure 139). This menu contains many of the same choices as the contextual menu for an entry-point node.
Figure 13 9
Figure 139 The contextual menu for the header of a group node
Hide Group Items The choice Hide Group Items is available if the method nodes are displayed. Select this option to hide the methods that were called. Show Group Items If the node is collapsed, hiding the method nodes, the choice Show Group Items is available. Select this option to show the methods that were called. Isolate Sub-Tree Select Isolate Sub-Tree to isolate the group node on which you right-clicked and its sub-tree. Selecting this option recolors this node and its sub-tree accordingly: the range of values for the active metric that you selected does not include values from pruned nodes. Depending on whether or not you checked the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), this nodes previously pruned sub-trees will either remain hidden or continue to display as ghosted when you select Isolate Sub-Tree. If you did not check the Hide Pruned SubTrees checkbox in the Edit Options dialog, selecting Isolate Sub-Tree will cause all other (non-isolated) nodes and sub-trees to display as ghosted.
Prune Node Click Prune Node to prune a group node. If this node is in the path between two nodes that have not been pruned, it will display as ghosted. Tip: The range of values for the active metric that you selected does not include values from pruned nodes. Prune the most expensive node to exclude it from this range of values. The call tree will be recolored, allowing you to use the new maximum value to highlight slightly less expensivebut still problematicnodes that might otherwise have been overshadowed. If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting this option will cause the node to display as ghosted. Un-Prune Node Click Un-Prune Node to un-prune a group node. Tip: If you want to un-prune a node that is not displayed in the request tree because you checked the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), right-click on its parent node. A contextual menu will appear in which Un-Prune Sub-Tree is enabled. Select this option. If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting this option will cause this node to no longer display as ghosted. Prune Sub-Tree Click Prune Sub-Tree to prune a group node and, if applicable, its sub-trees. If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting this option will cause the node and its subtree to display as ghosted. Un-Prune Sub-Tree Click Un-Prune Sub Tree to un-prune a group node and, if applicable, its subtrees. This item is disabled if neither the node nor its sub-trees have been pruned. If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting this option will cause this node and its subtrees to no longer display as ghosted.
Un-Prune All Click Un-Prune All to un-prune all nodes and sub-trees. This item is disabled if no nodes or sub-trees have been pruned. Copy Node Name Click Copy Node Name if you want to be able to paste class names, method names, or SQL queries into another application, such as a spreadsheet. View Response Times Click View Response Times to launch a new Request Time browser based on the request to which the node on which you right-clicked belongs. View SQL Response Times The menu item View SQL Response Times is enabled in JDBC group nodes and in all group nodes in a request tree that includes one or more JDBC group node. Select this option to display a submenu with two choices: For All Statements in Request and For Selected Statements. Select For All Statements in Request to launch a new SQL browser based on this request. Select For Selected Statements to launch a new SQL browser based on the statements that you selected. The option For Selected Statements is only enabled in JDBC group nodes with statements. View Related Metrics Select this option to launch a new Metrics browser based on metrics associated with the node on which you right-clicked. The specific metrics graphed in the new browser will depend on the nodes component type, but will include response time metrics for the root request and for the component technology within that request. Performance Diagnostics The menu item Performance Diagnostics is enabled in JDBC group nodes. When you select the Performance Diagnostics menu item, a submenu is displayed from which you have two choices: Spotlight on Oracle and Spotlight on DB2. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select one of these options, Spotlight is launched to check database problems more closely.
SQL Tuning The menu item SQL Tuning is enabled in JDBC group nodes. See SQL Tuning on page 298 for more information about the options available under this menu item. Export JProbe Launcher File The option Export JProbe Launcher File is disabled in JDBC group nodes but enabled in the contextual menus for other group nodes. See Creating a JProbe Launcher File on page 332 for more information. Right-clicking a Method Node Right-click on a method node (displayed as a rectangular box within the group node) to make its contextual menu appear (Figure 140). The choices in this menu are similar to those in the contextual menu for an entry-point node.
Note:
The options Expand All Children, Hide Children, Show Children, and Collapse All Children are only available in the contextual menus for method nodes with child nodes.
Figure 140
Figure 140 The contextual menu for a method node
Expand All Children If a methods child nodes have been hidden or collapsed, the choice Expand All Children is available. Select this option to display all the methods that were called in this methods child nodes.
Hide Children If a methods child nodes are visible, the choice Hide Children is available. Select this option to hide the child nodes in their current state. Show Children If a methods child nodes are hidden, the choice Show Children is available. Select this option if you want to display the child nodes in the state in which they were hidden. Collapse All Children If a methods child nodes are visible, the choice Collapse All Children is available. Select this option to hide and collapse the child nodes. Isolate Sub-Tree Click Isolate Sub-Tree to isolate a method node and, if applicable, its sub-tree. Selecting this option recolors the method node and its sub-trees nodes accordingly. If the method node on which you right-click is the only member of a group node, selecting Isolate Sub-Tree isolates the whole group node and, if applicable, the method nodes sub-tree. If you have not checked the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting Isolate Sub-Tree causes all other nodes and sub-trees to display as ghosted. Prune Node Click Prune Node to prune the method node. If the method node on which you right-click is the only member of a group node, selecting Prune Node prunes the whole group node. If the whole node or the method node is in the path between two nodes that have not been pruned, it will display as ghosted. If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting Prune Node will cause the whole node or the method node to display as ghosted.
Un-Prune Node Click Un-Prune Node to un-prune a method node. Tip: If you want to un-prune a method node that is not displayed in the request tree because you checked the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), right-click on the group nodes header. A contextual menu will appear in which UnPrune Sub-Tree is enabled. Select this option. If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting this option will cause the method node to no longer display as ghosted. Prune Sub-Tree Click Prune Sub-Tree to prune a method node and, if applicable, its sub-trees. If the method node on which you right-click is the only member of a group node, selecting Prune Sub-Tree causes the whole group node to be pruned. If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting Prune Sub-Tree will cause the method node (or the whole node) and its sub-trees to display as ghosted. Un-Prune Sub-Tree Click Un-Prune Sub Tree to un-prune a method node and, if applicable, its subtrees. This item is disabled if neither the method node nor its sub-trees have been pruned. If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options...), selecting this option will cause the method node and its sub-trees to no longer display as ghosted. Un-Prune All Click Un-Prune All to un-prune all nodes and sub-trees. This item is disabled if no nodes or sub-trees have been pruned. Copy Node Name Click Copy Node Name if you want to be able to paste class names, method names, or SQL queries into another application, such as a spreadsheet.
View Response Times Click View Response Times to launch a new Request Time browser based on the request to which the node on which you right-clicked belongs. View SQL Response Times The menu item View SQL Response Times is enabled in JDBC group nodes and in all group nodes in a request tree that includes one or more JDBC node. Select this option to display a submenu with two choices: For All Statements in Request and For Selected Statements. Select For All Statements in Request to launch a new SQL browser based on this request. Select For Selected Statements to launch a new SQL browser based on the statements that you selected. The option For Selected Statements is only enabled in JDBC group nodes with statements. View Related Metrics Select this option to launch a new Metrics browser based on metrics associated with this node. See View Related Metrics on page 322 for more information. Performance Diagnostics The menu item Performance Diagnostics is enabled in JDBC group nodes. When you select the Performance Diagnostics menu item, a submenu is displayed from which you have two choices: Spotlight on Oracle and Spotlight on DB2. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select one of these options, Spotlight is launched to check database problems more closely. SQL Tuning The menu item SQL Tuning is enabled in JDBC group nodes. See SQL Tuning on page 298 for more information about the options available under this menu item. Export JProbe Launcher File The option Export JProbe Launcher File menu item is enabled in the contextual menus for all method nodes. See Creating a JProbe Launcher File on page 332 for details. Right-clicking a Disclosure Triangle Right-click on a Disclosure Triangle and a contextual menu appears (Figure 141). This menu contains some of the same options as the contextual menu for a group
node. See Hide Group Items on page 320 and Show Group Items on page 320 for details.
Figure 141
Figure 141 The contextual menu for a Disclosure Triangle
Right-clicking a Show/Hide Child Node Button Right-click on the round Show/Hide Child Node button (located on the right side of an entry-point node or a group node) and a contextual menu appears. This menu contains some of the same options as the contextual menu for a method node. See Expand All Children on page 323, Hide Children on page 324, Show Children on page 324, and Collapse All Children on page 324 for details.
Figure 142
Figure 142 The contextual menu for a Show/Hide Child Node button.
Zooming the Request Tree

To zoom in to or out from the request tree, Ctrl-Click and drag on the request tree or use the Zoom Control slider.
Request Tree Browser Detail Pane

The Request Tree browsers detail pane provides an explorer view of the requests that are depicted graphically in the graph pane. The detail pane shows
information including method names, cumulative times, and call counts in a tabular fashion. Tip: Double-click a node in the request tree to transfer focus to the corresponding item in the Request Tree detail pane. You dont have to spend time searching for the item. The process works in reverse as well. Double-click an item in the Request Tree detail pane to transfer focus to the corresponding node in the request tree. Because multiple methods of one type may exist in the tree, the most expensive one is selected based on the active metric.
Figure 14 3
Figure 143 The detail pane in the Request Tree browser
Detail Pane Columns

The columns in the detail pane (Figure 144) are described next.
Figure 14 4
Figure 144 The column headers in the Request Tree browsers detail pane
Name The Name column lists the URLs that were called during the interval spanned by the Time Control panels Zonar; see Time Control Panel on page 219 for more information. Each URL listed in the Name column can be expanded to show the methods that have been called.
Agent The Agent that collected the data. Avg Call Count The Avg Call Count column lists the number of times the method was called per request during the interval spanned by the Zonar. Call Count The Call Count column lists the total number of times the object was called during the interval spanned by the Zonar. The call count for a root node is the number of requests that executed to completion during the interval spanned by the Zonar. All requests are counted, even when the number of sampled requests is less than 100%. Avg Cumulative Time The Avg Cumulative Time is the Total Cumulative Time divided by the call count. It is the average time taken by the method (and its children) during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or Per Call) that you selected (View > Metric Display or from the toolbar), the Avg Cumulative Time is displayed in seconds per request or seconds per call. Max Cumulative Time The Max Cumulative Time column lists the longest total time taken by all calls to the selected method (and its children) during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or Per Call) that you selected (View > Metric Display or from the toolbar), the Max Cumulative Time is displayed in seconds per request or seconds per call. Min Cumulative Time The Min Cumulative Time column lists the shortest total time taken by all calls to the selected method (and its children) during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or Per Call) that you selected (View > Metric Display or from the toolbar), the Min Cumulative Time is displayed in seconds per request or seconds per call. Total Cumulative Time The Total Cumulative Time column lists the total time (in seconds) taken by all requests that completed during the interval spanned by the Zonar. If requests were sampled at less than 100% of the Nexus ability, Total Cumulative Time is an
extrapolated value. See Sampling Tab on page 188 and Sampling Parameters on page 204 for more information about setting the sampling rate using the Recording Settings dialog or nexusctl. Avg Exclusive Time The Avg Exclusive Time column lists the average time taken by the method, excluding its children, during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or Per Call) that you selected (View > Metric Display or from the toolbar), the Avg Exclusive Time is displayed in seconds per request or seconds per call. Avg Parameter Data Serialized The Avg Parameter Data Serialized column lists the average number of bytes for any serialized objects that were passed as parameters as the result of an RMI method call. Averaging takes place over the requests that completed during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or Per Call) that you selected (View > Metric Display or from the toolbar), the number of bytes is displayed per request or per call. Max Parameter Data Serialized The Max Parameter Data Serialized column lists the number of bytes of the largest of the serialized objects that were passed as parameters as the result of all calls to the RMI method during any service request instance. This maximum applies to the requests that completed during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or Per Call) that you selected (View > Metric Display or from the toolbar), the number of bytes is displayed per request or per call. Min Parameter Data Serialized The Min Parameter Data Serialized column lists the number of bytes of the smallest of the serialized objects that were passed as parameters as the result of all calls to the RMI method during any service request instance. This minimum applies to the requests that completed during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or Per Call) that you selected (View > Metric Display or from the toolbar), the number of bytes is displayed per request or per call. Avg Return Data Serialized The Avg Return Data Serialized column lists the average number of bytes for any serialized objects that were received as the result of an RMI method call. Averaging takes place over the requests that completed during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or
Per Call) that you selected (View > Metric Display or from the toolbar), the number of bytes is displayed per request or per call. Max Return Data Serialized The Max Return Data Serialized column lists the number of bytes of the largest of the serialized objects that were received as the result of all calls to the RMI method during the service request instance. This maximum applies to the requests that completed during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or Per Call) that you selected (View > Metric Display or from the toolbar), the number of bytes is displayed per request or per call. Min Return Data Serialized The Min Return Data Serialized column lists the number of bytes of the smallest of the serialized objects that were received as the result of all calls to the RMI method during the service request instance. This minimum applies to the requests that completed during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or Per Call) that you selected (View > Metric Display or from the toolbar), the number of bytes is displayed per request or per call. Avg Exceptional Exits The Avg Exceptional Exits column lists the average number of exceptional exits that occurred. Averaging takes place over the requests that completed during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or Per Call) that you selected (View > Metric Display or from the toolbar), this number is displayed per request or per call. Exceptions that are caught or handled within the method do not cause exceptional exits. Incomplete % The Incomplete % column lists the percentage of incomplete calls to the method that occurred during the interval spanned by the Zonar. Depending on the Metric Display option (Per Request or Per Call) that you selected (View > Metric Display or from the toolbar), this percentage is displayed per request or per call. Item/Tree Toggle Button Use the item/tree toggle button ( ) at the far right of the header row to switch between a tree view and a list view of the metric data. The way the lines are drawn inside the button does not indicate the mode of the current view, instead it
indicates which view will appear when you click on the button. In the list view, all the methods associated with a given request are listed in a single column. In the tree view, calling relationships are preserved. In either view, the items in the detail pane are the same as those diagrammed in the graph pane. While the graph pane color-codes the most expensive requests, clicking on a column header in the detail pane sorts the rows based on the values in that column. Tip: You may have tried to find where a method was called by entering its name in the Filter Requests text field at the bottom of the graph pane and then clicking Apply. Subsequently, you saw that a request tree did appear in the graph pane, indicating that the method is somewhere in that request tree. Yet upon searching the call tree, the method did not seem to be there, or anywhere in the list of names in the detail pane. The solution is to select Method from the Bundling Mode drop-down menu (View > Bundling Mode or in the toolbar). When you select this option, methods that call other methods in the same class will be shown.
Creating a JProbe Launcher File

By using PerformaSure, you may have found that a certain method or method group node is taking a long time to complete. Now that you have determined the node, how do you examine the internal behavior of the method to see where it is spending its time? You can use JProbe to examine the details of the methods operation.
Creating a JProbe Launcher File

1.
Open the Edit Options dialog (Tools > Options...) and select Request Tree from the pane on the left-hand side. Select JProbe 4.x, JProbe 5.0, or JProbe 5.2 from the JPL File Format drop-down menu. Click OK to confirm your selection and close the dialog. Select one or more method nodes in the Request Tree browser.
2.
3. 4.
Important: If you export a JPL file for method calls in a session recorded from clustered servers, the JPL file that you create will not show the name of the server from which you collected this data. Instead, the name of the server will appear as _OtherServer.
5.
Select Export JProbe Launcher File from the Browser menu or from the contextual menu obtained by right-clicking one of the method nodes you selected. From the submenu that appears, choose either Profile Selected Package(s)... or Profile Selected Class(es).... The Export JProbe Launcher File dialog will open (see Figure 145). The options in this dialog are specific to JProbe. See its manual for details.
Figure 145
6.
7.
Figure 145
The JProbe Launcher options dialog
Click Continue to open a Save dialog from which you can choose a name for the launcher file and then click Save to create it. The .jpl file extension is automatically appended. To close the Export JProbe Launcher File dialog, click Cancel; to launch contextsensitive help, click Help. Now that you have a JProbe launcher file, you can use it to run JProbe Profiler. See JProbe Integration on page 127 for a discussion of the information contained in a JPL file and how you can use the file to profile the packages and classes in your application.
Request Tree Browser FAQ

What do the tree nodes represent? A node represents an entry into an instrumented object. It can be an HTTP request, an RMI call, a JDBC call, or a method entry. Whats in a JDBC node? PerformaSure breaks down JDBC calls into the underlying operations that the application must complete with the database in order to service a request. This includes both the time spent and number of calls required to
Set up the connection, Prepare and pass parameters to a SQL statement, Execute the statement, Manipulate the returned ResultSet Commit or roll back the changes to the database.
JDBC nodes are tracked as separate entities. They have a cylindrical shape to distinguish them from the other group nodes. Why do I see a JDBC node as an isolated (root) request? It is likely that nodes of this type are associated with a JMS call. Figure 146 shows a request that makes a JMS call (the node at the top right). Since the JMS specification demands that messages must not be lost, the application server persists them in some way. In this case, the application server has saved the message to a database.
Figure 14 6
Figure 146 A JDBC node as an isolated root request
The database activity is not the direct result of a method call in the call path of the request. Instead, it is a result of an internal configuration of the application server and the way it handles JMS persistence, so it is not tracked as part of the Tag and Follow mechanism for the request. Internal application server methods are not tracked, but JDBC calls are, so it shows up as an isolated node. Can I exclude classes from being instrumented by PerformaSure? See Including and Excluding Classes on page 65 for information on how to modify PerformaSure defaults in order to include or exclude specific classes.
Chapter 14
Metrics Browser

Metrics Browser Metric Types Menus and ToolbarSummary Menus and ToolbarFull Detail Time Control Panel Metrics Browser Navigation Pane Metrics Browser Graph PaneSummary Metrics Browser Graph PaneSummary Metrics Browser FAQ
Metrics Browser
The Metrics browser allows you to visually correlate multiple metrics displayed in the same chart, to examine charts to see if certain metrics exceed the minimum or maximum thresholds you have set for them, to observe the duration of threshold violations, and to check for any anomalous behavior. This browser also provides access to the Threshold Editor, the dialog in which you set metric thresholds. See Threshold Editor on page 392 for more information about setting thresholds. If you have set a threshold for a metric and the metric exceeds that threshold during the interval spanned by the Zonar, the chart shows a diagonally striped, rectangular strip at the right-hand edge of the chart. This strip indicates the range on the y-axis in which the metric exceeds its normal bounds; a threshold line is drawn across the chart to indicate the threshold boundary.
335
The Metrics Browser contains a Time Control panel, the full list of available metrics organized in a collapsible tree hierarchy (the navigator pane), and a graph pane in which you can open a variable number of metric charts.
Figure 147
Figure 147 The Metrics browser
Metric Types
PerformaSure divides metrics into two broad categories: raw and derived. Raw metrics are those that are reported from the operating system, web server, and application servers. They may be further divided into periodic metrics, network metrics, and service request metrics. Some of these may not be directly useful. For example, there are a number of never-decreasing metrics that are reported. Knowing the value of such a metric is not useful in itself, but knowing the time rate of increase of the metric is useful, and a sharp spike in the rate may indicate an area for further investigation. Derived metrics are calculated by PerformaSure from one or more raw metrics, and possibly from other derived metrics.
Raw Metrics
Periodic metrics are collected by PerformaSure by polling the system under test. Operating system, web server, and application server metrics are collected at set
intervals. Other approaches are used for collecting network metrics and service request metrics.
Derived Metrics
Derived metrics are calculated by PerformaSure, usually from raw metrics. Multiple derived metrics can be displayed on the same chart. Naturally, the metrics should be comparable for such a chart to be useful.

Menu Bar
The Metrics browsers menu bar is located along the top of the browser window. The following tables describe the controls available from the different menus in the menu bar. Metrics Browser Menu BarBrowser Menu
Control
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Opens the New Browser dialog. Use this dialog to choose the type of browser you want to launch. Adds the browser to your PerformaSure Project. A Metrics browser icon will appear in the Browsers area of the Project window. Begins the process of generating a print version of the browser suitable for inclusion in a report. Launches the Browser Properties dialog. See Properties on page 340 for details. Closes the browser. Closes all open Projects and browsers and shuts down the Workstation.
Metrics Browser Menu BarView Menu

Control
Close All Charts
Type
Menu item
Default Value
N/A
Description
Closes all metric charts in the graph pane.
Metrics Browser 337
Metrics Browser Menu BarTools Menu

Control
Type
Default Value
Description
SQL Tuning Options
Menu item Menu item
N/A Enabled
Metrics Browser Menu BarWindows Menu

Control
Type
Default Value
Description
Metrics Browser Menu BarHelp Menu

Control
Help About
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Toolbar
Under the Metrics browsers menu bar is a toolbar with controls for opening new PerformaSure browsers, launching Spotlight and Quest database tools, and performing other actions like exporting a report. The following table describes the controls available from the toolbar. Metrics Browser Toolbar
Control
New Browser
Type
Default Value
Enabled
Description
Clicking on the left-hand side of this button launches the New Browser dialog. See New Browser on page 163 for details. Clicking on the right-hand displays a dropdown menu from which you can choose the type of new browser that you want to open. See New Browser on page 343 for details. Adds the browser to the Project. This button is disabled if you have already added the browser to the Project. Begins the process of generating a print version of the browser suitable for inclusion in a report. Launches the Browser Properties dialog. See Properties on page 344 for details. Displays a drop-down menu with four choices. See Performance Diagnostics on page 344 for more information. Displays a drop-down menu with two choices. See SQL Tuning on page 344 for more information. Toggles whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. See Link Browsers to Use Same Zone/Break Link Between Browsers on page 345 for more information.
N/A
Link Browsers To Use Same Zone/Break Link Between Browsers
Enabled
Metrics Browser 339

New Browser Choose New Browser... to launch the New Browser dialog, which allows you to select and open a new browser of a specific type. The new browser is not automatically added to the Project or listed in the Project window. Keyboard accelerator: Ctrl-B. Add New Browser To Project The Add New Browser To Project menu item is enabled if you have not yet added this browser to the Project. Click this item to add the browser to the Project. A new Metrics browser icon will appear in the Browsers area of the Project Window. Keyboard accelerator: Ctrl-A. Export Report Select Export Report... to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Keyboard accelerator: Ctrl-R. Properties Choose Properties... to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Close Select the Close menu item to close the browser but leave the Project open. Keyboard accelerator: Ctrl-W. Exit PerformaSure Choose Exit PerformaSure to close all open Projects and browsers and shut down the Workstation. When you select this menu item, you may be prompted to
Menu BarView
Close All Charts Click Close All Charts to close all metric charts that are currently displayed in the graph pane.
Menu BarTools
Note:
Metrics Browser 341
Menu BarWindows
Menu BarHelp
Toolbar
The Metrics browsers toolbar is located directly below the menu bar.
Figure 148
Figure 148 The toolbar in the Metrics browser
Figure 149
New Request Time Browser Select New Request Time Browser to launch a new Request Time browser. New SQL Browser Select New SQL Browser to launch a new SQL browser. New Request Tree Browser Select New Request Tree Browser to launch a new Request Tree browser. New Metrics Browser Select New Metrics Browser to launch a new Metrics browser. New Network Traffic Browser Select New Network Traffic Browser to launch a new Network Traffic browser.
Metrics Browser 343
New Thresholds Browser Select New Thresholds Browser to launch a new Thresholds browser. Add New Browser to Project The Add New Browser to Project button is enabled if you have not yet added this browser to the Project. Click this button to add the browser to the Project. A new Metrics browser icon will appear in the Browsers area of the Project window. Export Report Click the Export Report button to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Properties Click the Properties button to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Performance Diagnostics The Performance Diagnostics button displays a drop-down menu from which you have four choices: Spotlight on Oracle, Spotlight on DB2, Spotlight on WebSphere, and Spotlight on WebLogic. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select Spotlight on WebSphere or Spotlight on WebLogic Server, Spotlight is launched to check the entire application server. When you select Spotlight on Oracle or Spotlight on DB2, Spotlight is launched to check database problems more closely. SQL Tuning The SQL Tuning button displays a drop-down menu from which you have two choices: SQLab Vision for Oracle, and SQL Tuning for DB2. Each choice is enabled if the corresponding cartridge is installed.
Link Browsers to Use Same Zone/Break Link Between Browsers Every PerformaSure browser contains a button that allows you to toggle whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. Click the Link Browsers to Use Same Zone button to link the browsers Time Control panels. When linked, the Zonar and (where applicable) the Sightline in each browser are in the same state as the browser in which the button was clicked. Using the Zonar or (where applicable) the Sightline in one browser will impact all other browsers as well. If a problem occurs during a specific interval spanned by the Zonar, linking the browsers can help you track this problem across different browsers. Click the Break Link Between Browsers button to return the browsers Time Control panels to an unlinked state. This allows each browsers Zonar and Sightline to function independently.
Time Control Panel

The Time Control panel is located directly below the Metrics browsers toolbar. This panel has the same controls in all PerformaSure browsers. See Time Control Panel on page 219 for a detailed description of its controls.
Metrics Browser Navigation Pane

The navigation pane contains a list of metrics organized in a tree hierarchy. All the metrics available for the session that you are currently analyzing are listed in this pane. The metrics available in a session will vary depending on several factors, such as the application server(s) that you are instrumenting. See The Metric Hierarchy on page 446 for a description of the structure of the metric hierarchy that is displayed in the navigation pane.
Metrics Browser 345
Exploring the Tree Hierarchy

Double-click a node in the tree or click the square ( ) to the left of the node to expose the next level in the hierarchy. Tip: You can navigate the metric hierarchy using your keyboard. To select or deselect entries in the tree, press the spacebar. To expand or close folders, use the right and left arrow keys. To move from node to node, use the up and down arrow keys.
Selecting Metrics For Display

There are several ways that you can select metrics from the tree hierarchy for presentation in the graph pane.
To open a metric chart:
Select a metric in the tree and press Enter or double-click a metric. You can also click and drag a metric from the navigation pane to a blank space in the graph pane or to the edge of a chart in the graph pane. Performing any one of these actions causes the metric to be displayed in its own chart.
To add a metric to an existing chart:
Click on the metric in the tree hierarchy and drag it to a chart in the graph pane.
Tip: Charting a metric in the same chart as another makes it easier to compare the trend of several metrics.
To open a chart with multiple metrics:

Ctrl-click or Shift-click the metrics in the navigation pane and press Enter Ctrl-click or Shift-click the metrics in the navigation pane and right-click on the selected metrics to cause a contextual menu to appear. This menu contains three options: Open, Open in Overlap Mode, Open in Stacked Mode. When you select Open, the metrics are charted together in Default mode. See Changing the Chart Type on page 350 for more information about chart types.
To reposition a metric chart within the graph pane:
Click the top portion of the chart and drag it to another spot in the graph pane.
To remove a metric chart from the graph pane:
Click the Close Chart button or right-click below the top portion of the chart and select Close Chart from the contextual menu that appears.
Metrics Browser Graph PaneSummary

The following tables describe the controls and the contextual (right-click) menus available in each chart in the graph pane. Metrics Browser Graph Pane
Control
Chart header
Type
Drop-down menu
Default Value
Enabled
Description
Displays the name of the metric (in a single-metric chart) or the active metric (in a multiple-metric chart). Click it to display a menu from which you can select a different metric (in a multiplemetric chart). Displays a menu from which you can select the function applied to one or more metrics in the chart. Displays a menu from which you can select the plot type applied to the metric (in a single-metric chart) or to the active metric (in a multiple-metric chart). Maximizes the chart. Restores a maximized chart to its former size. This button is only available when you have maximized a chart. Closes the chart. Changes the position of the Sightline in all charts in the graph pane. Clicking an Indicator changes the active metric (in a multiplemetric chart). See Using the Legend on page 350 for more information. Displays a menu from which you can select the chart type. Opens the Threshold Editor for the metric (in a single-metric chart) or for the active metric (in a multiple-metric chart).
Function Set chooser Plot Type chooser Maximize Chart Restore Chart Close Chart Sightline slider Legend entries
Drop-down menu Drop-down menu
Enabled Enabled
Button Button Button Slider Metric Indicators
Enabled Enabled Enabled Enabled Enabled
Chart Type chooser Edit Thresholds
Drop-down menu Button
Enabled Enabled
Metrics Browser 347
Metrics Browser Graph PaneContextual Menus

Control
Function for Selected Metric Apply [Plot Type] Plot Type To All Delete Maximize Chart Restore Close Chart Close All Charts
Type
Drop-down menu Menu item Menu item Menu item Menu item Menu item Menu item
Description
Displays a menu from which you can select the function applied to the metric on which you right-clicked. Applies the plot type applied to the active metric to all items in the chart. Removes the active metric from the chart (in a multiple-metric chart) or clears the chart (in a single-metric chart). Maximizes the chart. This option is only available when the chart has not been maximized. Restores a maximized chart to its former size. This option is only available when you have maximized the chart. Closes the chart. Closes all charts in the graph pane.
Metrics Browser Graph PaneFull Detail

The Metrics browsers graph pane includes several elements.
Figure 150
Figure 150 Elements in the Metrics browsers graph pane

You can open a collection of charts in the Metrics browsers graph pane. Each chart that you open illustrates the history of one or more metrics during the interval spanned by the Zonar. The metrics that are available for display in the graph pane are listed in the tree hierarchy in the navigation pane. See Selecting Metrics For Display on page 346 for details about how to select metrics from the tree hierarchy for display in the graph pane. Tip: Hold down the Shift key and drag the mouse between two points in a chart to cause the Zonar to zoom in to a smaller portion of the Timeline. When you perform this action, the metric data displayed in all charts in the graph pane will be for the new interval spanned by the Zonar.
Metrics Browser 349
Using the Metric Drop-Down Menu The header for each chart in the graph pane displays the name of the metric that is currently selected in that chart. Tip: Hover the cursor over the chart header to make a tooltip appear that displays the full name of the active metric.
Using the Legend As shown in Figure 150, the legend in each chart contains a group of Metric Indicators. Click a Metric Indicator to select a new active metric. A dark square appears around the Metric Indicator that corresponds to the active metric in that chart. Changing the Chart Type The header for the Chart Type chooser displays the chart type that is currently selected. Click this header to display a drop-down menu from which you can select a new chart type. The options available in this menu are described below. Default When you select the Default chart, all metrics in the chart are charted using a single y-axis. Tip: Select the Default chart if you want to compare multiple metrics with similar ranges in the same chart.
Overlap When you select the Overlap chart, a separate y-axis is used to graph each metric in the chart; a Metric Indicator appears next to the Chart Type chooser to indicate to which metric the current y-axis applies. Select a metric in the chart or click its corresponding Indicator in the legend to cause the range of values for that metric to be shown on the y-axis. Tip: Select the Overlap chart when you want to compare the trend of two multiple metrics with very different ranges in the same chart.
Example: Three metrics are charted in the same chart in the graph pane. For the interval spanned by the Zonar, Metric A has a range of 0 to 0.2 milliseconds, Metric B has a range of 5 to 45 milliseconds, and Metric C has a range of 145 to 815 milliseconds. Because of the disparity among their ranges, displaying all three metrics in a Default chart causes Metric A and Metric B to be shown as a nearly flat lines near 0. If you use an Overlap chart instead, Metric A can be charted with a y-axis range of approximately 0 to 250 microseconds, Metric B can be charted with a y-axis range of approximately 0 to 45 milliseconds, and Metric C can be charted with a y-axis range of approximately 100 to 900 milliseconds. The scale shown on the y-axis will thus correspond more closely to the values for each metric. As a result, Metric A and Metric B can be charted a way that provides you with a better visual indication of each metrics trend. Stacked When you select the Stacked chart, the metrics in the chart are displayed as additive metrics and are charted using a single y-axis. In this type of chart, the broken line that extends horizontally from the y-axis and intersects the Sightline is aligned with the top (the sum) of the stacked metrics. Tip: Select the Stacked chart when you want to compare the total of multiple metrics and to compare the relative breakdown of this total on a permetric basis.
Changing the Function Set Click the Function Set chooser icon to display a drop-down menu from which you can select the function applied to one or more metrics in the chart. The options listed in this menu are the functions that exist for the active metric. When you select a new function using the Function Set chooser, however, this function will be applied to all metrics in the chart whose function sets include this function. The functions available for a given metric can vary depending on the underlying application server or operating system. Tip: Hover the cursor over the Function Set chooser icon to make a tooltip appear that displays the function currently applied to the active metric.
Metrics Browser 351
Note:
To change the function applied to a single metric in the chart, right-click the metric to cause a contextual menu to appear. You can then select a new function from the Function submenu.
Changing the Plot Type Click the Plot Type chooser icon to display a drop-down menu from which you can select the plot type. When Default or Overlap is selected from the Chart Type chooser, the options available in this menu are Line, Bar, and Area and the option that you select is applied to the active metric in the chart. When Stacked is selected from the Chart Type chooser, the options available in this menu are Stacked Bar and Stacked Area and the option that you select is applied to the entire chart. Tip: Hover the cursor over the Plot Type chooser icon to make a tooltip appear that displays the plot type that is currently applied either to the active metric or to the entire chart.
Using the Sightline and the Sightline Slider Each chart in the Metrics browser contains its own Sightline and Sightline slider. All Sightlines and Sightline sliders in the same Metrics browser are linked: when you adjust the position of the Sightline in one chart, the Sightlines in the other charts move as well. See Sightline on page 222 for more information about the Sightline. In addition to using the slider, you can move the Sightline to any point in a chart by double-clicking that point.
Note:
The Sightline snaps to time slice boundaries. If the point on which you double-clicked does not correspond to a time slice boundary, the Sightline will be repositioned to the point that corresponds to the closest boundary. See Time Slice Size on page 181 and Timeline on page 220 for more information about time slices and time slice boundaries.
Edit Thresholds Button Click the Edit Thresholds... button to launch the Threshold Editor for the charted metric (in a single-metric chart) or for the active metric (in a multiplemetric chart). See Threshold Editor on page 392 for details about the Threshold Editor. See Thresholds Browser FAQ on page 395 for information about the availability of the Edit Thresholds button.
Repositioning a Chart Click the top portion of the chart and drag it to another spot in the graph pane. Maximizing a Chart Click the Maximize Chart button Restoring a Chart Click the Restore Chart button size. Closing a Chart Click the Close Chart button to close a chart in the graph pane. to restore a maximized chart to its former to maximize a chart in the graph pane.

Indicator Tooltips Hover the cursor over a Metric Indicator to cause a tooltip to appear in which the name of the corresponding metric and the function applied to that metric are displayed.
Figure 151
Figure 152
Metrics Browser 353

You can right-click anywhere in a chart in the graph pane to make a contextual menu appear. Function for Selected Metric Select this menu item to cause a submenu to appear from which you can select the function applied to the metric on which you right-clicked. Apply [Plot Type] Plot Type To All Select this menu item to apply the plot type that is applied to the active metric to all metrics in the chart. See Changing the Plot Type on page 352 for more information about the options available from the Plot Type Chooser. Delete Select Delete to remove the active metric from the chart on which you rightclicked. If there is only one metric displayed in the chart, selecting this option clears the chart but does not cause it to be removed from the graph pane. Keyboard accelerator: Delete.
Note:
Removing a metric from a chart in the graph pane does not cause the entry for that metric to be deleted from the navigator panes tree hierarchy.
Maximize Chart Select this menu item to maximize the chart on which you right-clicked in the graph pane. Restore This menu item becomes available when you maximize a chart. Select it to restore the chart to its former size and make the other charts in the graph pane visible again. Close Chart Select this menu item to close the chart on which you right-clicked. Close All Charts Select this menu item to close all charts in the graph pane.
Metrics Browser FAQ

How can I tell which metrics listed in the hierarchy have been charted in the graph pane? When you chart a metric in the graph pane, the icon for the metric displayed in the hierarchy ( ) changes to this icon: .
Metrics Browser 355
Chapter 15
Network Traffic Browser


Network Traffic Browser Menus and ToolbarSummary Menus and ToolbarFull Detail Time Control Panel Filter Machines Dialog Network Traffic Browser Graph PaneSummary Network Traffic Browser Graph PaneFull Detail Network Interaction Chart Zoom Control Slider Tooltips in the Graph Pane Network Traffic Browser Detail Pane Detail Pane Columns Contextual Menus in the Detail Pane Network Traffic Browser FAQ

The Network Traffic browser (Figure 153) presents a two-dimensional or threedimensional view of traffic from one network interface to another. The data is arranged in a grid of x, y pairs in the graph panes network interaction chart. The senders are listed along the y-axis and the machines to which they transfer data
357
over the network are listed along the x-axis, making the sources of outgoing traffic distinguishable from the destination interfaces. Important: The Network Traffic browser only graphs sent traffic, not received traffic.
Figure 15 3
Figure 153 Network Traffic browser

Menu Bar
The Network Traffic browsers menu bar is located along the top of the browser window. The following tables describe the controls available from the different menus in the menu bar. Network Traffic Browser Menu BarBrowser Menu
Control
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Opens the New Browser dialog. Use this dialog to choose the type of browser you want to launch. Adds the browser to your PerformaSure Project. A Network Traffic browser icon will appear in the Browsers area of the Project window. Begins the process of generating a print version of the browser suitable for inclusion in a report. Launches the Browser Properties dialog. See Properties on page 362 for details. Closes the browser. Closes all open Projects and browsers and shuts down the Workstation.
Network Traffic Browser Menu BarView Menu

Control
Display As 3D Chart Auto-Fit All Columns Show/Hide Columns
Type
Menu item with checkbox Menu item Menu item
Default Value
Description
Switches the view in the graph pane to a three-dimensional rendering of the volume of network traffic. Resizes the width of all columns in the table so that all values within each column are visible. Opens a dialog containing a checkbox. Select or deselect this checkbox to toggle the display of the metric Data Volume in the detail pane. Launches the Filter Machines dialog. See Filter Machines Dialog on page 368 for more information.
Filter Machines
Menu item
Selected
Network Traffic Browser 359
Network Traffic Browser Menu BarTools Menu

Control
Type
Default Value
Description
SQL Tuning Options
Menu item Menu item
N/A Enabled
Network Traffic Browser Menu BarWindows Menu

Control
Type
Default Value
Description
Network Traffic Browser Menu BarHelp Menu

Control
Help About
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Toolbar
Under the Network Traffic browsers menu bar is a toolbar with controls for opening new PerformaSure browsers, launching Spotlight and Quest database tools, controling the view in the Network Traffic browsers graph and detail panes, and performing other actions like exporting a report. The following table describes the controls available from the toolbar. Network Traffic Browser Toolbar
Control
New Browser
Type
Default Value
Enabled
Description
Clicking on the left-hand side of this button launches the New Browser dialog. See New Browser on page 163 for details. Clicking on the right-hand displays a dropdown menu from which you can choose the type of new browser that you want to open. See New Browser on page 365 for details. Adds the browser to the Project. This button is disabled if you have already added the browser to the Project. Begins the process of generating a print version of the browser suitable for inclusion in a report. Launches the Browser Properties dialog. See Properties on page 366 for details. Displays a drop-down menu with four choices. See Performance Diagnostics on page 366 for more information. Displays a drop-down menu with two choices. See SQL Tuning on page 367 for more information. Toggles whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. See Link Browsers to Use Same Zone/Break Link Between Browsers on page 367 for more information. Toggles the display of the detail pane. Launches the Filter Machines dialog. See Filter Machines Dialog on page 368 for more information.
N/A
Link Browsers To Use Same Zone/Break Link Between Browsers Show Detail/Hide Detail Filter
Enabled
Button Button
Enabled Enabled

New Browser Choose New Browser... to launch the New Browser dialog, which allows you to select and open a new browser of a specific type. The new browser is not automatically added to the Project or listed in the Project window. Keyboard accelerator: Ctrl-B. Add New Browser To Project The Add New Browser To Project menu item is enabled if you have not yet added this browser to the Project. Click this item to add the browser to the Project. A new Network Traffic browser icon will appear in the Browsers area of the Project window. Keyboard accelerator: Ctrl-A. Export Report Select Export Report... to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Keyboard accelerator: Ctrl-R. Properties Choose Properties... to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Close Select the Close menu item to close the browser but leave the Project open. Keyboard accelerator: Ctrl-W. Exit PerformaSure Choose Exit PerformaSure to close all open Projects and browsers and shut down the Workstation. When you select this menu item, you may be prompted to
Menu BarView
Display as 3D Chart Click Display as 3D Chart to switch the view in the graph pane to a threedimensional rendering of the volume of network traffic. In this view, the height of each column is proportional to the amount of data transferred from one machine to another per second. Auto-Fit All Columns Click Auto-Fit All Columns to resize the width of all columns in the table so that all values within each column are visible. Show/Hide Columns You can choose whether or not to display the metric Data Volume in the detail pane. Select Show/Hide Columns... to open a dialog that contains an entry for this metric and a checkbox. The checkbox controls the display of this metric in a column in the detail pane.
Menu BarTools
Recording Control Window Select Recording Control Window... to launch the Recording Control window. See Recording Control Window on page 179 for more information about using the controls in this window. Session Management Select Session Management... to open the Session Management dialog. See Session Management Dialog on page 151 for more information about using this dialog. Thresholds Select Thresholds... to launch the Threshold Editor. See Threshold Editor on page 392 for more information.
Change Password Select Change Password... to open the Change Password dialog. See Change Password Dialog on page 151 for more information about using this dialog. User Administration Select User Administration... to launch the User Management dialog. See User Management on page 149 for details about using this dialog.
Note:
Menu BarWindows
The Windows menus one static choice is Bring All To Front, which ensures that all open PerformaSure windows have a higher stacking order than nonPerformaSure windows. The other items in the Windows menu allow you to switch from one open Project window or browser to another. In addition to Bring All To Front, the Windows menu will always contain at least two items: one for the Project window and one for this browser.
Menu BarHelp
Toolbar
The Network Traffic browsers toolbar is located directly below the menu bar.
Figure 154
Figure 154 The toolbar in the Network Traffic browser
Figure 155
New Request Time Browser Select New Request Time Browser to launch a new Request Time browser. New SQL Browser Select New SQL Browser to launch a new SQL browser.
New Request Tree Browser Select New Request Tree Browser to launch a new Request Tree browser. New Metrics Browser Select New Metrics Browser to launch a new Metrics browser. New Network Traffic Browser Select New Network Traffic Browser to launch a new Network Traffic browser. New Thresholds Browser Select New Thresholds Browser to launch a new Thresholds browser. Add New Browser to Project The Add New Browser to Project button is enabled if you have not yet added this browser to the Project. Click this button to add the browser to the Project. A new Network Traffic browser icon will appear in the Browsers area of the Project window. Export Report Click the Export Report button to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Properties Click the Properties button to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Performance Diagnostics The Performance Diagnostics button displays a drop-down menu from which you have four choices: Spotlight on Oracle, Spotlight on DB2, Spotlight on WebSphere, and Spotlight on WebLogic. Each choice is
enabled if the corresponding Spotlight cartridge is installed. When you select Spotlight on WebSphere or Spotlight on WebLogic Server, Spotlight is launched to check the entire application server. When you select Spotlight on Oracle or Spotlight on DB2, Spotlight is launched to check database problems more closely. SQL Tuning The SQL Tuning button displays a drop-down menu from which you have two choices: SQLab Vision for Oracle, and SQL Tuning for DB2. Each choice is enabled if the corresponding cartridge is installed. Link Browsers to Use Same Zone/Break Link Between Browsers Every PerformaSure browser contains a button that allows you to toggle whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. Click the Link Browsers to Use Same Zone button to link the browsers Time Control panels. When linked, the Zonar and (where applicable) the Sightline in each browser are in the same state as the browser in which the button was clicked. Using the Zonar or (where applicable) the Sightline in one browser will impact all other browsers as well. If a problem occurs during a specific interval spanned by the Zonar, linking the browsers can help you track this problem across different browsers. Click the Break Link Between Browsers button to return the browsers Time Control panels to an unlinked state. This allows each browsers Zonar and Sightline to function independently. Hide/Show Detail The Hide/Show Detail button browsers detail pane. Filter Click the Filter button to launch the Filter Machines dialog. See Filter Machines Dialog on page 368 for more information. toggles the display of the Request Tree
Time Control Panel

The Time Control panel is located directly below the Network Traffic browsers toolbar. This panel has the same controls in all PerformaSure browsers. See Time Control Panel on page 219 for a detailed description of its controls.
Filter Machines Dialog

The Filter Machines dialog appears when you click the Filter button in the toolbar or select View > Filter Machines... from the menu bar. The controls in this dialog allow you to customize which machines are shown in the Network Traffic browsers graph and detail panes.
Figure 15 6
Figure 156 The Filter Machines dialog for the Network Traffic browser
Controls in the Filter Machines Dialog

Always Include IP Addresses This area lists the IP addresses used by machines in the monitored system. Each entry includes the machine name and IP address. Select the checkboxes corresponding to the entries in the list for which you would like to display network traffic information in the graph and detail panes. All Click All to select all checkboxes in the Always Include IP Addresses list. None Click None to clear all checkboxes in the Always Include IP Addresses list.
Apply Click Apply to apply your changes; the information in the graph and detail panes will be updated immediately. The Filter Machines dialog will remain open, allowing you to make other changes.
Network Traffic Browser Graph PaneSummary

The following table describes the controls available in the graph pane. Network Traffic Browser Graph Pane
Control
Color Scale Toggle Zoom Control
Type
Button Slider
Default Value
Enabled 100%
Description
Toggles the display of the color scale on the left side of the graph pane. Moving the slider to the right causes the graph pane to zoom in to the network interaction chart; moving it to the left causes it to zoom out.
Network Traffic Browser Graph PaneFull Detail

The Network Traffic browsers graph pane includes several elements.
Figure 157
Figure 157 The graph pane in the Network Traffic browser
Network Interaction Chart

The network interaction chart displays a grid of machines for which traffic has been logged. The x-axis and y-axis labels are the machine names; network activity is shown in the grid on the x-y plane. If Display as 3D Chart is selected, the z axis measures the amount of data transferred per second (listed in the detail pane as the metric Data Volume). The volume of data sent from one machine to another is shown in 2D mode by coloring sections of the grid, and in 3D mode by displaying a colored columnar bar at each grid intersection. Each color represents a range within the metric Data Volume for the interval spanned by the Zonar. In the 3D chart, the height of each bar is proportional to the metric value charted at that grid intersection for the interval spanned by the Zonar. See Color Scale Toggle Button below for details about color coding in the chart. Tip: Rotate the 3D graph by holding down the Ctrl key while dragging on the graph.
Color Scale Toggle Button

Click the Color Scale Toggle button to display a five-color scale on the left side of the graph pane. You can compare the colors in this scale with the colors used in the network interaction chart. Each color represents a range within the metric Data Volume for the interval spanned by the Zonar. When the chart is visible, the tooltip for each color shows the metric range that it represents. See Edit Options Dialog on page 215 for information about customizing the colors used in the color scale. Color Coding in the Network Interaction Chart The hot color at the top of the color scale is used to mark the grid sections or columnar bars that represent the high-volume data transfers that occurred during the interval spanned by the Zonar. The cool color is used to mark low-volume data transfers. The other three colors are assigned proportionately to intermediate-volume data transfers.
Zoom Control Slider

A network interaction chart that illustrates traffic from many machines might not fit in the graph pane unless you reduce its scale. You can use the Zoom Control
slider to reduce the scale of the chart displayed in the graph pane. The scale of the 3D chart can be reduced by as much as 75% and the scale of the 2D chart can be reduced by as much as 90%.

Machine Name Label Tooltips Hover the cursor over a machine name label in the chart to cause a tooltip to appear that displays the corresponding IP address.
Figure 158
Figure 158 A machine name label tooltip in the graph pane
Grid Section/Columnar Bar Tooltips Hover the cursor over a section of the grid (in the 2D chart) or a columnar bar (in the 3D chart) to cause a tooltip to appear that shows the volume of data sent from one machine to another.
Figure 159
Figure 159 A grid section tooltip in the graph pane
Network Traffic Browser Detail Pane

The Network Traffic browsers detail pane provides an explorer view of the machines in your network. Click on the entry for a machine to expose a sub-tree for each IP address. You can use the detail pane to find out exactly how many bytes of data were sent per second from one machine to another. Tip: Selecting a row in the detail table and putting it in the operating systems copy buffer allows for further processing. (Select the row in Unix, or Ctrl-C in Windows.) After the row is copied, you can paste it into another application, such as a spreadsheet.
Figure 160
Figure 160 The detail pane in the Network Traffic browser
Detail Pane Columns

Figure 161
Figure 161 The column headers in the Network Traffic browsers detail pane
Name The Name column lists the names of the machines sending and receiving data over the network. Tip: Hover the cursor over an entry in the Name column to display the full name of the machine.
Data Volume This column lists the volume of data sent over the network from one machine to another. The metric Data Volume is displayed in units (bytes, kilobytes) per second.

You can right-click anywhere in the detail table to make a contextual menu appear. The items in this menu are described below.
Figure 162
Auto-Fit Column Click Auto-Fit Column to resize the width of that column so that all values within the column are visible. Auto-Fit All Columns Click Auto-Fit All Columns to resize the width of all columns in the table so that all values within each column are visible. Hide Column Click Hide Column if you do not want the column on which you right-clicked to be displayed in the table. This item is disabled when you right-click on the Name column. Show/Hide Columns... You can choose whether or not to display the metric Data Volume in the detail pane. Select Show/Hide Columns... to open a dialog that contains an entry for this metric and a checkbox. The checkbox controls the display of this metric in a column in the detail pane.
Network Traffic Browser FAQ

Can I configure the browser not to display data for certain machines? Use the Filter Machines dialog to select which machines are shown in the Network Traffic browsers graph and detail panes. Click the Filter button in the toolbar or select View > Filter Machines... from the menu bar to launch the Filter Machines dialog. See Filter Machines Dialog on page 368 for more information.
Chapter 16
Thresholds Browser

Thresholds Browser Menus and ToolbarSummary Menus and ToolbarFull Detail Time Control Panel Thresholds Browser Graph PaneSummary Thresholds Browser Graph PaneFull Detail Charts in the Graph Pane Tooltips in the Graph Pane Thresholds Browser Detail Pane Detail Pane Columns Bar Charts in the Detail Pane Contextual Menus in the Detail Pane Threshold Editor Thresholds Browser FAQ
Thresholds Browser
The Thresholds browser contains information about metrics with threshold violations, such as operating system metrics, application metrics, server metrics, SQL statement metrics, and service request metrics. This last category includes response times, the percentage of sampled requests and incomplete requests, exceptional exit counts, and JDBC times aggregated across all tiers. As shown in Figure 163, the display name used as the header for the graph pane identifies the metric that is selected in the detail pane.
375
Figure 163
Figure 163 The Thresholds browser
The Thresholds browser contains a Time Control panel, a menu bar, a toolbar, a detail pane in which the metrics that have exceeded their thresholds are listed, and a graph pane in which metrics with threshold violations can be charted. Clicking on any row in the detail pane causes the chart for that metric to appear in the graph pane and its name to be displayed in the header at the top of the graph pane. The diagonally striped, rectangular strip on the right-hand side of the chart indicates the range on the y-axis in which the metric exceeded its bounds. A threshold boundary is represented by a threshold line drawn across the chart.
Note:
You can select metrics sequentially by pressing the Tab key, or Shift-Tab to move in the opposite direction.
The Thresholds browser can help you identify problem areas that should be investigated further. Once you have pinpointed intervals in the session during which metric thresholds were exceeded, you can continue your investigation in other PerformaSure browsers to determine the cause of these threshold violations.

Menu Bar
The Thresholds browsers menu bar is located along the top of the browser window. The following tables describe the controls available from the different menus in the menu bar. Thresholds Browser Menu BarBrowser Menu
Control
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Opens the New Browser dialog. Use this dialog to choose the type of browser you want to launch. Adds the browser to your PerformaSure Project. A Thresholds browser icon will appear in the Browsers area of the Project window. Begins the process of generating a print version of the browser suitable for inclusion in a report. Launches the Browser Properties dialog. See Properties on page 380 for details. Closes the browser. Closes all open Projects and browsers and shuts down the Workstation.
Thresholds Browser Menu BarView Menu

Control
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Resizes the width of all columns in the table so that all values within each column are visible. Opens a dialog containing a group of checkboxes. Select or deselect these checkboxes to toggle the display of certain metric properties in the detail pane. Opens a dialog containing a group of checkboxes. Select or deselect these checkboxes to toggle the display of certain bar charts in the detail pane columns. Toggles the display of the Filter Bar at the bottom of the graph pane. See Show Filter Bar on page 381 for more information about using the controls in the Filter Bar.
Menu item
Enabled
Selected
Thresholds Browser 377
Thresholds Browser Menu BarTools Menu

Control
Type
Default Value
Description
SQL Tuning Options
Menu item Menu item
N/A Enabled
Thresholds Browser Menu BarWindows Menu

Control
Type
Default Value
Description
Thresholds Browser Menu BarHelp Menu

Control
Help About
Type
Menu item Menu item
Default Value
Enabled Enabled
Description
Toolbar
Under the Thresholds browsers menu bar is a toolbar with controls for opening new PerformaSure browsers, launching Spotlight and Quest database tools, controling the view in the Thresholds browsers graph and detail panes, and performing other actions like exporting a report. The following table describes the controls available from the toolbar. Thresholds Browser Toolbar
Control
New Browser
Type
Default Value
Enabled
Description
Clicking on the left-hand side of this button launches the New Browser dialog. Clicking on the right-hand displays a drop-down menu from which you can choose the type of new browser that you want to open. See New Browser on page 384 for details. Adds the browser to the Project. This button is disabled if you have already added the browser to the Project. Begins the process of generating a print version of the browser suitable for inclusion in a report. Launches the Browser Properties dialog. See Properties on page 385 for details. Displays a drop-down menu with four choices. See Performance Diagnostics on page 385 for more information. Displays a drop-down menu with two choices. See SQL Tuning on page 385 for more information. Toggles whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. See Link Browsers to Use Same Zone/Break Link Between Browsers on page 386 for more information. Toggles the display of the detail pane.
N/A
Enabled
Button
Enabled

New Browser Choose New Browser... to launch the New Browser dialog, which allows you to select and open a new browser of a specific type. The new browser is not automatically added to the Project or listed in the Project window. Keyboard accelerator: Ctrl-B. Add New Browser To Project The Add New Browser To Project menu item is enabled if you have not yet added this browser to the Project. Click this item to add the browser to the Project. A new Thresholds browser icon will appear in the Browsers area of the Project Window. Keyboard accelerator: Ctrl-A. Export Report Select Export Report... to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Keyboard accelerator: Ctrl-R. Properties Choose Properties... to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Close Select the Close menu item to close the browser but leave the Project open. Keyboard accelerator: Ctrl-W. Exit PerformaSure Choose Exit PerformaSure to close all open Projects and browsers and shut down the Workstation. When you select this menu item, you may be prompted to
Menu BarView
Auto-Fit All Columns Click Auto-Fit All Columns to resize the width of all columns in the table so that all values within each column are visible. Show/Hide Columns You can choose whether or not to display certain metric properties in the detail pane. Select Show/Hide Columns... to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated metric property in a column in the detail pane. Show/Hide Bar Charts You can choose whether or not to display certain bar charts in the detail pane columns. Select Show/Hide Bar Charts to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated bar chart. Show Filter Bar Select or deselect the checkbox associated with the menu item Show Filter Bar to toggle the display of the Filter Requests bar at the bottom of the graph pane. You can enter a literal string or a regular expression in the Filter Requests bars Filter Requests text field. When you click the Apply button, the string or expression that you entered is matched against the metric names listed in the detail pane; only the metrics that match are displayed in the graph pane and in the detail pane. By default, the Filter Requests text field contains an empty literal string so that all metrics are selected. Tip: If you enter a regular expression in the Filter Requests text field, ensure that the Use Regular Expression checkbox is selected before you click Apply.
Menu BarTools
Note:
Menu BarWindows
Menu BarHelp
Toolbar
The Thresholds browsers toolbar is located directly below the menu bar.
Figure 164
Figure 164 The toolbar in the Thresholds browser
New Browser The New Browser... button has two parts. Click on the left-hand side of this button to launch the New Browser dialog, from which you can select the type of browser that you want and assign it a name. Click on the right-hand side of the New Browser... button to display a drop-down menu from which you can choose the type of browser that you want. The options in the New Browser... drop-down menu (Figure 165) are listed below.
Figure 165
Add New Browser to Project The Add New Browser to Project button is enabled if you have not yet added this browser to the Project. Click this button to add the browser to the Project. A new Thresholds browser icon will appear in the Browsers area of the Project window. Export Report Click the Export Report button to begin the process of generating a print version of the browser suitable for inclusion in a report. When you select this option, a Save file chooser is launched so that you can supply a file name for the report. See PerformaSure Reports on page 397 for a discussion of the reports that PerformaSure can provide. Properties Click the Properties button to launch the Browser Properties dialog. This dialog allows you to rename the browser, provide a description of the problems that you have found by using this browser and its settings, and select whether you would like this browser to open automatically when you open the Project. Performance Diagnostics The Performance Diagnostics button displays a drop-down menu from which you have four choices: Spotlight on Oracle, Spotlight on DB2, Spotlight on WebSphere, and Spotlight on WebLogic. Each choice is enabled if the corresponding Spotlight cartridge is installed. When you select Spotlight on WebSphere or Spotlight on WebLogic Server, Spotlight is launched to check the entire application server. When you select Spotlight on Oracle or Spotlight on DB2, Spotlight is launched to check database problems more closely. SQL Tuning The SQL Tuning button displays a drop-down menu from which you have two choices: SQLab Vision for Oracle, and SQL Tuning for DB2. Each choice is enabled if the corresponding cartridge is installed.
Link Browsers to Use Same Zone/Break Link Between Browsers Every PerformaSure browser contains a button that allows you to toggle whether or not the Time Control panels of all existing and newly created browsers are linked. Clicking this button affects the browsers in the current Project only. Click the Link Browsers to Use Same Zone button to link the browsers Time Control panels. When linked, the Zonar and (where applicable) the Sightline in each browser are in the same state as the browser in which the button was clicked. Using the Zonar or (where applicable) the Sightline in one browser will impact all other browsers as well. If a problem occurs during a specific interval spanned by the Zonar, linking the browsers can help you track this problem across different browsers. Click the Break Link Between Browsers button to return the browsers Time Control panels to an unlinked state. This allows each browsers Zonar and Sightline to function independently.
Time Control Panel

The Time Control panel is located directly below the Thresholds browsers toolbar. This panel has the same controls in all PerformaSure browsers. See Time Control Panel on page 219 for a detailed description of its controls.
Thresholds Browser Graph PaneSummary

The following table describes the controls available in the graph pane. Thresholds Browser Graph Pane
Control
Chart header Function Set chooser Plot Type chooser Sightline slider
Type
Drop-down menu Drop-down menu Drop-down menu Slider
Default Value
Description
Displays the name of the active metric. Displays a menu from which you can select the function applied to the metric charted in the graph pane. Displays a menu from which you can select the plot type applied to the active metric. Changes the position of the Sightline.
Thresholds Browser Graph Pane

Control
Chart Type chooser Edit Thresholds
Type
Drop-down menu Button
Default Value
Enabled Enabled
Description
Displays a menu from which you can select the chart type. Opens the Threshold Editor for the active metric.
Thresholds Browser Graph PaneFull Detail

The Thresholds browsers graph pane includes several elements.
Figure 166
Figure 166 Elements in the Thresholds browsers graph pane; the Chart Type is set to Default and the Plot Type is set to Line.

In the Thresholds browser graph pane, you can view a chart for every metric with threshold violations. To view the chart for a metric in the graph pane, click on the entry for that metric in the detail pane. Tip: Hold down the Shift key and drag the mouse between two points in the graph pane to cause the Zonar to zoom in to a smaller portion of the Timeline. When you perform this action, the metric data displayed in the graph pane will be for the new interval spanned by the Zonar. Chart Header The chart header displays the name of the metric that is currently charted in the graph pane. Tip: Hover the cursor over the chart header to make a tooltip appear that displays the full name of the active metric.
Changing the Function Set Click the Function Set chooser icon to display a drop-down menu from which you can select the function applied to the metric that is charted in the graph pane. Tip: Hover the cursor over the Function Set chooser icon to make a tooltip appear that displays the function that is currently applied to the metric charted in the graph pane.
Changing the Plot Type Click the Plot Type chooser icon to display a drop-down menu from which you can select the plot type. When Default or Overlap is selected from the Chart Type chooser, the options available in this menu are Line, Bar, and Area. When Stacked is selected from the Chart Type chooser, the options available in this menu are Stacked Bar and Stacked Area. Tip: Hover the cursor over the Plot Type chooser icon to make a tooltip appear that displays the plot type that is currently selected.
Edit Thresholds Button Click the Edit Thresholds... button to launch the Threshold Editor. See Threshold Editor on page 392 for details about the Threshold Editor. See Thresholds Browser FAQ on page 395 for information about the availability of the Edit Thresholds button.

Indicator Tooltips Hover the cursor over a Metric Indicator to cause a tooltip to appear in which the name of the corresponding metric and the function applied to it are displayed.
Figure 167
Chart Tooltips Hover the cursor over a data point in the chart to cause the x- and y-axis values charted at that point to appear in a tooltip.
Figure 168
Thresholds Browser Detail Pane

The Thresholds browsers detail pane provides an explorer view of the metrics that are charted in the graph pane. Metric properties are displayed in the detail pane in tabular form. Tip: Selecting a row in the detail table and putting it in the operating systems copy buffer allows for further processing. (Select the row in Unix, or Ctrl-C in Windows.) After the row is copied, you can paste it into another application, such as a spreadsheet.
Figure 169
Figure 169 The detail pane in the Thresholds browser
Detail Pane Columns

Figure 170
Figure 170 The column headers in the Thresholds browsers detail pane
Name The Name column lists the names of the metrics with threshold violations during the interval spanned by the Zonar. Tip: Hover the cursor over an entry in the Name column to display the full name of the metric.
Function The Function column lists the function applied to the metric with threshold violations. See Setting Thresholds on page 394 for more information about how metrics with threshold violations are listed in the Thresholds browsers detail pane.
Violation Count The Violation Count column lists the total number of threshold violations for the function applied to the metric. This count includes the point(s) during the interval spanned by the Zonar at which the measurement crosses the maximum threshold line or the minimum threshold line, but not the subsequent points at which the measurement exceeds one of these lines. If the measurement already exceeds one of these lines at the beginning of the interval spanned by the Zonar, the initial measurement point for this interval will be counted as a threshold violation. Total Duration The Total Duration column lists the total length of time during which the thresholds for the function of the metric have been exceeded during the interval spanned by the Zonar.

The bar charts in the Violation Count and Total Duration columns in the Thresholds browsers detail pane allow you to visually compare the values listed in these columns for multiple metrics with threshold violations (see Figure 169).

You can right-click anywhere in the detail table to make a contextual menu appear. The items in these menus are described below.
Figure 171
Auto-Fit Column Click Auto-Fit Column to resize the width of that column so that all values within the column are visible.
Auto-Fit All Columns Click Auto-Fit All Columns to resize the width of all columns in the table so that all values within each column are visible. Hide Column Click Hide Column if you do not want the column on which you right-clicked to be displayed in the table. Show/Hide Columns... You can choose whether or not to display certain metrics in the detail pane. Select Show/Hide Columns... to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated metric in a column in the detail pane. Hide Bar Chart Click Hide Bar Chart if you do not want bar charts displayed in that column. Show/Hide Bar Charts... You can choose whether or not to display certain bar charts in the detail pane columns. Select Show/Hide Bar Charts to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated bar chart.
Threshold Editor
To launch the Threshold Editor, click the Edit Thresholds button in the Metrics, Request Time, SQL, or Thresholds browser or select Tools > Thresholds... from any browsers menu bar. The Edit Thresholds button is only available when you have a Default or Overlap chart open in one of these browsers. See Thresholds Browser FAQ on page 395 for more information.
Figure 172
Figure 172 A response time metric displayed in the Threshold Editor
Using the Threshold Editor

Selecting Metrics from the Navigator Pane
Metrics are listed in a tree hierarchy in the navigator pane on the left-hand side of the Threshold Editor (see Figure 172). The metrics that are listed in this pane include default metrics and all metrics available within the session that you are currently analyzing, such as operating system metrics, application metrics, Java virtual machine metrics, application server metrics, SQL statement metrics and request metrics. You can examine or change the thresholds for a metric by clicking on the entry for that metric in the tree hierarchy. Important: The metrics listed in the navigator pane will vary depending on the application server(s) that you are instrumenting. See The Metric Hierarchy on page 446 for more information about the structure of the metric hierarchy displayed in the Threshold Editor and in the Metrics browser.
Editing Metric Thresholds

A set of threshold properties is associated with each metric. When you select a metric in the tree hierarchy, the properties associated with that metric (Function,
Min Threshold, Max Threshold, and Unit) are listed listed in a table on the right-hand side of the Threshold Editor. The columns in this table are described below. Function Function sets vary between metrics. A separate entry appears in the table for each function applied to the metric that you selected. Max Threshold and Min Threshold Some metrics have default Max Threshold and Min Threshold settings, while other metrics default to undefined. Double double-click the appropriate field in one of these columns to set a new threshold. See Setting Thresholds below for more information. Unit The units of measurement from which you can choose vary between metrics. To select a different unit of measurement, click on the entry in the Unit column to display a drop-down menu in which the options available for that metric are listed. Reset to Default Values Click the Reset To Default Values checkbox to restore the threshold properties listed in the table to their default values. This checkbox will be selected and disabled if the properties have not been changed from their default values. Caution: Clicking the Reset to Default Values checkbox will reset all values listed for every entry in the table, not just the values in the row that you have selected.
Setting Thresholds
Editing the Max Threshold and Min Threshold properties associated with a metric allows you to set bounds which, if exceeded, indicate a possible performance bottleneck that may contribute to an underperforming system. You set maximum and minimum thresholds for each function applied to a metric. When a metric exceeds the bounds that you set in the Threshold Editor, the entry that appears in the table in the Thresholds browsers detail pane corresponds to a specific function of that metric. You can edit the Max Threshold field to contain the value that should not be exceeded during normal operation. Values greater than the one you set here
indicate a system under stress. The Min Threshold field allows you to set a minimum value that should always be exceeded during normal operation. Values less than the one set here indicate that the chosen metric is being underutilized. Important: Threshold settings are saved on a per-Workstation basis. This means that the threshold settings that you save using one PerformaSure Workstation will be available in all Projects that you open using that Workstation. This feature allows you to compare the metrics collected in multiple sessions (when some or all of the same metrics are available), making it easier to track performance problems across sessions. When you open a Project on a new Workstation, the threshold settings will be returned to their default values.
Thresholds Browser FAQ

Ive charted a metric in the graph pane using the Stacked chart, and I want to edit the thresholds for this metric, but the Edit Thresholds button has disappeared. How do I make this button appear so that I can access the Threshold Editor? You cannot edit metric thresholds when you are using a Stacked chart in the Request Time, SQL, Metrics or Thresholds browsers; this is why the Edit Thresholds button is unavailable. Switch to a Default or Overlap chart to make this button appear.
Chapter 17
PerformaSure Reports

PerformaSure Reports Generated Reports Choosing the Report Option PDF Reports CSV Format XML Format Threshold Report Request Time Report SQL Report Request Tree Report Metric Report Network Traffic Report PerformaSure Reports FAQ
PerformaSure Reports
Reports are useful for communicating the data contained in session files to those who need to see the results of an investigation, but who may not want to use the Workstation and open the various browsers. Reports can be distributed widely and they can contain just the information you need to convey. You can create PDF reports, which can be incorporated into other company reports, or you can create CSV- or XML-based reports, which are suitable for further processing by spreadsheets and the like.
397
Generated Reports
Reports are based on browsers. The first step in generating a report is to configure the browser the way you want it to look in the report.
Choosing the Report Option

To generate a report:
1. 2.
Set up the PerformaSure browser the way you want it to look in the report. Click the Export Report button in the browsers toolbar, select Browser > Export Report... from the menu bar, or type Ctrl-R. If you are generating a report from the Request Tree browser, the Request Tree Report dialog will open at this point. Clicking the Continue button will launch the Save dialog. See Request Tree Report Dialog on page 406 for more information about the controls in this dialog.
3.
The Save dialog appears. Select the directory in which you want the report to be saved, supply a filename for the report, and select the format for the generated report from the Files of Type drop-down menu.
The appearance and structure of a report depends on the type of report that you generate (a Request Time Report, SQL Report, Request Tree Report, Metric Report, Network Traffic Report, or Threshold Report) and the file format you select (PDF, CSV, or XML). See Threshold Report on page 407, Request Time Report on page 403, SQL Report on page 404, Request Tree Report on page 404, Metric Report on page 406, and Network Traffic Report on page 407 for more information about the different types of reports. See PDF Reports, CSV Format, and XML Format, below for more information about the different file fomats.
PDF Reports
In PDF format, generated reports contain a header and a body. See Customizing a PDF Report below for more information about PDF report headers. In all types of reports, the body of the report begins with a Reporting Period line stating the date and time interval covered by the report; the start time and end time listed in this line are based on the interval spanned by the browsers Zonar. In all reports except the Request Tree Report, the Reporting Period line is followed by a printer-friendly replica of the view in the graph pane when you generated the
report and a table with details about the session data displayed in this view; see Figure 175 for an example of a PDFRequest Tree Report. In the PDF version of the Metrics Browser Report, for example, there is a replica of each metric graph that was open in the Metrics browser when you generated the report. Each graph is preceded by a Reporting Period line and followed by a table that lists the metrics charted in that graph. Details about these metrics are also included in the table. In certain types of PDF reports, such as the Request Time Report, the SQL Report, and the Threshold Report, the first graph and table are followed by one or more other tables. The information listed in these tables is based on the data displayed in the detail pane of the browser from which you generated the report. The number of tables included in the report and the information that they contain varies depending on the type of report that you generate.
Figure 173
Figure 173 A report in PDF format
PerformaSure Reports 399
Tip: When there are many items displayed in the browser, the PDF version of the Request Tree Report (and to a lesser extent, all reports) may require a significant amount of memory and may cause an out of memory error on some systems. As well, the time required to generate a report may be long, perhaps running to a minute or two. Very large PDF file sizes could well be the result. In the Request Tree browser, for example, you are likely only interested in the top few potential offenders in each request. To reduce the size of the report, you can adjust the settings in the browsers Time Control panel to focus on the part of the session that is of most interest to you and use the Request Tree Report dialog to limit the of number request items included in the report. See Request Tree Report on page 404 for more information about using this dialog. Customizing a PDF Report The header of a PDF report contains, on the left, the report type, the generation date, and the name of the session file. You can add a custom image or custom text to the right-hand side of the reports header. The area on the right is 4.5 inches wide by 0.625 inches high and it can contain the default PerformaSure image, your own custom image, text of your choice, or it can be left blank. These choices are selected in the Edit Options dialog. To open this dialog, select Tools > Options... from the menu bar in the Project window or in any browser. Select Reports from the left-hand side of the Edit Options dialog to display a pane from which you can select different PDF report options. The options in this pane are listed below. Default PerformaSure Image The option Default PerformaSure Image is selected by default. When this option is selected, the area on the right-hand side of the report contains a PerformaSure image. Image Selecting Image allows you to include an image of your choice. GIF, JPEG, or PNG images are supported. Your image should have a size of 324 by 45 pixels if you want it to completely fill the available rectangle. Larger images are scaled to fit, and the aspect ratio of the original image is maintained. Smaller images are placed in the top right-hand corner of the frame. Use padding to place a small image at another location within the frame.
Text Select Text to include custom text in the reports header. Font size depends on the amount of text. Text is auto-scaled to fit in the available area. None Select None if you want to leave the area blank.
Figure 174
Figure 174 Choices for the right-hand side of the PDF report header
CSV Format
The Comma Separated Values form is useful for importing into spreadsheets. Data is presented in tabular format in a generated report saved as a CSV file. The basic structure of a CSV file is as follows: Report Title Report Generation Date Session Name Reporting Period Start date and time Reporting Period End date and time Data Series line(s)
Example: Threshold Report

Generated on:,2004/04/07 18:01 Session:,FirstQuestCars_2003-Oct-30 10:15:29 Reporting Period Start:,10/30/2003 10:15 Reporting Period End:,10/30/2003 10:17 Time (ms),1.06753E+12,1.06753E+12 % JVM heap used for all servers in Unclustered Servers; function:Percent; unit:percent,397.906,63.46 Name,Function,Violation Count,Total Duration (s) % JVM heap used for Unclustered Servers/examplesServer (WebLogic),Percent/Min/Max,1,60 % JVM heap used for Unclustered Servers/examplesServer (WebLogic),Percent,1,60 % JVM heap used for all servers in Unclustered Servers,Percent/Min/Max,1,60 % JVM heap used for all servers in Unclustered Servers,Percent,1,60
XML Format
All generated reports saved in XML format include an XML header, the report root element with name, generated-on, and timezone attributes, as well as session and data elements. The session element contains name, start-time, and end-time attributes. The data element contains different elements and attributes depending on the browser from which you generated the report.
Example: <?xml version="1.0" encoding="UTF-8" ?> <report name="Threshold Report" generated-on="Apr 7, 2004 6:59:48 PM" timezone="EDT"> <session name="FirstQuestCars_2003-Oct-30 10:15:29" start-time="Oct 30, 2003 10:15:29 AM" endtime="Oct 30, 2003 10:17:29 AM" /> <data> <metric-group> <metric name="% JVM heap used for all servers in Unclustered Servers" function="Percent" unit="percent"> <data-point time="1067526929426" value="397.906" /> <data-point time="1067526989426" value="63.46" /> </metric> </metric-group> <threshold-violations> <metric name="% JVM heap used for Unclustered Servers/examplesServer (WebLogic)" function="Percent/Min/Max"> <count>1</count> <total-duration-seconds>60.0</totalduration-seconds> </metric> <metric name="% JVM heap used for Unclustered Servers/examplesServer (WebLogic)" function="Percent"> <count>1</count> <total-duration-seconds>60.0</totalduration-seconds> </metric> <metric name="% JVM heap used for all servers in Unclustered Servers" function="Percent/Min/Max"> <count>1</count> <total-duration-seconds>60.0</totalduration-seconds> </metric> ... </threshold-violations> </data> </report>
Request Time Report

A Request Time Report is based on a Request Time browser. It is available in PDF, CSV, and XML file formats. In all three formats, it begins with the name of the
report, the date on which it was generated, the name of the session, the reporting period start date and time and the reporting period end date and time. Depending on the option that was selected from the Display By drop-down menu in the Request Time browser when you generated the report, the body of the Request Time Report lists either tier or component technology response times for all service requests that entered the instrumented system during the reporting period. The body of the report also includes detailed response time information for the request that you selected broken down either by tier or by component technology. If Show Response Time for All Requests was selected in the browser when you generated the report, the metric Response Time is included with the information for the selected request. This metric is the aggregate response time for all requests. If you have drilled down into the selected request to investigate response time by component technology, tier, or server, the report will also include the drill-down history and details about the response time metrics available for the request at that drill-down level.
SQL Report
A SQL Report is based on a SQL browser. It is available in PDF, CSV, and XML file formats. In all three formats, it begins with the name of the report, the date on which it was generated, the name of the session, the reporting period start date and time and the reporting period end date and time. In the body of the report, there is a list of the SQL statements used in your application and response time metrics for these statements. The report also includes detailed response time information for the SQL statement that you selected broken down by operation (prepare, execute, and retrieve). If Show Response Time for All Statements was selected in the browser when you generated the report, the metric Total Response Time is included with the information for the selected statement. This metric is the aggregate response time for all SQL statements.
Request Tree Report

A Request Tree Report is based on a Request Tree browser. It is available in PDF, CSV, and XML file formats. In all three formats, it begins with the name of the report, the date on which it was generated, the name of the session, the reporting period start date and time, the reporting period end date and time, the number of service requests that entered the instrumented system during the reporting
period, the number of items included in each request, the active metric (the metric by which requests are ordered in the report, for example, Average Cumulative Time), the metric display mode (Per Request or Per Call), and the bundling mode (Component, Class, or Method). The active metric, the metric display mode and the bundling mode are set in the Request Tree browser. See Active Metric on page 292, Metric Display on page 291, and Bundling Mode on page 294 for more information. The number of items included in each request is set in the Request Tree Report dialog. See Request Tree Report Dialog below for more information. In the body of the Request Tree Report, there is a numbered list of the service requests that entered the instrumented system during the reporting period. Requests are ranked in descending order according to the most expensive item in each request. The items within each request are also ranked in descending order. Both rankings are based on the active metric that you selected from the Active Metric drop-down menu in the Request Tree browser. See Active Metric on page 292 for a description of the options available from this menu. Metrics are listed in tabular form for each item within a request. A sample Request Tree Report in PDF format is shown in Figure 175.
Figure 175
Figure 175 A sample Request Tree Report in PDF format
Request Tree Report Dialog

This dialog allows you to select how many items within each service request are included in the Request Tree Report. The controls in this dialog are listed below. Request Tree Items Limit Report to Top n Items in each Service Request Select this option and adjust the setting in the editable spin box to include only the top n most expensive items (based on the active metric) within each request in the report. The default setting is 10. All Service Request Items Select this option to include all items within each service request in the report. Continue After you have selected one of the two options in the Request Tree Items box, click Continue to launch the Save file chooser. Use this file chooser to provide a filename for the report, select a file format, and navigate to the directory in which you want to save the report.
Metric Report
A Metric Report is based on a Metrics browser. It is available in PDF, CSV, and XML file formats. In all three formats, it begins with the name of the report, the date on which it was generated, the name of the session, the reporting period start date and time and the reporting period end date and time. Detailed information is included in the body of the report for each metric graph that was open in the Metrics browser. The name of each charted metric, the function applied to it, its unit of measurement, and the maximum and minimum values charted for that metric during the reporting period are listed in tabular form. The CSV and XML versions of the Metric Report are more useful for data reduction. It is likely that you will want to produce Metric reports in one of these file formats so you can import them into your data reduction and analysis software.
Network Traffic Report

A Network Traffic Report is based on a Network Traffic browser. It is available in PDF, CSV, and XML file formats. In all three formats, the report begins with the name of the report, the date on which it was generated, the name of the session, the reporting period start date and time and the reporting period end date and time. The body of the Network Traffic Report lists the volume of traffic sent from one network location to another during the reporting period. The machine name and IP address is provided for each sender and receiver.
Threshold Report
A Threshold Report is based on a Thresholds browser. It is available in PDF, CSV, and XML file formats. In all three formats, the report begins with the name of the report, the date on which it was generated, the name of the session, the reporting period start date and time and the reporting period end date and time. The body of the Threshold Report contains details about the metric with threshold violations that you selected in the browser, followed by a list of all metrics whose threshold settings were exceeded during the reporting period and details about these metrics.
PerformaSure Reports FAQ

Can I customize generated reports? You can customize reports generated in PDF format in the Edit Options dialog. To launch this dialog, select Tools > Options... from the menu bar in the Project window or in any browser. See Customizing a PDF Report on page 400 for more information.
Part
III
Reference Appendices
Appendix A
Configuring PerformaSure
The Configuration File Hierarchy

Configuration files are located in <performasure_home>/config/ and its subfolders. The configuration file hierarchy is illustrated in Figure 176.
Figure 176
Figure 176 The folders in <performasure_home>/config
Configuring Agents
An Agent must know:
The hostname or IP address and port of the Nexus. The default value of the port is 41706.
411
How long it should wait between attempts to reconnect to the Nexus if it was not able to connect successfully at startup, or if the connection was subsequently lost. How long the Agent should wait for authentication approval during its initial attempt to connect to the Nexus. Whether it will be taking JDBC data into account in Monitoring Mode. Whether it can launch a System Agent if the Nexus requests it.
You can also specify:
A unique Agent name.
You set all the parameters mentioned above in <performasure_home>/config/agent.config.
The Parameters in agent.config

The file <performasure_home>/config/agent.config contains the parameters used in configuring the properties of both Service Request and System Agents. The configuration sections in this file are described below. Important: You must restart the Agents and your instrumented application servers after editing agent.config.
Specifying the Location of the Nexus

NexusHost The hostname or IP address of the Nexus machine to which Agents must connect.
What it is used for: Agents send the data that they have collected to the Nexus using the PerformaSure Proprietary Protocol (PaSPP). At startup, Agents read this configuration section to find the location of the Nexus. Important: You must edit NexusHost, which tells the Agent where to find the Nexus. The default setting is localhost, which assumes that all PerformaSure components are on the same machine as the Nexus. While this is possible, it is not recommended. The Nexus should be on its own machine and it is expected that your Web and application servers occupy a cluster of machines on your network. Example usage:
NexusHost = localhost;
NexusPort The port number that Agents use to communicate with the Nexus. What it is used for: Monitoring Agents send the data that they have collected to the Nexus using the PerformaSure Proprietary Protocol (PaSPP). At startup, Agents read this configuration section to find the location of the Nexus. Example usage:
NexusPort = 41706;
Attempting to Restore the Agent-Nexus Connection

NexusRetryInterval Sets the interval after which an Agent will try to re-establish a broken connection with the Nexus. What it is used for: If the connection between an Agent and the Nexus is broken or if the Agent fails on its initial attempt to connect to the Nexus, the Agent tries to reconnect at regular intervals. This configuration section specifies the time in milliseconds between such attempts. The default setting is 5000 (5 seconds).
Configuring PerformaSure 413
Example usages: To try the connection every five seconds:

NexusRetryInterval = 5000;
To prevent the connection from being retried if it is dropped:

NexusRetryInterval = 0;
Setting the Authentication Timeout

AuthenticateTimeout The time that an Agent will wait for a response from the Nexus after an authentication request. The default is 30 seconds. If the Nexus does not respond within this time, the Agent drops the connection. What it is used for: There are three stages to authentication of the Agent by the Nexus:
1. 2.
The Agent sends an authentication request to the Nexus. The Nexus checks the license number for the Agent and responds with the message, Authentication approved. The Agent sends a message indicating that it acknowledges the Nexus authentication approval. The Agent is now ready to collect data.
3.
The AuthenticateTimeout configuration option specifies the time to wait before a failure message is generated. If the authentication reply is not sent before the timeout, the connection is broken. The Agent retries the connection at regular intervals based on the value of NexusRetryInterval. Example usage: To cause the Agent to wait 30 seconds for a response from the Nexus:
AuthenticateTimeout = 30000;
Taking JDBC Data Into Account

JdbcMonitoringEnabled May have a boolean value of either true or false. This configuration section determines whether the Agent will be taking JDBC data into account when it is in Monitoring Mode. This setting does not affect the data recorded in a session.
Example usage: The default setting is:

JdbcMonitoringEnabled = false;
Specifying an Agent Name

AgentName A configuration option that allows you to specify your choice of name for an Agent. What it is used for: This configuration option allows you to specify a unique Agent name of your own choosing. By default, the Agent name is constructed automatically from the host or server name, so in most cases you do not need to change it. To set a custom name, uncomment the AgentName configuration section in <performasure_home>/config/agent.config (delete the # that precedes it) and then edit it. Example usage:
AgentName = Some Agent Name;
Plug-ins
WebLogic Server plug-in
Multiple WebLogic Server instances on the same machine It is common practice to have multiple WebLogic Server instances running on the same machine. If this is the case, they should be launched sequentially when they are being instrumented by PerformaSure. This will prevent a possible race condition involving the pre-instrumentor, which deletes an existing bootstrap JAR before launching the Agent. If WebLogic Server instances are launched nearly simultaneously, there is a chance that the second instance will delete the bootstrap JAR before the first instance has a chance to use it. In this case, the first Agent will fail. Caution: If you are going to run multiple instances of WebLogic Server on the same machine, then start them up sequentially, not all at once.
Configuring the WebLogic Server See the Installation and Configuration Guide for details.
WebSphere Server plug-in

Configuring the WebSphere Server See the Installation and Configuration Guide for instructions on using PerformaSures Integration Manager to configure IBM WebSphere to work with PerformaSure.
Oracle Application Server Plug-in

See the Installation and Configuration Guide for instructions on configuring Oracle Application Servers to work with PerformaSure.
JBoss Plug-in
See the Installation and Configuration Guide for instructions on configuring JBoss Application Server to work with PerformaSure.
Tomcat Plug-in
See the Installation and Configuration Guide for instructions on configuring Tomcat to work with PerformaSure.
Apache Proxy Plug-in

See the Installation and Configuration Guide for instructions on configuring Apache with a PerformaSure Agent.
iPlanet Proxy Plug-in

See the Installation and Configuration Guide for instructions on configuring iPlanet with a PerformaSure Agent.
Network Traffic Monitor plug-ins

To monitor network traffic on Windows:
To monitor network traffic on machines running the Windows operating system, a driver must be installed. WinPcap is an architecture for packet capture and network analysis for the Win32 platforms. It includes a kernel-level packet filter, a low-level dynamic link library (packet.dll), and a high-level and systemindependent library (wpcap.dll, based on libpcap version 0.5). This device driver allows the Agent to measure the volume of data passing through a network card, which it filters and stores. The packets themselves are not stored, and only the packet length is ready by PerformaSure. Note that all traffic to and from the network interface card is counted, including applications not instrumented with PerformaSure. If you have installed the Nexus on a machine by itself, you will be able to monitor the traffic to and from it. If your test or production environment includes other applications that generate network traffic, but are not part of the servers instrumented with PerformaSure, their volume will be added to the totals.
To monitor network traffic on Solaris:
Similarly, on machines running the Unix operating system, libpcap provides the functionality for monitoring the volume of network traffic.
To monitor network traffic on AIX:
On AIX, the BPF (BSD Packet Filter) interface is used to capture packets. This requires the use of the files in /dev/bpf*. The PerformaSure Agent on AIX will automatically run, as root, /usr/sbin/tcpdump. This will create the files that are needed and will load the correct device drivers. You must have root privileges in order to collect network traffic statistics.
Configuring the Nexus

The Nexus is a set of services with the added ability to change or extend some of functionality through its flexible architecture. This structure is designed to support:
Custom solutions increased ability to adapt to your specific environment. For example, you can: Specify a location for the sessions directory other than the default. Change the default settings for the port on which the Nexus sends messages
to Agents and that Agents use for sending the data they collect to the Nexus. Turn the Nexus System Agent on to benchmark Nexus performance. You configure the Nexus by editing its configuration file, <performasure_home>/config/nexus.config.
The Parameters in nexus.config
Important: You must restart the Nexus after editing <performasure_home>/config/nexus.config. You must restart the Nexus, the Agents, and your instrumented application servers after editing AgentListenHost or AgentListenPort.
Changing the Sessions Directory

SessionDirectory Sets the location of the data collected in a session. What it is used for: The data collected by PerformaSure is kept in session files. By default, they are stored in <performasure_home>/sessions (SessionDirectory is set to sessions). Edit the SessionDirectory configuration section to change the location where session files are kept. For improved performance, consider reserving a drive or a partition of a drive on the same machine as the Nexus solely for session files. Example usages:
SessionDirectory = D:\\Users\\User1\\Sessions; SessionDirectory = /tmp/PerformaSure; SessionDirectory = E:\\Data; SessionDirectory = /usr/ps/sessions;
The SessionDirectory configuration option should contain a single directory name. Absolute or relative paths are allowed. Important: The sessions directory, where the Nexus stores the data reported by PerformaSure Agents, must be on a local drive. The Nexus cannot be run from a network mounted drive using protocols such as NFS (Network Filesystem) or SMB (Server Message Block). If necessary, edit <performasure_home>/config/nexus.config to ensure that this is the case.
Configuring the Communication Ports Used by the Nexus

AgentListenHost and AgentListenPort Set the host and port that the Nexus uses to collect performance data from the Agents using the PerformaSure Proprietary Data Collection Protocol (PaSPDCP). The default value of AgentListenHost is *. The default value of AgentListenPort is 41706. Important: After editing AgentListenHost or AgentListenPort, you must update the <performasure_home>/config/agent.config files for all Agents to match the new settings in <performasure_home>/config/nexus.config, then restart the Nexus, the Agents, and your instrumented application servers. What they are used for:
AgentListenHost has a default value of *. This setting causes the Nexus to listen for connections from the Agents on all available IP addresses . If you substitute a hostname or IP address (such as, for example, 192.168.0.1) for the default value, the Nexus will listen for connections from the Agents only on the IP address that you specify.
Tip: Substitute a hostname or IP address for * if you have multiple network cards on the Nexus machine and you want to only allow Agent connections through one.
You would want to change the default value of AgentListenPort in the unlikely event that you are already using the port number for another purpose.
Example usage: The default settings are:

AgentListenHost = *; AgentListenPort = 41706;
If you need to change the port number, choose one that is greater than 1024. Important: If there is a firewall between the Nexus and Agents, the firewall must be configured to allow connections to be made from the Agents to the Nexus on the port number specified in the AgentListenPort configuration section. ClientListenHost and ClientListenPort Set the host and port that the Nexus uses to service the Workstations and the LoadRunner Connector using Java RMI. The default value of ClientListenHost is *. The default value of ClientListenPort is 42705. What they are used for:
ClientListenHosts default value of * causes the Nexus to listen on all available IP addresses. If you substitute a hostname or IP address (such as, for example, 192.168.0.1) for the default value, the Nexus will listen only on the IP address that you specify.
Tip: Substitute a hostname or IP address for * if you have multiple network cards on the Nexus machine and you want to only allow connections through one.
Example usages: The default settings are:

ClientListenHost = *; ClientListenPort = 42705;
If you need to change the port number, choose one that is greater than 1024. Important: If there is a firewall between the Nexus and the Workstations, the firewall must be configured to allow connections to be made from the Workstations to the Nexus on the port number specified in the ClientListenPort configuration section. See The Parameters in rmiclient.config on page 424 for information about forwarding connections from the Nexus to Nexus clients such as the Workstation through a firewall.
ForceSinglePortRMI May have a boolean value of either true or false. This configuration option determines whether the Nexus is forced to communicate with the Workstation using a single port, ClientListenPort. What it does: When it is set to true, ForceSinglePortRMI restricts communication between the Workstation and the Nexus to the port specified by ClientListenPort; when it is set to false, ports are selected at random. Change ForceSinglePortRMI to false if you are getting errors about a Workstation being unable to connect to the Nexus, a situation which can occur if there are multiple Workstations trying to connect to the Nexus. Caution: Do not set ForceSinglePortRMI to false if the Nexus is on the inside of a firewall that separates it from the Workstations. Setting ForceSinglePortRMI to false will break the connection between the Nexus and any Workstation that is outside the firewall. You should only change ForceSinglePortRMI to false if there is no firewall between the Nexus and the Workstations or if the Nexus is outside the firewall. Example usage: The default setting is:
ForceSinglePortRMI = true;
Enabling a System Agent on the Nexus Machine

LaunchNexusSystemAgent May have a boolean value of either true or false. This configuration section controls whether a System Agent should be launched for the Nexus machine. What it is used for: An instrumented application server runs its own System Agent along with its Service Request Agent. You can choose to run a System Agent on the Nexus machine. The default setting is false, but Quest Software recommends that you run a System Agent on the Nexus machine periodically to ensure that the Nexus is not overtaxing its machine.
Example usage: The default setting is:

LaunchNexusSystemAgent = false;
Changing the Commit Timeout Setting

CommitTimeout The length of time in milliseconds that the Nexus waits before committing a service request to the session data file even if there is missing performance information from an external system. The default value is 4000 (4 seconds). What it is used for: A service request usually spends time in various containers. The part of the request that is processed in a specific container is called a request fragment. The Nexus starts a timer when a request enters a container and it waits for that part of the request to finish. The timer is reset whenever an Agent reports data for the service request. In your environment, some request fragments may be slow. You can increase the value of CommitTimeout if you are seeing a number of fragmented requests. If your application calls out to an uninstrumented server, however, such requests will always be fragmented. The reason for this is that PerformaSure records the call from the instrumented component, but after that the correlation is lost because the information coming back from the uninstrumented server cant be identified with the call. The request completes, and PerformaSure notes the completion, but recognizes that part of the request data is missing. In this case, increasing the value of CommitTimeout is not helpful, so it should not be changed. Tip: PerformaSure is more efficient when the value of CommitTimeout is only slightly greater than the longest service request being instrumented. If you expect to make repetitive tests on a relatively stable environment, it may be worthwhile decreasing the value of CommitTimeout until you begin to see fragmented requests, using 150% of this value. Example usage:
CommitTimeout = 15000;
Specifying the Agent Order Interval

AgentOrderInterval Specifies in milliseconds how often the Nexus will place orders with the Agents for service request samples. The default value is 2000 (2 seconds). What it is used for: The Nexus regularly places orders with the Agents to collect a certain number of service request samples. The interval at which the Nexus places these orders is determined by the value of AgentOrderInterval. This interval is also called the sampling interval. After the Nexus places an order, the Agents determine which service requests to sample. It is not recommended that you edit this configuration option. Decreasing the value of AgentOrderInterval will make the Nexus more responsive to changes in load and will cause the Agents to collect more samples when the Few Samples ... Many Samples slider in the Sampling tab of the Recording Settings dialog is set to the far left. Increasing this value will make the Nexus less responsive to changes in load and will cause the Agents to collect fewer samples when the Few Samples ... Many Samples slider is set to the far left. Example usage: The default setting is:
AgentOrderInterval = 2000;
Launching System Agents Automatically

AllowAutomaticSystemAgentLaunching Has a boolean value of either true or false. This configuration section controls whether the Nexus will attempt to ensure that a System Agent is launched on every host from which another type of Agent has connected. What it is used for: When set to true, the host machine of each instrumented application server will run its own System Agent along with its Service Request Agent or along with the X-Agent. System Agents measure operating system and network metrics. Collecting these types of metrics allows you to monitor the performance of the machines running your application servers.
Example usage The default setting is:

AllowAutomaticSystemAgentLaunching = true;
Configuring Nexus Clients

Each Nexus client (the Workstation, nexusctl, and the LoadRunner Connector) must know:
The hostname or IP address and port that it will use to receive notifications from the Nexus.
You can also specify:
The IP address or hostname of a firewall or NAT that is preventing the Nexus from connecting to the client to deliver notifications and the port on which it will connect to that IP address.
You set all the parameters mentioned above in <performasure_home>/config/rmiclient.config.
The Parameters in rmiclient.config

Configuring Clients to Listen for Notifications from the Nexus
ListenHost and ListenPort Set the host and port that the client (the Workstation, nexusctl, or the LoadRunner Connector) will use to receive notifications from the Nexus using Java RMI. The default value of ListenHost is *. The default value of ListenPort is 42706. What they are used for:
ListenHosts default value of * causes the client to listen on all available IP
addresses. If you substitute a hostname or IP address (such as, for example,
192.168.0.1) for the default value, the client will listen only on the IP address that you specify. Tip: Substitute a hostname or IP address for * if you have multiple network cards on the client machine and you only want to allow connections through one.
You can configure ListenPort to have a value of 0, which will make the client listen for notifications from the Nexus on multiple random ports. If you want to make the client listen for notifications from the Nexus on one port only, configure ListenPort to have a specific value, such as 42706. Setting ListenPort to a specific value allows a firewall to be easily configured to let connections through from the Nexus to the client on the port that you specify. Important: ListenPort must be changed from its default value if the client machine is inside a firewall that separates it from the Nexus and 42706 is already used on the client machine and on the firewall. You must configure the client machine and the firewall to use the same port number. Example usages: The default settings are:
ListenHost = *; ListenPort = 42706;
If you need to change the port number, choose one that is greater than 1024.
Connecting to Clients Through a Firewall

FirewallHost and FirewallPort Set the IP address (or hostname) of a firewall or NAT that is preventing the Nexus from connecting to the client to deliver notifications and the port on which the Nexus will connect to that IP address.
Note:
It is recommended that you set FirewallHost to the IP address of the firewall or NAT.
What they are used for: If a connection needs to be forwarded by a firewall or NAT from a Nexus outside the firewall to any client inside the firewall, uncommenting FirewallHost and setting it to the IP address of the firewall or NAT will make the Nexus connect to
this IP address using the port specified by FirewallPort (which must also be uncommented and set). FirewallPort is the port on the firewall that is forwarded to the ListenPort on the client machine. After uncommenting and setting FirewallHost and FirewallPort, you must configure the firewall or NAT to forward connections to the correct client IP address on the port specified by FirewallPort to ListenPort. Important: The configuration options FirewallHost and FirewallPort must be uncommented and set in rmiclient.config on every machine that hosts a Workstation, nexusctl, or the LoadRunner Connector and is inside a firewall that separates it from the Nexus. Example usage:
FirewallHost = 123.45.67.8; FirewallPort = 42706;
Configuration Lookup Sequence

PerformaSure has a four-stage lookup mechanism that provides fallback, defaults, and the ability to locally override Agent configurations. This mechanism is implemented as a method that takes a name parameter (for example, agenttype/weblogic-61.config). The configuration lookup sequence is described below.
1.
Override: The Agent looks locally in <performasure_home>/config/clientoverride/<name>. Please note that this directory does not exist on installation.
2.
Global: If it is connected to the Nexus, the Agent asks the Nexus to send the file config/client/agent-type/<name> and waits for a reply. The Nexus maps this to <performasure_home>/config/client/agent-type/<name>. The Agent saves the result locally in <performasure_home>/state/<userID>/config-cache/agenttype/<name>. Cached: The Agent looks locally in <performasure_home>/state/<userID>/config-cache/agent-type/<name>. Default: The Agent looks locally in <performasure_home>/config/client/agenttype/<name>.
3.
4.
If the Agent does not find anything after performing all four steps in the lookup sequence, the subsystem which requires that configuration file will fail and be
disabled. In the case of the Agent type configuration or the instrumentation configuration, this will cause the Agent to be shut down.
Note:
PerformaSure logs this exception as part of an ERROR message that is written to the log target that you specified; see Logging below for more information about configuring log targets and setting the log level.
This lookup method is used by the main Agent startup mechanism to retrieve the configuration for a particular Agent type, instrumentation configuration, and the configuration for individual plug-ins that require additional configuration. Important: If there are multiple files in the locations described above, only the first one in the lookup order will be used. Multiple files will not be merged. If an overriding configuration file (for example, a file in config/client-override or on the Nexus) needs to be based on the default configuration file, it must copy the contents of the default configuration file.
Caution: The <performasure_home>/state directory does not contain any user-editable files. Do not edit any of the files in the /state directory or in any of its subdirectories.
Logging
The Parameters in log.config
Important: You must restart the Nexus, the Agents and your instrumented application servers after editing <performasure_home>/config/log.config.
Setting the Locale

Locale Changing the value of Locale allows you to log messages in a language other than the default. What it is used for: The Nexus writes log messages to the console, to log files stored in <performasure_home>/logs, and to other targets that you set (see Target below). These messages inform you about the operation of PerformaSure. When you change the value of Locale, log messages are written in the language that you specify (using the format shown below). Example usages: You must specify the value of Locale using one of the following formats:
xx xx_yy xx_yy_zz
In these formats, xx is an ISO language code, yy is an ISO country code and zz is a vendor-specific variant. For example, to switch to the Canadian English locale:
Locale = en_CA;
Configuring Log Targets

Target Sets the defined log targets: CONSOLE, FILE, NEXUS, NATIVE, SESSION, WEBSPHERE, and LOADRUNNERUI. What it is used for: Log messages include errors and exceptions and information such as the version numbers for PerformaSure, the platform, operating system, JDK, and JVM. Each target specifies an output location for log messages.
CONSOLE: Outputs log messages to the console in which PerformaSure was
started (the Nexus or Agent console).
FILE: Outputs log messages to a file in the directory <performasure_home>\logs (Windows) or <performasure_home>/logs (Solaris). A new log file is created every time the Nexus, Workstation, or an Agent is restarted. NEXUS: Forwards Agent messages to the Nexus for echoing on the Nexus.
NATIVE: Forwards Agent messages to a native (non-Java) logging system like iPlanet or Apache. SESSION: Outputs Nexus messages to the session that is being recorded. WEBSPHERE: Forwards Agent messages to the WebSphere log system. LOADRUNNERUI: Forwards log messages to the LoadRunner Console.
The table below shows the standard target configuration for the Agents, Nexus, Workstation, and the LoadRunner Console.
Target
CONSOLE FILE NEXUS NATIVE SESSION WEBSPHERE LOADRUNNERUI Active Active
All Agents
Active Active Active
WebSphere Agent
Active Active Active
iPlanet and Apache Agents

Active Active Active Active
Nexus
Active Active
Workstation
Active Active
LoadRunner Console
Active Active
Active
Each target has properties that can be configured to modify its behavior. All targets have one common property, threshold: String, the threshold log level for the target. A target ignores log messages that are a level below this threshold. The default log levels for the targets are shown in the chart below. DEBUG is the most verbose level and results in a rapidly-growing log file. See Log Levels below for more information.
Log Level
DEBUG INFO WARN ERROR FATAL Default Default Default Default Default Default Default
CONSOLE
FILE
NEXUS
NATIVE
SESSION
WEBSPHERE
LOADRUNNERUI
The FILE log target has the following additional properties:
charset: String. This property controls the character set in which to write to the file. The default setting is UTF-8. compressBackups: Boolean. This property controls whether old log files are compressed using the gzip method when the maximum log file size is reached and a new log file is opened. The default setting is false.
maxBackupCount: Integer. This property controls how many old log files are retained when the maximum log file size is reached and a new one is opened. The default setting is -1 (infinite). maxFileSize: Long. This property controls the maximum size of a log file before it is closed and a new log file is opened. The size is checked after each log message is written, so the actual size may exceed the maximum slightly. The default setting is 0 (infinite).
CONSOLE, FILE and LOADRUNNERUI are formatting log targets. That is, they apply
a formatting specification to the log message before writing it. Each of these targets has a default formatter:
CONSOLE uses WrappingLogMessageFormatter, which is based on DefaultLogMessageFormatter. WrappingLogMessageFormatter wraps the
formatted log message to a right margin. It will also optionally indent the subsequently wrapped lines.
FILE and LOADRUNNERUI use DefaultLogMessageFormatter.
The formatter is controlled using the formatter subset of properties. The formatter.class property sets the class name for a new instance of a formatter that must be created and assigned to that log target. If the formatter.class property is not present, the remaining properties are applied to the existing formatter. The DefaultLogMessageFormatter has the following properties:
suppressImplDetails: Boolean. When set to true, the formatter does not
include implementation details (thread name, category class and exception stacktrace).
suppressTimestamp: Boolean. When set to true, the formatter does not
include the timestamp. This property is used by log targets which have their own timestamping mechanism, such as NATIVE. The WrappingLogMessageFormatter has the following properties:
columns: Integer. This property controls the maximum number of
characters per line.
indentWrappedLines: Boolean. This property controls whether wrapped
lines are indented by 2 spaces. Example usages:

Target.CONSOLE.formatter.columns = 120; Target.FILE.threshold = "DEBUG"; Target.FILE.compressBackups = true; Target.FILE.maxBackupCount = 100; Target.FILE.maxFileSize = 10000000; Target.FILE.charset = "EUC-JP"; Target.FILE.formatter.class = com.sitraka.pas.common.log.WrappingLogMessageFormatter";
Target.FILE.formatter.indentWrappedLines = false; Target.NEXUS.threshold = "OFF";
Log Levels
The log levels that are used to set a targets threshold are as follows:
DEBUG all messages will be logged. Not used for normal operation, debug messages provide the highest level of reporting at the expense of a rapidly growing log file and some performance degradation. Youll see messages at this level when Quest Software support engineers request extra information to assist you with a problem that you have encountered. INFO The default level for logging messages. This category excludes debug
messages. These messages are used for reporting information about normal operations, such as the location of the PerformaSure home directory, the current Java VM heap size options, the location of the JRE used by PerformaSure, and many other operational details.
WARN Warning messages indicate that some suspicious operation or
configuration has been noted, but it may not have an impact on normal operation.
ERROR Error messages indicate a serious condition which will affect datacollection and other important aspects of PerformaSures operation. FATAL The system writes this message to the log file when some unrecoverable error has occurred, which usually results in PerformaSure shutting down.
Tip: PerformaSure log events are written to the WebSphere console. WebSphere has three levels. The mapping of PerformaSure log levels to these WebSphere levels is as follows:
DEBUG: INFO: WARN: ERROR: FATAL: 3 3 2 1 1
Instrumentation
PerformaSure is a tool with multiple uses. It can be used in development, for QA, and in production. There are times when you want to look at a high-level overview of your systems behavior rather than looking at the method-by-method level. Seeing too much detail before you are ready may make it harder to make some problems stand out. Furthermore, in your deployed application you want to
see an overview of your systems behavior without incurring the overhead of full detail. When you are ready, being able to see the full detail of your application allows you to isolate the particular method that is consuming the most time. PerformaSure can track every method in your J2EE application, and it can track a large number of application server, JMS, JNDI, HTTP, and RMI methods as well, including threads spawned by a servlet. Note: If a class is sufficiently large that, when instrumented, the constant pool size exceeds 64Kb, PerformaSure will not instrument that class. This is to prevent the defineClass() method from failing.
PerformaSure gives you the option of recording a session at two levels: Full Detail or Component Detail. You can set the detail level using the Workstation or nexusctl. See Sampling Tab on page 188 and Sampling Parameters on page 204 for more information. Important: The recording level is set to full detail or component detail in the Sampling tab of the Recording Settings dialog or using nexusctl. This task no longer requires editing one of the configuration files. To force the component-only mode or include custom components, however, you must edit <performasure_home>/config/client/instrumentation.config. See Forcing the Component-Only Mode on page 441 and Customizing Component-Level Data Collection on page 442 for more information. Even if you have recorded a session at full detail, you can choose to view the call trees in the Request Tree browser in component detail by setting the Bundling Mode to Component. When you record a session at full detail and then view the call trees with the Bundling Mode set to Method, you can see every class that is called and every method calleven those that call methods within the same class. At the expense of some complexity, this view allows you to see fine-grained detail within a given request. The component detail setting limits data-collection to important J2EE components or to a custom set of components that you select. Recording a session at the Component Detail level reduces the volume of performance data that is collected and creates an architectural view of each type of service request. This high-level view can help you identify performance problems that may not immediately be apparent when viewing a session recorded in full detail. See Component Instrumentation below for more information on collecting data at this level.
Application Methods in Full Detail

PerformaSure instruments all the classes and methods in your application unless you explicitly choose to exclude some. At the package or class level, you can control which packages or classes are included or excluded by editing UserClasses in <performasure_home>/config/client/instrumentation.config. See Including and Excluding Classes on page 438 for more information. Within a class, you can control the number of recursive calls that are fully instrumented by PerformaSure by editing RecursionCount in instrumentation.config. See Setting the Recursion Limit on page 440 for more information.
Component Instrumentation
There are many reasons why taking a birds eye view of your application is the best way to begin looking for potential performance problems. Focusing on a few crucial methods permits you to localize a potential trouble spot. Then you can add instrumentation targets to expand your search. Afterwards, by switching to full instrumentation mode, you can collect performance data on each class in your application. Component instrumentation also reduces overhead. By collecting data only on a limited set of important classes, you can run PerformaSure with little degradation to your systems response time. To implement component instrumentation, PerformaSure measures selected methods in Servlets, JSPs, EJBs, JMS, JNDI, HTTP, and JDBC, and you can include your own choice of custom components by editing the CustomComponents configuration section in the file <performasure_home>/config/client/instrumentation.config. See the comments in this section of instrumentation.config and Customizing Component-Level Data Collection on page 442 for more information.
Application Methods in Component-Level Detail

When you choose component-level detail, only the classes listed in the following sections are instrumented. Therefore, any of your applications classes that do not implement or extend the interfaces listed in this section are not Tagged and Followed. When you need specific information about all the classes in your application, record in full detail. When you want to gather data on key J2EE
classes, record in component-level detail. You can also extend the componentlevel view to include custom components. Important: Depending on how your application server implements them, certain methods listed below may not appear in a session recorded with component-level detail.
Component-level Classes for Servlets For classes that implement the javax.servlet.Servlet interface, PerformaSure records:
void service(ServletRequest, ServletResponse)
For classes that implement the javax.servlet.http.HttpServlet interface, PerformaSure records:

void void void void void doGet(HttpServletRequest, HttpServletResponse) doPost(HttpServletRequest, HttpServletResponse) doPut(HttpServletRequest, HttpServletResponse) doDelete(HttpServletRequest, HttpServletResponse) doTrace(HttpServletRequest, HttpServletResponse)
For classes that implement the javax.servlet.filter interface, PerformaSure records:

void doFilter(HttpServletRequest, HttpServletResponse)
Component-Level Classes for JSPs For classes that implement the javax.servlet.jsp.HttpJspPage interface, PerformaSure records:
void _jspService(HttpServletRequest, HttpServletResponse)
Component-level Classes for EJBs Session beans, entity beans, and message-driven beans are instrumented. As well, all classes that implement the javax.ejb.EJBLocalHome interface or the javax.ejb.EJBHome interface are recorded, excluding RMI stub classes. WebLogic or WebSphere EJB wrapper classes are excluded from componentlevel instrumentation. For example, in a PetStore session, the productdetails tree has a node for the class named InventoryEJB_ripg5n_Impl. This class contains methods such as __WL_setBusy(Boolean) and __WL_isBusy(). This class is a WebLogic-generated wrapper class for the InventoryEJB and is not instrumented in component mode.
Generic EJB Classes For classes that implement the javax.ejb.EJBLocalHome interface, or the javax.ejb.EJBHome interface, but excluding RMI stub classes, PerformaSure records:
<unknown> create<METHOD>(args) void remove(java.lang.Object) <unknown> find<METHOD>(args) WebLogic and WebSphere wrapper classes are excluded from component instrumentation.
Component-level Classes for Session EJBs For classes that implement the javax.ejb.SessionBean interface, PerformaSure records all public methods, including:
void ejbCreate<METHOD>(args) void ejbActivate() void ejbPassivate()
PerformaSure records all the public methods that your application has added to the bean to support your custom business logic. PerformaSure does not record:
void ejbRemove() void setSessionContext(SessionContext)
Component-level Classes for Entity EJBs For classes that implement the javax.ejb.EntityBean interface, PerformaSure records all public methods, including:
void void void void void void void ejbCreate<METHOD>(args) ejbFind<METHOD>(args) ejbLoad() ejbPostCreate<METHOD>(args) ejbRemove() ejbStore() ejbSelect<METHOD>(args)
PerformaSure does not record:

void ejbPassivate() void setEntityContext(EntityContext) void unsetEntityContext()
Component-level Classes for Message-driven EJBs For classes that implement the javax.ejb.MessageDrivenBean interface, and the javax.jms.MessageListener interface, PerformaSure records all public methods, including:
void onMessage(javax.jms.Message)
PerformaSure does not record:

void ejbRemove() void setMessageDrivenContext(MessageDrivenContext)
JDBC Component-level Detail For classes that implement the java.sql.Connection interface, PerformaSure records:
void close() void commit() void releaseSavepoint(Savepoint) void rollback() void rollback(Savepoint) Savepoint setSavepoint() Savepoint setSavepoint(String)
For classes that implement the java.sql.Driver interface, PerformaSure records:

Connection connect(String, Properties)
For classes that implement the java.sql.PreparedStatement interface, PerformaSure records:

boolean execute() ResultSet executeQuery() int executeUpdate() getMetaData() getParameterMetaData() Note: If you are using a ResultSet implementation with scrollable and sensitive to changes (TYPE_SCROLL_SENSITIVE) enabled, you may see
unexpected database activity in the tree view if while collecting session data your users employed cursor movement methods such as, for example, last() or next(). This is because a ResultSet marked as scrollable and sensitive can require internal calls back to the database to fetch data as a result of method calls that move the cursor. For classes that implement the java.sql.ResultSet interface, PerformaSure records:
void void void void deleteRow() insertRow() RefreshRow() UpdateRow()
For classes that implement the java.sql.Statement interface, PerformaSure records:

boolean execute(String) boolean execute(String, int) boolean execute(String, int[]) boolean execute(String, String[]) int[] executeBatch() ResultSet executeQuery(String) int executeUpdate(String) int executeUpdate(String, int)
int executeUpdate(String, int[]) int executeUpdate(String, String[])
For classes that implement the javax.sql.ConnectionPoolDataSource interface, PerformaSure records:

PooledConnection getPooledConnection() PooledConnection getPooledConnection(String, String)
For classes that implement the javax.sql.DataSource interface, PerformaSure records:

Connection getConnection() Connection getConnection(String, String)
For classes that implement the javax.sql.PooledConnection interface, PerformaSure records:

void close() Connection getConnection()
For classes that implement the javax.sql.XADataSource interface, PerformaSure records:

XAConnection getXAConnection() XAConnection getXAConnection(String, String)
JMS, JNDI, HTTP, and RMI Component-level Classes PerformaSure records the same information in component detail as it does for the full detail level. JMS Component-level Detail PerformaSure records calls to methods in JMS interfaces as follows:
javax.jms.QueueSender all send(...) methods javax.jms.TopicPublisher all publish methods javax.jms.MessageConsumer all receive methods javax.jms.MessageListener all onMessage methods javax.jms.Message all methods javax.jms.Destination all methods javax.jms.Queue all methods javax.jms.Topic all methods
javax.jms.TopicSubscriber all methods javax.jms.QueueReceiver all methods
JNDI Component-level Detail PerformaSure records calls to all methods of these interfaces:

javax.naming.Context javax.naming.NamingEnumeration javax.naming.directoryDirContext
HTTP Component-level Detail PerformaSure instruments all the service requests that enter your instrumented HTTP server unless you explicitly choose to exclude some. See Service Request Filtering on page 73 and Filters Tab on page 193 for more information. You also have the option of splitting one service request and following each part separately. See Service Request Separation on page 71 and Separators Tab on page 190 for more information. RMI Component-level Detail PerformaSure instruments all the RMI calls that enter your instrumented system.
The Parameters in instrumentation.config
Important: You must restart the Agents and your instrumented application servers after editing <performasure_home>/config/client/instrumentation.config.
Including and Excluding Classes

UserClasses Edit this attribute to explicitly exclude or include packages or classes from monitoring.
What it is used for: By default, PerformaSure does not instrument classes that belong to the server itself. The reason for this is that it is usually not possible to alter these classes, so the detailed information about their execution is superfluous. Thus, classes in the server packages and in the JDK are excluded. All others are assumed by PerformaSure to be user code and are instrumented. In most cases, you should not need to alter these settings. If there are times when you would like to instrument a class that is inside a package that has been marked as server code, you can edit the UserClasses configuration section in <performasure_home>/config/client/instrumentation.config to tell the Agents to include that class in their monitoring. This configuration section is used to customize the packages and classes that are fully instrumented by PerformaSure. You can include additional packages and classes for instrumentation and you can exclude packages and classes that are normally included. To include or exclude packages or classes, specify the class or package name in a class list alongside an include or exclude element as shown below. Example usage: To include just one class while excluding the rest of the package:
UserClasses= ClassList( include com.globex.plan.DominateWorld, exclude (\.|^)globex\., exclude /.*globex\..*/, );
Using regular expressions
Regular expressions can be used to select a group of classes or packages that match a given pattern. This approach can help you avoid giving a long list of classes. It can also help you when the exact names of the classes are not known, but they fit a known pattern. If the class names contain an identifying substring, it can be specified in the regular expression.
Using multiple include and exclude elements
When you use multiple include and exclude elements in the UserClasses configuration section, it is the first element that matches that will control the outcome. For example:
UserClasses exclude include exclude ); = ClassList( foo.bar.Baz foo.bar. foo.bar.Boing
In this example, the class foo.bar.Baz is excluded, but foo.bar.Boing is included, because the generic foo.bar. include pattern matches it first. Note that packages are specified with a trailing (.), as the entry foo.bar. indicates. Tip: It is not recommended that you do so, but you can edit the CustomComponents configuration section in the instrumentation.config file for one particular Agent to modify which classes are instrumented for that Agent only. Since the change does not apply to all Agents, the resulting call tree in the Request Tree browser could be confusing. If this procedure is used, the CustomComponents configuration section should be re-edited to match the sections in the other instrumentation.config files as soon as the test for which the procedure was designed is completed.
Customizing the Collection of Data on Long Running Methods

LongRunningUserMethods and LongRunningUserMethodWaypoints The Long Running User Methods configuration sections (LongRunningUserMethods and LongRunningUserMethodWaypoints) can be customized to gather performance information on long running threads or methods. The most common usage is to handle a looping run() method of a thread; see the Long Running Methods section in <performasure_home>/config/client/instrumentation.config for more information.
Setting the Recursion Limit

RecursionLimit Sets the maximum number of recursive calls that are fully instrumented. What it is used for: It is generally not very interesting to collect detailed information on each instance of a recursive call. By default, PerformaSure only measures the first five then continues to collect timing information for the entire recursive sequence, which it aggregates. In the Request Tree browser, PerformaSure tags the terminal node in a recursive sequence with the recursive call icon ( more calls that are not being drawn.
Figure 177
) to indicate that there are
Figure 177 Recursive calls in the Request Tree browser
If you want to see detailed timing information about each recursive call, increase the value of RecursionLimit, restart the Agents and your instrumented application servers, and record a new session. After recording a session that measures each recursive call and determining that the recursive calls are not a performance problem, you can return RecursionLimit to its default setting. This will decrease the load on the Agents and the Nexus. Example usage: To see none of the recursive calls:
RecursionLimit = 0;
With this setting, you will see the method that calls itself in the Request Tree browser. This method will be labeled with the recursive call icon to indicate that recursive calls have occured.
Forcing the Component-Only Mode

InstrumentAtComponentLevel Has a boolean value of either true or false. When set to true, the detail level will be clamped to component no matter what setting you choose in the Workstation or using nexusctl. What it is used for: This configuration section is set to false by default. When it is set to false, you can change the recording detail level to either Component Detail or Full Detail in the Sampling tab of the Workstations Recording Settings dialog or using nexusctl. See Sampling Tab on page 188 and Sampling Parameters on page 204 for more information. Setting InstrumentAtComponentLevel to true ensures that Agents collect component detail only, no matter what setting you choose in the Recording Settings dialog or using nexusctl. Example usage: The default setting is:
InstrumentAtComponentLevel = false; Note:
It is recommended that you leave InstrumentAtComponenetLevel with its default boolean value of false. That way, you can record sessions at the full or component detail level without having to edit <performasure_home>/config/client/instrumentation.config and then restart the Agents and your instrumented application servers.
Customizing Component-Level Data Collection

CustomComponents Extends the default set of J2EE components that are included when you record a session at the component detail level. What it is used for: J2EE applications have very well-defined interfaces that provide natural points at which to limit the collection of performance data. Collecting data at these points by recording a session at the component detail levelhas the benefit of reducing the volume of data (and hence reducing PerformaSures overhead) while also creating a high-level, architectural view of each type of service request. Your application may contain other classes that you deem suitable for inclusion in component-level instrumentation. You can add more items to be fully instrumented by editing the CustomComponents configuration section. The following frameworks and libraries are included in the default set of custom components defined in <performasure_home>/config/client/instrumentation.config:

Apache Struts BEA WebLogic Integration BEA WebLogic Portal IBM Commerce Server IBM Portal Oracle TopLink
See the comments in the CustomComponents configuration section in instrumentation.config for more information about the default set of custom components. Example usage: To include custom components:
CustomComponents = { "MQSeries": MethodList(include /com\.ibm\.mq\..*/), "TopLink": MethodList(include "oracle.toplink."), "Globex": MethodList( include "com.globex.plan.DominateWorld", include "com.globex.pocket.Sugar", include "com.globex.cypresscreek.HammockHut.sit", ) };
As shown in this example, the package or class name of each component must be specified in a method list. You can do so either by entering the components name or by forming a regular expression that matches the name or pattern. Enter the include element before each item in the list.
Configuration FAQ
Large class instrumentation If a class is sufficiently large that, when instrumented, the constant pool size exceeds 64K entries, PerformaSure will not instrument that class. This is to prevent the defineClass() method from failing. What happens if an Agent plug-in fails to load? PerformaSure catches the exception, handles it, and moves on to the next plug-in. It doesnt halt the entire system, but a log message is generated to record the event. PerformaSure generates an exception in the case of a catastrophic failure that it deems too risky for other parts of the system to have it continue.
Note:
Even though execution will continue, some functionality will be disabled.
Error Recovery/Handling Mechanism The following are potential errors that can occur when starting or running Agents:
The Agent is disconnected from the Nexus This error is handled by the communications layer of PerformaSure. When the data is sent to the communications layer and the broken connection is detected, the communications layer automatically tries to reconnect, without any intervention from the other Agent components. However, if the connection cannot be re-established, the Agent instructs the communications layer to periodically attempt to re-establish connection with the Nexus. The repetition interval is set by NexusRetryInterval in <performasure_home>/config/agent.config. See Attempting to Restore the AgentNexus Connection on page 413 for details.
Fatal error occurs inside one of the Agent Threads Although rare, a fatal error, like an uncaught NullPointerException, is sent to the log file, and the Agent is shut down. The server that the Agent is monitoring continues to run, but no data is collected by PerformaSure. The
best course of action to take in this case is to restart the application server, which restarts its Service Request Agent, then record the session from the beginning. What happens if the Agent becomes disconnected from the Nexus while it is recording data? If the Nexus is stopped, all Agents stop recording. This ensures that when the Nexus is restarted, Agents will not try to send data to a Nexus that is not in the recording state. When the Nexus is restarted, the Agents automatically reconnect. However, they will not start recording until a new session is initiated. How do I synchronize data collection in PerformaSure with Mercury LoadRunner? Use the LoadRunner Connector. See the Installation and Configuration Guide. Should I run a System Agent on my load-testing machine? Its a good idea to do so. There could be a bottleneck here that might be interpreted as a problem with the application. By adding a System Agent to your load test machine you can be sure that it is not operating in an overloaded condition.
Appendix B
Metrics in PerformaSure
What Metrics do Agents Measure? PerformaSure divides metrics into two broad categories: raw and derived. Raw metrics are those that are reported from the operating system, web server, and application servers. They may be further divided into periodic metrics, network metrics, and service request metrics. Some of these may not be directly useful. For example, there are a number of never-decreasing metrics that are reported. Knowing the value of such a metric is not useful in itself, but knowing the time rate of increase of the metric is useful, and a sharp spike in the rate may indicate an area for further investigation. Derived metrics are calculated by PerformaSure from one or more raw metrics, and possibly from other derived metrics. Raw Metrics Periodic metrics are collected by PerformaSure by polling the system under test. Operating system, web server, and application server metrics are collected at set intervals. Other approaches are used for collecting network metrics and service request metrics. Derived Metrics Derived metrics are calculated by PerformaSure, usually from raw metrics. Multiple derived metrics can be displayed on the same chart. Naturally, the metrics should be comparable for such a chart to be useful.
445
The Metric Hierarchy

In order to help you analyze performance problems, PerformaSure organizes derived metrics into a metric hierarchy as well as providing a description of and unit of measure for each derived metric. Metrics are organized in this hierarchy in the navigation panes of the Metrics browser and the Threshold Editor. Click on the root node and each subsequent node within the hierarchy that contains a folder icon ( ) to display the items available in that sub-tree. To select a metric, double-click the metric icon ( ). In the Metrics browser, this icon( ) appears next to the entry in the navigation pane for each metric that is charted in the graph pane. Important: The metrics that are available for display and analysis varies depending on the application server(s) that you are instrumenting. The following sections in this chapter illustrate the general form of the metric hierarchy and the nodes and subtrees that may be available within it.
Request Metrics
Requests Root Node
Click on the Requests root node and its sub-nodes to display the following subtrees: Requests

Response Time Response Time All Requests for each [Request] See Request Sub-Trees Call Count All Requests for each [Request] See Request Sub-Trees below. Calls per Second
Call Count

Calls per Second
All Requests for each [Request]

See Request Sub-Trees below.
Exceptional Exits Exceptional Exits All Requests for each [Request]

See Request Sub-Trees below.
% Incomplete % Incomplete All Requests for each [Request] See Request Sub-Trees below. % Sampled % Sampled for each [Request]
% Sampled
Request Sub-Trees Click on a node described above as for each [Request] to expose the following subtree:
Note:
[Metric] All Tiers for each [Tier] [Metric] All Servers for each [Server] [Metric] for each [Component Technology] [Metric] for each [Component] [Metric] for each [method]
The aggregate metric Requests / Call Count / [Request] / [Tier] / [Server] / EJB / [ejb] / Call Count is not a sum of all individual EJB Call Count metrics: it is a count of entry points into EJB technology. When one EJB
Metrics in PerformaSure 447
calls directly into another, the call to the second EJB will not be included in this aggregate metric.
SQL Statement Metrics

SQL Statements Root Node
Click on the SQL Statements root node and its sub-nodes to display the following sub-trees: SQL Statements

Execute Count All SQL Statements for each [SQL Statement] Maximum Execute Time All SQL Statements for each [SQL Statement] Average Response Time All SQL Statements for each [SQL Statement]

All Execution Stages Execute Prepare Retrieve
Total Response Time All SQL Statements for each [SQL Statement]

All Execution Stages Execute Prepare Retrieve
Note:
Prepare, execute, and retrieve metrics are only shown in the hierarchy when they are available. For example, if a SQL statement was executed but no retrieve operations were performed on the SQL statement, the retrieve metric will not be available in the hierarchy for that statement.
Application Metrics
Applications Root Node
The Applications root node contains performance information on the deployed components sorted by application and component technology. Servlets and JSPs are both listed in the Servlets sub-tree. Click on the Applications root node and its sub-nodes to display the following sub-trees: Applications

for each [Application] EJBs for each [EJB] for each [Metric Group] for each [Cluster]

All Servers for each [Server]
Servlets for each [Servlet] for each [Metric Group] for each [Cluster]

Note:
The concept of an application name does not exist in WebLogic Server 5.1. For sessions recorded with WebLogic Server 5.1, a node called /Default Application is added to the metric hierarchy to maintain the structure of the /Applications/for each [Application] sub-tree described above. Oracle 9iAS does not provide metrics for Message Driven Beans. For this reason, no metrics for MDBs will appear under /Applications/for each [Application]/EJBs/ for sessions recorded with Oracle 9iAS. Certain metrics are not available for CMP Beans in sessions recorded with Oracle 9iAS, and thus these metrics will not appear in the metrics hierarchy.
Note:
Note:
Application Server Metrics

Application Servers Root Node
The Application Servers root node contains metrics specific to the application server(s) organized by category. Click on the Application Servers root node and its sub-nodes to display the following sub-trees:

Application Servers Performance for each [Metric Group] See Performance > Metric Group Sub-Trees below. JDBC for each [Metric Group] for each [Pool] for each [Cluster] All Servers for each [Server]
JMS for each [Metric Group] See JMS > Metric Group Sub-Trees below. JTA See JTA Sub-Trees below.
Performance > Metric Group Sub-Trees When you click on a node described above as for each [Metric Group] (in the subtree Application Servers > Performance), you will expose one of the two following sub-trees:

for each [Queue] for each [Cluster] All Servers for each [Server]
or

for each [Cluster] All Servers for each [Server]
JMS > Metric Group Sub-Trees When you click on a node described in Application Servers Root Node as for each [Metric Group] (in the sub-tree Application Servers > JMS), you will expose one of the two following sub-trees:

for each [Queue] for each [Cluster] See JMS > Metric Group > Queue > Cluster Sub-Trees below.
or
for each [Cluster]

See JMS> Metric Group > Cluster Sub-Trees below.
JMS > Metric Group > Queue > Cluster Sub-Trees When you click on a node described in JMS > Metric Group Sub-Trees as for each [Cluster] (in the sub-tree Application Servers > JMS > for each [Metric Group] > for each [Queue]), you will expose one of the two following lists of metrics:

or
for each [Server]
JMS> Metric Group > Cluster Sub-Trees When you click on a node described in JMS > Metric Group Sub-Trees as for each [Cluster] (in the sub-tree Application Servers > JMS > for each [Metric Group] ), you will expose one of the two following lists of metrics:

or
for each [Server]
JTA Sub-Trees When you click on the JTA node, you will expose one or more of the three following sub-trees:
for each [Metric Group]

Global Transactions for each [Metric Group]

Local Transactions for each [Metric Group]

Machine Metrics
Machines Root Node
The Machines root node contains metrics specific to the physical machines in the system organized by System Agent. Click on the Machines root node and its sub-nodes to display the following subtrees: Machines

for each [System Agent] Processors for each [Metric Group] All Processors for each [Processor]
Partitions for each [Metric Group]

All Partitions for each [Partition]
Memory [OS-specific Metric] [OS-specific Metric] System System Calls Interrupts for each [Metric Group]
Interrupt Network
Bytes Sent From [each local IP address] All IP Addresses To [each remote IP address] At [each local IP address] All IP Addresses From [each remote IP address]
Bytes Received
Metrics in PerformaSure FAQ

Why are the values for some metrics displayed as negative percentages? At certain points in time, the value that is charted for a metric in the Metrics browser or the Thresholds browser may be a negative percentage. When this occurs, it is due to the relative timing intervals of the metrics numerator and denominator. For example, you may see a negative value for the metric Application Servers/JTA/% Non-Application Rollbacks if the number of total rollbacks drops below the number of application rollbacks. Why cant I find metrics like Activation Rate, Passivation Rate or Remove Rate listed for CMP beans in a session recorded with Oracle 9iAS? Certain metrics are not available for CMP beans in sessions recorded with Oracle 9iAS, and thus will not appear in the metrics hierarchy. Why cant I find any metrics listed for Message Driven Beans in a session recorded with Oracle 9iAS?
Oracle 9iAS does not provide metrics for Message Driven Beans. This is the reason why no metrics for MDBs will appear in the metrics hierarchy under /Applications/for each [Application]/EJBs/ for sessions recorded with Oracle 9iAS.
Appendix C
Lexicon
Term
Actions
Context LoadRunner
Concept Actions are used when recording client activity. They are a part of each virtual user script. Nodes in the Request Tree browser are ranked against a number of user-selected metrics, such as average exclusive time. The ranking is used to assign a color to the node. The Active Metric is the one that is currently in effect, and is being used as the basis for the ranking. An activity graph and report provides information about the number of virtual users and the number of requests executed during the scenario run. LoadRunners Analysis Graphs and Reports are divided into three categories: Activity, Performance, and Web. PerformaSure Agents collect data, either by monitoring events in instrumented servers (Service Request Agents) or by using OS and Java VM APIs (System Agents). PerformaSure also features the X-Agent, which can be used to instrument standalone Java applications and Java application servers other than JBoss, Oracle 9iAS, Oracle 10g, Tomcat, WebLogic and WebSphere.
Active Metric
Request Tree browser
Activity Graphs and Reports
LoadRunner
Agent
PerformaSure
455
Term
Agent
Context LoadRunner
Concept The Agent enables the Controller and the host to communicate with each other. It receives instructions from the Controller to initialize, run, pause, and abort virtual users. The agent also relays data on the status of the virtual users back to the Controller. The purpose of the Agent is to gather raw data from individual Web servers, application servers and machines, and pass this data to the Nexus. Analysis is the LoadRunner component that processes results gathered during a scenario execution and generates graphs and reports. Also called a Component Transaction Monitor, an application server is a program running on a computer in a distributed network that manages the interaction among browser-based data terminals, business logic servers, and database back-ends, as well as connectivity for application programs. You can use Foglight to trigger a PerformaSure session. For more information, see the Getting Started Guide for your Foglight cartridge. A standard against which some product or process can be measured. Benchmark Factory is Quests load-testing solution that scales throughput to virtually unlimited users, helping you discover the limits of your critical environments before you go live. A BLOB is a SQL built-in type that stores a Binary Large Object as a column value in fields of a database table. A bottleneck is a stage in a process that causes the entire process to slow down or stop. See Transaction Breakdown.
Analysis
LoadRunner
Application Server
General
AutoCapture
Foglight/ PerformaSure
Benchmark
General
Benchmark Factory
Quest Software
BLOB
SQL
Bottleneck
General
Breakdown
LoadRunner
Term
Browser
Context PerformaSure
Concept The data collected in a PerformaSure session can be examined using various browsers. The six types of browser are: Metrics, Network Traffic, Request Time, Request Tree, SQL and Thresholds. The process of merging a call tree fragment into a single node. Bundling is used to hide data so that performance problems are more apparent. For example, a series of method call nodes of the same class in the call tree can be bundled together so that only the initial method node is visible. To find a problem in that class, you need only look at a single node. A business case is a user performing a specific action (for instance, checking a bank balance). See Request Type. Business logic refers to the code that implements the functionality of an application. In the Enterprise JavaBeans model, this logic is implemented by an enterprise bean. Byte code is Java compiler-generated code that is executed by the Java interpreter. A call tree is a visual display of method calls showing the caller-callee relationship. In PerformaSures Request Tree browser, a call tree can also contain RMI and URL invocations. The call trees displayed in this browser are also referred to as request trees. A chart represents data visualized in the form of a graph on x, y, and possibly z axes. JClass Chart is Quest Softwares charting tool. A class is a template for objects. It may be regarded as the objects type. A CLOB is a SQL built-in type that stores a Character Large Object as a column value in fields of a database table.
Bundling
Business Case (Process)
LoadRunner
Business Logic
Designing Enterprise Applications
Byte Code
Java Virtual Machine PerformaSure and JProbe
call tree
Chart
General
JCChart Class
JClass Java
CLOB
SQL
Lexicon 457
Term
Context
Concept Communication services is the interface to the communications layer that the host application sees. The Nexus considers a service request complete if it has seen all the events that make up the request before the end of the session or the end of the incomplete request timeout period. A component is an application-level software unit supported by a container. Components are configurable at deployment time. The J2EE platform defines four types of components: enterprise beans, Web components, applets, and application clients. An object adhering to a component architecture. Examples are Swing GUI components and J2EE Enterprise Java Beans. An option in PerformaSure that reduces complexity is to show the key components in a J2EE application rather than showing all classes and methods that were involved. Often, this higher-level view of the application makes it easier to isolate a trouble spot. A container is an entity that provides life cycle management, security, deployment, and runtime services to components. Each type of container (EJB, Web, JSP, servlet, applet and application client) also provides component-specific services. Context refers to the information that must be associated with a particular element in a request to uniquely identify it. Context is the path taken by a request type through a series of methods. See Critical Path. The controller manages and maintains scenarios. Using the controller, the user can control all the virtual users in a scenario from a single workstation.
Communication Communications Services Layer
Complete Request
PerformaSure Nexus
Component
Designing Enterprise Applications
Component
General
Componentlevel instrumentation
PerformaSure
Container
Designing Enterprise Application
Context
PerformaSure
Context
Request Tree browser LoadRunner
Controller
Term
Correlating (Statements)
Context LoadRunner
Concept Correlating allows the user to link Web statements by using the result of one statement as input to another. The set of entities in the Critical Request, one of which may be contributing to a performance bottleneck. In the Request Tree browser, the critical request is the one that takes the longest time to complete. It is the prime candidate for optimization efforts. Cross-scenario analysis enables comparison of results and performance data from various scenarios on a single graph. The enterprise application integration allows new Web applications to access data and functions residing on existing systems, such as mainframes. Enterprise JavaBeans (EJB) is an architecture for setting up program components, written in the Java programming language, that run in the servers of a computer network that uses the client/server model. An entry-point node represents the URL, RMI invocation, or method by which a request type enters the monitored system. Export mode allows advanced users to fine-tune LoadRunner configuration settings. In the context of this document, an external system is one that is not instrumented by PerformaSure, like a banks credit card validation system that is called from an instrumented e-business application. PerformaSure uses sampling when the load on the system is such that every request cannot be Tagged and Followed. In these situations, PerformaSure uses extrapolation to calculate totals for metrics like cumulative times.
Critical Path
Critical Request Request Tree
browser
Cross-Scenario Analysis
LoadRunner
Enterprise Application Integration (EAI) Enterprise JavaBeans (EJB)
General
Java
Entry-Point Node
Export Mode
LoadRunner
External System
PerformaSure
Extrapolated metric
PerformaSure
Lexicon 459
Term
Failed request
Concept Failed requests are simply completed requests that exited exceptionally from their root node (either because a root method threw an exception, or a root http node returned a result code of 400 or above). Use the FastFind feature after changing the active metric in the Request Tree browser to expose the nodes that are high consumers with respect to the new metric. Filtering is done by typing a literal string or regular expression into the Request Time, Request Tree, or Threshold browsers Filter Requests bar or into the SQL browsers Filter Statements bar. Only those requests or statements that match the literal string or regular expression are displayed. Service request filtering allows you to filter out specified requests using regular expressions or literal strings. Filtering reduces traffic from the Agents to the Nexus, thus decreasing both overhead and storage requirements. You can configure service request filtering to include or exclude certain requests, regardless of the request type (HTTP, RMI, or JMS). Filtering allows a user to display only those items that meet selected criteria (e.g., Filter virtual user window to display only those virtual users that are in a ready state). See Sorting. It is possible for the Nexus to receive data from some Agents but not others during the incomplete request timeout period. This situation results in fragmented requests. Both complete and incomplete requests can potentially become fragmented. For example, PerformaSure would consider a complete request to be fragmented if one part of it did not report back, possibly because that part was being processed by an uninstrumented server.
FastFind
Filtering
PerformaSure browsers
Filtering
PerformaSure
Filtering
LoadRunner
Fragmented Request
PerformaSure Nexus
Term
Garbage Collection
Context General
Concept Garbage Collection is a technique used in Java to eliminate objects that are no longer needed by the program. When no other objects or variables are accessing an object, it can be safely removed, freeing memory allocated to that object. Garbage collection may appear in PerformaSure as an overly-long time for a request to complete. A gateway is a standard way for a Web server to pass a Web users request to an application program and to receive data back, which it then forwards to the user. Term for the metacharacter language for expanding wild card characters in a path name. Metacharacters: * = zero or more characters, for example *.bat ? = any single character {} indicate alternation of comma-separated alternatives. Thus config{.xml,cmd} expands to "config.xml" and "config.cmd". This syntax generates a list of all possible expansions, rather than matching one. Windows and the various Unix shells all implement their own versions of file globbing. Synonymous with chart. See Virtual User Group (Vuser Group) The Group Header is the header and background of a request tree node. It contains the name of the class whose methods are being called. Called methods are represented as rectangular boxes within the Group Header. Graphical User Interface. The host is the machine that executes the virtual user script, enabling the virtual user to emulate the actions of a human user. The host list is a list of machines that execute virtual user scripts during a scenario run. It displays the machines that can run virtual users during scenario execution.
Gateway or Common Gateway Interface (CGI) Glob
General
Unix/Windows
Graph Group Group Header
General LoadRunner Request Tree browser
GUI Host
General LoadRunner
Host List
LoadRunner
Lexicon 461
Term
Incomplete Requests (Percentage)
Concept PerformaSure calculates the percentage of service requests that do not complete. Incomplete requests are long-running requests that exceed the time limit set on them. See Incomplete Request Timeout. A request is considered incomplete if some of the events that make up the request are unpaired and the request has remained in that state with no other events coming into the Nexus for the duration of the incomplete request timeout period. A request is also considered incomplete if the session ends before the response to the request is recorded. The time after which the Nexus classifies a service request as incomplete. See Incomplete Request. Performance timing is not recorded for an incomplete request, but enough information is provided to help you identify what the request was doing when PerformaSure stopped tracking it. A request classified as incomplete may have completed after either the timeout period or the session ended. Servers that have PerformaSure Agents attached to them so requests can be Tagged and Followed. The Java 2 Enterprise Edition API. The Java API for database connectivity. The Java Runtime Environment. Java Server Pages. Java Virtual Machine. Load balancing refers to techniques that aim to spread tasks among the servers assigned to some e-business task.
Mercury Interactives load-testing tool.
Incomplete Request
PerformaSure
Incomplete Request Timeout
PerformaSure
Instrumented servers
PerformaSure
J2EE JDBC JRE JSP JVM Load Balancing
Java Java Java Java Java Application Servers
LoadRunner
LoadRunner
Term
Mercury Interactive LoadRunner Method
Context
LoadRunner
Concept A load-testing tool that emulates a chosen number of users. See the LoadRunner Web page for details. A method is a programmed procedure that is defined in a class and included in any instance of that class. See call tree and Request Tree Browser.
Java
Method Call Tree Metric Query
PerformaSure
PerformaSure
Metric queries are performed by the Workstation to retrieve information stored in a session. Collectively, metrics are the measurements taken in an instrumented application. PerformaSure distinguishes between two types of metrics: System Metrics and Service Request Metrics. System metrics are those quantities related to things that can be quantified about the operating system, JVMs, and the entities in an application server that measure, for instance, how many beans are loaded. Other examples are memory available from the operating system, JVM heap size, and the cached beans current count in an application server. Service request metrics are measurements on the methods in an application server that contribute to a request. Examples are call counts and the various times, bytes, and exceptions associated with the method calls in a request. The Metrics browser is a specialized PerformaSure window that contains a list of metrics and allows you to select metrics for charting. Network monitoring is used to determine whether the network is causing a delay in the scenario. It can also determine the problematic network node. Used to synchronize the time of a computer client or server to another server or reference time source. See NTP
Metrics
PerformaSure
Metrics Browser PerformaSure
Network Monitoring
LoadRunner
Network Time Protocol (NTP)
General
Lexicon 463
Term
Concept The Network Traffic browser is a specialized PerformaSure window that shows the number of bytes transferred between any two machines in your system. You have the option of visualizing this information in a two- or threedimensional graph. The Nexus is PerformaSures central repository; essentially, it is the central manager, the datastore component, and the analysis engine of PerformaSure. The Nexus collects data from Agents to provide information to Workstations. Parameterixing refers to replacing the constant values in the virtual user script with parameters and setting the properties and data source for the parameters. 1)The speed at which a computer operates. 2) The total effectiveness of a computer system, including throughput, individual response time, and availability. 3) The capability of a J2EE application to service requests promptly. This is the meaning of the word when it is used in this manual. Performance graphs and reports analyze virtual user performance and request times. See Activity Graphs and Reports and Web Graphs. Projects are PerformaSures central point of control. You can add as many browsers of each type as you want to a Project and adjust their settings to focus on the problems that you have unearthed in a certain session. When you reload a Project that you saved, the browsers that you added to it are ready to be used again. A query is a request for information. There are two kinds of queries discussed in this manual: 1) SQL queries made through JDBC calls. 2) Queries that a Workstation sends to the Nexus. In this case, the Nexus responds with service request data for display in a browser.
Nexus
PerformaSure
Parameterixing
LoadRunner
Performance
General
Performance Graphs and Reports
LoadRunner
Project
PerformaSure
Query
General
Term
Rendezvous Points
Context LoadRunner
Concept A rendezvous point instructs virtual users to wait during test execution for multiple virtual users to arrive at a certain point (e.g., to emulate peak load on a bank server, you insert a rendezvous point instructing 100 virtual users to deposit cash into their accounts at the same time). PerformaSures Tag and Follow technology defines a request as anything that enters the system causing the application server to spawn a new thread, such as HTTP or an RMI call, and results in a sequence of method calls that may span multiple VMs and computers. A request instance is an ordered sequence of observable server-side events that take place between the time the user makes an HTTP request and when they receive a response. The Request Time browser is a specialized PerformaSure window that shows the time a service request spends in each container that contributes to its execution; it also shows the total time spent servicing the request. The Request Time browser allows you to view the request by tier, by component technology, or by server. The Request Tree browser is a specialized PerformaSure window that shows service requests illustrated in request trees. A request tree starts with the requests invocation as it enters the system and progresses through the various method and database calls. Information about the nodes in the request tree is displayed (on a per-method basis) in a table and the tree nodes tooltips. 1) A use-defined structural (and time-ordered) set of observable events. In the case of URLs, PerformaSure allows you to use separators to separate requests with the same base URL into distinct request types based on query and post parameters. 2) A specific kind of service request (HTTP, RMI, or JMS).
Request
PerformaSure
Request Instance
PerformaSure
PerformaSure
PerformaSure
Request Type
PerformaSure
Lexicon 465
Term
Resource Monitoring Run-Time Settings
Context LoadRunner
Concept Resource monitoring tracks resources used during a scenario. Run-time settings specify how the script behaves when it runs. Configuring run-time settings allows you to emulate different kinds of user activity (e.g. think-time, iterations). PerformaSure uses sampling in high load situations when it is impossible collect performance data for every service request that enters the system. An algorithm is used to collect an appropriate number of samples of each service request type so that the actual behavior of the distributed application can be estimated (extrapolated). A scenario defines the events that occur during each testing session. It defines and controls the number of users to emulate, the actions that they perform, and the machines on which they run their emulations. Scenario also refers to the means by which the user emulates a real-life user. It contains information about how they emulate real users: the number of virtual users, the test scripts these users will run, and the host machines that run the scripts. The scheduler allows a user to set the timing aspect of the scenario (e.g., insert external delays and trigger external events to take place at a specific time). See Virtual User Script (Vuser Script). A script list contains all the virtual user scripts that virtual users can run. The script list may contain scripts for all types of virtual users. See Virtual User Script (Vuser Script) A server is a computer program that provides services to other computer programs in the same or other computers. PerformaSure instruments both Web servers and application servers so that service requests can be tracked and analyzed.
LoadRunner
Sampling
PerformaSure
Scenario
LoadRunner
Scheduler
LoadRunner
Script Script List
LoadRunner LoadRunner
Server
General
Term
Service Request Agent
Concept Service Request Agents collect data on J2EE metrics by instrumenting Web and application servers and by following requests from the point that they enter the instrumented system using Tag and Follow technology. Service Request metrics are the metrics that PerformaSure measures in instrumented Web servers and application servers during a recording session. A Servlet is a Java program that runs on a Web server, generating dynamic content and interacting with Web clients using a requestresponse paradigm. The process of collecting data using PerformaSures capability for instrumenting machines and servers is referred to as a session. The data that is collected is referred to as a session, session data, or a session file. A prolonged connection between a user and a Web application lasting through multiple HTTP requests. The Sightline is a user interface control that identifies a point in time in the graph pane of the Request Time, SQL, and Thresholds browsers and in each of the graphs in the Metrics browser. Sorting displays all the items in a list in a certain order (e.g., sort in order of virtual user ID number). See Filtering. The SQL browser is a specialized PerformaSure window that allows you to view detailed performance information about the SQL statements that are being used in your application. In the browsers graph and detail panes, you can view response time metrics for individual SQL statements broken down by operation; in the graph pane, you can chart the aggregate response time of all statements listed in the detail pane.
Service Request Metrics
PerformaSure
Servlet
General
Session
PerformaSure
Session
General
Sightline
Time Control panel
Sorting
LoadRunner
SQL Browser
PerformaSure
Lexicon 467
Term
Synchronized Time Stamping
Concept
Synchronized Time Stamping is a procedure for
getting two or more timestamping threads to give the same results, even on different machines. PerformaSure System Agents measure operating system, network, and JVM metrics. System Metrics are metrics collected by System Agents. This category of metrics includes operating system parameters and Java virtual machine data. Compare to Service Request Metrics. System performance is a a benchmark against which applications can be measured by using System Agents. PerformaSure is a performance analysis tool.
Tag and Follow is PerformaSures technology for monitoring caller-callee relationships, making request tracking possible. Tag and Follow technology is used to build the request call tree shown in the Request Tree browser.
System Agent
System Metrics
PerformaSure
System Performance
PerformaSure
Tag and Follow
PerformaSure
TCP/IP Test Case
General PerformaSure
The standard Ethernet protocols. Test Case is a session having a restricted set of service requests and other controlled parameters, such as the number of requests of the specified type being issued per time slice. Test-objectives define success criteria. Common client/server objectives that LoadRunner helps users test are: Measuring end-user response time Defining optimal hardware configuration Checking reliability Checking hardware or software upgrades Evaluating new products Measuring system capacity Identifying bottlenecks
Test-Objectives
LoadRunner, PerformaSure
Think Time
LoadRunner
Think time emulates the time that a real user waits between actions.
Term
Throughput
Context General
Concept Throughput is the amount of work that a computer can do in a given time period. It is also a measure of the comparative effectiveness of large commercial computers that run many programs concurrently. The Thresholds browser is a specialized PerformaSure window that contains information about metrics with threshold violations. Metrics that have exceeded their thresholds are listed in the browsers detail pane alongside information about these metrics. Metrics with threshold violations can be charted in the graph pane. A diagonally striped, rectangular strip on the edge of the chart indicates the range on the y-axis in which the metric exceeded its bounds; a threshold line is drawn across the chart to represent the threshold boundary. The Time Control panel contains several elements, such as the Timeline and the Zonar, that allow you to adjust the span of time over which you view session data in a browser. The Time Control panel is the same in all browsers. A time slice is the smallest unit of time in a session. All service requests are deemed to have ended in one time slice or another. The Timeline presents a pictorial representation of the period of time during which a session was recorded. It shows the time when the session started and ended. The tick marks on the Timeline correspond to time slice boundaries. A timeout determines the maximum time (in seconds) that LoadRunner waits for each virtual user to arrive at a rendezvous. Each rendezvous has a set timeout. The default timeout is 30 seconds. A transaction is an atomic unit of work that modifies data. It encloses one or more program statements, all of which either complete or are rolled back. Transactions enable multiple users to access the same data concurrently.
Thresholds Browser
PerformaSure
Time Control panel
PerformaSure browsers
Time Slice
PerformaSure
Timeline
Time Control panel
Timeout
LoadRunner
Transaction
General
Lexicon 469
Term
Transaction
Context LoadRunner
Concept A transaction is an action or set of actions that the user is interested in measuring. Transactions are defined within the virtual user script. After you define a transaction you use it to measure how the server performs under different loads. For example, you could define a transaction to measure the time it takes for a bank server to process a virtual users request to view the balance of an account. A LoadRunner transaction may result in multiple PerformaSure transactions. A transaction breakdown is one of LoadRunners monitoring tools. It is a utility used after analyzing the results of a scenario on an Oracle database server machine to determine where a bottleneck occurred. Tree base time is the instantiation time of the root node of a TransCCT; the time that data about that particular request-type begins to be gathered. Unmatched requests are service requests whose parts have become cut off from each other because some intermediate process failed to complete. These are converted to Fragmented Requests by PerformaSure. An update is a modification to an existing transaction. There are two varieties of updates: insertion of new nodes (insert updates) and addition of incoming metric data to existing nodes (report updates). The use case is a methodology used in system analysis to identify, clarify, and organize system requirements. It is made up of a set of possible sequences of interactions between systems and users in a particular environment and is related to a particular goal.
Transaction Breakdown
LoadRunner
Tree base time
LoadRunner
Unmatched Request
PerformaSure Nexus
Update
General
Use Case
General
Term
View
Concept A view is a presentation of session data contained in one part of a browser. There are several different kinds of views on the data. For example, the presentation of session data in the Request Tree browsers graph pane is sometimes referred to as the tree view. A virtual script generator is the primary tool for developing virtual user scripts. It is a Windowsbased application which enables a user to develop a wide variety of virtual user scripts. It also records scripts and runs them. The virtual script generation creates a virtual user script by recording the actions that you perform on a client application. A virtual user emulates the actions of a human user by performing a typical business process. A virtual user group is a collection of virtual users with a common property (e.g., a common script). Virtual users can be placed into different Groups to classify them according to their tasks. A virtual user list contains all of the virtual users defined in the scenario, with the script and host that were assigned to them. A virtual user script is a description of the actions that a virtual user performs during the scenario. It includes functions that measure and record the performance of the server during the scenario. Each virtual user type requires a particular type of virtual user script (e.g., DB Vuser, GUI Vuser, RTE Vuser). Each virtual user script contains at least three sections: vuser_init, one or more Actions, and vuser end. A virtual user type is a type of virtual user suited to a particular load-testing environment. Virtual user types are divided into six categories: Ebusiness, Middleware, Erp, Client/Server, Legacy, and General. Each virtual user technology is suited to a particular architecture, and results in a specific type of virtual user.
Virtual Script Generator (VuGen)
LoadRunner
Virtual User (Vuser) Virtual User Group (Vuser Group)
LoadRunner
LoadRunner
Virtual User List LoadRunner (Vuser List)
Virtual User Script (Vuser Script)
LoadRunner
Virtual User Type (Vuser Type)
LoadRunner
Lexicon 471
Term
Web Graphs
Context LoadRunner
Concept A Web graph provides information about the throughput and hits of Web virtual users. See Performance Graphs and Reports and Activity Graphs and Reports. A Web server is a program that, using the client/server model and the World Wide Webs Hypertext Transfer Protocol, serves the files that form Web pages to Web users (whose computers contain HTTP clients that forward their requests). The Zonar is part of the Time Control panel. It controls the interval of time for which data is displayed in the browsers graph and detail panes. You can can drag, stretch, and shrink the Zonar within the Timeline and the data displayed in the browser will be adjusted accordingly.
Web Server
General
Zonar
Time Control panel
Appendix D
Regular Expressions
Regular expressions are used throughout PerformaSure to configure components and to select data in queries. For example, you can use regular expressions to filter service requests for display in the Request Tree browser. The Request Tree browser potentially contains a large number of nodes. Of those, some are of immediate interest and some are not. When you have selected the candidates that require further investigation, you can use the Filter Requests text box in the Filter Requests bar to specify the requests that you would like to see. You can input the names of requests (or the methods that are called as part of a service request) literally or you can use Regular Expression syntax to match a group of names. See Show Filter Bar on page 296 for more information about using the Filter Requests bar in the Request Tree browser. See Show Filter Bar on page 232 for information about using the Filter Requests bar in the Request Time browser. See Show Filter Bar on page 263 for information about using the Filter Statements bar in the SQL browser. Tip: Use regular expressions to select groups of requests, classes, methods, or SQL statements for detailed study in the Request Tree, Request Time, and SQL browsers.
Regular expressions employ metacharacters. A metacharacter is a character with special meaning. It does not denote a normal letter, but instead affects the interpretation of other characters in a regular expression. Metacharacters only occur inside a regular expression; for example, an asterisk (*) in a data string is not a metacharacter. There are only a few metacharacters in the regular expression language, but their effect can be quite powerful.
473
The following table lists the metacharacters in PerformaSure and describes their function.
Metacharacter asterisk (*) alias: star Description and Example of Use in a Regular Expression The metacharacter that matches zero or more repetitions of the literal character or sub-expression it follows. Example: the regular expression White *space matches Whitespace, or White space, or White@@any number of space characters@@space, but not White *space (the string containing a literal asterisk). Note: nexus* does NOT match nexus.bat, or nexusconfig. Path name-style matching (file globbing) is not the same as regular expression syntax. The period is a metacharacter that matches any single character or sub-expression unless it is enclosed in a character class, in which case it is simply a period. Examples: The regular expression HTTP1[.]0 matches HTTP1.0. Placing the period in a character class removes its metacharacter status. The regular expression HTTP1.0 matches HTTP1.0 (the string containing the literal period), or HTTP1A0 or HTTP110, but not HTTP1.x or HTTP1..x. The combination dot-star matches any string of characters. It is an idiom for the rest of the characters in a string, but not including the end of line character. Example: the regular expression HTTP.* matches HTTP1.0, or HTTP1://www.xyz.com/index.html. Warning: the regular expression mayb.com.* matches maybecompletely wrong!. The dot in the regular expression matches any character, in this case an e. Note: Because the dot is a metacharacter, use the character class [.] to match a literal dot in a string. It is more robust than attempting to protect the dot with a backslash (\.). The question mark metacharacter matches zero or one occurrence of the character or sub-expression it follows. Examples: the regular expression i?www matches www or iwww; the regular expression (ab)?cd matches abcd and cd. The plus sign metacharacter matches one or more occurrences of the character or sub-expression it follows. Example: the regular expression i+www matches iwww or iiwww, but not www.
period (.) alias: dot
question mark (?)
plus (+)
Metacharacter square brackets ([])
Description and Example of Use in a Regular Expression A pair of bracket metacharacters enclose a character class. Any character in the class is a suitable character for the match. Example: the regular expression [bcp]at matches bat, cat, or pat, but not mat. Note: Which characters are metacharacters and what they do are different inside character classes. The minus sign is a metacharacter only if it occurs between two characters in a character class, in which case it represents a range of characters. Example: the regular expression [b-h]at matches bat, or cat, or fat, or hat, but not mat. Unless it appears as the first entry in a bracketed character class, the caret metacharacter matches the special character that represents the start of a string. The combination [^...] represents a negated character class. All characters except the ones listed are allowed in the match. Examples: the regular expression âbc matches abcxyz but not xyzabc. The regular expression [^cpt]at matches hat, or mat, or any three-letter combination ending in at that does not begin with the letters c, p, or b. Unless it appears as the first entry in a bracketed character class, the dollar metacharacter matches the special character that represents the end of a string. Note: The dollar sign ($) is a shell metacharacter in Unix. If you are running PerformaSure on a Unix system and want to include the dollar sign as a metacharacter in a regular expression, surround the expression with single quotes. For example: sh nexusctl.sh start-recording -fir \.[Gg][Ii][Ff]($|\?)/
minus (-) alias: dash
caret (^)
dollar sign ($)
vertical bar aliases: or, bar
The vertical bar metacharacter matches either of the expressions it separates. Example: the regular expression foo|bar matches foo or bar, but not foobar.
Regular Expressions 475
Metacharacter backslash (\) (reverse solidus)
Description and Example of Use in a Regular Expression This metacharacter, rarely if ever known except by its alias, enforces the literal interpretation of the character following it. It has no effect when placed before an ordinary character. When placed before a metacharacter, it turns off its metacharacter status, thus reducing the character to its literal meaning. Example: the regular expression myhost\.com matches myhost.com, but not myhostscom. Parentheses are used for grouping, for instance, to limit the scope of the or operator. Example: the regular expression http://(my|our)host\.com matches http://myhost.com or http://ourhost.com
parentheses (())
Caution: Do not use parenthesized expressions followed by a plus sign (+) or an asterisk (*) in any of PerformaSures configuration files, in the Workstation, or as part of a nexusctl command.
How Regular Expressions are Scanned

When ambiguities are possible, use these rules to decide how regular expressions do their matching.
The rules for applying regular expressions to target strings are as follows:
1.
The first match is chosen. If a regular expression could possibly match two different parts of an input string then it will match the one that begins earliest. Example: if the regular expression is a.*t and the target string is cataract, the match succeeds with everything after the c. The leftmost choice in a parenthesized group wins. If a regular expression contains | operators, the leftmost matching sub-expression is chosen. Example: if the regular expression is (cat|dog) and the target string is cats and dogs, the match succeeds with cat after the first three letters have been scanned. The longest match wins. In *, +, and ? constructs, longer matches are chosen in preference to shorter ones. Example: if the regular expression is ^Hes ba* and the target string is Hes baaaaack!, the match succeeds with Hes baaaaa after the full list of contiguous as have been scanned.
2.
3.
4.
In sequences of expression components, the components are considered from left to right.
Typical Regular Expression Patterns

Matching the Start and End of a String
The caret and dollar represent the start and end, respectively, of a string. They do not represent characters, but simply the abstract notion of begin and end. They are useful as anchors for the rest of the regular expression.
Regular Expression ^www[.]quest[.]com$ Matches www.quest.com but not http://www.quest.com or www.quest.com/index.html com.quest.performasure, but not homedir.com.quest.performasure java.rmi, but not java.rmi.activation
^com[.]quest[.].*
rmi$
Note:
The meaning of the caret is different if it is the first entry in a character class. In this case it means anything but the characters following it. For instance, [âbc] in a regular expression means that some single character must be matched at the position of the character class within the regular expression, but it cant be a or b or c. If a caret (^) appears anywhere else but the first position in a character class, it simply stands for itself. The same is true for a dollar sign ($) in a character classit is just a dollar sign, not a metacharacter.
Matching with Character Classes

Character classes let you provide a range of possibilities as well as letting you give a specific list. The first example in the table shows the use of a regular expression to match the American or British spelling of the word analyze.
Regular Expression Analy[sz]e this Matches Analyze this, and Analyse this
Regular Expression www[0-9][0-9]?[.]co
Matches www0.co, www01.co, but not www001.co The regular expression matches www followed by a numeral, followed by no more than one more numeral, followed by .co. Thus, 001 fails the match. www.co, www1.co, but not wwwx.co www.quest.com This is the recommended way of matching the dot separator in Java package names and fully qualified names.
www[â-zA-Z]?\.co www[.]quest[.]com
Caution: The dash (-) is a metacharacter only when it occurs between two characters in a character class. Otherwise, it is just an ordinary character. The exception to the rule of interpreting a dash as a range operator when it is between two characters is the following: the regular expression [^-*] means exclude dashes and asterisks from a match.
Matching Any Character: the Dot

Warning: since the dot is a metacharacter, real periods in package names and URLs must be enclosed in square brackets or preceded by backslashes when they are part of a regular expression.
You use the dot (.) metacharacter when you want to indicate that any character is allowed at this position. Combined with parentheses, dot metacharacters can be used to indicate the number of arbitrary characters to be allowed after another pattern. See the second entry in the table below for an example of this case. The first entry in the table is an illustration of the commonly-seen dot-star combination, which matches any number of arbitrary characters. Also, its important to remember that dots are not metacharacters when they occur within a character class.
Regular Expression com\.quest\..* Matches com.quest.the rest of the string, commas, spaces, periods, and all. As long as the test string contains com.quest. followed by any number of additional characters, the match succeeds.
Regular Expression [ ]co(.|..|...|....)[ ]
Matches The words cod, coal, codes, collar, and even co13 The character classes at both ends of the regular expression contain the space character, which limit the match to space-separated words. The matched word must begin with co, followed by one, two, three, or four characters. 594-1026, 594.1026, 594/1026 A dot inside a character class is not a metacharacter.
594[-./]1026
Caution: A forward slash (/) marks regular expression boundaries in PerformaSures configuration files. That is, it is used to start and end regular expressions; you can escape with a backslash (\) if you are using a forward slash in a regular expression in a PerformaSure configuration file. The forward slash is a regular character when it is used outside of PerformaSures configuration files. A dot in a character class is not a metacharacter. A dash is not a metacharacter if it is the first or last character in a character class, or if it follows a leading caret.
Alternation
Use the or (|) metacharacter to combine several possibilities into a single expression. Usually, the or metacharacter is used with parentheses to provide grouping.
Regular Expression (java|javax) This is an explicit equivalent to javax? [(s|t)] Matches java, javax.
(, or s, or |, or t, or ) None of these characters are metacharacters when they are part of a character class. com.sun, com.quest, com.klg
com\.(sun|quest|klg)
Using Regular Expressions in PerformaSure

Using Regular Expressions in Request Separation and Filtering
Regular Expressions and Service Request Separation You can use regular expressions to separate requests with the same base URL into separate request types depending on the requests query and post parameters in the Separators tab of the Workstations Recording Settings dialog and using nexusctl.
To configure service request separators using regular expressions (Workstation instructions):
1.
Open the Recording Control window by selecting Record New Session from the PerformaSure Startup window and then clicking OK. You can also open the Recording Control window by clicking the Recording Control Window button in the Project windows toolbar or by selecting Tools > Recording Control Window from the menu bar of the Project window or any browser. Click the Settings... button in the Recording Control window. The Recording Settings dialog will appear. Click on the Separators tab. Adjust the controls found in this tab to configure service request separation. For example:
4.1 4.2
2.
3. 4.
Press the Add new entry button. An editable entry will appear in the Separate requests that match, in order table. The text field in the URL Expression column will be empty. Doubleclick this text field to make it editable and enter an expression such as the following:
estore/portal-.*\.jsp
4.3
The text field in the Parameters column will also be empty. Doubleclick this text field to make it editable and enter parameters such as the following:
cmd,country,user
4.4
Make sure that RegEx is selected from the drop-down menu in the Type column and the checkbox in the far left column is selected (the default settings). Adjust the setting in the Maximum length of value used for separation editable spin box as desired (the default setting is 32).
4.5
5.
Click OK. The Recording Settings dialog will close but the Recording Control window will remain open, allowing you to begin recording when you choose by clicking Record.
To configure service request separators using regular expressions (nexusctl instructions):

1.
When you are ready to start recording, open a command shell, navigate to the PerformaSure home directory, then to the scripts subdirectory. Include the option -srr URIregex PARAM when you issue the command nexusctl start-recording in the command shell. Example usage:
-srr estore/portal-.*\.jsp country
2.
See Separators Tab on page 190 or Request Separation Parameters on page 205 for more information about using the Workstation or nexusctl to configure service request separators. Regular Expressions and Service Request Filtering You can set filtering patterns for requests in the Filters tab of the Workstations Recording Settings dialog and using nexusctl. The filters support regular expressions. Filtering patterns are used to include or exclude requests that match the given pattern. Tip: If you have specified request separation on a parameter in the Separators tab, you can filter requests on that parameter in the Filters tab.
To set request filtering patterns using regular expressions (Workstation instructions):

1.
Open the Recording Control window by selecting Record New Session from the PerformaSure Startup window and then clicking OK. You can also open the Recording Control window by clicking the Recording Control Window button in the Project windows toolbar or by selecting Tools > Recording Control Window from the menu bar of the Project window or any browser. Click the Settings... button in the Recording Control window. The Recording Settings dialog will appear. Click on the Filters tab. Adjust the controls found in this tab to configure service request filtering. For example, to exclude GIFs from the requests:
4.1 4.2
2.
3. 4.
Press the Add new entry button. An editable entry will appear in the Include or exclude requests that match, in order table. The text field in the Expression column will be empty. Double-click this text field to make it editable and enter the following:
\.[Gg][Ii][Ff]($|\?)/
4.3
Make sure that Exclude is selected from the drop-down menu in the Action column and the checkbox in the far left column is selected (the default settings). Make sure that Included is selected from the All other requests should be drop-down menu (its default setting).
4.4
5.
Click OK. The Recording Settings dialog will close but the Recording Control window will remain open, allowing you to begin recording when you choose by clicking Record.
To set request filtering patterns using regular expressions (nexusctl instructions):
Tip: If you have specified request separation on a parameter by entering a nexusctl request separation flag, you can filter requests on that parameter by using one of nexusctls request filtering options.
1.
When you are ready to start recording, open a command shell, navigate to the PerformaSure home directory, then to the scripts subdirectory. To exclude GIFs from the requests, for example, include the option -fxr \.[Gg][Ii][Ff]($|\?)/ when you issue the command nexusctl startrecording in the command shell.
2.
See Filters Tab on page 193 or Filtering Parameters on page 206 for more information about using the Workstation or nexusctl to set service request filtering patterns.
Using Regular Expressions in PerformaSures Browsers

You can use regular expressions to filter requests for display in the Request Time browser, to filter requests and method and database calls for display in the Request Tree browser, and to filter SQL statements for display in the SQL browser. See Show Filter Bar on page 232 and Show Filter Bar on page 296 for more information about using the Filter Requests bar in the Request Time and Request Tree browsers. See Show Filter Bar on page 263 for more information about using the Filter Statements bar in the SQL browser.
Appendix E
License Credits
The following trademark owners for materials used or referenced by PerformaSure are listed in this chapter:

Adobe Acrobat Ant Apache BEA WebLogic Server BCEL Hewlett-Packard IBM WebSphere JBoss Linux Mercury Interactive Microsoft Netscape Oracle Quest Software Sun Microsystems Tomcat UNIX WinPcap
483
License Credits
Adobe Acrobat
Acrobat is a registered trademark of Adobe Systems Incorporated that may be registered in certain jurisdictions. http://www.adobe.com/
Ant
Apache Ant is a Java-based build tool. Copyright 2000-2002 Apache Software Foundation. All rights Reserved. http://jakarta.apache.org/ant/
Apache
The Apache Software Foundation is the source of these products, which are used in PerformaSure: Ant, BECL, and Log4j. http://www.apache.org
BEA WebLogic Server

BEA WebLogic Server is a registered trademark of BEA Systems, Inc. http://www.bea.com/
BCEL
BCEL and CCK are 2000/2001 Markus Dahm (GNU Lesser General Public License), and is distributed by the Jakarta Java Apache Project. http://jakarta.apache.org/
Hewlett-Packard
HP and HP-UX are registered trademarks of Hewlett-Packard Company. http://www.hp.com/
IBM WebSphere
WebSphere is a registered trademark of IBM Corporation.
JBoss
JBoss is a registered trademark and servicemark of JBoss Inc. 2004 JBoss Inc. All rights reserved. http://www.jboss.org/
Linux
Linux is a registered trademark of Linus Torvalds.
Mercury Interactive
LoadRunner is a registered trademark of Mercury Interactive Corporation.
License Credits 485
http://www-heva.mercuryinteractive.com/
Microsoft
Windows, Windows NT, Windows 2000, Windows XP, and Internet Explorer are registered trademarks of Microsoft Corporation. http://www.microsoft.com/
Netscape
Netscape is a registered trademark of Netscape, America Online Inc. http://www.netscape.com
Oracle
Oracle is a registered trademark of Oracle Corporation. http://www.oracle.com/
Quest Software
Quest Software, the Quest Software logo, PerformaSure, JProbe, JProbe Coverage, JProbe Profiler, JProbe Memory Debugger, and JProbe Threadalyzer are trademarks or registered trademarks of Quest Software Inc. in Canada, United States, and other countries. http://www.quest.com
Sun Microsystems
Sun, Solaris, HotSpot, Java, Java ServerPages, and Enterprise JavaBeans are registered trademarks of Sun Microsystems, Inc. Brazil RegEx (Sun Public License 1.0) http://www.sun.com/
Tomcat
Tomcat is distributed by the Apache Jakarta Project. Copyright 1999-2004, The Apache Software Foundation. http://jakarta.apache.org/tomcat/
UNIX
The UNIX System is a registered trademark of The Open Group in the United States and other countries. http://www.unix-systems.org/
WinPcap
This product includes software developed by the University of California, Lawrence Berkeley Laboratory, Politecnico di Torino, and its contributors, and is distributed subject to the following notice. (http://www-nrg.ee.lbl.gov/nrg-copyright.txt)
/* * * * * * * * * * * * * * Copyright (c) 1988, 1989, 1991, 1994, 1995, 1996, 1997 The Regents of the University of California. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that: (1) source code distributions retain the above copyright notice and this paragraph in its entirety, (2) distributions including binary code include the above copyright notice and this paragraph in its entirety in the documentation or other materials provided with the distribution, and (3) all advertising materials mentioning features or use of this software display the following acknowledgement: This product includes software developed by the University of California, Lawrence Berkeley Laboratory and its contributors. Neither the name of the University nor the names of its contributors may be used to endorse
License Credits 487
* or promote products derived from this software without specific prior * written permission. * THIS SOFTWARE IS PROVIDED AS IS AND WITHOUT ANY EXPRESS OR IMPLIED * WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. */
( http://netgroup-serv.polito.it/analyzer/misc/copyright.htm)
Copyright (c) 1998, 1999, 2000, Politecnico di Torino. All rights reserved. Redistribution and use in binary forms, with or without modification, are permitted provided that: 1.distributions including binary code include the above copyright notice and this paragraph in its entirety in the documentation or other materials provided with the distribution 2.all advertising materials mentioning features or use of this software display the following acknowledgement:This product includes software developed by the Politecnico di Torino, and its contributors. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED AS IS AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
All other products, names, and services are trademarks or registered trademarks of their respective companies or organizations.
Index
A
Active Metric drop-down menu in the Request Tree browsers Toolbar
302
View menu item in the Request Tree browser 292 Add button in the Define Nexus dialog 143 Add New Browser To Project Browser menu item in the Metrics browser 340 Browser menu item in the Network Traffic browser 362 Browser menu item in the Request Time browser 230 Browser menu item in the Request Tree browser 289 Browser menu item in the SQL browser 262 Browser menu item in the Thresholds browser 380 Add Nexus Dialog 57, 144 adding a metric to an existing chart 346 adding comments in the Project window 89 to a browser 89 to a folder 89 to a Project 89 Address in the Add Nexus dialog 58, 144 in the Edit Nexus dialog 57, 144 Agent column in the detail pane of the Request Tree browser
329
Agent configuration lookup sequence 426 Agent list resetting 46, 209 agent.config 412 AgentListenHost 419 AgentListenPort 419 AgentName 415 Agent-Nexus connection 413 AgentOrderInterval 423 Agents Agent startup 48 configuring 411 defined 455 naming 48 Alias in the Add Nexus dialog 58, 144 in the Edit Nexus dialog 57, 143 All Requests mode in the Request Time browser 239
using the Request Time browser in this mode 98 AllowAutomaticSystemAgentLaunching 423 alternation in regular expressions 479 analyzing a session guidelines 84 Apache Proxy plug-in 416 application methods in component-level detail 433 application methods in full detail 433 Application Servers root node in the metric hierarchy 450 Applications root node in the metric hierarchy 449 asterisk in regular expressions 474 AuthenticationTimeout 414 AutoCapture 15, 24 Auto-Fit All Columns View menu item in the Network Traffic browser 363 View menu item in the SQL browser 263 View menu item in the Thresholds browser 381 average exceptional exits 294 Avg Call Count in the detail pane of the Request Tree browser 329 Avg Cumulative Time in the detail pane of the Request Time browser 251 in the detail pane of the Request Tree browser 329 Avg Exceptional Exits in the detail pane of the Request Time browser 251 in the detail pane of the Request Tree browser 331 Avg Exclusive Time in the detail pane of the Request Tree browser 330 Avg Parameter Data Serialized in the detail pane of the Request Tree browser 330 Avg Response Time in the detail pane of the SQL browser 279 Avg Return Data Serialized in the detail pane of the Request Tree browser 330
B
backslash in regular expressions 476 bar in regular expressions 475 Benchmark Factory
489
Quest Softwares load tester 24 Browser menu in the Metrics browsers menu bar 340 menu in the Network Traffic browsers menu bar 362 menu in the Request Time browsers menu bar 230 menu in the Request Tree browsers menu bar 289 menu in the SQL browsers menu bar 262 menu in the Thresholds browsers menu bar 380 Browsers area in the Project window 159 pane in the Edit Options dialog 216 browsers 25 adding comments 89 customizing 91 defined 457 Metrics 335 NetworkTraffic 357 reports generated from browsers 398 Request Time 226 Request Tree 283 SQL 257 Thresholds 375 using 90 Browsers area organizing 88 Bundling Mode drop-down menu in the Request Tree browsers Toolbar
302
C
Call Count in the detail pane of the Request Time browser 251 in the detail pane of the Request Tree browser 329 call count metrics for EJBs 447 Cancel Query button 223 caret in regular expressions 475, 477 Change Password Tools menu item in the Metrics browser 341 Tools menu item in the Network Traffic browser 364 Tools menu item in the Project window 168 Tools menu item in the Request Time browser 233 Tools menu item in the Request Tree browser 297 Tools menu item in the SQL browser 264 Tools menu item in the Startup window 56, 149 Tools menu item in the Thresholds browser 382 Change Password Dialog 151 changing the chart type in the Metrics browser graph pane 350 in the Request Time browser graph pane 246 in the SQL browser graph pane 274 changing the commit timeout setting 422 changing the display mode in the Request Time browser 246
changing the function set in the Metrics browser graph pane 351 in the Request Time browser graph pane 248 in the SQL browser graph pane 276 in the Thresholds browser graph pane 388 changing the log message language 428 changing the plot type in the Metrics browser graph pane 352 in the Request Time browser graph pane 248 in the SQL browser graph pane 276 in the Thresholds browser graph pane 388 changing the sessions directory 418 character classes in regular expressions 477 chart header in the graph pane of the Thresholds browser 388 charts adding a metric to an existing chart 346 opening a metric chart 346 opening multiple metrics in a chart 346 removing a metric from a chart 347 repositioning a metric chart 346 charts in the graph pane of the Metrics browser 349 of the Request Time browser 245 of the SQL browser 273 of the Thresholds browser 388 classes including and excluding 65, 438 CMP Beans and Oracle 9iAS 449 collecting data 59 color coding in request trees 312 in the network interaction chart 370 Color Scale Toggle button in the Network Traffic browser 370 button in the Request Tree browser graph pane 312 coloring the Identifier bars in the Request Tree browser
112
commenting on PerformaSure 11 CommitTimeout 422 communication between the Workstation and the Nexus using a single port 421 communication port used by the Agents 413 used by the Nexus 419 complete request 68 defined 458 Component drill-down action in the Request Time browser 243 component detail 61 component detail level 433 Component Technology display mode in the Request Time browser 98, 231,
252
display mode in the Request Tree browser 291 drill-down action in the Request Time browser 241,
242
component technology identifier in the Request Tree browser graph pane 311 component-level classes for EJBs 434 for Entity EJBs 435 for JSPs 434 for Message-driven EJBs 435 for Servlets 434 for Session EJBs 435 component-level detail HTTP 438 JDBC 436 JMS 437 JNDI 438 RMI 438 component-level instrumentation 62, 433 components in the Time Control panel 219 concepts specific to PerformaSure 16 Configuration FAQ 443 configuration file hierarchy 411 configuration lookup sequence 426 configuring Agents 411 configuring log targets 428 configuring Nexus clients listening for notifications from the Nexus 424 configuring PerformaSure 411 configuring the communication ports used by the Nexus
in the Request Tree browser 109 critical request defined 459 CSV format generated reports 401 Current Drill Down History in the Request Time browser control pane in Single Request Investigation mode 242 CustomComponents 442 customizing component-level data collection 442 customizing PDF reports 400 customizing the collection of data on long running methods 440
D
dash in regular expressions 475 dashed lines in metric charts 93 data collecting 59 data availability 93 Data Availability Indicator 93, 220 data collection modes 61 Data Volume in the detail pane of the Network Traffic browser 372 Default Application node in the Applications sub-tree of the metric hierarchy
449
Define button in the startup sequence 53, 141 Define Nexus Dialog 142 Delete User Alert 150 delivering Nexus notifications through a firewall 425 derived metric hierarchy 446 derived metrics 337 detail levels for recording sessions 431 detail pane in the Network Traffic browser 371 in the Request Time browser 250 in the Request Tree browser 327 in the SQL browser 278 in the Thresholds browser 390 Detail Table Mode View menu item in the Request Tree browser 295 details pane in the Project window 159 directory for sessions 81, 418 disclosure triangle in request tree nodes 326 Display as 3D Chart View menu item in the Network Traffic browser 363 Display By View menu item in the Request Time browser 231
419
configuring the Nexus 417 Confirm Password in the New User dialog 150 text field in the Change Password dialog 151 constructor methods in the request tree 311 contacting customer support 10 contextual menus for entry-point nodes 316 for group nodes 319 for method nodes 323 in the Network Traffic browser detail pane 373 in the Request Time browser detail pane 253 in the SQL browser detail pane 280 in the Thresholds browser detail pane 391 converting a session sessions converting 84 converting old sessions 148 copy node name data from the request tree 318 creating a JProbe Launcher file 332 creating a new Project 146 critical path defined 459
Index
491
View menu item in the Request Tree browser 290 display mode in the Request Time browser 98, 246 dollar sign in regular expressions 44, 206, 475, 477 dot in regular expressions 474, 478 drill-down actions in the Request Time Browser control pane in All Requests mode 240 drill-down history in the Request Time browser control pane in Single Request Investigation mode 242 duration and offset label in the Time Control panel 221
E
Edit button in the Define Nexus dialog 143 Edit Nexus Dialog 57, 143 Edit Options dialog 215 Edit Thresholds button 392 in the Metrics browser graph pane 352 in the Request Time browser graph pane 249 in the SQL browser graph pane 276 in the Thresholds browser graph pane 389 editing metric thresholds 393 EJB call count metrics 447 EJB classes generic 435 EJBs 434, 435 in the request tree 310 enabling a System Agent on the Nexus machine 421 end time label 221 Entity EJBs 435 entry-point nodes 310 contextual menus 316 error while collecting data in the Project window 174 excluding and including classes 65 Execute Count in the detail pane of the SQL browser 279 Existing Project open from the startup sequence 54 existing project open from the startup sequence 146 Exit Browser menu item in the Metrics browser 340 Browser menu item in the Request Time browser 231 Browser menu item in the Request Tree browser 290 Browser menu item in the SQL browser 262 button in the startup sequence 53, 141 Exit button in the Startup window 56
Exit PerformaSure Browser menu item in the Network Traffic browser 362 Browser menu item in the Thresholds browser 380 in the Project windows Project menu 167 exploring the tree hierarchy 346 export JProbe Launcher File 333 Export JProbe Launcher File 127 Browser menu item in the Request Tree browser 289 Export Report Browser menu item in the Metrics browser 340 Browser menu item in the Network Traffic browser 362 Browser menu item in the Request Time browser 230 Browser menu item in the Request Tree browser 289 Browser menu item in the SQL browser 262 Browser menu item in the Thresholds browser 380 button in the Metrics browsers toolbar 344 button in the Network Traffic browsers toolbar 366 button in the Request Time browsers toolbar 236 button in the Request Tree browsers toolbar 300 button in the SQL browsers toolbar 267 button in the Thresholds browsers toolbar 385 extrapolated metric 459
F
factors affecting the size of a session 79 FAQs recording a session 81 Request Time browser 255 SQL browser 282 Thresholds browser 395 FastFind button in the Request Tree browsers Toolbar 302 View menu item in the Request Tree browser 291 file JProbe launcher 332 Filter Machines dialog 368 filtering requests 73 FirewallHost 425 FirewallPort 425 Foglight integration 131 folders adding comments 89 ForceSinglePortRMI 421 forcing the component-only mode 441 format of session files 84 forwarding a connection through a firewall 425 fragmented request 68 defined 460 from the Timeline 221 full detail 61, 433
Function in the detail pane of the Thresholds browser 390 function set chooser in the Metrics browser graph pane 351 in the Request Time browser graph pane 248 in the SQL browser graph pane 276 in the Thresholds browser graph pane 388
I
Identifier bars in the Request Tree browser graph pane 311 including and excluding classes 65, 438 Incomplete % in the detail pane of the Request Tree browser 331 incomplete request 68 defined 462 incomplete requests percentage 294 setting the Incomplete Request Timeout 187 Incomplete Requests (%) defined 462 in the detail pane of the Request Time browser 252 initializers in the request tree 311 Installation and Configuration Guide 9 InstrumentAtComponentLevel 441 instrumentation 431 component-level 62, 433 full 433 instrumentation.config 438 integration with Foglight 131 with JProbe 127 with Quest Database tools 131 with Spotlight 131 interaction with Foglight 35 interaction with load testing tools 35 interaction with Quest database tools 36 interaction with Spotlight 35 interpreting the Timeline labels 92 Introduction 15 investigating response time drilling down into a request 240, 242 investigation modes in the Request Time browser 239 iPlanet Proxy plug-in 416 isolated node 334 isolating performance problems 135 item-tree toggle button in the detail pane of the Request Tree browser 331
G
generated reports 397, 398 CSV format 401 customizing PDF reports 400 Metric Report 406 Network Traffic Report 407 PDF reports 398 Request Time Report 403 Request Tree Report 404 SQL Report 404 Threshold Report 407 XML format 402 generic EJB classes 435 glossary see lexicon group nodes 308, 309 contextual menus 319 guidelines for analyzing a session 84
H
Help menu in the Metrics browsers menu bar 342 menu in the Network Traffic browsers menu bar 365 menu in the Project windows menu bar 169 menu in the Request Time browsers menu bar 234 menu in the Request Tree browsers menu bar 298 menu in the SQL browsers menu bar 265 menu in the Thresholds browsers menu bar 383 Hide/Show Detail button in the Network Traffic browsers Toolbar 367 button in the Request Time browsers Toolbar 237 button in the Request Tree browsers Toolbar 301 button in the SQL browsers toolbar 268 hierarchy of derived metrics 446 history of drill-down levels in the Request Time browser control pane in Single Request Investigation mode 242 hostname of the Nexus machine 412 HTTP component-level detail 438 HTTP requests in the request tree 310
J
JBoss plug-in 416 JDBC calls in the request tree 310 JDBC component-level detail 436 JDBCMonitoringEnabled 414 JMS component-level detail 437 JMS calls in the request tree 311 JMS, JNDI, HTTP and RMI component-level classes 437 JNDI
Index
493
component-level detail 438 JNDI calls in the request tree 311 JProbe and PerformaSure 128 creating a launcher file 332 integration 127 JProbe Launcher file generating 128 JSPs 434 in the request tree 310
K
Key PerformaSure Concepts and Terms 16
L
labels on the Timeline 92 large sessions viewing 85 launch the Nexus from a script 39 launcher file JProbe 332 launching System Agents automatically 423 launching the Threshold Editor 392 LaunchNexusSystemAgent 421 legend in the Metrics browser graph pane 350 in the Request Time browser graph pane 246 in the SQL browser graph pane 274 Less Zone Detail button in the Time Control panel 221 lexicon 455 libpcap monitoring network traffic on UNIX machines 417 Limit Session Length checkbox in the Recording Settings dialog 186 Link Browsers To Use Same Zone/Break Link Between Browsers button in the Metrics browsers toolbar 345 button in the Network Traffic browsers toolbar 367 button in the Request Time browsers toolbar 237 button in the Request Tree browsers toolbar 301 button in the SQL browsers toolbar 268 button in the Thresholds browsers toolbar 386 using this button 96, 222 linking the browsers Time Control panels 96, 222 list of Agents resetting 46, 209 ListenHost 424 ListenPort 424 load in the Nexus 69
load testing tools interaction with 35 LoadRunner 24 LoadRunner Connector configuring 424 Locale 428 location of session data 418 location of the Nexus specifying 412 log levels 431 log targets 428 log.config 427 logging in to the Workstation 52, 140 Login button in the startup sequence 53, 141 Login window in the Workstation 140 Logout Tools menu item in the Startup window 56, 149 LongRunningUserMethods 440 LongRunningUserMethodWaypoints 440
M
Machines root node in the metric hierarchy 452 Max Cumulative Time in the detail pane of the Request Time browser 251 in the detail pane of the Request Tree browser 329 Max Execute Time in the detail pane of the SQL browser 279 Max Parameter Data Serialized in the detail pane of the Request Tree browser 330 Max Return Data Serialized in the detail pane of the Request Tree browser 331 memory needed for large sessions 85 menu bar in the Metrics browser 337, 340, 341, 342 in the Network Traffic browser 359, 362, 363, 364, in the Project window 167, 169 in the Request Time browser 227, 230, 231, 233, 234 in the SQL browser 259, 262, 263, 264, 265 in the Thresholds browser 377, 380, 381, 382, 383 Message-driven EJBs 435 and Oracle 9iAS 132, 449 method nodes 308 contextual menus 323 methodology finding performance problems 84 for analyzing a session 83 metric defined 463 metric chart
365
closing 353 maximizing 353 reposition 120 repositioning 353 restoring 353 metric charts adding a metric to an existing chart 346 opening a chart 346 opening multiple metrics in a chart 346 removing a metric from a chart 347 repositioning a chart 346 Metric Display drop-down menu in the Request Tree browsers Toolbar
monitoring network traffic 417 More Zone Detail button in the Time Control panel 221
N
Name column in the detail pane of the Request Tree browser
328
in the detail pane of the Network Traffic browser 372 in the detail pane of the Request Time browser 251 in the detail pane of the Thresholds browser 390 naming Agents 48 navigating the Timeline 92 navigation pane in the Metrics browser 345 in the Project window 159 negative percentages as metric values 453 network interaction chart 357, 370 network traffic libpcap 417 WinPcap 417 Network Traffic browser 357 defined 464 using the Network Traffic browser 121 Network Traffic browser graph pane 369 Network Traffic Monitor plug-ins 417 New Browser Browser menu item in the Metrics browser 340 Browser menu item in the Network Traffic browser 362 Browser menu item in the Request Time browser 230 Browser menu item in the Request Tree browser 289 Browser menu item in the SQL browser 262 Browser menu item in the Thresholds browser 380 menu item in the Project windows Project menu 163 New Metrics Browser button in the Thresholds browsers Toolbar 384 menu item in the Metrics browsers toolbar 343 menu item in the Network Traffic browsers toolbar 366 menu item in the Project windows toolbar 170 menu item in the Request Time browsers toolbar 235 menu item in the Request Tree browsers toolbar 299 menu item in the SQL browsers toolbar 266 New Network Traffic Browser button in the Thresholds browsers Toolbar 384 menu item in the Metrics browsers toolbar 343 menu item in the Network Traffic browsers toolbar 366 menu item in the Project windows toolbar 170 menu item in the Request Time browsers toolbar 235 menu item in the Request Tree browsers toolbar 300 menu item in the SQL browsers toolbar 266 New Password text field in the Change Password dialog 151 New Project
301
View menu item in the Request Tree browser 291 Metric drop-down menu in the Metrics browser graph pane 350 metric hierarchy 446 Application Servers root node 450 Applications root node 449 in the Metrics browser navigation pane 346 Machines root node 452 Requests root node 446 SQL Statements root node 448 metric legend in the Metrics browser graph pane 350 in the Request Time browser graph pane 246 in the SQL browser graph pane 274 metric properties editing 393 metric types 336 Metrics pane in the Edit Options dialog 216 metrics application metrics 449 application server metrics 450 derived 337 machine metrics 452 metric types 445 raw 336 request metrics 446 selecting from the Metrics browser navigation pane 346 SQL statement metrics 448 Metrics browser 335 defined 463 using the Metrics browser 118 Metrics browser graph pane 347, 348 Metrics browser navigation pane 345 Metrics in PerformaSure 445 Metrics in PerformaSure FAQ 453 Min Parameter Data Serialized in the detail pane of the Request Tree browser 330 Min Return Data Serialized in the detail pane of the Request Tree browser 331 minus sign in regular expressions 475 modes of data collection 61
Index
495
using the New Project Wizard 156 New Project Wizard open from the startup sequence 54, 146 New Request Time Browser button in the Thresholds browsers Toolbar 384 menu item in the Metrics browsers toolbar 343 menu item in the Network Traffic browsers toolbar 365 menu item in the Project windows toolbar 170 menu item in the Request Time browsers toolbar 235 menu item in the Request Tree browsers toolbar 299 menu item in the SQL browsers toolbar 266 New Request Tree Browser button in the Thresholds browsers Toolbar 384 menu item in the Metrics browsers toolbar 343 menu item in the Network Traffic browsers toolbar 366 menu item in the Project windows toolbar 170 menu item in the Request Time browsers toolbar 235 menu item in the Request Tree browsers toolbar 299 menu item in the SQL browsers toolbar 266 new session record 145 New SQL Browser button in the Thresholds browsers Toolbar 384 menu item in the Metrics browsers toolbar 343 menu item in the Network Traffic browsers toolbar 365 menu item in the Project windows toolbar 170 menu item in the Request Time browsers toolbar 235 menu item in the Request Tree browsers toolbar 299 menu item in the SQL browsers toolbar 266 New Thresholds Browser button in the Thresholds browsers Toolbar 384 menu item in the Metrics browsers toolbar 344 menu item in the Network Traffic browsers toolbar 366 menu item in the Project windows toolbar 170 menu item in the Request Time browsers toolbar 235 menu item in the Request Tree browsers toolbar 300 menu item in the SQL browsers toolbar 266 New User Dialog 150 Next Drill Down in the Request Time browser control pane in Single Request Investigation mode 242 Nexus communication ports 419 configuring 417 defined 464 drop-down menu in the startup sequence 53, 141 not responding 141 specifying the location of the Nexus 412 start 40 viewing connections 46, 208 Nexus stop using nexusctl 40 nexus.config 418 nexusctl 39, 40, 177 configuring 424 start-recording 40, 201
stop-recording 40, 201 NexusHost 412 NexusPort 413 NexusRetryInterval 413
O
Offset and Duration Label in the Time Control panel 93, 221 Old Password text field in the Change Password dialog 151 Open Existing Project in the Startup window 146 option in the startup sequence 54 Open Project menu item in the Project windows Project menu 164 Open Recent Project in the Startup window 148 option in the startup sequence 54 Open Session in New Project in the Project windows Project menu 164 in the Startup window 146 option in the startup sequence 54 opening a recent Project 148 opening an existing Project 146 opening metric charts 346 opening multiple metrics in a chart 346 opening sessions 54 opening the Threshold Editor 392 Options menu item 215 Tools menu item in the Metrics browser 342 Tools menu item in the Network Traffic browser 364 Tools menu item in the Project window 168 Tools menu item in the Request Time browser 234 Tools menu item in the Request Tree browser 298 Tools menu item in the SQL browser 265 Tools menu item in the Thresholds browser 383 or in regular expressions 475 Oracle Application Server plug-in 416 Order by in the New Project Wizard 159 organization of derived metrics 446 organizing the Browsers area 88 orphan node at the root level 334 out-of-memory error in large sessions 85 overview of the manual 5
P
parameters in agent.config 412 parameters in instrumentation.config 438 parameters in log.config 427 parameters in nexus.config 418 parentheses in regular expressions 476 partial request 68 Password in the New User dialog 150 in the startup sequence 53, 141 PDF reports 398 customizing 400 performance defined 464 Performance Diagnostics button in the Metrics browsers Toolbar 344 button in the Network Traffic browsers Toolbar 366 button in the Request Time browsers Toolbar 236 button in the Request Tree browsers Toolbar 300 button in the SQL browsers toolbar 267 button in the Thresholds browsers Toolbar 385 Tools menu item in the Metrics browser 342 Tools menu item in the Network Traffic browser 364 Tools menu item in the Project window 168 Tools menu item in the Request Time browser 233 Tools menu item in the Request Tree browser 298 Tools menu item in the SQL browser 264 Tools menu item in the Startup window 149 Tools menu item in the Thresholds browser 382 performance problems in J2EE applications 60 PerformaSure at a Glance 17 components 27 overview of components 19 PerformaSure browsers 25 PerformaSure Direct Technical Support contact information 10 PerformaSure Projects 155 PerformaSure reports 397 PerformaSure support Quest SupportLink PerformaSure technical support 10 PerformaSure terminology and components introduction to 16 PerformaSure Workstation 33, 51 PerformaSures components 19, 27 period in regular expressions 474 plot type chooser in the Metrics browser graph pane 352 in the Request Time browser graph pane 248 in the SQL browser graph pane 276 in the Thresholds browser graph pane 388 plug-ins 415 Apache Proxy plug-in 416
iPlanet Proxy plug-in 416 JBoss plug-in 416 Oracle Application Server plug-in 416 Tomcat plug-in 416 WebLogic Server plug-in 415 WebSphere Server plug-in 416 plugins Network Traffic Monitor plug-ins 417 plus sign in regular expressions 474 Port in the Add Nexus dialog 58, 144 in the Edit Nexus dialog 57, 144 ports Agent communication port 413 Nexus communication port 419 prepare, execute, and retrieve metrics displayed in the metric hierarchy 448 product feedback 11 profile selected classes or packages with JProbe 333 Project template 159 Project menu in the Project window 163 Project Properties in the Project windows Project menu 167 Projects adding comments 89 Properties Browser menu item in the Metrics browser 340 Browser menu item in the Network Traffic browser 362 Browser menu item in the Request Time browser 231 Browser menu item in the Request Tree browser 290 Browser menu item in the SQL browser 262 Browser menu item in the Thresholds browser 380 button in the Metrics browsers toolbar 344 button in the Network Traffic browsers toolbar 366 button in the Project windows toolbar 171 button in the Request Time browsers toolbar 236 button in the Request Tree browsers toolbar 300 button in the SQL browsers toolbar 267 button in the Thresholds browsers toolbar 385
Q
Query Progress bar 223 Quest Database tools integration 131 Quest SupportLink PerformaSure support question mark in regular expressions 474
Index
497
R
raw metrics 336 readme for PerformaSure 8 receiving notifications from the Nexus configuring Nexus clients 424 Recent Project open from the startup sequence 54 recent project open from the startup sequence 148 Record button in the Recording Control Window 183 Record New Session in the Startup window 145 option in the startup sequence 54 recording from the PerformaSure Workstation 177 recording a new session 145 recording a session 59, 76 Recording Control Window 177 button in the Project windows toolbar 171 Tools menu item in the Metrics browser 341 Tools menu item in the Network Traffic browser 363 Tools menu item in the Project window 167 Tools menu item in the Request Time browser 233 Tools menu item in the Request Tree browser 297 Tools menu item in the SQL browser 264 Tools menu item in the Thresholds browser 382 Recording Control window open from the startup sequence 54, 145 recording levels component detail 61 full detail 61 recording sessions choosing the detail level 431 recording settings file 45, 207 recursion limit 65 RecursionLimit 440 recursive calls configuring display of 65 regular expressions 473 in PerformaSure 480 scanning 476 using the dollar sign metacharacter 44, 206, 475 related documents 8 related time controls 222 Remove button in the Define Nexus dialog 143 removing a metric from a chart 347 Reports pane in the Edit Options dialog 216 reports CSV format 401 customizing PDF reports 400 generated from browsers 398
Metric Report 406 Network Traffic Report 407 PDF reports 398 Request Time Report 403 Request Tree Report 404 SQL Report 404 Threshold Report 407 XML format 402 repositioning a metric chart 346 request complete 68 defined 465 filtering 73 fragmented 68 incomplete 68 partial 68 sampling 70 separation 71 timeout thresholds 69 unmatched 68 request call graph in the Request Tree browser 284 Request Investigation in the Request Time Browser control pane in All Requests mode 240 Request Time browser 226 defined 465 FAQ 255 in All Requests mode 239 in Single Request Investigation mode 242 investigation modes 239 using the Request Time browser 96 Request Time browser control pane 238, 239 Request Time browser detail pane controlling the display of columns in the table 99 Request Time browser drill-down history in the control pane in Single Request Investigation mode 242 Request Time browser graph pane 244 Request Tree pane in the Edit Options dialog 216 Request Tree browser 283 defined 465 using the Request Tree browser 108 Request Tree browser graph pane 303, 307 Request Tree detail pane in the Request Tree browser 284 request tree nodes tooltips 312, 314, 315 request tree tooltips 312 request trees in the Request Tree browser graph pane 308 request type defined 465 requests separating based on URL parameters 192
setting the Incomplete Request Timeout 187 Requests root node in the metric hierarchy 446 resetting the Agent list 46, 209 Resize Sliders in the Request Tree browser graph pane 308 Response Time drop-down menu in the Request Time browser graph pane 246 RMI component-level detail 438 RMI calls in the request tree 310 rmiclient.config 424
S
sampled requests affected by incomplete requests 314 sampling 70 rate 188 Save in the Project windows Project menu 165 in the Save file chooser 165 Save Project As in the Project windows Project menu 165 scanning in regular expressions 476 script launching the Nexus from a script 40 security 34 selecting metrics for display in the Metrics browser graph pane 346 separating requests based on URL parameters 192 separation of service requests 71 Server drill-down action in the Request Time browser 241,
session files format 84 session length setting a time limit for a session 187 Session Management button in the Project windows toolbar 171 Tools menu item in the Metrics browser 341 Tools menu item in the Network Traffic browser 363 Tools menu item in the Project window 168 Tools menu item in the Request Time browser 233 Tools menu item in the Request Tree browser 297 Tools menu item in the SQL browser 264 Tools menu item in the Startup window 55, 148 Tools menu item in the Thresholds browser 382 Session Start Time Label and Session End Time Label 92,
221
sessions directory 81 recording a session 59 viewing large 85 SessionsDirectory 418 setting the time slice size 75 setting the authentication timeout 414 setting the display mode in the Request Time browser 98 setting the locale 428 setting the recursion limit 440 setting thresholds 392 Show Filter Bar View menu item in the SQL browser 263 View menu item in the Thresholds browser 381 Show Panner button in the Request Tree browsers Toolbar 301 button in the Request Tree browsers toolbar 111 View menu item in the Request Tree browser 111, 295 Show/Hide Bar Charts View menu item in the SQL browser 263 View menu item in the Thresholds browser 381 Show/Hide Child Node buttons contextual menus 327 Show/Hide Columns View menu item in the Network Traffic browser 363 View menu item in the Request Time browser 232 View menu item in the Request Tree browser 296 View menu item in the SQL browser 263 View menu item in the Thresholds browser 381 showing connections to the Nexus 46, 208 Sightline 222 defined 467 in the charts in the Metrics browser 352 slider 95, 222 using the Sightline and the Sightline slider 95 Single Request Investigation mode in the Request Time browser 242 using the Request Time browser in this mode 102 size of a session file 79
243
service request description 26 filtering 73 separation 71 timeout thresholds 69 Servlets 434 in the request tree 310 session acquisition 74, 76 defined 467 error icon in the Project window 174 open in new Project from the Startup window 146 sampling 188 session data availability 93 Session EJBs 435 session file factors that affect the size of a session 79
Index
499
setting the time slice size 187 Sort Tree View menu item in the Request Tree browser 291 specifying an Agent name 415 specifying the Agent order interval 423 specifying the location of the Nexus 412 Spotlight integration 131 Spotlight on DB2 launching from the contextual menu for a group node in the request tree 322 launching from the contextual menu for a method node in the request tree 326 launching from the contextual menu in the SQL browser detail pane 281 launching from the Metrics browsers Toolbar 344 launching from the Network Traffic browsers Toolbar
168
launching from the Tools menu in the Request Time browser 233 launching from the Tools menu in the Request Tree browser 298 launching from the Tools menu in the SQL browser 264 launching from the Tools menu in the Thresholds browser 382 Spotlight on WebLogic Server launching from the Metrics browsers Toolbar 344 launching from the Network Traffic browsers Toolbar
366
launching from the Request Time browsers Toolbar
236
launching from the Request Tree browsers Toolbar 300 launching from the SQL browsers toolbar 267 launching from the Thresholds browsers Toolbar 385 launching from the Tools menu in the Metrics browser
366
342
launching from the Tools menu in the Network Traffic browser 364 launching from the Tools menu in the Project window
236
168
launching from the Tools menu in the Request Time browser 233 launching from the Tools menu in the Request Tree browser 298 launching from the Tools menu in the SQL browser 264 launching from the Tools menu in the Startup window
342
168
launching from the Tools menu in the Request Time browser 233 launching from the Tools menu in the Request Tree browser 298 launching from the Tools menu in the SQL browser 264 launching from the Tools menu in the Thresholds browser 382 Spotlight on Oracle launching from the contextual menu for a group node in the request tree 322 launching from the contextual menu for a method node in the request tree 326 launching from the contextual menu in the SQL browser detail pane 281 launching from the Metrics browsers Toolbar 344 launching from the Network Traffic browsers Toolbar
56, 149
launching from the Tools menu in the Thresholds browser 382 Spotlight on WebSphere launching from the Metrics browsers Toolbar 344 launching from the Network Traffic browsers Toolbar
366
236
342
366
168
launching from the Tools menu in the Request Time browser 233 launching from the Tools menu in the Request Tree browser 298 launching from the Tools menu in the SQL browser 264 launching from the Tools menu in the Startup window
236
342
56, 149
launching from the Tools menu in the Thresholds browser 382
SQL browser 257 defined 467 FAQ 282 using the SQL browser 104 SQL browser control pane 268, 269 SQL browser detail pane controlling the display of columns in the table 105 SQL browser graph pane 271, 272 SQL Statement in the detail pane of the SQL browser 278 SQL Statements Root Node in the metric hierarchy 448 SQL Tuning button in the Metrics browsers toolbar 344 button in the Network Traffic browsers toolbar 367 button in the Request Time browsers toolbar 236 button in the Request Tree browsers toolbar 301 button in the SQL browsers toolbar 267 button in the Thresholds browsers toolbar 385 Tools menu item in the Metrics browser 342 Tools menu item in the Network Traffic browser 364 Tools menu item in the Project window 168 Tools menu item in the Request Time browser 234 Tools menu item in the Request Tree browser 298 Tools menu item in the SQL browser 265 Tools menu item in the Thresholds browser 383 SQL tuning integration 131 SQL Tuning for DB2 launching from the contextual menu in the SQL browser detail pane 281 launching from the Metrics browsers toolbar 344 launching from the Network Traffic browsers Toolbar
236
342
168
launching from the Tools menu in the Request Time browser 234 launching from the Tools menu in the Request Tree browser 298 launching from the Tools menu in the SQL browser 265 launching from the Tools menu in the Thresholds browser 383 square brackets in regular expressions 475 star in regular expressions 474 start option in nexusctl 40 start time label 221 start-recording option in nexusctl 40, 201 startup Agent startup 48 static methods in the request tree 311 Stop button in the Recording Control window 183 stop recording dialog 183 stop-recording option in nexusctl 40, 201 suggested reading 9 support 10 contacting 10 SupportWatch see Quest SupportLink System Agent enabling to run on the Nexus machine 421 launching automatically 423 system clock resetting 39
367
236
342
168
launching from the Tools menu in the Request Time browser 234 launching from the Tools menu in the Request Tree browser 298 launching from the Tools menu in the SQL browser 265 launching from the Tools menu in the Thresholds browser 383 SQLab Vision for Oracle launching from the contextual menu in the SQL browser detail pane 281 launching from the Metrics browsers toolbar 344 launching from the Network Traffic browsers Toolbar
T
Tag and Follow 74 taking JDBC data into account 414 Target 428 technical support 10 template for Project files 159 terms specific to PerformaSure 16
367
Index
501
Themes pane in the Edit Options dialog 216 Threshold Editor 392 Thresholds Tools menu item in the Metrics browser 341 Tools menu item in the Network Traffic browser 363 Tools menu item in the Project window 168 Tools menu item in the Request Time browser 233 Tools menu item in the Request Tree browser 297 Tools menu item in the SQL browser 264 Tools menu item in the Thresholds browser 382 thresholds editing 393 Thresholds browser 375 defined 469 FAQ 395 using the Thresholds browser 125 Thresholds browser graph pane 386, 387 Tier display mode in the Request Time browser 98, 231,
252
display mode in the Request Tree browser 290 drill-down action in the Request Time browser 240 tier identifier in the Request Tree browser graph pane 311 time setting the session length 187 setting the time slice size 187 Time Control Panel in the Metrics browser 345 in the Network Traffic browser 368 in the Request Time browser 237 in the Request Tree browser 302 in the SQL browser 268 in the Thresholds browser 386 Time Control panel 219 components in the panel 219 in the Metrics browser 336 in the Request Tree browser 284 using the Time Control panel 91 Time Control panels linking 96 time controls related to the Time Control panel 222 time slice defined 469 setting 187 Time Slice Size setting 75 Timeline defined 469 in the Time Control panel 220 navigating the Timeline 92 zooming the Timeline 94 Timeline labels 92 in the Time Control panel 221
timeout setting the Incomplete Request Timeout 187 Tomcat plug-in 416 Toolbar in the Metrics browser 343 in the Network Traffic browser 365 in the Project window 169 in the Request Time browser 234 in the SQL browser 265 in the Thresholds browser 383 toolbar in the Metrics browser 339 in the Network Traffic browser 361 in the Project window 162 in the Request Time browser 229 in the Request Tree browser 287 in the SQL browser 261 in the Thresholds browser 379 Tools drop-down menu in the Startup window 55, 148 menu in the Metrics browsers menu bar 341 menu in the Network Traffic browsers menu bar 363 menu in the Project windows menu bar 167 menu in the Request Time browsers menu bar 233 menu in the Request Tree browsers menu bar 297 menu in the SQL browsers menu bar 264 menu in the Thresholds browsers menu bar 382 tooltips for EJB nodes 314 for request tree nodes 312, 314, 315 in the Metrics browser graph pane 353 in the Network Traffic browser graph pane 371 in the Network Traffic browsers graph pane 123 in the Request Time browser graph pane 249 in the Request Tree browser graph pane 312 in the SQL browser graph pane 276 in the Thresholds browser graph pane 389 Total Cumulative Time in the detail pane of the Request Time browser 251 in the detail pane of the Request Tree browser 329 Total Duration in the detail pane of the Thresholds browser 391 Total Response Time in the detail pane of the SQL browser 279 Total Response Time drop-down menu in the SQL browser graph pane 274 tracking drill-down levels in the Request Time browser control pane in Single Request Investigation mode 242 tree hierarchy in the Metrics browser navigation pane 346 troubleshooting See also FAQ types of metrics 336
U
Unix using the dollar sign metacharacter in regular expressions 44, 206, 475 unmatched request 68 upgrading sessions from a previous version 148 User Administration Tools menu item in the Metrics browser 341 Tools menu item in the Network Traffic browser 364 Tools menu item in the Project window 168 Tools menu item in the Request Time browser 233 Tools menu item in the Request Tree browser 297 Tools menu item in the SQL browser 264 Tools menu item in the Startup window 56, 149 Tools menu item in the Thresholds browser 382 user interface introduction 51 User Name in the New User dialog 150 in the startup sequence 53, 141 text area in the Change Password dialog 151 UserClasses 438 Using PerformaSure introduction 20 using the legend in the Metrics browser graph pane 350 in the Request Time browser graph pane 246 in the SQL browser graph pane 274 using the Metric drop-down menu in the Metrics browser graph pane 350 using the Metrics browser 118 using the Network Traffic browser 121 using the Request Time browser 96 using the Request Time browser in All Requests mode 98 Using the Request Time browser in Single Request Investigation mode 102 using the Request Tree browser 108 using the Response Time drop-down menu in the Request Time browser graph pane 246 using the Sightline 95 using the Sightline and the Sightline slider 352 using the SQL browser 104 using the Threshold Editor 393 using the Thresholds browser 125 using the Time Control panel 91 using the Total Response Time drop-down menu in the SQL browser graph pane 274 using the Zonar 93
menu in the Request Time browsers menu bar 231 menu in the Request Tree browsers menu bar 290 menu in the SQL browsers menu bar 263 menu in the Thresholds browsers menu bar 381 viewing Nexus connections 46, 208 viewing sessions 54 Violation Count in the detail pane of the Thresholds browser 391
W
WebLogic Server plug-in 415 WebSphere levels and PerformaSure log levels 431 WebSphere Server plug-in 416 Windows menu in the Metrics browsers menu bar 342 menu in the Network Traffic browsers menu bar 364 menu in the Project windows menu bar 169 menu in the Request Time browsers menu bar 234 menu in the Request Tree browsers menu bar 298 menu in the SQL browsers menu bar 265 menu in the Thresholds browsers menu bar 383 WinPcap monitoring network traffic on Windows machines 417 Workstation 33, 51 configuring 424 logging in 52, 140 Login window 53
X
XML format generated reports 402
Z
Zonar in the Time Control panel 220 using the Zonar 93 Zonar label 221 Zonar Offset and Duration Label 93, 221 Zoom Control slider in the Network Traffic browser graph pane 370 in the Request Tree browser graph pane 312, 327 zoom in to the Timeline 221 zoom out 221 zooming the network interaction chart 123 zooming the Timeline 94
V
vertical bar in regular expressions 475 View menu in the Metrics browsers menu bar 341 menu in the Network Traffic browsers menu bar 363
Index
503

Perform A Sure UserGuide

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Perform A Sure UserGuide

Uploaded by

Copyright:

Available Formats

PerformaSure

J2EE performance diagnosis

Part No: STPSUSER350

Part I: Structure and Workflow

Chapter 2 Starting PerformaSure ......................................................37

Chapter 3 Recording a Session ........................................................59

Chapter 4 Analyzing Sessions.......................................................... 83

Chapter 5 Isolating Performance Problems ........................................135

Part II: The PerformaSureWorkstation

Chapter 7 PerformaSure Projects ................................................... 155

Chapter 8 Recording Control Window and nexusctl................................................................ 177

Chapter 9 Edit Options Dialog.........................................................215 Chapter 10 Time Control Panel.........................................................219

Chapter 11 Request Time Browser.....................................................225

Chapter 12 SQL Browser.................................................................257

Chapter 13 Request Tree Browser .................................................... 283

Chapter 14 Metrics Browser ........................................................... 335

Chapter 15 Network Traffic Browser ................................................. 357

Network Traffic Browser FAQ................................................................. 373

Chapter 16 Thresholds Browser ........................................................375

Chapter 17 PerformaSure Reports .....................................................397

Part III: Reference Appendices

Appendix B Metrics in PerformaSure ................................................. 445

Appendix C Lexicon ...................................................................... 455 Appendix D Regular Expressions....................................................... 473

Appendix E License Credits ............................................................ 483

viii PerformaSure: Users Guide

x PerformaSure: Users Guide

About Quests Java and J2EE Products

Quests place in monitoring Java performance

4 PerformaSure: Users Guide

Overview of the Manual

6 PerformaSure: Users Guide

Conventions Used in this Manual

Important: Introduces material of special importance.

Troubleshooting: Suggests a corrective action if you encounter the problem described.

8 PerformaSure: Users Guide

Installation and Configuration Guide

PerformaSure Users Guide

To Contact PerformaSure Support

Telephone Fax European Customers Contact Information PerformaSure FAQs

You can use SupportLink to do the following:

10 PerformaSure: Users Guide

Product Feedback and Announcements

12 PerformaSure: Users Guide

Part Structure and Workflow

Key PerformaSure Concepts and Terms

16 PerformaSure: Users Guide

Term service request

Background: Distributed Systems

A typical 3-tier system configuration

18 PerformaSure: Users Guide

JMS bytes transferred

A 3-tier system instrumented with PerformaSure

An Overview of PerformaSures Components

PerformaSures three types of components

20 PerformaSure: Users Guide

What Does PerformaSure Do?

Reconstruction of the true execution path using Tag and Follow

22 PerformaSure: Users Guide

What Approach Does PerformaSure Take?

Who Uses PerformaSure?

Database administrators can:

Application server and system administrators can: