Quest Software 5.0 PerformaSure User’s Guide
Below you will find brief information for PerformaSure 5.0. 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 Java EE environments and can also be used once an application is deployed to ensure that planned capacity goals are met.
advertisement
TM
PerformaSure
User’s Guide
Version 5.0
Java EE performance diagnosis
World Headquarters
5 Polaris Way
Aliso Viejo, CA 92656 www.quest.com
email: [email protected]
June 04, 2009 Part No: PerformaSure50
© 2009 Quest Software, Inc. ALL RIGHTS RESERVED.
This guide contains proprietary information 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 purchaser's personal use without the written permission of Quest Software, Inc.
If you have any questions regarding your potential use of this material, contact:
Quest Software World Headquarters
LEGAL Dept
5 Polaris Way
Aliso Viejo, CA 92656 www.quest.com
email: [email protected]
Refer to our Web site for regional and international office information.
Trademarks
Quest, Quest Software, the Quest Software logo, Aelita, Akonix, AppAssure, Benchmark Factory, Big Brother, ChangeAuditor, DataFactory,
DeployDirector, ERDisk, Foglight, Funnel Web, GPOAdmin, iToken, I/Watch, Imceda, InLook, IntelliProfile, InTrust, Invirtus, IT Dad,
I/Watch, JClass, Jint, JProbe, LeccoTech, LiteSpeed, LiveReorg, MessageStats, NBSpool, NetBase, Npulse, NetPro, PassGo, PerformaSure,
Quest Central, SharePlex, Sitraka, SmartAlarm, Spotlight, SQL LiteSpeed, SQL Navigator, SQL Watch, SQLab, Stat, StealthCollect, Tag and
Follow, Toad, T.O.A.D., Toad World, vAMP, vAnalyzer, vAutomator, vControl, vConverter, vDupe, vEssentials, vFoglight, vMigrator, vOptimizer Pro, vPackager, vRanger, vRanger Pro, vReplicator, vSpotlight, vToad, Vintela, Virtual DBA, VizionCore, Vizioncore vAutomation Suite, Vizioncore vEssentials, Xaffire, and XRT are trademarks and registered trademarks of Quest Software, Inc in the United
States of America and other countries. Other trademarks and registered trademarks used in this guide are property of their respective owners.
Third-Party Contributions
See “
.
Disclaimer
The information in this document is provided in connection with Quest products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Quest products. EXCEPT AS SET FORTH IN
QUEST'S TERMS AND CONDITIONS AS SPECIFIED IN THE LICENSE AGREEMENT FOR THIS PRODUCT, QUEST
ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY
RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL QUEST BE LIABLE FOR ANY
DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT
LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF INFORMATION) ARISING OUT
OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF QUEST HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES. Quest makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Quest does not make any commitment to update the information contained in this document.
User’s Guide
June 04, 2009
Version 5.0
2
Contents
Preface ....................................................................... 13
Conventions Used in this Guide ...........................................................14
PerformaSure Installation and Configuration Guide ..........................16
Contacting Quest Software ....................................................................17
Contacting Quest Support .....................................................................17
Part I: Structure and Workflow
Chapter 1 Introducing PerformaSure ................................................. 21
Key PerformaSure Concepts and Terms..............................................22
Background: Distributed Systems .........................................................23
What Does PerformaSure Do? ..............................................................25
What Approach Does PerformaSure Take?.........................................27
With Your Infrastructure and Tools?......................................................27
What Do PerformaSure Browsers Do?.................................................28
How does PerformaSure Define a Service Request? ..........................28
How does PerformaSure Show a Service Request? ............................29
Who Uses PerformaSure? ......................................................................29
3
The Components of PerformaSure.............................................................30
PerformaSure Agents..............................................................................30
PerformaSure Nexus ..............................................................................33
PerformaSure Workstation ....................................................................35
Interaction with Load-Testing Tools ..........................................................38
Chapter 2 Starting PerformaSure ......................................................39
Installing and Configuring PerformaSure ..................................................40
Integrating PerformaSure in Your Environment.................................40
Running the Nexus.................................................................................41
Running the Workstation.......................................................................56
Starting PerformaSure FAQ ........................................................................64
Chapter 3 Recording a Session ........................................................65
Component or Full Detail? ....................................................................66
Component-Level Instrumentation ......................................................66
Full Detail Recording Level...................................................................69
Including and Excluding Classes ................................................................70
Choosing Classes for Instrumentation..................................................71
How the Nexus Categorizes Service Requests ..........................................73
Complete Requests.................................................................................73
Incomplete Requests ..............................................................................73
Fragmented Requests .............................................................................74
Service Request Sampling......................................................................76
4 PerformaSure: User’s Guide
Service Request Separation....................................................................77
Service Request Filtering........................................................................84
Session Time Slice Size ..........................................................................86
Configuration Overview ........................................................................88
Collecting Your First Session.................................................................92
Chapter 4 Analyzing Sessions.......................................................... 95
General Guidelines for Analyzing a Session ........................................96
Navigating the Project Window ..................................................................97
Selecting Another Project or Session ....................................................97
Customizing the Project Window .........................................................97
Customizing the Browsers................................................................... 102
Using the Time Control Panel............................................................ 102
Filtering Data in the Browsers ............................................................ 107
Using the Request Time Browser....................................................... 107
Using the SQL Browser....................................................................... 115
Using the Request Tree Browser........................................................ 119
Using the Metrics Browser.................................................................. 129
Using the Thresholds Browser............................................................ 132
5
Chapter 5 Isolating Performance Problems........................................ 141
A Strategy for Finding Performance Problems .......................................141
Part II: The PerformaSureWorkstation
Chapter 6 PerformaSure Workstation ............................................... 145
Defining Nexus Instances ....................................................................148
Navigating the Startup Window..........................................................150
Changing a Password ...........................................................................154
User Management ................................................................................154
Session Management............................................................................164
Chapter 7 PerformaSure Projects ................................................... 171
New Project Wizard—Summary ..........................................................172
New Project Wizard—Full Detail .........................................................174
Menus and Toolbar—Summary ...........................................................179
Menus and Toolbar—Full Detail..........................................................182
PerformaSure Projects FAQ ......................................................................193
Recording Control Window......................................................................197
Recording Control Window—Summary.............................................197
Recording Control Window—Full Detail............................................198
Recording Settings Dialog—Summary ................................................203
6 PerformaSure: User’s Guide
Recording Settings Dialog—Full Detail .............................................. 206
Advanced Sampling Dialog...................................................................... 221
Advanced Sampling Dialog—Summary ............................................. 221
Advanced Sampling Dialog—Full Detail............................................ 222
nexusctl—Summary .............................................................................. 226
Equivalent Recording Control Options .................................................. 241
Chapter 9 Edit Options Dialog.........................................................247
Chapter 10 Time Control Panel.........................................................253
Components in the Time Control Panel ................................................. 253
Data Availability Indicator ................................................................. 254
Link Browsers to Use Same Zone/Break Link Between Browsers . 257
Query Progress Bar and Cancel Query Button ................................ 257
Chapter 11 Live Data Updates ..........................................................259
Chapter 12 Agent Information ..........................................................261
Chapter 13 Request Time Browser.....................................................265
Request Time Browser Modes ........................................................... 267
Menus and Toolbar—Summary .......................................................... 267
Menus and Toolbar—Full Detail......................................................... 270
7
Time Control Panel ..............................................................................277
Request Time Browser Control Pane—Summary ..............................277
Request Time Browser Control Pane—Full Detail.............................278
Request Time Browser Graph Pane—Summary ................................283
Request Time Browser Graph Pane—Full Detail ...............................284
Request Time Browser Detail Pane ....................................................290
Request Time Browser FAQ .....................................................................294
Chapter 14 SQL Browser ................................................................ 295
Menus and Toolbar—Summary ...........................................................297
Menus and Toolbar—Full Detail..........................................................300
Time Control Panel ..............................................................................305
SQL Browser Control Pane—Summary..............................................305
SQL Browser Control Pane—Full Detail.............................................306
SQL Browser Graph Pane—Summary ................................................308
SQL Browser Graph Pane—Full Detail...............................................309
SQL Browser Detail Pane ....................................................................314
Chapter 15 Request Tree Browser .................................................... 319
Saving Browser Settings .......................................................................320
Menus and Toolbar—Summary ...........................................................321
Menus and Toolbar—Full Detail..........................................................325
Time Control Panel ..............................................................................337
Request Tree Browser Graph Pane—Summary .................................338
Request Tree Browser Graph Pane—Full Detail ................................341
Request Tree Browser Detail Pane .....................................................362
Creating a JProbe Launcher File.........................................................368
Request Tree Browser FAQ ......................................................................369
8 PerformaSure: User’s Guide
Chapter 16 Metrics Browser ............................................................371
Menus and Toolbar—Summary .......................................................... 373
Menus and Toolbar—Full Detail......................................................... 376
Time Control Panel ............................................................................. 380
Metrics Browser Navigation Pane...................................................... 381
Metrics Browser Graph Pane—Summary........................................... 382
Metrics Browser Graph Pane—Full Detail ......................................... 384
Chapter 17 Thresholds Browser........................................................391
Menus and Toolbar—Summary .......................................................... 393
Menus and Toolbar—Full Detail......................................................... 396
Time Control Panel ............................................................................. 401
Thresholds Browser Graph Pane—Summary .................................... 401
Thresholds Browser Graph Pane—Full Detail ................................... 402
Thresholds Browser Detail Pane ........................................................ 405
Using the Threshold Editor ................................................................ 408
Thresholds Browser FAQ ......................................................................... 410
Chapter 18 PerformaSure Reports .....................................................411
Generated Reports............................................................................... 412
Request Time Report .......................................................................... 418
Request Tree Report ........................................................................... 419
9
PerformaSure Reports FAQ ......................................................................421
Part III: Reference Appendices
Appendix A—Configuring PerformaSure............................... 425
The Configuration File Hierarchy ............................................................425
The Parameters in agent.config..............................................................426
The Parameters in nexus.config .............................................................430
Configuration Lookup Sequence ..............................................................436
The Parameters in log.config .................................................................437
Application Methods in Full Detail ....................................................445
Component Instrumentation ...............................................................445
The Parameters in instrumentation.config .............................................452
Appendix B—Metrics in PerformaSure ................................ 463
SQL Statement Metrics ........................................................................468
Application Server Metrics ..................................................................470
Metrics in PerformaSure FAQ ..................................................................476
Appendix C—Lexicon ..................................................... 477
Appendix D—Regular Expressions...................................... 489
How Regular Expressions are Scanned ...................................................492
10 PerformaSure: User’s Guide
Typical Regular Expression Patterns ................................................. 493
Using Regular Expressions in PerformaSure .................................... 496
Appendix E—License Credits and Trademarks ........................499
Apache Commons, BCEL .................................................................. 500
Index .........................................................................507
11
12 PerformaSure: User’s Guide
Preface
It’s a good bet that you are reading this User’s Guide because you are responsible for a Java™ Platform, Enterprise Edition application that must live up to its design standards regarding throughput. Although tracking down the source of Java EE performance problems isn’t 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 track service requests
through your application. (See “ How does PerformaSure Define a Service
” on page 28.) You’ll 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 importantly, you’ll be able to measure round trip service request times and see a request tree of all the methods involved. With
PerformaSure you have a performance analysis tool that collects information on the native platform, the Java runtime environment, and application servers that host the Java EE application. You can even monitor and drill right into the Java code for your applications using our companion products in the Performance
Management and Application Assurance suites, Foglight
®
Monitoring for J2EE
Applications and JProbe
®
.
About this Guide
This guide presents instructions for using PerformaSure in your pre-production or production environment.
13
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 Java EE technology as well as of the supported application servers listed in the Installation and
Configuration Guide
Conventions Used in this Guide
Typewriter
Font
Italic Text
Bold
Bold Italic
<value>
• 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. Example pathnames are provided in Unix path/name format.
• 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.
14 PerformaSure: User’s Guide
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.
Preface 15
Related Documentation
Release Notes
The Release Notes file is in HTML format, and is called
PerformaSure_ReleaseNotes.html. It includes information about new features in
PerformaSure 5.0 and about supported platforms and servers, notes about
PerformaSure, 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 or in the
PerformaSure Installation and Configuration Guide.
PerformaSure Installation and Configuration Guide
The Installation and Configuration Guide contains information about setting up and configuring PerformaSure to work with your application servers. All installation and configuration procedures are covered in the Installation and Configuration
Guide.
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 vendor’s manuals for these topics.
Setting up and configuring your application server software. However, additional instructions for configuring the servers to work with PerformaSure are provided.
Internal efficiency issues in Java and EJB environments.
16 PerformaSure: User’s Guide
About Quest Software, Inc.
Quest Software, Inc., a leading enterprise systems management vendor, delivers innovative products that help organizations get more performance and productivity from their applications, databases, Windows infrastructure and virtual environments. Through a deep expertise in IT operations and a continued focus on what works best, Quest helps more than 100,000 customers worldwide meet higher expectations for enterprise IT. Quest provides customers with client management as well as server and desktop virtualization solutions through its subsidiaries, ScriptLogic and Vizioncore.
Quest Software can be found in offices around the globe and at
www.quest.com
.
Contacting Quest Software
Web site [email protected]
Quest Software, Inc.
World Headquarters
5 Polaris Way
Aliso Viejo, CA 92656
USA
www.quest.com
Refer to our web site for regional and international office information.
Contacting Quest Support
Quest Support is available to customers who have a trial version of a Quest product or who have purchased a commercial version and have a valid maintenance contract. Quest Support provides around the clock coverage with
SupportLink, our web self-service. Visit SupportLink at: http://support.quest.com
.
■
■
■
From SupportLink, you can do the following:
Quickly find thousands of solutions (Knowledgebase articles/documents).
Download patches and upgrades.
Seek help from a Support engineer.
Preface 17
■ Log and update your case, and check its status.
View the Global Support Guide for a detailed explanation of support programs, online services, contact information, and policy and procedures.
The guide is available at:
http://support.quest.com/pdfs/Global Support
Guide.pdf
.
Suggested Reading
Java EE Patterns: http://developer.java.sun.com/developer/technicalArticles/J2EE/patterns/
Java EE Articles: http://developer.java.sun.com/developer/technicalArticles/ebeans/
EJB Tutorial: http://developer.java.sun.com/developer/onlineTraining/Beans/EJBTutorial/index.html
18 PerformaSure: User’s Guide
Part
Structure and
Workflow
I
Chapter 1
Introducing PerformaSure
Many Java EE system developers and production specialists need a Java EE analysis tool because their application is not meeting specific performance requirements. 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 Java EE environments and can also be used once an application is deployed to ensure that planned capacity goals are met. The rich user interface and reporting mechanism for PerformaSure 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.
Introducing PerformaSure
This section provides basic information about terminology related to
PerformaSure and its components. For a more detailed discussion about how
PerformaSure works, see “ Using PerformaSure ” on page 25.
21
Key PerformaSure Concepts and Terms
This section contains a short list of terms used to describe concepts and
components specific to PerformaSure. See “ Appendix C—Lexicon ” on page 477
for a more complete list of terms relating to load testing and performance analysis.
Term Definition
Browser
PerformaSure
Agent
PerformaSure
Nexus
The data collected in a session can be examined using a PerformaSure browser. PerformaSure has numerous browsers, each of which are designed to help you isolate different types of performance problems.
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. In this manual, “Workstation” is used as a synonym for “PerformaSure
Workstation.” service request Quest Software’s Tag and Follow
™
technology defines a service request as anything that enters the Agent-instrumented system, like a
HTTP-based request, an RMI call, a JMS call, a direct method call, or a defined interface. This gives you the ability to track an average request as it progresses through the various containers in your distributed application.
session A session refers to the performance data that is collected by
PerformaSure, which is stored in a session file.
Tag and Follow
™
Quest Software’s Tag and Follow technology instruments the Java EE environment so that service requests can be tracked from inception to completion.
time slice The granularity of data-collection. 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.
22 PerformaSure: User’s Guide
Background: Distributed Systems
Large business applications are usually spread across distributed systems. 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 server’s servlet container. The servlets and JSPs will likely call EJBs (collectively called the middle tier), which in turn retrieve data from a back-end database. In many cases the application servers are clustered, which means that there are many possible execution paths through the system.
Figure 1
Figure 1 A typical 3-tier system configuration
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. The ability that PerformaSure possesses to track a request through a distributed application helps you focus on the parts of the application that contribute most to performance loss from the end-user’s perspective.
■ Network traffic: the number of bytes transferred between machines.
Measurement of the traffic between machines may alert you to an excessive amount of data transfer, some of which may be unnecessary.
Introducing PerformaSure 23
■
■
■
Operating system metrics: includes 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 allows 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 2
24 PerformaSure: User’s Guide
Figure 2 A 3-tier system instrumented with PerformaSure
Using PerformaSure
What Does PerformaSure Do?
PerformaSure will help you to isolate performance problems in your transactional
Java EE e-business systems. Low-level, system-wide performance data that doesn’t focus on end-user response times isn’t enough; too much raw data 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 that requests and SQL statements spend in each machine in your system.
The call tree for a service request. Quest Software’s unique Tag and Follow technology is used to track the request-response cycle through a complete sequence of calls from the moment of a service request’s generation by a
URL, RMI call (RMI request), through data retrieval, and back to the enduser.
Introducing PerformaSure 25
Figure 3
26 PerformaSure: User’s Guide
Figure 3 Reconstruction of the true execution path using Tag and Follow technology
PerformaSure takes performance data and breaks it down by request so that you can look at this 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 solve a specific type of performance problem. PerformaSure uses Tag and Follow technology to mark service requests and to track 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 system’s activity organized by requests:
PerformaSure collects, correlates, and unifies data from any number of distributed servers using Tag and Follow technology.
Use browsers to find the context in which a problem occurred.
See a request decomposition for critical time periods and view the associated metrics. 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 lets you:
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 application server, or the underlying hardware
Call in the functional expert, knowing that the problem has been isolated.
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
®
, Oracle
®
Application Server,
Apache Tomcat, JBoss
®
Application Server, Oracle 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, the component instrumentation mode for
PerformaSure and the sampling capabilities that PerformaSure has keep overhead down while providing monitoring capability.
Introducing PerformaSure 27
What Do PerformaSure Browsers Do?
A PerformaSure project may have a number of browsers, each capable of providing insight into your system’s 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 Java EE 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 system’s 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 metric’s thresholds were exceeded.
How does PerformaSure Define a Service Request?
PerformaSure instruments application servers. The end-user sends application
HTTP requests, RMI, or JMS calls, as a starting point of a request for a 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 each request type.
28 PerformaSure: User’s Guide
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 Request Tree browser, which shows logical execution paths and timings.
The time control functionality in PerformaSure lets you isolate any period of time, allowing you to refine your view of service requests and their constituent events. Use the Zonar to find the time period where a problem occurred. See
“ Time Control Panel ” on page 253 for more information about the Zonar. 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.
Who Uses PerformaSure?
Lead architects, QA professionals, load testers, database administrators, production performance engineers, integration engineers, and functional testers all benefit from the ability that PerformaSure has 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
■
■
■
■
Application server and system administrators can:
Tune application server resources
Tune operating system parameters
Uncover situations where hardware limitations 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:
Introducing PerformaSure 29
■
■
■
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 Detect—Diagnose—Repair cycle.
■
■
■
■
Production performance engineers can:
Use component instrumentation to capture the overall system behavior
Adjust the sampling rate for PerformaSure 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 the AutoCapture feature of PerformaSure to automatically capture a session when Foglight
®
detects a suspicious event.
PerformaSure projects and reports encapsulate the troubleshooting process in sharable resources, allowing all groups within the performance and production teams to work together to resolve problems.
The Components of PerformaSure
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 they collect metrics from the host operating systems, Java virtual machines, and servers. For complete coverage, System Agents can be placed on the Web Server machines, the database machine and on the machines hosting your load generator.
30 PerformaSure: User’s Guide
What does an Agent do?
An Agent collects performance information from individual 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 Java EE application server metrics through vendor-provided 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 and network metrics, and
Service Request Agents, which track service request information and instrument application servers.
PerformaSure also features the X-Agent, which can be used to instrument standalone Java applications and Java application servers other than the application servers supported by PerformaSure. See “
Some Agents run inside an application’s 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 one of the application servers supported by PerformaSure, 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 Quest Software’s 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 thirdparty classes
The X-Agent needs to be configured by Quest Consulting. 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. See the Release Notes file (relnotes.html) for the Quest X-Agent support policy.
Introducing PerformaSure 31
32 PerformaSure: User’s Guide
What Do Agents Do?
■
■
■
■
■
Use Tag and Follow technology to track service requests
Application server metric collection
JVM metric collection
Network traffic metric collection
Operating system metric collection
How Do They Do It?
Byte code instrumentation
Quest Software has considerable experience with byte code instrumentation, beginning with our JProbe suite of products. The developers of PerformaSure have continued the practice by providing instrumentation hooks for application servers. Taking this approach enables you to monitor operation details that would otherwise be invisible.
Tag and Follow technology
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. It’s important to know the context in which the method executes, how many times it gets called, and what objects it calls. Tag and Follow technology functions by instrumenting application servers. This technology facilitates the detailed views furnished by the browsers in a PerformaSure
Workstation, which give you a true picture of your application’s operation.
Operating system APIs and Application Server Metric Interfaces
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
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.
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 may have multiple System and Service
Request Agents and one or more Workstations but only one PerformaSure Nexus.
What is the Nexus?
The PerformaSure Nexus is the hub of the PerformaSure architecture. 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 this information, and reply to any PerformaSure Workstation queries. In effect, the Nexus plays three 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 reconstructs the full application-level execution path by organizing the collected data into service requests using Tag and Follow technology. It receives data collected from the Agents, then combines and converts Agent-based event information into a cohesive information set—the service requests in a session—that can be queried and presented graphically by a PerformaSure
Workstation.
Introducing PerformaSure 33
34 PerformaSure: User’s Guide
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 unacceptable load on your system, especially when analyzing large sessions.
Figure 4
Data analysis mode
In data analysis mode, the Nexus communicates with one or more Workstations.
Session Storage
The data-store component of the Nexus collects data sent from the Agents and stores it. It also constructs replies to queries sent by Workstations. The data-store compresses the data and saves it to disk.
Nexus Performance
The Nexus is designed to handle a fairly intense volume of data. However, at times, it may be sent much more data than usual. To handle this potentially overwhelming amount of data, it informs the PerformaSure Agents exactly how much data it can accept. This may result in some requests being excluded from
monitoring. See “ Load Levels ” on page 75 for information about service request
levels for PerformaSure.
The Nexus Console
As shown in Figure 4, a console contains log messages associated with an active
Nexus. Messages are categorized according to their severity. A description of the
message types is given in “ Log Levels ” on page 442.
Figure 5
Figure 4 Messages in the Nexus console
PerformaSure Workstation
The Workstation connects to the Nexus to retrieve information for analysis. You can run as many Workstations as you are licensed for, allowing various team members to record and analyze sessions.
■
■
■
■
■
■
■
The Workstation is primarily a presentation tool, although you can use it to start and stop sessions and perform other management functions. The Workstation’s functions include:
■
Managing users (with the required permissions)
Managing PerformaSure Projects
Initiating a session and collecting data
Choosing which session to view
Setting thresholds for metric data
Using the browsers to track down performance problems
Generating reports in CSV, PDF, or XML format
Exporting a JProbe
®
launcher file
■ Launching Spotlight
®
in Quest Central. See
Interaction with Spotlight below
for details.
Introducing PerformaSure 35
Security
For more information about the Workstation, please see Section II of the User’s
Guide.
User Management
PerformaSure includes two default users, user and admin. Initially, new users can
only be added using the admin account. See “ User Management ” on page 154 for
information about permissions and roles, adding new users, removing registered users, and changing user information (such as the role that has been assigned to a user).
Figure 6
36 PerformaSure: User’s Guide
Figure 5 The tabs in the Workstation’s User Management window
Once users have been authenticated, they may use only the components and controls for which they have the required permissions (through the role that they
have been assigned). See “ Default Users ” on page 156 and “
Default Roles ” on page 158 for information about default users and roles included with
PerformaSure. See “ Selecting Permissions ” on page 160 for information about the
actions that each permission enables a user to perform.
Note: Any user whose role includes the Stop Recording permission may 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 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
®
in Quest Central from PerformaSure:
■
■
You can launch Spotlight
®
in Quest Central from the Tools menu of the
Project window or any browser (Tools > Performance Diagnostics) or from the toolbar of any browser.
You can also launch Spotlight
®
in Quest Central 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
®
in Quest Central from the context menu.
Note: Selecting the Spotlight
®
in Quest Central menu item launches the version of Spotlight
®
that is included with Quest Central. You must have
Quest Central installed to launch Spotlight
®
from PerformaSure.
Introducing PerformaSure 37
Interaction with Load-Testing Tools
PerformaSure has been created to work well with load-testing tools. Load-testing tools can be used to provide a model of system behavior and performance by emulating users on your system. Since PerformaSure measures loads but doesn’t generate any, it relies on you to stress the system in the way that you choose.
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 system—down 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 your system is behaving suspiciously.
38 PerformaSure: User’s Guide
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 the Installation and Configuration Guide, in this
chapter, and in the next two chapters (Recording a Session and Analyzing
1.
Installing PerformaSure on each target machine using the PerformaSure
Installer, which allows you to choose which specific components should be installed.
2.
Editing your server’s initialization file so that PerformaSure starts when the server is started. Sample scripts are provided for this purpose.
3.
Editing the file <performasure_home>/config/agent.config to specify the location of the PerformaSure Nexus.
4.
Starting the PerformaSure Nexus.
5.
Starting the application server or servers.
6.
Starting a PerformaSure Workstation. Beginning to collect data and—if you are using a load testing tool—using it to apply a test scenario.
7.
Setting up Projects and analyzing the performance data that you have collected in the PerformaSure browsers.
39
Installing and Configuring PerformaSure
You’ll find detailed installation and configuration instructions in the Installation
and Configuration Guide. Consult it for information on:
■ Supported platforms. PerformaSure instruments a variety of application servers. The complete list of supported servers and supported operating systems is found in the Installation and Configuration Guide’s.
■
■
Installing PerformaSure. You install PerformaSure on every machine that hosts a server that you want to instrument.
Configuring PerformaSure. Because PerformaSure works with different servers and different operating systems, it needs to be integrated with your environment.
After installing PerformaSure and configuring your servers to work with it, you are ready to measure your system’s performance.
The User’s Guide (this manual) assumes that you have already installed
PerformaSure and integrated it with your environment. This manual 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, 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 Configuration Guide before running PerformaSure.
40 PerformaSure: User’s Guide
Running PerformaSure
Running the Nexus
Since the Agents and Workstations need to communicate with the Nexus, it should normally be 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.
Caution: 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.
Note: If you run the Nexus on a multi-CPU machine, the number of processing threads is automatically adjusted for you.
Configuring the Nexus
■
■
Configuration options can be set for the Nexus through the file
<performasure_home>/config/nexus.config. For example, you can:
Specify a location for the sessions directory other than the default.
Change the default settings for the port that the Nexus uses to communicate with the Agents, the Workstations, and nexusctl.
■ Turn the Nexus System Agent on to benchmark Nexus performance.
See “ Configuring the Nexus ” on page 430 for more information.
Starting PerformaSure 41
42 PerformaSure: User’s Guide
Starting the Nexus
You can start the Nexus by opening a Unix shell or DOS command window, navigating to the bin subdirectory of the PerformaSure home directory, and invoking the Unix or Windows filename ( nexus.sh
or nexus.exe
).
To launch the Nexus console, click the Nexus icon in the PerformaSure program group in the Start menu (Windows) or use the installed link (Linux or Solaris).
Note: The Nexus will not start if another Nexus from the same version of
PerformaSure is already running.
The Nexus can also be run as a daemon on Unix or Linux, as a Windows service,
or in the background on Windows. See “ Starting the Nexus from a script ” and
Passing JVM options to the Nexus
Any option that you can provide to a Java 1.6 (or later) VM can be passed to the
Nexus when you start it from the command line by invoking the filename nexus.[exe|sh] from the bin directory or by issuing the command nexusctl start from the scripts directory.
You can also pass JVM options to the Nexus when it is started as a service; see
“ Starting the Nexus service with command-line parameters ” on page 44 for
details.
Starting the Nexus from a script
You can create a script to automatically launch the Nexus. PerformaSure also provides two scripts:
■
■
nexusctl is a utility script that can be used to launch the Nexus in the background on Windows or as a daemon on Unix or Linux. It is located in the
<performasure_home>/scripts directory. See “ Using nexusctl ” on page 46 for a
description of the parameters in nexusctl.
Note: 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.
quest-nexus-daemon.suse.sh is sample script that launches the Nexus as a daemon. This script is specific to SuSE Linux, but can be used as a template.
It is located in the <performasure_home>/scripts/unsupported directory.
Running the Nexus as a daemon
You can run the Nexus as a daemon on a Unix or Linux system. When you start the Nexus as a daemon, it will continue running when the user who started it logs out.
There are two ways to start the Nexus daemon from the command line:
■ Navigate to the <performasure_home>/bin directory and enter the following command: nexus daemon
■ Navigate to the <performasure_home>/scripts directory and enter the following command: nexusctl start
These commands start the Nexus and switch it into daemon mode. Control is then returned to the console, and the Nexus continues running in the background.
Troubleshooting: Only a user with the required permission can stop the
Nexus; see “ Shutdown Nexus ” on page 163 for details. However, no
additional permission checks are performed when a user attempts to stop the Nexus daemon. This means that, for example, a non-root user who has the default role Power User assigned to their PerformaSure user account will be able to stop a Nexus daemon started by a root user.
To prevent this from happening, use the controls in the User
Management window’s Edit Role dialog to modify the permissions included in the roles assigned to non-root users.
Running the Nexus as a service
You can install and run the Nexus as a Windows service. If you did not install the
Nexus as a service when you installed PerformaSure, then you can install it manually by opening a DOS command window, navigating to the
<performasure_home>\bin directory and entering the following command: nexus install-service
By default, this service’s startup type is set to automatic: it will start (or restart) when you reboot the machine on which it was installed and will continue to run when you log out.
Go to the Control Panel and use Services to view or configure the properties of the
PerformaSure Nexus service or to manually start or stop this service.
Starting PerformaSure 43
Starting the Nexus service with command-line parameters
You can include command-line parameters like -X , -D , -ea , -esa , -da , and -dsa when you start the Nexus service. The two ways to modify the Nexus service to run with command-line parameters are described below.
To add start parameters temporarily through Services:
1.
Install the Nexus service. See the Installation and Configuration Guide for details.
2.
Open Services. Select PerformaSure Nexus from the list of services and then select Action > Properties or right-click the service and select Properties.
The Properties dialog opens.
3.
Add the parameters to the Start Parameters text field and click OK.
Important: When you add start parameters through the Properties dialog in
Services, the PerformaSure Nexus service will run with those parameters the first time that you start the service only. These changes are not saved when you close the dialog. To make permanent changes, modify the ImagePath registry entry for the service by following the instructions below.
To add start parameters permanently by modifying the ImagePath entry:
1.
Open the Windows Registry Editor.
2.
Go to the following registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\PerformaSureNexus
3.
Open the ImagePath property.
4.
Add the startup parameters at the end of the current value. For example:
"C:\PerformaSure5.0\bin\Nexus.exe" start-service -Xms768m -Xmx768m
-Dquest.debug=1
44 PerformaSure: User’s Guide
Confirming that the Nexus Has Started
To confirm that the Nexus has started:
■
■
Look for the Nexus started message that the Nexus writes to the console or to the Unix shell or DOS command window in which you started the Nexus.
Look for the Nexus started message in the Nexus log file. By default, this file is created in the logs subdirectory of the PerformaSure home directory.
If you don’t see this message, check your installation to ensure all files are present.
Stopping the Nexus
The Nexus can be shut down by any user with the required permissions.
Permissions are set in the Workstation’s User Management window. See “ Managing
Roles ” on page 158 for details.
Depending on the mode in which you started the Nexus and the platform on which it is running, there may be several ways to stop the Nexus.
To stop the Nexus program or daemon:
1.
Open a DOS command window (to stop the Nexus program) or a Unix shell
(to stop the Nexus program or daemon).
2.
Navigate to the bin subdirectory of the PerformaSure home directory.
3.
Issue the following command: nexus stop
Note: On Unix or Linux systems, the same command ( nexus stop ) is used to stop a Nexus running as a program or as a daemon.
To stop the Nexus program from the Windows Start menu:
■ Click the Nexus Stop icon in the PerformaSure program group.
To stop and remove the Nexus service:
1.
Open a DOS command window.
2.
Navigate to <performasure_home>\bin.
3.
Issue the following command: nexus remove-service
To stop the Nexus service:
1.
Access the Services administrative tool from the Control Panel.
2.
Select the PerformaSure Nexus service from the list.
3.
Click the Stop Service button in the toolbar or right-click on the service and select Stop from the context menu that appears.
To stop the Nexus daemon or a Nexus running in the background on Windows:
1.
Open a DOS command window or a Unix shell.
2.
Navigate to the scripts subdirectory of the PerformaSure home directory.
Starting PerformaSure 45
3.
Issue the following command: nexusctl stop
Troubleshooting: If there is no valid license file for PerformaSure installed, the nexusctl stop command will fail. This is because nexusctl needs to connect to the Nexus in order to shut it down. If there is no valid license file, the Nexus will not accept connections.
Using nexusctl
The command-line utility nexusctl allows you to perform various actions, such as starting or stopping the Nexus, displaying a list of connections to the Nexus, and starting and stopping session recording.
Tip: By embedding a call to nexusctl.sh or nexusctl.cmd in a command file within a cron job or in Task Scheduler, you can cause PerformaSure to collect session data automatically at some scheduled time.
To control its mode of operation, nexusctl accepts a number of command options.
The options for nexusctl are listed below.
Note: In this section, no distinction is made between the Windows and Unix versions of this script (nexusctl.cmd and nexusctl.sh).
Note: Java 1.6 is required to run nexusctl.
Basic options
■
■ nexusctl start Starts the Nexus in the background (Windows) or as a daemon (Unix or Linux systems).
• You can specify -X or -D parameters.
Example usage: nexusctl start -Xms768m -Xmx768m -Dquest.debug=1 nexusctl stop Properly shuts down the Nexus. The three optional parameters for nexusctl stop
46 PerformaSure: User’s Guide
Nexus version options
■ nexusctl version Retrieves the version number of the Nexus in the form of a string, such as 5.0
. There are four optional parameters for nexusctl version :
• -user Your PerformaSure login username.
• -pwd Your PerformaSure login password (if you have set one—otherwise omit this parameter).
• -r NEXUSURI Retrieves the version number of a remote Nexus or a local
Nexus that does not use the default port. For example: nexusctl version -r your.remote.host.com:42705
• -b Retrieves the build number of a local Nexus in the form of a string, such as PAS_430-20060304-0506 .
Recording options
See “ Recording Options ” on page 229 for a list of nexusctl’s recording options.
Showing connections to the Nexus
■
■ nexusctl show-connections Shows all connections to the Nexus. This command lists all connected users (for example, nexusctl or the Workstations) and PerformaSure Agents in tabular form in the shell or DOS command window. The tables in which the enabled and disabled Agents are listed include entries indicating whether the Agents are connected or disconnected.
nexusctl show-connections-xml Shows all connections to the Nexus. This command lists all connected users (for example, nexusctl or the Workstations) and all known, connected, included, and excluded PerformaSure Agents in
XML format in the shell or DOS command window.
The three optional parameters for nexusctl show-connections and nexusctl show-connections-xml
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. The three optional parameters for nexusctl reset-agent-list are described below.
Optional parameters for nexusctl stop, show-connections, show-connections-xml, and reset-agent-list
■ -user Your PerformaSure login username.
Starting PerformaSure 47
■
■
-pwd Your PerformaSure login password (if you have set one—otherwise omit this parameter).
-r Sets the connection URI for the Nexus when it is on a different machine than the one on which the nexusctl script is located or for a local Nexus that does not use the default port.
Important: The nexusctl script must not be moved from the directory in which it was installed.
Example usages: nexusctl stop -user lisa -pwd oboe789 -r your.remote.host.com:42705 nexusctl show-connections -user lisa -pwd oboe789 -r your.remote.host.com:42705 nexusctl reset-agent-list -user lisa -pwd oboe789 -r your.remote.host.com:42705
Running Agents
48 PerformaSure: User’s Guide
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 51.
System Agents
System Agents collect operating system and network traffic metrics. System
Agents must therefore be run by a user that has sufficient permissions on system resources, including read/write permissions on the network devices for that machine. See the Installation and Configuration Guide for instructions on setting permissions on the supported platforms.
When a Service Request Agent for an application server starts, it connects to the
Nexus. Once the connection is established, the Service Request Agent starts the
System Agent only if both CanLaunchSystemAgent = true in
<performasure_home>/config/agent.config, and it is instructed to do so by the Nexus.
If there is no Service Request Agent installed on the machine (the Nexus machine, RDBMS servers, load testing machines), or if the Service Request
Agent is not running with appropriate user permissions, the System Agent must be started manually.
Note: On AIX, ensure that the fileset bos.net.tcp.server is installed. The package is available on the AIX install disks and is required by PerformaSure to capture network traffic.
Starting a System Agent manually
To run System Agents on servers where the Service Request Agent runs as a user that does not have proper permissions to collect operating system and network metrics, or on database machines and other machines that ordinarily don’t run
Service Request Agents:
■ Start the Agent on each machine using systemagent in the bin directory of your
PerformaSure installation or from installed shortcuts for the System Agent for your platform, then start the Service Request Agent. If there is already a
System Agent running on the host machine, a separate Agent will not be launched. The Service Request Agent will not attempt to start another System
Agent if you have started one manually. If you are starting the System Agent manually because the Service Request Agent does not have the proper permissions, set CanLaunchSystemAgent = false in
<performasure_home>/config/agent.config to prevent the Service Request Agent from attempting to restart the System Agent if it stops for some reason.
Important: On AIX, System Agents must be run as root. This is because only the root account can have access to the network devices and to the operating system metrics. If you attempt to run a
System Agent without root permissions, it will quit with an error message and no CPU or Network metrics will be collected.
Running a System Agent as a daemon
You can run a System Agent as a daemon on a Unix or Linux system. When you start a System Agent as a daemon, it will continue running when the user who started it logs out.
To start a System Agent daemon from the command line, navigate to the
<performasure_home>/bin directory and enter the following command: systemagent daemon
This command starts the System Agent and switches it into daemon mode.
Control is then returned to the console, and the System Agent continues running in the background.
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 and for information about adding or removing the System Agent service after you have installed
Starting PerformaSure 49
PerformaSure. By default, this service’s startup type is set to automatic: it will start
(or restart) when you reboot the machine on which it was installed and will continue to run when you log out.
Go to the Control Panel and use Services to configure or view the properties of the
Systemagent service or to manually start or stop this service.
Starting the System Agent service with command-line parameters
You can include command-line parameters like -X , -D , -ea , -esa , -da , and -dsa when you run the PerformaSure Systemagent service. The two ways to modify the service to run with command-line parameters are described below.
To add start parameters temporarily through Services:
1.
Install the System Agent service. See the Installation and Configuration Guide for details.
2.
Open Services. Select PerformaSure Systemagent from the list of services and then select Action > Properties or right-click the service and select Properties.
The Properties dialog opens.
3.
Add the parameters to the Start Parameters text field and click OK.
Important: When you add start parameters through the Properties dialog in
Services, the PerformaSure Systemagent service will run with those parameters the first time that you start the service only. These changes are not saved when you close the dialog. To make permanent changes, modify the ImagePath registry entry for the service by following the instructions below.
To add start parameters permanently by modifying the ImagePath entry:
1.
Install the System Agent service. See the Installation and Configuration Guide for details.
2.
Modify the ImagePath registry entry by appending parameters to the value.
For example:
"C:\PerformaSure5.0\bin\Systemagent.exe" start-service -Xms768m
-Xmx768m -Dquest.debug=1
50 PerformaSure: User’s Guide
Service Request Agents
Service Request Agents track service request information within your Java EE architecture. The notion of a service request as a unit of work is extended in
PerformaSure to include entities (Servlets, JSPs, RMIs) that enter the system and make their way through other tiers to finally return results.
■
■
■
■
■
The following Service Request Agents are included with PerformaSure:
WebLogic Server Agent
WebSphere Server Agent
Oracle Application Server Agent
JBoss Agent
Tomcat Agent
Service Request Agents run when the server they are monitoring starts. By default, when a Service Request Agent starts, it also attempts to start a System
Agent in a separate process on that machine if it is instructed to do so by the
Nexus. If there is already a System Agent running, a second Agent will not be started. To disable the launching of a System Agent, set the value of
CanLaunchSystemAgent configuration option to false in the
<performasure_home>/config/agent.config file.
See “ Agent Startup ” below for more information about how Service Request
Agents are launched.
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 10g with
PerformaSure.
• Using a custom startup script for WebLogic, which automatically starts a
WebLogic Service Request Agent.
• A WebSphere Application Server Service Request Agent is launched when you start a WebSphere server that has been manually integrated with
PerformaSure.
• On your load simulator or RDBMS machines, the stand-alone System
Agents are started using an executable—systemagent (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
<performasure_home>/config/nexus.config to enable a System Agent on the
Nexus machine. See the note in nexus.config for instructions.
• All application server machines require System Agents; the Nexus will automatically tell the Service Request Agents on each of these machines to
Starting PerformaSure 51
52 PerformaSure: User’s Guide start a System Agent. It is recommended that you place System Agents on your web server machines and load generator machine as well.
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 (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, Application Server Agents can be configured to ignore the Nexus’ command to start a
System Agent. See the Installation and Configuration Guide.
2.
The Agent loads the file <performasure_home>/config/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.
3.
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 and in the Agent log files to see what went wrong. By default, these files are located in <performasure_home>/logs.
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.
Important: The PerformaSure Preinstrumentor Agent also attempts to connect to the Nexus to load its configuration settings from
<performasure_home>/config/client/instrumentation.config and from the appropriate configuration file in
<performasure_home>/config/client/agent-type. However, if its initial attempt to connect to the Nexus fails, it will not retry the connection, but will use cached or default configuration files.
The locations of these files are described in Step 3 and Step 4 of
“ Configuration Lookup Sequence ” on page 436.
4.
The Nexus checks the license number for the Agent and responds with the message, “ Authentication approved ”.
5.
The Agent sends a message indicating that it acknowledges the Nexus’ authentication approval.
6.
The Agent asks the Nexus to send the configuration file appropriate for the type of Agent (for example, the WebLogic 8.1 Agent requests
<performasure_home>/config/client/agent-type/weblogic-81.config) and waits for a reply.
7.
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.
8.
The Agent asks the Nexus to send the file
<performasure_home>/config/client/instrumentation.config, which determines how
Java applications are instrumented. The Agent also saves this locally in
<performasure_home>/state/<userID>/config-cache.
Note: 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.
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 436 for more information.
Agent Initialization
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='8.1'.”
The Nexus scans the files in <performasure_home>/config/config/client/agent-type/ for a match to this information. Using the same example, the Nexus would match this information with <performasure_home>/config/client/agent-type/weblogic-81.config.
Naming Agents
Each Agent is given a unique default name. This is the case even when there are multiple instances of an application server running simultaneously on the same
Starting PerformaSure 53
machine, and therefore multiple Agents. You can change an Agent’s name by using the AgentName element in <performasure_home>/config/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.
Confirming that an Agent Has Started
■
■
■
■
In the log messages: look at the Agent machine’s console or in the Agent’s log file for a message indicating that a connection to the Nexus has been established. By default, the log file is created in the logs subdirectory of the
PerformaSure home directory on the Agent machine.
Agent startup procedures are different for different servers, but since the
Agent starts before the server, once the server confirms that it is running, the
Agent should also be running.
Viewing Agent Status Information
You can view the status of PerformaSure Agents (enabled or disabled, connected or disconnected) and information about Agents (ID, name, and type) in the
Workstation’s Recording Control window or by issuing the nexusctl command showconnections .
Tip: Verify the status of Agents before you start recording a session, since you cannot change which Agents are enabled or disabled while session recording is in progress.
54 PerformaSure: User’s Guide
Note: By default, Agents that connect to the Nexus for the first time during recording are enabled.
To ensure that the desired Agents are operating—Workstation instructions:
1.
Before you start recording, open the Recording Control window and check the list of Agents.
2.
Ensure that a check mark ( ) appears in the Enabled column and that the
State column lists Connected in the row corresponding to each desired Agent.
If you would like to enable or disable certain Agents:
1.
Click on the Configure... button in the Recording Control window. The
Recording Settings dialog opens.
2.
Select the recording settings configuration that you would like to use from the
Settings drop-down menu, or create a new configuration. See “ Configuring
Recording Settings ” on page 207 for details.
3.
Select the Agents tab.
4.
Use the controls in this tab to enable or disable specific Agents. See “ Agents
Tab ” on page 220 for details.
5.
Click Apply to save the selections in this tab as part of the recording settings configuration.
To ensure that the desired Agents are operating—nexusctl instructions:
Open a Unix shell or DOS command window, navigate to the
<PerformaSure_home>/scripts directory, and issue the command: nexusctl.[cmd|sh] show-connections
If you would like to enable or disable certain Agents, use the -ae or -ad parameter with the nexusctl command start-recording
Parameters ” on page 231 for details.
Tip: If you have PerformaSure installed on several servers in a cluster, use the Recording Setting dialog or nexusctl view the status of Agents and enable or disable certain Agents. By doing so, you can collect performance information selectively.
Stopping Agents
Service Request Agents
After integrating PerformaSure with your application servers, Service Request
Agents are started automatically when the servers are started. They are stopped when the servers are stopped.
Note that you do not have to stop an Agent (and its associated application server)
disabling specific Agents. An Agent that has been disabled remains connected to
Starting PerformaSure 55
the Nexus, but does not collect any data. It will be re-enabled at the end of the session.
System Agents
There are different ways to stop a System Agent, depending on the mode in which it is running.
Note: A System Agent that was started by a Service Request Agent is stopped automatically when the Service Request Agent is stopped.
To stop a manually-started System Agent:
Type Ctrl-C in its console window to stop a manually-started System Agent running in a console.
To stop the System Agent daemon:
1.
Open a Unix shell.
2.
Navigate to the bin subdirectory of the PerformaSure home directory.
3.
Issue the following command: systemagent stop
To stop the System Agent service:
1.
Access the Services administrative tool from the Control Panel.
2.
Select the PerformaSure System Agent service from the list.
3.
Click the Stop Service button in the toolbar or right-click on the service and select Stop from the context menu that appears.
Running the Workstation
56 PerformaSure: User’s Guide
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. The job of
PerformaSure 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 the PerformaSure browsers are: Metrics, 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 101.
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 the functionality of
PerformaSure. 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 <performasure_home>/config/nexus.config, an operation that requires restarting the Nexus and its Agents.
Using nexusctl.cmd or nexusctl.sh to perform tasks like starting the Nexus in the background (on Windows) or as a daemon (on Unix or Linux systems), retrieving the build and version number of the Nexus, and showing
connections to the Nexus. See “ Using nexusctl ” on page 46 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 Dialog—Quick Start ” on page 62 for more information.
Logging in to PerformaSure, so you can have access to the rest of its functions.
See “ Logging In—Quick Start ” on page 58 for instructions on how to log in.
■
■
Managing your account or that of other users (if you have the required
permissions). See “ User Management ” on page 154 for details.
Recording a session. See “ Recording a Session ” on page 65 for more
information.
■
■
Viewing the status of a session. See “ Status, Elapsed Time, and Duration ” on page 200 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 95 for more
information.
Starting PerformaSure 57
■ Launching Spotlight
®
for Quest Central. See “ Spotlight Integration ” on page
Starting the Workstation
The recommended way of starting the Workstation is by clicking its icon in the
PerformaSure Start menu group (Windows) or by using the installed link (Linux or Solaris).
Logging In—Quick 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 7
58 PerformaSure: User’s Guide
Figure 6 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.
Important: The user name admin and the password admin can initially be used to log in to the Workstation with administrator privileges and add additional user accounts through the User Management window. Quest Software recommends that you promptly change the password for the admin account to something other
than its installed value. See “ Changing a Password ” on page 154
for more information.
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 8
Figure 7 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 Dialog—Quick Start ” on page 62 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 147 for a description of login
errors that you might encounter.
Note: You can only add user names to the login database if you have the required permissions.
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.
Starting PerformaSure 59
Figure 9
Figure 8 PerformaSure Startup window showing the Tools menu choices
Important: Depending on the permissions that are included in the role you have been assigned, certain options may not be available from
the Startup window. See “ User Management ” on page 154 for
information about roles and permissions.
Record New Session
Select this radio button and click OK to open the Recording Control window. See
“ Recording Control Window ” on page 197 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.
60 PerformaSure: User’s Guide
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 10
Figure 9 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 10.
See “ The Project Window ” on page 178 for more details.
Figure 11
Figure 10 The Project window
The main part of the project window is described in “ Browsers Area ” on page
Tools menu
The Tools menu is located at the bottom of the Startup window (see Figure 8).
This menu contains the following options:
■
■
Session Management... Opens a dialog where you can edit, or delete a
session. See “ Session Management ” on page 164 for details.
Change Password... Opens a dialog where users can change their own
passwords. See “ Changing a Password ” on page 154 for details.
Starting PerformaSure 61
■ User Management... Opens a window where you can create and modify user roles, add new users, and assign passwords and roles to users. Initially, only
To exit PerformaSure without selecting any of these options, click Exit. To log out of the Workstation and return to the Login window, click Logout. For more
information about selecting a session or an existing project, see “ Open Session in
” on page 151 and “ Open Existing Project ” on page 152.
Define Nexus Dialog—Quick 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 8). See “ Defining Nexus Instances ” on page 148 for more details.
Figure 12
Figure 11 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 13
62 PerformaSure: User’s Guide
Figure 12 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 14
Figure 13 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 145.
Starting PerformaSure 63
Starting PerformaSure FAQ
When I try to start the PerformaSure Nexus service from the command line, an error dialog that says “StartServiceCtrlDispatcher failed” appears. Why does this happen?
This dialog appears if you attempt to start the PerformaSure Nexus service but it is not currently installed. If you see this dialog, go to the Control Panel and use
Services to ensure that the Nexus is installed as a service. See the Installation and
Configuration Guide for instructions on installing this service.
When I try to start the Nexus, the following message appears in the Nexus console:
FATAL Unable to start Connection Listener; Location: Host: *, Port: 41705.
What does this error message mean?
This error message appears if you attempt to start the Nexus when it is already running and listening for connections on port 41705.
64 PerformaSure: User’s Guide
Chapter 3
Recording a Session
This chapter offers suggestions about planning a session based on the Java EE performance investigation strategy of Detect, Diagnose, Resolve. It discusses the recording levels in PerformaSure 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
PerformaSure session—the diagnosis phase. Resolution of the problem can take many forms depending on its source.
Recording Levels
There is no upper limit to the number of classes and methods in a Java EE application. Request trees can, and frequently do, contain thousands of nodes.
This information may be invaluable during the QA phase of product development, but collecting all of it places a heavy load on the system. For production systems, a less intrusive solution is required.
Fortunately, Java EE 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 collected—and 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
defines as its ‘component-only view of Java EE resources.’
65
Alternatively, at full detail, 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. PerformaSure can extend the component-level
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 overhead associated with the Tag and Follow
™ technology 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 methods—by recording at the component level or by extending the component level to include custom components—ensures that the number of instrumented points is limited.
Component detail is the default recording level for PerformaSure. It’s 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 set the recording level in the Sampling tab of the Recording Settings dialog
or by using the command-line utility nexusctl. See “ Standard Component-Level
” on page 66 and “ Full Detail Recording Level ” on page 69 for
more information.
Component-Level Instrumentation
66 PerformaSure: User’s Guide
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
Workstation’s Recording Settings dialog and saving this setting as part of a recording settings configuration or by entering the nexusctl command nexusctl startrecording -c .
To set the recording level to component detail—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 its icon in the Project window’s toolbar or by selecting Tools > Recording Control Window from the menu bar of the Project window or any browser.
2.
Click the Configure... button in the Recording Control window. The Recording
Settings dialog will appear.
3.
Select the recording settings configuration that you would like to use from the
Settings drop-down menu, or create a new configuration. See “ Configuring
Recording Settings ” on page 207 for details.
4.
Select the Sampling tab.
5.
Select Component Detail Recording Level in this tab.
6.
Click Apply to save this setting as part of the recording settings configuration.
Note: The Component Detail Recording Level radio button is automatically selected as part of the Default Settings recording
configuration. See “ Default Settings ” on page 206 for more information
about this configuration.
To set the recording level to component detail—nexusctl 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 Java EE components that are included when you record a session at the component detail level.
Note: A set of common custom components is pre-defined in
instrumentation.config. See the instructions in this file for details.
Recording a Session 67
68 PerformaSure: User’s Guide
Tip: Use custom component instrumentation when your distributed application uses third-party technologies that aren’t part of the default list of items included with PerformaSure, but which you want to be included in the component-only view. You’ll only have to edit
CustomComponents once to include these technologies.
To configure custom components—Workstation instructions:
1.
2.
Make a backup copy of <performasure_home>/config/client/instrumentation.config.
3.
Open instrumentation.config in a text editor and scroll to the bottom of the section on custom components.
4.
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",
When PerformaSure matches method names to the methods in a list, it interprets them as custom components. For more information about using
regular expressions, see “ Appendix D—Regular Expressions ” on page 489.
5.
After editing and saving 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 using the recording settings configuration for which you set the recording level to component detail. PerformaSure will instrument entry
points into the custom components that you specified. See “ Collecting Your First
Session ” on page 92 for instructions on using the Workstation to record a new
session.
To configure custom components—nexusctl instructions:
1.
Follow steps 2—5 above.
2.
When you are ready to record a new session, enter the command nexusctl start-recording -c .
3.
When you’ve finished recording the session, you can view the methods in the
Request Tree browser.
See “ Customizing Component-Level Data Collection ” on page 456 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 true 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 457
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 70
and “ UserClasses ” on page 452 for more information.
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 detail—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 its icon in the Project window’s toolbar or by selecting Tools > Recording Control Window from the menu bar of the Project window or any browser.
2.
Click the Configure... button in the Recording Control window. The Recording
Settings dialog will appear.
3.
Select the recording settings configuration that you would like to use from the
Settings drop-down menu, or create a new configuration. See “ Configuring
Recording Settings ” on page 207 for details.
Recording a Session 69
4.
Select the Sampling tab.
5.
Select Full Detail Recording Level in this tab.
6.
Click Apply to save this setting as part of the recording settings configuration.
To set the recording level to full detail—nexusctl 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; in the Request Tree browser, the terminal node in the chain is marked with the recursion symbol ( ) to indicate that there are more calls that are not shown.
Figure 15
Figure 14 A recursive call path
You can control the number of recursive calls that are shown in the request tree by editing RecursionLimit in
<performasure_home>/config/client/instrumentation.config and then saving this file.
When RecursionLimit is set to its default setting ( 5 ), only the method and its first five recursive calls are shown. To obtain data on each of the recursive calls separately, set RecursionLimit to a number larger than the expected recursion depth. To see only the first method call but none of the recursive calls, set
RecursionLimit to 0
. See “ Setting the Recursion Limit ” on page 458 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.
70 PerformaSure: User’s Guide
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. In fact, 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 to include for full instrumentation by
PerformaSure or to exclude 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.
Make a backup copy of <performasure_home>/config/client/instrumentation.config.
2.
Open instrumentation.config in a text editor and scroll to the bottom of the section on User Classes.
3.
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”
);
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. For more information
about using regular expressions, see “ Appendix D—Regular Expressions ” on page 489.
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.
Recording a Session 71
4.
After editing and saving instrumentation.config, ensure that this file is read by restarting the Agents and the instrumented application servers.
To exclude a class or package from instrumentation:
1.
Make a backup copy of <performasure_home>/config/client/instrumentation.config.
2.
Open instrumentation.config in a text editor and scroll to the bottom of the section on User Classes.
3.
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.”
);
In this example, the class “ com.globex.plan.DominateWorld
” would be excluded, as well as all classes in the package “ com.globex.scheme
”. For
more information about using regular expressions, see “ Appendix D—Regular
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.
4.
After editing and saving instrumentation.config, ensure that this file is read by restarting the Agents and the instrumented application servers.
Including and Excluding Multiple Classes
72 PerformaSure: User’s Guide
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.
Make a backup copy of <performasure_home>/config/client/instrumentation.config.
2.
Open instrumentation.config in a text editor and scroll to the bottom of the section on User Classes.
3.
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 = ClassList( include “com.globex.plan.DominateWorld”, exclude /(\.|^)globex\./, include “com.globex.pocket.Sugar”
);
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. For more information about using regular expressions, see
“ Appendix D—Regular Expressions ” on page 489.
4.
After editing and saving instrumentation.config, ensure that this file is read by restarting the Agents and the instrumented application servers.
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
PerformaSure also tracks incomplete requests. There are two reasons why incomplete requests may occur:
■ A request may not complete within the time during which the session was recorded. An incomplete request can occur when the session ends before the response to the request is recorded.
Recording a Session 73
■ A request may not complete within a specified time, called the incomplete
request timeout period. An incomplete request can occur when the timeout period ends before the request completes. The duration of this period can be
Tip: When system throughput is poor, keeping track of incomplete requests helps you to determine which component is to blame.
Fragmented Requests
It is also possible to have fragmented requests. Fragmented requests are service requests whose parts become cut off from each other because some intermediate process fails to complete. 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 value of
CommitTimeout (set in <performasure_home>/config/nexus.config) is too short. A WARN message appears in the log file when fragmented requests
are detected. See “ Service Request Timeout Thresholds ” below for
details.
74 PerformaSure: User’s Guide
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 messages associated with tracking requests using Tag and Follow 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 track fewer service requests using Tag and Follow technology in the next sampling interval.
If the Nexus can’t keep up even after entering its lowest sampling regime, it sends messages to its Agents instructing them to stop tracking requests using Tag and
Follow 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 fullysampled 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
Recording a Session 75
Service Request Sampling
In performance tests of long duration, or very high load, there is little need for every service request to be tracked using Tag and Follow; 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 application’s 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 its icon in the Project window’s toolbar or by selecting Tools > Recording Control Window from the menu bar of the Project window or any browser.
2.
Click the Configure... button in the Recording Control window. The Recording
Settings dialog will appear.
76 PerformaSure: User’s Guide 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.
3.
Select the recording settings configuration that you would like to use from the
Settings drop-down menu, or create a new configuration. See “ Configuring
Recording Settings ” on page 207 for details.
4.
Select the Sampling tab.
5.
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.
6.
Review the rest of the settings in this tab (such as the recording level) and, if they are what you want, click OK to save your selections as part of the recording settings configuration and close the dialog. The Recording Control window will remain open, allowing you to begin recording when you choose by clicking the Start Recording button.
Note: 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 233 for more information.
Setting Sampling Weights
In sampling mode, PerformaSure uses Tag and Follow technology to track 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 221 for more information.
Service Request Separation
By default, PerformaSure groups all requests that have the same base URL into a single request and provides aggregate statistics for it; for example, they are displayed as a single request tree in the Request Tree browser’s graph pane.
PerformaSure allows you to use separators to separate requests with the same base URL into distinct request types based on the requests’ GET and POST parameters, cookies, or HTTP headers. By allowing service request separation,
PerformaSure gives you the option of treating each parameter as if it were a separate request.
Separating Service Requests
You can apply a request separation pattern to URLs passed to instrumented servers. Separation occurs if any of the parameters in a request match the request
Recording a Session 77
78 PerformaSure: User’s Guide separation rule for that URL, meaning that a request may be separated based on more than one parameter. For example, if the separation rule contains the parameters USER=BOB,LOGIN then any request with either USER=BOB , or LOGIN , or both as parameters will be separated from requests with the same base URL that do not contain one or both of these parameters.
You can configure request separation based on one or more GET or POST parameter, cookie, or HTTP header names or name-value pairs. Request separation will occur as follows based on the information that you provide in the separator:
■ Name only: If you provide only a GET or POST parameter, cookie, or
HTTP header name, requests will be separated based on that name: all URLs that have the same value for that GET or POST parameter, cookie, or HTTP header name will be considered to be requests of the same type, but different from URLs that have a different value for that parameter name. See
“ Separating Requests Based on GET or POST Parameters ” below or
“ Separating Requests Based on Cookies ” on page 80 for examples
■ Name and value: If you provide a GET or POST parameter, cookie, or
HTTP header name-value pair, requests will be separated based on both the name and the value: only URLs that contain that name-value pair in the GET or POST parameter, cookie, or HTTP header will be considered to be
requests of the same type. See “ Separating Requests Based on a Name-Value
Pair ” on page 83 for an example.
It is possible for GET and POST parameters, cookies, and HTTP headers to have the same name or name and value. When you specify a name or name-value pair as the parameter on which requests are separated, all GET and POST parameters, cookies, and HTTP headers with that name or name-value pair are used for separating requests.
PerformaSure appends the parameters that are used for request separation to the separated URL. Parameters are always appended in the same order, even to requests with different base URLs. For example, if two requests with different base URLs are separated based on the same three parameters, these parameters will be appended in the same order to each separated URL. Name-value pairs are appended to each URL the same number of times that they appear in a separated request’s GET and POST parameters, cookies, and HTTP headers.
The sections below describe the different options for separating requests and provide example scenarios in which service request separation can help isolate
performance problems. See “ Configuring Request Separation ” on page 84 for
instructions on configuring request separation in the Workstation or using nexusctl.
Separating Requests Based on GET or POST Parameters
Standard Java EE practice includes the case of a single JSP or Servlet that contains arguments which it forwards to the appropriate processor. PerformaSure
would normally group all calls to this JSP or Servlet as a single request. 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.
Example:
There is 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.example.com/littlebusiness.jsp?cmd="login"
http://www.example.com/littlebusiness.jsp?cmd="query"
http://www.example.com/littlebusiness.jsp?cmd="order"
Because the base URL is the same, PerformaSure would, by default, consider these as part of the same request and amalgamate the information collected for all three URLs into one graph in its Request Tree browser. However, because the three
URLs perform different tasks, it makes sense to regard them as three separate requests.
The parameter string of each URL described above contains a name-value pair such as cmd="login" . By specifying cmd in the Parameters column of the table in the Separators tab (as shown below), all URLs that have the same value for cmd (for example, "login" ) will be considered to be requests of the same type, but different from URLs that have a cmd parameter with a different value, such as
"query" or "order" .
Figure 16
Figure 15 Configuring request separation on the query parameter cmd
See “ Separators Tab ” on page 213 for more information about using the controls
in the Recording Settings dialog’s Separators tab.
Recording a Session 79
80 PerformaSure: User’s Guide
Separators can also be configured when recording a session using nexusctl. See
“ Request Separation Parameters ” on page 234 for more information.
Important: POST parameter separation is only support for requests that use Content-Type: x-www-form-urlencoded . This means that, when performing POST parameter request separation,
PerformaSure will ignore requests that use Content-Type: multipart/form-data .
Separating Requests Based on Cookies
There are situations when it is useful to separate requests based on cookies, such as when you would like to track the requests made by users who are experiencing long response times.
Example:
A company is receiving complaints from customers that when they log in to the company’s web application, everything seems slower, but when they browse the company’s site without logging in, it is far more responsive.
To track down the source of this performance problem, the company’s performance engineer, Jane, wants to view requests to the same URL as separate requests depending on whether or not a user is logged in. Fortunately, there is a way to do this. The web application stores user login information in a cookie
(called LoginName ), so she decides to configure request separation based on this cookie name.
In the Sampling tab of the Recording Settings dialog, she adds a new separator that uses the URL expression .* and the cookie name LoginName , and specifies
RegEx as the expression type (as shown below). Now, when she records a session, requests for the same URL from users who are logged in will not be aggregated with those from users who are not logged in. When she views the session in the Request Time and Request Tree browsers, for example, the two types of requests will be displayed separately, making it easier for her to identify the problem with the logged-in users’ requests.
Figure 17
Figure 16 Configuring request separation on the cookie name LoginName
See “ Separators Tab ” on page 213 for more information about using the controls
in the Recording Settings dialog’s Separators tab.
Separators can also be configured when recording a session using nexusctl. See
“ Request Separation Parameters ” on page 234 for more information.
Important: PerformaSure does not collect certain cookie attributes and reserved cookie names.
The following cookie attributes are not collected:
• Comment
• CommentURL
• Discard
• Domain
• Expires
• Max-Age
• Path
• Post
• Secure
• Version
All cookie names that begin with $ are reserved and will be ignored by PerformaSure because they should only be used by web servers and user-agents.
Recording a Session 81
82 PerformaSure: User’s Guide
Separating Requests Based on HTTP Headers
Separating requests based on HTTP headers can help you identify the source of a performance problem.
Example:
A company is receiving reports from customers that, when they use the company’s web application, periods when the application is very responsive alternate with long wait times. Jane, the company’s performance engineer, does some initial investigation with PerformaSure and concludes that there is no correlation between the long response times and either the types of requests that users make or the volume of requests at the times when the site’s responsiveness decreases.
The company’s web site includes a load balancer that distributes users’ requests to several web and application servers. Jane suspects that certain requests are taking longer to execute depending on the web and application servers to which they are forwarded. She asks Bob, the company’s web and application server administrator, to investigate further.
Bob needs to find out if certain servers are performing poorly and where the problem is on each server. In order to do so, he does not want PerformaSure to aggregate requests for the same URL that end up on different servers.
Fortunately, the company’s load balancer adds a custom HTTP header to each request with the name of the server to which it forwards the request. The name of this header is X-LoadBalance-Forward .
Using nexusctl, Bob configures a separator for all requests that include the header
X-LoadBalance-Forward by specifying the following option with the startrecording command:
-srr “.*” “X-LoadBalance-Forward”
After he does so, only requests for the same URL that are also forwarded to the same server are aggregated in the session that he records. When he analyzes the session in the Request Time browser, he discovers that a request can take over twice as long to execute depending on the web and application servers to which it is forwarded.
See “ Request Separation Parameters ” on page 234 for more information about
using nexusctl to configure service request separators.
Separators can also be configured in the Workstation’s Recording Settings dialog.
See “ Separators Tab ” on page 213 for more information.
Separating Requests Based on a Name-Value Pair
In addition to separating requests based on a GET or POST parameter, cookie, or HTTP header name, you can also separate requests that contain a specific name-value pair.
Example:
A company is receiving complaints from customers that the company’s web application runs very slowly when they add items to their shopping cart, but not when they perform other actions, such as submitting search information.
The application’s developers decide to isolate all requests that include the query parameter action=AddItem by adding a separator in the Sampling tab of the
Recording Settings dialog that uses the URL expression .* and includes this namevalue pair (as shown below). When they record a new session, only requests that contain the parameter action=AddItem will be separated, but not requests that include action=Search or just action= .
Figure 18
Figure 17 Configuring request separation on the name-value pair action=AddItem
See “ Separators Tab ” on page 213 for more information about using the controls
in the Recording Settings dialog’s Separators tab.
Separators can also be configured when recording a session using nexusctl. See
“ Request Separation Parameters ” on page 234 for more information.
Recording a Session 83
Configuring Request Separation
You can configure separators using nexusctl or through the Workstation.
To configure service-request separation with nexusctl:
You can use the options available in the nexusctl command-line utility to configure
service request separation. See “ Request Separation Parameters ” on page 234 for
more information.
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 window’s toolbar or by selecting Tools > Recording
Control Window from the menu bar of the Project window or any browser.
2.
Click the Configure... button in the Recording Control window. The Recording
Settings dialog will appear.
3.
Select the recording settings configuration that you would like to use from the
Settings drop-down menu, or create a new configuration. See “ Configuring
Recording Settings ” on page 207 for details.
4.
Select the Separators tab.
5.
Adjust the controls found in this tab. See “ Separators Tab ” on page 213 for
detailed instructions.
6.
Review 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 to save your selections as part of the recording settings configuration and close the dialog. The Recording Control window will remain open, allowing you to begin recording when you choose by clicking the Start Recording button.
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 can be used to determine which requests are included and which are excluded. You can also match requests using literal
strings. See “ Appendix D—Regular Expressions ” on page 489 for more
information about using regular expressions.
84 PerformaSure: User’s Guide
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. By default, PerformaSure excludes requests for .gif, .jpg, .css, .png, .js, and .ico files.
After you have measured the request times for certain objects and you are satisfied that there are no problems with them, you can use service request filtering to remove them from view.
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 window’s toolbar or by selecting Tools > Recording
Control Window from the menu bar of the Project window or any browser.
2.
Click the Configure... button in the Recording Control window. The Recording
Settings dialog will appear.
3.
Select the recording settings configuration that you would like to use from the
Settings drop-down menu, or create a new configuration. See “ Configuring
Recording Settings ” on page 207 for details.
4.
Select the Filters tab.
5.
Adjust the controls found in this tab. See “ Filters Tab ” on page 216 for detailed
instructions.
6.
Review 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 to save your selections as part of the recording settings configuration and close the dialog. The Recording Control window will remain open, allowing you to begin recording when you choose by clicking the Start Recording button.
Note: You can also use the options available in the nexusctl command-line
Recording a Session 85
Session Acquisition
Tag and Follow
A typical session-acquisition flow is illustrated in Figure 18. 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 track using 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 marked upon entry into your PerformaSure-instrumented Java
EE environment,
■
■
The Agents integrated within the elements of your environment emit events to the Nexus as the service request is tracked, then
The Nexus reconstructs the full execution path for the service request.
Figure 19
Figure 18 The session acquisition pipeline
Session Time Slice Size
Service requests that have been tracked to completion using Tag and Follow are aggregated into the time slice in which they complete and the data is stored in the
86 PerformaSure: User’s Guide
session file (see Figure 19). The width of the time slice defines the finest
granularity of time that you can analyze with the PerformaSure browsers.
Figure 20
Figure 19 How service requests are aggregated
A request is associated with a time slice based on when it completes. Thus, in
Figure 19, 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 can be set in the Session tab of the Recording Settings dialog or using nexusctl. This setting 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 minutes) and wide time slice values for relatively long runs (> 10 minutes).
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).
Recording a Session 87
Acquiring a Session
Configuration Overview
The Workstation’s 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 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 195
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. It’s 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.
Settings
The Settings drop-down menu allows you to select a saved set of recording settings that are used when you start recording a new session. When you first launch the
Recording Control window, this menu includes the recording settings configuration
88 PerformaSure: User’s Guide
Default Settings, which is selected by default. See “ Default Settings ” on page 206
for more information about the settings included in this configuration.
Important: A recording settings configuration is required to record a session. If no configurations are listed in the Settings drop-down menu (for example, if the Default Settings configuration is accidentally deleted), you will not be able to record a session.
See “ Configuring Recording Settings ” on page 207 for
information about adding a new configuration.
Start Recording
The Start Recording button causes PerformaSure to start recording a session.
Clicking this button initiates recording by sending messages to all enabled Agents instructing them to send data to the Nexus. This button is disabled while you are recording a session.
Tip: You can automate session recording by means of the nexusctl
command-line utility. See “ Starting the Nexus from a script ” on page
Recording Settings Dialog
You can use the controls in the Recording Settings dialog to modify the settings included in a recording settings configuration, to remove a recording settings configuration, or to add a new configuration.
To change the settings included in an existing recording configuration, select the configuration from the Settings drop-down menu, adjust the controls in the dialog
as desired, and click Apply. See “ Configuring Recording Settings ” on page 207
for information about adding a new configuration. To remove a configuration, simply select the configuration from the Settings drop-down menu and click
Remove.
The basic recording settings that you may want to configure in the tabs of this dialog are described below.
Session 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
Recording a Session 89
90 PerformaSure: User’s Guide the session manually by clicking the Stop Recording button in the Recording
Control window.
Time Slice Size
The time slice size can be adjusted using the Time Slice Size associated dropdown 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.
Sampling 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 Overhead 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 Java EE 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
<performasure_home>/config/nexus.config. You will also need to restart the Agents and your instrumented application servers after editing ListenHost and ListenPort in nexus.config. See
“ ListenHost and ListenPort ” on page 432 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 “ Specifying the
Location of the Nexus ” on page 427 for details.
Location of the session file
The default location of all session files is the sessions subdirectory of the
PerformaSure home directory (<performasure_home>/sessions) on the machine hosting the Nexus. To change the location where the Nexus stores sessions, edit
SessionDirectory in <performasure_home>/config/nexus.config on the Nexus machine. If you supply a relative pathname, it is relative to the home directory for
PerformaSure.
Important: The directory where the Nexus stores sessions 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 nexus.config to ensure that this is the case.
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 429, “
” on page 434, and “ Incomplete Request Timeout ” on page 209
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 such as the level at which messages are logged, the language in which they are displayed, the places where the logs appear, and the
directory in which log files are created. See “ The Parameters in log.config
” on page 437 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.
Recording a Session 91
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 38 for more information about
how PerformaSure interacts with load-testing tools. Consult your load-testing tool’s manuals for product-specific details about installation, configuration, and use.
Collecting Your First Session
■
■
■
■
■
■
If it is your first time using PerformaSure, it’s better to start with a smaller session before using all of the capabilities of PerformaSure 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 5, set the PMI level to High or lower.
On WebSphere, do not use the JVMPI option ( heavily loaded.
-XrunpmiJvmpiProfiler
Minimize the number of application server metrics being gathered.
Arrange your load-testing scenario so that your application server is not
).
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 195.
92 PerformaSure: User’s Guide
Pre-Recording Checklist
Before you start recording, ensure that:
■
information.
Running the Nexus ” on page 41 for more
■ You have specified the correct host name and port number for the Nexus in
■
■
The Agents are running. See “ Running Agents ” on page 48 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 In—Quick Start ” on page 58 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 225 for more information.
Recording a New Session
To record a new session from the Workstation:
1.
Once you have logged in to the Workstation, select Record New Session from the PerformaSure Startup window.
2.
Click OK. The Recording Control window will appear.
3.
Click the Configure... button. The Recording Settings dialog will open.
4.
Select the recording settings configuration that you want to use from the
Settings drop-down menu.
Tip: The first time you record a session, you may want to use the Default
Settings recording configuration. See “ Default Settings ” on page 206 for
information about this configuration.
5.
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.
6.
Click on the Sampling tab. Make sure that the Component Detail
Recording Level radio button is selected.
7.
Click OK to save any changes that you made to the recording settings configuration and close the Recording Settings dialog. The Recording Control window will remain open.
8.
In the Recording Control window, select the recording settings configuration that you want to use from the Settings drop-down menu.
9.
Choose an appropriate name for your session and type it in the Name field.
10.
Enter comments about why you are recording the session in the Comments field.
11.
Ensure that the Open Session When Recording Completes checkbox is checked.
Recording a Session 93
12.
Press the Start Recording button.
13.
Send requests to your instrumented application server.
14.
If you have not set the duration of the session in the Recording Settings dialog, click the Stop Recording button 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:
Recording a Session FAQ
I can’t access the Recording Control window from the Workstation (the Recording
Control Window buttons and menu items are disabled). Why can’t I open this window and start recording a session?
If the Recording Control Window buttons and menu items are disabled, the role which has been assigned to your user account does not include the permissions required to start recording a session. Speak to your PerformaSure administrator about the permissions included in the role that you have been
assigned. See “ User Management ” on page 154 for more information about
permissions and roles.
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 <performasure_home>/config/nexus.config on the machine hosting the Nexus so that PerformaSure knows where to find the files.
See “ Location of the session file ” on page 91 for more information.
94 PerformaSure: User’s Guide
Chapter 4
Analyzing Sessions
This chapter discusses a methodology for analyzing the data that you collected using PerformaSure. It provides instructions for using the Project window, the Time
Control panel, and the browsers.
Methodology
This section presents general recommendations to help you begin analyzing sessions. For more detailed information about analyzing sessions in the
PerformaSure Workstation, see “ Navigating the Project Window ” on page 97 and
with JProbe
®
, Foglight
®
, and Spotlight
®
.
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:
■
■
The Nexus is running. See “ Running the Nexus ” on page 41 for more
information.
The Workstation is running and you are logged in. See “ Logging In—Quick
Start ” on page 58 for login instructions.
■
■
You have collected session data. See “ Collecting Your First Session ” on page
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.
95
Note: Sessions recorded with versions of PerformaSure prior to version 5.0 cannot be opened in PerformaSure 5.0. The error dialog shown in
Figure 20 appears if you attempt to open an obsolete session. The
Upgrade Session option has been disabled for the current version.
Figure 21
Figure 20 This dialog appears if you attempt to open an obsolete session
General Guidelines for Analyzing a Session
Because each person’s 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
265 for detailed information about this browser.
2. Launch the SQL browser. This browser allows you to take a high-level view of the SQL statements used in your Java EE application and investigate their
overall performance. See “ SQL Browser ” on page 295 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, time-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 319 for detailed
information about this browser.
4. 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 371 and “
Thresholds Browser ” on page 391 for detailed information about these browsers.
96 PerformaSure: User’s Guide
Navigating the Project Window
Selecting Another Project or Session
Once you have a Project window open, you have the option of opening another
Project or of 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.
2.
From the list of PerformaSure Project files (files with the .sure extension), double-click on a file or select one and then click Open.
To open a session in a new Project:
1.
Click the Open Session in New Project button in the Project window’s toolbar or select Project > Open Session in New Project... from the menu bar to launch the New Project Wizard.
2.
Select a session from the table. By default, the list of sessions is sorted by session name. Click on the header of another column in the table to sort the
3.
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
176 for more information about Project templates.
4.
Click Open. 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.
See “ Creating a New Project ” on page 174 for details about the fields and controls
in the New Project Wizard.
Customizing the Project Window
The PerformaSure Project window is the control panel for your Project. This window is highly configurable: you can select the browsers that give the best
Analyzing Sessions 97
indication of underperformance in your system and add them to the Project; organize browsers into folders in the navigation pane of the Project window’s
Browsers area; and add comments to browsers, folders, and the Project as a whole.
Figure 22
Figure 21 A Project window: browser icons have been organized into named folders
98 PerformaSure: User’s Guide
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 window’s toolbar or select Project > New Browser... from the menu bar. The
New Browser dialog will open.
2.
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.
3.
Click OK. The dialog will close and a new browser of the type you selected will open.
4.
Click the Add New Browser to Project button in the browser’s 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.
5.
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.
Note: 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.
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 22). 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 22 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.
To add comments to a Project:
1.
Select Project > Project Properties... from the menu bar. The Project
Properties dialog will open.
Analyzing Sessions 99
2.
Add comments to the Project.
3.
Click OK to save your comments and close the dialog. Save your project, if desired.
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 context menu that appears. The Folder Properties dialog will open.
2.
Add comments to the folder.
3.
Click OK to save your comments and close the dialog. Save your project, if desired.
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 context menu that appears. The Browser Properties dialog will open.
2.
Add comments to the browser.
3.
Click OK to save your comments and close the dialog. Save your project, if desired.
Note: You can access the Browser Properties dialog from individual browsers.
Click the Properties button in a browser’s toolbar or select Browser >
Properties... from its menu bar to launch the Browser Properties dialog.
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.
Creating a Custom Project Template
It’s easy to create your own Project templates based on existing PerformaSure
Projects. There may be many different reasons you want to do this, for example:
■ When you’re 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.
100 PerformaSure: User’s Guide
■
■
You’ve 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 you’ve 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.
2.
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 might not show up in
other sessions. See “ Adding Browsers
” on page 98, “ Organizing the
” on page 99, and “ Customizing the Browsers ” on page 102
for information about configuring browsers and the Project window.
3.
Save the Project in the <performasure_home>/config/templates directory: select the option Save Project as Template from the Project menu in the Project window’s menu bar, then name and save the new template using the Save file chooser that appears.
The next time you open a session in a new Project, you will be able to select that template from the Template drop-down menu in the New Project Wizard.
Using the Browsers
This section describes what the PerformaSure 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 individual browsers and their features, see Section II of this manual.
Analyzing Sessions 101
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.
2.
Click the Properties button in the toolbar of that browser or select
Browser > Properties... from its menu bar. The Browser Properties dialog will open.
3.
Check the Automatically open this browser when project is opened checkbox and click OK. Save your project, if desired.
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 graphs, themes, and reports and configure certain aspects of the Request Tree browser and the
Metrics browser. See “ Edit Options Dialog ” on page 247 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 23
Figure 22 The Time Control panel
102 PerformaSure: User’s Guide
Using the Time Control Panel
Navigating the Timeline
The Timeline represents the total period of time during which the session was recorded. 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 24
Figure 23 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 Zonar’s 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 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 Zonar’s position relative to the start of the session and the length of time that you have adjusted it to cover.
Analyzing Sessions 103
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 22). 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.
104 PerformaSure: User’s Guide
To move the Zonar to a different location within the Timeline:
1.
Click the middle of the Zonar.
2.
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 22). 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.
Adjust the Zonar so that it spans the length of time in which you are interested.
2.
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.
Analyzing Sessions 105
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. The slider’s offset from the leftmost point on the chart’s 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 chart’s xaxis reflects the range currently spanned by the Zonar. When you move the
Sightline’s slider, it snaps to time slice boundaries imposed by the Zonar.
Figure 25
Figure 24 The Sightline and its slider in the Metrics browser
PerformaSure draws a horizontal dashed line from the y-axis to the Sightline’s current position in the chart along the x-axis. This allows you to accurately determine the measured quantity’s 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
106 PerformaSure: User’s Guide
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 browser’s Zonar and
Sightline to function independently.
Filtering Data in the Browsers
In several of the PerformaSure browsers, you can filter the data that is displayed in the graph and detail panes. For example, if you are only interested in seeing the metrics that have exceeded their bounds for a certain server, you can specify a filter in the Thresholds browser’s Filter Metrics bar that includes that server’s name.
See “ Using the Thresholds browser’s Filter Metrics bar ” on page 397 for more
information.
In the Request Time, and Request Tree browsers, you filter data for display by entering a literal string or regular expression in the Filter Requests bar. This string or expression is matched against the items listed in the detail pane; only the items that match are displayed in the graph and detail panes. By default, this bar
contains an empty literal string so that all items are selected. See “ Using the
Request Time browser’s Filter Requests bar
” on page 273, and “ Using the Request
Tree browser’s Filter Requests bar ” on page 333 for more information.
There is a Filter Statements bar in the SQL browser that functions the same way as the Filter Requests bar; you can use it to filter SQL statements for display in the
browser. See “ Using the SQL browser’s Filter Statements bar ” on page 301 for
more information.
Note: The filters that you specify in the browsers listed above are casesensitive.
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.
Analyzing Sessions 107
Figure 26
Figure 25 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
108 PerformaSure: User’s Guide
request. It allows you to determine which service request took the longest to complete, and where the majority of the request’s time was spent.
Using the Request Time Browser—Quick 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 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. 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 charts in the graph pane and detail panes. PerformaSure consistently assigns colors to standard and custom components. When you select the option Component Technology, the segments in the chart are grouped by component technology. The component
technology segments are listed in the table “ Component Technology Chart
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.
2.
Click the radio button associated with either Tier or Component
Technology.
Analyzing Sessions 109
Isolating Requests in the Detail Pane
The detail pane is only available when the browser is in All Requests mode. The detail pane presents a list of requests and of response time metrics for these
requests in tabular form. See “ Detail Pane Columns ” on page 290 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 select
Show/Hide Columns... from the context menu. 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 context 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.
3.
Click OK to apply these settings and close the dialog.
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 109 for details.
2.
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.
Figure 27
Figure 26 Sorting requests by Avg Cumulative Time in the detail pane
110 PerformaSure: User’s Guide
Charting Response Time Metrics For a Request
Once you have isolated a request of interest in the detail pane, simply click its entry in the table to cause a metric chart to be displayed in the graph pane for that request. 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 109 for details. See “ Request Time Browser Graph
Pane—Full Detail ” on page 284 for information about the controls, tooltips, and
context 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 28
Figure 27 The aggregate response time of all requests charted in the graph pane
As shown in above, 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
Analyzing Sessions 111
down into the request. In All Requests mode, three Request Investigation actions are available in the browser’s control pane. 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 280 for more information about the drill-down actions
available in the browser in All Requests mode.
Figure 29
Figure 28 The Request Time browser’s control pane in All Requests mode
Investigating a Request in Other PerformaSure Browsers
In All Requests mode, three 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
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 options available in the control
pane in Single Request Investigation mode are described below. See “ Request Time
Browser Graph Pane—Full Detail ” on page 284 for information about the
controls, tooltips, and context menus available in the graph pane.
112 PerformaSure: User’s Guide
Figure 30
Figure 29 The Request Time browser’s 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 31
Figure 30 A drill-down history tooltip
Selecting the Next Drill-Down Level
The request investigation actions that you can perform vary depending on the current drill-down level. The actions that are available from the current level are
section.
Analyzing Sessions 113
Investigating a Request in Other PerformaSure Browsers
In Single Request Investigation mode, three 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 282 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 106 for more information.
Request Time Browser Reports
Click the Export Report button in the browser’s 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 413 for
more information about generating a report. See “ Request Time Report ” on page
418 for details about the information included in a report generated from the
Request Time browser.
114 PerformaSure: User’s Guide
Using the SQL Browser
Figure 32
Figure 31 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.
Analyzing Sessions 115
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 Browser—Quick Start
Isolating SQL Statements in the Detail Pane
The SQL browser’s detail pane presents a list of SQL statements and of response
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.
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 context 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 context 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.
3.
Click OK to apply these settings and close the dialog.
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.
116 PerformaSure: User’s Guide
Figure 33
Figure 32 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 Pane—Full Detail ” on page 309 for details
about the controls, tooltips, and context 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 34
Figure 33 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.
Analyzing Sessions 117
Using the SQL Browser’s Control Pane
The SQL browser’s 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 35
Figure 34 The SQL browser’s 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 browser’s 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
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 106 for more information.
118 PerformaSure: User’s Guide
SQL Browser Reports
Click the Export Report button in the browser’s 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 413 for
more information about generating a report. See “ SQL Report ” on page 418 for
details about the information included in a report generated from the SQL browser.
Using the Request Tree Browser
Figure 36
Figure 35 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 request’s 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
Analyzing Sessions 119
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 Java EE 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 37
Figure 36 Elements in the Request Tree browser’s 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.
120 PerformaSure: User’s Guide
Figure 38
Figure 37 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, simply rightclick on the request in the graph pane of the Request Time browser and select
View Call Tree from the context menu that appears.
By deconstructing a service request into its constituent parts and displaying them in a request tree, this browser enables you to view the nested set of calls that are made as the request progresses. A request tree shows the relationship between all components—such as Servlets, EJBs, and JDBC calls—that contributed to the completion of a service request.
Using the Request Tree Browser—Quick Start
For detailed descriptions of all of the fields and controls in this browser, see
“ Request Tree Browser ” on page 319.
Navigating the Graph Pane
Zooming the graph pane
A typical request tree will not 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.
Analyzing Sessions 121
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 below, 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 39
Figure 38 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.
2.
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.
Note: If the Panner Updates Graph While Dragging checkbox is selected in the Graphs 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.
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.
122 PerformaSure: User’s Guide
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 328 for a complete list of metrics.
Coloring the Identifier bars
You can also color the Identifier bar found on the left side of each node (see
Figure 37) 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.
2.
Select Component Technology. The Identifier bars in the request trees will change color. You can now distinguish each standard and custom component in your Java EE application based on the unique color that it is assigned.
Using and Customizing the Color Scale
The Color Scale Toggle button toggles the display of a color-based legend called the Color Scale . 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.
2.
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.
Analyzing Sessions 123
3.
Select Custom from the drop-down menu.
4.
The Color Scale options box contains two color rectangles, which are used to set the extreme hot and cold colors in the Request Treebrowsers. 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 browser’s Color Scale and then click OK to close the dialog.
Note: 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 247 for
more information.
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 328 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 40
Figure 39 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.
124 PerformaSure: User’s Guide
Figure 41
Figure 40 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 347 for more information about
the tooltips associated with the various types of nodes.
There is also a 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 image below). 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 42
Figure 41 The tooltip for a section of the Color Scale in the Request Tree browser
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 Java EE classes and methods in each request tree, giving you an overview of your application’s behavior. Class-level bundling
Analyzing Sessions 125
displays both Java EE 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: The default bundling mode for PerformaSure is Component.
That means that even if you recorded your session at full detail, only the key Java EE 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 application’s 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.
2.
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.
Pruning and Isolating Request Trees
Nodes that are very expensive based on the active metric can overshadow nodes that are less expensive—but still problematic. The Prune and Isolate options available from the context 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... >
Graphs). Certain nodes will always display as ghosted when you prune them because they must remain in place to maintain the request tree’s 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.
126 PerformaSure: User’s Guide
The action performed when you select one of the Prune or Isolate options can
vary depending on the context menu from which you select it. See “ Context
Menus in the Graph Pane ” on page 351 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. 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 363 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 don’t 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.
Note that focus will not be transferred to nodes that were pruned or excluded and are hidden; however, focus will be transferred to nodes that were pruned or excluded and are displayed as ghosted.
Transferring focus to a hidden child node will cause it to be displayed again.
There are two settings for viewing this information, List and Tree. List is the default setting. When List 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 43
Figure 42 Items listed in the detail pane (with Tree selected)
To change the detail table mode to Tree:
1.
Click the list/tree toggle button at the far right of the detail pane or select View > Detail Table Mode > Tree. The way the lines are drawn
Analyzing Sessions 127
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 don’t 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.
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 context 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 context 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 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.
3.
Click OK to apply these settings and close the dialog.
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 106 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 134 for more information.
Request Tree Browser Reports
Click the Export Report button in the browser’s 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 413 for
more information about generating a report. See “ Request Tree Report ” on page
419 for details about the information included in a report generated from the
Request Tree browser.
128 PerformaSure: User’s Guide
Using the Metrics Browser
Figure 44
Figure 43 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 anomalous behavior.
Tip: By correlating system metrics with service request metrics, you can often expose a performance problem.
Analyzing Sessions 129
The Metrics browser also provides access to the Threshold Editor, the dialog in
which you set metric thresholds. See “ Threshold Editor ” on page 408 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 browser’s 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 Browser—Quick 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 464 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.
130 PerformaSure: User’s Guide
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 context 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 385 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 context 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 browser’s 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 Pane—Full
Detail ” on page 384 for details about the tooltips and context 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 browser’s 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 413 for
Analyzing Sessions 131
more information about generating a report. See “ Metric Report ” on page 420 for
details about the information included in a report generated from the Metrics browser.
Using the Thresholds Browser
Figure 45
Figure 44 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
132 PerformaSure: User’s Guide
interval spanned by the Zonar are listed in the browser’s 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 Browser—Quick Start
Selecting a Metric For Display
The Thresholds browser’s 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 405 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 46
Figure 45 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 45). See “ Thresholds Browser Graph Pane—Full Detail ” on page 402 for
details about the controls and tooltips available in the graph pane.
Analyzing Sessions 133
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 408 for more information.
Thresholds Browser Reports
Click the Export Report button in the browser’s 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 413 for
more information about generating a report. See “ Threshold Report ” on page 421
for details about the information included in a report generated from the
Thresholds browser.
Integration with the Quest Software Suite for Further Analysis
■
■
The following topics are covered in this section:
JProbe Integration
JProbe Profiler is the ideal tool for profiling the internals of Java classes.
PerformaSure provides a handy tool to make coordination with JProbe even easier. This section describes the functions available from the Export JProbe
™
Launcher File menu choice that is available in the Request Tree browser.
134 PerformaSure: User’s Guide
Figure 47
Figure 46 Export JProbe Launcher File menu choice
Generating and Using a JProbe Launcher File
The .jpl file contains settings to start the application server under JProbe Profiler, either from a command line or from JProbe’s LaunchPad, and to collect performance data on the classes and methods that you select in the Request Tree browser.
Caution: Use the drop-down menu in the Request Tree pane of the Edit
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 launch the Edit Options dialog, select
Tools > Options... from the menu bar of the Project window or any browser.
To generate a JPL file:
1.
Select one or more nodes in the call tree displayed in the Request Tree browser’s 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.
2.
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.
3.
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
Analyzing Sessions 135
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 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.
Ensure that JProbe is installed on a machine as described in step 2 above.
2.
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 application 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.
Note: 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 developer’s workstation or a test environment running the same application server and deployed software.
Profiling Packages and Classes
This section uses JProbe-specific terminology and assumes some familiarity with
JProbe and its use. If you are new to JProbe, refer to the JProbe Profiler
Developer’s Guide for a complete description of the application.
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.
1. If you selected methods, the classes containing these methods is profiled.
136 PerformaSure: User’s Guide
Type of profiling based on selections and menu choice
The following table summarizes what is 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 node’s package result = 1 filter
The nodes’ package result = 1 filter
The nodes’ package result = 1 filter
Multiple nodes from multiple classes in multiple packages
The nodes’ packages result = 1 filter per selected package
- no duplicates
Menu Choice: Profile Selected
Class(es)
The node’s 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
Spotlight Integration
There are several ways to launch Spotlight
® in Quest Central from PerformaSure:
■ You can launch Spotlight
® in Quest Central from the Tools menu of the
Project window or any browser (Tools > Performance Diagnostics) or from the toolbar of any browser.
■ You can also launch Spotlight
® in Quest Central 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
®
in Quest Central from the context menu.
Note: Selecting the Spotlight
®
in Quest Central menu item launches the version of Spotlight
®
that is included with Quest Central. You must have
Quest Central installed to launch Spotlight
®
from PerformaSure.
Analyzing Sessions 137
Analyzing Sessions FAQ
What does it mean if the message “No Data For Selected Settings” appears in a browser?
This message appears when there is no data available for display because of the configuration of one or more of the browser’s settings. For example, this message will appear when:
■ There is no session data available for display in the browser for the section of
the Timeline spanned by the Zonar. See “ Using the Zonar ” on page 104 for
information about adjusting the length of time spanned by the Zonar.
■ A filter has been specified in the browser’s Filter Requests, Filter Statements, or
Filter Metrics bar that does not return any data. See “ Filtering Data in the
Browsers ” on page 107 for information about specifying filters.
After I log into the Workstation, the Open Session in New Project, Open Existing
Project, and Open Recent Project radio buttons are disabled in the Startup window.
Why can’t I view the sessions that have been recorded?
If these buttons are disabled, the role that has been assigned to your user account does not include the permissions required to open existing Projects or to open sessions in new Projects. Speak to your PerformaSure administrator about the
permissions included in the role that you have been assigned. See “ User
Management ” on page 154 for more information about permissions and roles.
The following WARN error appears in the log files for a session that I recorded:
“Node has used a remote protocol too many times: filtering subsequent flows. This is a likely cause of performance problems in the application.” How can I find out which node is responsible?
If you see this WARN error in a PerformaSure log file or in the Project window’s
Session Log dialog, you can discover which method initiated the RMI calls by following these steps:
1.
If you have not already done so, start the Workstation and open the session.
2.
Launch the Request Tree browser.
3.
Type the following into the text field in the Request Tree browser’s Filter Requests bar:
Remote Invocation Limit Exceeded
4.
Ensure that the Regular Expression and Apply to Root Nodes Only checkboxes are deselected and press Apply.
5.
Right-click the round Show/Hide Child Node button on the entry-point node of each request tree that is displayed in the graph pane and select Expand All
Children from the context menu that appears.
138 PerformaSure: User’s Guide
6.
Look for nodes labelled Remote Invocation Limit Exceeded (see image below).
7.
Trace back along the call tree from a Remote Invocation Limit Exceeded node to find the method that initiated the RMI calls.
For information about the RemoteInvocationLimit configuration setting in the
file <performasure_home>/config/client/instrumentation.config, see “ Setting the
Remote Invocation Limit ” on page 458.
Figure 48
Figure 47 Search for nodes labelled Remote Invocation Limit Exceeded in the request tree
Why does an Out of Memory error occur when I open certain sessions?
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.
2.
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 .
3.
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
Unix: Edit the text file <performasure_home>/bin/workstation.lax to change the memory option setting. Example: lax.nl.java.option.additional=-Xms128m -Xmx 512 m -Dquest.debug=0
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.
I would like to be able to 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:
Analyzing Sessions 139
■
■
■
When you’re 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.
You’ve 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 you’ve 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.
2.
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 might not show up in
other sessions. See “ Adding Browsers
” on page 98, “ Organizing the
” on page 99, and “ Customizing the Browsers ” on page 102
for information about configuring browsers and the Project window.
3.
Save the Project in the <performasure_home>/config/templates directory: select the option Save Project as Template from the Project menu in the Project window’s menu bar, then name and save the new template using the Save file chooser that appears.
The next time you open a session in a new Project, you will be able to select that template from the Template drop-down menu in the New Project Wizard.
Do the JPL files created by PerformaSure 5.0 work with the latest version of JProbe?
The JPL file formats available in PerformaSure 5.0 are JProbe 6.x-8.x..
To select a JPL file format:
1.
Select Tools > Options... from the menu bar of the Project window or any browser. The Edit Options dialog opens.
2.
Click on Request Tree in the pane on the left-hand side of the Edit Options dialog.
3.
Select the version of JProbe that you are using from the JPL File Format drop-down menu in the Request Tree pane.
4.
Click OK to save your selection and close the dialog.
140 PerformaSure: User’s Guide
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 users even though most of them don’t 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 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
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 overly-long requests or requests that result in too many database calls.
2.
Perform a load test using a single application server on a multi-processor machine. At this stage, you may be able to detect resource contention and serialization issues.
3.
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 shouldn’t be too far removed from your production system.
141
142 PerformaSure: User’s Guide
Part
II
The
PerformaSure
Workstation
Chapter 6
PerformaSure Workstation
The Workstation is the graphical user interface (GUI) for PerformaSure. With it, you can manage users and roles, collect data, and explore and analyze sessions with the help of the PerformaSure browsers. These 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.
Once you have identified time-consuming requests, you can use the browsers to correlate them with other data collected from your distributed system during the same period, such as SQL statement, network traffic, application server, and OS metrics. If you load your system with hundreds of users, you’ll be able to measure the system’s average behavior and compare it to the maximum request times.
As long as your system resources are sufficiently powerful, the licensed members of your team can run several Workstations simultaneously.
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.
Note: The Workstation is not used for tasks like configuring your application server to work with PerformaSure or other setup tasks that require hand tooling, such as editing configuration files. See the Installation and
Configuration Guide for instructions on setting up your environment to
PerformaSure.
145
Starting the Workstation
Logging In
When you launch PerformaSure, a Splash screen appears. To run the
Workstation, you must first successfully log in through the Login window.
Figure 49
Figure 48 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.
Important: The user name admin and the password admin can initially be used to log in to the Workstation with administrator privileges and add additional user accounts through the User Management window. Quest Software recommends that you promptly change the password for the admin account to something other
than its installed value. See “ Changing a Password ” on page 154
for more information.
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 “ Defining Nexus
Instances ” on page 148 for details.
Once you have entered all the information, click Login. If you click Exit, you will close PerformaSure.
146 PerformaSure: User’s Guide
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 50
Figure 49 The logon error alert
If you see the Not Responding error dialog, verify that the Nexus is running, that its address and port number are correct, and that the network connections are functioning.
Figure 51
Figure 50 Failure to connect to the Nexus results in this alert
If you are running the Workstation on RedHat Enterprise Linux AS 3.0, the
Workstation may be unable to connect to a remote Nexus and will log an error like the following:
2006-03-06 09:12:15.018 [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 Enterprise Linux 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
PerformaSure Workstation 147
Defining Nexus Instances
The Define Nexus dialog (Figure 52) allows you to edit, add, or remove a Nexus
instance. You can access it by clicking Define in the Login window (Figure 49).
Figure 52
Figure 51 The Define Nexus dialog
Define Nexus Dialog—Summary
Define Nexus Dialog
Control Type
Nexus instances Table
Edit...
Add...
Remove
Button
Button
Button
Default Value Description
N/A 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.
Disabled
Enabled
Disabled
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.
Define Nexus Dialog—Full Detail
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.
148 PerformaSure: User’s Guide
Edit Nexus Dialog
The Edit Nexus dialog allows you to change the properties of an existing Nexus instance.
Figure 53
Figure 52 The Edit Nexus dialog
The fields in this dialog are listed below.
Alias
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 54
Figure 53 The Add Nexus dialog
The fields in this dialog are listed below.
Alias
When you launch the Add Nexus dialog, this field contains a default name such as Nexus 1. This is the name by which the Nexus is known in the Define Nexus dialog; you can edit this field to specify a new display name for the Nexus.
PerformaSure Workstation 149
Address
The IP address for the machine hosting the Nexus.
Port
The port on which this Nexus listens.
Remove
If there are items in the Nexus instance table that are no longer applicable, select the instance you want to delete from the list and click Remove.
Navigating the Startup Window
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 55
Figure 54 PerformaSure Startup window showing the Tools menu choices
Important: Depending on the permissions that are included in the role you have been assigned, certain options may not be available from
the Startup window. See “ User Management ” on page 154 for
information about roles and permissions.
150 PerformaSure: User’s Guide
Startup Window—Summary
Startup Window
Control
Logout
OK
Type
Record New Session Radio button
Open Session in New
Project
Radio button
Open Existing Project Radio button
Not selected
Not selected
Open Recent Project Radio button and project list
Tools
Not selected
Drop-down menu Enabled
Exit
Button
Button
Button
Default Value Description
Selected Opens the Recording Control window.
Launches the New Project Wizard.
Enabled
Enabled
Enabled
Launches the Open file chooser.
Opens the PerformaSure Project that you select from the project list.
Displays a drop-down menu. See “ Tools ” below for more
information.
Logs you out of the Workstation and returns you to the
Login window.
Confirms your selection and opens the appropriate window or dialog.
Closes the Startup window and exits PerformaSure.
Startup Window—Full Detail
Record New Session
Select this radio button and click OK to open the Recording Control window. See
“ Recording Control Window and Nexusctl ” on page 195 for details about the
fields and controls available in this window.
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.
Sessions recorded with versions of PerformaSure prior to version 5.0 cannot be opened in PerformaSure 5.0. The Upgrade Session option has been disabled for
the current version. See “ New Project Wizard ” on page 171 for details about
creating a new Project.
An error dialog will appear if you attempt to open an obsolete session.
PerformaSure Workstation 151
Open Existing Project
Select this radio button and click OK to launch the Open file chooser, which allows you to navigate to the directory in which you saved the Project.
By default, Projects are saved in the PerformaSure root directory. PerformaSure
Project files are created with the help of the New Project Wizard and have the .sure extension.
Note: Opening a Project causes a session file to be read. The progress dialog
shown in Figure 56 appears while the session file is being scanned.
Figure 56
Figure 55 This alert appears while the session file is loading
When you try to open an existing Project, the Session Error dialog (Figure 57) 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
“ Upgrading 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 (Figure 55), from which you can create a new
Project, record a new session, or open another existing Project.
Figure 57
Figure 56 The Session Error dialog
152 PerformaSure: User’s Guide
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 the file
<performasure_home>/config/nexus.config on the machine hosting the
Nexus.
To re-associate a Project with a session file that has been moved:
1.
Click No to close the Session Error dialog.
2.
Shut down the Workstation (click Exit in the Startup window) and stop the Nexus.
3.
Open the file nexus.config on the machine hosting the Nexus.
4.
Edit SessionDirectory to point the Nexus to the folder (on a local
drive) in which you are storing session files. See “ Changing the Sessions
Directory ” on page 430 for more information.
5.
Save and close nexus.config.
6.
Restart the Nexus and the Workstation.
Upgrading a Session
A session recorded with a version of PerformaSure prior to version 5.0 cannot be opened in PerformaSure 5.0. This option has been disabled for the current version.
Open Recent Project
Select this radio button and click OK to open the Project that you chose from the project 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 (see Figure 55). 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 ” on page 164 for more information.
PerformaSure Workstation 153
Change Password...
Choose this option to open a dialog in which you can change your password.
See “ Changing a Password ” below for more information.
User Management...
Choose this option to open a dialog in which you can add new users, create roles, and assign passwords and roles to users. This option is disabled if you
do not have the required permissions. See “ User Management ” on page 154
for more information.
To exit PerformaSure without selecting any of these options, click Exit. To log out of the Workstation and return to the Login window, click Logout.
Changing a Password
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 58
Figure 57 The Change Password dialog
Note: Passwords are sent to the Nexus in encrypted format for user authentication.
User Management
If you have the required permissions, you can manage users through the User
Management window (Figure 59). You can open this window by selecting User
Management... from the Tools drop-down menu in the Startup window (Figure
55). This menu item is disabled if you do not have the permissions required to
view or manage users and roles.
154 PerformaSure: User’s Guide
The user management terminology used in PerformaSure is defined below.
User Management in PerformaSure
Term
Permission
Role
User
Definition Use in PerformaSure
A permission authorizes a user to perform a certain set of actions using PerformaSure. The list of permissions defined by PerformaSure cannot be modified. See
“ Selecting Permissions ” on page 160 for more
information.
A role is a named set of permissions. PerformaSure includes three default roles: Session Analyst, Power User,
and Administrator. See “ Managing Roles ” on page 158 for
information about the default roles, adding new roles, and modifying roles.
Permissions are assigned to users through roles.
You can use the default roles, create multiple new roles based on different combinations of permissions, and modify the set of permissions assigned to each role, but only one role can be assigned to each user.
Each user has a username and password and is assigned a single role. PerformaSure includes two default users:
user and admin. See “ Managing Users ” on page 156 for
information about the default users, adding new users, and modifying user information.
Logging on as a specific user allows you perform a certain set of actions, based on the permissions included in the role assigned to that user.
Figure 59
Figure 58 The tabs in the User Management window showing the default set of users and roles
PerformaSure Workstation 155
User Management Window—Users Tab
Control
List of users
Type
Text area
Default Value admin, user
New
Edit
Delete
Button
Button
Button
Enabled
Disabled
Disabled
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.
Opens the New User dialog.
Launches the Edit User dialog. This button is enabled when you select a user from the list.
Deletes the selected user (after confirmation). This button is enabled when you select a user from the list.
User Management Window—Roles Tab
Control
List of roles
Type
Text area
New
Edit
Delete
Button
Button
Button
Default Value
Administrator,
Power User,
Session Analyst
Enabled
Disabled
Disabled
Description
Lists the set of roles to which users can be assigned. This text area is not editable: it simply displays a list of all the roles that have been defined.
Opens the New Role dialog.
Launches the Edit Role dialog. This button is enabled when you select a role from the list.
Deletes the selected role (after confirmation). This button is enabled when you select a role from the list.
Managing Users
Default Users
By default, PerformaSure includes the user accounts user and admin. The initial settings for these accounts are described below.
■ user: Includes a blank password and is assigned the Power User role. See
” on page 158 for information about this role. See “ Editing User
Information ” on page 157 for information about changing a user’s password or
role.
■ admin: Includes the password admin and is assigned the Administrator role. See
“ Default Roles ” on page 158 for information about this role.
The admin user cannot be deleted. You can change the role assigned to this
156 PerformaSure: User’s Guide
user, but the new role must include at least the View Users and Roles,
Important: Quest Software recommends that you promptly change the password for the admin account to something other than its installed value.
Adding a New User
Click the New button in the Users tab to launch the New User dialog. This dialog contains the Role drop-down menu and three required text fields in which you enter information about the 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.
Note: User names and passwords are case-sensitive.
Each user is assigned a single role. Use the Role drop-down menu to select a role for the new user. Since permissions are specified through roles, the role that you assign to a user determines the actions that they are authorized to perform. See
“ Selecting Permissions ” on page 160 for information about the set of permissions
from which you can choose when creating or editing a role.
Figure 60
Figure 59 Assigning a role in the New User dialog
Editing User Information
Select one or more user and click the Edit button to launch the Edit User dialog.
You can use this dialog to change a user’s password or role, but user names cannot be changed.
PerformaSure Workstation 157
Figure 61
Figure 60 Changing a user’s role in the Edit User dialog
Deleting a User
Select a user and click the Delete button to cause the Delete Users alert to appear.
This alert allows a user with the necessary permissions to confirm the deletion of one or more users from the system.
Figure 62
Figure 61 The Delete Users alert
Note: The admin user cannot be deleted.
Managing Roles
Default Roles
By default, PerformaSure includes the roles Session Analyst, Power User, and
Administrator. The permissions initially included in these roles are described below.
■ Session Analyst: Includes the Open Sessions permission. This role allows users to analyze session data in the browsers by opening an existing Project or opening a session in a new Project.
■ Power User: Includes all permissions except those required to view and manage users and roles. This role allows users to perform a variety of actions, including analyzing and managing existing sessions, starting and stopping session recording, and shutting down the Nexus.
158 PerformaSure: User’s Guide
■ Administrator: Includes all permissions. This role allows users perform all of the actions available within the Power User role and also enables them to manage users and roles. The Administrator role cannot be deleted. You can change the permissions included in this role, but it must include at least the
View Users and Roles, Manage Users, and Manage Roles permissions.
See “ Selecting Permissions ” on page 160 for details about the permissions
described above.
Creating a New Role
Click the New button in the Roles tab to launch the New Role dialog. This dialog allows you to specify a name for the new role using the Role Name text field and to select permissions for this role using the checkboxes in the Permissions area. See
“ Selecting Permissions ” below for more information.
Figure 63
Figure 62 Adding permissions in the New Role dialog
Editing a Role
Select a role and click the Edit button to launch the Edit Role dialog. You can use
this dialog to change the permissions associated with a role; see “ Selecting
Permissions ” below for more information. Role names cannot be changed.
PerformaSure Workstation 159
Figure 64
Figure 63 Removing a permission in the Edit Role dialog
Selecting Permissions
By selecting or deselecting the checkboxes in the Permissions area of the New Role and Edit Role dialogs, you can choose which permissions are associated with a certain role. The permissions from which you can choose are described below.
Open Sessions
This permission enables a user to analyze sessions in the browsers.
When this permission is not included in the role assigned to a user, the user will not be able to open a session in a new Project or to open an existing
Project.
Upgrade Sessions
PerformaSure version 5.0 does not currently support session conversions from any previous version of PerformaSure.
The Upgrade Sessions option is disabled for this version.
Edit Sessions
This permission enables a user to edit session names and comments that have been added to sessions using the Edit Session Properties dialog. This dialog is accessible from the Session Management dialog and in the New Project Wizard.
When this permission is not included in the role assigned to a user, the Edit button and the Edit Session context menu item (which launch the Edit Session
Properties dialog) are disabled in the Session Management dialog and in the New
Project Wizard.
160 PerformaSure: User’s Guide
Delete Sessions
This permission enables a user to delete sessions using the Session Management dialog and the New Project Wizard.
When this permission is not included in the role assigned to a user, the Delete button and the Delete Session context menu item are disabled in the Session
Management dialog and in the New Project Wizard.
View Agents
This permission enables a user to view the list of (enabled or disabled, connected or disconnected) Agents by issuing the nexusctl command showconnections .
When neither this permission nor the Start Recording permission are included in the role assigned to a user, the tables with Agent information will not be displayed when this command is issued.
Note:
Note:
Permission to view Agent information (in the Recording Control window, in the Recording Settings dialog, and using nexusctl) is automatically included in the Start Recording permission.
If none of View Agents, View Users, Start Recording, or Manage
Users are included in the role that is assigned to a user, information about neither the Agents nor the connected users will be displayed when the nexusctl command show-connections is issued, and a message similar to the following will appear in the Unix shell or DOS command window:
<DateStamp> INFO User does not have permissions to execute command: show-connections
Clear Agent Information
This permission enables a user to remove disconnected Agents from the list of
Agents by clicking using the Reset Agent List button in the Agents tab of the
Recording Settings dialog or by issuing the nexusctl command reset-agentlist .
When this permission is not included in the role assigned to a user, the Reset
Agent List button in the Agents tab of the Recording Settings dialog is disabled.
In addition, when the nexusctl command reset-agent-list is issued, the list of Agents will not be reset and a message similar to the following will appear in the Unix shell or DOS command window:
<DateStamp> ERROR Could not make remote call to Nexus
<DateStamp> INFO User does not have permissions to execute command: reset-agent-list
Start Recording
This permission enables a user to start recording a session using the Recording
Control window or nexusctl.
PerformaSure Workstation 161
When this permission is not included in the role assigned to a user, the menu items and buttons in the Workstation that launch the Recording Control window are disabled. In addition, when the nexusctl command start-recording is issued, PerformaSure will not start recording a session and a message similar to the following will appear in the Unix shell or DOS command window:
<DateStamp> ERROR Could not make remote call to Nexus
<DateStamp> INFO User does not have permissions to execute command: start-recording
Stop Recording
This permission enables a user to stop recording a session using the Recording
Control window or nexusctl.
When this permission is not included in the role assigned to a user, the menu items and buttons in the Workstation that launch the Recording Control window are disabled. In addition, when the nexusctl command stop-recording is issued, PerformaSure will not stop recording the session and a message similar to the following will appear in the Unix shell or DOS command window:
<DateStamp> ERROR Could not make remote call to Nexus
<DateStamp> INFO User does not have permissions to execute command: stop-recording
View Users and Roles
This permission enables a user to perform the following actions:
• View the lists of users and roles in the tabs of the User Management window.
The New, Edit, and Delete buttons will be disabled if this permission is included in the role assigned to a user but Manage Users is not.
• View the list of users and client types ( Workstation or NexusCtl ) that are connected to the Nexus by issuing the nexusctl command showconnections .
When neither this permission nor Manage Users are included in the role assigned to a user, the User Management... menu item is disabled in the
Tools menu in the Startup window, in the Project window, and in the browsers.
In addition, the tables with information about the connected users will not be displayed when the nexusctl command show-connections is issued.
Note: Permission to view users and roles is automatically included in the
Manage Users permission.
Note: If none of View Agents, View Users, Start Recording, or Manage
Users are included in the role that is assigned to a user, information about neither the Agents nor the connected users will be displayed when the nexusctl command show-connections is issued, and a message similar to the following will appear in the Unix shell or DOS command window:
<DateStamp> INFO User does not have permissions to execute command: show-connections
162 PerformaSure: User’s Guide
Manage Users
This permission enables a user to perform the following actions:
• Add a new user and assign a password and role to that user.
• Edit user information (change a user’s password or assigned role).
• Delete a user from the system.
When this permission is not included in the role assigned to a user, the New,
Edit, and Delete buttons are disabled in the Users tab of the User Management window.
Important: The Manage Users permission provides the equivalent of administrator privileges to a user.
Manage Roles
This permission enables a user to perform the following actions:
• Add a new role and specify the permissions that are associated with it.
• Edit a role (change the permissions included in that role).
• Delete a role from the system.
When this permission is not included in the role assigned to a user, the New,
Edit, and Delete buttons are disabled in the Roles tab of the User Management window.
Important: The Manage Roles permission provides the equivalent of administrator privileges to a user.
Shutdown Nexus
This permission enables a user to shut down the Nexus. Depending on the mode in which the Nexus was started and the platform on which it is running,
there may be several ways to stop the Nexus; see “ Stopping the Nexus ” on page 45 for details.
When this permission is not included in the role assigned to a user, the Nexus will not shut down when the user attempts to do so, and an error message may appear. For example, issuing the nexusctl command stop to shut down a
Nexus running in the background on Windows without the required permission will cause a message similar to the following to appear in the DOS command window:
<DateStamp> INFO Requesting Nexus shutdown.
<DateStamp> ERROR Could not make remote call to the Nexus
PerformaSure Workstation 163
<DateStamp> INFO User does not have permissions to execute command: stop
Deleting a Role
Select one or more roles and click the Delete button to cause the Delete Roles alert to appear. This alert allows a user with the necessary permissions to confirm the deletion of one or more roles from the system.
Figure 65
Figure 64 The Delete Roles alert
Note: The Administrator role cannot be deleted.
Session Management
The Session Management dialog allows you to edit session properties, and delete sessions. To open the Session Management dialog, click the Session Management button in the Project window or select Tools > Session Management... in the
Startup window, the Project window, or any browser.
Figure 66
Figure 65 The Session Management dialog
164 PerformaSure: User’s Guide
Session Management Dialog—Summary
Session Management Dialog
Control
Session information
Type
Table
OK
Edit
Delete
Upgrade
Help
Button
Button
Button
Button
Button
Default Value Description
N/A
Enabled
Enabled if the selected session uses the current format
Enabled
Disabled for this version.
Enabled
Lists the sessions available to the Nexus in the Session Name column and contains information about these sessions in the
Version, State, Owner, Start date, End date, Length, Time slice,
Detail level, and Comments columns.
Closes the Session Management dialog.
Launches the Edit Session Properties dialog.
Allows you to delete the selected session.
PerformaSure version 5.0 does not currently support session conversions from previous versions. This option is currently disabled.
Launches context-sensitive help.
Session Management Dialog—Context Menu
Control
Auto-Fit Column
Auto-Fit All
Columns
Hide Column
Show/Hide
Columns...
Edit Session
Delete Session
Upgrade Session
Type
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Default Value
Enabled
Enabled
Enabled
Enabled
Description
Resizes the column so that all values within the column are visible.
Resizes all columns so that all values within each column are visible.
Causes the column to no longer be displayed in the table.
Launches the Show/Hide Columns dialog. See “ Show/Hide
Launches the Edit Session Properties dialog. See “ Edit ” below
for more information.
Enabled if the selected session uses the current format
Enabled
Disabled for this version
Allows you to delete the selected session.
PerformaSure version 5.0 does not currently support session conversions from any previous version of PerformaSure.
The Upgrade Sessions option is disabled for this version.
PerformaSure Workstation 165
Session Management Dialog—Full Detail
The fields and controls in this dialog are described in more detail below.
Session Information
The list of sessions and details about these sessions are displayed in tabular form in the Session Management dialog. The columns in this table are described below.
Session Name
Lists the sessions available to the Nexus. By default, sessions are stored in the
sessions subdirectory of the PerformaSure home directory. See “ Changing the
Sessions Directory ” on page 430 for more information.
Version
Lists the version of PerformaSure that was used to record the session. If the session is obsolete or invalid, <unknown version> is listed in this field.
State
Lists Obsolete if it cannot be upgraded. This field is blank if the session was recorded using the current version . Invalid is listed in this column if
PerformaSure does not recognize the session file format.
Owner
Lists the username under which the session was initiated. If the session is obsolete or invalid, <unknown owner> is listed in this field.
Start date and End date
These columns list the date and time when recording began and ended.
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).
166 PerformaSure: User’s Guide
Comments
Lists any user-supplied description of the session. If the session is obsolete or invalid, the following message appears in this field:
This session was recorded by an unrecognized or unsupported version of PerformaSure.
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.
Note: This button is disabled if the session is obsolete, or invalid.
Figure 67
Figure 66 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 of the session file, or click
Cancel to close the dialog without making any deletions.
Figure 68
Figure 67 The Delete Session alert
Upgrade
PerformaSure version 5.0 does not currently support session conversions from any previous version of PerformaSure. The Upgrade Sessions option is disabled for this version.
PerformaSure Workstation 167
Context Menus in the Session Management Dialog
You can right-click anywhere in the table to make a context menu appear. The items in this menu are described below.
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 will be visible as you scroll through the dialog.
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 session details in the table.
Select Show/Hide Columns... to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated session detail.
Edit Session
Click Edit Session to launch the Edit Session Properties dialog (Figure 67). This
dialog contains two editable text fields, Session Name and Comments. You can use this dialog to change the name of the session, add comments to the session, or edit any existing comments.
Note: This menu item is disabled if the session is obsolete, or invalid.
Delete Session
When you click Delete Session, a Warning dialog appears asking you to confirm
the deletion of the selected session (Figure 68). Select Delete to confirm deletion
of the session file, or click Cancel to close the dialog without making any deletions.
168 PerformaSure: User’s Guide
Upgrade Session
PerformaSure version 5.0 does not currently support session conversions from any previous version of PerformaSure. The Upgrade Sessions option is disabled for this version.
PerformaSure Workstation 169
170 PerformaSure: User’s Guide
Chapter 7
PerformaSure Projects
Projects are one of the central points of control in PerformaSure. Each
PerformaSure Project is associated with a session. One important function of a
Project is to choose a set of browsers that you use to view a session’s data. One set of browsers may be appropriate for analyzing one session, while another set may work better for another session. Sometimes it’s 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 and adjust their settings to focus on the problems you have discovered. When you reload the Project, the saved browsers are ready to be used again. If you make changes to any of these settings, you may 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.
New Project Wizard
The New Project Wizard (Figure 69) allows you to view the sessions available to the
Nexus and details about these sessions, select and open a session in a new
171
PerformaSure Project, and perform session management tasks like deleting sessions and editing session properties.
Figure 69
Figure 68 The New Project Wizard
New Project Wizard—Summary
New Project Wizard—Summary
Control
Session information
Template
Open
Edit
Type
Table
Drop-down menu
Button
Button
Default Value
N/A
Default
Description
Lists the sessions available to the Nexus in the Session Name column and contains information about these sessions in the
Version, State, Owner, Start date, End date, Length, Time slice,
Detail level, and Comments columns.
Allows you to choose a template. The two static choices are None and Default. Any custom templates that you save in the
<performasure_home>/config/templates subdirectory will also appear in this list.
Opens the selected session in a new Project. See “ Open ” below for
more information.
Enabled if the selected session uses the current format
Enabled if the selected session uses the current format
Launches the Edit Session Properties dialog.
172 PerformaSure: User’s Guide
New Project Wizard—Summary
Control
Delete
Upgrade
Type
Button
Button
Cancel
Help
Button
Button
Default Value
Enabled
Disabled for this version.
Enabled
Enabled
Description
Allows you to delete the selected session.
PerformaSure version 5.0 does not currently support session conversions from previous versions. This option is currently disabled.
Closes the New Project Wizard.
Launches context-sensitive help.
New Project Wizard—Context Menu
Control
Auto-Fit Column
Type
Menu item
Auto-Fit All
Columns
Hide Column
Show/Hide
Columns...
Open Session
Edit Session
Delete Session
Upgrade Session
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Default Value
Enabled
Enabled
Enabled
Enabled
Enabled if the selected session uses the current format
Enabled if the selected session uses the current format
Enabled
Disabled for the current version.
Description
Resizes the column so that all values within the column are visible.
Resizes all columns so that all values within each column are visible.
Causes the column to no longer be displayed in the table.
Launches the Show/Hide Columns dialog. See “ Show/Hide
Opens the selected session in a new Project. See “ Open ” below
for more information.
Launches the Edit Session Properties dialog. See “ Edit ” below
for more information.
Allows you to delete the selected session.
PerformaSure version 5.0 does not currently support session conversions from previous versions.
PerformaSure Projects 173
New Project Wizard—Full Detail
Projects allow you to view, organize, and analyze 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.
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 open.
Tip: Click the Open Session in New Project button in the Project window’s 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 associated with a PerformaSure session file.
To create a new Project:
1.
Select a session compatible with PerformaSure 5.0 from the table in the New
Project Wizard. By default, the list of sessions is sorted by session name. Click on the header of another column in the table to sort the list of sessions based
on a different session detail. See “ Session Information ” below for more
information about the columns in this table.
2.
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 ” below for
more information about Project templates.
3.
Click Open. 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. PerformaSure will automatically append the extension .sure to the Project filename.
Note: PerformaSure version 5.0 does not currently support session conversions from any previous version of PerformaSure. The Upgrade Sessions option is disabled for this version.
Once you have created a new Project, you can add folders and browsers to it, organize the browsers into folders, and rename folders and browsers or delete
ones that you don’t need. See “ Browsers Area ” on page 190 for more information.
174 PerformaSure: User’s Guide
The fields and controls in the New Project Wizard are described below.
Session Information
The list of sessions and details about these sessions are displayed in tabular form in the New Project Wizard. The columns in this table are described below.
Session Name
Lists the sessions available to the Nexus. By default, sessions are stored in the
sessions subdirectory of the PerformaSure home directory. See “ Changing the
Sessions Directory ” on page 430 for more information.
Version
Lists the version of PerformaSure that was used to record the session. If the session is obsolete or invalid, <unknown version> is listed in this field.
State
Lists Obsolete if it cannot be upgraded. This field is blank if the session was recorded using the current version. Invalid is listed in this column if
PerformaSure does not recognize the session file format.
Owner
Lists the username under which the session was initiated. If the session is obsolete or invalid, <unknown owner> is listed in this field.
Start date and End date
These columns list the date and time when recording began and ended.
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. If the session is obsolete or invalid, the following message appears in this field:
This session was recorded by an unrecognized or unsupported version of PerformaSure.
PerformaSure Projects 175
Template
The Template drop-down menu allows you to select a template. Templates are sample Projects that are not associated with a session file. Templates are kept in the <performasure_home>/config/templates subdirectory. Since templates have the same structure as any PerformaSure Project file, you can add your own template
files to this directory; see “ Creating a Custom Project Template ” on page 100 for
details.
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.
Open
After you have selected a session from the list, click Open to open the session in a new PerformaSure Project. PerformaSure version 5.0 does not currently support session conversions from any previous version of PerformaSure.
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 existing comments.
Note: This button is disabled if the session is obsolete, or invalid.
Figure 70
Figure 69 The Edit Session Properties dialog
176 PerformaSure: User’s Guide
Delete
Clicking Delete displays a Warning dialog asking you to confirm the deletion of the selected session. Select Delete to confirm deletion of the session file, or click
Cancel to close the dialog without making any deletions.
Figure 71
Figure 70 The Delete Session alert
Upgrade
PerformaSure version 5.0 does not currently support session conversions from previous versions. This option is currently disabled.
Context Menus in the New Project Wizard
You can right-click anywhere in the table to make a context menu appear. The items in this menu are described below.
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 will be visible as you scroll through the dialog.
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 session details in the table.
Select Show/Hide Columns... to open a dialog that contains a group of checkboxes. Each checkbox controls the display of the associated session detail.
PerformaSure Projects 177
Open Session
Click Open Session to open the selected session in a new PerformaSure Project.
PerformaSure version 5.0 does not currently support session conversions from any previous version of PerformaSure. The Upgrade Sessions option is disabled for this version.
Edit Session
Click Edit Session to launch the Edit Session Properties dialog (Figure 70). This
dialog contains two editable text fields, Session Name and Comments. You can use this dialog to change the name of the session, add comments to the session, or edit any existing comments.
Note: This menu item is disabled if the session is obsolete, or invalid.
Delete Session
When you click Delete Session, a Warning dialog appears asking you to confirm
the deletion of the selected session (Figure 71). Select Delete to confirm deletion
of the session file, or click Cancel to close the dialog without making any deletions.
Upgrade Session
PerformaSure version 5.0 does not currently support session conversions from previous versions. This option is currently disabled.
The Project Window
The Project window (Figure 72) consists of a menu bar, a toolbar, a Session label,
and a Browsers area. The Browsers area contains a navigation pane and a details pane.
178 PerformaSure: User’s Guide
Figure 72
Figure 71 The Project window
Menus and Toolbar—Summary
Menu Bar
The Project window’s menu bar is located along the top of the Project window. The following tables describe the options available from the different menus in the menu bar.
Project Window Menu Bar—Project Menu
Menu Item
New Browser
New Folder
Open Session in
New Project
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.
Opens the New Project Wizard. See “ New Project Wizard ” on page 171 for more information.
PerformaSure Projects 179
Project Window Menu Bar—Project Menu
Menu Item Description
Open Project
Close
Save Project
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.
Save Project As
Save Project As
Template
Launches the Save dialog. Use this file chooser to save the Project and give it a name.
Launches the Save dialog with the
<performasure_home>/config/templates directory open. Use this
dialog to save the Project as a template. See “ Save Project As
Template ” on page 184 for more information.
Opens the selected browser windows.
Open Selected
Items
Delete Selected
Items
Deletes the selected browsers and/or folders from the Project.
Edit Properties of
Selected Item
Opens the Browser Properties dialog or the Folder Properties
dialog. See “ Edit Properties of Selected Item ” on page 185 for
more information.
Project Properties
Launches the Project Properties dialog. See “ Project Properties ” on page 186 for details.
Exit
PerformaSure
Closes all open Projects and browsers and shuts down the
Workstation.
Project Window Menu Bar—Tools Menu
Menu Item Description
Recording Control Window Launches the Recording Control window.
Session Management
Thresholds
Change Password
User Management
Performance Diagnostics
Options
Opens the Session Management dialog.
Launches the Threshold Editor.
Opens the Change Password dialog.
Launches the User Management window. This menu item is enabled if you have the required permissions.
Displays a submenu. See “ Performance Diagnostics ” on page 187 for more information.
Launches the Edit Options dialog.
180 PerformaSure: User’s Guide
Project Window Menu Bar—Windows Menu
Menu Item
Bring All To Front
[Switch to a Project window]
[Switch to a browser]
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.
Project Window Menu Bar—Help Menu
Menu Item
Help
About
Description
Launches context-sensitive help.
Opens a new window that displays product information about
PerformaSure.
Toolbar
Under the Project window’s 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
Button
New Browser
Save Project
Properties
Description
Clicking on the left-hand side of this button launches the New
Browser dialog. See “ New Browser ” on page 182 for details.
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 188 for details.
Saves the Project with its current settings. If you have never saved the Project, clicking this button launches the Save dialog.
Launches the Project Properties dialog. See “ Project
Properties ” on page 186 for details.
PerformaSure Projects 181
Project Window Toolbar
Button Description
Recording Control
Window
Open Session in New
Project
Session
Management
Launches the Recording Control window.
Opens the New Project Wizard. See “ New Project Wizard ” on page 171 for more information.
Opens the Session Management dialog.
Menus and Toolbar—Full Detail
Menu Bar—Project
New Browser
Select New Browser... to launch the New Browser dialog (Figure 73), which allows
you to select and open a new browser of a specific type and give it a name.
Keyboard accelerator: Ctrl-B.
Figure 73
Figure 72 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 98 for
more information about adding browsers to a Project.
Tip: Open multiple browsers in 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 folder’s
182 PerformaSure: User’s Guide
contents.
Keyboard accelerator: Ctrl+Shift-N.
Figure 74
Figure 73 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 folder’s icon over the target folder’s 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 174 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 PerformaSure5.0 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 Project’s state, including the settings in all browsers that have been added to the Project. If you have never saved the Project,
PerformaSure Projects 183
selecting this menu item launches the Save file chooser.
Keyboard accelerator: Ctrl-S.
Important: By default, Projects are saved in the PerformaSure5.0 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 browser’s 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. PerformaSure will add the .sure extension to the Project filename.
After you have clicked Save to save the new Project, you will continue to work in that Project. Any changes that 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.
Save Project As Template
Templates are sample Projects that are not associated with a session file.
Templates are kept in the <performasure_home>/config/templates subdirectory.
Since templates have the same structure as any PerformaSure Project file, you can add your own template files to this directory by selecting Save Project as
Template.... When you select this option, the Save file chooser opens automatically, allowing you to save a copy of the Project as a template in the
<performasure_home>/config/templates directory. Any Project files that you add to the templates subdirectory will appear as choices in the Template drop-down menu in the New Project Wizard.
Open Selected Items
The Open Selected Items menu item is disabled until you select one or more browser icons in the Browsers area. Choosing this menu item causes all selected browsers to be opened. Selecting a folder has no effect; to open browsers
184 PerformaSure: User’s Guide
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 75) 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 75
Figure 74 The Browser Properties dialog
Folder Properties Dialog
The Folder Properties dialog (Figure 76) allows you change the name of the
selected folder and add comments about the types of browsers that it contains.
PerformaSure Projects 185
Figure 76
Figure 75 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 77
Figure 76 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 Bar—Tools
Recording Control Window
Select Recording Control Window... to launch the Recording Control window.
See “ Recording Control Window ” on page 197 for more information about using
the controls in this window.
186 PerformaSure: User’s Guide
Session Management
Select Session Management... to open the Session Management dialog. See
“ Session Management ” on page 164 for more information about using this dialog.
Thresholds
Change Password
Select Change Password... to open the Change Password dialog. See “ Changing a
Password ” on page 154 for more information about using this dialog.
User Management
Select User Management... to launch the User Management window. See “ User
Management ” on page 154 for details about using this window.
Note: This menu item is disabled if you do not have the required permissions.
Performance Diagnostics
Selecting the Performance Diagnostics menu item displays a submenu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest Central is installed. When you select this option, the version of Spotlight
®
included with
Quest Central is launched.
Options
Selecting the Options... menu item launches the Edit Options dialog. See “ Edit
Options Dialog ” on page 247 for details about using this dialog.
Menu Bar—Windows
The Windows menu’s one static choice is Bring All To Front, which ensures that all open PerformaSure windows have a higher stacking order than non-
PerformaSure 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).
PerformaSure Projects 187
Menu Bar—Help
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 window’s toolbar is located directly below the menu bar.
Figure 78
Figure 77 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 182 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.
Save
Click the Save button to save the Project’s state, including the settings in all browsers that have been added to the Project. If you have never saved the Project,
Recording Control Window
Click the Recording Control Window button to launch the Recording Control
window. See “ Recording Control Window ” on page 197 for more information
about using the controls in this window.
188 PerformaSure: User’s Guide
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 174 to learn how to create a new
Project.
Session Management
Click the Session Management button to open the Session Management
dialog. See “ Session Management ” on page 164 for more information about using
this dialog.
Properties
Click the Properties button to launch the Project Properties dialog. See
“ Project Properties ” on page 186 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.
2.
Select a session from the Choose session list and click the Edit button. The Edit
Session Properties dialog will appear.
3.
Edit the Session Name field in the Edit Session Properties dialog and click OK.
4.
Click Close in the Session Management dialog.
PerformaSure Projects 189
Browsers Area
The Browsers area has two parts: the navigation pane and the details pane (see
Figure 79). 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 79
Figure 78 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 browser’s 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
” on page 98 for instructions on launching a new browser and
adding it to the Project. See “ Organizing the Navigation Pane ” on page 99 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.
190 PerformaSure: User’s Guide
Context Menus in the Browsers Area
You can right-click anywhere in the navigation pane of the Browsers area to make a context 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
New Folder
Project Properties
Select Project Properties... to launch the Project Properties dialog. See “ Project
Properties ” on page 186 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
Delete
When you select Delete, a dialog appears asking you to confirm the deletion of the selected Project item.
Figure 80
Figure 79 An attempt to delete a Project item produces this dialog
PerformaSure Projects 191
Edit Properties
Select Edit Properties... to launch the Folder Properties dialog. See “ Folder
Properties Dialog ” on page 185 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
Edit Properties
Select Edit Properties... to launch the Browser Properties dialog. See “ Browser
Properties Dialog ” on page 185 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 messages in the log file that was written when the data was collected. Click the icon to see a dialog containing the error messages.
Figure 81
Figure 80 The Session log dialog containing Nexus log file messages
192 PerformaSure: User’s Guide
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.
PerformaSure Projects 193
194 PerformaSure: User’s Guide
Chapter 8
Recording Control Window and Nexusctl
You can use the Recording Control window to see which Agents are enabled and connected to the Nexus, to select a saved configuration of recording settings, and to record a session. From the Recording Control window, you can also access the
Recording Settings dialog, which allows you to customize and save recording settings. The Recording Control window can be opened from the Startup window, or from the Tools menu in the Project window or in any browser.
Figure 82
Figure 81 The Recording Control window
The Recording Control window includes configuration controls for:
195
■
■
■
■
Selecting a recording settings configuration which you previously created,
named, and saved in the Recording Settings dialog. See “ Settings ” on page 199
for more information.
Specifying a name for the session and adding descriptive comments. See
” on page 199 and “ Comments ” on page 200 for more
information.
Starting to record a session and issuing a stop command. See “ Start
Recording ” on page 201 and “ Stop Recording ” on page 201 for more
information.
Viewing information about which Agents are enabled or disabled, connected or disconnected, and sorting the list of Agents based on different Agent
attributes. See “ Agents Table ” on page 220 for more information.
The tabs in the Recording Settings dialog include configuration controls for:
■ Adding a new recording settings configuration and giving it a name, or
■
■
Selecting whether recording settings from Quest Foglight are used. See “ Using
Foglight Recording Settings ” on page 208 for details.
Setting a duration for the session. See “ Limit Session Length ” on page 209 and
“ Time ” on page 209 for more information.
■
■
■
■
Setting the Time Slice Size. See “ Setting the Session Time Slice ” on page 87
and “ Time Slice Size ” on page 209 for more details about defining a Time
Slice.
Selecting an option that requests confirmation before a recording session is
stopped. See “ Confirm Before Stopping Recording ” on page 210 for more
information.
Selecting whether fewer than the maximum possible samples should be taken.
See “ Service Request Sampling
” on page 76, “ A Note on Sampling ” on page
211, “ Collect As Many Samples as Possible ” on page 212, and “ Collect Fewer
Samples to Reduce Overhead ” on page 212 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 212 and “ Full
Detail Recording Level ” on page 212 for more information.
Selecting whether advanced sampling settings are used. See “ Advanced
Sampling Dialog ” on page 221 for more information.
Specifying URL expressions and parameters, cookies, or headers for request
separation. See “ Service Request Separation
Setting filters for including or excluding requests. See “ Service Request
Filtering ” on page 84 for details.
196 PerformaSure: User’s Guide
■
The Advanced Sampling dialog includes configuration controls for:
■
Setting sampling weights. See “ Changing Sampling Weights ” on page 222 for
details.
Many of the recording controls listed above are also available in the command-
line utility nexusctl. See “ Recording with nexusctl
” on page 225 and “ Equivalent
Recording Control Options ” on page 241 for details.
Recording Control Window
Recording Control Window—Summary
Recording Control Window
Field or Control
Settings
Type
Drop-down menu
Default Value
Default Settings
Configure...
Button
Session Name
Append Date and
Time to Session
Name
Comments
Text field
Checkbox
Text field
The Recording Control window (Figure 82) has the following settings:
Enabled user
Checked
Blank
Description
Allows you to select a saved configuration of recording settings.
When you first open the Recording Control window, the Default
Settings recording configuration is selected by default. See
“ Settings ” on page 199 and “
Default Settings ” on page 206 for
more information.
Launches the Recording Settings tabbed dialog. The settings are
described in “ Recording Settings Dialog—Summary ”
Edit this field to give the session a descriptive name.
When checked, a full date string is appended to the Session Name.
Time Slice Size Info only 1 minute
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.
Recording Control Window and Nexusctl 197
Recording Control Window (Continued)
Field or Control
Detail Level
Owner
Status bar
Status
Elapsed time
Duration
Type
Info only
Info only
Progress bar
Info only
Info only
Info only
Default Value
Component user
Disabled
Idle
00:00:00
Unlimited
Start Recording
Stop Recording
Button
Button
Open Session
When Recording
Completes
Agent status summary
Agents table
Checkbox
Info only
Table
Enabled when not recording
Enabled when recording
Checked
N/A
Empty
Description
Shows the value of the recording level. Use the Recording
Settings dialog (Sampling tab) to change the value.
Lists the username under which session recording was initiated.
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.
Lists the recording status. The status changes when you start or stop recording.
Shows the elapsed time when session recording is in progress.
Displays either Unlimited or the session length that you specified.
See “ Status, Elapsed Time, and Duration ” below for more
information.
Initiates session recording. Messages are sent to all enabled
Agents instructing them to send data to the Nexus.
Stops recording.
When checked, the session’s Project window opens as soon as recording stops, allowing you to begin your investigation right away.
Lists the total number of Agents listed in the table and the number of disconnected Agents.
Has these fields: Enabled, Agent Name, Hostname, Type, Version,
and State. See “ Agents Table ” below for more information.
Recording Control Window—Full Detail
Using the Recording Control Window
The Recording Control window is used to perform tasks like starting and stopping session recording; selecting a recording configuration that defines what settings are used for a session; and viewing Agent status information.
The fields and controls in the Recording Control window are described below. The information displayed in some of these fields will vary depending on the recording settings that you have selected.
198 PerformaSure: User’s Guide
Settings
The Settings drop-down menu allows you to select a saved set of recording settings that are used when you start recording a new session. When you first launch the
Recording Control window, this menu includes the recording settings configuration
Default Settings, which is selected by default. See “ Default Settings ” on page 206
for more information about the settings included in this configuration.
Important: A recording settings configuration is required to record a session. If no configurations are listed in the Settings drop-down menu (for example, if the Default Settings configuration is accidentally deleted), you will not be able to record a session.
See “ Configuring Recording Settings ” on page 207 for
information about adding a new configuration.
Configure
The Configure... button launches the Recording Settings dialog, which allows you to modify the settings included in the recording settings configuration that is selected in the Settings drop-down menu; to remove a configuration; or to add a
new configuration. See “ Configuring Recording Settings ” on page 207, “
Foglight Recording Settings ” on page 208, “ Session Tab ” on page 208, “
” on page 211, “ Separators Tab ” on page 213, “
Filters Tab ” on page 216, and
“ Agents Tab ” on page 220 for more information.
Session Name
You can supply a name for the session in this editable text field. 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 similarly-named sessions. The file on disk has an extension psdat . Example:
LongRunningExample_2006-Mar-06_09-12-15.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.
Recording Control Window and Nexusctl 199
Comments
You can record reminders about the purpose of the session in the Comments text field. Information that you enter in the Comments field is saved after you finish recording a session and after you close the Recording Control window.
Time Slice Size
This area shows the value of the time slice that will be used when you begin recording (based on the recording settings configuration that you selected) or the time slice size that is currently being used for a session that is in progress. 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 Configure... > Session. See
values.
Detail Level
This area shows the value of the recording level that will be used when you begin recording (based on the recording settings configuration that you selected) or the recording level that is currently being used for a session that is in progress. The default setting is Component. To change this value, navigate to the Sampling tab of
the Recording Settings dialog by selecting Configure... > Sampling. See “ Sampling
Tab ” on page 211 for details.
Owner
This area lists the username of the user who logged in to the Workstation and launched the Recording Control window. If a session is currently being recorded, this area lists the username under which session recording was initiated.
Status Bar
If you specified the length of the session in the Recording Settings dialog and saved it as part of the recording settings configuration that you selected, the status bar shows the session’s recording progress. The status bar is disabled and reset when the session recording status Idle is displayed.
Status, Elapsed Time, and Duration
The text area below the status bar shows the recording status, the elapsed time, and the total duration of the session.
■ Status: this area displays Idle (the default value) or Recording. The status changes when you start or stop recording.
■ Elapsed time: this area shows the elapsed time when you are recording a session, or the value 00:00:00 when you are not recording.
200 PerformaSure: User’s Guide
■ Duration: when you are recording a session, this area displays either the session recording length that you specified in the Recording Settings dialog (and saved as part of the recording settings configuration that you selected) or the value Unlimited (if the session length is not specified). The value Unlimited is also displayed in this area when session recording is not in progress.
Open Session When Recording Completes
This checkbox is selected by default. When it is selected, the session’s 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 Recording 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.
Start Recording
The Start Recording button causes PerformaSure to start recording a session.
Clicking this button initiates recording by sending messages to all enabled Agents instructing them to send data to the Nexus.
Note: This button becomes the Stop Recording button when session recording is in progress.
Stop Recording
The Stop Recording button causes PerformaSure to stop collecting session data.
This button is enabled only when session recording is in progress.
Stop Recording Dialog
If you have selected the Confirm Before Stopping Recording checkbox in the
Session tab of the Recording Settings dialog, the dialog shown in Figure 83 appears
when the Stop Recording 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 210 for more
information.
Figure 83
Figure 82 This dialog may appear when you click the Stop button
Recording Control Window and Nexusctl 201
Agent Status Summary
Above the Agents table, there is a summary of the total number of Agents listed in the table and (in brackets) the number of disconnected Agents.
Agents Table
You can use this text area to view which Agents are active and connected to the
Nexus. 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 (connected or disconnected).
An Agent is enabled if a check mark ( ) appears in the Enabled column in the row that corresponds to it. Before you start recording, you can enable or disable
Agents using controls in the Agents tab of the Recording Settings dialog. See “ Agents
Tab ” on page 220 for details.
Recording Settings Dialog
The tabs in the Recording Settings dialog (Figure 84, Figure 85, Figure 86, Figure
87, and Figure 88) contain fields and controls for configuring the recording
settings for a new session and for saving these settings.
202 PerformaSure: User’s Guide
Recording Settings Dialog—Summary
Recording Settings dialog—All tabs
Field or Control
Settings
Add
Type
Drop-down menu
Button
Remove Button
Use Foglight
Recording
Settings for Filters and Separators
Checkbox
Default Value Description
Default Settings Allows you to select a recording settings configuration that you previously created and saved.
Enabled
Launches the Add Recording Setting dialog. See “ Configuring
Recording Settings ” on page 207 for information about adding
new recording settings configurations.
Enabled
Not selected
Allows you to delete the recording settings configuration that is currently selected in the Settings drop-down menu.
Uses Foglight recording settings for request separation and
filtering. See “ Using Foglight Recording Settings ” on page 208
for details.
Recording Settings dialog—Session tab
Field or Control
Limit Session
Length
Time
Type Default Value Description
Checkbox Not selected When checked, the Time spin boxes are enabled.
Disabled Set the duration of the session in hours, minutes, and seconds.
Time Slice Size
Incomplete
Request Timeout
Editable spinners
Dropdown menus
Editable spinners
1 minute
2 minutes
Set the aggregation interval for PerformaSure. See “ Setting the
Session Time Slice ” on page 87 for more details.
Confirm Before
Stopping
Recording
Checkbox Enabled
Set the incomplete request timeout. After this span of time has elapsed, the Nexus will classify a request as incomplete. See
“ Incomplete Request Timeout ” on page 209 for details.
If checked, an alert appears when you click the Stop Recording button in the Recording Control window. This alert does not appear if the session stops recording automatically based on the Session Length that you set.
Recording Control Window and Nexusctl 203
Recording Settings dialog—Sampling tab
Field or Control
Collect as Many
Samples as
Possible
Choose Fewer
Samples to
Reduce Overhead
Type
Radio button
Radio button
Component Detail
Recording Level
Radio button
Full Detail
Recording Level
Use Advanced
Sampling Settings
Checkbox
Advanced...
Radio button
Button
Default Value Description
Selected 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.
Not selected
Selected
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 ” on page 211.
Reduces overhead and simplifies the call trees in the Request Tree browser by collecting data only on bellwether Java EE classes and methods.
Not selected 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
<performasure_home>/config/client/instrumentation.config. See “ Full
Detail Recording Level ” on page 69 for more information.
Not selected
Enabled
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 ” on page 221 for details.
Recording Settings dialog—Separators tab
Field or Control
Separate HTTP requests that match, in order
Type
Table
Add new entry Button
Remove selection Button
Move selection up Button
Default Value Description
Empty Has these fields: URL Expression, Type, and
Parameters/Cookies/Headers. Contains descriptions of HTTP requests that should be separated based on GET or POST parameters, cookies,
or HTTP headers. See “ Separators Tab ” on page 213 for details.
Enabled
Disabled
Disabled
Adds a new entry to the list.
Removes the selected entry from the list.
Moves the selected entry up the list.
204 PerformaSure: User’s Guide
Recording Settings dialog—Separators tab (Continued)
Field or Control
Move selection down
Maximum length of value used for separation
Type
Button
Spinner box
Default Value Description
Disabled Moves the selected entry down the list.
32 Allows you to set the maximum length (in characters) for values used for performing request separation. This maximum is used for all request separation parameters. Its default setting is 32; it can be set to any value between 1 and 512.
Recording Settings dialog—Filters tab
Field or Control
Include or exclude requests that match, in order
Type
Table
Add new entry Button
Remove selection Button
Move selection up Button
Move selection down
Button
All other requests should be
Dropdown menu
Included
Default Value Description
Contains default filters
Contains filters that describe conditions under which requests should
Enabled
Disabled
Disabled
Disabled
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 select whether service requests that do not match the entries in the table are included or excluded.
Recording Settings dialog—Agents tab
Field or Control
Agent status summary
Agents table
Type
Info only
Table
Select All
Deselect All
Reset Agent List
Button
Button
Button
Default Value Description
N/A Lists the total number of Agents listed in the table and the number of disconnected Agents.
Empty Has these fields: Enabled, Agent Name, Hostname, Type, Version, and
State. See “ Agents Table ” on page 220 for more information.
N/A
N/A
Selects all Agents in the list.
Deselects all Agents in the list.
Enabled Resets the Agent list.
Recording Control Window and Nexusctl 205
Recording Settings dialog—Agents tab (Continued)
Field or Control
Automatically enable newly discovered Agents
Type
Checkbox
Default Value Description
Checked Toggles whether Agents that connect to the Nexus after you start recording are enabled.
Recording Settings Dialog—Full Detail
Default Settings
When you first open the Recording Settings dialog, the Settings drop-down menu lists the recording settings configuration Default Settings. This configuration consists of the following settings:
■ All tabs:
• Use Foglight Recording Settings for Filters and Separators checkbox: deselected.
■ Session tab:
• Limit Session Length checkbox: not selected
• Time editable spin boxes: disabled
• Time Slice Size associated drop-down menus: set to 1 minute
• Incomplete Request Timeout editable spin boxes: set to 2 minutes
• Confirm Before Stopping Recording checkbox: selected
■
■
■
■
Sampling tab:
• Collect as Many Samples as Possible radio button: selected
• Component Detail Recording Level radio button: selected
• Use Advanced Sampling Settings checkbox: not selected
Separators tab:
• Separate requests that match, in order table: empty
• Maximum length of value used for separation spin box: set to 32
Filters tab:
• Include or exclude requests that match, in order table: includes the default filters
(see “ Service Request Filtering ” on page 219 for details)
• All other requests should be drop-down menu: set to Included
Agents tab:
• Agents table: lists the Agents in your monitored environment, all of which are enabled by default
• Automatically enable newly discovered Agents checkbox: selected
206 PerformaSure: User’s Guide
You can make changes to the Default Settings configuration. See the instructions in
“ To modify an existing recording settings configuration: ” on page 207 for details.
Note: The settings included in the Default Settings configuration are also included by default in each new configuration that you add. In addition, if all configurations listed in the Settings drop-down menu are deleted, the settings in the tabs of the Recording Settings dialog revert to the default settings listed above.
Configuring Recording Settings
You can create and save multiple recording settings configurations in the Recording
Settings dialog. This allows you to easily switch between configurations if, for example, you frequently record sessions at different detail levels or with a different set of Agents.
To create a new recording settings configuration:
1.
Click the Add button at the top of the Recording Settings dialog. The Add
Recording Setting dialog appears.
2.
Specify a name for the configuration in the Setting Name text field and then click OK. The new configuration includes the default recording settings, and is automatically selected in the Settings drop-down menu.
Note: You must select a unique name for each new configuration. An error dialog will appear if you attempt to add a new configuration that has the same name as an existing configuration.
3.
Configure the settings in the tabs of the Recording Settings dialog as desired. See
“ Session Tab ” on page 208, “
” on page 211, “ Separators Tab ” on page 213, “
” on page 216, and “ Agents Tab ” on page 220 for more
information.
4.
Click the Apply button at the bottom of the Recording Settings dialog to save the current selections in all tabs of the dialog as part of the new configuration.
To modify an existing recording settings configuration:
1.
Select the configuration from the Settings drop-down menu.
2.
Configure the settings in the tabs of the Recording Settings dialog as desired. See
“ Session Tab ” on page 208, “
” on page 211, “ Separators Tab ” on page 213, “
” on page 216, and “ Agents Tab ” on page 220 for more
information.
3.
Click the Apply button at the bottom of the Recording Settings dialog to save the changes that you have made to the configuration.
Recording Control Window and Nexusctl 207
Using Foglight Recording Settings
The Use Foglight Recording Settings for Filters and Separators checkbox at the top of the Recording Settings dialog allows you to select whether PerformaSure will use recording settings for request filtering and separation from Quest
Foglight. When this checkbox is selected, the controls in the Separators and
Filters tabs of the Recording Settings dialog are disabled. You can also configure
To use Foglight recording settings:
1.
Select the recording settings configuration with which you would like to use
Foglight recording settings for request filtering and separation, or create a new
configuration with which to include this option. See “ Configuring Recording
Settings ” on page 207 for details about creating a new recording settings
configuration or modifying an existing one.
2.
Select the Use Foglight Recording Settings for Filters and Separators checkbox.
3.
Click the Apply button at the bottom of the Recording Settings dialog.
Session Tab
Figure 84
Figure 83 The Recording Settings dialog showing the Session tab
208 PerformaSure: User’s Guide
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.
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 browser’s 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 browser’s 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.
Recording Control Window and Nexusctl 209
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.
Note: Incomplete Request Timeout must be set to a value between 0 and 24 hours (1440 minutes). An error dialog will appear if you specify a value for this setting that is higher than 1439 minutes and 59 seconds.
Confirm Before Stopping Recording
The Confirm Before Stopping Recording checkbox is selected by default.
When this checkbox is selected, the dialog shown in Figure 83 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.
210 PerformaSure: User’s Guide
Sampling Tab
Figure 85
Figure 84 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.
You can 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 request’s 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
Recording Control Window and Nexusctl 211
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, tracking each request using Tag and Follow 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 tracked using Tag and Follow 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 Java EE
classes. See “ Component Instrumentation ” on page 445 for a description and a
list of the Java EE components that are tracked by PerformaSure when using this option.
Full Detail Recording Level
Choose Full Detail Recording Level to fully instrument your application.
212 PerformaSure: User’s Guide
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 221 for details.
Separators Tab
Figure 86
Figure 85 The Recording Settings dialog showing the Separators tab
Important: See “ Service Request Separation ” on page 77 for information
about how request separation works in PerformaSure.
Note: You can also enable separation through the nexusctl utility. For more
information, see “ nexusctl—Summary ” on page 226.
Recording Control Window and Nexusctl 213
List of Requests to Separate
The Separators tab contains one table: Separate HTTP requests that match,
in order. In this table, you list the URL expressions and GET and POST parameters, cookies, and HTTP headers that will be used to match the requests that should be separated. The order of this list is important. PerformaSure will attempt to match service requests beginning at the top of the list of separators and then will move down the list. The first separator that includes a URL that matches a request is used; all other separators are ignored for that request.
Note: Requests will be separated if they match any of the listed parameters.
This means that a request may be separated based on more than one parameter.
There are four columns in this table:
■ The first column contains checkboxes. Select a checkbox to enable a separator, or deselect it to disable the separator. No checkboxes are visible when the table is empty.
■
■
URL Expression: in this column, enter the string of characters that is used to match the base URL. Expressions are case-insensitive and will match on partial strings.
Type: use the drop-down menu in this column to specify whether the URL
Expression is a literal expression (Literal) or a regular expression (RegEx).
Note:
■
Literal strings are referred to as literal expressions in the User’s Guide. See
“ Appendix D—Regular Expressions ” on page 489 for more information
about using regular expressions.
Parameters/Cookies/Headers: In this column, enter the specific parameters that are used to separate requests. The parameters on which requests are separated can be GET or POST parameter, cookie, or HTTP headers names or name-value pairs. Names and name-value pairs are matched case-insensitively. If you specify several parameters in this column, they must be entered as a list of comma-separated values.
Note that if you include leading or trailing spaces or spaces around the = sign in a name-value pair, they will be removed before parameters are matched to requests. However, spaces embedded in GET or POST parameters, cookies, or HTTP headers will be preserved.
Important: POST parameter separation is only support for requests that use Content-Type: x-www-form-urlencoded . This means that, when performing POST parameter request separation,
PerformaSure will ignore requests that use Content-Type: multipart/form-data .
214 PerformaSure: User’s Guide
Important: PerformaSure does not collect certain cookie attributes and reserved cookie names.
The following cookie attributes are not collected:
• Comment
• CommentURL
• Discard
• Domain
• Expires
• Max-Age
• Path
• Post
• Secure
• Version
All cookie names that begin with $ are reserved and will be ignored by PerformaSure because they should only be used by web servers and user-agents.
Maximum length of value used for separation
The Maximum length of value used for separation spinner box allows you to set the maximum length (in characters) of values used for performing request separation. This maximum applies to all request separation parameters. It is set to
32 characters by default but can be set to any value between 1 and 512. Values over 512 characters long will be truncated before being considered for request separation.
Modifying the List of Separators
To add a new entry to the table:
1.
Click the Add new entry button and is selected.
Note:
. The new entry is added to the table
New separators are enabled by default.
2.
Double-click the field in the URL Expression column to make it editable.
Enter a literal or regular expression for the base URL.
3.
By default, RegEx is selected from the drop-down menu in the Type column.
Select Literal from this drop-down if you entered a literal expression in the
URL Expression column.
4.
Double-click the field in the Parameters/Cookies/Headers column to make it editable. Enter a single parameter or a comma-separated list of parameters.
5.
Set the location of the new entry within the list of separators by using the
Move selection up button or the Move selection down button.
Recording Control Window and Nexusctl 215
6.
Click the Apply button to save your changes as part of the recording settings configuration.
To modify an entry:
1.
Edit the entry in the table:
• Select or deselect the checkbox in the left-hand column if you want to enable or disable that entry.
• Double-click the field in the URL Expression or the field in the
Parameters/Cookies/Headers column if you want to make it editable.
• Use the drop-down menu in the Type column if you want to change the expression type for the entry in the URL Expression column.
2.
Click the Apply button to save your changes as part of the recording settings configuration.
To remove an entry:
1.
Select the row that you want to remove by clicking on it.
2.
Click the Remove selection button .
3.
Click the Apply button to save your changes as part of the recording settings configuration.
To change the location of an entry in the list:
1.
Select the row that you want to move by clicking on it.
2.
Use the Move selection up button or the Move selection down button
3.
to move the entry to the desired location in the list.
Click the Apply button to save your changes as part of the recording settings configuration.
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.
216 PerformaSure: User’s Guide
Important: Requests for .css, .gif, .jpeg, .js, .png, and .ico 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 87
Figure 86 The Recording Settings dialog showing the default settings in the Filters tab
Filtering allows you to configure PerformaSure to reduce traffic between Agents and the Nexus, which decreases both overhead and storage requirements. In the
Filters tab, you can configure filtering to include certain requests and exclude others.
Include or exclude requests that match, in order
The order of the filters that you set in the Include or exclude requests that
match, in order table 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.
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).
Recording Control Window and Nexusctl 217
The first column contains checkboxes that you can select or deselect to enable or disable the filters 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. See “ Appendix D—Regular Expressions ” on page
489 for more information about using regular expressions.
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. See the entry
“ dollar sign ($) ” on page 491 for more information about using
this metacharacter in a regular expression.
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.
218 PerformaSure: User’s Guide
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.
Service Request Filtering
Many types of requests can safely be ignored once you have determined that they have no costly effects on performance. Among these are image files that are loaded via individual HTTP requests, and other static files whose loading times can be assumed to be constant. By default, PerformaSure excludes requests
for .gif, .jpg, .css, .png, .js, and .ico files (see Figure 87).
After you have measured the request times for certain objects and you are satisfied that there are no problems with them, you can use service request filtering to remove them from view.
Recording Control Window and Nexusctl 219
Agents Tab
Figure 88
Figure 87 The Recording Settings dialog showing the Agents tab
Agent Status Summary
Above the Agents table, there is a summary of the total number of Agents listed in the table and (in brackets) the number of disconnected Agents.
Agents Table
You can use this text area to view which Agents are active and connected to the
Nexus 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.
An Agent is enabled if the checkbox next to it is selected. Before you start recording, you can select or deselect the checkboxes in the Agent table to enable or disable individual Agents, or use the Select All or Deselect All buttons. See
“ Select All ” and “ Deselect All ” below for more information about these buttons.
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:
220 PerformaSure: User’s Guide
• Version—the version number of the Agent. For example, 5.0.
• State—whether the Agent is connected or disconnected.
Select All
Click the Select All button to select all Agents in the list. This button is disabled if all Agents are currently selected.
Deselect All
Click the Deselect All button to deselect all Agents in the list. This button is disabled if no Agents are currently selected.
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.
Automatically Enable Newly Discovered Agents
This checkbox allows you to toggle whether Agents will be enabled if they connect to the Nexus while session recording is in progress.
Advanced Sampling Dialog
Advanced Sampling Dialog—Summary
The Advanced Sampling dialog (Figure 89) 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
Type
Table
Default Value Description
Empty Has these fields: Expression, Type, and Weight. Contains entries
describing sampling weight overrides. See “ Set Sampling Weights For
Requests That Match, In Order ” below for details.
Recording Control Window and Nexusctl 221
Advanced Sampling Dialog (Continued)
Control
Weight Of All
Other Requests
Type
Info only
Add new entry Button
Remove selection Button
Move selection up Button
Move selection down
Button
Default Value Description
1.00
Shows the sampling weight remaining for all other requests.
Enabled
Disabled
Disabled
Disabled
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.
Advanced Sampling Dialog—Full Detail
Figure 89
Figure 88 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.
222 PerformaSure: User’s Guide
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 track every tenth request using Tag and Follow.
Normally, there will be a mix of different request names, such as commitorder , enterstore , and so on. The Nexus records the frequency of occurrence 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 tracked. 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 dialog’s Set sampling weights for requests
that match, in order table, you would 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 won’t be tracked using Tag and Follow, so you won’t 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.
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 specify 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. For new entries, this column is empty by default. See
Recording Control Window and Nexusctl 223
“ Appendix D—Regular Expressions ” on page 489 for more information about
using regular expressions.
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. See the entry
“ dollar sign ($) ” on page 491 for more information about using
this metacharacter in a regular expression.
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.
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.00. 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.
224 PerformaSure: User’s Guide
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 from 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 from nexusctl that are analogous to the controls in the Workstation’s Recording Control window, Recording Settings dialog,
and in the Workstation. See “ Using nexusctl ” on page 46 for a complete list of
options available from nexusctl.
Recording Control Window and Nexusctl 225
nexusctl—Summary
Recording Options in nexusctl
Option nexusctl startrecording nexusctl stoprecording
Type
Recording option
Recording option
Default Value Description
Records with
1 minute time slice
N/A
Starts recording a new session, which is given the default name
Nexus_<timestamp>.
Stops recording the current session.
Parameters for nexusctl start-recording
Parameter Type
-user username Login parameter
-pwd password Login parameter
-n “NAME” Basic recording parameter
-a Basic recording parameter
-com
“COMMENTS”
Basic recording parameter
Agent parameter
-ad
“AGENTNAME”
-ae
“AGENTNAME”
-i
-l nnn
Agent parameter
Session parameter
Session parameter
-t nnn Session parameter
Default Value user
Blank
Nexus
Set
Not set
Not set
Not set
Set
Not set
1 minute
Description
Overrides the default username with the name that you specify.
Allows you to specify a password.
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 session’s filename.
Allows you to supply comments about the session.
Specifies which Agents are to be disabled. See “ -ad
“AGENTNAME” ” below for details.
Specifies which Agents are to be enabled. See “ -ae
“AGENTNAME” ” below for details.
Allows you to record indefinitely. If you do not specify either -i or
-l, -i is applied by default.
Sets the duration of the session. See “ -l nnn ” below for details.
Sets the time slice for the session.
226 PerformaSure: User’s Guide
Parameters for nexusctl start-recording (Continued)
Parameter
-irt nnn
-c
-f
-s nn
-swr nnn
“expression”
Type
Session parameter
Sampling parameter
Sampling parameter
Sampling parameter
Sampling parameter
Default Value
2 minutes
Set
Not set
100
Not set
-swl nnn
“expression”
Sampling parameter
Not set
Not set
Description
Sets the incomplete request timeout for the session. See “ -irt nnn ” below for details.
Records at component detail level.
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.
literal expressions.
Separates requests using regular expressions. See “ -srr
“URIregex” “PARAM” ” below for details.
-srr “URIregex”
“PARAM”
-srl “URIliteral”
“PARAM”
Request separation parameter
Request separation parameter
-sl nn
-fir
“expression”
-fil
“expression”
-fxr
“expression”
-fxl
“expression”
-ia
-xa
Request separation parameter
Filtering parameter
Filtering parameter
Filtering parameter
Filtering parameter
Filtering parameter
Filtering parameter
Not set
32
Not set
Not set
Not set
Not set
Set
Not set
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).
Recording Control Window and Nexusctl 227
Parameters for nexusctl start-recording (Continued)
Parameter
-r URI
Type
Connection parameter
Default Value
Not set
-o “/path/to/ filename.ext”
-fgl
Recording settings parameter
Recording settings parameter
N/A
Not set
Description
Sets the connection URI for the Nexus when it is on a different machine than the nexusctl script or for a local Nexus that does not use the default port.
overriding a recording settings file.
Uses Foglight recording settings for request separation and
filtering. See “ -fgl ” below for details.
Parameters for nexusctl stop-recording
Parameter Type
-user username Login parameter
-pwd password Login parameter
-r URI Connection parameter
Default Value Description user Overrides the default username with the name that you specify.
Blank
Not set
Allows you to specify a password.
Sets the connection URI for the Nexus when it is on a different machine than the nexusctl script or for a local Nexus that does not use the default port.
Options for Showing Connections to the Nexus
Option nexusctl showconnections nexusctl showconnections-xml nexusctl resetagent-list
Type
Display option
Display option
Display option
Default Value Description
N/A Lists all connections to the Nexus in a table.
N/A
N/A
Lists all connections to the Nexus in XML format.
Resets the list of Agents, removing the entries for Agents that have been disconnected. This command is disabled during recording.
228 PerformaSure: User’s Guide
Parameters for nexusctl show-connections, show-connections-xml, and nexusctl reset-agent-list
Parameter Type
-user username Login parameter
-pwd password Login parameter
-r URI Connection parameter
Default Value Description user Overrides the default username with the name that you specify.
Blank
Not set
Allows you to specify a password.
Sets the connection URI for the Nexus when it is on a different machine than the nexusctl script or for a local Nexus that does not use the default port.
nexusctl—Full 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 default name given to the session is Nexus_<timestamp>.
The default time slice for recording a session using start-recording is one
minute, as it is in the Recording Settings dialog’s Session tab. See “ -t nnn ” below
and “ Setting the Session Time Slice ” on page 87 for more information about the
time slice size.
nexusctl stop-recording
■
■
The stop-recording control stops recording the current session. There are three optional parameters for nexusctl stop-recording :
-user Your PerformaSure login username.
-pwd Your PerformaSure login password (if you have set one—otherwise omit this parameter).
■ -r Sets the connection URI for the Nexus when it is on a different machine than the one on which the nexusctl script is located or for a local Nexus that does not use the default port.
Recording Control Window and Nexusctl 229
Example usage: nexusctl stop-recording -user lisa -pwd oboe789 -r your.remote.host.com:42705
Important: The nexusctl script must not be moved from the directory in which it was installed.
Parameters for nexusctl start-recording
Note: The parameters -swr , -srr , -fir , and -fxr (described below) use
regular expressions. See “ Appendix D—Regular Expressions ” on page
489 for more information about using regular expressions.
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. See the entry
“ dollar sign ($) ” on page 491 for more information about using
this metacharacter in a regular expression.
Login Parameters
-user username
The parameter -user username overrides the default username with username .
This parameter is optional for all nexusctl commands except start (which launches the Nexus in the background), where it is not required. If you do not specify a username, PerformaSure will assume a default username of user .
-pwd password
The parameter -pwd password allows you to specify a password. This parameter is optional for all nexusctl commands except start (which launches the Nexus in the background), 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.
230 PerformaSure: User’s Guide
Basic Recording Parameters
-n “NAME”
The parameter -n “NAME” allows you to provide a customized name for the session. Specifying the parameter -n “NAME” 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 session name.
-com “COMMENTS”
The parameter -com “COMMENTS” allows you to supply comments about the session that you are recording or are about to record. It is recommended that you place double quotes around your comments.
Agent Parameters
-ad “AGENTNAME”
The parameter -ad “AGENTNAME” allows you to specify which Agents will be disabled for the current session only. AGENTNAME is a unique name given to each
Agent, which you can specify in <performasure_home>/config/agent.config. It is recommended that you place double quotes around Agent names.
You only need to specify which Agents are to be disabled using -ad
“AGENTNAME” . Unless they are specified to be disabled, PerformaSure will record from any Agents that are connected to the Nexus and from any new Agents that connect to the Nexus after you start recording. You can specify multiple -ad entries for a single nexusctl command.
-ae “AGENTNAME”
The parameter -ae “AGENTNAME” allows you to specify which Agents will be enabled for the current session only. AGENTNAME is a unique name given to each
Agent, which you can specify in <performasure_home>/config/agent.config. It is recommended that you place double quotes around Agent names.
You only need to specify which Agents are to be enabled using -ae
“AGENTNAME” . When you include -ae parameters in a start-recording command, PerformaSure will not record from any Agents that are connected to the Nexus or from any new Agents that connect to the Nexus after you start
Recording Control Window and Nexusctl 231
recording unless they are specified to be enabled. You can specify multiple -ae entries for a single nexusctl command.
Note: If you do not specify either -ad “AGENTNAME” parameters or -ae
“AGENTNAME” parameters with a start-recording command, Agents that connect to the Nexus after you start recording are automatically enabled.
Caution: Do not include both -ad “AGENTNAME” parameters and -ae
“AGENTNAME” parameters in a start-recording command. If you include both -ad and -ae parameters, only the last parameter specified will affect which Agents are enabled or disabled.
Session Parameters
-i
The parameter -i allows you to record indefinitely. To stop recording, issue the command nexusctl stop-recording later on.
Note: If you do not specify either -i or -l , -i is applied by default.
-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.
232 PerformaSure: User’s Guide
-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 Java EE components are recorded, which gives you an overall picture of the application.
See “ Component Instrumentation ” on page 445 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.
Recording Control Window and Nexusctl 233
-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 User’s Guide.
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. It is recommended that you place double quotes around the expressions used to set sampling weights.
Request Separation Parameters
Important: See “ Service Request Separation ” on page 77 for information
about how request separation works in PerformaSure.
-srr “URIregex” “PARAM”
The parameter -srr “URIregex” “PARAM” separates requests using a regular expression. For example:
-srr “estore/portal-.*\.jsp” “country” “user-agent”
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: only the first -srr entry that a URL matches will be used for request separation. All other entries will be ignored for that request.
The parameters on which requests are separated can be GET or POST parameter, cookie, or HTTP header names or name-value pairs. You can specify any combination of GET or POST parameters, cookies, and HTTP headers in a single -srr entry. If you provide multiple request separation parameters, they
234 PerformaSure: User’s Guide
must be separated by spaces (as shown in the example above). The expressions and parameters used for request separation are case-insensitive.
Important: POST parameter separation is only support for requests that use Content-Type: x-www-form-urlencoded . This means that, when performing POST parameter request separation,
PerformaSure will ignore requests that use Content-Type: multipart/form-data .
Important: PerformaSure does not collect certain cookie attributes and reserved cookie names.
The following cookie attributes are not collected:
• Comment
• CommentURL
• Discard
• Domain
• Expires
• Max-Age
• Path
• Post
• Secure
• Version
All cookie names that begin with $ are reserved and will be ignored by PerformaSure because they should only be used by web servers and user-agents.
If you enter leading or trailing spaces with request separation parameters or include spaces around the = sign in a name-value pair, these spaces will be removed before parameters are matched to requests. However, spaces embedded in GET or POST parameters, cookies, or HTTP headers will be preserved.
Note: Requests will be separated if they match any of the parameters that you specify with an -srr entry. This means that a request may be separated based on more than one parameter.
Note: It is recommended that you place double quotes around the expressions used to separate requests.
-srl “URIliteral” “PARAM”
The parameter -srl “URIliteral” “PARAM” separates requests using a literal expression. For example:
-srl “littlebusiness/welcome.jsp” “cmd=login” “lang” “LoginName”
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
Recording Control Window and Nexusctl 235
an indication of priority: only the first -srl entry that a URL matches will be used for request separation. All other entries will be ignored for that request.
The parameters on which requests are separated can be GET or POST parameter, cookie, or HTTP header names or name-value pairs. You can specify any combination of GET or POST parameters, cookies, and HTTP headers in a single -srl entry. If you provide multiple parameters, they must be separated by spaces (as shown in the example above). The expressions and parameters used for request separation are case-insensitive.
Important: POST parameter separation is only support for requests that use Content-Type: x-www-form-urlencoded . This means that, when performing POST parameter request separation,
PerformaSure will ignore requests that use Content-Type: multipart/form-data .
Important: PerformaSure does not collect certain cookie attributes and reserved cookie names.
The following cookie attributes are not collected:
• Comment
• CommentURL
• Discard
• Domain
• Expires
• Max-Age
• Path
• Post
• Secure
• Version
All cookie names that begin with $ are reserved and will be ignored by PerformaSure because they should only be used by web servers and user-agents.
If you enter leading or trailing spaces with request separation parameters or include spaces around the = sign in a name-value pair, these spaces will be removed before parameters are matched to requests. However, spaces embedded in GET or POST parameters, cookies, or HTTP headers will be preserved.
Note: Requests will be separated if they match any of the parameters that you specify with an -srl entry. This means that a request may be separated based on more than one parameter.
Note: It is recommended that you place double quotes around the expressions used to separate requests.
236 PerformaSure: User’s Guide
-sl nn
The parameter -sl nn sets the maximum length (in characters) of values used for performing request separation. The range for nn is 1 to 512; the default setting is
32. Values over 512 characters long will be truncated before being considered for request separation.
Note: This is a global entry that will be applied to all request separation parameters.
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, .jpg, .js, .png, and .ico files are excluded by default. If you want to include any of these requests, you must specify -fir options that have the same pattern as the excluded requests. For example, to include .css
files, you would specify
-fir “\.(css|Css|CSS)$” because the pattern \.(css|Css|CSS)$ exactly matches the pattern used in the default exclude filter for this type of request.
See nexusctl help (enter the command nexusctl from the
<performasure_home>\scripts directory) for a complete list of the exclude filters that are applied by default.
-fir “expression”
The parameter -fir “expression” filters requests for inclusion using a regular
expression. See “ Appendix D—Regular Expressions ” on page 489 for more
information about using regular expressions.
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”
Recording Control Window and Nexusctl 237
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. It is recommended that you place double quotes around the expressions used to filter requests.
-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.
Connection Parameters
-r URI
The parameter -r URI sets the connection URI for the Nexus. For example:
-r your.remote.host.com:42705
Use this flag to set the connection URI for the Nexus when it is on a different machine than the one on which the nexusctl script is located or for a local Nexus that does not use the default port.
Important: The nexusctl script must not be moved from the directory in which it was installed.
238 PerformaSure: User’s Guide
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.
Important: Place quotation marks around any values in the recording settings file that contain spaces. For example:
-com “Comments about a new session”
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.”
Using Foglight Recording Settings
-fgl
Including the parameter -fgl with the start-recording command causes
PerformaSure to use recording settings from Quest Foglight and ignore all other settings for request filtering and separation, whether they are specified on the command line or in a recording settings file.
Options for Showing Connections to the Nexus
Showing Connections to the Nexus nexusctl show-connections Shows all connections to the Nexus. This command lists all connected users (for example, nexusctl or the Workstations) and
PerformaSure Agents in tabular form in the shell or DOS command window. The tables in which the enabled and disabled Agents are listed include entries indicating whether the Agents are connected or disconnected.
nexusctl show-connections-xml Shows all connections to the Nexus. This command lists all connected users (for example, nexusctl or the Workstations) and
Recording Control Window and Nexusctl 239
all known, connected, included, and excluded PerformaSure Agents in XML format in the shell or DOS command window.
■
■
There are three optional parameters for nexusctl show-connections and show-connections-xml :
-user Your PerformaSure login username.
-pwd Your PerformaSure login password (if you have set one—otherwise omit this parameter).
■ -r Sets the connection URI for the Nexus when it is on a different machine than the one on which the nexusctl script is located or for a local Nexus that does not use the default port.
Example usage: nexusctl show-connections -user lisa -pwd oboe789 -r your.remote.host.com:42705
Important: The nexusctl script must not be moved from the directory in which it was installed.
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. There are three optional parameters for nexusctl reset-agent-list :
-user Your PerformaSure login username.
-pwd Your PerformaSure login password (if you have set one—otherwise omit this parameter).
■ -r Sets the connection URI for the Nexus when it is on a different machine than the one on which the nexusctl script is located or for a local Nexus that does not use the default port.
Example usage: nexusctl reset-agent-list -user lisa -pwd oboe789 -r your.remote.host.com:42705
Important: The nexusctl script must not be moved from the directory in which it was installed.
240 PerformaSure: User’s Guide
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.
Specify which
Agents are to be disabled.
nexusctl
-a
-ad “AGENTNAME”
Specify which
Agents are to be enabled.
Record at the component detail level.
-ae “AGENTNAME”
-c
Supply comments about a session.
-com “COMMENTS”
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.
Enabled (column in
Agents table)
Enabled (column in
Agents table)
Component Detail
Recording Level (radio button)
Comments (text field) nexusctl: enter this parameter and specify the Agent names with the start-recording option.
Workstation: deselect the checkboxes in the
Enabled column of the table in the
Recording Control window to disable the corresponding Agents. Select the
Automatically enable newly connected
Agents checkbox if you want Agents that connect to the Nexus during recording to be enabled.
nexusctl: enter this parameter and specify the Agent names with the start-recording option.
Workstation: select the checkboxes in the
Enabled column of the table in the
Recording Control window to enable the corresponding Agents. Select the
Automatically enable newly connected
Agents checkbox if you want Agents that connect to the Nexus during recording to be enabled.
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.
Recording Control Window and Nexusctl 241
Recording controls in the Workstation and nexusctl (Continued)
Action
Record at the full detail level.
Use recording settings from
Quest Foglight.
Filter requests for inclusion using literal expressions.
Filter requests for inclusion using regular expressions.
Filter requests for exclusion using literal expressions.
nexusctl
-f
-fgl
-fil “expression”
-fir “expression”
-fxl “expression”
Workstation
Full Detail Recording
Level (radio button)
Use Foglight Recording
Settings for Filters and
Separators (checkbox)
Filters tab of the
Recording Settings dialog
Filters tab of the
Recording Settings dialog
Filters tab of the
Recording Settings dialog
How to use 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 with the startrecording option. All other request filtering and separation parameters will be ignored.
Workstation: select the checkbox in the
Recording Settings dialog. All controls in the
Separators and Filters tabs will be disabled.
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.
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 dropdown menu in the Type column and click
OK.
242 PerformaSure: User’s Guide
Recording controls in the Workstation and nexusctl (Continued)
Action
Filter requests for exclusion using regular expressions.
Record indefinitely
Include all other requests (after filtering certain requests).
Set the incomplete request timeout for the session.
Set the length of the session.
Reset the list of
Agents so that only currently connected Agents are listed.
nexusctl
-fxr “expression”
-i
-ia
-irt
-l nnn nexusctl reset-agent-list
Workstation
Filters tab of the
Recording Settings dialog
Limit Session Length
(checkbox)
All other requests should be (drop-down menu)
Incomplete Request
Timeout (editable spin boxes)
Limit Session Length
(checkbox) and Time
(editable spin boxes)
Reset Agent List
How to use 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 dropdown 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 timeout period.
Workstation: use the spin boxes in the
Session tab of the Recording Settings dialog to customize the timeout period.
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.
Recording Control Window and Nexusctl 243
Recording controls in the Workstation and nexusctl (Continued)
Action
Show all connections to the
Nexus.
Start recording a new session.
Stop recording the current session.
Specify the name for a session.
Select a set of recording settings.
Set the service request sampling percentage.
nexusctl Workstation nexusctl showconnections or nexusctl showconnections-xml
Agents table nexusctl start-recording Record (button)
How to use nexusctl: enter one of these options.
Workstation: Review the entries listed in this table.
nexusctl: enter this option.
Workstation: press this button in the
Recording Control window.
nexusctl stop-recording
-n NAME
Stop (button)
Session Name (text field) 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.
-o “path/to/filename.ext” Settings (drop-down menu) nexusctl: enter this option.
Workstation: press this button in the
Recording Control window.
nexusctl: create a recording settings file with a list of the nexusctl parameters that you want to use, and then enter this parameter with the start-recording option.
Workstation: create and save a recording settings configuration in the Recording
Settings dialog, and then select the configuration from the Settings drop-down menu in the Recording Control window when you are ready to record a session.
-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) 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.
244 PerformaSure: User’s Guide
Recording controls in the Workstation and nexusctl (Continued)
Action
Set the maximum length for a value used in request separation.
Separate requests using literal expressions.
Separate requests using regular expressions.
Set advanced sampling weights using literal expressions.
nexusctl
-sl nn
-srl “URIregex”
“PARAM”
-srr “URIregex”
“PARAM”
-swl nnn “expression”
Workstation
Maximum length of value used for separation
(editable spin box)
Separators tab of the
Recording Settings
Dialog.
Separators tab of the
Recording Settings
Dialog.
Use Advanced Sampling
Settings (checkbox),
Advanced (button), and
Advanced Sampling dialog
How to use 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 startrecording option.
Workstation: in the table in the Separators tab of the Recording Settings dialog, enter the literal expression, select Literal from the drop-down menu in the Type column, specify the parameters (param) and click
OK.
nexusctl: enter this flag, the regular expression, and the parameters with the start-recording 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.
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.
Recording Control Window and Nexusctl 245
Recording controls in the Workstation and nexusctl (Continued)
Action
Set advanced sampling weights using regular expressions.
Set the time slice for the session.
Exclude all other requests (after filtering certain requests).
nexusctl
-swr nnn “expression”
-t nnn
-xa
Workstation
Use Advanced Sampling
Settings (checkbox),
Advanced (button), and
Advanced Sampling dialog
Time Slice Size
(associated drop-down menus)
All other requests should be (drop-down menu)
How to use 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.
246 PerformaSure: User’s Guide
Chapter 9
Edit Options Dialog
Selecting Options... from the Tools menu displays the Edit Options dialog box.
Figure 90
Figure 89 Edit Options dialog. box
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, graphs, and PerformaSure Reports.
247
Choose which pane is displayed by clicking on one of the following nodes in the tree view:
■ Browsers—contains two browser-related options. Project—Don’t ask to add a new browser to a project when closing. If this option is selected, new browsers are not added automatically to the project and data is permanently lost when closed. You can add a browser manually by clicking Add New Browser to Project on the toolbar. Live Updates—Configure the frequency of data collection updates to a Workstation.
Under the Browser option, three additional Edit Options are available:
• Request Tree—contains two options boxes (JProbe Integration and Open New
Browser With These Settings).
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.
• Metrics—this pane contains two checkboxes: Automatically Create New
Columns When Adding Charts, which is selected by default, and Show
Raw Metrics, which is not selected by default. The Show Raw Metrics checkbox allows you to toggle the display of raw metrics in the Metrics
PerformaSure collects.
■
■
Graphs—this pane contains two checkboxes (Panner Updates Graph While
Dragging and Hide Pruned Sub-Trees) and the FastFind options box. The controls in this pane apply to the graphs in the Request Tree browser.
• Panner Updates Graph While Dragging is selected by default (update mode is automatically selected). If you choose not to use the update mode by deselecting this option, the view in the graph pane does not update until you have released the mouse button.
• Hide Pruned Sub-Trees is not selected by default. Selecting this option hides the pruned sub-trees completely; if this option is not selected, pruned sub-trees will be displayed as ghosted.
• FastFind option allows you to choose how many of the top critical paths or nodes to expose in the request trees or control hierarchies when you select
FastFind.
Reports—this pane contains the options box PDF Report Logo, in which you can change the header information in PerformaSure generated reports, and the checkbox Do Not Round Values In CSV Or XML Reports.
The PDF Report Logo box contains four options:
248 PerformaSure: User’s Guide
■
• 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.
The checkbox Do Not Round Values In CSV Or XML Reports is selected by default. If you deselect this checkbox, PerformaSure will round the values listed in the CSV or XML reports that you generate from the browsers.
Values are rounded to a maximum of three decimal places.
Themes—this pane contains the Theme drop-down menu (which has the choices White, Black, and Custom) and three options boxes (General, Color
Scale, and Request Graphs).
Choose one of the options from the Theme drop-down menu to set the theme.
White and Black are pre-configured themes; White is selected by default.
See below for instructions on configuring the Custom theme.
The options in the General box are: Background, Text, Action Text, and
Focused Action Text.
The Color Scale options box contains two color rectangles, which are used to set the extreme Hot and Cold colors in the Request Tree browser.
Use the color rectangles in the Request Graphs box to set the Fill, Outline,
Pruned Background, and Pruned Foreground colors for the nodes in the tree views.
Tip: When you set options and click the Apply button, some settings take effect on the next browser that you open.
Edit Options Dialog 249
To configure the Custom theme:
Figure 91
Figure 90 The Edit Options dialog (Themes pane selected)
1.
There are two ways to start configuring the Custom theme:
• Select Custom if you would like to configure a complete set of colors.
• Select White or Black if you would like to use most of the colors in one of these pre-configured themes.
2.
Click on a color rectangle in one of the options boxes to launch the Select Color chooser. There are three ways of specifying the new color: color swatches,
HSB, or RGB.
Note: When you change a color in the White or Black theme,
PerformaSure automatically switches the theme to Custom. This
Custom theme will contain the colors from the pre-configured theme that you selected (with the exception of the color that you changed).
3.
After you have selected new colors, click Apply to save the changes to the
Custom theme. Themes are immediately updated in the browsers to which the settings apply.
250 PerformaSure: User’s Guide
To Configure the Frequency of Live Data Updates
The Get Live Updates option is defaulted to off. When selected, it is defaulted to automatically collect live data every five minutes. This setting can be configured to automatically collect data at different interval.
Note: The minimum update frequency is one minute.
1.
Open a Project file.
2.
On the Tools menu, click Options.
3.
On the left column of the Edit Options window, click Browser.
Live Updates configuration options are displayed.
4.
Configure hours, minutes, and seconds.
5.
Click OK.
Edit Options Dialog 251
252 PerformaSure: User’s Guide
Chapter 10
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 92
Timeline
Figure 91 The Time Control Panel
The Time Control panel contains several elements, which are described below.
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.
253
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 92). This line indicates the presence of data within the visible
Timeline.
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,
254 PerformaSure: User’s Guide
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
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.
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 93
Figure 92 The Timeline labels and the Zonar Offset and Duration label in the Time Control panel
The Zonar’s 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 255
Related Controls
Certain controls in the PerformaSure 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 Sightline’s 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 below, 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 Sightline’s slider, it will snap to time slice boundaries imposed by the Zonar.
Figure 94
Figure 93 The Sightline and its slider in the Metrics browser
PerformaSure draws a horizontal dashed line from the y-axis to the Sightline’s current position in the chart along the x-axis. This allows you to accurately determine the measured quantity’s ordinate. The point at which these two lines intersect is marked by small square colored by the active metric.
256 PerformaSure: User’s Guide
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 browser’s 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 browser’s 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 95
Figure 94 The Query Progress Bar in its active state
Time Control Panel 257
258 PerformaSure: User’s Guide
Chapter 11
Live Data Updates
The Get Live Updates option provides the ability to view live data as it is being collected. This system operations live feedback assists you in diagnosing a performance problem faster. Response times are displayed as they become available.
Note: This option is available in all browsers except the Request Tree Browser.
This browser simply presents a graph tree listing the critical path within a request.
The Get Live Data option is only available for a session which is in recording process. Both the Record New Session and Open Session in New Project windows display this option. By default, this option is off. The default setting for automatically collecting live data is five minutes. The minimum update frequency is one minute.
To Force a Live Data Update:
1.
Launch PerformaSure, and click one of the following options:
Record New Session
Open Session in New Project
Figure 96
Figure 95 Sessions selection
259
2.
Click OK.
The Recording Control window appears.
3.
Place a check mark in the View session while recording box.
4.
Click Start Recording.
On the browser toolbar, Get Live Updates is selected by default. Data is collected based on the Edit Options. For more information about setting a
different frequency for collecting live data updates, see “ Edit Options Dialog ” on page 247.
5.
On the toolbar, click Update Browser Data.
Figure 97
Figure 96 Toolbar icon for Update Browser Data.
Live data updates automatically appear in the browser.
260 PerformaSure: User’s Guide
Chapter 12
Agent Information
The Agent Information view displays information the Agent collects about itself and its environment during a recorded session.
From this view you can explore various Java properties (for example, name, version, vendor, classpath), application server settings, OS name and version, as well as settings used to record the session, such as filters and separators.
When using the Get Live Updates tool in a browser, the latest data collected is updated in the Agent Information view. For more information about the Get Live
Updates, see “ Live Data Updates ” on page 259.
To open the Agent Information viewer:
1.
Open your Project.
2.
Click Tools > Agent Info.
Figure 98
Figure 97 Agent Info
The Agent Information view displays a split pane. The left side of the pane displays a complete list of agents names, ids, and recording session states. The right side of the pane displays details on the selected agent. Each component of this table can be collapsed to allow you to focus on one or more property groups.
261
Figure 99
Figure 98 Agent Information View
The following table outlines the detailed properties displayed for an agent.
Property
General Agent Info
• Agent Name
• Agent Version
• Agent Build
• Debug Level
Environment Properties
• Host Name
• CPU Count
• OS Name
• OS Version
Recording Settings
• Filtering Information
• Separation Information
Application (Server) Properties
262 PerformaSure: User’s Guide
Property
• Cluster Name
• Application Arguments
• Main Class
• Component Type
• Platform Home
• WebLogic Name
• WebLogic Home
• log4j Configuration
• Log Configuration File
• Server Root
• EJB Delegation Mode
• EJB Instance Name
• Catalina Base
• Catalina Home
Java Properties
• Java Version
• Java Classpath
• Java Home
• Java Vendor
• Java Library Path
• Book Vlasspath
• Boot LibraryPath
• JRockit Version
• JRockit VIM
Agent Information 263
264 PerformaSure: User’s Guide
Chapter 13
Request Time Browser
■
■
■
■
■
■
■
The following topics are covered in this chapter:
■
•
Request Time Browser Control Pane—Summary
Request Time Browser Control Pane—Full Detail
•
•
Single Request Investigation Mode
Request Time Browser Graph Pane—Summary
■
■
Request Time Browser Graph Pane—Full Detail
•
•
•
Context Menus in the Graph Pane
Request Time Browser Detail Pane
•
•
•
•
Context Menus in the Detail Pane
265
Request Time Browser
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.
The Request Time browser launches automatically when you open a new Project based on the Default template, enabling you to start your investigation right away by isolating the request that is consuming the most time. Once you identify an expensive request, you can launch a Request Tree browser to see all the methods and database calls in the request. You can also launch a Metrics browser to view metrics related to that request and see if any of those metrics exceed their normal bounds.
Figure 99 The Request Time browser
266 PerformaSure: User’s Guide
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 279 and “ Single Request Investigation
Menus and Toolbar—Summary
Menu Bar
The Request Time browser’s 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 Bar—Browser Menu
Control
New Browser
Add New
Browser To
Project
Export Report
Type Default Value Description
Menu item Enabled
Menu item Enabled
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.
Menu item Enabled
Properties
Close
Exit
PerformaSure
Menu item Enabled
Menu item Enabled
Menu item Enabled
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
Closes the browser.
Closes all open Projects and browsers and shuts down the
Workstation.
Request Time Browser 267
Request Time Browser Menu Bar—View Menu
Control
Display By
Type
Menu item
Default Value
Tier
Auto-Fit All Columns Menu item
Show/Hide Columns Menu item
Show/Hide Bar
Charts
Show Filter Bar
Menu item
Enabled
Enabled
Enabled
Menu item with checkbox
Selected
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 273 for
more information about the Filter Requests Bar.
Request Time Browser Menu Bar—Tools Menu
Control Type
Recording Control Window Menu item
Session Management Menu item
Thresholds
Change Password
User Management
Menu item
Menu item
Menu item
Default Value
Enabled
Enabled
Enabled
Enabled
Disabled
Performance Diagnostics Menu item
Options Menu item
N/A
Enabled
Description
Launches the Recording Control window.
Opens the Session Management dialog.
Launches the Threshold Editor.
Opens the Change Password dialog.
Launches the User Management window. This menu item is enabled if you have the required permissions.
Displays a submenu with one option. See
“ Performance Diagnostics ” on page 274 for more
information.
Launches the Edit Options dialog.
268 PerformaSure: User’s Guide
Request Time Browser Menu Bar—Windows Menu
Control
Bring All To Front
[Switch to a Project window]
[Switch to a browser]
Type Default Value Description
Menu item Enabled
Menu item Enabled
Menu item Enabled
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 Bar—Help Menu
Control
Help
About
Type Default Value Description
Menu item Enabled
Menu item Enabled
Launches context-sensitive help for this browser.
Opens a new window that displays product information about PerformaSure.
Toolbar
Request Time Browser Toolbar
Under the Request Time browser’s menu bar is a toolbar with controls for opening new PerformaSure browsers, launching Spotlight
®
and Quest database tools, controlling the view in the Request Time browser’s graph and detail panes, and performing other actions like exporting a report. The following table describes the controls available from the toolbar.
Control
New Browser
Type
Button and drop-down menu
Add New Browser To
Project
Export Report
Button
Button
Default Value
Enabled
Enabled
Enabled
Description
Clicking on the left-hand side of this button launches the
New Browser dialog. See “ New Browser ” on page 182
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 275 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.
Request Time Browser 269
Request Time Browser Toolbar
Control
Properties
Performance
Diagnostics
Get Live Updates
Type
Button
Button and drop-down menu
Check box
Update Browser Data Button
Link Browsers To Use
Same Zone/Break
Link Between
Browsers
Button
Show Detail/Hide
Detail
Display By
Button
Drop-down menu
Default Value
Enabled
N/A
On
N/A
Enabled
Enabled
Description
Launches the Browser Properties dialog. See
“ Properties ” on page 276 for details.
Displays a drop-down menu with one option. See
“ Performance Diagnostics ” on page 276 for more
information.
Launches an automatic data collection update and
refreshes the display of data in a browser. See “ Live
Data Updates ” on page 259 for more details.
Forces a live data collection update. See “ Live Data
Updates ” on page 259 for more details.
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 276 for more information.
Toggles the display of the detail pane.
Tier
Allows you to change the display mode. See “ Tier ” and
“ Component Technology ” on page 272 for more
information about the two display options.
Menus and Toolbar—Full Detail
Menu Bar—Browser 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
270 PerformaSure: User’s Guide
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 411 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 Bar—View
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.
Request Time Browser 271
Tier
Changing the display mode to Tier causes the response time data displayed in the graph pane and the response time metric bar charts in the detail pane to be broken down and colored by tier.
Selecting this option allows you to distinguish the tiers of your application in the charts in the graph and detail panes. PerformaSure consistently assigns one color to each tier and one for each application server cluster.
Component Technology
Changing the display mode to Component Technology causes the response time data displayed in the graph pane and the response time metric bar charts in the detail pane to be broken down and colored by component technology.
Selecting this option allows you to distinguish component types in the charts in the graph pane and detail panes. Component technologies include HTTP,
Servlets, EJBs, RMI, URL, JNDI, JMS, JDBC, and custom components.
PerformaSure consistently assigns colors to standard and custom component technologies.
The component technology chart segments that may appear in the graph and detail pane are listed in the table below.
Component Technology Chart Segments
Java EE
HTTP
Servlet
EJB
RMI
URL
JNDI
JMS
JDBC
Web Client
RMI Outgoing
Remote
Other
[Custom Components]
Other
272 PerformaSure: User’s Guide
The HTTP segment includes only the portion from the application server. Java
EE component technology segments span all application servers in the system, regardless of cluster. The Servlet segment includes both JSPs and Servlets.
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.
Using the Request Time browser’s Filter Requests bar
You can enter a literal string or a regular expression in the Filter Requests bar’s
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. See “ Appendix D—Regular
Expressions ” on page 489 for more information about using regular expressions.
Tip: If you enter a regular expression in the Filter Requests text field, ensure that the Regular Expression checkbox is selected before you click Apply.
Request Time Browser 273
Menu Bar—Tools
Recording Control Window
Select Recording Control Window... to launch the Recording Control window.
See “ Recording Control Window ” on page 197 for more information about using
the controls in this window.
Session Management
Select Session Management... to open the Session Management dialog. See
“ Session Management ” on page 164 for more information about using this dialog.
Thresholds
Change Password
Select Change Password... to open the Change Password dialog. See “ Changing a
Password ” on page 154 for more information about using this dialog.
User Management
Select User Management... to launch the User Management window. See “ User
Management ” on page 154 for details about using this window.
Note: This menu item is disabled if you do not have the required permissions.
Performance Diagnostics
Selecting the Performance Diagnostics menu item displays a submenu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest Central is installed. When you select this option, the version of Spotlight
®
included with
Quest Central is launched.
Options
Selecting the Options... menu item launches the Edit Options dialog. See “ Edit
Options Dialog ” on page 247 for details about using this dialog.
274 PerformaSure: User’s Guide
Menu Bar—Windows
The Windows menu’s one static choice is Bring All To Front, which ensures that all open PerformaSure windows have a higher stacking order than non-
PerformaSure 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 Bar—Help
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 browser’s toolbar is located directly below the menu bar.
Figure 100
Figure 100 The toolbar in the Request Time 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; see “ New Browser ” on page 182 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.
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
Request Time Browser 275
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 411 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
Clicking the Performance Diagnostics button displays a drop-down menu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest
Central is installed. When you select this option, the version of Spotlight
® included with Quest Central is launched.
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 browser’s Zonar and
Sightline to function independently.
276 PerformaSure: User’s Guide
Hide/Show Detail
The Hide/Show Detail button toggles the display of the Request Time browser’s detail pane.
Display By
The Display By drop-down menu contains two options: Tier and Component
Technology. See “ Display By ” on page 271 for more information.
Time Control Panel
The Time Control panel is located directly below the Request Time browser’s toolbar. This panel has the same controls in all PerformaSure browsers. See
“ Time Control Panel ” on page 253 for a detailed description of its controls.
Request Time Browser Control Pane—Summary
The following table describes the configuration controls and actions available from the control pane in All Requests mode.
Request Time Browser Control Pane—All Requests Mode
Control/Action
Show Response
Time for All
Requests
Tier
Type
Checkbox
Action
Default Value Description
Checked Toggles the display of aggregate response time data in the graph pane for all requests listed in the detail pane.
Enabled
Component
Technology
Server
View call tree of selected request
Action
Action
Action
Enabled
Enabled
Enabled
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.
Request Time Browser 277
Request Time Browser Control Pane—All Requests Mode
Control/Action Type
View related metrics of selected request
Action
Default Value Description
Enabled Launches a new Metrics browser based on the metrics for the request that is currently selected.
The following table describes the features and actions available from the control pane in Single Request Investigation mode.
Request Time Browser Control Pane—Single Request Investigation Mode
Feature/Action
Current Drill Down
History
Next Drill Down
Type
Drill-down history/ actions
Actions
Default Value Description
N/A
Enabled
Enabled
Displays the drill-down history for the request that you are currently investigating. The entries for previous drilldown levels function like request investigation actions.
Lists the drill-down options that are currently available.
Click a drill-down option to display response time data in the graph pane broken down by that option. See
“ Next Drill Down ” on page 281 for more information.
Returns the browser to All Requests mode.
Choose another request
View call tree of selected request
View related metrics of selected request
Action
Action
Action
Enabled
Enabled
Launches a new Request Tree browser based on the request that you are currently investigating.
Launches a new Metrics browser based on the metrics for the request that you are currently investigating.
Request Time Browser Control Pane—Full 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.
278 PerformaSure: User’s Guide
Figure 101
Figure 101 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 102
Figure 102 The aggregate response time of all requests charted in the graph pane
Request Time Browser 279
As shown in Figure 102, 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 request investigation 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 by component
technology. See “ Component Technology Chart Segments ” on page 272 for a list
of and information about the component technology chart segments.
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.
280 PerformaSure: User’s Guide
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 103, 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 103
Figure 103 A drill-down history tooltip
Next Drill Down
The request investigation actions that are available from the current drill-down level are listed in the Next Drill Down section of the control pane. The request investigation actions that you can perform vary depending on the current drilldown level.
Request Time Browser 281
View by Component Technology
Select View By 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 is charted in the graph pane. At the Component Technology drill-down level, the segments in the chart are grouped by component technology. See
“ Component Technology Chart Segments ” on page 272 for a list of and
information about the component technology chart segments.
Note: This action is available from the Tier and Server drill-down levels.
View by Server
Select View by 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.
View by Component
Select View by 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.
282 PerformaSure: User’s Guide
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 Pane—Summary
The following tables describe the controls and the context (right-click) menus available in the graph pane.
Request Time Browser Graph Pane
Control
Chart header
Type Default Value Description
Drop-down menu Enabled
Function Set chooser
Plot Type chooser
Drop-down menu
Drop-down menu
Enabled
Enabled
Sightline slider Slider Enabled
Legend entries Metric Indicators Enabled
Chart Type chooser
Drop-down menu
Edit Thresholds Button
Enabled
Enabled
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 285 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 408 for more information.
Request Time Browser Graph Pane—Context Menus
Control
Function for Selected Metric
Plot Type for Selected Metric
Type
Drop-down menu
Description
Displays a menu from which you can select the function applied to the active response time metric.
Drop-down menu
Displays a menu from which you can select the plot type applied to the active response time metric.
Request Time Browser 283
Request Time Browser Graph Pane—Context Menus
Control
Copy
View Call Tree
Type
Menu item
Menu item
View Related Metrics Menu item
Description
Copies the active response time metric.
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 Pane—Full Detail
The Request Time browser’s graph pane includes several elements.
Figure 104
Figure 104 Elements in the Request Time browser’s 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.
284 PerformaSure: User’s Guide
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 271 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 104, the graph pane legend contains a group of Metric
Indicators. Click a Metric Indicator to select a new active response time metric.
Request Time Browser 285
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.
286 PerformaSure: User’s Guide
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 yaxis. 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.
Request Time Browser 287
Note: To change the function applied to a single response time metric, rightclick the metric to cause a context 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.
When Stacked is selected from the Chart Type chooser, the options available in this menu are Stacked Bar and Stacked Area. The plot type that you select is applied to all response time metrics in the chart.
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 for the active
response time metric. See “ Threshold Editor ” on page 408 for details about the
Threshold Editor. See “ Thresholds Browser FAQ ” on page 410 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 105
Figure 105 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.
288 PerformaSure: User’s Guide
Figure 106
Figure 106 The tooltip for a data point
Context Menus in the Graph Pane
You can right-click anywhere in the graph pane to make a context menu appear.
Function for Selected Metric
Click Function for Selected Metric to cause a submenu to appear from which you can select the function applied to the active response time metric.
Plot Type For Selected Metric
Click Plot Type for Selected Metric to cause a submenu to appear from which you can select the plot type applied to the active response time metric. 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.
Copy
Click Copy to copy the active response time metric, allowing you to paste it into a chart in the Metrics browser. You can also paste the metric name into another application, such as a spreadsheet.
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 289
Request Time Browser Detail Pane
The Request Time browser’s 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 system’s 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 107
Figure 107 The detail pane in the Request Time browser
Detail Pane Columns
The columns in the detail pane are described below.
Figure 108
Figure 108 The column headers in the Request Time browser’s 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.
290 PerformaSure: User’s Guide
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 211 and “
Sampling Parameters ” on page 233 for more information about
setting the sampling rate in the Recording Settings dialog or using 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
” on page 211 and “ Sampling Parameters ” on page 233 for more information
about setting the sampling rate in the Recording Settings dialog or using 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.
Request Time Browser 291
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
209 and “ Session Parameters ” on page 232 for more information about setting the
incomplete request timeout in the Recording Settings dialog or using nexusctl.
Sampled Requests (%)
The Sampled Requests (%) column lists the percentage of service requests that were tracked using Tag and Follow 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 the 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 by component technology. See “ Component Technology
Chart Segments ” on page 272 for a list of and information about the component
technology chart segments.
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
292 PerformaSure: User’s Guide
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.
Context Menus in the Detail Pane
You can right-click anywhere in the detail table to make a context menu appear.
The items in these menus are described below.
Figure 109
Figure 109 A context 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.
Request Time Browser 293
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
How can I keep track of the exact value of previous drill-down levels when drilling down several levels into a request? 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 110
Figure 110 The tooltip for a previous drill-down level
294 PerformaSure: User’s Guide
■
■
■
■
■
■
■
■
The following topics are covered in this chapter:
SQL Browser Control Pane—Summary
SQL Browser Control Pane—Full Detail
SQL Browser Graph Pane—Summary
SQL Browser Graph Pane—Full Detail
•
•
•
Context Menus in the Graph Pane
■
■
•
•
•
Context Menus in the Detail Pane
Chapter 14
SQL Browser
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.
295
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 more easily and with greater accuracy.
Figure 111
Figure 111 The SQL browser
296 PerformaSure: User’s Guide
Menus and Toolbar—Summary
Menu Bar
The SQL browser’s 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 Bar—Browser Menu
Control
New Browser
Add New
Browser To
Project
Export Report
Type Default Value Description
Menu item Enabled Opens the New Browser dialog. Use this dialog to choose the type of browser you want to launch.
Menu item Enabled Adds the browser to your PerformaSure Project. A SQL browser icon will appear in the Browsers area of the Project window.
Menu item Enabled
Properties
Close
Exit
PerformaSure
Menu item Enabled
Menu item Enabled
Menu item Enabled
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
Closes the browser.
Closes all open Projects and browsers and shuts down the
Workstation.
SQL Browser Menu Bar—View Menu
Control Type
Auto-Fit All Columns Menu item
Default Value
Enabled
Show/Hide Columns Menu item
Show/Hide Bar
Charts
Show Filter Bar
Menu item
Enabled
Enabled
Menu item with checkbox
Selected
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 301 for more
information about using the controls in the Filter Bar.
SQL Browser 297
SQL Browser Menu Bar—Tools Menu
Control Type
Recording Control Window Menu item
Session Management Menu item
Thresholds
Change Password
User Management
Menu item
Menu item
Menu item
Performance Diagnostics Menu item
Options Menu item
Default Value
Enabled
Enabled
Enabled
Enabled
Disabled
N/A
Enabled
Description
Launches the Recording Control window.
Opens the Session Management dialog.
Launches the Threshold Editor.
Opens the Change Password dialog.
Launches the User Management window. This menu item is enabled if you have the required permissions.
Displays a submenu with one option. See
“ Performance Diagnostics ” on page 302 for more
information.
Launches the Edit Options dialog.
SQL Browser Menu Bar—Windows Menu
Control
Bring All To Front
[Switch to a Project window]
[Switch to a browser]
Type Default Value Description
Menu item Enabled
Menu item Enabled
Menu item Enabled
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.
SQL Browser Menu Bar—Help Menu
Control
Help
About
Type Default Value Description
Menu item Enabled
Menu item Enabled
Launches context-sensitive help for this browser.
Opens a new window that displays product information about PerformaSure.
298 PerformaSure: User’s Guide
Toolbar
Under the SQL browser’s menu bar is a toolbar with controls for opening new
PerformaSure browsers, launching Spotlight
®
and Quest database tools, controlling the view in the SQL browser’s 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
Button and drop-down menu
Default Value
Enabled
Add New Browser To
Project
Export Report
Button
Button
Properties
Performance
Diagnostics
Get Live Updates
Link Browsers To Use
Same Zone/Break
Link Between
Browsers
Button
Show Detail/Hide
Detail
Button
Button and drop-down menu
Check box
Update Browser Data Button
Button
Enabled
Enabled
Enabled
N/A
On
N/A
Enabled
Enabled
Description
Clicking on the left-hand side of this button launches the
New Browser dialog. See “ New Browser ” on page 182
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 303 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 304 for details.
Displays a drop-down menu with one option. See
“ Performance Diagnostics ” on page 304 for more
information.
Launches an automatic data collection update and
refreshes the display of data in a browser. See “ Live
Data Updates ” on page 259 for more details.
Forces a live data collection update. See “ Live Data
Updates ” on page 259 for more details.
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 304 for more information.
Toggles the display of the detail pane.
SQL Browser 299
Menus and Toolbar—Full Detail
Menu Bar—Browser 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 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 411 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
300 PerformaSure: User’s Guide
save the Projects that are open or add new browsers to these Projects before exiting PerformaSure.
Menu Bar—View
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 browser’s Filter Statements bar at the bottom of the graph pane.
Using the SQL browser’s Filter Statements bar
You can enter a literal string or a regular expression in the Filter Statements bar’s
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. See “ Appendix D—Regular
Expressions ” on page 489 for more information about using regular expressions.
Tip: If you enter a regular expression in the Filter Statements text field, ensure that the Regular Expression checkbox is selected before you click Apply.
SQL Browser 301
Menu Bar—Tools
Recording Control Window
Select Recording Control Window... to launch the Recording Control window.
See “ Recording Control Window ” on page 197 for more information about using
the controls in this window.
Session Management
Select Session Management... to open the Session Management dialog. See
“ Session Management ” on page 164 for more information about using this dialog.
Thresholds
Change Password
Select Change Password... to open the Change Password dialog. See “ Changing a
Password ” on page 154 for more information about using this dialog.
User Management
Select User Management... to launch the User Management window. See “ User
Management ” on page 154 for details about using this window.
Note: This item is disabled if you do not have the required permissions.
Performance Diagnostics
Selecting the Performance Diagnostics menu item displays a submenu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest Central is installed. When you select this option, the version of Spotlight
®
included with
Quest Central is launched.
Options
Selecting the Options... menu item launches the Edit Options dialog. See “ Edit
Options Dialog ” on page 247 for details about using this dialog.
302 PerformaSure: User’s Guide
Menu Bar—Windows
The Windows menu’s one static choice is Bring All To Front, which ensures that all open PerformaSure windows have a higher stacking order than non-
PerformaSure 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 Bar—Help
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 SQL browser’s toolbar is located directly below the menu bar.
Figure 112
Figure 112 The toolbar in the SQL 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; see “ New Browser ” on page 182 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.
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
SQL Browser 303
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 411 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
Clicking the Performance Diagnostics button displays a drop-down menu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest
Central is installed. When you select this option, the version of Spotlight
® included with Quest Central is launched.
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 browser’s Zonar and
Sightline to function independently.
304 PerformaSure: User’s Guide
Hide/Show Detail
The Hide/Show Detail button toggles the display of the SQL browser’s detail pane.
Time Control Panel
The Time Control panel is located directly below the SQL browser’s toolbar. This
panel has the same controls in all PerformaSure browsers. See “ Time Control
Panel ” on page 253 for a detailed description of its controls.
SQL Browser Control Pane—Summary
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
Prepare
Type
Checkbox
Checkbox
Default Value Description
Checked Controls whether aggregate response time data is displayed in the graph pane for all SQL statements listed in the detail pane.
Checked
Execute
Retrieve
Checkbox
Checkbox
View call tree of related request
View related metrics of selected statement
Action
Action
Checked
Checked
Enabled
Enabled
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 305
SQL Browser Control Pane—Full Detail
Components in the Control Pane
The SQL browser’s 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 browser’s control pane
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
306 PerformaSure: User’s Guide
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 metric’s trend.
See “ Changing the Chart Type ” on page 310 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 307
SQL Browser Graph Pane—Summary
The following tables describe the controls and the context (right-click) menus available in the graph pane.
SQL Browser Graph Pane
Control
Chart header
Type Default Value Description
Drop-down menu Enabled
Function Set chooser
Drop-down menu Enabled
Plot Type chooser
Sightline slider
Drop-down menu Enabled
Slider Enabled
Legend entries Metric Indicators Enabled
Chart Type chooser
Drop-down menu
Edit Thresholds Button
Enabled
Enabled
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 310 for more
information.
Displays a menu from which you can select the chart type.
Opens the Threshold Editor for the active SQL response time metric.
SQL Browser Graph Pane—Context Menus
Control
Function for Selected Metric
Plot Type for Selected Metric
Copy
View Call Tree
View Related Metrics
Type
Drop-down menu
Drop-down menu
Menu item
Menu item
Menu item
Description
Displays a menu from which you can select the function applied to the active SQL response time metric.
Displays a menu from which you can select the plot type applied to the active SQL response time metric.
Copies the active SQL response time metric.
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.
308 PerformaSure: User’s Guide
SQL Browser Graph Pane—Full Detail
The SQL browser’s graph pane includes several elements.
Figure 115
Figure 115 Elements in the SQL browser’s graph pane; the Chart Type is set to Overlap and the Plot Type is set to
Line.
Charts in the Graph Pane
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 309
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.
310 PerformaSure: User’s Guide
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 metric’s 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 311
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.
When Stacked is selected from the Chart Type chooser, the options available in this menu are Stacked Bar and Stacked Area. The plot type that you select is applied to all SQL response time metrics in the chart.
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 for the active
SQL response time metric. See “ Threshold Editor ” on page 408 for details about
the Threshold Editor. See “ Thresholds Browser FAQ ” on page 410 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 SQL response time metric and the function applied to that metric are displayed.
312 PerformaSure: User’s Guide
Figure 116
Figure 116 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 117
Figure 117 The tooltip for a data point
Context Menus in the Graph Pane
You can right-click anywhere in the graph pane to make a context menu appear.
Function for Selected Metric
Click Function for Selected Metric to cause a submenu to appear from which you can select the function applied to the active SQL response time metric.
Plot Type For Selected Metric
Select Plot Type for Selected Metric to cause a submenu to appear from which you can select the plot type applied to the active SQL response time metric.
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.
Copy
Click Copy to copy the active SQL response time metric, allowing you to paste it into a chart in the Metrics browser. You can also paste the metric name into another application, such as a spreadsheet.
SQL Browser 313
View Call Tree
Click View Call Tree to launch a new Request Tree browser based on the request related to the selected SQL statement.
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 browser’s 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 system’s 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
The columns in the detail pane are described below.
Figure 119
Figure 119 The column headers in the SQL browser’s detail pane
314 PerformaSure: User’s Guide
SQL Statement
The SQL Statement column lists the SQL statements used in your application.
Tip: Right-click the entry for a SQL statement and select Show SQL
Statement from the context menu that appears to display the full statement in a dialog.
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 response 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.
Bar Charts in the Detail Pane
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.
SQL Browser 315
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
Context Menus in the Detail Pane
You can right-click anywhere in the detail table to make a context menu appear.
The items in this menu are described below.
Figure 121
Figure 121 A context menu in the detail pane
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.
316 PerformaSure: User’s Guide
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.
Show SQL Statement
Select Show SQL Statement to open a dialog in which the full SQL statement is displayed.
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. Selecting the Performance
Diagnostics menu item displays a submenu with one option: Spotlight
®
in
Quest Central. This option is enabled if Quest Central is installed. When you select this option, the version of Spotlight
®
included with Quest Central is launched.
SQL Browser 317
SQL Browser FAQ
SQL statements are sometimes truncated in the SQL Statement column in the detail pane. Is there a way of displaying the full statement without adjusting the size of the columns in the detail pane?
You can display the full SQL statement in a dialog by right-clicking the entry for that statement in the detail table and selecting Show SQL Statement from the context menu that appears.
318 PerformaSure: User’s Guide
Chapter 15
Request Tree Browser
■
■
■
■
■
■
■
■
The following topics are covered in this chapter:
Request Tree Browser Graph Pane—Summary
Request Tree Browser Graph Pane—Full Detail
•
•
•
•
Context Menus in the Graph Pane
•
■
Request Tree Browser Detail Pane
•
Creating a JProbe Launcher File
Request Tree Browser
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.
319
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, 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 browser’s 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.
320 PerformaSure: User’s Guide
Menus and Toolbar—Summary
Menu Bar
The Request Tree browser’s 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 Bar—Browser Menu
Control
New Browser
Add New Browser
To Project
Export Report
Export JProbe
Launcher File
Type Default Value Description
Menu item Enabled Opens the New Browser dialog. Use this dialog to choose the type of browser you want to launch.
Menu item
Menu item
Menu item
Enabled
Enabled
Disabled
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 325 for
more information.
Properties
Close
Exit PerformaSure
Menu item Enabled
Menu item
Menu item
Enabled
Enabled
Launches the Browser Properties dialog. See “ Properties ” on page 326
for details.
Closes the browser.
Closes all open Projects and browsers and shuts down the
Workstation.
Request Tree Browser Menu Bar—View Menu
Control
Display By
Type
Menu item
Default Value
Tier
FastFind Menu item Enabled
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.
Request Tree Browser 321
Request Tree Browser Menu Bar—View Menu
Control
Sort Tree
Metric Display
Active Metric
Bundling Mode
Detail Table Mode
Show Panner
Auto-Fit All Columns
Show Filter Bar
Type
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item with checkbox
Show/Hide Columns Menu item
Menu item
Menu item with checkbox
Default Value
Enabled
Per Request
Avg Cumulative
Time
Component
List
Not selected
Enabled
Enabled
Selected
Description
Redraws the request tree after a new active metric has been
selected. See “ Sort Tree ” on page 328 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 328 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 331
for more information.
Displays a submenu from which you can select either List 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 333 for more information
about using the controls in the Filter Bar.
Request Tree Browser Menu Bar—Tools Menu
Control Type
Recording Control Window Menu item
Session Management Menu item
Thresholds
Change Password
Menu item
Menu item
Default Value
Enabled
Enabled
Enabled
Enabled
Description
Launches the Recording Control window.
Opens the Session Management dialog.
Launches the Threshold Editor.
Opens the Change Password dialog.
322 PerformaSure: User’s Guide
Request Tree Browser Menu Bar—Tools Menu
Control
User Management
Type
Menu item
Default Value
Disabled
Performance Diagnostics Menu item
Options Menu item
N/A
Enabled
Description
Launches the User Management window. This menu item is enabled if you have the required permissions.
Displays a submenu with one option. See
“ Performance Diagnostics ” on page 334 for more
information.
Launches the Edit Options dialog.
Request Tree Browser Menu Bar—Windows Menu
Control
Bring All To Front
[Switch to a Project window]
[Switch to a browser]
Type Default Value Description
Menu item Enabled Ensures that all open PerformaSure windows have a higher stacking order than non-PerformaSure windows.
Menu item Enabled Switches to the Project window that you select. Each menu item of this type will display the name of an open Project.
Menu item Enabled Switches to the open browser that you select. Each menu item of this type will display the name of an open PerformaSure browser.
Request Tree Browser Menu Bar—Help Menu
Control
Help
About
Type Default Value Description
Menu item Enabled Launches context-sensitive help for this browser.
Menu item Enabled Opens a new window that displays product information about PerformaSure.
Toolbar
Under the Request Tree browser’s menu bar is a toolbar with controls for opening new PerformaSure browsers, launching Spotlight
®
and Quest database tools, controlling the view in the Request Tree browser’s graph and detail panes, and
Request Tree Browser 323
Request Tree Browser Toolbar performing other actions like exporting a report. The following table describes the controls available from the toolbar.
Control
New Browser
Add New Browser To
Project
Export Report
Properties
Type
Button and drop-down menu
Button
Button
Button
Performance
Diagnostics
Link Browsers To Use
Same Zone/Break Link
Between Browsers
Button and drop-down menu
Button
Show Detail/Hide
Detail
Show Panner/Hide
Panner
Button
Button
Default Value
Enabled
Enabled
Enabled
Enabled
N/A
Enabled
Enabled
Description
Clicking on the left-hand side of this button launches the
New Browser dialog. See “ New Browser ” on page 182 for
details. 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 335 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 326 for details.
Displays a drop-down menu with one option. See
“ Performance Diagnostics ” on page 336 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 336 for more information.
Toggles the display of the detail pane.
Metric Display
Active Metric
FastFind
Drop-down menu
Drop-down menu
Button
Enabled
Per Request
Avg Cumulative
Time
Enabled
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 337 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 328 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.
324 PerformaSure: User’s Guide
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 331 for a
description of these options.
Menus and Toolbar—Full Detail
Menu Bar—Browser 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 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 411 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
Request Tree Browser 325
that you can use to run JProbe Profiler. See “ Creating a JProbe Launcher File ” on
page 368 for more information about creating this type of file. See “ JProbe
Integration ” on page 134 for more information about using 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 Bar—View
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.
326 PerformaSure: User’s Guide
Component Technology
Coloring by component technology allows you to distinguish component types in the request tree. Component technologies include HTTP, Servlets, EJBs, RMI,
URL, JNDI, JMS, JDBC, and custom components. PerformaSure consistently assigns colors to standard and custom component technologies. Any node that represents a class that does not belong to a standard or custom component technology is colored grey.
The component technology types identified in the graph pane are listed in the table below.
Java EE
HTTP
Servlet
EJB
RMI
URL
JNDI
JMS
JDBC
Web Client
RMI Outgoing
Remote
Other
[Custom Components]
Other
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.
2.
Select View > FastFind. The top n expensive nodes will be exposed and the most expensive node will be scrolled into view.
Request Tree Browser 327
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 node’s 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.
328 PerformaSure: User’s Guide
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 363 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.
Request Tree Browser 329
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 object’s parameters were serialized is used to color the node.
Max Parameter Data Serialized
The maximum amount of data sent to the network when this object’s parameters were serialized is used to color the node.
Min Parameter Data Serialized
The minimum amount of data sent to the network when this object’s 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.
330 PerformaSure: User’s Guide
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
” on page 209 and “ -irt nnn ” on page 233 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 Java EE classes and methods in the request tree, giving you an overview of your application’s behavior. Class-level bundling displays both Java EE 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: The default bundling mode for PerformaSure is Component.
That means that even if you recorded your session at full detail, only the key Java EE 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 application’s behavior.
Detail Table Mode
Selecting Detail Table Mode displays a submenu with the choices List or Tree.
List is selected by default.
List
When the radio button associated with List is selected, the methods associated with a request are listed in a single column under that request.
Tree
When the radio button associated with Tree is selected, the methods associated with a request are arranged in a tree structure under the request.
Request Tree Browser 331
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 Graphs 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.
332 PerformaSure: User’s Guide
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.
Using the Request Tree browser’s Filter Requests bar
You can enter a literal string or a regular expression in the Filter Requests bar’s
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 isn’t 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. See “ Appendix D—Regular Expressions ” on page 489 for more
information about using regular expressions.
Tip: If you enter a regular expression in the Filter Requests text field, ensure that the Regular Expression checkbox is selected before you click Apply.
Menu Bar—Tools
Recording Control Window
Select Recording Control Window... to launch the Recording Control window.
See “ Recording Control Window ” on page 197 for more information about using
the controls in this window.
Session Management
Select Session Management... to open the Session Management dialog. See
“ Session Management ” on page 164 for more information about using this dialog.
Request Tree Browser 333
Thresholds
Change Password
Select Change Password... to open the Change Password dialog. See “ Changing a
Password ” on page 154 for more information about using this dialog.
User Management
Select User Management... to launch the User Management window. See “ User
Management ” on page 154 for details about using this window.
Note: This item is disabled if you do not have the required permissions.
Performance Diagnostics
Selecting the Performance Diagnostics menu item displays a submenu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest Central is installed. When you select this option, the version of Spotlight
®
included with
Quest Central is launched.
Options
Selecting the Options... menu item launches the Edit Options dialog. See “ Edit
Options Dialog ” on page 247 for details about using this dialog.
Menu Bar—Windows
The Windows menu’s one static choice is Bring All To Front, which ensures that all open PerformaSure windows have a higher stacking order than non-
PerformaSure 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.
334 PerformaSure: User’s Guide
Menu Bar—Help
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 Tree browser’s toolbar is located directly below the menu bar.
Figure 125
Figure 125 The toolbar in the Request Tree 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; see “ New Browser ” on page 182 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.
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 411 for a discussion of the reports
that PerformaSure can provide.
Request Tree Browser 335
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
Clicking the Performance Diagnostics button displays a drop-down menu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest
Central is installed. When you select this option, the version of Spotlight
® included with Quest Central is launched.
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 browser’s Zonar and
Sightline to function independently.
Hide/Show Detail
The Hide/Show Detail button toggles the display of the Request Tree browser’s detail pane.
Show Panner
The Show Panner button causes the panner to appear in its own window.
See “ Show Panner ” on page 332 for more information about using the panner.
336 PerformaSure: User’s Guide
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 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 328 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 331 for more
information.
Time Control Panel
The Time Control panel is located directly below the Request Tree browser’s toolbar.
This panel has the same controls in all PerformaSure browsers. See “ Time
Control Panel ” on page 253 for a detailed description of its controls.
Request Tree Browser 337
Request Tree Browser Graph Pane—Summary
The following table describes the controls available in the graph pane. See
” on page 342 and “ Request Tree Tooltips ” on page 347 for
information about request trees, tree nodes, and tooltips in the graph pane.
Request Tree Browser Graph Pane
Control
Resize Sliders
Default Value Description
Minimum column width Control the width of the columns in which the tree nodes are displayed.
Toggle the display of method nodes within group nodes.
Disclosure Triangles Turned for expansion in group nodes
Show/Hide Child
Node Buttons
Show Child Node
Enabled
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.
Color Scale Toggle
Button
Zoom Control 100% 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 context (right-click) menus in the graph pane.
Request Tree Browser Graph Pane—Context Menu: Entry-Point Node
Control
Expand All Children
Hide Children
Show Children
Collapse All Children
Isolate Sub-Tree
Prune Node
Type
Menu item
Menu item
Menu item
Menu item
Menu item
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 352.
Prunes the entry-point node, causing all trees in the graph pane to be recolored accordingly. The node’s un-pruned sub-trees will remain unpruned. This node will display as ghosted, allowing it to be un-pruned.
338 PerformaSure: User’s Guide
Request Tree Browser Graph Pane—Context Menu: Entry-Point Node
Control
Prune Sub-Tree
Un-Prune Sub-Tree
Un-Prune All
Copy Node Name
View Response Times
View SQL Response Times
View Related Metrics
Performance Diagnostics
Export JProbe Launcher File
Type
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
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
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 node’s 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 354 for more information.
Launches a new Metrics browser based on metrics associated with the
entry-point node. See “ View Related Metrics ” on page 354 for more
information.
Disabled in entry-point nodes.
Disabled in HTTP nodes but enabled in other entry-point nodes.
Request Tree Browser Graph Pane—Context Menu: Group Node
Control
Hide Group Items
Show Group Items
Isolate Sub-Tree
Prune Node
Type
Menu item
Menu item
Menu item
Menu item
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 Sub-Tree ” on page 355.
Prunes the group node, causing all trees in the graph pane to be recolored accordingly. The node’s un-pruned sub-trees will remain un-pruned. The
display of pruned group nodes can vary. See “ Prune Node ” on page 356.
Request Tree Browser 339
Request Tree Browser Graph Pane—Context Menu: Group Node
Control
Prune Sub-Tree
Un-Prune Sub-Tree
Un-Prune All
Copy Node Name
View Response Times
View SQL Response Times
View Related Metrics
Performance Diagnostics
Export JProbe Launcher File
Type
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Description
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 356.
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 357 for more
information.
Launches a new Metrics browser based on metrics associated with the
group node. See “ View Related Metrics ” on page 357 for more information.
Enabled in JDBC group nodes. See “ Performance Diagnostics ” on page 357
for more information.
Disabled in the context menus for JDBC group nodes but enabled in other
group nodes. See “ Creating a JProbe Launcher File ” on page 368 for more
information.
Request Tree Browser Graph Pane—Context Menu: Method Node
Control
Expand All Children
Hide Children
Show Children
Collapse All Children
Type
Menu item
Menu item
Menu item
Menu item
Description
Expands and displays the method’s child nodes. This option is only available in the context menus of method nodes with collapsed child nodes.
Hides the method’s child nodes in their current state. This option is only available in the context menus of method nodes with visible child nodes.
Displays the method’s child nodes in the state in which they were hidden.
This option is only available in the context menus of method nodes with hidden child nodes.
Collapses and hides a method’s child nodes. This option is only available in the context menus of method nodes with visible child nodes.
340 PerformaSure: User’s Guide
Request Tree Browser Graph Pane—Context Menu: Method Node
Control
Isolate Sub-Tree
Prune Node
Prune Sub-Tree
Un-Prune Sub-Tree
Un-Prune All
Copy Node Name
View Response Times
View SQL Response Times
View Related Metrics
Performance Diagnostics
Type
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Menu item
Export JProbe Launcher File Menu item
Description
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 359.
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 359.
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 360.
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 node’s 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
Launches a new Metrics browser based on metrics associated with the node.
See “ View Related Metrics ” on page 357 for more information.
Enabled in the context menus for all method nodes. See “ Creating a JProbe
Launcher File ” on page 368 for more information.
Request Tree Browser Graph Pane—Full Detail
The Request Tree browser’s graph pane includes several elements.
Request Tree Browser 341
Figure 126
Figure 126 Elements in the Request Tree browser’s graph pane
Request Trees
The request trees in the Request Tree browser’s 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.
342 PerformaSure: User’s Guide
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 toolbar. See “ Active Metric ” on page 328 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 127
Figure 127 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
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 browser’s representation of the actual request tree doesn’t 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.
Request Tree Browser 343
This does not mean that the methods can’t 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 128. Detailed
information about the node’s 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 347 for more
information. Context menus are also available when you right-click on various
parts of a request tree. See “ Context Menus in the Graph Pane ” on page 351 for
details.
Figure 128
Figure 128 A basic group node
Basic group nodes are used for JSPs, Servlets, EJBs, and 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 129
Figure 129 An entry-point node representing an HTTP request
344 PerformaSure: User’s Guide
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 node’s Identifier bar will identify it as Other.
An example of a node representing an outgoing RMI call is shown in Figure 130.
Other types of RMI Outgoing nodes will have the protocol that was used (T3,
IIOP, HTTP, or JRMP) listed in the header instead of RMI. When the display mode is set to Component Technology (View > Display By), the tooltip for this node’s Identifier bar will identify it as RMI Outgoing.
Figure 130
Figure 130 An RMI Outgoing node with RMI listed in the header
A Web Client node is shown in Figure 131. Web Client nodes represent outgoing
HTTP connections made by means of java.net.URL
and supporting classes only. The header for this type node will display the hostname and port number of the destination machine (if available) or the IP address and port number. When the display mode is set to Component Technology (View > Display By), the tooltip for this node’s Identifier bar will identify it as Web Client.
Figure 131
Figure 131 A Web Client node
A node representing a JDBC call is shown in Figure 132.
Figure 132
Figure 132 A JDBC group node
Request Tree Browser 345
As shown in Figure 132, 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
10g), 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 133.
JMS and JNDI group nodes have the shape of a truncated diamond.
Figure 133
Figure 133 A 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 class’s 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 node’s 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
346 PerformaSure: User’s Guide
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 tooltip’s 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.
Request Tree Browser 347
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 tracked using Tag and Follow. Only root nodes display the Sampled Requests field.
Note: The Called in Requests field shows the number of requests in which an object was called during the interval spanned by the Zonar. For root nodes, the Called in Requests field always displays the same value as the
Call Count field.
As shown in Figure 134 and Figure 135, 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 134
Figure 134 Tooltip for an HTTP node when Per Request is selected
Figure 135
Figure 135 Tooltip for an HTTP node when Per Call is selected
348 PerformaSure: User’s Guide
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 occurred is recorded.
Tooltips for group and method nodes
The tooltips for group and method 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 the tooltip for an EJB group node, 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 average call count shows 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 requestaveraged call count of 2.5. When Per Call is selected, the call count 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 136
Figure 136 Tooltip for a method node in an EJB group node when Per Request is selected
Request Tree Browser 349
If you compare Figure 136 to Figure 137, 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 137
Figure 137 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 application’s 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.
The Called in Requests field shows the number of requests in which the object was
called during the interval spanned by the Zonar. As shown in Figure 136 and
Figure 137, the value of Called in Requests for the EJB is the same as the EJB’s Call
Count. This is because the EJB was called once per request.
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 138. It contains extra fields in which
the volume of traffic for passing method parameters and for receiving returned data is displayed.
As with HTTP nodes, the Called in Requests field in the tooltip for an RMI node displays the same value as the Call Count field.
350 PerformaSure: User’s Guide
Figure 138
Figure 138 Tooltip for an RMI node when Per Request is selected
Context Menus in the Graph Pane
You can right-click anywhere on or around the request trees to make a context 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... > Graphs), 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 context menu (Figure 139).
Request Tree Browser 351
Figure 139
Figure 139 The context menu for an entry-point node
Expand All Children
If any of an entry-point node’s 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 node’s 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 node’s 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 node’s children are showing, the choice Collapse All Children is available. Select this option to hide and collapse the request’s 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... > Graphs), this node’s previously pruned sub-trees will either remain hidden or continue to display as
352 PerformaSure: User’s Guide
ghosted when you select Isolate Sub-Tree. If you did not check the Hide
Pruned Sub-Trees 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 node’s 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... > Graphs), selecting this option will cause this node’s 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 node’s sub-trees have been pruned.
If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options... > Graphs), selecting this option will cause this node and its sub-tree 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.
Request Tree Browser 353
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 node’s 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.
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 context menus for other group
nodes and for all method nodes. See “ Creating a JProbe Launcher File ” on page
Right-clicking the Header of a Group Node
Right-click on the header of a group node to make a context menu appear for that
node (Figure 140). This menu contains many of the same choices as the context
menu for an entry-point node.
354 PerformaSure: User’s Guide
Figure 140
Figure 140 The context 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... > Graphs), this node’s 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 Sub-Trees checkbox in the Edit Options dialog, selecting Isolate Sub-
Tree will cause all other (non-isolated) nodes and sub-trees to display as ghosted.
Request Tree Browser 355
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 expensive—but still problematic—nodes that might otherwise have been overshadowed.
If you did not check the Hide Pruned Sub-Trees checkbox in the Edit Options dialog (View > Options... > Graphs), 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 context 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... > Graphs), 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... > Graphs), selecting this option will cause the node and its sub-tree 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... > Graphs), selecting this option will cause this node and its sub-trees to no longer display as ghosted.
356 PerformaSure: User’s Guide
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 node’s 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.
Selecting the Performance Diagnostics menu item displays a submenu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest Central is installed. When you select this option, the version of Spotlight
®
included with
Quest Central is launched.
Request Tree Browser 357
Export JProbe Launcher File
The option Export JProbe
™
Launcher File is disabled in JDBC group nodes but
enabled in the context menus for other group nodes. See “ Creating a JProbe
Launcher File ” on page 368 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 context menu appear (Figure 141). The choices in this menu are
similar to those in the context 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 context menus for method nodes with child nodes.
Figure 141
Figure 141 The context menu for a method node
Expand All Children
If a method’s 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 method’s child nodes.
Hide Children
If a method’s child nodes are visible, the choice Hide Children is available.
Select this option to hide the child nodes in their current state.
358 PerformaSure: User’s Guide
Show Children
If a method’s 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 method’s 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-tree’s 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 node’s sub-tree.
If you have not checked the Hide Pruned Sub-Trees checkbox in the Edit
Options dialog (View > Options... > Graphs), 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... > Graphs), 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 node’s header. A context 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... > Graphs), selecting this option will cause the method node to no longer display as ghosted.
Request Tree Browser 359
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... > Graphs), 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... > Graphs), 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.
360 PerformaSure: User’s Guide
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 357 for more information.
Performance Diagnostics
The menu item Performance Diagnostics is enabled in JDBC group nodes.
Selecting the Performance Diagnostics menu item displays a submenu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest Central is installed. When you select this option, the version of Spotlight
®
included with
Quest Central is launched.
Export JProbe Launcher File
The option Export JProbe
™
Launcher File menu item is enabled in the context
menus for all method nodes. See “ Creating a JProbe Launcher File ” on page 368
for details.
Right-clicking a Disclosure Triangle
Right-click on a Disclosure Triangle and a context menu appears (Figure 142). This
menu contains some of the same options as the context menu for a group node.
See “ Hide Group Items ” on page 355 and “ Show Group Items ” on page 355 for
details.
Figure 142
Figure 142 The context 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 context menu appears. This menu contains some of the same options as the context menu for a method node. See
“ Expand All Children ” on page 358, “ Hide Children
Children ” on page 359, and “ Collapse All Children ” on page 359 for details.
Request Tree Browser 361
Figure 143
Figure 143 The context 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 browser’s 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 don’t 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.
Note that focus will not be transferred to nodes that were pruned or excluded and are hidden; however, focus will be transferred to nodes that were pruned or excluded and are displayed as ghosted.
Transferring focus to a hidden child node will cause it to be displayed again.
362 PerformaSure: User’s Guide
Figure 144
Figure 144 The detail pane in the Request Tree browser
Detail Pane Columns
The columns in the detail pane are described next.
Tip: Click on a column header in the detail pane to sort the rows based on the values in that column.
Name
The Name column lists the URLs that were called during the interval spanned by
the Time Control panel’s Zonar; see “ Time Control Panel ” on page 253 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.
Note: This column is hidden by default. To display this column in the detail pane, select Show/Hide Columns... from the detail pane context menu or from the View menu and then select the Agent checkbox.
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.
Request Tree Browser 363
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%.
Called in Requests
The Called in Requests column lists the number of requests in which the object was called during the interval spanned by the Zonar.
For root nodes, the Called in Requests column always displays the same value as the call count.
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.
This value is unknown when the row shows an aggregate of multiple nodes in the request tree. In this case, a dash (-) is listed in this column.
Note: This column is hidden by default. To display this column in the detail pane, select Show/Hide Columns... from the detail pane context menu or from the View menu and then select the Max Cumulative Time checkbox.
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.
This value is unknown when the row shows an aggregate of multiple nodes in the request tree. In this case, a dash (-) is listed in this column.
364 PerformaSure: User’s Guide
Note: This column is hidden by default. To display this column in the detail pane, select Show/Hide Columns... from the detail pane context menu or from the View menu and then select the Min Cumulative Time checkbox.
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
Settings dialog or using 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.
This value is unknown when the row shows an aggregate of multiple nodes in the request tree. In this case, a dash (-) is listed in this column.
Note: This column is hidden by default. To display this column in the detail pane, select Show/Hide Columns... from the detail pane context menu
Request Tree Browser 365
or from the View menu and then select the Max Parameter Data
Serialized checkbox.
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.
This value is unknown when the row shows an aggregate of multiple nodes in the request tree. In this case, a dash (-) is listed in this column.
Note: This column is hidden by default. To display this column in the detail pane, select Show/Hide Columns... from the detail pane context menu or from the View menu and then select the Min Parameter Data
Serialized checkbox.
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.
This value is unknown when the row shows an aggregate of multiple nodes in the request tree. In this case, a dash (-) is listed in this column.
Note: This column is hidden by default. To display this column in the detail pane, select Show/Hide Columns... from the detail pane context menu or from the View menu and then select the Max Return Data
Serialized checkbox.
366 PerformaSure: User’s Guide
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.
This value is unknown when the row shows an aggregate of multiple nodes in the request tree. In this case, a dash (-) is listed in this column.
Note: This column is hidden by default. To display this column in the detail pane, select Show/Hide Columns... from the detail pane context menu or from the View menu and then select the Min Return Data
Serialized checkbox.
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.
List/Tree Toggle Button
Use the list/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
Request Tree Browser 367
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.
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 method’s 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.
2.
Select JProbe x from the JPL File Format drop-down menu in the Request
Tree pane.
3.
Click OK to confirm your selection and close the dialog.
4.
Select one or more method nodes in the Request Tree browser.
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 context menu obtained by right-clicking one of the method nodes you selected.
368 PerformaSure: User’s Guide
6.
From the submenu that appears, choose either Profile Selected Package(s)... or Profile Selected Class(es)....
7.
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
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 134 for more information.
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.
Why do I see a tree node labelled “External System”?
An External System node (shown in Figure 146) appears in the request tree if an
instrumented server has crashed or failed and other instrumented servers attempt to call that server while the session is being recorded.
Figure 146
Figure 146 An External System node
What’s in a JDBC node?
Request Tree Browser 369
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 147 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 147
Figure 147 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 70 for information on how to
modify PerformaSure defaults in order to include or exclude specific classes.
370 PerformaSure: User’s Guide
Chapter 16
Metrics Browser
■
■
■
■
■
■
■
■
■
The following topics are covered in this chapter:
Metrics Browser Navigation Pane
Metrics Browser Graph Pane—Summary
Metrics Browser Graph Pane—Full Detail
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 408 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.
371
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 148
Figure 148 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, 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.
372 PerformaSure: User’s Guide
Raw Metrics
Periodic metrics are collected by PerformaSure by polling the system under test.
Operating system and application server metrics are collected at set intervals.
Other approaches are used for collecting network metrics and service request metrics.
By default, raw metrics are not listed in the Metrics browser. Follow the instructions below to cause raw metrics to be displayed in the Metrics browser’s navigation pane.
To display raw metrics:
1.
Select Tools > Options... from the menu bar. The Edit Options dialog will open.
2.
In the tree view, click on Browsers > Metrics.
3.
Select Show Raw Metrics.
4.
Click OK to apply this change and close the dialog. Raw metrics will be listed at the bottom of the navigation pane.
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.
Menus and Toolbar—Summary
Menu Bar
The Metrics browser’s 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 Bar—Browser Menu
Control
New Browser
Type Default Value Description
Menu item Enabled Opens the New Browser dialog. Use this dialog to choose the type of browser you want to launch.
Metrics Browser 373
Metrics Browser Menu Bar—Browser Menu
Control
Add New
Browser To
Project
Export Report
Type Default Value
Menu item Enabled
Description
Adds the browser to your PerformaSure Project. A Metrics browser icon will appear in the Browsers area of the Project window.
Menu item Enabled
Properties
Close
Exit
PerformaSure
Menu item Enabled
Menu item Enabled
Menu item Enabled
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
Closes the browser.
Closes all open Projects and browsers and shuts down the
Workstation.
Metrics Browser Menu Bar—View Menu
Control
Close All Charts
Type
Menu item
Default Value
N/A
Description
Closes all metric charts in the graph pane.
Metrics Browser Menu Bar—Tools Menu
Control Type
Recording Control Window Menu item
Session Management Menu item
Thresholds
Change Password
User Management
Menu item
Menu item
Menu item
Performance Diagnostics Menu item
Options Menu item
Default Value
Enabled
Enabled
Enabled
Enabled
Disabled
N/A
Enabled
Description
Launches the Recording Control window.
Opens the Session Management dialog.
Launches the Threshold Editor.
Opens the Change Password dialog.
Launches the User Management window. This menu item is enabled if you have the required permissions.
Displays a submenu with one option. See
“ Performance Diagnostics ” on page 378 for more
information.
Launches the Edit Options dialog.
374 PerformaSure: User’s Guide
Metrics Browser Menu Bar—Windows Menu
Control
Bring All To Front
[Switch to a Project window]
[Switch to a browser]
Type Default Value Description
Menu item Enabled
Menu item Enabled
Menu item Enabled
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.
Metrics Browser Menu Bar—Help Menu
Control
Help
About
Type Default Value Description
Menu item Enabled
Menu item Enabled
Launches context-sensitive help for this browser.
Opens a new window that displays product information about PerformaSure.
Toolbar
Add New Browser To
Project
Export Report
Button
Button
Under the Metrics browser’s 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
Button and drop-down menu
Default Value
Enabled
Enabled
Enabled
Description
Clicking on the left-hand side of this button launches the
New Browser dialog. See “ New Browser ” on page 182
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 379 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.
Metrics Browser 375
Metrics Browser Toolbar
Control
Properties
Type
Button
Performance
Diagnostics
Get Live Updates
Button and drop-down menu
Check box
Update Browser Data Button
Link Browsers To Use
Same Zone/Break
Link Between
Browsers
Button
Default Value
Enabled
N/A
On
N/A
Enabled
Description
Launches the Browser Properties dialog. See
“ Properties ” on page 380 for details.
Displays a drop-down menu with one option. See
“ Performance Diagnostics ” on page 380 for more
information.
Launches an automatic data collection update and
refreshes the display of data in a browser. See “ Live
Data Updates ” on page 259 for more details.
Forces a live data collection update. See “ Live Data
Updates ” on page 259 for more details.
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 380 for more information.
Menus and Toolbar—Full Detail
Menu Bar—Browser 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 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
376 PerformaSure: User’s Guide
chooser is launched so that you can supply a file name for the report. See
“ PerformaSure Reports ” on page 411 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 Bar—View
Close All Charts
Click Close All Charts to close all metric charts that are currently displayed in the graph pane.
Menu Bar—Tools
Recording Control Window
Select Recording Control Window... to launch the Recording Control window.
See “ Recording Control Window ” on page 197 for more information about using
the controls in this window.
Session Management
Select Session Management... to open the Session Management dialog. See
“ Session Management ” on page 164 for more information about using this dialog.
Metrics Browser 377
Thresholds
Change Password
Select Change Password... to open the Change Password dialog. See “ Changing a
Password ” on page 154 for more information about using this dialog.
User Management
Select User Management... to launch the User Management window. See “ User
Management ” on page 154 for details about using this window.
Note: This item is disabled if you do not have the required permissions.
Performance Diagnostics
Selecting the Performance Diagnostics menu item displays a submenu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest Central is installed. When you select this option, the version of Spotlight
®
included with
Quest Central is launched.
Options
Selecting the Options... menu item launches the Edit Options dialog. See “ Edit
Options Dialog ” on page 247 for details about using this dialog.
Menu Bar—Windows
The Windows menu’s one static choice is Bring All To Front, which ensures that all open PerformaSure windows have a higher stacking order than non-
PerformaSure 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.
378 PerformaSure: User’s Guide
Menu Bar—Help
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 Metrics browser’s toolbar is located directly below the menu bar.
Figure 149
Figure 149 The toolbar in the Metrics 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; see “ New Browser ” on page 182 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.
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 411 for a discussion of the reports
that PerformaSure can provide.
Metrics Browser 379
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
Clicking the Performance Diagnostics button displays a drop-down menu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest
Central is installed. When you select this option, the version of Spotlight
® included with Quest Central is launched.
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 browser’s Zonar and
Sightline to function independently.
Time Control Panel
The Time Control panel is located directly below the Metrics browser’s toolbar. This
panel has the same controls in all PerformaSure browsers. See “ Time Control
Panel ” on page 253 for a detailed description of its controls.
380 PerformaSure: User’s Guide
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 464 for a description of the structure of the metric
hierarchy that is displayed in the navigation pane.
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
Metrics Browser 381
■ Ctrl-click or Shift-click the metrics in the navigation pane and right-click on the selected metrics to cause a context 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 385 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 context menu that appears.
Metrics Browser Graph Pane—Summary
The following tables describe the controls and the context (right-click) menus available in each chart in the graph pane.
Metrics Browser Graph Pane
Control
Chart header
Function Set chooser
Plot Type chooser
Type Default Value Description
Drop-down menu Enabled
Drop-down menu Enabled
Drop-down menu Enabled
Maximize Chart Button
Restore Chart Button
Close Chart
Sightline slider
Button
Slider
Enabled
Enabled
Enabled
Enabled
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.
382 PerformaSure: User’s Guide
Metrics Browser Graph Pane
Control Type Default Value
Legend entries Metric Indicators Enabled
Description
Clicking an Indicator changes the active metric (in a multiple-
metric chart). See “ Using the Legend ” on page 385 for more
information.
Displays a menu from which you can select the chart type.
Chart Type chooser
Drop-down menu
Edit Thresholds Button
Enabled
Enabled Opens the Threshold Editor for the metric (in a single-metric chart) or for the active metric (in a multiple-metric chart).
Metrics Browser Graph Pane—Context Menus
Control
Function for Selected Metric
Type
Drop-down menu
Description
Displays a menu from which you can select the function applied to the active metric.
Plot Type for Selected Metric
Find Selected Metric in Hierarchy Menu item
Copy
Paste
Delete
Menu item
Menu item
Menu item
Maximize Chart
Drop-down menu
Displays a menu from which you can select the plot type applied to
the active metric. See “ Plot Type For Selected Metric ” on page 389
for more information.
Highlights the active metric in the metric hierarchy.
Menu item
Copies the active metric.
Pastes the metric that you copied.
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.
Restore Chart
Close Chart
Close All Charts
Menu item
Menu item
Menu item
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 383
Metrics Browser Graph Pane—Full Detail
The Metrics browser’s graph pane includes several elements.
Figure 150
Figure 150 Elements in the Metrics browser’s graph pane
Charts in the Graph Pane
You can open a collection of charts in the Metrics browser’s 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
384 PerformaSure: User’s Guide
Metrics For Display ” on page 381 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.
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
Metrics Browser 385
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 metric’s 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
386 PerformaSure: User’s Guide
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.
Note: To change the function applied to a single metric in the chart, right-click the metric to cause a context 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.
When Stacked is selected from the Chart Type chooser, the options available in this menu are Stacked Bar and Stacked Area. The plot type that you select is applied to all metrics in the chart.
Tip: Hover the cursor over the Plot Type chooser icon to make a tooltip appear that displays the plot type that is currently selected.
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 256 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 200 and “ Timeline ” on page
253 for more information about time slices and time slice boundaries.
Metrics Browser 387
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 multiple-
metric chart). See “ Threshold Editor ” on page 408 for details about the Threshold
Editor. See “ Thresholds Browser FAQ ” on page 410 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 to maximize a chart in the graph pane.
Restoring a Chart
Click the Restore Chart button to restore a maximized chart to its former size.
Closing a Chart
Click the Close Chart button to close a chart in the graph pane.
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 metric and the function applied to that metric are displayed.
Figure 151
Figure 151 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.
388 PerformaSure: User’s Guide
Figure 152
Figure 152 The tooltip for a data point
Context Menus in the Graph Pane
You can right-click anywhere in a chart in the graph pane to make a context menu appear.
Function for Selected Metric
Click Function for Selected Metric to cause a submenu to appear from which you can select the function applied to the active metric.
Plot Type For Selected Metric
Click Plot Type for Selected Metric to cause a submenu to appear from which you can select the plot type applied to the active metric. 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.
Find Selected Metric in Hierarchy
Click Find Selected Metric in Hierarchy to cause the active metric to be highlighted in the metric hierarchy in the Metrics browser’s navigation pane.
Copy
Click Copy to copy the active metric, allowing you to paste it into another metric chart. You can also paste the metric name into another application, such as a spreadsheet.
Paste
Click Paste to paste the metric that you copied.
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
Metrics Browser 389
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 pane’s tree hierarchy.
Maximize Chart
Select this menu item to maximize the chart on which you right-clicked in the graph pane.
Restore Chart
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: .
390 PerformaSure: User’s Guide
Chapter 17
Thresholds Browser
■
■
■
■
■
■
■
■
The following topics are covered in this chapter:
Thresholds Browser Graph Pane—Summary
Thresholds Browser Graph Pane—Full Detail
•
•
•
Context Menus in the Graph Pane
■
Thresholds Browser Detail Pane
•
•
•
Context Menus in the Detail Pane
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.
391
As shown in Figure 153, the display name used as the header for the graph pane
identifies the metric that is selected in the detail pane.
Figure 153
Figure 153 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.
392 PerformaSure: User’s Guide
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.
Menus and Toolbar—Summary
Menu Bar
The Thresholds browser’s 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 Bar—Browser Menu
Control
New Browser
Add New
Browser To
Project
Export Report
Type Default Value Description
Menu item Enabled Opens the New Browser dialog. Use this dialog to choose the type of browser you want to launch.
Menu item Enabled Adds the browser to your PerformaSure Project. A Thresholds browser icon will appear in the Browsers area of the Project window.
Menu item Enabled
Properties
Close
Exit
PerformaSure
Menu item Enabled
Menu item Enabled
Menu item Enabled
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
Closes the browser.
Closes all open Projects and browsers and shuts down the
Workstation.
Thresholds Browser Menu Bar—View Menu
Control Type
Auto-Fit All Columns Menu item
Default Value
Enabled
Show/Hide Columns Menu item 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.
Thresholds Browser 393
Thresholds Browser Menu Bar—View Menu
Control
Show/Hide Bar
Charts
Type
Menu item
Default Value
Enabled
Show Filter Bar Menu item with checkbox
Selected
Description
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 397 for more
information about using the controls in the Filter Bar.
Thresholds Browser Menu Bar—Tools Menu
Control Type
Recording Control Window Menu item
Session Management Menu item
Thresholds
Change Password
User Management
Menu item
Menu item
Menu item
Default Value
Enabled
Enabled
Enabled
Enabled
Disabled
Performance Diagnostics Menu item
Options Menu item
N/A
Enabled
Description
Launches the Recording Control window.
Opens the Session Management dialog.
Launches the Threshold Editor.
Opens the Change Password dialog.
Launches the User Management window. This menu item is enabled if you have the required permissions.
Displays a submenu with one option. See
“ Performance Diagnostics ” on page 398 for more
information.
Launches the Edit Options dialog.
Thresholds Browser Menu Bar—Windows Menu
Control
Bring All To Front
[Switch to a Project window]
[Switch to a browser]
Type Default Value Description
Menu item Enabled Ensures that all open PerformaSure windows have a higher stacking order than non-PerformaSure windows.
Menu item Enabled
Menu item Enabled
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.
394 PerformaSure: User’s Guide
Thresholds Browser Menu Bar—Help Menu
Control
Help
About
Type Default Value Description
Menu item Enabled
Menu item Enabled
Launches context-sensitive help for this browser.
Opens a new window that displays product information about PerformaSure.
Toolbar
Thresholds Browser Toolbar
Control
New Browser
Type
Button and drop-down menu
Add New Browser To
Project
Export Report
Button
Button
Properties
Performance
Diagnostics
Get Live Updates
Under the Thresholds browser’s menu bar is a toolbar with controls for opening new PerformaSure browsers, launching Spotlight
®
and Quest database tools, controlling the view in the Thresholds browser’s graph and detail panes, and performing other actions like exporting a report. The following table describes the controls available from the toolbar.
Button
Button and drop-down menu
Check box
Update Browser Data Button
Default Value
Enabled
Enabled
Enabled
Enabled
N/A
On
N/A
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 399 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 400 for details.
Displays a drop-down menu with one option. See
“ Performance Diagnostics ” on page 400 for more
information.
Launches an automatic data collection update and
refreshes the display of data in a browser. See “ Live
Data Updates ” on page 259 for more details.
Forces a live data collection update. See “ Live Data
Updates ” on page 259 for more details.
Thresholds Browser 395
Thresholds Browser Toolbar
Control Type
Link Browsers To Use
Same Zone/Break
Link Between
Browsers
Button
Default Value
Enabled
Description
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 400 for more information.
Menus and Toolbar—Full Detail
Menu Bar—Browser 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 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 411 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.
396 PerformaSure: User’s Guide
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 Bar—View
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 Metrics bar at the bottom of the graph pane.
Using the Thresholds browser’s Filter Metrics bar
You can enter a literal string or a regular expression in the Filter Metrics bar’s
Filter Metrics 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 Metrics text field contains an empty literal
Thresholds Browser 397
Tip: If you enter a regular expression in the Filter Metrics text field, ensure that the Regular Expression checkbox is selected before you click
Apply.
Menu Bar—Tools
Recording Control Window
Select Recording Control Window... to launch the Recording Control window.
See “ Recording Control Window ” on page 197 for more information about using
the controls in this window.
Session Management
Select Session Management... to open the Session Management dialog. See
“ Session Management ” on page 164 for more information about using this dialog.
Thresholds
Change Password
Select Change Password... to open the Change Password dialog. See “ Changing a
Password ” on page 154 for more information about using this dialog.
User Management
Select User Management... to launch the User Management window. See “ User
Management ” on page 154 for details about using this window.
Note: This item is disabled if you do not have the required permissions.
Performance Diagnostics
Selecting the Performance Diagnostics menu item displays a submenu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest Central is installed. When you select this option, the version of Spotlight
®
included with
Quest Central is launched.
398 PerformaSure: User’s Guide
Options
Selecting the Options... menu item launches the Edit Options dialog. See “ Edit
Options Dialog ” on page 247 for details about using this dialog.
Menu Bar—Windows
The Windows menu’s one static choice is Bring All To Front, which ensures that all open PerformaSure windows have a higher stacking order than non-
PerformaSure 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 Bar—Help
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 Thresholds browser’s toolbar is located directly below the menu bar.
Figure 154
Figure 154 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.
Thresholds Browser 399
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 411 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
Clicking the Performance Diagnostics button displays a drop-down menu with one option: Spotlight
®
in Quest Central. This option is enabled if Quest
Central is installed. When you select this option, the version of Spotlight
® included with Quest Central is launched.
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.
400 PerformaSure: User’s Guide
Click the Break Link Between Browsers button to return the browsers’
Time Control panels to an unlinked state. This allows each browser’s Zonar and
Sightline to function independently.
Time Control Panel
The Time Control panel is located directly below the Thresholds browser’s toolbar.
This panel has the same controls in all PerformaSure browsers. See “ Time
Control Panel ” on page 253 for a detailed description of its controls.
Thresholds Browser Graph Pane—Summary
The following table describes the controls available in the graph pane.
Thresholds Browser Graph Pane
Control Type
Chart header
Function Set chooser
Plot Type chooser
Drop-down menu
Drop-down menu
Drop-down menu
Enabled
Enabled
Enabled
Sightline slider
Chart Type chooser
Slider
Edit Thresholds Button
Enabled
Drop-down menu Enabled
Enabled
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.
Displays a menu from which you can select the chart type.
Opens the Threshold Editor for the active metric.
Thresholds Browser Graph Pane—Context Menus
Control
Function for Selected Metric
Plot Type for Selected Metric
Copy
Type Description
Drop-down menu
Drop-down menu
Menu item
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 metric charted in the graph pane.
Copies the metric charted in the graph pane.
Thresholds Browser 401
Thresholds Browser Graph Pane—Full Detail
The Thresholds browser’s graph pane includes several elements.
Figure 155
Figure 155 Elements in the Thresholds browser’s graph pane; the Chart Type is set to Default and the Plot Type is set to Line.
Charts in the Graph Pane
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.
402 PerformaSure: User’s Guide
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 408 for details about the Threshold Editor. See
“ Thresholds Browser FAQ ” on page 410 for information about the availability of
the Edit Thresholds button.
Thresholds Browser 403
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 metric and the function applied to it are displayed.
Figure 156
Figure 156 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.
Figure 157
Figure 157 The tooltip for a data point
Context Menus in the Graph Pane
You can right-click anywhere in a chart in the graph pane to make a context menu appear.
Function for Selected Metric
Click Function for Selected Metric to cause a submenu to appear from which you can select the function applied to the metric that is charted in the graph pane.
Plot Type For Selected Metric
Select Plot Type for Selected Metric to cause a submenu to appear from which you can select the plot type applied to the metric that is charted in the graph pane. 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.
404 PerformaSure: User’s Guide
Copy
Click Copy to copy the metric that is charted in the graph pane, allowing you to paste it into a chart in the Metrics browser. You can also paste the metric name into another application, such as a spreadsheet.
Thresholds Browser Detail Pane
The Thresholds browser’s 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 system’s 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 158
Figure 158 The detail pane in the Thresholds browser
Detail Pane Columns
The columns in the detail pane are described below.
Figure 159
Figure 159 The column headers in the Thresholds browser’s 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.
Thresholds Browser 405
Function
The Function column lists the function applied to the metric with threshold
violations. See “ Setting Thresholds ” on page 410 for more information about how
metrics with threshold violations are listed in the Thresholds browser’s 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 applied to the metric have been exceeded during the interval spanned by the Zonar.
The total duration of a threshold violation is calculated by multiplying the number of time slices in which a threshold violation occurs by the sample rate of the metric. If the sample rate is unavailable for a certain metric, the number of time slices in which a threshold violation occurs is multiplied by the session’s time slice size. For example, if a threshold violation occurs in five time slices during the interval spanned by the Zonar and the sample rate for the metric is 20 seconds, then the value listed in the Total Duration column will be 100 .
Bar Charts in the Detail Pane
The bar charts in the Violation Count and Total Duration columns in the Thresholds browser’s detail pane allow you to visually compare the values listed in these
columns for multiple metrics with threshold violations (see Figure 158).
Context Menus in the Detail Pane
You can right-click anywhere in the detail table to make a context menu appear.
The items in these menus are described below.
406 PerformaSure: User’s Guide
Figure 160
Figure 160 A context 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.
Thresholds Browser 407
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 browser’s 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 410 for more information.
Figure 161
Figure 161 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 161). 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
408 PerformaSure: User’s Guide
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 464 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 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.
Thresholds Browser 409
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 browser’s 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
I’ve 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.
410 PerformaSure: User’s Guide
Chapter 18
PerformaSure Reports
■
■
■
■
■
■
■
■
The following topics are covered in this chapter:
•
•
•
•
•
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.
411
Generated Reports
Before you generate a report, you must first select report options, then configure the browser on which the report will be based.
Customizing Reports
The Edit Options dialog contains several options for customizing generated reports. To access these options, select Tools > Options... from the menu bar in the Project window or in any browser, then select Reports from the left-hand side of the dialog. The options in the Reports pane are described below.
Figure 162
Figure 162 Choices for customizing reports in the Edit Options dialog
Customizing PDF Reports
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 report’s 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.
You select these options in the Reports pane of the Edit Options dialog (Tools >
Options... > Reports). These options are described 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.
412 PerformaSure: User’s Guide
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 report’s 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.
Customizing CSV and XML Reports
You can choose whether or not to round values in CSV and XML reports in the
Reports pane of the Edit Options dialog (Tools > Options... > Reports). The checkbox Do Not Round Values In CSV Or XML Reports is selected by default. Deselect this checkbox if you would like the values in CSV and XML reports to be rounded. Rounded values have a maximum of three decimal places.
Choosing the Report Option
To generate a report:
1.
Set up the PerformaSure browser the way you want it to look in the report.
2.
Click the Export Report button in the browser’s 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
Clicking the Continue button in the Request Tree Report dialog launches the
Save 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.
PerformaSure Reports 413
The appearance and structure of a report depends on the type of report that you
generate and the file format you select (PDF, CSV, or XML). See “ PDF Reports ”,
“ CSV Format ”, and “ XML Format ”, below for more information about the
different file formats. See “ Threshold Report
Report ” on page 418, “ SQL Report
” on page 418, and “ Request Tree Report ” on page 419, and “
Metric Report ” on page 420 for more information about the
different types of reports.
PDF Reports
In PDF format, generated reports contain a header and a body. See “ Customizing
PDF Reports ” on page 412 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 browser’s Zonar.
In all reports except the Request Tree Report and 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 164 for an example of a PDF Request 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.
414 PerformaSure: User’s Guide
Figure 163
Figure 163 A report in PDF format
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, 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 browser’s 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 419 for
more information about using this dialog.
PerformaSure Reports 415
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:,2006/03/06 09:12
Session:,TestSession_2006-Mar-04 11:12:13
Reporting Period Start:,03/04/2006 11:12
Reporting Period End:,03/04/2006 11:14
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.
416 PerformaSure: User’s Guide
Example: <?xml version="1.0" encoding="UTF-8" ?>
<report name="Threshold Report" generated-on="Mar 6,
2006 9:12:15 AM" timezone="EDT">
<session name="TestSession_2006-Mar-04 11:12:13" start-time="Mar 04, 2006 11:12:13 AM" end-time="Mar
04, 2006 12:13:14 PM" />
<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>
PerformaSure Reports 417
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.
418 PerformaSure: User’s Guide
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 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 328, “ Metric Display ”
on page 328, and “ Bundling Mode ” on page 331 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 in a numbered list. 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 328 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 164.
Figure 164
Figure 164 A sample Request Tree Report in PDF format
PerformaSure Reports 419
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 within each request (based on the active metric) 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.
420 PerformaSure: User’s Guide
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 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 Reports ” on page 412 for more information.
PerformaSure Reports 421
422 PerformaSure: User’s Guide
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 165.
Figure 165
Figure 165 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 41705.
425
■
■
■
■
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 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.
426 PerformaSure: User’s Guide
Example usage:
AgentName = “Some Agent Name”;
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:
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 = 41705;
Appendix A—Configuring PerformaSure 427
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).
Example usages:
To try the connection every five seconds:
NexusRetryInterval = 5000;
To prevent the connection from being retried if it is dropped:
NexusRetryInterval = 0;
Attempting to Reconnect to the Nexus After an Authentication
Failure
NexusAuthFailureRetryInterval
Sets the amount of time that the Agent will wait before trying to connect to the
Nexus after an authentication failure. This setting is required.
What it is used for:
If the Agent fails on its initial attempt to connect to the Nexus due to an authentication failure (such as a build number mismatch or expired licensing), it tries to connect at regular intervals. NexusAuthFailureRetryInterval sets the interval in milliseconds between such attempts. A value of 0 will prevent the
Agent from attempting to reconnect after an authentication failure. The default setting is 120000 (2 minutes).
Example usages:
To try the connection every two minutes:
NexusAuthFailureRetryInterval = 120000;
To prevent the connection from being retried after an authentication failure:
NexusAuthFailureRetryInterval = 0;
428 PerformaSure: User’s Guide
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.
The Agent sends an authentication request to the Nexus.
2.
The Nexus checks the license number for the Agent and responds with the message, “ Authentication approved ”.
3.
The Agent sends a message indicating that it acknowledges the Nexus’ authentication approval. The Agent is now ready to collect data.
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 option 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;
Appendix A—Configuring PerformaSure 429
Launching a System Agent
CanLaunchSystemAgent
May have a boolean value of either true or false . This configuration option determines whether the Agent can launch a System Agent if the Nexus requests it.
Example usage:
The default setting is:
CanLaunchSystemAgent = true;
Configuring the Nexus
Many runtime parameters can be set for the Nexus. For example, you can:
• Specify a location for the sessions directory other than the default.
• Change the default settings for the port that the Nexus uses to communicate with the Agents, the Workstations, and nexusctl.
• 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 ListenHost or ListenPort .
Changing the Sessions Directory
SessionDirectory
Sets the location of the data collected in a session.
430 PerformaSure: User’s Guide
What it is used for:
The data collected by PerformaSure is kept in session files on the machine hosting the Nexus. 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 directory where the Nexus stores sessions 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.
Appendix A—Configuring PerformaSure 431
Configuring the Communication Ports Used by the Nexus
ListenHost and ListenPort
Set the host and port that the Nexus uses to communicate with Agents,
Workstations, and nexusctl using the NexusTalk 2 protocol (NT2).
Important: If the Nexus is behind a firewall, then the firewall must be configured to allow connections to be made from any Agents or
Nexus clients (the Workstation or nexusctl) that are on the other side of the firewall to the Nexus on the port number specified by ListenPort .
If there is no firewall between the Nexus and the Agents and the Nexus and Nexus clients (the Workstations or nexusctl), then
ListenPort in <performasure_home>/config/nexus.config,
NexusPort in <performasure_home>/config/agent.config, and the
Port field in the Workstation’s Define Nexus dialog (for the
Nexus instance that you have selected) must always be set to the same port number. If you change the value of ListenPort , you must follow the steps listed below.
1.
Update the value of NexusPort in the agent.config files for all Agents to match the new value of ListenPort .
2.
Logout from the Workstation if it is running (click the Logout button in the Startup window). Launch the Workstation if it is not running.
• From the Login window, click Define... to open the Define Nexus dialog. Select the Nexus instance that you want to edit and click
Edit....
• Update the Port field in the Edit Nexus dialog to match the new value of ListenPort . Click OK to save your changes and close the Edit
Nexus dialog, then click OK to close the Define Nexus dialog.
• Click Exit in the Startup window to shut down the Workstation.
• Repeat these steps for all Workstations that will connect to the Nexus on the new port number.
3.
Restart the Nexus, the Agents, and your instrumented application servers. If necessary, restart the Workstation. When using nexusctl, specify the new port number by including the -r URI
URI ” on page 238 for more information.
What they are used for:
ListenHost has a default value of “*” . This setting causes the Nexus to listen for connections on all available IP addresses . If you substitute a hostname or IP
432 PerformaSure: User’s Guide
address (such as, for example, “123.45.67.8” ) for the default value, the Nexus will listen for connections 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 to the Nexus through one.
You would want to change the default value of ListenPort in the unlikely event that you are already using the port number for another purpose.
Example usage:
The default settings are:
ListenHost = “*”;
ListenPort = 41705;
If you need to change the port number, choose one that is greater than 1024.
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 in the recording settings configuration that you are using. 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.
Appendix A—Configuring PerformaSure 433
Example usage:
The default setting is:
AgentOrderInterval = 2000;
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; increasing this value can help prevent 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 can’t 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;
434 PerformaSure: User’s Guide
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;
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;
Appendix A—Configuring PerformaSure 435
Preventing a Firewall from Closing Nexus Connections
MessageTrafficTimeout
Ensures that a firewall does not close Nexus connections due to inactivity. This setting is optional; the value for this setting is specified in milliseconds.
Note: This setting applies to all Nexus connections, whether from the Agents,
Workstations, or nexusctl.
What it is used for:
Some firewalls and NAT devices automatically close connections after a certain period of inactivity. Uncommenting and setting MessageTrafficTimeout configures both endpoints of a Nexus connection to ensure that the idle timeout is not exceeded. A connection will be closed if it is idle for longer than this timeout.
The value that you specify in milliseconds for MessageTrafficTimeout should be equivalent to the firewall’s timeout for idle connections. You can leave this setting commented out if there is no firewall between the Nexus and Agents or between the Nexus and the Workstations or nexusctl or if the firewall does not close idle connections.
Example usage:
The default setting is:
MessageTrafficTimeout = 30000;
Configuration Lookup Sequence
PerformaSure has a four-stage configuration lookup sequence that provides the ability to locally override Agent configurations and allows the Agent to look for configuration information in several locations, including a default location. The lookup sequence is as follows:
1.
Override: The Agent looks locally in <performasure_home>/config/client- override/<name>.
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/agent-
type/<name>.
436 PerformaSure: User’s Guide
3.
Cached: The Agent looks locally in
<performasure_home>/state/<userID>/config-cache/agent-type/<name>.
4.
Default: The Agent looks locally in <performasure_home>/config/client/agent-
type/<name>.
Note: In the steps described above, <name> signifies the configuration file (for example, weblogic-81.config).
If the Agent does not find anything after performing all four steps in the lookup sequence, PerformaSure will log an ERROR message (which is written to the log
target that you specified) and the Agent may be shut down. See “ Logging ” below
for more information about configuring log targets and setting the log level.
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 <performasure_home>/config/client-override or on the
Nexus machine) needs to be based on the default configuration file, the contents of the default file must be copied to the overriding 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.
Appendix A—Configuring PerformaSure 437
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:
■
■
PerformaSure writes log messages to the following locations:
The Nexus and Agent consoles.
Log files stored in <performasure_home>/logs (the default location), or in the directory that you specify using the directory property in
<performasure_home>/config/log.config. See the description of the directory log
target property in “ Additional properties for log targets ” on page 441 for
information about changing the directory in which log files are created.
■
To other targets that you set. See “ Target ” on page 438 for more information.
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 , SERIALIZED_FILE , NEXUS , NATIVE ,
SESSION , and WEBSPHERE .
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.
438 PerformaSure: User’s Guide
■
■
■
■
■
■
■
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 logs subdirectory of the
PerformaSure home directory or in the directory that you specify using the directory property in log.config.
SERIALIZED_FILE : Outputs log messages to a serialized object file in the logs subdirectory of the PerformaSure home directory or in the directory that you specify using the directory property in log.config.
Note: See the description of the directory log target property in
“ Additional properties for log targets ” on page 441 for information
about changing the directory in which log files are created.
NEXUS : Forwards Agent messages to the Nexus for echoing on the Nexus.
NATIVE : Forwards Agent messages to a native (non-Java) logging system like
Apache.
SESSION : Outputs Nexus messages to the session that is being recorded.
WEBSPHERE : Forwards Agent messages to the WebSphere log system.
Default target configuration
The table below shows the standard target configuration for the Agents, Nexus, and Workstation.
Target
CONSOLE
FILE
SERIALIZED_
FILE
NEXUS
NATIVE
SESSION
WEBSPHERE
All
Agents
Active
Active
Active
Active
WebSphere
Agent
Apache Agent
Active
Active
Active
Active
Active
Active
Nexus
Active
Active
Active
Active Active
Active
Active
Workstation
Active
Active
Active
Active
Each target has properties that can be configured to modify its behavior. See
” and “ Additional properties for log targets ” below for
more information.
Appendix A—Configuring PerformaSure 439
Default target log levels
All targets have one common property, 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.
As shown in the table in “ Default target configuration ” above, the
SERIALIZED_FILE target is automatically active for all PerformaSure applications. However, its threshold is set to OFF in release mode and set to ALL in
debug mode (see the tables below). See “ Log Levels ” below for more information
about these two log levels. You can override the default release mode setting for
SERIALIZED_FILE by setting the threshold to something other than OFF , preferably ALL .
Default log levels for release mode
CONSOLE FILE Log Level
DEBUG
VERBOSE
INFO
WARN
ERROR
FATAL
ALL
OFF
Default
Default
SERIALIZED_FILE NEXUS NATIVE SESSION WEBSPHERE
Default
Default
Default
Default
Default
Default log levels for debug mode
Log Level
DEBUG
VERBOSE
INFO
WARN
ERROR
CONSOLE
Default
FILE
Default
SERIALIZED_FILE NEXUS NATIVE SESSION WEBSPHERE
Default
Default
Default
Default
440 PerformaSure: User’s Guide
Default log levels for debug mode
CONSOLE FILE Log Level
FATAL
ALL
OFF
SERIALIZED_FILE NEXUS
Default
NATIVE SESSION WEBSPHERE
Additional properties for log targets
The FILE and SERIALIZED_FILE log targets have the following additional properties:
■ 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. This property defaults to false .
■ directory : String. This property sets the directory in which log files are created. If you specify a relative path, it is resolved from the PerformaSure home directory. The directory that you specify and all its parent directories are created if they do not exist. This property defaults to the logs subdirectory of the PerformaSure home directory.
Note: When specifying a value for this property, backslashes used as path separators must be escaped. For example,
"C:\\SystemLogs\\PerformaSure"
■
■ 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.
-1 sets maxBackupCount to infinite. This property defaults to 50 .
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. 0 sets maxFileSize to infinite. This property defaults to 20000000 (20MB).
The FILE log target also has the following property:
■ charset : String. The character set in which to write to the file. This property defaults to “UTF-8” .
CONSOLE and FILE 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 uses DefaultLogMessageFormatter .
Appendix A—Configuring PerformaSure 441
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 include implementation details (thread name, category class and exception stacktrace).
: Boolean. When set to true , the formatter does not
■ 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 per line.
: Integer. This property controls the maximum number of characters
■ indentWrappedLines : Boolean. This property controls whether wrapped lines are indented by four 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 target’s 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. You’ll see messages at this level when Quest Software support engineers request extra information to assist you with a problem that you have encountered.
442 PerformaSure: User’s Guide
■
■
■
■
■
■
■
VERBOSE — Logs configuration information and other detailed information.
For example, when the target NEXUS is set to this level, the Nexus console displays Agent system information such as the OS of the machine from which the Agent connects. When you start recording, session details are also logged at this level.
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 the operation of PerformaSure.
FATAL — The system writes this message to the log file when some unrecoverable error has occurred, which usually results in PerformaSure shutting down.
ALL — The target accepts all log messages ( DEBUG , VERBOSE , INFO , WARN ,
ERROR , and FATAL ).
OFF — The target does not accept any log messages. In addition, when the target SERIALIZED_FILE is set to this log level, no .pslog file is created.
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: 3
INFO: 3
WARN: 2
ERROR: 1
FATAL: 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 system’s 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 system’s behavior without incurring the overhead of full detail.
Appendix A—Configuring PerformaSure 443
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 Java EE 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.
Important: 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 in the Workstation or
using nexusctl. See “ Sampling Tab
” on page 211 and “ Sampling Parameters ” on page 233 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 457 and
“ Customizing Component-Level Data Collection ” on page 456
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 call—even 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 Java EE 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.
444 PerformaSure: User’s Guide
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 452 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 458 for
more information.
Component Instrumentation
There are many reasons why taking a ‘bird’s 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 system’s 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 456 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 application’s classes that do not implement or extend the interfaces listed in this section are not tracked using Tag and Follow. When you need specific information about all the classes in your application, record in full detail. When you want to gather data on key Java EE
Appendix A—Configuring PerformaSure 445
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 destroy()
void init(ServletConfig)
void service(ServletRequest, ServletResponse)
For classes that implement the javax.servlet.http.HttpServlet
interface,
PerformaSure records:
void doDelete(HttpServletRequest, HttpServletResponse)
void doGet(HttpServletRequest, HttpServletResponse)
void doHead(HttpServletRequest, HttpServletResponse)
void doOptions(HttpServletRequest, HttpServletResponse)
void doPost(HttpServletRequest, HttpServletResponse)
void doPut(HttpServletRequest, HttpServletResponse)
void doTrace(HttpServletRequest, HttpServletResponse)
long getLastModified(HttpServletRequest)
void service(ServletRequest, ServletResponse)
void service(HttpServletRequest, HttpServletResponse)
For classes that implement the javax.servlet.Filter
interface, PerformaSure records:
void doFilter(ServletRequest, ServletResponse, FilterChain)
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
446 PerformaSure: User’s Guide
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()
void ejbRemove()
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 setSessionContext(SessionContext)
Component-level Classes for Entity EJBs
For classes that implement the javax.ejb.EntityBean
interface, PerformaSure records all public methods, including:
void ejbCreate<METHOD>(args)
void ejbPostCreate<METHOD>(args)
void ejbRemove()
void ejbLoad()
void ejbStore()
void ejbFind<METHOD>(args)
void ejbSelect<METHOD>(args)
void ejbPassivate()
PerformaSure does not record:
void setEntityContext(EntityContext)
void unsetEntityContext()
Appendix A—Configuring PerformaSure 447
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)
void ejbRemove()
PerformaSure does not record:
void setMessageDrivenContext(MessageDrivenContext)
Component-level Classes for EJB3 Annotations
For classes that are annotated with javax.ejb.Stateless
, PerformaSure records all public methods, including methods that are annotated with the following: javax.annotation.PostConstruct
javax.annotation.PreDestroy
For classes that are annotated with javax.ejb.Stateful
, PerformaSure records all public methods, including methods that are annotated with the following: javax.annotation.PostConstruct
javax.annotation.PreDestroy
javax.ejb.PostActivate
javax.ejb.PrePassivate
javax.ejb.Init
javax.ejb.Remove
For classes that are annotated with javax.ejb.MessageDriven
, PerformaSure records all public methods, including methods that are annotated with the following: javax.annotation.PostConstruct
javax.annotation.PreDestroy
For classes that are annotated with javax.interceptor.Interceptors
,
PerformaSure records all public methods, including methods that are annotated with the following: javax.annotation.PostConstruct
javax.annotation.PreDestroy
javax.ejb.PostActivate
javax.ejb.PrePassivate
For classes that are annotated with javax.persistence.Entity
, PerformaSure records all public methods, including methods that are annotated with the following: javax.persistence.PrePersist
javax.persistence.PostPersist
javax.persistence.PreRemove
javax.persistence.PostRemove
javax.persistence.PreUpdate
448 PerformaSure: User’s Guide
javax.persistence.PostUpdate
javax.persistence.PostLoad
For classes that are annotated with javax.persistence.EntityListeners
,
PerformaSure records all public methods, including methods that are annotated with the following: javax.persistence.PrePersist
javax.persistence.PostPersist
javax.persistence.PreRemove
javax.persistence.PostRemove
javax.persistence.PreUpdate
javax.persistence.PostUpdate
javax.persistence.PostLoad
For classes that are annotated with javax.persistence.MappedSuperclass, PerformaSure records all public methods, including methods that are annotated with the following: javax.persistence.PrePersist
javax.persistence.PostPersist
javax.persistence.PreRemove
javax.persistence.PostRemove
javax.persistence.PreUpdate
javax.persistence.PostUpdate
javax.persistence.PostLoad
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:
void addBatch()
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
Appendix A—Configuring PerformaSure 449
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 deleteRow()
void insertRow()
void RefreshRow()
void UpdateRow()
For classes that implement the java.sql.Statement
interface, PerformaSure records:
void addBatch(String)
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.
450 PerformaSure: User’s Guide
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 tracks all the services requests that enter your instrumented
application server unless you explicitly choose to exclude some. See “ Service
” on page 84 and “ Filters Tab ” on page 216 for more
information. You also have the option of splitting one service request and tracking
each part separately. See “ Service Request Separation ” on page 77 and
“ Separators Tab ” on page 213 for more information.
RMI Component-level Detail
PerformaSure instruments all the RMI calls that enter your instrumented system.
Appendix A—Configuring PerformaSure 451
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.
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.
452 PerformaSure: User’s Guide
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. For more information about using
regular expressions, see “ Appendix D—Regular Expressions ” on page 489.
Using multiple include and exclude elements
When you use multiple include and exclude elements, it is the first element that matches that will control the outcome. For example:
UserClasses = ClassList( exclude “foo.bar.Baz” include “foo.bar.” exclude “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.
InstrumentedClasses
Can be used to completely exclude certain classes from instrumentation.
What it is used for:
One possible use for the InstrumentedClasses setting is to exclude a class because instrumenting it is causing errors. You can use regular expressions to
exclude elements can be used in the block (as shown in the example below), but it is the first element that matches that will control the outcome.
Appendix A—Configuring PerformaSure 453
Example:
InstrumentedClasses = ClassList ( exclude "com.globex.plan.DominateWorld", exclude "com.globex.scheme."
);
In the example above, the class com.globex.plan.DominateWorld
would be excluded, as well as all classes in the package com.globex.scheme
.
Important: Do not use the InstrumentedClasses setting to exclude classes from instrumentation except at the recommendation of a Quest Software customer support representative.
AllowedClassesByPlugin
Can be used to exclude classes from instrumentation by a specific plugin.
What it is used for:
One possible use for the AllowedClassesByPlugin setting is to exclude a class because instrumenting it is causing errors. You can use regular expressions to
include and exclude elements can be used in the block, but it is the first element that matches that will control the outcome.
Note: The full names of the plugins taking part in the instrumentation of a particular application server can be found in the configuration file that corresponds to that server. These configuration files are located in the
agent-type subdirectory of the PerformaSure home directory.
Example:
AllowedClassesByPlugin.com.sitraka.pas.agent.plugin.instrumentor
.method.JndiInstrumentor = ClassList ( include "com.evermind.naming.file.FileContext", exclude /./
);
454 PerformaSure: User’s Guide
In the example above, only com.evermind.naming.file.FileContext
will be examined (and possibly instrumented) by JndiInstrumentor .
Important: Do not use the AllowedClassesByPlugin setting to exclude classes from instrumentation except at the recommendation of a Quest Software customer support representative.
Customizing the Collection of Data on Long Running Methods
LongRunningUserMethods and LongRunningUserMethodWaypoints
Customize the collection performance information on methods that execute over a long period of time.
What they are used for:
By default, PerformaSure waits for a method to finish executing before treating the collected data as complete. However, it can sometimes be preferable to consider the data complete at specific points in the code, such as when instrumenting the run() method of a background thread and other methods that execute over a long period of time. When you set the LongRunningUserMethods and LongRunningUserMethodWaypoints configuration options, PerformaSure will pause at the waypoint methods to treat the data as complete before continuing. This makes the data available in smaller increments as the long running method executes instead of all at once when it completes. A minimal set of waypoint methods allows for the best possible performance.
Example:
LongRunningUserMethods = MethodList( include "com.globex.plan.DominateWorldThread.run"
);
LongRunningUserMethodWaypoints = MethodList( include "com.globex.plan.DominateWorldThread.executeProject"
);
In the example above, the method com.globex.plan.DominateWorldThread.run
will treat the data as complete each time the method executeProject() is called from run() .
Appendix A—Configuring PerformaSure 455
Customizing Component-Level Data Collection
CustomComponents
Extends the default set of Java EE components that are included when you record a session at the component detail level.
What it is used for:
Java EE 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 level—has the benefit of reducing the volume of data (and hence reducing the overhead associated with running PerformaSure) 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 Beehive
Apache Struts
Apache TagLibs
Oracle WebLogic Integration
Hibernate
IBM Commerce Server
IBM Portal
OpenSymphony
Oracle TopLink
Spring
Note: Apache TagLibs is included in the CustomComponents configuration section but is commented out by default.
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\..*/),
456 PerformaSure: User’s Guide
};
"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 component’s name or by forming a regular expression that matches the name or pattern. Enter the include
element before each item in the list. See “ Appendix D—Regular
Expressions ” on page 489 for more information about using regular expressions.
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 set the recording detail level to either Component Detail or Full Detail in the Sampling tab of the Workstation’s Recording Settings dialog or using nexusctl.
” on page 211 and “ Sampling Parameters ” on page 233 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.
Appendix A—Configuring PerformaSure 457
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 labels the terminal node in a recursive sequence with the recursive call icon ( ) to indicate that there are more calls that are not being drawn.
Figure 166
Figure 166 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:
The default setting is:
RecursionLimit = 5;
To see none of the recursive calls:
RecursionLimit = 0;
When RecursionLimit is set to 0 , 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.
Setting the Remote Invocation Limit
RemoteInvocationLimit
Sets the maximum number of calls that PerformaSure will track from a single method to a remote system. The default value is 10 .
458 PerformaSure: User’s Guide
What it is used for:
Once the number set by RemoteInvocationLimit has been exceeded,
PerformaSure will collect performance information for the remote system invocations and aggregate it. This is done for two reasons:
1.
A large number calls to remote systems from a single method is highly likely to produce a performance problem.
2.
It is expensive for the PerformaSure Nexus to process Tag and Follow
™ information for a large number of remote invocations on a single request.
If this limit is exceeded, PerformaSure will produce a WARN log message that identifies the method where the remote invocations are taking place.
Example usage:
The default setting is:
RemoteInvocationLimit = 10;
Increase the value of RemoteInvocationLimit if you are receiving WARN log messages and you require more detail on the remote invocations. Decrease this value if you are receiving the WARN log messages but the Nexus is exhibiting symptoms of excessive use of memory.
Note: Increasing the value of RemoteInvocationLimit will cause the Nexus to increase its use of CPU and memory.
Tracking Objects
Important: As with all other changes to instrumentation.config, you must restart the Agents and your instrumented application servers after editing any of the configuration options in the Object
Tracking section of instrumentation.config.
In addition, if you have integrated PerformaSure with Oracle
Application Server or with Tomcat 5 running as a Windows service, you must manually run the preinstrumentor shell script or cmd file (located in the scripts directory of your PerformaSure installation) on all Agent machines after editing any of the configuration options in the Object Tracking section.
Appendix A—Configuring PerformaSure 459
ObjectTrackerClasses
Allows you to specify groups of classes for which allocated object instances will be tracked during a sampled request.
What it is for:
The ObjectTrackerClasses configuration option is used to watch for objects that are never reclaimed by the garbage collector.
For details, see the comments in the Object Tracking section in
<performasure_home>/config/client/instrumentation.config.
ObjectTrackerWeightMethods
Allows you to collect an optional weight metric for sampled instances of the classes specified by ObjectTrackerClasses .
What it is for:
The ObjectTrackerWeightMethods configuration option allows you to specify a method that is invoked on live instances of the classes included in one of the groups listed in ObjectTrackerClasses . The value returned from calling the specified method is included in the information collected about the classes in that group that are allocated during a sampled request.
For details, see the comments in the Object Tracking section in
<performasure_home>/config/client/instrumentation.config.
ObjectTrackerSampleRatio
Sets the ratio of sampled requests to requests that are sampled for object tracking.
What it is for:
The ObjectTrackerSampleRatio parameter is used to limit the number of sampled objects that will be tracked. For example, using this parameter’s default value of 10 will cause PerformaSure to track 1 in 10 of the sampled requests that are processed per thread.
ObjectTrackerSampleRatio is commented out by default. If you want to use this parameter with its default value of 10, you do not need to uncomment it.
However, if you want to use a value other than 10, you must uncomment this parameter in instrumentation.config on the Nexus machine and change its value
The random request distribution provided by ObjectTrackerSampleRatio will limit the memory overhead that is incurred while collecting data and can be
460 PerformaSure: User’s Guide
adjusted based on your performance diagnosis requirements. Setting
ObjectTrackerSampleRatio to a higher value will result in fewer tracked objects for sampled requests and decreased system overhead; using a lower value will cause more objects to be tracked, but at the expense of a higher overhead on the application server.
For details, see the comments in
<performasure_home>/config/client/instrumentation.config.
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 doesn’t 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 Agent-
Nexus Connection ” on page 428 for details.
Fatal error occurs inside one of the Agent Threads
Appendix A—Configuring PerformaSure 461
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.
Should I run a System Agent on my load-testing machine?
It’s 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.
462 PerformaSure: User’s Guide
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, 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, and application server metrics are collected at set intervals.
Other approaches are used for collecting network metrics and service request metrics.
By default, raw metrics are not listed in the navigation pane of Metrics browser or the Threshold Editor. Follow the instructions below to cause raw metrics to be displayed.
To display raw metrics:
1.
Select Tools > Options... from the menu bar of the Project window or any browser. The Edit Options dialog will open.
2.
In the tree view, click on Browsers > Metrics.
3.
Select Show Raw Metrics.
4.
Click OK to apply this change and close the dialog. Raw metrics will be listed at the bottom of the navigation pane of the Metrics browser and the Threshold
Editor.
463
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.
The Metric Hierarchy
In order to help you analyze performance problems, PerformaSure organizes derived metrics into a metric hierarchy and also provides 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 your operating system and on the application server(s) that you are instrumenting. The following sections in this chapter illustrate the general form of the derived metric hierarchy and the nodes and sub-trees 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
Call Count
Calls per Second
464 PerformaSure: User’s Guide
•
•
•
•
•
Exceptional Exits
% Incomplete
% Sampled
All Requests
•
See“ Request and All Requests Sub-Trees ” below.
for each [Request]
• Response Time
•
•
•
•
Call Count
Calls per Second
Exceptional Exits
% Incomplete
• % Sampled
•
See “ Request and All Requests Sub-Trees ” below.
Request and All Requests Sub-Trees
Click on an All Requests node or a node described above as for each [Request] to expose the following sub-tree:
• All Tiers
• All Servers
• for each [Component Technology]
•
•
•
•
•
•
Response Time
Call Count
Calls per Second
Exceptional Exits
% Incomplete
for each [Component]
•
•
•
Response Time
Call Count
Calls per Second
•
•
•
Exceptional Exits
% Incomplete
for each [method]
• Response Time
•
•
Call Count
Calls per Second
Appendix B—Metrics in PerformaSure 465
•
•
•
• Exceptional Exits
•
for each [Server]
% Incomplete
Response Time
•
•
•
•
•
Call Count
Calls per Second
Exceptional Exits
% Incomplete
for each [Component Technology]
•
•
•
•
Response Time
Call Count
Calls per Second
Exceptional Exits
•
•
% Incomplete
for each [Component]
•
•
Response Time
Call Count
•
•
•
•
Calls per Second
Exceptional Exits
% Incomplete
for each [method]
•
•
•
•
•
for each [Tier]
• Response Time
Response Time
Call Count
Calls per Second
Exceptional Exits
% Incomplete
•
•
Call Count
Calls per Second
•
•
•
Exceptional Exits
% Incomplete
All Servers
• for each [Component Technology]
• Response Time
466 PerformaSure: User’s Guide
•
•
•
•
•
•
•
•
•
•
•
•
Call Count
Calls per Second
Exceptional Exits
% Incomplete
for each [Component]
•
•
•
•
Response Time
Call Count
Calls per Second
Exceptional Exits
•
•
% Incomplete
for each [method]
•
•
Response Time
Call Count
•
•
Calls per Second
Exceptional Exits
•
for each [Server]
% Incomplete
Response Time
Call Count
Calls per Second
Exceptional Exits
% Incomplete
for each [Component Technology]
•
•
•
Response Time
Call Count
Calls per Second
•
•
•
Exceptional Exits
% Incomplete
for each [Component]
• Response Time
•
•
•
•
•
Call Count
Calls per Second
Exceptional Exits
% Incomplete
for each [method]
Appendix B—Metrics in PerformaSure 467
•
•
•
•
•
Response Time
Call Count
Calls per Second
Exceptional Exits
% Incomplete
Note: The aggregate Call Count metric for a component technology is not a sum of the Call Count metrics for the components listed under it. For example, Requests / [Request] / [Tier] / [Server] / EJB / Call Count is a count of entry points into EJB technology, not a sum of all individual EJB Call
Count metrics. Thus, when one EJB 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
Total Response Time
Average Response Time
•
•
All SQL Statements
•
See“ SQL Statement and All SQL Statements Sub-Trees ” below.
for each [SQL Statement]
•
•
Execute Count
Total Response Time
• Average Response Time
•
See“ SQL Statement and All SQL Statements Sub-Trees ” below.
SQL Statement and All SQL Statements Sub-Trees
Click on an All SQL Statements node or a node described above as for each [SQL
Statement] to expose the following sub-tree:
• Execute
• Maximum Response Time
468 PerformaSure: User’s Guide
•
•
•
•
Total Response Time
• Average Response Time
Prepare
Total Response Time
• Average Response Time
Retrieve
•
•
Total Response Time
Average Response Time
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]
• Sessions
• for each [Metric Group]
• for each [Cluster]
•
• All Servers
• for each [Server]
EJBs
• All EJBs
• for each [Metric Group]
• for each [Cluster]
• All Servers
•
• for each [Server]
for each [EJB]
• for each [Metric Group]
• for each [Cluster]
• All Servers
Appendix B—Metrics in PerformaSure 469
•
•
•
Servlets
• All Servlets
for each [Server]
• for each [Metric Group]
• for each [Cluster]
• All Servers
•
• for each [Server]
for each [Servlet]
• for each [Metric Group]
• for each [Cluster]
• All Servers
•
Work Managers
for each [Server]
• for each [Metric Group]
• for each [Manager]
• for each [Cluster]
•
•
All Servers
for each [Server]
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
• JVM
•
•
•
Garbage Collection
• [Sub-Groups]
Heap
• [Sub-Groups]
Objects
470 PerformaSure: User’s Guide
•
•
•
•
•
•
•
•
• [Sub-Groups]
for each other [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]
JCA
• for each [Metric Group]
• for each [Pool]
• for each [Cluster]
•
• All Servers
• for each [Server]
for each [Pool Instance]
• for each [Cluster]
• All Servers
• for each [Server]
JMS
• for each [Metric Group]
•
See “ JMS > Metric Group Sub-Trees ” below.
JTA
•
MDB
• for each [Metric Group]
• for each [MDB]
• for each [Cluster]
• All Servers
•
• for each [Server]
Work Managers
• for each [Metric Group]
• for each [Manager]
for each [Cluster]
• All Servers
• for each [Server]
Thread Pool
• for each [Metric Group]
Appendix B—Metrics in PerformaSure 471
• for each [Cluster]
• All Servers
• for each [Server]
Note: The metric /Application Servers/Performance/CPU Utilization is not available for sessions recorded with WebSphere ND.
Performance > Metric Group Sub-Trees
The category for each other [Metric Group] represents metric groups other than
JVM in the sub-tree Application Servers > Performance. When you click on a node described above as for each other [Metric Group], you will expose one or more of the following sub-trees:
• for each [Sub-Group]
• for each [Cluster]
•
•
All Servers
for each [Server] or
• for each [Queue]
• for each [Cluster]
•
•
All Servers
for each [Server] or
• for each [Thread Pool]
• for each [Cluster]
•
•
All Servers
for each [Server] or
• for each [Cluster]
• All Servers
• for each [Server]
472 PerformaSure: User’s Guide
JCA > Metric Group > Pool Sub-Trees
When you click on a node described in “ Application Servers Root Node ” as for
each [Pool] (in the sub-tree Application Servers > JCA > for each [Metric
Group]), you will expose one of the two following sub-trees:
• for each [Cluster]
• All Servers
• for each [Server] or
•
•
for each [Cluster]
• All Servers
• for each [Server]
for each [Pool Instance]
• 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 [JMS Server]
• for each [Cluster]
•
See “ JMS > Metric Group > JMS Server > Cluster Sub-Trees ” below.
or
• for each [Cluster]
•
See “ JMS> Metric Group > Cluster Sub-Trees ” below.
JMS > Metric Group > JMS Server > 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 [JMS Server]), you will expose one of the two following lists of metrics:
•
•
All Servers
for each [Server]
Appendix B—Metrics in PerformaSure 473
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:
•
•
All Servers
for each [Server] 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]
• for each [Cluster]
•
•
All Servers
for each [Server]
• Client Transactions
• for each [Metric Group]
• for each [Cluster]
• All Servers
• for each [Server]
• Global Transactions
• for each [Metric Group]
• for each [Cluster]
•
•
All Servers
for each [Server]
• Local Transactions
474 PerformaSure: User’s Guide
• for each [Metric Group]
• for each [Cluster]
•
•
All Servers
for each [Server]
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]
Disks
• for each [Metric Group]
All Disks
•
•
• for each [Disk]
Partitions
• for each [Metric Group]
• All Partitions
• for each [Partition]
Memory
•
•
• [OS-specific Metrics]
System
• [OS-specific Metrics]
Network
• Bytes Sent
• From [each local IP address]
• All IP Addresses
Appendix B—Metrics in PerformaSure 475
•
• To [each remote IP address]
Bytes Received
• At [each local IP address]
• All IP Addresses
• From [each remote IP address]
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 metric’s 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.
476 PerformaSure: User’s Guide
Appendix C—Lexicon
Term
Active Metric
Agent
Application
Server
AutoCapture
Benchmark
Benchmark
Factory
BLOB
Context
Request Tree browser
PerformaSure
General
Foglight/
PerformaSure
General
Concept
Nodes in the Request Tree 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.
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 those supported by PerformaSure.
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.
Quest Software Benchmark Factory is Quest’s load-testing solution that scales throughput to virtually unlimited users, helping you discover the limits of your critical environments before you go live.
SQL A BLOB is a SQL built-in type that stores a Binary
Large Object as a column value in fields of a database table.
477
478 PerformaSure: User’s Guide
Term
Bottleneck
Browser
Bundling
Context
General
PerformaSure
Request Tree browser
Concept
A bottleneck is a stage in a process that causes the entire process to slow down or stop.
The data collected in a PerformaSure session can be examined using various browsers. The five types of browser are: Metrics, 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.
Business Logic
Byte Code call tree
Chart
Designing
Enterprise
Applications
Java Virtual
Machine
PerformaSure and JProbe
General
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 the 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.
Class
CLOB
Java
SQL
A class is a template for objects. It may be regarded as the object’s 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.
Communication
Services
Communications
Layer
Communication services is the interface to the communications layer that the host application sees.
Term
Complete
Request
Component
Component
Componentlevel instrumentation
Container
Context
Context
Critical Path
Request Tree browser
Request Tree browser
Critical Request Request Tree browser
Enterprise
Application
Integration
(EAI)
Context
PerformaSure
Nexus
Designing
Enterprise
Applications
General
PerformaSure
Designing
Enterprise
Application
PerformaSure
General
Concept
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 Java EE 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 Enterprise
Java Beans.
An option in PerformaSure that reduces complexity is to show the key components in a Java EE 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 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.
The enterprise application integration allows new Web applications to access data and functions residing on existing systems, such as mainframes.
Appendix C—Lexicon 479
480 PerformaSure: User’s Guide
Term
Enterprise
JavaBeans
(EJB)
Entry-Point
Node
External
System
Extrapolated metric
Context
Java
PerformaSure
Failed request PerformaSure
FastFind
Filtering
Filtering
Request Tree browser
PerformaSure
Request Tree browser
PerformaSure browsers
PerformaSure
Concept
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.
In the context of this document, an external system is one that is not instrumented by PerformaSure, like a bank’s 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 tracked using Tag and Follow. In these situations,
PerformaSure uses extrapolation to calculate totals for metrics like cumulative times.
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 to expose the most expensive node with regard to the new metric.
Filtering is done by typing a literal string or regular expression into the Request Time, or Request Tree; into the SQL browser’s Filter Statements bar; or into the Thresholds browser’s Filter Metrics bar. Only those requests, statements, or metrics 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).
Term
Fragmented
Request
Garbage
Collection
Gateway or
Common
Gateway
Interface (CGI)
Glob
Context
PerformaSure
Nexus
General
General
Unix/Windows
Concept
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.
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 user’s request to an application program and to receive data back, which it then forwards to the user.
Graph General
Group Header Request Tree browser
GUI General
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.
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.
Appendix C—Lexicon 481
482 PerformaSure: User’s Guide
Term
Incomplete
Requests
(Percentage)
Incomplete
Request
Incomplete
Request
Timeout
Instrumented servers
Java EE
JDBC
JRE
JSP
JVM
Load Balancing
Mercury
Interactive
LoadRunner
Method
Context
PerformaSure
PerformaSure
PerformaSure
PerformaSure
Java
Java
Java
Java
Java
Application
Servers
LoadRunner
Java
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 tracked using Tag and
Follow.
The Java Platform, 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 ebusiness task.
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.
Term
Method Call
Tree
Metric Query
Context
PerformaSure
PerformaSure
Concept
Metrics PerformaSure
Metrics Browser PerformaSure
Network Time
Protocol (NTP)
Nexus
Performance
General
PerformaSure
General
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: periodic metrics and request metrics.
Periodic metrics are measurements 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.
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.
Used to synchronize the time of a computer client or server to another server or reference time source. See
NTP
The Nexus is the central repository for PerformaSure; essentially, it is the central manager, the data-store component, and the analysis engine of PerformaSure.
The Nexus collects data from Agents to provide information to Workstations.
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 Java EE application to service requests promptly. This is the meaning of the word when it is used in this manual.
Appendix C—Lexicon 483
484 PerformaSure: User’s Guide
Term
Project
Query
Request
Request
Instance
Context
PerformaSure
General,
PerformaSure
PerformaSure
PerformaSure
Request Time
Browser
PerformaSure
Request Tree
Browser
PerformaSure
Concept
Projects are one of the central points of control in
PerformaSure. 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.
Quest Software’s 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 request’s 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.
Term
Request Type
Sampling
Server
Service
Request
Metrics
Servlet
Context
PerformaSure
Service
Request Agent
PerformaSure
Session
Session
PerformaSure
General
PerformaSure
General
PerformaSure
General
Concept
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 GET and POST parameters, cookies, or
HTTP headers.
2) A specific kind of service request (HTTP, RMI, or
JMS).
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 server is a computer program that provides services to other computer programs in the same or other computers. PerformaSure instruments application servers so that service requests can be tracked and analyzed.
Service Request Agents collect metrics on Java EE service requests by instrumenting application servers and by tracking requests from the point that they enter the instrumented system using
technology.
Service Request metrics are the metrics that
PerformaSure measures in instrumented 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 request-response paradigm.
The process of collecting data using the capability that PerformaSure has 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.
Appendix C—Lexicon 485
486 PerformaSure: User’s Guide
Term
Sightline
SQL Browser
Tag and
Follow
™
Context
Time Control panel
Synchronized
Time Stamping
PerformaSure
System Agent
System Metrics PerformaSure
System
Performance
TCP/IP
Test Case
PerformaSure
PerformaSure
PerformaSure
PerformaSure
General
PerformaSure
Concept
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. The Sightline is linked to the Zonar. Using the Sightline’s slider, you can move the Sightline through a range of time that is equivalent to that spanned by the Zonar.
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 browser’s 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.
Synchronized Time Stamping is a procedure for getting two or more timestamping threads to give the same results, even on different machines.
System Agents measure operating system and network metrics.
System Metrics are metrics collected by System
Agents. This category of metrics includes operating system parameters. Compare to
System performance is a a benchmark against which
applications can be measured by using System
PerformaSure is a performance analysis tool.
Tag and Follow is Quest Software’s 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.
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.
Term
Throughput
Thresholds
Browser
Time Control panel
Time Slice
Timeline
Transaction
Unmatched
Request
Context
General
PerformaSure
PerformaSure browsers
PerformaSure
Time Control panel
General
PerformaSure
Nexus
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 browser’s 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,
, 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 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.
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.
Appendix C—Lexicon 487
488 PerformaSure: User’s Guide
Term
Update
Use Case
View
Web Server
Zonar
Context
General
General
PerformaSure
General
Time Control panel
Concept
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.
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 browser’s graph pane is sometimes referred to as the
“tree view”.
A Web server is a program that, using the client/server model and the World Wide Web’s
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 drag, stretch, and shrink the Zonar within the Timeline and the data displayed in the browser will be adjusted accordingly.
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 333 for more information about using the Filter
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.
489
The following table lists the metacharacters in PerformaSure and describes their function.
Metacharacter asterisk (*) alias: star period (.) alias: dot question mark (?) plus (+)
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.example.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’.
490 PerformaSure: User’s Guide
Metacharacter square brackets ([]) 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.
minus (-) alias: dash
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’.
caret (^)
Description and Example of Use in a Regular Expression dollar sign ($)
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 ‘^abc’ 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]($|\?)/’ 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’.
Appendix D—Regular Expressions 491
Metacharacter backslash (\)
(reverse solidus) parentheses (())
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’
Caution: Do not use parenthesized expressions followed by a plus sign (+) or an asterisk (*) in any of the configuration files for PerformaSure, 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’.
2.
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.
3.
The longest match wins. In “*”, “+”, and “?” constructs, longer matches are chosen in preference to shorter ones.
Example: if the regular expression is ‘^He’s ba*’ and the target string is ‘He’s baaaaack!’, the match succeeds with ‘He’s baaaaa’ after the full list of contiguous a’s have been scanned.
492 PerformaSure: User’s Guide
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$
^com[.]quest[.].* rmi$
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
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, [^abc] 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 can’t 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 class—it 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
Appendix D—Regular Expressions 493
Regular Expression www[0-9][0-9]?[.]example www0.example, www01.example, but not www001.example
The regular expression matches ‘www’ followed by a numeral, followed by no more than one more numeral, followed by ‘.example’. Thus, 001 fails the match.
www[^a-zA-Z]?\.example
www.example, www1.example, but not wwwx.example
www[.]quest[.]com
Matches
www.quest.com This is the recommended way of matching the dot separator in Java package names and fully qualified names.
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.’
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.
Matching Any Character: the Dot
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, it’s 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.
494 PerformaSure: User’s Guide
Regular Expression
[ ]co(.|..|...|....)[ ]
594[-./]1026
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.
Caution: A forward slash (/) marks regular expression boundaries in the configuration files for PerformaSure. 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 the configuration files for
PerformaSure.
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 Matches
(java|javax)
This is an explicit equivalent to javax?
java, javax.
[(s|t)] com\.(sun|quest|klg)
(, 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
Appendix D—Regular Expressions 495
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 based on GET and POST parameters, cookies, or HTTP headers in the Separators tab of the Workstation’s Recording Settings dialog or 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 window’s toolbar or by selecting Tools > Recording
Control Window from the menu bar of the Project window or any browser.
2.
Click the Configure... button in the Recording Control window. The Recording
Settings dialog will appear.
3.
Select the recording settings configuration that you would like to use from the
Settings drop-down menu, or create a new configuration. See “ Configuring
Recording Settings ” on page 207 for details.
4.
Select the Separators tab.
5.
Adjust the controls in this tab to configure service request separation. For example:
5.1
Press the Add new entry button. An editable entry will appear in the
Separate requests that match, in order table.
5.2
The text field in the URL Expression column will be empty. Doubleclick this text field to make it editable and enter a regular expression. For example: estore/portal-.*\.jsp
5.3
5.4
The text field in the Parameters/Cookies/Headers column will also be empty. Double-click this text field to make it editable and enter one or more parameter, cookie, or HTTP header names or name-value pairs.
Multiple items must be entered in a comma-separated list. For example: cmd,LoginName,user-agent,action=AddItem
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).
496 PerformaSure: User’s Guide
5.5
Adjust the setting in the Maximum length of value used for
separation editable spin box as desired (the default setting is 32 ).
6.
Click OK to save your selections as part of the recording settings configuration and close the dialog.
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.
2.
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”
See “ Separators Tab ” on page 213 or “
Request Separation Parameters ” on page
234 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 Workstation’s
Recording Settings dialog or 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 window’s toolbar or by selecting Tools > Recording
Control Window from the menu bar of the Project window or any browser.
2.
Click the Configure... button in the Recording Control window. The Recording
Settings dialog will appear.
3.
Select the recording settings configuration that you would like to use from the
Settings drop-down menu, or create a new configuration. See “ Configuring
Recording Settings ” on page 207 for details.
4.
Select the Filters tab.
Appendix D—Regular Expressions 497
5.
Adjust the controls found in this tab to configure service request filtering. For example, to exclude GIFs:
5.1
Press the Add new entry button. An editable entry will appear in the
Include or exclude requests that match, in order table.
5.2
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]($|\?)/
5.3
5.4
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).
6.
Click OK to save your selections as part of the recording settings configuration and close the dialog.
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 nexusctl’s 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.
2.
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.
” on page 216 or “ Filtering Parameters ” on page 237 for more
information about using the Workstation or nexusctl to set service request filtering patterns.
Using Regular Expressions in the PerformaSure Browsers
You can use regular expressions to filter items for display in several of the
browsers. See “ Using the Request Time browser’s Filter Requests bar ” on page
273, “ Using the SQL browser’s Filter Statements bar
Request Tree browser’s Filter Requests bar
Thresholds browser’s Filter Metrics bar ” on page 397 for more information.
498 PerformaSure: User’s Guide
Appendix E—License Credits and Trademarks
■
■
■
■
■
■
■
The following trademark owners for third-party products used by PerformaSure are listed in this chapter:
See “ Trademarks ” on page 505 for a list of trademark owners for materials
referenced by PerformaSure.
License Credits
ANTLR
This product includes software developed by Terence Parr and is distributed subject to the following notice:
Copyright © 2005, Terence Parr. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
499
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of the author 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 BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
Apache Commons, BCEL
This product includes software developed by the Apache Software Foundation
( http://www.apache.org/ ) and is distributed subject to the following notice:
Apache License Version 2.0, January 2004 http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity.
For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
500 PerformaSure: User’s Guide
"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition,
"submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, nocharge, royalty-free, irrevocable copyright license to reproduce, prepare
Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, nocharge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the Work or
Derivative Works thereof in any medium, with or without modifications, and in
Source or Object form, provided that You meet the following conditions:
(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices stating that
You changed the files; and c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the
Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the
Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative
Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the
License. You may add Your own attribution notices within Derivative Works that
You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise, any
Contribution intentionally submitted for inclusion in the Work by You to the
Appendix E—License Credits and Trademarks 501
Licensor shall be under the terms and conditions of this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade names, rademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its
Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory, whether in tort
(including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work
(including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing the Work or
Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
JDOM
This product includes software developed by the JDOM Project
( http://www.jdom.org/ ) and is distributed subject to the following notice:
Copyright © 2000-2002 Brett McLaughlin & Jason Hunter, all rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the disclaimer that follows these conditions in the documentation and/or other materials provided with the distribution.
3. The name "JDOM" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected].
4. Products derived from this software may not be called "JDOM", nor may "JDOM" appear in their name, without prior written permission from the JDOM Project
Management ([email protected]).
502 PerformaSure: User’s Guide
THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
libpcap
This product includes software developed by Torsten Landschoff and Sebastian
Krahmer and is distributed subject to the following notice:
Copyright © 2000 Torsten Landschoff and Sebastian Krahmer.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The names of the authors may not 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.
my_getopt
This product includes software developed by Benjamin Sittler
( http://www.geocities.com/bsittler ) and is distributed subject to the following notice:
Copyright 1997-2001, Benjamin Sittler
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Appendix E—License Credits and Trademarks 503
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:
Copyright (c) 1999 - 2005 NetGroup, Politecnico di Torino (Italy).
Copyright (c) 2005 - 2009 CACE Technologies, Davis (California).
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the Politecnico di Torino, CACE Technologies 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 BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
Xerces
This product includes software developed by the Apache Software Foundation
( http://www.apache.org/ ) and is distributed subject to the following notice:
The Apache Software License, Version 1.1
Copyright (c) 2000 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyri