Mercury LoadRunnerTM

Controller User’s Guide

Version 8.0
Mercury LoadRunner Controller User’s Guide, Version 8.0

This manual, and the accompanying software and other documentation, is protected by U.S. and
international copyright laws, and may be used only in accordance with the accompanying license
agreement. Features of the software, and of other products and services of Mercury Interactive
Corporation, may be covered by one or more of the following patents: U.S. Patent Nos. 5,701,139;
5,657,438; 5,511,185; 5,870,559; 5,958,008; 5,974,572; 6,138,157; 6,144,962; 6,205,122; 6,237,006;
6,341,310; 6,360,332, 6,449,739; 6,470,383; 6,477,483; 6,549,944; 6,560,564; and
6,564,342.6,564,342; 6,587,969; 6,631,408; 6,631,411; 6,633,912 and 6,694,288. Other patents
pending. All rights reserved.

Mercury, Mercury Interactive, the Mercury Interactive logo, LoadRunner, LoadRunner TestCenter,
QuickTest Professional, SiteScope, SiteSeer, TestDirector, Topaz and WinRunner are trademarks or
registered trademarks of Mercury Interactive Corporation or its subsidiaries, in the United States
and/or other countries. The absence of a trademark from this list does not constitute a waiver of
Mercury Interactive's intellectual property rights concerning that trademark.

All other company, brand and product names are registered trademarks or trademarks of their
respective holders. Mercury Interactive Corporation disclaims any responsibility for specifying which
marks are owned by which companies or which organizations.

Mercury Interactive Corporation

379 North Whisman Road
Mountain View, CA 94043
Tel: (650) 603-5200
Toll Free: (800) TEST-911
Customer Support: (877) TEST-HLP
Fax: (650) 603-5300

© 2004 Mercury Interactive Corporation, All rights reserved

If you have any comments or suggestions regarding this document, please send them via e-mail to
[email protected].

LRCTRUG8.0/01
Table of Contents

Welcome to Mercury LoadRunner .......................................................xi

Online Resources ..................................................................................xi
LoadRunner Documentation Set........................................................ xii
Using the LoadRunner Documentation Set ...................................... xiii
Documentation Updates .....................................................................xv
Typographical Conventions...............................................................xvi

P A R T I : U N DE R S T A N D I N G L O A D RU N N E R
Chapter 1: Introduction .......................................................................3
Application Load Testing .....................................................................3
The LoadRunner Solution ....................................................................4
Using LoadRunner.................................................................................5
Working with LoadRunner ..................................................................6
LoadRunner Vuser Technology .............................................................7
LoadRunner Vuser Types.......................................................................8
LoadRunner License Information .......................................................14
Chapter 2: The LoadRunner Testing Process......................................17
Step I: Planning the Test ....................................................................18
Step II: Creating the Vuser Scripts ....................................................18
Step III: Creating the Scenario ............................................................18
Step IV: Running the Scenario ...........................................................19
Step V: Monitoring a Scenario ...........................................................20
Step VI: Analyzing Test Results ..........................................................20
Chapter 3: Load Test Planning............................................................21
About Load Test Planning ...................................................................21
Analyzing the Application ..................................................................22
Defining Testing Objectives ................................................................25
Planning LoadRunner Implementation ..............................................27
Examining Load Testing Objectives....................................................33

iii
Table of Contents

Chapter 4: The LoadRunner Controller at a Glance ...........................37

Opening the Controller.......................................................................37
Introducing the LoadRunner Controller.............................................40
Managing Scenario Files .....................................................................44
Running a Scenario .............................................................................46

P A RT I I : D ES I GN I N G A SC E N A R I O
Chapter 5: Creating a Manual Scenario..............................................51
About Creating a Scenario ..................................................................52
Creating Vuser Groups .......................................................................55
Configuring Vusers in a Vuser Group ................................................64
Configuring Vuser Run-Time Settings ................................................71
Configuring Load Generators ............................................................74
Configuring Load Generator Settings ................................................78
Configuring Terminal Services Settings ..............................................90
Configuring WAN Emulation Settings................................................97
Configuring Scripts ..........................................................................105
Using Relative Paths for Scripts.........................................................109
Chapter 6: Creating a Manual Scenario Using the
Percentage Mode ...........................................................................111
About Creating a Manual Scenario Using the Percentage Mode......111
Defining the Total Number of Vusers ..............................................114
Assigning Properties to Scripts ..........................................................115
Configuring Scripts ..........................................................................118
Converting a Scenario to the Vuser Group Mode.............................123
Chapter 7: Creating a Goal-Oriented Scenario ...............................125
About Planning a Goal-Oriented Scenario........................................125
Understanding the Goal-Oriented Scenario Design Tab ..................128
Defining Scenario Goals....................................................................130
Assigning Properties to Scripts ..........................................................136
Configuring Scripts ..........................................................................139
Chapter 8: Scheduling a Scenario.....................................................145
About Scenario Scheduling ...............................................................146
Delaying the Start of a Scenario ........................................................147
Selecting a Schedule .........................................................................148
Scheduling a Scenario ......................................................................151
Scheduling Vuser Groups .................................................................155
Adding Vusers to a Scheduled Scenario ............................................159

iv
 Table of Contents

Chapter 9: Using Rendezvous Points ...............................................161

About Using Rendezvous Points .......................................................161
Setting the Rendezvous Attributes ...................................................163
Setting the Rendezvous Policy ..........................................................165
Disabling and Enabling Rendezvous Points......................................167
Disabling and Enabling Vusers at Rendezvous Points ......................167
Viewing Rendezvous Information ....................................................169
Chapter 10: Configuring a Scenario .................................................173
About Configuring a Scenario...........................................................173
Setting Timeout Intervals .................................................................174
Configuring Scenario Run-Time Settings..........................................177
Setting the Run-Time File Location .................................................179
Specifying Path Translation .............................................................183
Chapter 11: Preparing to Run a Scenario .........................................185
About Preparing to Run a Scenario ...................................................185
Specifying a Results Location ...........................................................186
Results Directory File Structure ........................................................189
Collating Results ...............................................................................191
Setting Scenario Summary Information ...........................................194
Chapter 12: Managing Scenarios Using Quality Center...................195
About Managing Scenarios Using Quality Center ...........................195
Connecting to and Disconnecting from Quality Center .................196
Opening Scenarios from a Quality Center Project ...........................200
Saving Scenarios to a Quality Center Project ...................................201
Saving Results to a Quality Center Project .......................................203
Adding Vuser Scripts from a Quality Center Project .......................204

P A R T I I I : EX E C UT I N G A S C E N A R I O
Chapter 13: Running a Scenario .......................................................209
About Running a Scenario ...............................................................209
Running an Entire Scenario .............................................................211
Controlling Vuser Groups .................................................................212
Controlling Individual Vusers...........................................................219
Manually Releasing Vusers from a Rendezvous ................................221
Manually Adding Vusers to a Running Scenario ..............................222

v
Table of Contents

Chapter 14: Viewing Vusers During Execution.................................229

About Viewing Vusers During Execution .........................................229
Monitoring Vuser Status ..................................................................230
Viewing the Output Window............................................................233
Viewing the Vuser Script Log ............................................................239
Logging Execution Notes .................................................................242
Viewing the Agent Summary ...........................................................243

PA RT I V: W O R K I N G W I T H FI R E WA L L S
Chapter 15: Using Firewalls in LoadRunner......................................247
About Using Firewalls in LoadRunner ..............................................247
Configuring Your System ..................................................................250
Overview of Running or Monitoring Vusers over a Firewall ............252
Checking Connectivity .....................................................................254
Chapter 16: Running Vusers Over a Firewall ....................................257
About Running Vusers Over a Firewall .............................................257
Overview of Running Vusers Over a Firewall ...................................258
Installing LoadRunner Agents Inside the Firewall ............................259
Configuring LoadRunner Agents Inside the Firewall .......................260
Configuring the Firewall to Allow Agent Access...............................269
Installing and Configuring the MI Listener Outside the Firewall ....270
Configuring the Controller to Run or Monitor Vusers
over a Firewall.................................................................................272
Chapter 17: Monitoring Over a Firewall...........................................275
About Monitoring over a Firewall ....................................................275
Installing Monitors over Firewall ......................................................276
Preparing for Data Collection ...........................................................277
Configuring Server Monitor Properties ............................................277
Configuring the Network Delay Monitor over a Firewall.................283

P A RT V : W O R K I N G W I T H D IA GN O ST I C S
Chapter 18: J2EE Diagnostics Module...............................................287
About J2EE Diagnostics Monitoring .................................................288
J2EE Diagnostics Module Architecture..............................................289
Setting up the Monitoring Environment..........................................290
Configuring J2EE Diagnostics on the Client Machine .....................294
Viewing J2EE Diagnostics Data .........................................................297
Examples of Modifying Application Server Configurations .............309
Troubleshooting the J2EE Diagnostics Module Monitor ..................320

vi
 Table of Contents

Chapter 19: ERP/CRM Diagnostics Modules.....................................323

About LoadRunner ERP/CRM Diagnostics Modules .........................324
ERP/CRM Diagnostics Module Architecture .....................................325
LoadRunner ERP/CRM Diagnostics Types ........................................327
Working With LoadRunner ERP/CRM Diagnostics ..........................328
Configuring Siebel Diagnostics .........................................................329
Configuring Siebel DB Diagnostics ...................................................338
Configuring Oracle DB Diagnostics ..................................................346
Enabling Diagnostics .........................................................................354
Viewing Diagnostics Results..............................................................357

P A R T V I: M O N I T O R I N G A S CE N A R I O
Chapter 20: Online Monitoring ........................................................361
About Online Monitoring .................................................................361
Setting Up the Monitoring Environment .........................................362
Monitor Types ...................................................................................364
Choosing Monitors and Measurements in the Controller ...............367
Starting the Monitors in the Controller............................................372
Opening Online Monitor Graphs in the Controller.........................374
Customizing the Online Monitor Display View ...............................376
Setting Monitor Options ...................................................................377
Chapter 21: Configuring Online Graphs...........................................381
About Online Monitor Graphs..........................................................381
Configuring Graph Properties...........................................................383
Configuring Graph Measurements ..................................................387
Merging Graphs ................................................................................392
Exporting Online Monitor Graphs ..................................................393
Viewing Data Offline ........................................................................394
Available Graphs Tree........................................................................394
Chapter 22: Remote Performance Monitoring ................................395
About Remote Performance Monitoring ..........................................396
Installing the Remote Performance Monitor Server ........................397
Configuring the Remote Performance Monitor User Settings..........398
Connecting to the LoadRunner Remote Performance Monitor ......401
Monitoring Load Test Data ...............................................................403
Viewing Online Graphs.....................................................................403
Customizing Online Graph Settings .................................................406

vii
Table of Contents

PA RT VII: A PPE ND IXES

Appendix A: Interpreting LoadRunner Online Graphs.....................413
Online Monitoring Graphs ..............................................................413
Appendix B: Performing Path Translation........................................417
Understanding Path Translation ......................................................417
Adding Entries to the Path Translation Table...................................419
Editing the Path Translation Table ..................................................420
Path Translation Examples................................................................422
Appendix C: Working in Expert Mode..............................................423
Entering Expert Mode .......................................................................423
Options - General Settings ...............................................................424
Options - Debug Information Settings .............................................426
Options - Output Settings ................................................................428
Options - Monitor Settings ...............................................................430
Load Generator Information - UNIX Environment Settings ...........431
Load Generator Information - Connection Log Settings..................432
Appendix D: Troubleshooting the Controller ..................................435
About Troubleshooting .....................................................................435
LoadRunner Communications .........................................................436
Failure to Communicate with a Load Generator ..............................437
Failure to Connect to the AUT Database ..........................................443
Failure to Access Files ........................................................................443
Failed Vusers or Transactions ............................................................445
Increasing the Number of Vusers on a Windows Machine ..............449
Troubleshooting Firewalls .................................................................450
Working With the LoadRunner Agent..............................................458
Appendix E: Configuring Multiple IP Addresses...............................461
About Multiple IP Addresses .............................................................461
Adding IP Addresses to a Load Generator .........................................463
Using the IP Wizard ..........................................................................464
Configuring Multiple IP Addresses on UNIX....................................468
Updating the Routing Table..............................................................470
Enabling Multiple IP Addressing from the Controller......................471
Appendix F: Controller Command Line Arguments .........................473
About Controller Command Line Arguments ..................................473
Invoking the Controller from the Command Line ..........................474
Quality Center Arguments ................................................................475
Run-Time Arguments ........................................................................476

viii
 Table of Contents

Appendix G: Working with Digital Certificates ................................477

Using Digital Certificates with Firewalls ...........................................477
Creating and Using Digital Certificates ............................................478
Index ..................................................................................................483

ix
Table of Contents

x
Welcome to Mercury LoadRunner

Welcome to LoadRunner, Mercury’s tool for application performance

testing. LoadRunner stresses your entire application to isolate and identify
potential client, network, and server bottlenecks.

LoadRunner enables you to test your system under controlled and peak load
conditions. To generate load, LoadRunner runs thousands of Virtual Users,
or Vusers, that are distributed over a network. Using a minimum of
hardware resources, these Vusers provide consistent, repeatable, and
measurable load to exercise your application just as real users would.
LoadRunner’s in-depth reports and graphs provide the information that you
need to evaluate the performance of your application.

Online Resources
LoadRunner includes the following online tools:

Read Me First provides last-minute news and information about

LoadRunner.

Books Online displays the complete documentation set in PDF format.

Online books can be read and printed using Adobe Acrobat Reader, which is
included in the installation package. Check Mercury’s Customer Support
Web site for updates to LoadRunner online books.

LoadRunner Function Reference gives you online access to all of

LoadRunner’s functions that you can use when creating Vuser scripts,
including examples of how to use the functions. Check Mercury’s Customer
Support Web site for updates to the online LoadRunner Function Reference.

xi
Welcome

LoadRunner Context Sensitive Help provides immediate answers to

questions that arise as you work with LoadRunner. It describes dialog boxes,
and shows you how to perform LoadRunner tasks. To activate this help,
click in a window and press F1. Check Mercury’s Customer Support Web site
for updates to LoadRunner help files.

Technical Support Online uses your default Web browser to open Mercury’s
Customer Support Web site. This site enables you to browse the knowledge
base and add your own articles, post to and search user discussion forums,
submit support requests, download patches and updated documentation,
and more. The URL for this Web site is http://support.mercuryinteractive.com.

Support Information presents the locations of Mercury’s Customer Support

Web site and home page, the e-mail address for sending information
requests, and a list of Mercury’s offices around the world.

Mercury Interactive on the Web uses your default Web browser to open
Mercury’s home page (http://www.mercuryinteractive.com). This site enables
you to browse the knowledge base and add your own articles, post to and
search user discussion forums, submit support requests, download patches
and updated documentation, and more.

LoadRunner Documentation Set

LoadRunner is supplied with a set of documentation that describes how to:

➤ install LoadRunner
➤ create Vuser scripts
➤ use the LoadRunner Controller
➤ configure the LoadRunner monitors
➤ use the LoadRunner Analysis

xii
 Welcome

Using the LoadRunner Documentation Set

The LoadRunner documentation set consists of an installation guide, a
Controller user’s guide, a Monitor Reference, an Analysis user’s guide, and a
guide for creating Virtual User scripts.

Installation Guide
For instructions on installing LoadRunner, refer to the LoadRunner
Installation Guide. The installation guide explains how to install:

➤ the LoadRunner Controller—on a Windows-based machine

➤ Virtual User components—for both Windows and UNIX platforms
➤ Additional LoadRunner components

Controller User’s Guide

The LoadRunner documentation set includes a Controller user’s guide:

The LoadRunner Controller User’s Guide describes how to create and run
LoadRunner scenarios using the LoadRunner Controller in a Windows
environment. The Vusers can run on UNIX and Windows-based platforms.
The Controller user’s guide presents an overview of the LoadRunner testing
process.

Monitor Reference
The LoadRunner documentation set includes a Monitor Reference guide:

The LoadRunner Monitor Reference describes how to set up the server monitor
environment and configure LoadRunner monitors for monitoring data
generated during a scenario or tuning session.

Analysis User’s Guide

The LoadRunner documentation set includes an Analysis user’s guide:

The LoadRunner Analysis User’s Guide describes how to use the LoadRunner
Analysis graphs and reports after running a scenario or tuning session to
analyze system performance.

xiii
Welcome

Guide for Creating Vuser Scripts

The LoadRunner documentation set includes a guide for creating scripts:

The Mercury Virtual User Generator User’s Guide describes how to create scripts
using VuGen. When necessary, supplement this document with the online
LoadRunner Function Reference and the WinRunner User’s Guide for creating
GUI scripts.

Note: The Mercury Virtual User Generator User’s Guide online version is a
single volume, while the printed version consists of two volumes, Volume I -
Using VuGen and Volume II - Protocols.

For information on Look here...

Installing Mercury LoadRunner Installation Guide

LoadRunner

The LoadRunner load testing LoadRunner Controller User’s Guide

process

Creating Vuser scripts Mercury Virtual User Generator User’s Guide

Volume I - Using VuGen, Volume II - Protocols

Configuring the server LoadRunner Monitor Reference

monitors

Creating and running load LoadRunner Controller User’s Guide

test scenarios

Analyzing test results LoadRunner Analysis User’s Guide

xiv
 Welcome

Documentation Updates
Mercury is continuously updating its product documentation with new
information. You can download the latest version of this document from
Mercury’s Customer Support Web site (http://support.mercuryinteractive.com).

To download updated documentation:

1 In the Customer Support Web site, click the Documentation link.
2 Select the product name. Note that if LoadRunner does not appear in the
list, you must add it to your customer profile. Click "My Account" to update
your profile.
3 Click Retrieve. The Documentation page opens and lists all the
documentation available for the current release and for previous releases. If
a document was recently updated, Updated appears next to the document
name.
4 Click a document link to download the documentation.

xv
Welcome

Typographical Conventions
This book uses the following typographical conventions:

1, 2, 3 Bold numbers indicate steps in a procedure.

➤ Bullets indicate options and features.
> The greater than sign separates menu levels (for
example, File > Open).
Stone Sans The Stone Sans font indicates names of interface
elements on which you perform actions (for example,
“Click the Run button.”). It also indicates method or
function arguments, file names or paths.
Bold Bold text indicates method or function names
Italics Italic text indicates book titles.
Arial The Arial font is used for examples and text that is to
be typed literally.
<> Angle brackets enclose a part of a file path or URL
address that may vary from user to user (for example,
<Product installation folder>\bin).
[ ] Square brackets enclose optional arguments.
{} Curly brackets indicate that one of the enclosed values
must be assigned to the current argument.
... In a line of syntax, an ellipsis indicates that more items
of the same format may be included. In a
programming example, an ellipsis is used to indicate
lines of a program that were intentionally omitted.
| A vertical bar indicates that one of the options
separated by the bar should be selected.

xvi
 Part I
Understanding LoadRunner
2
1
Introduction

LoadRunner load tests your application by emulating an environment in

which multiple users work concurrently. While the application is under
load, LoadRunner accurately measures, monitors, and analyzes a system’s
performance and functionality.

Application Load Testing

Modern system architectures are complex. While they provide an
unprecedented degree of power and flexibility, these systems are difficult to
test. Whereas single-user testing focuses primarily on functionality and the
user interface of a system component, application testing focuses on
performance and reliability of an entire system.

For example, a typical application testing scenario might depict 1000 users
that log in simultaneously to a system on Monday morning: What is the
response time of the system? Does the system crash? To be able to answer
these questions—and more—a complete application performance testing
solution must:

➤ test a system that combines a variety of software applications and hardware

platforms
➤ determine the suitability of a server for any given application
➤ test the server before the necessary client software has been developed
➤ emulate an environment where multiple clients interact with a single server
application
➤ test an application under the load of tens, hundreds, or even thousands of
potential users

3
Part I • Understanding LoadRunner

Manual Testing Limitations

Traditional or manual testing methods offer only a partial solution to load
testing. For example, you can test an entire system manually by
constructing an environment where many users work simultaneously on
the system. Each user works at a single machine and submits input to the
system. However, this manual testing method has the following drawbacks:

➤ it is expensive, requiring large amounts of both personnel and machinery

➤ it is complicated, especially coordinating and synchronizing multiple testers
➤ it involves a high degree of organization, especially to record and analyze
results meaningfully
➤ the repeatability of the manual tests is limited

The LoadRunner Solution

LoadRunner addresses the drawbacks of manual performance testing:

➤ LoadRunner reduces personnel requirements by replacing human users with

virtual users or Vusers. These Vusers emulate the behavior of real users—
operating real applications.
➤ Because numerous Vusers can run on a single computer, LoadRunner
reduces the amount of hardware required for testing.
➤ The LoadRunner Controller allows you to easily and effectively control all
the Vusers—from a single point of control.
➤ LoadRunner monitors the application performance online, enabling you to
fine-tune your system during test execution.
➤ LoadRunner automatically records the performance of the application
during a test. You can choose from a wide variety of graphs and reports to
view the performance data.
➤ LoadRunner checks where performance delays occur: network or client
delays, CPU performance, I/O delays, database locking, or other issues at the
database server. LoadRunner monitors the network and server resources to
help you improve performance.

4
 Chapter 1 • Introduction

➤ Because LoadRunner tests are fully automated, you can easily repeat them as
often as you need.

Using LoadRunner
Using LoadRunner, you divide your application performance testing
Scenarios requirements into scenarios. A scenario defines the events that occur during
each testing session. Thus, for example, a scenario defines and controls the
number of users to emulate, the actions that they perform, and the
machines on which they run their emulations.

In the scenario, LoadRunner replaces human users with virtual users or

Vusers Vusers. When you run a scenario, Vusers emulate the actions of human
users working with your application. While a workstation accommodates
only a single human user, many Vusers can run concurrently on a single
workstation. In fact, a scenario can contain tens, hundreds, or even
thousands of Vusers.

The actions that a Vuser performs during the scenario are described in a
Vuser Scripts Vuser script. When you run a scenario, each Vuser executes a Vuser script.
The Vuser scripts include functions that measure and record the
performance of your application’s components.

To measure the performance of the server, you define transactions. A

Transactions transaction represents an action or a set of actions that you are interested in
measuring. You define transactions within your Vuser script by enclosing
the appropriate sections of the script with start and end transaction
statements. For example, you can define a transaction that measures the
time it takes for the server to process a request to view the balance of an
account and for the information to be displayed at the ATM.

You insert rendezvous points into Vuser scripts to emulate heavy user load
Rendezvous on the server. Rendezvous points instruct Vusers to wait during test
points
execution for multiple Vusers to arrive at a certain point, so that they may
simultaneously perform a task. For example, to emulate peak load on the
bank server, you can insert a rendezvous point instructing 100 Vusers to
deposit cash into their accounts at the same time.

5
Part I • Understanding LoadRunner

You use the LoadRunner Controller to manage and maintain your scenarios.
Controller Using the Controller, you control all the Vusers in a scenario from a single
workstation.

When you execute a scenario, the LoadRunner Controller distributes each

Load Vuser in the scenario to a load generator. The load generator is the machine
generator
that executes the Vuser script, enabling the Vuser to emulate the actions of a
human user.

Vuser scripts include functions that measure and record system performance
Performance during load-testing sessions. During a scenario run, you can monitor the
analysis
network and server resources. Following a scenario run, you can view
performance analysis data in reports and graphs.

Working with LoadRunner

Suppose you want to test an online banking Web server that is accessed by
many Internet users. The Web site provides a full range of banking services
to the customers—such as the ability to transfer funds and check account
balances. To test this server, you create a scenario. The scenario defines the
actions that are performed on the server during the load test.

During the scenario that loads and monitors the bank server, you want to:

➤ emulate conditions of controlled load on the server

➤ emulate conditions of maximum load on the server
➤ measure server performance under load
➤ check where performance delays occur: network or client delays, CPU
performance, I/O delays, database locking, or other issues at the server
➤ monitor the network and server resources under load

6
 Chapter 1 • Introduction

LoadRunner Vuser Technology

On each Windows load generator, you install the Remote Agent Dispatcher
(Process) and a LoadRunner Agent.

Vuser Remote Agent

Dispatcher (Process)

Vuser Agent

Vuser
Controller

Load Generator

Remote Agent The Remote Agent Dispatcher (Process) enables the Controller to start
Dispatcher applications on the load generator machine.
(Process)
The LoadRunner Agent enables the Controller and the load generator to
Agent communicate with each other. When you run a scenario, the Controller
instructs the Remote Agent Dispatcher (Process) to launch the LoadRunner
agent. The agent receives instructions from the Controller to initialize, run,
pause, and stop Vusers. At the same time, the agent also relays data on the
status of the Vusers back to the Controller.

7
Part I • Understanding LoadRunner

LoadRunner Vuser Types

LoadRunner has various types of Vusers. Each type is designed to handle
different aspects of today’s system architectures. You can use the Vuser types
in any combination in a scenario in order to create a comprehensive
application test. The following Vuser types are available:

➤ Application Deployment Solution

For the Citrix protocol.
➤ Client/Server
For MS SQL, ODBC, Oracle Web Applications 11i, DB2 CLI, Sybase Ctlib,
Sybase Dblib, Windows Sockets, and DNS protocols.
➤ Custom
For C templates, Visual Basic templates, Java templates, Javascript, and
VBScript type scripts.
➤ Distributed Components
For COM/DCOM, Corba-Java, and Rmi-Java protocols.
➤ E-business
For FTP, LDAP, Palm, Web (HTTP/HTML), Web Services, and the dual
Web/Winsocket protocols.
➤ Enterprise Java Beans
For EJB Testing and Rmi-Java protocols.
➤ ERP/CRM
For Baan, Oracle NCA, Peoplesoft 8, Peoplesoft-Tuxedo, SAP-Web, SAPGUI,
SAPGUI/SAP-Web dual, and Siebel (Siebel-DB2 CLI, Siebel-MSSQL, Siebel-
Web, and Siebel-Oracle) protocols.
➤ Legacy
For Terminal Emulation (RTE).
➤ Mailing Services
Internet Messaging (IMAP), MS Exchange (MAPI), POP3, and SMTP.

8
 Chapter 1 • Introduction

➤ Middleware
For the Jacada and Tuxedo (6, 7) protocols.
➤ Streaming
For MediaPlayer and RealPlayer protocols.
➤ Wireless
For i-Mode, VoiceXML, and WAP protocols.

9
Part I • Understanding LoadRunner

GUI Vusers
GUI Vusers operate graphical user interface (GUI) applications. These
GUI Vusers applications can run in a Microsoft Windows environment. Each GUI Vuser
that you develop emulates a real user by submitting input to, and receiving
output from, GUI applications. For example, a GUI Vuser could operate
Microsoft Paint as follows:

1. Select Open from the File menu.

2. Select a graphic file called test.bmp.
3. Click the Open button.
4. Select Flip/Rotate from the Image menu.
5. Click the Flip Horizontal radio button.
6. Click the OK button.
7. Select Save from the File menu.

10
 Chapter 1 • Introduction

The operations that a GUI Vuser performs on an application are defined in a

GUI Vuser script. You create GUI Vuser scripts using Mercury’s GUI testing
tools: WinRunner (for Microsoft Windows applications), and Astra
QuickTest (for Web applications).

You can run only a single GUI Vuser on a Windows-based load generator.
Use Citrix to run multiple GUI Vusers. Refer to the Readme file for
additional information about configuring your load generators using Citrix.
For additional information on Windows-based GUI Vusers, refer to the
Mercury Virtual User Generator User’s Guide.

Note: You can run GUI and SAP Vusers on remote load generators only if
you install the Remote Agent Dispatcher as a process. If you install the
Remote Agent Dispatcher as a service, you cannot run GUI Vusers on remote
load generators.

Vuser Technology
Vusers (except for GUI and RTE Vusers) generate load on a server by
submitting input directly to the server. Vusers do not operate client
applications—they access the server using LoadRunner API functions. These
API functions emulate the input from an actual application.

Vuser script

Vuser Server

Because Vusers are not reliant on client software, you can use Vusers to test
server performance even before the client software has been developed.
Further, since Vusers do not have a user interface, the amount of system
resources required is minimal. This allows you to run large numbers of
Vusers on a single workstation.

11
Part I • Understanding LoadRunner

The following example illustrates the use of Vusers: Suppose that you have a
Web-based database server that maintains your customer information. The
information is accessed by numerous customer service personnel who are
located throughout the country. The server receives the queries, processes
the requests, and returns responses via the Web to field personnel.

You want to test the response times of the entire system when numerous
service personnel simultaneously access the server. Using LoadRunner, you
could create several hundred Vusers, each Vuser accessing the server
database. The Vusers enable you to emulate and measure the performance of
your database and Web servers under the load of many users.

You develop a Vuser script to define the actions of a Vuser. A Vuser script
includes functions that control the script execution, specify the input that
the Vuser submits to the server, and measure the server performance.

You develop Vuser scripts either by recording with Mercury’s Virtual User
Generator (VuGen) or by using LoadRunner’s Vuser script templates.

For the database server example above, you could create a Vuser script that
performs the following actions:

➤ logs in to the Web application

➤ connects to the database server
➤ submits an SQL query
➤ retrieves and processes the server response
➤ disconnects from the server and the Web

You can create Vuser scripts on a Windows-based platform, or program them

on a UNIX platform. For a list of the supported UNIX platforms, see the
LoadRunner Readme file. For more information about Vusers, refer to the
Mercury Virtual User Generator User’s Guide.

12
 Chapter 1 • Introduction

RTE Vusers
RTE Vusers operate character-based applications. Each RTE Vuser that you
RTE Vusers develop emulates a real user by submitting input to, and receiving output
from, character-based applications.

The following example illustrates the use of RTE Vusers: Suppose that you
have a database server that maintains customer information. The
information is accessed by numerous field service representatives who are
located throughout the country. Every time a field service representative
makes a repair, he accesses the server database by modem. Using a character-
based application, the service representative records the customer complaint
and accesses additional information about the customer.

You want to test the response times of the server when many service
personnel simultaneously access the server. Using LoadRunner, you could
create several hundred RTE Vusers, each Vuser accessing the server database
using a character-based application. The RTE Vusers enable you to emulate
and measure the performance of your server under the load of many users.

13
Part I • Understanding LoadRunner

The operations that an RTE Vuser performs on an application are defined in

an RTE Vuser script. You create RTE Vuser scripts by using the VuGen. The
generator enables you to record the actions that you perform on a character-
based application.

Terminal Emulator

RTE Vuser script Application

RTE Vuser Server

For further information on RTE Vusers, refer to the Mercury Virtual User
Generator User’s Guide.

LoadRunner License Information

To preview your license key information, click
Start > Programs > Mercury LoadRunner > LoadRunner. Mercury
LoadRunner opens. Click the License button. The License Information
dialog opens.

14
 Chapter 1 • Introduction

The LoadRunner License Information dialog displays the following

information:

License Keys: Displays the available license keys, as well as a summary of all
the available license keys.

License Key Information

Type: Displays the type of license available for the license key you selected.
The following types of licenses are available:

➤ Permanent: The license never expires.

➤ Time Limited: The license is limited by a start date and an expiration
date.
➤ Temporary: The license is granted for a pre-defined number of days after
product installation.
➤ VUD-based: The license is limited by a number of Virtual User Days
(VUDs). A VUD license enables the user to use the product an unlimited
number of times within a period of 24 hours.

Note: If a user has a VUD-based license for 1000 Vusers and the maximum
number of concurrently running Vusers within a 24-hour period is 300, the
following day the user will be able to run the remaining 700 Vusers.

➤ Plugged: The license requires a dongle.

License Validity: Displays the time limitation of the selected license key.

Vuser Types: Displays a list of Vuser protocols available for the selected
license key.

Monitors: Displays the server monitors available for the selected license key.

Host ID: Displays an ID for a specific machine. To receive a license key for a
specific machine, contact Mercury’s Customer Support.

15
Part I • Understanding LoadRunner

To modify the current license information:

1 Click Start > Programs > Mercury LoadRunner > LoadRunner to open the
Mercury LoadRunner window, and then click the License button. The
LoadRunner License Information dialog box opens.
2 Click the New License button. The New LoadRunner License dialog box
opens.

3 Enter the new license number exactly as it was given to you and click OK. If
your license is limited for a specific amount of time, LoadRunner issues a
message accordingly.
4 Click OK to close the New LoadRunner License dialog.

16
2
The LoadRunner Testing Process

You can easily create and run load test scenarios by following the
LoadRunner testing process below. The following illustration outlines the
testing process:

17
Part I • Understanding LoadRunner

This chapter gives you an overview of LoadRunner’s six–step process for

testing your Web-based application under load.

Step I: Planning the Test

Successful load testing requires that you develop a thorough test plan. A
clearly defined test plan will ensure that the LoadRunner scenarios that you
develop will accomplish your load testing objectives. For more information,
see Chapter 3, “Load Test Planning.”

Step II: Creating the Vuser Scripts

Vusers emulate human users interacting with your Web-based application. A
Vuser script contains the actions that each Vuser performs during scenario
execution.

In each Vuser script, you determine the tasks that will be:

➤ performed by each Vuser

➤ performed simultaneously by multiple Vusers
➤ measured as transactions

For more information on creating Vuser scripts, refer to the Mercury Virtual
User Generator User’s Guide.

Step III: Creating the Scenario

A scenario describes the events that occur during a testing session. A
scenario includes a list of machines on which Vusers run, a list of scripts that
the Vusers run, and a specified number of Vusers or Vuser groups that run
during the scenario. You create scenarios using the LoadRunner Controller.
For an introduction to the Controller, see Chapter 4, “The LoadRunner
Controller at a Glance.”

18
 Chapter 2 • The LoadRunner Testing Process

Creating a Manual Scenario

You create a scenario by defining Vuser groups to which you assign a
quantity of individual Vusers, Vuser scripts, and load generators to run the
scripts. For instructions on creating a manual scenario, see Chapter 5,
“Creating a Manual Scenario.”

You can also create a scenario using the Percentage Mode, in which you
define the total number of Vusers to be used in the scenario, and the load
generator machines and percentage of the total number of Vusers to be
assigned to each Vuser script. For instructions on creating a manual scenario
in Percentage Mode, see Chapter 6, “Creating a Manual Scenario Using the
Percentage Mode.”

Creating a Goal-Oriented Scenario

For Web tests, you can create a goal-oriented scenario, in which you define
the goals you want your test to achieve. LoadRunner automatically builds a
scenario for you, based on these goals. For instructions on creating a goal-
oriented scenario, see Chapter 7, “Creating a Goal-Oriented Scenario.”

Step IV: Running the Scenario

You emulate user load on the server by instructing multiple Vusers to
perform tasks simultaneously. You can set the level of load by increasing and
decreasing the number of Vusers that perform tasks at the same time. For
more information, see Chapter 9, “Using Rendezvous Points.”

Before you run a scenario, you set the scenario configuration and
scheduling. This determines how all the load generators and Vusers behave
when you run the scenario. For more information, see Chapter 10,
“Configuring a Scenario” and Chapter 8, “Scheduling a Scenario.”

You can run the entire scenario, groups of Vusers (Vuser groups), or
individual Vusers. While a scenario runs, LoadRunner measures and records
the transactions that you defined in each Vuser script. You can also monitor
your system’s performance online. For more information, see Part III,
“Executing a Scenario.”

19
Part I • Understanding LoadRunner

Step V: Monitoring a Scenario

You can monitor scenario execution using the LoadRunner online run-time,
transaction, system resource, Web resource, Web server resource, Web
application server resource, database server resource, network delay,
streaming media resource, firewall server resource, ERP/CRM server resource,
Java performance, J2EE transaction breakdown, application deployment,
middleware performance, application component, and infrastructure
resources monitors. For more information, see Part VI, “Monitoring a
Scenario.”

Step VI: Analyzing Test Results

During scenario execution, LoadRunner records the performance of the
application under different loads. You use LoadRunner’s graphs and reports
to analyze the application’s performance. For more information about
LoadRunner’s reports and graphs, see the LoadRunner Analysis User’s Guide.

20
3
Load Test Planning

Developing a comprehensive test plan is a key to successful load testing. A

clearly defined test plan ensures that the LoadRunner scenarios you develop
will accomplish your load testing objectives.

This chapter introduces the load test planning process:

➤ About Load Test Planning

➤ Analyzing the Application
➤ Defining Testing Objectives
➤ Planning LoadRunner Implementation
➤ Examining Load Testing Objectives

About Load Test Planning

As in any type of system testing, a well-defined test plan is the first essential
step to successful testing. Planning your load testing helps you to:

➤ Build test scenarios that accurately emulate your working environment.

Load testing means testing your application under typical working
conditions, and checking for system performance, reliability, capacity, and
so forth.

➤ Understand which resources are required for testing.

Application testing requires hardware, software, and human resources.
Before you begin testing, you should know which resources are available
and decide how to use them effectively.

➤ Define success criteria in measurable terms.

21
Part I • Understanding LoadRunner

Focused testing goals and test criteria ensure successful testing. For example,
it’s not enough to define vague objectives like “Check server response time
under heavy load.” A more focused success criterion would be “Check that
50 customers can check their account balance simultaneously, and that the
server response time will not exceed one minute.”

Load test planning is a three-step process:

Analyzing the Application

The first step to load test planning is analyzing your application. You should
become thoroughly familiar with the hardware and software components,
the system configuration, and the typical usage model. This analysis ensures
that the testing environment you create using LoadRunner will accurately
reflect the environment and configuration of the application under test.

Identifying System Components

Draw a schematic diagram to illustrate the structure of the application. If
possible, extract a schematic diagram from existing documentation. If the
application under test is part of a larger network system, you should identify
the component of the system to be tested. Make sure the diagram includes
all system components, such as client machines, network, middleware, and
servers.

22
 Chapter 3 • Load Test Planning

The following diagram illustrates an online banking system that is accessed

by many Web users. The Web users each connect to the same database to
transfer funds and check balances. The customers connect to the database
server through the Web, using multiple browsers.

Describing the System Configuration

Enhance the schematic diagram with more specific details. Describe the
configuration of each system component. You should be able to answer the
following questions:

➤ How many users are anticipated to connect to the system?

➤ What is the application client’s machine configuration (hardware, memory,
operating system, software, development tool, and so forth)?
➤ What types of database and Web servers are used (hardware, database type,
operating system, file server, and so forth)?
➤ How does the server communicate with the application client?
➤ What is the middleware configuration and application server between the
front-end client and back-end server?
➤ What other network components may affect response time (modems and so
forth)?
➤ What is the throughput of the communications devices? How many
concurrent users can each device handle?

23
Part I • Understanding LoadRunner

For example, the schematic diagram above specified that there are multiple
application clients accessing the system.

Front-End Client Configuration

Anticipated number of application 50 concurrent application clients

clients

Hardware / Memory 586 / 32MB

Operating system & version Windows NT 4.0

Client browser Internet Explorer 4.0

Analyzing the Usage Model

Define how the system is typically used, and decide which functions are
important to test. Consider who uses the system, the number of each type of
user, and each user’s common tasks. In addition, consider any background
load that might affect the system response time.

For example, suppose 200 employees log on to the accounting system every
morning, and the same office network has a constant background load of 50
users performing various word processing and printing tasks. You could
create a LoadRunner scenario with 200 virtual users signing in to the
accounting database, and check the server response time.

To check how background load affects the response time, you could run
your scenario on a network where you also simulate the load of employees
performing word processing and printing activities.

Task Distribution
In addition to defining the common user tasks, examine the distribution of
these tasks. For example, suppose the bank uses a central database to serve
clients across many states and time zones. The 250 application clients are
located in two different time zones, all connecting to the same Web server.
There are 150 in Chicago and 100 in Detroit. Each begins their business day
at 9:00 AM, but since they are in different time zones, there should never be
more than 150 users signing in at any given time. You can analyze task
distribution to determine when there is peak database activity, and which
activities typically occur during peak load time.

24
 Chapter 3 • Load Test Planning

Defining Testing Objectives

Before you begin testing, you should define exactly what you want to
accomplish.

Following are common application testing objectives that LoadRunner helps

you test, as described in Robert W. Buchanan, Jr’s The Art of Testing Network
Systems (John Wiley & Sons, Inc., 1996).

Objective Answers the Question

Measuring end-user response How long does it take to complete a business

time process?

Defining optimal hardware Which hardware configuration provides the

configuration best performance?

Checking reliability How hard or long can the system work without
errors or failures?

Checking hardware or software How does the upgrade affect performance or

upgrades reliability?

Evaluating new products Which server hardware or software should you

choose?

Measuring system capacity How much load can the system handle
without significant performance degradation?

Identifying bottlenecks Which element is slowing down response

time?

A more detailed description of each objective appears at the end of this

chapter.

25
Part I • Understanding LoadRunner

Stating Objectives in Measurable Terms

Once you decide on your general load testing objectives, you should
identify more focused goals by stating your objectives in measurable terms.
To provide a baseline for evaluation, determine exactly what constitutes
acceptable and unacceptable test results.

For example:

General Objective - Product Evaluation: choose hardware for the Web

server.

Focused Objective - Product Evaluation: run the same group of 300 virtual
users on two different servers, HP and NEC. When all 300 users
simultaneously browse the pages of your Web application, determine which
hardware gives a better response time.

Deciding When to Test

Load testing is necessary throughout the product life cycle. The following
table illustrates what types of tests are relevant for each phase of the product
life cycle:

Planning
Development Deployment Production Evolution
and Design

Evaluate new Measure Check Measure Check HW or

products response time reliability response SW upgrades
time

Measure Check optimal Measure Identify Measure

response hardware response time bottlenecks system
time configuration capacity

Check HW or Measure
SW upgrades system
capacity

Check
reliability

26
 Chapter 3 • Load Test Planning

Planning LoadRunner Implementation

The next step is to decide how to use LoadRunner to achieve your testing
goals.

Defining the Scope of Performance Measurements

You can use LoadRunner to measure response time at different points in the
application. Determine where to run the Vusers and which Vusers to run
according to the test objectives:

➤ Measuring end-to-end response time:

You can measure the response time that a typical user experiences by
running a GUI Vuser or RTE Vuser at the front end. GUI Vusers emulate real
users by submitting input to and receiving output from the client
application; RTE Vusers emulate real users submitting input to and receiving
output from a character-based application.

You can run GUI or RTE Vusers at the front end to measure the response
time across the entire network, including a terminal emulator or GUI front
end, network, and server.

RTE
API
GUI

Client Middleware Server

➤ Measuring network and server response times:

You can measure network and server response time, excluding response time
of the GUI front end, by running Vusers (not GUI or RTE) on the client
machine. Vusers emulate client calls to the server without the user interface.

27
Part I • Understanding LoadRunner

When you run many Vusers from the client machine, you can measure how
the load affects network and server response time.

GUI API

Client Middleware Server

➤ Measuring GUI response time:

You can determine how the client application interface affects response time
by subtracting the previous two measurements:

GUI response time = end-to-end - network and server

GUI response time

GUI API

Client Middleware Server

➤ Measuring server response time:

You can measure the time it takes for the server to respond to a request
without going across the network. When you run Vusers on a machine
directly connected to the server, you can measure server performance.

GUI API

Client Middleware Server

28
 Chapter 3 • Load Test Planning

➤ Measuring middleware-to-server response time:

You can measure response time from the server to middleware if you have
access to the middleware and its API. You can create Vusers with the
middleware API and measure the middleware-server performance.

GUI API

Client Middleware Server

Defining Vuser Activities

Create Vuser scripts based on your analysis of Vuser types, their typical tasks
and your test objectives. Since Vusers emulate the actions of a typical end-
user, the Vuser scripts should include the typical end-user tasks. For
example, to emulate an online banking client, you should create a Vuser
script that performs typical banking tasks. You would browse the pages that
you normally visit to transfer funds or check balances.

You decide which tasks to measure based on your test objectives and define
transactions for these tasks. Transactions measure the time that it takes for
the server to respond to tasks submitted by Vusers (end-to-end time). For
example, to check the response time of a bank Web server supplying an
account balance, define a transaction for this task in the Vuser script.

In addition, you can emulate peak activity by using rendezvous points in

your script. Rendezvous points instruct multiple Vusers to perform tasks at
exactly the same time. For example, you can define a rendezvous to emulate
70 users simultaneously updating account information.

Selecting Vusers
Before you decide on the hardware configuration to use for testing,
determine the number and type of Vusers required. To decide how many
Vusers and which types to run, look at the typical usage model, combined
with the testing objectives. Some general guidelines are:

➤ Use one or a few GUI users to emulate each type of typical user connection.
➤ Use RTE Vusers to emulate terminal users.

29
Part I • Understanding LoadRunner

➤ Run multiple non-GUI or non-RTE Vusers to generate the rest of the load for
each user type.

For example, suppose that you have five kinds of users, each performing a
different business process:

Usage Model GUI RTE Other

100 customer service users in New York 2 _ 98

(LAN connection)

30 customers in Europe 2 _ 28
(dial-in ISDN connection)

5 background batch processes _ _ 5

150 customers _ 150 _

(terminal connection)

6 managers 1 (486 PC) _ 4

(2 users with 486 PCs, 4 with 586 PCs) 1 (586 PC)

Choosing Testing Hardware/Software

The hardware and software should be powerful and fast enough to emulate
the required number of virtual users.

To decide on the number of machines and correct configuration, consider

the following:

➤ It is advisable to run the LoadRunner Controller on a separate machine.

➤ Each GUI Vuser requires a separate Windows-based machine; several GUI
Vusers can run on a single UNIX machine.
➤ Configuration of the test machine for GUI Vusers should be as similar as
possible to the actual user’s machine.
Refer to the following tables to estimate the required hardware for each
LoadRunner testing component. These requirements are for optimal
performance.

30
 Chapter 3 • Load Test Planning

Windows Configuration Requirements

Controller with Virtual Vuser

Requirement Virtual Users Analysis Module
Online Monitors Generator

Computer/ Pentium 350 Pentium 350 Pentium 1 GHz or Pentium 350

Processor MHz or higher MHz or higher higher MHz or higher

Operating Windows NT® Windows NT® Windows NT® Windows NT®

System service pack 6a service pack 6a service pack 6a or service pack 6a
or later or later later or later
Windows 2000 Windows 2000 Windows 2000 Windows 2000
Windows XP Windows XP Windows XP Windows XP
HP UX 11.x or
higher, Solaris 2.6 or
higher, AIX 4.3.3 or
higher, Linux Red
Hat 6.0 or higher

Memory 128 MB or more 128 MB or more At least 1 MB RAM 128 MB or more

for non-multi-
threaded Vuser or at
least 512 KB multi-
threaded Vuser

Swap Space Twice the total Twice the total Twice the total Twice the total
physical mem- physical mem- physical memory physical mem-
ory ory ory

Free Hard 200 MB 200 MB Minimum 500 MB Minimum 500

Disk Space MB

Browser IE 5.x or higher IE 5.x or higher N/A IE 5.x or higher

Netscape Navi- Netscape Navi- Netscape Navi-
gator 4.x, 6.x gator 4.x, 6.x gator 4.x, 6.x

Note: The results file requires a few MB of disk space for a long scenario run
with many transactions. The load generator machines also require a few MB
of disk space for temporary files if there is no NFS. See Chapter 10,
“Configuring a Scenario” for more information about run-time file storage.

31
Part I • Understanding LoadRunner

Note: Refer to
http://www.mercuryinteractive.com/products/loadrunner/technical/ for the most
updated installation requirements.

UNIX Configuration Requirements

GUI Vuser Vuser Web Vuser

Requirement
(per user) (per user) (per user)

Memory 4-5 MB plus At least 1.5 ~0.5 MB

client MB (depends
application on
requirements application)

Swap Space Four times Four times Two times

the total the total the total
physical physical physical
memory memory memory

Disk Space n/a n/a n/a

No. of 4 1 1
Processes

No. of pty’s n/a n/a n/a

1 CPU 30-50 or 200-300 or 300-400 or

supports x more more more
users

Note: The results file requires a few MB of disk space for a long scenario run
with many transactions. The load generator machines also require a few MB
of disk space for temporary files if there is no NFS. Refer to Chapter 10,
“Configuring a Scenario” for more information about run-time file storage.

32
 Chapter 3 • Load Test Planning

Examining Load Testing Objectives

Your test plan should be based on a clearly defined testing objective. This
section presents an overview of common testing objectives:

➤ Measuring End-User Response Time

➤ Defining Optimal Hardware Configuration
➤ Checking Reliability
➤ Checking Hardware or Software Upgrades
➤ Evaluating New Products
➤ Identifying Bottlenecks
➤ Measuring System Capacity

Measuring End-User Response Time

Check how long it takes for the user to perform a business process and
receive a response from the server. For example, suppose that you want to
verify that while your system operates under normal load conditions, the
end users receive responses to all requests within 20 seconds. The following
graph presents a sample load vs. response time measurement for a banking
application:

80
Check account
Response 60 information
Time
(seconds)
40
Login
20
0
0 10 20 30 40 50
Number of Users

33
Part I • Understanding LoadRunner

Defining Optimal Hardware Configuration

Check how various system configurations (memory, CPU speed, cache,
adaptors, modems) affect performance. Once you understand the system
architecture and have tested the application response time, you can measure
the application response for different system configurations to determine
which settings provide the desired performance levels.

For example, you could set up three different server configurations and run
the same tests on each configuration to measure performance variations:

➤ Configuration 1: 200MHz, 64MB RAM

➤ Configuration 2: 200MHz, 128MB RAM
➤ Configuration 3: 266MHz, 128MB RAM

Checking Reliability
Determine the level of system stability under heavy or continuous work
loads. You can use LoadRunner to create stress on the system: force the
system to handle extended activity in a compressed time period to simulate
the kind of activity a system would normally experience over a period of
weeks or months.

Checking Hardware or Software Upgrades

Perform regression testing to compare a new release of hardware or software
to an older release. You can check how an upgrade affects response time
(benchmark) and reliability. Application regression testing does not check
new features of an upgrade; rather it checks that the new release is as
efficient and reliable as the older release.

Evaluating New Products

You can run tests to evaluate individual products and subsystems during the
planning and design stage of a product’s life cycle. For example, you can
choose the hardware for the server machine or the database package based
on evaluation tests.

34
 Chapter 3 • Load Test Planning

Identifying Bottlenecks
You can run tests that identify bottlenecks on the system and determine
which element is causing performance degradation, for example, file
locking, resource contention, and network overload. Use LoadRunner in
conjunction with the new network and machine monitoring tools to create
load and measure performance at different points in the system. For more
information, see Part VI, “Monitoring a Scenario.”

?
? ?
?
ISDN WAN

Modem Router

Application Server Database

Clients Server

Measuring System Capacity

Measure system capacity, and determine how much excess capacity the
system can handle without performance degradation. To check capacity,
you can compare performance versus load on the existing system, and
determine where significant response-time degradation begins to occur. This
is often called the “knee” of the response time curve.

Response Time
(seconds)

knee
Unacceptable
Acceptable
Number of Users

Once you determine the current capacity, you can decide if resources need
to be increased to support additional users.

35
Part I • Understanding LoadRunner

36
4
The LoadRunner Controller at a Glance

This chapter introduces the Controller window and explains how to

perform basic scenario operations.

This chapter describes:

➤ Opening the Controller

➤ Introducing the LoadRunner Controller
➤ Managing Scenario Files
➤ Running a Scenario

Opening the Controller

Set up the LoadRunner environment according to the instructions in the
LoadRunner Installation Guide.

To open the Controller:

You can open the Controller from either of following:

➤ Start > Programs > Mercury LoadRunner > Applications > Controller
➤ Start > Programs > Mercury LoadRunner > LoadRunner. Mercury
LoadRunner opens. Select the Load Testing tab, and then click Run Load
Tests.

37
Part I • Understanding LoadRunner

By default, the Controller opens with the New Scenario dialog box. Note
that the New Scenario dialog box will not open on startup if you clear the
Show at Startup check box or choose View > Show New Scenario dialog box
(check mark cleared). To show the New Scenario dialog box at startup, select
Show at Startup or choose View > Show New Scenario dialog box (check
mark displayed).

If the New Scenario dialog box does not open on startup, you can open it by
choosing File > New or by clicking the New button on the Controller
toolbar.

You can select one of two methods to create a scenario: Manual Scenario or
Goal-Oriented Scenario. In a manual scenario, you create the scenario
yourself by defining the number of Vuser groups you want to run, and
building a schedule for LoadRunner to run these groups. You can also create
a manual scenario by defining the total number of Vusers to be used in the
scenario, and assigning a percentage of the total number of Vusers to each

38
 Chapter 4 • The LoadRunner Controller at a Glance

script. If you want to create a scenario using the Percentage Mode, select Use
the Percentage Mode to distribute the Vusers among the scripts.

In a goal-oriented scenario, you define the goals you want your test to
achieve, and LoadRunner automatically builds a scenario for you, based on
these goals.

For instructions on creating a manual scenario, see Chapter 5, “Creating a

Manual Scenario.” For instructions on creating a manual scenario using the
Percentage Mode, see Chapter 6, “Creating a Manual Scenario Using the
Percentage Mode.”

For instructions on creating a goal-oriented scenario, see Chapter 7,

“Creating a Goal-Oriented Scenario.”

To select the script or scripts that you want to use in your scenario:
1 Select a script from the Available Scripts list. By default, the list displays the
fifty most recently used scripts.

Note: You can change the maximum number of scripts displayed in the
Available Scripts list by modifying the following registry key:
HKEY_CURRENT_USER\Software\Mercury Interactive\RecentScripts\
max_num_of_scripts

You can also click the Browse button to locate the script you want to use. To
view the directory path of a script listed in the Available Scripts list, right-
click the script and select Show Paths.
To select a script saved in the Quality Center database, click Quality Center.
To record a new script using VuGen, click Record.

Note: To select a VB Vuser script, browse to locate the .usr file.

2 Click Add to copy the script you selected to the Scripts in Scenario list.
3 Click Remove to remove a script from the Scripts in Scenario list.

39
Part I • Understanding LoadRunner

4 To bypass this dialog box the next time you create a new scenario, clear the
Show at startup check box. You will be able to add scripts later on, while
building your scenario.
5 Click OK to close the dialog box.

Introducing the LoadRunner Controller

The LoadRunner Controller window contains the following elements:

Title bar Displays the name of the scenario on which you are
currently working.

Menu bar Displays the menus from which you select

commands.

Toolbar Provides shortcuts for selecting commands. Clicking

a button executes a command.

Status Bar Displays tool tips for the Controller menu items, as
well as the following, if they are enabled: Quality
Center Connection, IP Spoofer, Auto Collate Results,
Auto Load Analysis, and WAN Emulator.

40
 Chapter 4 • The LoadRunner Controller at a Glance

Design tab Run tab

Scenario Groups pane
(Manual Scenario)

Scenario Schedule pane

(Manual Scenario)

41
Part I • Understanding LoadRunner

The Controller window has two tabs that correspond to two views:

Design view This view displays a list of all the Vuser

groups/scripts in a scenario, the load generator
machines, and the number of Vusers assigned to
each group/script. This view also displays basic
information about the scenario schedule (manual
scenario) or goal (goal-oriented scenario).

Run view Displays information on the running Vusers and

Vuser groups, as well as online monitor graphs.

In addition, if you select View > Show Output, the Controller opens the
Output window which displays error, warning, notification, debug, and
batch messages generated during scenario execution.

Choosing Commands from the Toolbar

You can execute many LoadRunner commands by clicking a button on the
toolbar in the LoadRunner Controller. There are some variations in the
buttons the toolbar displays, depending on whether you are in Design view
or Run view, and depending on whether you are creating a manual scenario
or a goal-oriented scenario.

42
Chapter 4 • The LoadRunner Controller at a Glance

43
Part I • Understanding LoadRunner

Managing Scenario Files

A scenario describes the events that occur during each load testing session.
You create a scenario using the Design view of LoadRunner Controller.

After you create the scenario, LoadRunner saves the information in a

scenario file (.lrs). You use the commands in the File menu to create, open,
save, and close scenario files. Some of these commands are available from
the toolbar.

Creating a New Scenario

The New command creates a completely new scenario. Note that the New
command clears all the information displayed in the Controller windows.
To create a new scenario, choose File > New, or click the New button on the
Controller toolbar.

Opening an Existing Scenario

The Open command opens any existing scenario.

To open an existing scenario:

1 Choose File > Open, or click the Open button. The Open Scenario dialog
box opens.

2 Click a file in the File Name list or type a file name in the File Name box.

44
 Chapter 4 • The LoadRunner Controller at a Glance

3 Click Open. The File Open dialog box closes and the scenario appears in the
LoadRunner Controller.

Saving a Scenario
The Save command saves the current scenario.

To save a scenario:
1 Choose File > Save, or click the Save button. The Save Scenario dialog box
opens the first time you save a scenario.

2 Type a scenario name in the File Name text box. Note that by default,
scenario files have the extension .lrs.
3 Click Save. The scenario is saved in the location you specified.

Closing a Scenario
Closing a scenario closes all the Controller windows. To close the scenario,
choose File > Close. If you made changes to the scenario, a Save Changes
message appears. Choose Yes to save the changes you made. All open
windows and icons in the Controller close.

45
Part I • Understanding LoadRunner

Running a Scenario
Once you have designed your scenario, you are ready to run it. You can
control the Vusers and Vuser groups and monitor their performance online
using the Run view of the LoadRunner Controller.

Design tab Run tab

Scenario Groups pane Online Monitor Scenario Status window

Graphs

46
 Chapter 4 • The LoadRunner Controller at a Glance

During scenario execution, you use the Scenario Groups pane in the Run
view to monitor the actions of all the Vusers and Vuser groups in the
scenario. The Status field of each Vuser group displays the current state of
each Vuser in the group.

You can also manipulate individual Vusers within the Vuser groups you
have defined by selecting a group and clicking the Vusers button. The Vusers
dialog box appears, with a list of the ID, Status, Script, Load Generator, and
Elapsed Time (since the beginning of the scenario) for each of the Vusers in
the group.

In addition, you can view a synopsis of the running scenario in the box in
the upper-right corner of the Run view.

47
Part I • Understanding LoadRunner

Note that you can detach the Scenario Status window from the Run view,
thereby enlarging the Scenario Groups pane.

While the scenario runs, the Vusers and load generators send error,
notification, warning, debug, and batch messages to the Controller. You can
view these messages in the Output window (View > Show Output).

For more information on the Output window, see “Viewing the Output
Window” on page 233.

You use the online monitors and online monitor graphs to monitor Vuser
status, transactions, system resources, database server resources, Web server
resources, Web application server resources, network delay, streaming media
resources, firewall server resources, ERP/CRM server resources, Java
performance, J2EE transaction breakdown, application deployment
resources, middleware performance, application component resources, and
infrastructure resources while running a scenario. For more information on
online monitors, see Chapter 20, “Online Monitoring.”

48
 Part II
Designing a Scenario
50
5
Creating a Manual Scenario

You can build a manual scenario by creating groups and specifying the
scripts, the load generators, and the number of Vusers included in each
group. You can also build a manual scenario using the Percentage Mode,
which allows you to define the total number of Vusers to be used in the
scenario, and assign load generators and a percentage of the total number of
Vusers to each script.

This chapter describes how to create a manual scenario using the Vuser
Group Mode. For information on creating a manual scenario using the
Percentage Mode, see Chapter 6, “Creating a Manual Scenario Using the
Percentage Mode.”

This chapter discusses:

➤ About Creating a Scenario

➤ Creating Vuser Groups
➤ Configuring Vusers in a Vuser Group
➤ Configuring Vuser Run-Time Settings
➤ Configuring Load Generators
➤ Configuring Load Generator Settings
➤ Configuring Terminal Services Settings
➤ Configuring WAN Emulation Settings
➤ Configuring Scripts
➤ Using Relative Paths for Scripts

51
Part II • Designing a Scenario

About Creating a Scenario

To test your system with LoadRunner, you must create a scenario—a file
with information about the test session. The scenario is the means by which
you emulate a real-life user. The scenario contains information about how to
emulate real users: the groups of virtual users (Vusers), the test scripts the
Vusers will run, and the load generator machines upon which to run the
scripts.

If you chose to create a regular manual scenario, each script you selected in
the New Scenario dialog box is assigned to a Vuser group. To each Vuser
group you then assign a number of virtual users. You can instruct all Vusers
in a group to run the same script on the same load generator machine, or
you can assign different scripts and load generators to the various Vusers in
a group.

Once you create your Vuser groups, you select or build a schedule for your
scenario. See Chapter 8, “Scheduling a Scenario” for more information on
creating a scenario schedule.

52
 Chapter 5 • Creating a Manual Scenario

Understanding the New Scenario Dialog Box

The new Scenario dialog box enables you to select scripts for a new scenario.

Selecting the Scenario Type

Select one of the following scenario options:

➤ Manual Scenario: Select this method if you want to build a manual scenario.
You build a manual scenario by creating groups and specifying the script,
the load generator, and the number of Vusers included in each group.
➤ Use the Percentage Mode to distribute the Vusers among the scripts:
Select this option if you want to build a manual scenario by specifying a
number of Vusers to be distributed among the selected Vuser scripts.
➤ Goal Oriented Scenario: Select this method to have LoadRunner build a
scenario for you. In a goal-oriented scenario, you define the goals you want
your test to achieve, and LoadRunner automatically builds a scenario for
you, based on these goals.

53
Part II • Designing a Scenario

Choosing a Script
Select a script from the Available Scripts list. Scripts that have been selected
appear in the Scripts in Scenario pane.

Available Scripts: Displays, by default, a list of the fifty most recently used
scripts.

Note: You can change the maximum number of scripts displayed in the
Available Scripts list by modifying the following registry key:
HKEY_CURRENT_USER\Software\Mercury Interactive\RecentScripts\
max_num_of_scripts

Add: Adds a script to the scenario.

Remove: Removes a script from the scenario.

Browse: Select scripts from a different directory. To select a VB Vuser script,

browse to locate the .usr file.

Record: Opens the Virtual User Generator so that you can begin recording a
script. For more information on recording scripts, see the Mercury Virtual
User Generator User’s Guide.

Quality Center: Opens the Connection to Quality Center dialog box, so that
you can open a connection to a Quality Center project.

Scripts in Scenario: Displays the scripts to be used in the scenario.

Show at startup: When selected, LoadRunner displays the New Scenario

dialog box each time you open the Controller.

54
 Chapter 5 • Creating a Manual Scenario

Creating Vuser Groups

A scenario consists of groups of Vusers that emulate human users interacting
with your application. When you run a scenario, the Vusers generate load
on the server, and LoadRunner monitors the server and transaction
performance.

Vuser groups are used to organize the Vusers in a scenario into manageable
groups. You create Vuser groups that contain Vusers with shared or similar
characteristics. For example, you can create a Vuser group for all Vusers that
run the same Vuser script.

Understanding the Manual Scenario Mode Design Tab

When you create a manual scenario, the Controller displays the Scenario
Schedule and Scenario Groups panes in the Design tab.

55
Part II • Designing a Scenario

The Scenario Schedule pane displays information regarding the schedule

profile: its name, the schedule mode, the duration of the scenario, and the
load behavior. Load Preview displays a graph of the scenario schedule you
defined. For more information on configuring schedule settings, see
“Scheduling a Scenario” on page 151.

The Scenario Groups pane lists all enabled and disabled Vuser Groups, their
paths, the number of Vusers assigned to each group, and the load generator
machines.

You can perform the following actions on a Vuser group or scenario:

➤ Define the Group Name, Vuser Quantity, Load Generator machine(s), and
Script(s) for the Vuser group
➤ Add one or more load generator machines to the Vuser group and configure
the load generator(s)
➤ Add and configure one or more scripts to the Vuser group
➤ Enable or disable a Vuser group for the scenario
➤ Remove a Vuser group from the scenario
➤ Schedule the Vuser group/scenario
➤ Run the scenario
➤ Stop the scenario
➤ Reset the scenario
➤ Configure scenario result settings

56
 Chapter 5 • Creating a Manual Scenario

Adding a Vuser Group

Vuser groups can be created and added to a scenario using the Add Group
dialog box.

To create Vuser Groups:

1 Click the Add Group button to the right of the Scenario Groups pane. The
Add Group dialog box opens:

2 In the Group Name box, enter a name for the Vuser group.
3 From the Vuser Quantity box, select the number of Vusers that you want to
create in the group.
4 Select a load generator from the Load Generator Name list. To use a load
generator that does not appear, select Add from the Load Generator Name
list. The Add New Load Generator dialog box opens:

57
Part II • Designing a Scenario

Type the name of the load generator in the Name box. In the Platform box,
select the type of platform on which the load generator is running.
By default, LoadRunner stores temporary files on the load generator during
scenario execution, in a temporary directory specified by the load
generator’s TEMP or TMP environment variables. To override this default for
a specific load generator, type a location in the Temporary Directory box.
To allow the load generator to take part in the scenario, check Enable load
generator to take part in the scenario.
Click More to expand the dialog box and show the Add Load Generator
tabs. For information on configuring settings for each load generator, see
“Configuring Load Generator Settings” on page 78.
Click OK to close the Add New Load Generator dialog box.
5 Select a script from the script list.
To use a script that does not appear, click Browse. Browse to select the path
and file name of the new script.
6 Click OK to close the Add Group dialog box. The new group’s properties
appear in the Scenario Groups pane.

Understanding the Add Group Dialog Box

Use the Add Group dialog box to insert a new group into the scenario.

Group Name: Enter the name of the new group you want to add. Note that
the name is limited to a maximum of 55 characters.

Vuser Quantity: Select the number of Vusers you want to add to the group.

Load Generator Name: Select the name of the load generator machine for
the new group. Choose a previously existing load generator from the list or
create a new load generator by choosing Add. The Add Load Generator
dialog box opens.

58
 Chapter 5 • Creating a Manual Scenario

Select Script: Displays the available scripts in the current directory. The list
contains all scripts that you previously added to the scenario.

➤ Script Name: Select the script you want the Vuser group you are creating
to use. The script appears in the Script Name column.
➤ Script Path: Displays the script directory’s path.
➤ Browse: Select the path and file name of a script from a different
directory. To use a VB Vuser script, select the .usr file.

Note: When you specify the location of a script, you can specify a location
that is relative to the current scenario directory. For details, see “Using
Relative Paths for Scripts” on page 109.

➤ Record: Opens the Virtual User Generator so that you can begin
recording a script. For more information on recording scripts, see the
Mercury Virtual User Generator User’s Guide.

Note: While a scenario is running, you can add Vuser groups to the scenario
and enable them. However, if you add a Vuser group after all the Vusers in
the scenario have been ramped up, the new group will not run in the
scenario.

59
Part II • Designing a Scenario

Deleting a Vuser Group

To delete a Vuser group, click the Remove Group button to the right of the
Scenario Groups pane, or right-click the Vuser group and select Remove
Group.

Disabling a Vuser Group

By default, all the Vuser groups displayed in the Scenario Groups pane are
enabled to run in the scenario. To disable a Vuser group, click the box to the
left of the Vuser group name. The color of the group changes to gray,
indicating that the group will not take part in the scenario. To re-enable the
Vuser group, select the same box again.

Modifying a Vuser Group from the Scenario Groups Pane

You can modify the script, vuser quantity, and load generator for a Vuser
group directly from the Scenario Groups pane of the Controller, or by using
the Group Information dialog box.

To modify a Vuser Group directly from the Scenario Groups pane:

1 Select the Group Name, Script Path, Quantity, or Load Generator you want
to modify.
2 Enter or select another name or number for the property.
3 To modify a Vuser group script’s run-time settings, click the Run-Time
Settings button to the right of the Scenario Groups pane. For more
information about run-time settings, see “Configuring Scripts” on page 105.
4 To edit a Vuser group’s script, click the View Script button to the right of the
Scenario Groups pane. LoadRunner’s script generation tool, VuGen, opens.
For more information on editing scripts, see the Mercury Virtual User
Generator User’s Guide.

60
 Chapter 5 • Creating a Manual Scenario

Modifying a Vuser Group Using the Group Information Dialog

Box
The Group Information dialog box displays details about a Vuser group, and
lets you modify the settings of a group.

To modify a Vuser Group using the Group Information dialog box:

1 Click the Details button to the right of the Scenario Groups pane, or right-
click the property you want to modify and select Details. The Group
Information dialog box opens.

2 In the Group Name box, enter the Vuser group name.

3 From the Vuser Quantity box, select the number of Vusers that you want to
run in the group.
4 Select a load generator from the Load Generator Name list.
To use a load generator that does not appear, select Add from the Load
Generator Name list and add a new load generator using the Add Load
Generator dialog box.
5 To modify the run-time settings you specified while recording a script using
VuGen, click Run-Time Settings. For more information about run-time
settings, see “Configuring Scripts” on page 105.
6 To edit a Vuser group’s script, click View Script. LoadRunner’s script
generation tool, VuGen, opens. For more information on editing scripts, see
“Configuring Scripts” on page 105.
7 Click OK to close the Group Information dialog box.

61
Part II • Designing a Scenario

Understanding the Group Information Dialog Box

Use the Group Information dialog box to display details about a Vuser
group, and modify the settings of a group.

Group Name: Displays the current group name. To modify the name, type a
new name in the Group Name box.

Load Generator Name: Displays the name of the selected Vuser’s load
generator. To specify a different load generator, select one from the Load
Generator Name list. Select Add from the Load Generator Name list to
specify a new load generator.

Vuser Quantity: Displays the number of Vusers in the group.

Script: Displays details of the selected script.

➤ Name: Displays the name of the script.

➤ Path: Displays the script directory’s path.
➤ Type: Displays the type of script.
➤ View Script: Opens the Virtual User Generator, so that you can edit the
script. For more information on editing scripts, see the Mercury Virtual
User Generator User’s Guide.
➤ Run-Time Settings: Opens the Run-Time Settings dialog box, enabling
you to edit the script run-time settings you previously set using VuGen. If
you did not set run-time settings for a script in VuGen, the default
VuGen settings are displayed for all but the Log and Think Time tabs,
which display the default Controller settings. For information on the
run-time settings, see the VuGen Help.
Refresh: Click this button and select Script to update the script details in the
scenario, if you make any changes to a script while the Controller is
running. Select Run-Time Settings to restore the initial run-time settings, if
you modify the run-time settings from the Controller.

62
 Chapter 5 • Creating a Manual Scenario

More/Less: Reveals/hides the following:

➤ Command Line: Type any command line options to use when running
the script—for example: -x value -y value. For information about passing
command line argument values to a script, refer to the Mercury Virtual
User Generator User’s Guide.
➤ Rendezvous: Displays the rendezvous points defined for the selected
script.
➤ Vusers: Displays all Vusers associated with the selected script.
➤ Files: Displays all files used by the script. To exclude a file from the list,
clear the check box adjacent to it.

Add: Click this button and select Add File or Add Directory. Browse to the
file or directory that you want to add to this list and click Open. The
selected files/directories are added to the files list.

Note: To run Visual C++ Vusers on a remote load generator machine, you
must add the .dll of the Vuser to the Files used by script list.

Sorting Vuser Groups in the Scenario Groups Pane

Once you have created your Vuser groups, you can sort them by group
name, script name, quantity of Vusers assigned to the group, or load
generator name.

To sort Vuser groups:

➤ Select the column by which you want to sort the groups. Click the column
header.
➤ Alternatively, you can right-click anywhere within the column you want to
sort, and select Sort Groups. Choose to sort by name, path, quantity, or
generator.
➤ To instruct the Controller to automatically sort a new Vuser group entry,
right-click the entry and select Auto Sort.

63
Part II • Designing a Scenario

Configuring Vusers in a Vuser Group

You can define properties for individual Vusers within the Vuser groups you
have defined, using the Vusers dialog box. To each Vuser you can assign a
different script and/or load generator machine.

To define properties for individual Vusers:

1 Select the Vuser group whose Vusers you want to modify, and click the
Vusers button to the right of the Scenario Groups pane. The Vusers dialog
box opens.

2 To change the script for an individual Vuser, select a different script in the
Script column. Alternatively, you can click the Details button, and select a
different script from the script list in the Vuser Information dialog box.
3 To change the load generator on which a Vuser runs, select a different load
generator in the Load Generator column. Alternatively, you can click the
Details button, and select a different load generator from the Load
Generator Name list in the Vuser Information dialog box.
To use a load generator that does not appear, select Add from the Load
Generator Name list and add a new load generator using the Add Load
Generator dialog box.

64
 Chapter 5 • Creating a Manual Scenario

Understanding the Vusers Dialog Box

The Vusers dialog box displays the status of the Vusers in the group.

Choose the scenario group from the list at the top of the dialog box.

Show the Selected Vusers: Opens a Run-Time Viewer for each selected Vuser.

Hide the Selected Vusers: Closes the Run-Time Viewers that were opened.

Open Vuser Log: Displays a log containing run-time information about the
Vuser that is refreshed, by default, every 1000 milliseconds.

Close Vuser Log: Closes the Vuser log.

ID: Displays the Vuser’s ID number.

Status: Displays the Vuser’s status. The possible statuses are:

Status Description

Down The Vuser is down.

Pending The Vuser is ready to be initialized and is waiting for an

available load generator, or is transferring files to the load
generator. The Vuser will run when the conditions set in its
scheduling attributes are met.

Initializing The Vuser is being initialized on the remote machine.

Ready The Vuser already performed the init section of the script
and is ready to run.

Running The Vuser is running. The Vuser script is being executed on

a load generator.

Rendezvous The Vuser has arrived at the rendezvous and is waiting to be

released by LoadRunner.

Done.Passed The Vuser has finished running. The script passed.

Done.Failed The Vuser has finished running. The script failed.

Error A problem occurred with the Vuser. Check the Status field
on the Vuser dialog box or the output window for a
complete explanation of the error.

65
Part II • Designing a Scenario

Status Description

Gradual Exiting The Vuser is completing the iteration or action it is running

(as defined in Tools > Options > Run-Time Settings) before
exiting.

Exiting The Vuser has finished running or has been stopped, and is
now exiting.

Stopped The Vuser stopped when the Stop command was invoked.

Script: Displays the script run by the Vuser.

Load Generator: Displays the load generator machine on which the Vuser is
running.

Elapsed Time: Displays the amount of time that has elapsed in the scenario
since the Vuser began running.

Run: Instructs the Controller to begin running the Vuser.

Stop: Instructs the Controller to stop running the Vuser.

Gradual Stop: Instructs the Controller to complete the current iteration or

action before stopping the Vuser. This option is only available when the
Vuser is in the RUN state, if you selected the Wait for the current iteration to
end before exiting or Wait for the current action to end before exiting
options in the Run-Time Settings tab of the Options dialog box.

Reset: Resets the status of the Vuser to Down.

Details: Opens the Vuser Information dialog box.

Add Vusers: Opens the Add Vusers dialog box so that you can add one or
more Vusers.

66
 Chapter 5 • Creating a Manual Scenario

The following additional right-click options are available:

➤ Renumber: Renumbers the Vusers in the group, changing each Vuser ID.
➤ Run-Time Settings: Opens the Run-Time Settings dialog box, enabling
you to edit the script run-time settings you previously set using VuGen. If
you did not set run-time settings for a script in VuGen, the default
VuGen settings are displayed for all but the Log and Think Time tabs,
which display the default Controller settings. For information on the
run-time settings, see the VuGen Help.

Note: Changing the run-time settings for one Vuser changes the run-time
settings for all of the Vusers in the group.

➤ View Script: Opens the Virtual User Generator so that you can edit the
script. For more information on editing scripts, see the Mercury Virtual
User Generator User’s Guide.
➤ Initialize Vuser/s: Distributes the Vuser to its designated load generator so
that it is ready to execute its script. If a Vuser fails to initialize, its status
changes to Error.
➤ Pause: Temporarily pauses the Vuser’s execution of its script.

Note: Pausing a Vuser group will affect its transaction response time.

➤ Show Vuser: Opens the Run-Time Viewer and displays the Vuser
executing its script.
➤ Hide Vuser: Closes the Run-Time Viewer showing the Vuser executing its
assigned script.
➤ Show Vuser Log: Displays a log containing run-time information about
the Vuser that is refreshed, by default, every 1000 milliseconds.
➤ Hide Vuser Log: Closes the Vuser script log.

67
Part II • Designing a Scenario

➤ Filter Vusers: Filters the Vusers displayed in the Vusers dialog box by
status. Note that you can also select the filter option you want to use
from the filter selector at the top of the Vusers dialog box.
➤ Sort Vusers: Sorts the Vusers in the group by ID, Status, Script, Load
Generator, or Elapsed Time.

Understanding the Vuser Information Dialog Box

The Vuser Information dialog box displays details about a specific Vuser in a
group, and lets you modify the load generator and script settings for the
Vuser.

Group Name: Displays the name of the group to which the selected Vuser
belongs.

Vuser Name: Displays the name of the selected Vuser.

Load Generator Name: Displays the name of the selected Vuser’s load
generator. To specify a different load generator, select one from the Load
Generator Name list. Select Add to specify a new load generator.

Select Script: Displays the available scripts in the current directory.

➤ Script Name: Select the script you want the Vuser you selected to use. The
script appears in the Script Name column.
➤ Script Path: Displays the script directory’s path.
➤ Browse: Select a script from a different directory. To select a VB Vuser
script, browse to locate the .usr file.
➤ Record: Opens VuGen so that you can begin recording a script. For more
information on recording scripts, see the Mercury Virtual User Generator
User’s Guide.
➤ Run-Time Settings: Opens the Run-Time Settings dialog box, enabling
you to edit the script run-time settings you previously set using VuGen. If
you did not set run-time settings for a script in VuGen, the default
VuGen settings are displayed for all but the Log and Think Time tabs,
which display the default Controller settings. For information on the
run-time settings, see the VuGen Help.

68
 Chapter 5 • Creating a Manual Scenario

Adding Vusers to a Vuser Group

You add Vusers to a Vuser group and define their properties using the Add
Vusers dialog box.

Note: You can activate additional Vusers while the scenario is running,
using the Run/Stop Vusers dialog box. For more information, see “Manually
Adding Vusers to a Running Scenario” on page 222.

To add Vusers to a Vuser group:

1 In the Vusers dialog box, click the Add Vuser(s) button. The Add Vusers
dialog box opens.

2 From the Group Name box, select the name of the Vuser group.
3 From the Quantity to add box, select the number of Vusers that you want to
add to the group.

69
Part II • Designing a Scenario

4 Select a load generator from the Load Generator Name list.

To use a load generator that does not appear, select Add from the Load
Generator Name list and add a new load generator using the Add Load
Generator dialog box.
5 Select a script from the script list.
To use a script that does not appear, click the Browse button. Browse to
select the path and file name of the new script.
6 Click OK to close the Add Vusers dialog box. The new Vuser’s properties
appear in the Vusers dialog box.

Understanding the Add Vusers Dialog Box

Adds a new Vuser to the Vuser group.

Group Name: Enter the name of the group to which you want to add a
Vuser.

Load Generator Name: Select the name of the load generator machine for
the new Vuser. Choose a previously existing load generator from the list or
create a new load generator by choosing Add. The Add Load Generator
dialog box opens.

Quantity to add: Select the number of Vusers you want to add to the group.

Select Script: Displays the available scripts in the current directory.

➤ Script Name: Select the script you want the Vuser you are creating to use.
The script appears in the Script Name column.
➤ Script Path: Displays the script directory’s path.
➤ Browse: Select a script from a different directory. To use a VB Vuser script,
select the .usr file.

Note: When you specify the location of a script, you can specify a location
that is relative to the current scenario directory. For details, see “Using
Relative Paths for Scripts” on page 109.

70
 Chapter 5 • Creating a Manual Scenario

➤ Record: Opens VuGen so that you can begin recording a script. For more
information on recording scripts, see the Mercury Virtual User Generator
User’s Guide.
➤ Run-Time Settings: Opens the Run-Time Settings dialog box, enabling
you to edit the script run-time settings you previously set using VuGen. If
you did not set run-time settings for a script in VuGen, the default
VuGen settings are displayed for all but the Log and Think Time tabs,
which display the default Controller settings. For information on the
run-time settings, see the VuGen Help.

Note: Modifying the run-time settings for the new Vuser will modify the
run-time settings for all the Vusers in the group. For more information
about run-time settings, see “Configuring Scripts” on page 105.

Configuring Vuser Run-Time Settings

You set the script’s run-time settings to customize the way the Controller
executes a Vuser script. There two ways to display the script run-time
settings:

➤ In the Group Information dialog box, click Run-Time Settings.

➤ In the Controller’s Scenario Groups pane, highlight a group or groups, and
click Run-Time Settings.
The Run-Time Settings dialog box displays the settings you previously set
using VuGen. If you did not set run-time settings for a script in VuGen, the
default VuGen settings are displayed for all but the Log and Think Time
tabs, which display the default Controller settings. Note that several
protocols, such as Web and Java, have specific settings.

For information on each specific run-time setting, refer to the Mercury

Virtual User Generator User’s Guide.

71
Part II • Designing a Scenario

Modifying the run-time settings for the new Vuser will modify the run-time
settings for all the Vusers in the group. If a group contains more than one
Vuser type, then you can modify the shared run-time settings, as described
in “Modifying Run-Time Settings for Multiple Scripts” below.

Note: If you modify the run-time settings from the Controller, LoadRunner
runs the script using the modified settings. To restore the initial settings,
click the Refresh button and select Run-Time Settings.

Modifying Run-Time Settings for Multiple Scripts

When you choose to modify script run-time settings, and you have selected
multiple scripts, or a group with multiple scripts, the Controller displays the
option of modifying the shared run-time settings:

Note: If one of the selected scripts does not support shared run-time
settings, then you will only have the option of modifying each script’s
individual run-time settings. Shared RTS mode will be disabled for GUI or
Astra LoadTest Vusers.

72
 Chapter 5 • Creating a Manual Scenario

Select a method for modifying run-time settings of multiple scripts:

Shared RTS: Opens one window containing all of the run-time settings in
blank mode. In this mode, you set only the options that you would like to
modify for all selected scripts. All other run-time settings remain
unchanged.

Individual RTS: Opens a separate window for each selected script. In this
mode, you modify each script’s settings individually.

Modifying Shared Run-Time Settings

Any settings that you change in shared mode will be applied to all selected
scripts. Any other settings remain unchanged. For example, if a dialog has
checkboxes, they appear in disabled mode, meaning that they are neither
selected nor cleared. If you select or clear a check box, then the change will
apply to all selected scripts.

Some run-time settings cannot be modified in shared mode. These settings

will not appear. To modify them, open the run-time settings for each
individual script.

All Run-Time Setting buttons will be disabled, for example the Change and
Advanced buttons in the Browser Emulation node.

The following nodes will not appear in shared mode:

➤ the Java Environment Settings:Classpath node

➤ the Internet Protocol:ContentCheck node
➤ the Run Logic node - for protocols which support the Run Logic node, the
Iterations box will appear in the Pacing node
➤ the nodes with tables in the format Property, Value for the protocols: Citrix
ICA, Oracle NCA, and WAP, for example, the Oracle NCA:Client Emulation
node

73
Part II • Designing a Scenario

Configuring Load Generators

You can set a load generator’s attributes while adding it to the load generator
list, or modify the attributes of an existing load generator at any time, using
the Load Generators dialog box.

To configure global settings for all load generators participating in the

scenario, use LoadRunner’s Options dialog box. For more information, see
Chapter 10, “Configuring a Scenario.” To set properties specific for each
load generator, use the Load Generators dialog box as described below.

You can also indicate which load generators will run Vusers in the scenario.
For example, if a load generator is unavailable for a particular scenario run,
you can exclude it temporarily instead of removing it entirely from your list
of load generators.

You select which load generators will take part in the scenario by using the
Enable and Disable commands. Disabling a load generator temporarily
removes it from the list. Enabling a load generator reinstates it. Disabling
load generators is particularly useful if you want to isolate a specific
machine to test its performance.

To configure a load generator:

1 Click the Generators button, or select Scenario > Load Generators. The Load
Generators dialog box opens. The Name of the load generator, its Status,
Platform, and Details are displayed.

74
 Chapter 5 • Creating a Manual Scenario

2 Click Connect to change the Status of the load generator from Down to
Ready. When the load generator is connected, the button automatically
changes to Disconnect. To change the Status of the load generator from
Ready to Down, click Disconnect.
3 To disable a load generator, select the load generator and click Disable. The
load generator name changes from blue to gray, and the load generator is
disabled. To enable a load generator, select the load generator and click
Enable. The load generator name changes from gray to blue, and the load
generator is enabled.
4 To view details of a load generator, select the load generator and click
Details. The Load Generator Information dialog box opens with information
about the load generator you selected.

Understanding the Load Generator Dialog Box

The Load Generators dialog box displays information about the load
generators connected to the scenario.

Name: Lists the name of the load generator.

Status: Displays the status of the load generator. The following table
describes the possible statuses of the load generator.

Status Description

Ready The load generator is connected

Connecting The load generator is in the process of connecting

Active The load generator is running Vusers

Down The load generator is not connected

Failed A connection with the load generator could not be

established

Platform: Displays the type of platform on which the load generator is

running.

Details: In the event that the connection fails, displays details about why it
failed.

75
Part II • Designing a Scenario

Connect: Instructs the Controller to connect the load generator for the
scenario. When the load generator is connected, the button automatically
changes to Disconnect.

Add: Opens the Add Load Generator dialog box.

Delete: Deletes the load generator. The load generator can be deleted only
when it is disconnected.

Reset: Attempts to reset a failed connection.

Details: Opens the Load Generator Information dialog box.

Disable/Enable: Instructs the Controller to disable or enable the load

generator. When a load generator is disabled, its Name, Status, Platform, and
Details appear in gray.

Note: The Controller monitors a Windows load generator machine’s CPU

usage and automatically stops loading Vusers on a load generator when it
becomes overloaded. You can monitor the status of a machine’s CPU usage
using the icons in the Load Generator dialog box. When the CPU usage of a
load generator becomes problematic, the icon to the left of the load
generator name contains a yellow bar. When the machine becomes
overloaded, the icon contains a red bar.

76
 Chapter 5 • Creating a Manual Scenario

Adding a Load Generator

You can add load generator machines to your scenario, or modify
information for existing load generators.

To add a load generator, or modify load generator information:

1 Click Add in the Load Generators dialog box. The Add New Load Generator
dialog box opens.

2 In the Name box, enter the name of the load generator.

3 In the Platform box, select the type of platform on which the load generator
is running.
4 In the Temporary Directory box, type a location on the load generator,
where the Controller can store temporary files, or leave empty to accept the
default location. By default, LoadRunner stores temporary files on the load
generator during scenario execution, in a temporary directory specified by
the load generator’s TEMP or TMP environment variables.
5 To allow the load generator to take part in the scenario, check Enable load
generator to take part in the scenario.
6 Click More to expand the dialog box and show the Add Load Generator
tabs. For information on configuring these settings, see “Configuring Load
Generator Settings” on page 78.
7 To remove a load generator, click Delete.
8 Click Close to close the Load Generators dialog box. The load generator
name you entered appears in the Load Generators list; its status is set to
Down.

77
Part II • Designing a Scenario

Understanding the Add New Load Generator Dialog Box

You can add load generator machines to your scenario using the Add New
Load Generator dialog box.

Name: Type the name of the load generator you want to add in the Name
box.

Platform: Select the type of platform on which the load generator is

running.

Temporary Directory: Type a location, on the load generator, where the

Controller can store temporary files. By default,LoadRunner stores
temporary files on the load generator during scenario execution, in a
temporary directory specified by the load generator’s TEMP or TMP
environment variables.

Enable load generator to take part in the scenario: Select to include the load
generator in the scenario.

Configuring Load Generator Settings

You can configure additional settings for individual load generators, using
the tabs in the Add New Load Generator or Load Generator Information
dialog boxes. The settings that can be configured are: Status, Run-Time File
Storage, UNIX Environment, Run-Time Quota, Vuser Limits, Vuser Status,
Terminal Services, Firewall, and WAN Emulation. You can also configure the
Connection Log Settings while working in Expert mode. For information on
the Connection Log tab, see “Working in Expert Mode” on page 423.

You can configure global settings for all load generators participating in the
scenario, using the Options dialog box. For more information, see
Chapter 10, “Configuring a Scenario.”

78
 Chapter 5 • Creating a Manual Scenario

To configure load generator settings:

1 Click the Generators button, or select Scenario > Load Generators to open
the Load Generators dialog box, and then click the Details button. The Load
Generator Information dialog box opens.
You can also configure the settings from the Add New Load Generator dialog
box. Click More to display the settings tabs.
2 Select a tab, and configure the load generator settings.
The settings apply to the load generator specified in the Name box. To
configure a load generator other than the one specified, enter the name and
platform of the load generator in the Name box, or select the load generator
from the Load Generator dialog box.
3 Click OK to close the Load Generator Information or Add New Load
Generator dialog box and save your settings.

Understanding the Load Generator Information dialog Box

The Load Generator Information dialog box enables you to add a load
generator machine to your scenario.

Name: Type the name of the load generator you want to add in the Name
box.

Platform: Select the type of platform on which the load generator is

running.

Temporary directory: Type a location, on the load generator, where the

Controller can store temporary files.

Enable load generator to take part in the scenario: Select to include the load
generator in the scenario.

79
Part II • Designing a Scenario

Status Tab
Select the Status tab to display details of the Load Generator Status.

Load Generator Status: Displays the status of the load generator.

Details: Displays error and other run-time information about the selected
load generator.

80
 Chapter 5 • Creating a Manual Scenario

Run-Time File Storage Tab

Select the Run-Time File Storage tab to specify the result directory for the
performance data that LoadRunner gathers from each load generator during
a scenario.

Scripts and results stored: Select one of the following options:

➤ As defined in Tools > Options> Run-Time File Storage: Stores the results
as specified in the global settings.
➤ In temporary directory on <load generator name>: Instructs the
Controller to save the run-time files (results of the scenario run and Vuser
scripts) on a hard drive of the load generator computer.
➤ On a shared network drive: Instructs the Controller to save the scenario
results and/or the Vuser scripts on a shared network drive. A shared
network drive is a drive to which the Controller and all the load
generators in the scenario have read and write permission.

81
Part II • Designing a Scenario

Note: If the load generator is localhost, then LoadRunner stores the scripts
and results on a shared network drive, and the checkboxes and radio
buttons for setting the location are all disabled.

If you are monitoring over the firewall, the Run-Time File Storage settings
are not relevant.

To set the network location for the results, see Chapter 11, “Preparing to
Run a Scenario.”

UNIX Environment Tab

Select the UNIX Environment tab to configure the login parameters and shell
type for each UNIX load generator.

82
 Chapter 5 • Creating a Manual Scenario

Login as
➤ Name: If the load generator is UNIX-based, set the login information for
the load generator. By default, LoadRunner uses your NT user name for
the UNIX login. In other words, if your NT login is lrunner, the
Controller will log on to the load generator as lrunner. To log on to a
UNIX-based load generator using a different login name, select the Name
check box and specify the desired UNIX login name. Using this option,
you can log on to the NT Controller as bill and connect to the UNIX load
generator as mike. However, you should make sure that mike allows bill
to log on using his name. This can be done by adding the line “+ bill” at
the beginning of mike's .rhosts file.
➤ Use lower case for login names: Instructs LoadRunner to use lower case
names during login to avoid case-sensitive issues with the UNIX
operation system.

Note: For information on the Local User setting available in Expert mode,
see “Working in Expert Mode” on page 423.

Shell Settings: Specify the UNIX shell settings for the remote UNIX load
generator.

➤ Default shell: Select the default shell on the UNIX load generator: csh (C
Shell—the default), bsh (Bourne Shell), or ksh (Korn Shell).

83
Part II • Designing a Scenario

Note: To allow LoadRunner to run your application under the Korn shell,
you first need to make sure that the .profile file contains all of the
LoadRunner environment settings—for example, the M_LROOT definition
and the LicenseManager variable. Your UNIX $M_LROOT/templates
directory contains a template for the .profile file, called dot profile. Use the
template as a guide for modifying your .profile file with the LoadRunner
environment settings.

In addition, if you are using a Korn shell (ksh), you must delete all
LoadRunner settings from the .cshrc file (e.g. M_LROOT) before executing
the scenario.

➤ Initialization command: Enter any command line options for

LoadRunner to use when logging on to a UNIX system. This initialization
command will run as soon as the shell opens. For example, you could
select ksh and use the following initialization command:
. .profile;

Note: If you are monitoring or running Vusers over the firewall, the UNIX
Environment settings are not relevant.

84
 Chapter 5 • Creating a Manual Scenario

Run-Time Quota Tab

Initializing or stopping a large number of Vusers simultaneously places large
stress on a load generator. To reduce stress on a load generator, you can
initialize or stop smaller batches of Vusers.

Select the Run-Time Quota tab to specify the maximum number of Vuser
types that the load generator will initialize or stop simultaneously.

Vuser Quota

➤ Number of Vusers that may be initialized at one time - <current load

generator>: Select the maximum number of Vusers that the current load
generator can initialize simultaneously.
➤ Limit the number of users that may be stopped at one time to: Select the
maximum number of Vusers that the current load generator can stop
simultaneously.
Defaults: Sets the number of Vusers that may be initialized or stopped at one
time to 50.

85
Part II • Designing a Scenario

You can set run-time quotas for an entire scenario using the Run-Time
Settings tab in the Options dialog box. For information on setting quotas
globally for an entire scenario, see Chapter 10, “Configuring a Scenario.”

Vuser Limits Tab

Select the Vuser Limits tab to modify the maximum number of GUI, RTE,
and other Vusers that a load generator can run.

Available Types: Select the type(s) of Vusers you want the load generator to
run.

Maximum Active: Select the maximum number of Vusers of each type for
the load generator to run.

Defaults: Sets GUI-WinRunner to 1, RTE to 1000, and Other Vusers to 5000.

86
 Chapter 5 • Creating a Manual Scenario

Note: The maximum number of active Vusers that you specify must not
exceed the number of Vusers that you are licensed to run. To check your
Vuser licensing limitations, in the Mercury LoadRunner window (Start >
Programs > Mercury LoadRunner > LoadRunner), click License.

Firewall Tab
Select the Firewall tab to enable monitoring or running Vusers over a
firewall.

Enable firewall: Enables LoadRunner to monitor or run Vusers over a

firewall.

87
Part II • Designing a Scenario

Note: If you select the Enable Firewall option, the Temporary directory
option for storing temporary files is disabled. Any location in the Temporary
directory box is erased.

Firewall Settings:

➤ Enable Monitoring over Firewall: Enables LoadRunner to monitor the

load generator machine through a firewall.
➤ Enable running Vusers over Firewall: Enables LoadRunner to run Vusers
on a load generator machine outside the firewall.
MI Listener: Type the name of the MI listener the load generator is using.

Note: If the load generator is connected, you cannot change values in the
Firewall tab. To disconnect a load generator, select the load generator in the
Load Generators dialog box, and click Disconnect. The load generator status
changes to Down, and you can change the settings.

The Firewall tab is disabled if the load generator is Localhost.

88
 Chapter 5 • Creating a Manual Scenario

Vuser Status Tab

Select the Vuser Status tab to view the status of all the Vusers connected to
the selected load generator machine. Note that this tab can only be viewed
when the load generator machine is connected.

GUI/WinRunner: Displays the number of GUI/WinRunner Vusers that are

Pending, Initializing, and Active.

RTE: Displays the number of RTE Vusers that are Pending, Initializing, and
Active.

Other Vusers: Displays the number of Vusers—other than GUI/WinRunner

and RTE Vusers—that are Pending, Initializing, and Active.

Totals: Displays the total number of Vusers that are Pending, Initializing,
and Active.

89
Part II • Designing a Scenario

Configuring Terminal Services Settings

You can use LoadRunner’s Terminal Services Manager to remotely manage
multiple load generators running in your load testing scenario on a terminal
server. In addition, you can use a terminal server to overcome the limitation
of being able to run only a single GUI Vuser on a Windows-based load
generator. By opening a terminal server session for each GUI Vuser, you can
run multiple GUI Vusers on the same application.

About Terminal Services

Terminal services allows centralized management of computing resources
for each client connected to the server, and provides each user with their
own working environment. Using a terminal server client, you can operate
in a server-based computing environment from a remote machine. The
terminal server transmits applications over the network and displays them
via terminal emulation software. Each user logs on and sees only their
individual session, which is managed transparently by the server operating
system, independent of any other client session.

Examine the following diagram to understand how the LoadRunner

components work together during a terminal session.

90
 Chapter 5 • Creating a Manual Scenario

Terminal Services Manager

A terminal server client can have multiple terminal sessions running
simultaneously. Using LoadRunner’s Terminal Services Manager, you can
select the number of terminals to be used in your scenario (provided that
you have sufficient terminal sessions running), and the maximum number
of Vusers that can be run per terminal. The Terminal Services Manager then
evenly distributes the number of virtual users among the client sessions.

To use LoadRunner’s Terminal Services Manager:

➤ Set up the terminal server agent on the Load Generator machine.

➤ Launch a terminal client session on the Controller machine.
➤ Distribute Vusers on the terminal server using the LoadRunner Terminal
Services Manager.

Setting up the Terminal Server Agent

Before you set up the terminal server agent on the Load Generator machine,
make sure that a Load Generator has been installed on the Terminal server
machine. For more information, refer to the LoadRunner Installation Guide.

To set up the Terminal Server Agent on the Load Generator Machine:

1 Stop the LoadRunner agent by right-clicking its icon in the system tray and
selecting Close.
2 Run Agent Configuration from
Start > Programs > Mercury LoadRunner > Advanced Settings, or run
<LR>\launch_service\bin\AgentConfig.exe. The Agent Configuration
dialog box opens.

91
Part II • Designing a Scenario

3 Select the Enable Terminal Services check box. If you are also running or
monitoring Vusers over a firewall, select the Enable Firewall Agent check
box, and then click Settings. See “Agent Configuration Settings” on
page 266 for information on configuring the agent settings.
Click OK.
4 Restart the LoadRunner agent as a process by double-clicking the shortcut
on the desktop, or from
Start > Programs > Mercury LoadRunner > LoadRunner Agent Process.

Note: For more information about the LoadRunner Agent, refer to “Working
With the LoadRunner Agent” on page 458.

92
 Chapter 5 • Creating a Manual Scenario

Launching a Terminal Client Session

A terminal services client must be installed on the Controller machine
before you can launch a terminal client session. For more information on
installing a terminal services client, refer to the installation documentation
for your Terminal server.

To open a Terminal Client session on the Controller machine:

1 Select Start > Programs > Terminal Services Client >
Terminal Services Client. The Terminal Services Client dialog box opens.

2 In the Server box, type the name or IP address of a terminal server, or select
a terminal server from the list of available servers.
3 In the Screen Area box, select a window size for the terminal client.

93
Part II • Designing a Scenario

4 Click Connect. The Windows logon dialog box opens.

5 Enter your username, password, and domain name (if required) for the
terminal server, and then click OK. A terminal client window opens.
6 Repeat steps 1 and 2 to open the number of sessions required.

Note: You must open a terminal server client session for each terminal that
you want to run Vusers on during the scenario.

94
 Chapter 5 • Creating a Manual Scenario

Distributing Vusers on the Terminal Server

Select the Terminal Services tab to distribute Vusers running in your load
testing scenario on a terminal server.

Name: The name of the Terminal server. You only need to add the name of
the terminal server to the Load Generators list once, regardless of the
number of instances that you intend to run.

Platform: The type of platform on which the load generator is running.

Temporary Directory: Type a location, on the load generator, where the

Controller can store temporary files. By default,LoadRunner stores
temporary files on the load generator during scenario execution, in a
temporary directory specified by the load generator’s TEMP or TMP
environment variables.

Enable Terminal Services Manager: Enables the Terminal Services settings to

be applied to load generator running on the terminal server.

95
Part II • Designing a Scenario

Number of terminals: Enter the number of terminals that you want to use in
your load test. Note that you must open a terminal client session for each
terminal that you want to run Vusers on during the scenario.

Maximum number of Vusers per terminal: Enter the maximum number of

Vusers that you want to run on each terminal. The maximum number of
Vusers per terminal depends on the Vuser type used in the script.

Defaults: Sets the number of terminals to two, and the maximum number of
Vusers per terminal to 50.

Troubleshooting
Check the connection between the Controller and the load generator on the
terminal server. In the Controller, select the load generator in the Load
Generators dialog box, and click Connect. The status changes from Down to
Ready when the load generator is connected.

If there is no connection, check that the LoadRunner agent icon appears in

the system tray of the terminal server. This indicates that the agent is
running. Restart the LoadRunner agent if necessary from
Start > Programs > Mercury LoadRunner > LoadRunner Agent
Service/Process.

96
 Chapter 5 • Creating a Manual Scenario

Configuring WAN Emulation Settings

You can emulate the behavior of a wide variety of network infrastructures in
your load testing scenario using the Shunra WAN Emulator. WAN emulation
provides the ability to simulate and test the effects of Wide Area Networks
on end-user response times and performance prior to deployment.

About WAN Emulation

WAN emulation enables you to accurately test point-to-point performance
of WAN-deployed products under real-world network conditions in your test
environment. By introducing highly probable WAN effects such as latency,
packet loss, link faults, and dynamic routing effects over your LAN, you can
characterize many aspects of the WAN cloud and efficiently control your
emulation in a single network environment. You can observe the effects of
your emulation settings on the network performance in the WAN emulation
monitoring reports.

Note: WAN Emulation is only available for load generators running on a

Windows platform. The WAN Emulation tab is disabled for load generators
running on a UNIX platform.

97
Part II • Designing a Scenario

Setting up the WAN Emulator

To use the Shunra WAN Emulator, you must first install the WAN Emulator
Driver on the Load Generator machine from the LoadRunner installation
CD. For instructions, refer to the LoadRunner Installation Guide.

Note: WAN Emulation requires a special license. Contact Mercury’s

Customer Support Web site (http://support.mercuryinteractive.com) for
licensing information.

Configuring the WAN Emulator

Select the WAN Emulation tab to configure WAN emulation settings for your
load test from the Controller machine.

98
 Chapter 5 • Creating a Manual Scenario

Enable WAN Emulation on Load Generator: Select the check box to enable
WAN emulation to start automatically on scenario execution.

Set Predefined Profile: Select a profile with predefined latency and packet
loss settings. The following profile settings are available:

➤ No Profile: This is the default setting. No profile has been selected, or a

predefined profile has been changed manually. Latency Value: 0ms.
Packet Loss Value: 1%.
➤ Metropolitan Area Network link: Emulates a metropolitan area network
link. Latency Value: 20ms. Packet Loss Value: 1%.
➤ Mainland Low Congestion link (Terrestrial): Emulates a mainland
terrestrial link with low network traffic congestion. Latency Value: 40ms.
Packet Loss Value: 1%.
➤ Mainland Congested link (Terrestrial): Emulates a mainland terrestrial
link with high network traffic congestion. Latency Value: 100ms. Packet
Loss Value: 3%.
➤ Transatlantic Low Congestion link (Terrestrial): Emulates an overseas
terrestrial link with low network traffic congestion. Latency Value: 60ms.
Packet Loss Value: 1%.
➤ Transatlantic Congested link (Terrestrial): Emulates an overseas terrestrial
link with high network traffic congestion. Latency Value: 120ms. Packet
Loss Value: 3%.
➤ Transatlantic Low Congestion link (Satellite): Emulates a satellite link
with low network traffic congestion. Latency Value: 280ms. Packet Loss
Value: 1%.
➤ Transatlantic Congested link (Satellite): Emulates a satellite link with
high network traffic congestion. Latency Value: 400ms. Packet Loss
Value: 3%.

99
Part II • Designing a Scenario

Latency: Displays a value representing the time, in milliseconds, that it takes

an IP packet to cross the WAN. This is usually effected by the geographical
distance, the available bandwidth, the network load on the route between
the two ends, and whether this is a terrestrial link or not. The default setting
is 0ms. To set a latency value manually, move the Latency slider to the
desired setting or enter a value in the Latency Value box. The default range is
0-400ms.

Note: To extend the WAN emulation latency range to a maximum of

8000ms, open the wlrun7.ini file in a text editor, and enter the desired
maximum value in the following format. For example:
[WAN_Emulation]
MaxLatency=1000

Packet Loss: Displays a value representing the chance of losing IP packets

while data travels through a WAN. Packets can get lost due to link faults or
due to extreme network load. The default setting is 1%. To set packet loss
manually, move the Packet Loss slider to the desired setting.

Apply All: Applies the WAN emulation settings to all load generators listed in
the Load Generators dialog box.

Exclude Hosts: Opens the Exclude Hosts dialog box enabling you to exclude
certain host names or IP addresses from the emulated WAN. For a list of
situations where hosts should be excluded from the emulated WAN, see
“Excluding Hosts from WAN Emulation” on page 103.

Advanced: Opens the WAN Emulation Advanced Options dialog box. For
more information on advanced options, see “Configuring the WAN
Emulation Advanced Options” on page 101.

Defaults: Restores the default settings.

100
 Chapter 5 • Creating a Manual Scenario

Note: You cannot change WAN emulation settings while a load generator is
connected. To disconnect a load generator, select the load generator in the
Load Generators dialog box, and click Disconnect. The load generator status
changes to Down, and you can then change the settings.

WAN emulation is disabled if the load generator is Localhost.

Configuring the WAN Emulation Advanced Options

You can set packet reordering, packet duplication, packet fragmentation, bit
errors, and link disconnections from the WAN Emulation Advanced
Options. To set advanced options, click the Advanced button in the WAN
Emulation tab.

101
Part II • Designing a Scenario

Note: By default, all the options are enabled. To adjust an option setting,
move the slider to the desired value. The profile values are displayed
beneath the setting range.

Packet Reordering: The chance of a packet order changing while it travels

through the WAN cloud. The default setting is 1%.

Packet Duplication: The chance of a packet duplication occurring while it

travels through the WAN cloud. Count is the number of copies of each
packet that will be created when duplication occurs. Default Chance setting
is 1%. Default Count setting is 1.

Packet Fragmentation: The chance of a packet fragmentation occurring (due

to a short Maximum Transmission Unit) while it travels through the WAN
cloud. MTU is the largest size packet or frame (specified in bytes), that can
be sent in a packet- or frame-based network such as the internet. Default
Chance setting is 1%. Default MTU setting is 512 Bytes.

Bit Errors: The frequency at which the emulator toggles one bit. Bit toggling
occurs every time the indicated number of bits has crossed the WAN cloud.
Default Chance setting is 100,000 Bits.

Link Disconnection: The chance (average frequency) of a network

disconnection occurring while a packet travels through the WAN cloud, and
the disconnection time span. Default Chance setting is one disconnection
every 256 seconds. Default Duration is 1 second.

Defaults: Restores the default settings.

102
 Chapter 5 • Creating a Manual Scenario

Excluding Hosts from WAN Emulation

In some situations you may want to exclude certain hosts from the WAN
emulation. You can do this by setting the WAN emulator to refrain from
affecting traffic to specified hosts. Network traffic which is not affected by
the emulation will not suffer any WAN effects and will not be included in
the WAN emulation monitoring reports.

Examples of situations where you should exclude hosts from an emulated

WAN include the following:

➤ In a Multiprotocol scenario that includes a Web server and a database server;

where information from the database server is not required as a part of the
load test.
➤ Where a user runs and stores scripts on a shared network drive.
➤ Where the Controller is running or monitoring Vusers over a firewall using
the TCP configuration. If the MI Listener is on a machine other than the
Controller, the MI Listener machine should be excluded.
➤ Where the Controller is running or monitoring Vusers over a firewall using
the HTTPS configuration. The IP address of the proxy server should be
excluded.

Understanding the Exclude Hosts Dialog Box

Select Exclude Hosts from the WAN Emulation tab in the Load Generator
Information dialog box to exclude specific hosts from the WAN emulation.

103
Part II • Designing a Scenario

Add: Opens the Add Host dialog box. Enter the name or IP address of the
machine you want to exclude from WAN emulation.

Note: You do not need to exclude the Controller machine and the network
file server (if you have the Network Installation configuration), as they are
automatically excluded from the emulated WAN.

Edit: Select the host name or IP address that you want to modify in the
Exclude Hosts list, and make changes to the host in the Edit Hosts dialog
box.

Remove: Removes an host name or IP address from the Exclude Hosts list.

Note: If you type the name of a machine, LoadRunner resolves the name
and replaces it with the machine’s IP address in the Exclude Hosts list.

Stopping and Starting WAN Emulation

You can stop and start WAN emulation at any time during a scenario run.

To stop or start WAN emulation during scenario execution:

1 To stop WAN emulation, select Scenario > Stop WAN Emulation.
2 To start WAN emulation, select Scenario > Start WAN Emulation.

104
 Chapter 5 • Creating a Manual Scenario

Configuring Scripts
Once you select a script for a Vuser or Vuser group, you can edit the script,
or view the details of the script you selected, from the Vusers or Group
Information dialog boxes.

To edit and view the details of a script used by a Vuser group:

1 Select the Vuser group whose script you want to modify, and click the
Details button to the right of the Scenario Groups pane, or right-click the
Vuser group and select Details. The Group Information dialog box opens
displaying the current Name, Path, and Type of the script.

2 Click Run-Time Settings to set the script’s run-time settings (optional). For
details, see “Configuring Vuser Run-Time Settings” on page 71.

Note: If you modify the run-time settings from the Controller, LoadRunner
runs the script using the modified settings. To restore the initial settings,
click the Refresh button and select Run-Time Settings.

3 To edit the script, click View Script. The script generation tool, VuGen,
opens. For more information on editing scripts, see the Mercury Virtual User
Generator User’s Guide.

105
Part II • Designing a Scenario

Note: If you use VuGen to make changes to a script while the Controller is
running, click the Refresh button and select Script to update the script
details in the scenario.

4 Click More to expand the Group Information dialog box and view
additional script information.

5 In the Command Line box, type any command line options to use when
running the script. For example: -x value -y value
For information about passing command line argument values to a script,
refer to the Mercury Virtual User Generator User’s Guide.
6 To see the rendezvous points included in the selected script, click the
Rendezvous tab.

106
 Chapter 5 • Creating a Manual Scenario

7 To see the list of Vusers associated with the selected script, click the Vusers
tab.

If you have not yet created Vusers, the box will be empty.
8 To see the list of files used by the script, click the Files tab.

By default, this list shows all files in the script’s directory (only after your
script has been added to the script list). These files include the configuration
settings file, the init, run, and end portions of the script, the
parameterization definitions file, and the .usr file. To add a file to the list,
click Add and add the file name. You can delete the files that you add, but
not the other files listed.

Note: To run Visual C++ Vusers on a remote load generator machine, you
must add the .dll of the Vuser to the Files used by script list.

107
Part II • Designing a Scenario

9 Click OK to close the Group Information dialog box.

To edit and view the details of a script used by an individual Vuser:

1 Click the Vusers button to the right of the Scenario Groups pane. The Vusers
dialog box opens.

2 To view details of a script, click Details. The script’s name and path are
displayed in the Vuser Information dialog box. To select a different script,
click the Browse button and select the path and file name of the new script.
To select a VB Vuser script, browse to locate the .usr file.

Note: When you specify the location of a script, you can specify a location
that is relative to the current scenario directory. For details, see “Using
Relative Paths for Scripts” on page 109.

3 To edit a script, right-click the script in the Vusers dialog box, and select
View Script. The script generation tool, VuGen, opens. For more
information on editing scripts, see the Mercury Virtual User Generator User’s
Guide.

108
 Chapter 5 • Creating a Manual Scenario

4 To modify the run-time settings you specified while recording a script using
VuGen, right-click the script in the Vusers dialog box, and select Run-Time
Settings. Note that modifying the run-time settings for one Vuser will
modify the run-time settings for all the Vusers in the group that are using
the same script.
If you highlight more than one script, you can modify the run-time settings
in shared mode, as described in “Modifying Run-Time Settings for Multiple
Scripts” on page 72.

For details about each run-time setting, see the Mercury Virtual User Generator
User’s Guide.

Using Relative Paths for Scripts

When you specify the location of a script, you can specify a relative
location. The location can be relative to the current scenario directory, or
the LoadRunner installation directory.

You can specify a path relative to the current scenario directory by typing
either of the following notations at the start of the script path:

.\ indicates that the path is relative to the location of the

scenario directory.
..\ indicates that the path is relative to the location of the
parent directory of the scenario directory.

For example, if the current scenario is located at F:\scenarios, to specify a

script located at F:\scenarios\scripts\user1.usr, you could type:

.\scripts\user1.usr

109
Part II • Designing a Scenario

You can specify a path relative to the LoadRunner installation directory by

typing a percent sign (%) at the beginning of the script path. For example, if
the LoadRunner installation directory is located at F:\LoadRunner, to specify
a script located at F:\LoadRunner\scripts\user1.usr, you could type:

%\scripts\user1

Note: When specifying a relative path, you can include standard DOS
notation (.\ and ..\) inside the path, as shown in the following example:
M:\LR\my_tests\..\..\test.usr.

When you run a scenario, by default, the script is copied to a temporary

directory on the Vuser group machine. This enables the Vuser group load
generator to access the script locally instead of over a network.

You can instruct the Controller to store the script on a shared network drive
(see Chapter 10, “Configuring a Scenario”). If you configure the Controller
to save the script to a network drive, you must ensure that the Vuser load
generator recognizes the drive. The Script window contains a list of all the
Vuser scripts and their paths. A script’s path is based on the Controller load
generator’s mapping of that location. If a Vuser load generator maps to the
script’s path differently, path translation is required. Path translation
converts the Controller load generator’s mapping to the Vuser load
generator’s mapping. For more information see Appendix B, “Performing
Path Translation.”

110
6
Creating a Manual Scenario Using the
Percentage Mode

You build a manual scenario in the Percentage Mode by defining the total
number of Vusers to be used in the scenario, and assigning load generators
and a percentage of the total number of Vusers to each script. This chapter
describes how to create a manual scenario in the Percentage Mode.

This chapter discusses:

➤ About Creating a Manual Scenario Using the Percentage Mode

➤ Defining the Total Number of Vusers
➤ Assigning Properties to Scripts
➤ Configuring Scripts
➤ Converting a Scenario to the Vuser Group Mode

About Creating a Manual Scenario Using the Percentage

Mode
When you design a regular manual scenario, you create Vuser groups, assign
them scripts, load generator machines, and virtual users. When you work in
the Percentage Mode, you define the total number of Vusers to be used in
the scenario, and assign load generators and a percentage of the total
number of Vusers to each script.

111
Part II • Designing a Scenario

When you create a new scenario, you can access the Percentage Mode
directly by selecting Use the Percentage Mode to distribute the Vusers
among the scripts in the New Scenario dialog box. You can also convert a
scenario created in the Vuser Group Mode to the Percentage Mode by
selecting Scenario > Convert Scenario to the Percentage Mode.

When converting your scenario from Vuser Group Mode to Percentage

Mode, note the following:

➤ If you defined multiple scripts for a Vuser group, the number of Vuser scripts
created in the Percentage Mode will equal the number of scripts defined for
the group.
➤ <All Load Generators> will be assigned to all Vuser scripts created in the
Percentage Mode. If you defined multiple load generators for a Vuser group,
the Vusers you assign to the script(s) in the Percentage Mode will be
distributed evenly among the load generators you previously assigned to the
group.
➤ All Vuser group schedule settings will be lost. All profiles will contain
scenario schedule settings only.

112
 Chapter 6 • Creating a Manual Scenario Using the Percentage Mode

Understanding the Percentage Mode Design Tab

When you create a manual scenario using the percentage mode, the
Controller displays the Scenario Schedule and Scenario Scripts panes in the
Design tab.

The Scenario Schedule pane displays information regarding the schedule

profile: its name, the schedule mode, the duration of the scenario, the load
behavior, and total number of Vusers to be used in the scenario. Load
Preview displays a graph of the scenario schedule you defined. For more
information on configuring schedule settings, see “Scheduling a Scenario”
on page 151.

The Scenario Scripts pane lists all enabled and disabled Vuser scripts, their
paths, the load generator machines, and the percentage of the total number
of Vusers assigned to each script.

113
Part II • Designing a Scenario

You can perform the following actions on a Vuser script or scenario:

➤ Define the total number of Vusers to be used in the scenario

➤ Define the Script Name, Script Path, Load Generator machine(s), and
percentage of the total number of Vusers for the Vuser script
➤ Add one or more load generator machines to the Vuser script and configure
the load generator(s)
➤ Add a new script to the scenario and configure it
➤ Enable or disable a Vuser script for the scenario
➤ Remove a Vuser script from the scenario
➤ Schedule the scenario
➤ Run the scenario
➤ Stop the scenario
➤ Reset the scenario
➤ Configure scenario result settings

Defining the Total Number of Vusers

When you build a scenario in the Percentage Mode, you define a total
number of Vusers to be used in the scenario, rather than a number of Vusers
per script. You enter this number in the Scenario Schedule pane.

114
 Chapter 6 • Creating a Manual Scenario Using the Percentage Mode

For information on creating a scenario schedule, see Chapter 8, “Scheduling

a Scenario.” Note that the Vuser Group settings are not available for the
Percentage Mode.

Assigning Properties to Scripts

The Scenario Scripts pane displays a list of scripts you selected in the New
Scenario dialog box, or defined in the Vuser Group Mode.

The % column indicates the percentage of the total number of Vusers that is
automatically distributed to each Vuser script. During scenario execution,
each script runs the percentage of Vusers assigned to it. The Load Generators
column automatically contains <All Load Generators> for each Vuser script.

Note: If you defined multiple load generators for a Vuser group, the Vusers
you assign to the script(s) in the Percentage Mode will be distributed evenly
among the load generators you previously assigned to the group.

115
Part II • Designing a Scenario

For each script you can modify:

➤ the percentage of the total number of Vusers assigned to the script

➤ the load generator(s) on which the Vusers will execute the script

To modify the percentage of Vusers assigned to a script:

In the script’s % column, enter a percentage of the total number of Vusers
you defined in the Scenario Schedule pane. The percentages assigned to the
other scripts change to create a total of 100 percent for all of the Vuser
scripts.

To add or modify load generator(s) for a script:

1 In the script’s Load Generators column, select one or more machine(s) from
the Load Generator Name list, and click OK. If you select multiple machines,
the Vusers assigned to the script are distributed evenly among the load
generators.
2 Alternatively, you can choose Add to add a load generator to the list. The
Add New Load Generator dialog box opens:

3 Type the name of the load generator in the Name box.

4 In the Platform box, select the type of platform on which the load generator
is running.
5 In the Temporary Directory box, type a location on the load generator,
where the Controller can store temporary files, or leave empty to accept the
default location. By default, LoadRunner stores temporary files on the load
generator during scenario execution, in a temporary directory specified by
the load generator’s TEMP or TMP environment variables.
6 To allow the load generator to take part in the scenario, check Enable load
generator to take part in the scenario.

116
 Chapter 6 • Creating a Manual Scenario Using the Percentage Mode

7 Click More to expand the dialog box and show the Add Load Generator
tabs. For information on configuring settings for each load generator, see
“Configuring Load Generator Settings” on page 78.
8 Click OK to close the Add Load Generator dialog box. LoadRunner adds the
new load generator to the Load Generator Name list. To include the new
load generator in your scenario, select it from the Load Generator Name list,
and click OK.
Repeat the above procedure for each load generator you want to add to your
scenario.

Note: The Controller monitors a Windows load generator machine’s CPU

usage and automatically stops loading Vusers on the overloaded load
generator, and distributes them among other load generators taking part in
the scenario. For more information, see “Load Balancing” on page 138.
You can monitor the status of a machine’s CPU usage using the icons in the
Load Generators dialog box. When the CPU usage of a load generator
becomes problematic, the icon to the left of the load generator name
contains a yellow bar. When the machine becomes overloaded, the icon
contains a red bar.

Configuring Load Generators

You can set a load generator’s attributes while adding it to the load generator
list, or modify the attributes of an existing load generator at any time, using
the Load Generators dialog box. You can also use the Load Generators dialog
box to indicate which load generators will run Vusers in the scenario. For
example, if a load generator is unavailable for a particular scenario run, you
can use the Load Generators dialog box to exclude it temporarily instead of
removing it entirely from your list of load generators. For instructions on
using the Load Generators dialog box, see “Understanding the Load
Generator Dialog Box” on page 75.

To configure global settings for all load generators participating in the

scenario, use LoadRunner’s Options dialog box. For more information, see
Chapter 10, “Configuring a Scenario.”

117
Part II • Designing a Scenario

Configuring Scripts
You can add a script to the Scenario Scripts list using the Add Script dialog
box. Once you have added the script to the list, you can view the details of
the script you selected, edit the script, enable/disable it, or change its run-
time settings.

To add a script:
1 Click the Add Script(s) button to the right of the Scenario Scripts window,
or right-click within a column and select Add Script. The Add Script dialog
box opens.

2 Click Browse. The Open Test dialog box opens.

Select the path and file name of the new script.

Note: When you specify the location of a script, you can specify a location
that is relative to the current scenario directory. For details, see “Using
Relative Paths for Scripts” on page 109.

3 Click Open to select the files. The Open Test dialog box closes, and the new
script name appears in the Add Script dialog box.

118
 Chapter 6 • Creating a Manual Scenario Using the Percentage Mode

4 Click OK to close the Add Script dialog box and enter the new script
information in the Scenario Scripts window.

Understanding the Add Script Dialog Box

The Add Script dialog box enables you to add scripts to your scenario.

Select Script: Displays the available scripts in the current directory.

➤ Script Name: Click the script you want to add to your scenario. The script
appears in the Script Name column.
➤ Script Path: Displays the script directory’s path.
➤ Browse: Select a script from a different directory. To select a VB Vuser
script, browse to locate the .usr file.
➤ Record: Opens the Virtual User Generator so that you can begin
recording a script. For more information on recording scripts, see the
Mercury Virtual User Generator User’s Guide.

Note: While a scenario is running, you can add Vuser scripts to the scenario
and enable them. However, if you add a script after all the Vusers in the
scenario have been ramped up, the new script will not run in the scenario.

119
Part II • Designing a Scenario

Viewing Script Information

Once you have added a script to the list, you can view the details of the
script you selected, edit the script, enable/disable it, or change its run-time
settings.

To view script details:

1 Select the script and click the Details button to the right of the Scenario
Scripts window, or right-click the script and select Details. The Script
Information dialog box opens, displaying the Path, Name, and Type of the
script you selected.

2 Click Run-Time Settings to set the script’s run-time settings (optional),

which allows you to customize the way the Controller executes a Vuser
script. The Run-Time Settings dialog box opens, displaying the settings you
previously set using VuGen.

Note: If you modify the run-time settings from the Controller, LoadRunner
runs the script using the modified settings. To restore the initial settings,
click Refresh and select Run-Time Settings.

3 To edit the script, click View Script. The script generation tool, VuGen,
opens. For more information on editing scripts, see the Mercury Virtual User
Generator User’s Guide.

120
 Chapter 6 • Creating a Manual Scenario Using the Percentage Mode

Note: If you use VuGen to make changes to a script while the Controller is
running, click Refresh and select Script to update the script details in the
scenario.

4 Click More to expand the Script Information dialog box and view additional
script information.

5 In the Command Line box, type any command line options to use when
running the script. For example: -x value -y value
For information about passing command line argument values to a script,
refer to the Mercury Virtual User Generator User’s Guide.
6 To see the rendezvous points included in the selected script, click the
Rendezvous tab.
7 To see the list of Vusers associated with the selected script, click the Vusers
tab.

121
Part II • Designing a Scenario

8 To see the list of files used by the script, click the Files tab. By default this list
shows all files in the script’s directory (only after your script has been added
to the script list). These files include the configuration settings file, the init,
run, and end portions of the script, the parameterization definitions file,
and the .usr file. To add a file to the list, click Add and add the file name.
Note that you can delete the files that you add, but not the other files listed.
9 Click OK to close the Script Information dialog box.

To delete a script:
Select the script and click the Remove Script button to the right of the
Scenario Scripts window, or right-click the script and select Remove Script.

To disable a script
Click the box to the left of the Vuser script name. The color of the script
entry changes to gray, indicating that the script will not take part in the
scenario. To re-enable the Vuser script, click the same box again.

Understanding the Script Information Dialog Box

Lets you view the details of a selected script and modify its settings.

Script: Displays details of the selected script.

➤ Name: Displays the name of the selected script. To modify the name,
type the modified name in the Name box.
➤ Path: Displays the script directory’s path.
➤ Type: Displays the type of the selected script.
➤ View Script: Opens the Virtual User Generator, so that you can edit the
script. For more information on editing scripts, see the Mercury Virtual
User Generator User’s Guide.
➤ Run-Time Settings: Opens the Run-Time Settings dialog box, enabling
you to edit the script run-time settings you previously set using VuGen.
For information on the run-time settings, see the VuGen Help.

122
 Chapter 6 • Creating a Manual Scenario Using the Percentage Mode

Refresh: Click this button and select Script to update the script details in the
scenario, if you make any changes to a script while the Controller is
running. Select Run-Time Settings to restore the initial run-time settings, if
you modify the run-time settings from the Controller.

More/Less: Reveals/hides the following:

➤ Command Line: Type any command line options to use when running
the script—for example: -x value -y value. For information about passing
command line argument values to a script, refer to the Mercury Virtual
User Generator User’s Guide.
➤ Rendezvous: Displays the rendezvous points defined for the selected
script.
➤ Vusers: Displays all Vusers associated with the selected script.
➤ Files: Displays all files used by the script. To exclude a file from the list,
select the check box adjacent to it. To add a file to the list, click Add.

Converting a Scenario to the Vuser Group Mode

You can convert a scenario created in the Percentage Mode to the Vuser
Group Mode by selecting Scenario > Convert Scenario to the Vuser Group
Mode.

Note: You can also convert a scenario in the Vuser Group Mode to the
Percentage Mode. For more information, see “About Creating a Manual
Scenario Using the Percentage Mode” on page 111.

LoadRunner displays a warning that you are about to convert your Manual
scenario from Vuser Group Mode to Percentage Mode, or vice versa. If you
want to convert your scenario, click Yes. If you want to remain in the
current mode, click No.

123
Part II • Designing a Scenario

Always show this dialog box before converting the scenario: Clear this box
if you do not want to be prompted with the current warning. To restore the
current warning, select Scenario > Show Convert Scenario Warning.

When converting your scenario from Percentage Mode to Vuser Group

Mode, note the following:

➤ Each script will be converted to a Vuser group.

➤ If you defined multiple load generators for a Vuser script, the Vuser group
that is created when converting the scenario will also contain multiple load
generators.
➤ All schedule settings will be kept.

124
7
Creating a Goal-Oriented Scenario

You build a goal-oriented scenario for an application by defining the goals

you want your test to achieve. This chapter describes how to create a goal-
oriented scenario.

This chapter discusses:

➤ About Planning a Goal-Oriented Scenario

➤ Understanding the Goal-Oriented Scenario Design Tab
➤ Defining Scenario Goals
➤ Assigning Properties to Scripts
➤ Configuring Scripts

About Planning a Goal-Oriented Scenario

In a goal-oriented scenario, you define the goals you want your test to
achieve, and LoadRunner automatically builds a scenario for you based on
these goals. You can define five types of goals in a goal-oriented scenario:
the number of virtual users, the number of hits per second (Web Vusers
only), the number of transactions per second, the number of pages per
minute (Web Vusers only), or the transaction response time you want your
scenario to reach. You define one of these scenario goals using the Edit
Scenario Goal dialog box. For more information on this dialog box, see
“Defining Scenario Goals” on page 130.

125
Part II • Designing a Scenario

Note: To run a Transactions per Second or Transaction Response Time goal

type, your script must contain transactions. For each of these goal types, you
define the transaction in your script that you want to test.

Virtual Users Goal Type

If you want to test how many Vusers your application can run
simultaneously, it is recommended that you define a Virtual Users goal type.
Running this type of goal-oriented scenario is similar to running a manual
scenario. For more information on defining this goal type, see “Defining
Scenario Goals” on page 130.

Pages per Minute and Hits/Transactions per Second Goal Types

If you want to test the strength of your server, it is recommended that you
define a Hits per Second, Pages per Minute, or Transactions per Second goal
type. Specify a minimum-maximum range of Vusers for LoadRunner to run,
and a Transaction Name for the Transactions per Second goal type.

The Controller attempts to reach the goal you defined using a minimum
number of Vusers. If it cannot reach this goal using the minimum number
of Vusers, the Controller increases the number of Vusers until the maximum
number you defined is reached. If your goal cannot be reached with the
maximum number of Vusers you specified, increase this number and
execute your scenario again. For more information regarding the formula
used by the Controller in running the Pages per Minute and
Hits/Transactions per Second goal types, see “Understanding the
Hits/Transactions per Second and Pages per Minute Goal Types” on
page 135.

126
 Chapter 7 • Creating a Goal-Oriented Scenario

Transaction Response Time Goal Type

If you want to test how many Vusers can be run simultaneously without
exceeding a desired transaction response time, it is recommended that you
define a Transaction Response Time goal type. Specify the name of the
transaction in your script that you want to test, and a minimum-maximum
range of Vusers for LoadRunner to run. The transaction response time you
specify should be a pre-defined threshold value. For example, if you do not
want a customer to wait more than five seconds to log in to your e-
commerce site, specify a maximum acceptable transaction response time of
five seconds. Set the minimum and maximum number of Vusers to the
minimum-maximum range of customers you want to be able to serve
simultaneously.

If the scenario does not reach the maximum transaction response time that
you defined, your server is capable of responding within a reasonable period
of time to the number of customers you want to be able to serve
simultaneously. If the defined response time is reached after only a portion
of the Vusers has been executed, or if you receive a message that the defined
response time will be exceeded if the Controller uses the maximum number
of Vusers defined, you should consider revamping your application and/or
upgrading your server software and hardware.

Note: In order for a Transaction Response Time goal-oriented scenario to be

effective, you must choose your transaction carefully, ensuring that it
performs effective hits on the server.

127
Part II • Designing a Scenario

Understanding the Goal-Oriented Scenario Design Tab

When you create a goal-oriented scenario, the Controller displays the
Scenario Goal and Scenario Scripts panes in the Design tab.

The Scenario Goal pane displays information regarding the goal profile: its
name, the goal you define, a minimum and maximum number of Vusers,
the duration of the scenario, and the load behavior.

You can define five types of goals in a goal-oriented scenario: the number of
virtual users, the number of hits per second (Web Vusers only), the number
of transactions per second, the number of pages per minute (Web Vusers
only), or the transaction response time you want your scenario to reach. For
more information on defining goal types, see the Edit Scenario Goal dialog
box on page 130.

128
 Chapter 7 • Creating a Goal-Oriented Scenario

The Scenario Scripts pane lists all enabled and disabled Vuser scripts, their
paths, the percentage of the total target assigned to each script, and the load
generator machines. For more information on the Scenario Scripts pane, see
“Assigning Properties to Scripts” on page 136.

You can perform the following actions on a goal profile or scenario:

➤ Define the goal profile name and goal type

➤ Add a new script to the scenario and configure it
➤ Add one or more load generator machines to a script and configure the load
generator(s)
➤ Enable or disable a script for the scenario
➤ Define the duration of the scenario and ramp-up behavior
➤ Run the scenario
➤ Stop the scenario
➤ Reset the scenario
➤ Configure scenario result settings

129
Part II • Designing a Scenario

Defining Scenario Goals

You define scenario goal settings for a goal-oriented scenario from the Edit
Scenario Goal dialog box.

To define a scenario goal:

1 Click Edit Scenario Goal in the Scenario Goal pane or select
Scenario > Goal Definition. The Edit Scenario Goal dialog box opens.

2 Select a Goal Profile Name. To enter a new name, click New, type the new
goal profile name in the New Goal Profile dialog box, and click OK. The new
goal profile name appears in the selector.
3 In the Define Scenario Goal box, select a Goal Type as described in
“Understanding the Edit Scenario Goal Dialog Box” on page 131.

Note: VuGen automatically defines each Init, Action, and End unit as a
transaction. In addition, you can insert a static transaction in your script
using the Start Transaction and End Transaction functions.

130
 Chapter 7 • Creating a Goal-Oriented Scenario

4 In the Scenario Settings tab, specify how long you want to run your
scenario after the target is achieved, and whether to continue the scenario if
the target cannot be reached. For more information, see “Understanding the
Scenario Settings Tab” on page 133.
5 Select the Load Behavior tab, and specify how and when you want the
Controller to reach your target. For more information, see “Understanding
the Load Behavior Tab” on page 134.
6 Select Do not change recorded think time if you want LoadRunner to run
the scenario using the think time recorded in your script.
7 Click OK to close the Edit Scenario Goal dialog box. The scenario target
information you entered appears in the Scenario Goal window.

Note: When you run a goal-oriented scenario, the goal you defined is
displayed in the appropriate graph, along with the scenario results. This
enables you to compare the results with your target goal.

Understanding the Edit Scenario Goal Dialog Box

The Edit Scenario Goal enables you to define scenario information for a
goal-oriented scenario.

Goal Profile Name: Select a goal profile name.

Rename: Rename a goal profile using the New Goal Profile dialog box.

Delete: Delete a goal profile from the list of goal profile names.

New: Enter a new goal profile name using the New Goal Profile dialog box.

Scenario Start Time: Opens the Scenario Start dialog box, enabling you to
start running a goal-oriented scenario at a later point in time.

131
Part II • Designing a Scenario

Define Scenario Goal

Goal Type: Select the type of goal you want for your scenario.

➤ Pages per Minute (Web Vusers only): Enter a target number of

downloaded pages per minute that you would like your scenario to
reach, and select a minimum and maximum number of Vusers for the
scenario.
➤ Virtual Users: Enter a target number of virtual users that you would like
your scenario to reach.
➤ Hits per Second (Web Vusers only): Enter a target number of hits per
second (HTTP requests per second) that you would like your scenario to
reach, and select a minimum and maximum number of Vusers for the
scenario.
➤ Transactions per Second: Enter a target number of transactions per
second that you would like your scenario to reach, and select a minimum
and maximum number of Vusers for the scenario. In addition, select a
static script transaction for your scenario to test, or enter the name of an
automatic script transaction that you have recorded in the Transaction
Name box.
➤ Transaction Response Time: Enter a target transaction response time that
you would like your scenario to reach, and select a minimum and
maximum number of Vusers for the scenario. In addition, select a static
script transaction for your scenario to test, or enter the name of a
dynamic script transaction that you have recorded in the Transaction
Name box.

Do not change recorded think time: Instructs LoadRunner to run the

scenario using the think time recorded in your script. Note that if you select
this option, you may need to increase the number of Vusers in your scenario
in order to reach your target.

Load Preview: Displays a graph of the goal and load behavior you defined.

132
 Chapter 7 • Creating a Goal-Oriented Scenario

Understanding the Scenario Settings Tab

The Scenario Settings Tab lets you specify how long you want your scenario
to run after the target is achieved, and whether to continue the scenario if
the target you defined cannot be reached.

Run Time

Run for X (HH:MM:SS) after the target has been achieved: Select the
amount of time you want your scenario to run after reaching the target.

If target cannot be reached: Select one of the following two options:

➤ Stop scenario and save results: Instructs the Controller to stop the
scenario and save the scenario results, if the target you defined cannot be
reached.
➤ Continue scenario without reaching goal: Instructs the Controller to
continue running the scenario, even if the target you defined cannot be
reached.
Receive notification: Instructs the Controller to send you an error message
indicating that the target cannot be reached.

133
Part II • Designing a Scenario

Understanding the Load Behavior Tab

The Load Behavior Tab lets you specify how and when you want the
Controller to reach your target.

Ramp Up: Select one of the following options:

➤ Automatic: Instructs the Controller to run the default number of Vusers

in a batch (50 Vusers—or all the Vusers, if the maximum number of
Vusers defined is less than 50—every two minutes).
➤ Reach target X after: Select the amount of scenario time you want to
elapse before the Controller reaches your target.
➤ Step up by (not available for the Transactions per Second and
Transaction Response Time goal types): Select the gradation according to
which you want the Controller to reach your target (x number of virtual
users/hits/pages every x amount of time).

134
 Chapter 7 • Creating a Goal-Oriented Scenario

Understanding the Hits/Transactions per Second and Pages per

Minute Goal Types
When you define a Pages per Minute or Hits/Transactions per Second goal
type, the Controller divides the target you defined by the minimum number
of Vusers you specified, and determines the target number of
hits/transactions per second or pages per minute that each Vuser should
reach. The Controller then begins loading the Vusers according to the load
behavior settings you defined, as follows:

➤ If you selected to run the Vusers automatically, LoadRunner loads fifty

Vusers in the first batch. If the maximum number of Vusers defined is less
than fifty, LoadRunner loads all of the Vusers simultaneously.
➤ If you chose to reach your target after a certain period of the scenario
elapses, LoadRunner attempts to reach the defined target within this period
of time. It determines the size of the first batch of Vusers based on the time
limit you defined and the calculated target number of hits, transactions, or
pages per Vuser.
➤ If you chose to reach your target by gradation (x number of pages/hits every
x amount of time), LoadRunner calculates the target number of hits or pages
per Vuser and determines the size of the first batch of Vusers accordingly.

Note: The last load behavior option is not available for the Transactions per
Second goal type.

After running each batch of Vusers, LoadRunner evaluates whether the

target for the batch was achieved. If the batch target was not reached,
LoadRunner recalculates the target number of hits, transactions, or pages
per Vuser, and readjusts the number of Vusers for the next batch to be able
to achieve the defined goal. Note that by default, a new batch of Vusers is
released every two minutes.

If the goal has not been reached once the Controller has launched the
maximum number of Vusers, LoadRunner attempts to reach the defined
target once more by recalculating the target number of hits, transactions, or
pages per Vuser, and running the maximum number of Vusers
simultaneously.

135
Part II • Designing a Scenario

A Pages per Minute or Hits/Transactions per Second goal-oriented scenario is

assigned a "Failed" status if:

➤ the Controller has twice attempted to reach the goal using the maximum
number of Vusers specified, and the goal could not be reached.
➤ no pages per minute or hits/transactions per second were registered after the
first batch of Vusers was run.
➤ the number of pages per minute or hits/transactions per second did not
increase after the Controller ran a certain number of Vuser batches.
➤ all the Vusers that were run failed.
➤ there were no available load generators for the type of Vusers you attempted
to run.

Assigning Properties to Scripts

The Scenario Scripts pane displays a list of scripts you selected for the
scenario.

The % of Target column indicates the percentage of the overall target

number of Vusers, pages per minute, hits per second, transactions per
second, or transaction response time that is automatically distributed to
each Vuser script. The Load Generators column automatically contains
<All Load Generators> for each Vuser script.

136
 Chapter 7 • Creating a Goal-Oriented Scenario

To modify the percentage of Vusers assigned to a script:

In the script’s % of Target column, enter a percentage of the total target
number of Vusers, pages per second, hits per second, transactions per
second, or transaction response time you want LoadRunner to reach during
the scenario. During the scenario, LoadRunner attempts to reach the
percentage of the total that you stipulate for each script in the scenario.

To add or modify load generator(s) for a script:

1 In the script’s Load Generators column, select one or more machine(s) from
the Load Generator Name list, and click OK. If you select multiple machines,
the Vusers assigned to the script are distributed evenly among the load
generators.
2 Alternatively, you can choose Add to add a load generator to the list. The
Add New Load Generator dialog box opens:

3 Type the name of the load generator in the Name box.

4 In the Platform box, select the type of platform on which the load generator
is running.
5 In the Temporary Directory box, type a location of the load generator where
the Controller can store temporary files, or leave the field empty to accept
the default location. By default, LoadRunner stores temporary files on the
load generator during scenario execution, in a temporary directory specified
by the load generator’s TEMP or TMP environment variables.
6 To allow the load generator to take part in the scenario, check Enable load
generator to take part in the scenario.
7 Click More to expand the dialog box and show the Add Load Generator
tabs. For information on configuring settings for each load generator, see
“Configuring Load Generator Settings” on page 78.

137
Part II • Designing a Scenario

8 Click OK to close the Add Load Generator dialog box. LoadRunner adds the
new load generator to the Load Generator Name list. To include the new
load generator in your scenario, select it from the Load Generator Name list,
and click OK. Note that you can select multiple load generators.
Repeat the above procedure for each load generator you want to add to your
scenario.

Configuring Load Generators

You can set a load generator’s attributes while adding it to the load generator
list, or modify the attributes of an existing load generator at any time, using
the Load Generators dialog box. You can also use the Load Generators dialog
box to indicate which load generators will run Vusers in the scenario. For
example, if a load generator is unavailable for a particular scenario run, you
can use the Load Generators dialog box to exclude it temporarily instead of
removing it entirely from your list of load generators. For instructions on
using the Load Generators dialog box, see “Configuring Load Generators”
on page 74. To configure additional load generator settings, see
“Configuring Load Generator Settings” on page 78.

To configure global settings for all load generators participating in the

scenario, use LoadRunner’s Options dialog box. For more information, see
Chapter 10, “Configuring a Scenario.”

Load Balancing
Load balancing evenly distributes the load generated by Vusers among the
requested load generator machines, ensuring an accurate load test.

When a Windows load generator machine’s CPU usage becomes overloaded,

the Controller stops loading Vusers on the overloaded load generator, and
automatically distributes them among load generators taking part in the
scenario. Only where there are no other load generators in the scenario does
the Controller stop loading Vusers.

You can monitor the status of a machine’s CPU usage using the icons in the
Load Generators dialog box. When the CPU usage of a load generator
becomes problematic, the icon to the left of the load generator name
contains a yellow bar. When the machine becomes overloaded, the icon
contains a red bar.

138
 Chapter 7 • Creating a Goal-Oriented Scenario

Note: Load balancing is only available in goal-oriented scenarios and

manually controlled scenarios in the Percentage Mode.

Configuring Scripts
You can add a script to the Scenario Scripts list using the Add Script dialog
box. Once you have added a script to the list, you can view the details of the
script you selected, edit the script, or change its run-time settings.

To add a script:
1 Click the Add Script button to the right of the Scenario Scripts pane, or
right-click within a column and select Add Script. The Add Script dialog box
opens.

2 Click Browse. The Open Test dialog box opens.

Select the path and file name of the new script. To select a VB Vuser script,
browse to locate the .usr file.

139
Part II • Designing a Scenario

Note: When you specify the location of a script, you can specify a location
that is relative to the current scenario directory. For details, see “Using
Relative Paths for Scripts” on page 109.

3 Click Open to select the files. The Open Test dialog box closes, and the new
script name appears in the Add Script dialog box.
4 Click OK to close the Add Script dialog box and enter the new script
information in the Scenario Scripts pane.

Note: A script’s rendezvous points are disabled in a goal-oriented scenario.

Viewing Script Information

Once you have added a script to the list, you can view the details of the
script you selected, edit the script, enable/disable it, or change its run-time
settings.

To view script details:

1 Click the Details button to the right of the Scenario Scripts pane, or right-
click a script and select Details. The Script Information dialog box opens,
displaying the Name, Path, and Type of the script you selected.

140
 Chapter 7 • Creating a Goal-Oriented Scenario

2 Click Run-Time Settings to set the script’s run-time settings (optional),

which allow you to customize the way the Controller executes a Vuser
script. The Run-Time Settings dialog box opens, displaying the settings you
previously set using VuGen. If you did not set run-time settings for a script
in VuGen, the default VuGen settings are displayed for all but the Log and
Think Time tabs, which display the default Controller settings. Note that
several protocols, such as Web and Java, have specific settings.
For information on configuring the run-time settings, refer to the Mercury
Virtual User Generator User’s Guide.

Note: If you modify the run-time settings from the Controller, LoadRunner
runs the script using the modified settings. To restore the initial settings,
click Refresh and select Run-Time Settings.

3 To edit the script, click View Script. The script generation tool, VuGen,
opens. For more information on editing scripts, see the Mercury Virtual User
Generator User’s Guide.

Note: If you use VuGen to make changes to a script while the Controller is
running, click Refresh and select Script to update the script details in the
scenario.

141
Part II • Designing a Scenario

4 Click More to expand the Script Information dialog box and view additional
script information.

5 In the Command Line box, type any command line options to use when
running the script. For example: -x value -y value
For information about passing command line argument values to a script,
refer to the Mercury Virtual User Generator User’s Guide.
6 To see the rendezvous points included in the selected script, click the
Rendezvous tab.
7 To see the list of Vusers associated with the selected script, click the Vusers
tab. If you have not yet created Vusers, the box will be empty.

142
 Chapter 7 • Creating a Goal-Oriented Scenario

8 To see the list of files used by the script, select the Files tab. By default, this
list shows all files in the script’s directory (only after your script has been
added to the script list). These files include the configuration settings file,
the init, run, and end portions of the script, the parameterization
definitions file, and the .usr file. To add a file to the list, click Add and add
the file name. Note that you can delete the files that you add, but not the
other files listed.
9 Click OK to close the Script Information dialog box.

To delete a script:
Click the Remove Script button to the right of the Scenario Scripts pane, or
right-click the script and select Remove Script.

To disable a script:
Click the box to the left of the Vuser script name. The color of the script
entry changes to gray, indicating that the script will not take part in the
scenario. To re-enable the Vuser script, click the same box again.

143
Part II • Designing a Scenario

144
8
Scheduling a Scenario

After you create a scenario, you can set the time at which the scenario will
begin running. In addition, for a manual scenario, you can set the duration
time of the scenario or of the Vuser groups within the scenario. You can also
select to gradually run and stop the Vusers within the scenario or within a
Vuser group.

Note: The Vuser group settings are not applicable to the Percentage Mode.

This chapter describes:

➤ About Scenario Scheduling

➤ Delaying the Start of a Scenario
➤ Selecting a Schedule
➤ Scheduling a Scenario
➤ Scheduling Vuser Groups
➤ Adding Vusers to a Scheduled Scenario

145
Part II • Designing a Scenario

About Scenario Scheduling

An important factor in the creation of a scenario is developing a test that
accurately portrays user behavior—the types of actions and the timing of
those actions, represented by Vuser scripts.

Using the Scenario Start dialog box, you can instruct LoadRunner to begin
executing a scenario with a delay. You can specify either the number of
minutes you want LoadRunner to wait from the time a Run command is
issued, or the specific time at which you want the scenario to begin.

Using the Schedule Builder, you can set the timing aspect of a manual
scenario, limiting the execution duration of the scenario or of a Vuser group
within the scenario. You limit the execution time duration by specifying the
number of minutes a scenario or Vuser group should be in the Running
status. When the scenario or group reaches its time limitation, it finishes.

Note: The Vuser group settings are not applicable to the Percentage Mode.

For manual scenarios, you can also stipulate how many Vusers LoadRunner
starts and stops within a certain time frame. You specify whether
LoadRunner should start or stop all Vusers in a scenario or Vuser group
simultaneously, or start/stop only a certain number of Vusers within a
specified amount of time.

The schedule you define is visually displayed in the Load Preview graph.

Note: Rendezvous points in a Vuser script interfere with a scheduled

scenario. If your script contains rendezvous points, your scenario will not
run as scheduled.

146
 Chapter 8 • Scheduling a Scenario

Delaying the Start of a Scenario

For both manual and goal-oriented scenarios, you can instruct LoadRunner
to start running the scenario at a later point in time. You can specify either
the number of minutes you want LoadRunner to wait from the time a Run
command is issued, or the specific time at which you want the scenario to
begin.

To delay the start of the scenario:

1 Select Scenario > Start Time. The Scenario Start dialog box opens, with the
default option—without delay—selected.

2 Select with a delay of X (HH:MM:SS) and enter the amount of time (in
hours:minutes:seconds format) by which you want to delay the start of your
scenario.
Alternatively, you can select at X (HH:MM:SS) on <date> and specify the
time (in hours:minutes:seconds format) and date for the start of the
scenario.
3 Click OK to close the dialog box and save your settings.

147
Part II • Designing a Scenario

Understanding the Start Scenario Dialog Box

The Start Scenario Dialog Box enables you to delay the time at which a
scenario begins.

Scenario Start: Select one of the following options:

➤ without delay: Starts the scenario immediately when you click the Start
Scenario button.
➤ with a delay of X (HH:MM:SS): Starts the scenario after the amount of
time you specify has elapsed.
➤ at X (HH:MM:SS) on <date>: Starts the scenario on the day and at the
time you specify.

Note: You can set the ramp up schedule and duration of a scenario or Vuser
group using the Schedule Builder.

Selecting a Schedule
You select the schedule you want to use for your manual scenario from the
Scenario Name box in the Scenario Schedule pane. You can select one of the
existing schedules—Slow Ramp Up or Ramp Up—or New Schedule, if you
want to create a schedule with new properties using the Schedule Builder.

Note that you can also change the properties for one of the three existing
schedules using the Schedule Builder.

148
 Chapter 8 • Scheduling a Scenario

To create a new schedule:

1 Select <new schedule> from the Scenario Name box in the Scenario
Schedule pane. The New Schedule dialog box opens.

2 In the Name text box, type the name of the New Schedule and click OK. The
Schedule Builder dialog box opens.

To modify the properties of an existing schedule:

1 Select Slow Ramp Up or Ramp Up from the Scenario Name box in the
Scenario Schedule pane of the Design tab.
2 Select Scenario > Schedule Builder, or click the Edit Schedule button. The
Schedule Builder dialog box opens.

To rename a schedule, click Rename. Enter the new name you want to use in
the dialog box that opens. To delete a schedule, click Delete.

149
Part II • Designing a Scenario

Understanding the Schedule Builder Dialog Box

The Schedule Builder dialog box enables you to configure the schedule
settings for the scenario.

Schedule Name: Select the name of the schedule you want to use for the
scenario. Three default names appear: Default Schedule, Ramp Up, and Slow
Ramp Up. Ramp Up increments the release of the Vusers at a relative pace.
Slow Ramp Up increments the release of the Vusers at a slower pace.

New: Opens the New Schedule dialog box, enabling you to enter the new
schedule name.

Rename: Renames the schedule.

Delete: Deletes the schedule name.

Scenario Start Time: Opens the Delay Scenario Start dialog box, enabling
you to start running a manual or goal-oriented scenario at a later point in
time.

Schedule Definition

➤ Schedule by Scenario: Defines the settings of the entire scenario.

➤ Ramp Up Tab: Determines how to start the scenario.
➤ Duration Tab: Sets the duration of the scenario.
➤ Ramp Down Tab: Determines how to stop the scenario.
➤ Schedule by Group: Defines an individual group’s settings. From the box on
the left, select the Vuser group you want to schedule.
➤ Start Time Tab: Determines how to set the start time for the Vuser group.
➤ Ramp Up Tab: Determines how to start the Vuser group.
➤ Duration Tab: Sets the duration of the Vuser group.
➤ Ramp Down Tab: Determines how to stop the Vuser group.

Note: The Vuser group settings are not applicable to the Percentage Mode.

150
 Chapter 8 • Scheduling a Scenario

Initialize all Vusers before Run: Instructs LoadRunner to initialize Vusers

before beginning to load them. The ramping up of the Vusers begins only
after all the Vusers reach the Ready status.

Load Preview: Displays a graph of the scenario schedule you defined.

Note: Rendezvous points in a Vuser script interfere with a scheduled

scenario. If your script contains rendezvous points, your scenario will not
run as scheduled.

Scheduling a Scenario
Using the Schedule Builder, you can control the execution of your scenario
by:

➤ limiting the scenario duration

➤ gradually running Vusers within a scenario
➤ gradually stopping Vusers within a scenario

151
Part II • Designing a Scenario

To set the scheduling options for a scenario:

1 Select the Schedule by Scenario option.

2 To determine how to start the scenario, click the Ramp Up tab. Choose one
of the following options:
➤ Load all Vusers simultaneously: Starts all the Vusers in the scenario at
once.
➤ Start X Vusers every X (HH:MM:SS): Begins running the specified
number of Vusers concurrently, and waits the specified time between
Vuser ramp ups.

Note: While a scenario is running, you can add Vuser groups/scripts to a

scenario and enable them. In the gradual ramp up mode, if you add a Vuser
group/script after all the Vusers in the scenario have been ramped up, the
new group/script will start loading immediately.

3 To instruct LoadRunner to initialize Vusers before beginning to load them,

select Initialize all Vusers before ramp up. Note that LoadRunner will only
begin to load the Vusers once they have all reached the Ready status.

152
 Chapter 8 • Scheduling a Scenario

4 To set the duration of the scenario, select the Duration tab.

Choose one of the following options:

➤ Run until completion
➤ Run for X (HHH:MM:SS) after the ramp up has been completed: Runs
the scenario for a specified amount of time, once all the Vusers have been
ramped up.
➤ Run indefinitely

Note: The duration setting overrides the Vuser iteration settings. This means
that if the duration is set to five minutes, the Vusers will continue to run as
many iterations as required in five minutes, even if the run-time settings
specify only one iteration.

In a scenario of limited duration, the duration time starts to run after all the
Vusers reach the Init status. Vusers that take a long time to initialize may not
reach the Run status before the scenario ends. To ensure that all Vusers run
in the scenario, check the Initialize all Vusers before Run check box.
Duration time only starts when all Vusers reach the Run status.

153
Part II • Designing a Scenario

5 To determine how to stop the scenario, click the Ramp Down tab.

Choose one of the following options:

➤ Stop all Vusers simultaneously: Stops all the Vusers in the scenario at
once.
➤ Stop X Vusers every X (HH:MM:SS): Stops a certain number of Vusers
within a specified time frame.

Note: The Ramp Down tab settings will only be applied if you select the
second option in the Duration tab.

6 Click OK to close the Schedule Builder and save your settings.

154
 Chapter 8 • Scheduling a Scenario

Scheduling Vuser Groups

After you create a Vuser group, you can schedule the group’s script
execution by setting:

➤ the amount of time after the start of the scenario that the group must wait
before it starts running
➤ the number of Vusers that will run within a specified period of time
➤ the number of Vusers that will be stopped within a specified period of time
➤ the amount of time the group will run

Note: The Vuser group settings are not applicable to the Percentage Mode.

To schedule a Vuser Group:

1 Select the Schedule by Group option. By default the Start Time tab is
displayed

2 Select a group from the box on the left.

155
Part II • Designing a Scenario

3 To set the start time for the group, choose one of the following options:
➤ Start the group at the beginning of the scenario
➤ Start X after the scenario begins: Waits the specified amount of time
before running the group.
➤ Start when group X finishes: Begins running the group after the specified
group has finished running.
4 To set the ramp up for the group, click the Ramp Up tab.

Choose one of the following options:

➤ Load all of the Vusers simultaneously: Starts all the Vusers in the group at
once.
➤ Start X Vusers every X (HH:MM:SS): Begins running the specified
number of Vusers concurrently, and waits the specified time between
Vuser ramp ups.

Note: While a scenario is running, you can add Vuser groups to a scenario
and enable them. In the gradual ramp up mode, if you add a Vuser group
after all the Vusers in the scenario have been ramped up, the new group will
start loading immediately.

5 To instruct LoadRunner to initialize Vusers before beginning to load them,

select Initialize all Vusers before ramp up. Note that LoadRunner will only
begin to load the Vusers once they have all reached the Ready status.

156
 Chapter 8 • Scheduling a Scenario

6 To set the duration of the group, click the Duration tab.

Choose one of the following options:

➤ Run until completion
➤ Run for X (HH:MM:SS) after the ramp has been completed: Runs the
group for the specified amount of time, once all the Vusers have been
ramped up.

Note: The duration setting overrides the Vuser iteration settings. This means
that if the duration is set to five minutes, the Vusers will continue to run as
many iterations as required in five minutes, even if the run-time settings
specify only one iteration.

In a scenario of limited duration, the duration time starts to run after all the
Vusers reach the Init status. Vusers that take a long time to initialize may not
reach the Run status before the scenario ends. To ensure that all Vusers run
in the scenario, check the Initialize all Vusers before Run check box.
Duration time only starts when all Vusers reach the Run status.

157
Part II • Designing a Scenario

7 To determine how to stop the Vuser group, click the Ramp Down tab.

Choose one of the following options:

➤ Stop all Vusers simultaneously: Stops all the Vusers in the group at once.
➤ Stop X Vusers every X (HH:MM:SS): Stops a certain number of Vusers
within a specified time frame.

Note: The Ramp Down tab settings will only be applied if you select the
second option in the Duration tab.

8 Click OK to close the Schedule Builder and save your settings.

158
 Chapter 8 • Scheduling a Scenario

Adding Vusers to a Scheduled Scenario

If you are running a scenario or Vuser group using Schedule Builder settings,
these settings will be applied to all Vusers that are manually added to the
scenario or Vuser group during the scenario run. For example, if a running
scenario or Vuser group has a set duration of five minutes, all Vusers
subsequently added to the scenario or Vuser group will only run for the
remaining part of this time period.

Vusers added to a scheduled scenario or Vuser group which has finished

running will not be affected by Schedule Builder settings and will run
according to the scenario run-time settings.

For more information on manually controlled Vusers, see “Manually Adding

Vusers to a Running Scenario” on page 222.

159
Part II • Designing a Scenario

160
9
Using Rendezvous Points

LoadRunner allows you to check your system’s response under specific load.
To do this, you can use rendezvous points to cause multiple Vusers to
perform tasks at exactly the same time, thereby creating intense user load on
the server.

This chapter describes:

➤ About Using Rendezvous Points

➤ Setting the Rendezvous Attributes
➤ Setting the Rendezvous Policy
➤ Disabling and Enabling Rendezvous Points
➤ Disabling and Enabling Vusers at Rendezvous Points
➤ Viewing Rendezvous Information

About Using Rendezvous Points

During a scenario run, you can instruct multiple Vusers to perform tasks
simultaneously by using rendezvous points. A rendezvous point creates
intense user load on the server and enables LoadRunner to measure server
performance under load.

Suppose you want to measure how a Web-based banking system performs

when ten Vusers simultaneously check account information. To emulate the
required user load on the server, you instruct all the Vusers to check account
information at exactly the same time.

161
Part II • Designing a Scenario

You ensure that multiple Vusers act simultaneously by creating a

rendezvous point. When a Vuser arrives at a rendezvous point, it is held
there by the Controller. The Controller releases the Vusers from the
rendezvous either when the required number of Vusers arrives, or when a
specified amount of time has passed. For details on the release criteria, see
“Setting the Rendezvous Policy” on page 165.

You define rendezvous points in the Vuser script. For information about
inserting rendezvous points into Vuser scripts, refer to the Mercury Virtual
User Generator User’s Guide.

Using the Controller, you can influence the level of server load by selecting:

➤ which of the rendezvous points will be active during the scenario

➤ how many Vusers will take part in each rendezvous
For example, to test a bank server, you could create a scenario that contains
two rendezvous points. The first rendezvous ensures that one thousand
Vusers simultaneously deposit cash. The second rendezvous ensures that
another thousand Vusers simultaneously withdraw cash. If you want to
measure how the server performs when only five hundred Vusers deposit
cash, you can deactivate (disable) the “withdraw” rendezvous, and instruct
only five hundred Vusers to participate in the “deposit” rendezvous.

The following procedure outlines how to control load peaks on the server:
1 Create the Vuser scripts, inserting the necessary rendezvous points.
2 Create a scenario.
When you add a Vuser group to a scenario, LoadRunner scans the group’s
associated script for the names of the rendezvous points and adds them to
the list in the Rendezvous Information dialog box (Scenario > Rendezvous).
If you create another Vuser group that runs the same script, the Controller
adds the new Vusers to the rendezvous and updates the list.

162
 Chapter 9 • Using Rendezvous Points

3 Set the level of emulated user load.

You determine the exact level of load by selecting the rendezvous points
that will take part in the scenario, and how many Vusers will participate in
each rendezvous.
4 Set the attributes for the rendezvous (optional).
For each rendezvous you can set Policy attributes. For more information, see
“Setting the Rendezvous Policy” on page 165.
5 Run the scenario.

Setting the Rendezvous Attributes

You can set the following rendezvous attributes from the Rendezvous
Information dialog box (Scenario > Rendezvous):

➤ Rendezvous Policy
➤ Enabling and Disabling of Rendezvous Points
➤ Enabling and Disabling of Vusers

163
Part II • Designing a Scenario

In addition, the dialog box displays general information about the

rendezvous point: which script is associated with the rendezvous, and
release history.

For information on manipulating the Vusers during scenario execution

using the Release command, see Chapter 13, “Running a Scenario.”

164
 Chapter 9 • Using Rendezvous Points

Setting the Rendezvous Policy

Setting the rendezvous policy determines how the Vusers handle a
rendezvous point. You set the following policy attributes for each
rendezvous:

Release policy: How many Vusers will be released from a rendezvous at a

time.

Timeout: How long the Controller waits before releasing Vusers from a
rendezvous.

To set the rendezvous policy attributes:

1 Choose Scenario > Rendezvous. The Rendezvous Information dialog box
opens.
2 Select a rendezvous from the Rendezvous box, and click the Policy button.
The Policy dialog box opens.

165
Part II • Designing a Scenario

3 In the Policy section, select one of the following three options:

➤ Release when X% of all Vusers arrive at the rendezvous: Releases the
Vusers only when the specified percentage of all Vusers arrives at the
rendezvous point.

Note: This option interferes with the scheduling of your scenario. If you
select this option, your scenario will not run as scheduled.

➤ Release when X% of all running Vusers arrive at the rendezvous: Releases

the Vusers only when the specified percentage of all Vusers running in
the scenario arrives at the rendezvous point.
➤ Release when X Vusers arrive at the rendezvous: Releases the Vusers only
when the specified number arrives at the rendezvous point.

4 Enter a timeout value in the Timeout between Vusers box. After each Vuser
arrives at the rendezvous point, LoadRunner waits up to the maximum
timeout period you set for the next Vuser to arrive. If the next Vuser does
not arrive within the timeout period, the Controller releases all the Vusers
from the rendezvous.
Each time a new Vuser arrives, the timer is reset to zero. The default timeout
is thirty seconds.
5 Click OK to save your settings and close the Policy dialog box.

166
 Chapter 9 • Using Rendezvous Points

Disabling and Enabling Rendezvous Points

You can temporarily disable a rendezvous and exclude it from the scenario.
By disabling and enabling a rendezvous, you influence the level of server
load.

You use the Disable Rendezvous/Enable Rendezvous button in the

Rendezvous Information dialog box, to change the status of a rendezvous.

To disable a rendezvous:
1 In the Rendezvous box, select the rendezvous you want to disable.
2 Click the Disable Rendezvous button. The button changes to Enable
Rendezvous and the rendezvous becomes disabled.

To enable a rendezvous:
1 In the Rendezvous box, select the disabled rendezvous that you want to
enable.
2 Click the Enable Rendezvous button. The button changes to Disable
Rendezvous and the rendezvous becomes enabled.

Disabling and Enabling Vusers at Rendezvous Points

In addition to disabling a rendezvous point for all Vusers in a scenario,
LoadRunner lets you disable it for specific Vusers. By disabling Vusers at a
rendezvous, you temporarily exclude them from participating in the
rendezvous. Enabling disabled Vusers returns them to the rendezvous. You
use the Disable and Enable commands to specify which Vusers will take part
in a rendezvous.

To disable a Vuser in a rendezvous:

1 In the Rendezvous box, select the rendezvous for which you want to disable
Vusers.

167
Part II • Designing a Scenario

2 In the Vusers box, select the Vuser(s) you want to exclude from the
rendezvous. Select multiple Vusers using the CTRL key.

3 Click the Disable Vuser button below the Vusers box. The disabled Vusers
change from black to gray and will not take part in the rendezvous.
To enable a Vuser, select it and click Enable Vuser.

168
 Chapter 9 • Using Rendezvous Points

Viewing Rendezvous Information

During and after a scenario, you can view the rendezvous status in the
Rendezvous Information dialog box. The following information is provided:

Current Status: The number of Vusers that arrived at the rendezvous point
out of the total number of Vusers assigned to the rendezvous.

Time: The time at which the Vusers at the rendezvous point were released.

Reason: The reason the Vusers at the rendezvous point were released. The
possible reasons are Timeout or Arrived.

To view rendezvous information:

Select the rendezvous whose information you want to view. The rendezvous
status is displayed in the Status Information section.

169
Part II • Designing a Scenario

Understanding the Rendezvous Information Dialog Box

The Rendezvous Information dialog box enables you to view and modify the
attributes of each rendezvous point in the scenario.

Rendezvous: Displays the name(s) of the rendezvous point(s) in the

scenario.

➤ Enable Rendezvous/Disable Rendezvous: Enables or disables the selected

rendezvous point(s) from participating in the scenario.
Scripts: Lists the Vuser scripts that are associated with the rendezvous
point(s).

Vusers: Lists the Vusers that are associated with the rendezvous point(s).

➤ Enable Vuser/Disable Vuser: Enables or disables a Vuser from taking part

in the rendezvous.

Policy: Opens the Policy dialog box, enabling you to set how many Vusers
are released from a rendezvous at a time, as well as the amount of time the
Controller waits before releasing Vusers from a rendezvous.

➤ Timeout: Enter the timeout value (in seconds). After each Vuser arrives at
the rendezvous point, LoadRunner waits up to the number of timeout
seconds specified for the next Vuser to arrive. If the next Vuser does not
arrive within the timeout period, the Controller releases all the Vusers
from the rendezvous. Each time a new Vuser arrives, the timer is reset to
zero. The default timeout is thirty seconds. You set a timeout for each
rendezvous point.

Status Information

➤ Current Status: Displays the number of Vusers that arrived at the

rendezvous point out of the total number of Vusers assigned to the
rendezvous.
➤ Time: Displays the time at which the rendezvous was released.
➤ Reason: Displays the reason for the release of the Vusers from the
rendezvous point. The possible reasons are Timeout or Arrived.

170
 Chapter 9 • Using Rendezvous Points

➤ Release: Releases all Vusers currently waiting at the selected rendezvous

point. If you want the scenario to continue even though all the Vusers
did not reach the rendezvous, click this button.
➤ Reset: Resets the Status Information, removing the information currently
displayed.

171
Part II • Designing a Scenario

172
10
Configuring a Scenario

You can configure how load generators and Vusers behave when you run a
scenario so that the scenario accurately emulates your working
environment.

This chapter describes:

➤ About Configuring a Scenario

➤ Setting Timeout Intervals
➤ Configuring Scenario Run-Time Settings
➤ Setting the Run-Time File Location
➤ Specifying Path Translation

About Configuring a Scenario

Before you run a scenario, you can configure both the load generator and
Vuser behaviors for the scenario. Although the default settings correspond
to most environments, LoadRunner allows you to modify the settings to
customize the scenario behavior. The settings apply to all future scenario
runs and generally need to be set only once.

The settings described in this chapter apply to all the load generators in a
scenario. To change the settings for individual load generator machines,
refer to Chapter 5, “Creating a Manual Scenario.” If the global scenario
settings differ from those of an individual load generator, the load generator
settings override them.

173
Part II • Designing a Scenario

The settings discussed in this chapter are unrelated to the Vuser run-time
settings. These settings, which apply to individual Vusers or scripts, contain
information about logging, think time, and the network, the number of
iterations, and the browser. For information on setting the run-time
settings, see the Mercury Virtual User Generator User’s Guide.

For information on setting the options for online monitors, see Chapter 20,
“Online Monitoring.”

The LoadRunner Expert mode allows you to configure additional settings for
the LoadRunner agent and other LoadRunner components. For more
information, see Appendix C, “Working in Expert Mode.”

Setting Timeout Intervals

The Timeout tab lets you specify timeout values for certain commands
related to the load generator. If the command is not executed successfully
within the timeout period, the load generator status changes to ERROR.

174
 Chapter 10 • Configuring a Scenario

To set timeout intervals:

1 Choose Tools > Options. The Options dialog box opens. Select the Timeout
tab.

2 To specify a command timeout interval, select the Enable timeout checks

check box and specify the appropriate timeouts. Clear the Enable timeout
checks check box to disable the timeout test.
3 Specify the frequency at which LoadRunner updates the elapsed time, in the
Update Vuser elapsed time every box.

Understanding the Options - Timeout Tab

LoadRunner enables you to set the timeout interval for commands and
Vuser elapsed time.

The command timeouts are the maximum time limits for various
LoadRunner commands. When a command is issued by the Controller, you
set a maximum time for the load generator or Vuser to execute the
command. If it does not complete the command within the timeout
interval, the Controller issues an error message.

175
Part II • Designing a Scenario

Command Timeout (seconds)

Enable timeout checks: Instructs LoadRunner to monitor the status of load

generators and Vusers after a command is issued by the Controller. If the
load generator or Vuser does not complete the command within the timeout
interval you specified, the Controller issues an error message. If you disable
the timeout limitations, LoadRunner waits an unlimited time for the load
generators to connect and disconnect, and for the Initialize, Run, Pause, and
Stop commands to be executed.

➤ Load Generator
➤ Connect: Enter the time limit that LoadRunner waits to connect to any
load generator. If a connection is not successful within this time, the
status of the load generator changes to FAILED. The default connection
timeout is 120 seconds.
➤ Disconnect: Enter the time limit that LoadRunner waits to disconnect
from any load generator. If a disconnection is not successful within this
time, the status of the load generator changes to FAILED. The default
disconnection timeout is 120 seconds.

Note: LoadRunner recognizes the fact that the number of active Vusers
influences the timeout values. For example, 1000 Vusers trying to initialize
will take much longer than 10 Vusers. LoadRunner adds an internal value,
based on the number of active Vusers, to the specified timeout value.

➤ Vuser
➤ Init: Enter the timeout value for the Initialize command. The default time
limit is 180 seconds.
➤ Run: Enter the timeout value for the Run command. The default time
limit is 120 seconds.
➤ Pause: Enter the timeout value for the Pause command. The default time
limit is 120 seconds.
➤ Stop: Enter the timeout value for the Stop command. The default time
limit is 120 seconds.

176
 Chapter 10 • Configuring a Scenario

Update Vuser elapsed time every: Specifies the frequency at which

LoadRunner updates the value displayed in the Elapsed Time column in the
Vusers dialog box. The default is 4 seconds.

Example:

If you select a Vuser and click the Initialize button, LoadRunner checks
whether the Vuser reaches the READY state within 180 seconds (the default
Init timeout period); if it does not, the Controller issues a message indicating
that the Init command timed out.

Configuring Scenario Run-Time Settings

You can specify scenario run-time settings relating to Vuser quotas, stopping
Vusers, and random sequence seed using the Run-Time Settings tab.

To set the scenario run-time settings:

1 Choose Tools > Options. The Options dialog box opens. Click the Run-Time
Settings tab.

2 To set a Vuser quota, specify the desired value.

177
Part II • Designing a Scenario

3 Select the way in which you want LoadRunner to stop running Vusers.
4 To specify a seed value for a random sequence, select the Use random
sequence with seed check box and enter the desired seed value.

Understanding the Options - Run-Time Setting Tab

The Run-Time Setting Tab lets you specify run-time setting values such as
the Vuser quota, the way in which Vusers are stopped, or the seed for
random sequences.

Vuser Quota: To prevent your system from overloading, you can set quotas
for Vuser activity. The Vuser quotas apply to Vusers on all load generators.

➤ Number of Vusers that may be initialized at one time - all load

generators: Sets the maximum number of Vusers that the load generator
can initialize at a time (when you send an Initialize command).
When stopping Vusers: Lets you control the way in which Vusers stop
running when you click the Stop button.

Select one of the following options:

➤ Wait for the current iteration to end before exiting: Instructs

LoadRunner to allow a Vuser to complete the iteration it is running
before stopping. The Vuser(s) move to the GRADUAL EXITING status and
exit the scenario gradually.
➤ Wait for the current action to end before exiting: Instructs LoadRunner
to allow a Vuser to complete the action it is running before stopping. The
Vuser(s) move to the GRADUAL EXITING status and exit the scenario
gradually.
➤ Stop immediately: Instructs LoadRunner to stop running the Vuser(s)
immediately. The Vuser(s) move to the EXITING status and exit the
scenario immediately.

178
 Chapter 10 • Configuring a Scenario

Use random sequence with seed: Allows LoadRunner to use a seed number
for random sequencing. Each seed value represents one sequence of random
values used for test execution. Whenever you use this seed value, the same
sequence of values is assigned to the Vusers in the scenario. This setting
applies to parameterized Vuser scripts using the Random method for
assigning values from a data file. It will also affect the random percentage of
recorded think time (see information on the Run-Time Settings dialog box
in the VuGen Help project). Enable this option if you discover a problem in
the test execution and want to repeat the test using the same sequence of
random values.

Setting the Run-Time File Location

When you run a scenario, by default the run-time files are stored locally on
each Vuser load generator (the machine running the Vuser script). The
default location of the files is under the temporary directory specified by the
load generator’s environment variables (on Windows, TEMP or TMP, and on
UNIX, $TMPDIR or $TMP). If no environment variable is defined, the files
are saved to the /tmp directory.

Note: The run-time file storage settings that are described in this chapter
apply to all the load generators in a scenario. You can change the settings for
individual load generator machines as described in “Configuring Load
Generators” on page 74.

179
Part II • Designing a Scenario

The primary run-time files are Vuser script and result files:

Script files: When you run a Vuser, the Controller sends a

copy of the associated Vuser script to the
Vuser load generator. The script is stored in
the load generator’s temporary run-time
directory.
Result files: While you run a scenario, the participating
Vusers write their results to the temporary
run-time file directory. After scenario
execution, these result files are collated or
consolidated—results from all of the load
generators are transferred to the results
directory. You set the location of the results
directory as described in Chapter 13,
“Running a Scenario.” After collating the
results, the temporary run-time directory is
deleted.

180
 Chapter 10 • Configuring a Scenario

To specify where LoadRunner stores run-time files:

1 Choose Tools > Options. The Options dialog box opens. Select the Run-Time
File Storage tab.

By default, the On the current Vuser machine option is selected. This means
that all run-time files—including result files and script files—are stored on
the Vuser load generators. The only exception is for Vusers running on the
local load generator (Controller machine), where you must use the shared
drive option.
2 To store script and result files on a shared network drive, click On a shared
network drive. To set the exact location on the network drive, see
Chapter 11, “Preparing to Run a Scenario.”
3 Click OK to close the dialog box.

181
Part II • Designing a Scenario

Understanding the Options - Run-Time File Storage Tab

The Run-Time File Storage tab lets you specify where LoadRunner saves run-
time files.

Scripts and results stored: Select one of the following options:

➤ On the current Vuser machine: Instructs the Controller to save the run-time
files on the computer that is running the Vuser script. On an NT-based
computer, the results are saved to the directory defined by the TEMP or TMP
environment variables. On a UNIX machine, the results are saved to the
directory defined by the TMPDIR environment variable. If the TMPDIR
environment variable is not defined, the results are saved to the /tmp
directory.

Note: If you choose to save result files on the Vuser load generators, you
must collate the results before you can perform any analysis. You can wait
for LoadRunner to collate the results when you launch the Analysis tool, or
you can collate results by selecting Results > Collate Results. Alternatively,
select Results > Auto Collate Results to automatically collate the results at
the end of each scenario run.

➤ On a shared network drive: Instructs the Controller to save the scenario

results and/or the Vuser scripts on a shared network drive. A shared network
drive is a drive to which the Controller and all the load generators in the
scenario have read and write permission. If you select to save results to a
shared network drive, you may need to perform path translation. Path
translation ensures that the specified results directory is recognized by the
remote load generator. For information about path translation see
Appendix B, “Performing Path Translation.”

182
 Chapter 10 • Configuring a Scenario

If you specify that all Vusers access their Vuser scripts directly at some
shared location, no transfer of script files occurs at run time. This alternative
method may be useful in either of the following situations:
➤ The file transfer facility does not work.
➤ The Vuser script files are large and therefore take a long time to transfer.
Remember that Vuser script files are transferred only once during a
scenario.

This alternate method often necessitates path translation. For details, see
Appendix B, “Performing Path Translation.”

Specifying Path Translation

If you specified a shared network drive for run-time file storage, (see “Setting
the Run-Time File Location” on page 179), you may need to perform path
translation. Path translation is a mechanism used by LoadRunner to convert
remote path names. A typical scenario may contain several load generator
machines that map the shared network drive differently. For more
information, see Appendix B, “Performing Path Translation.”

183
Part II • Designing a Scenario

184
11
Preparing to Run a Scenario

Before you run a scenario, you specify a location for the scenario results and
other run-time related settings.

This chapter describes:

➤ About Preparing to Run a Scenario

➤ Specifying a Results Location
➤ Results Directory File Structure
➤ Collating Results
➤ Setting Scenario Summary Information

About Preparing to Run a Scenario

Before you run a scenario, you need to specify the location of the results
(mandatory), assign a name to the results, schedule the scenario, and
provide scenario summary information. In addition, you can specify the
applications to invoke at the start of a scenario.

Although most of the pre-scenario settings are optional, using them can
enhance the testing process. These values are scenario-specific—you can set
different values for each LoadRunner scenario.

For information on one-time configuration settings such as timeout, output,

and quotas, see Chapter 10, “Configuring a Scenario.”

185
Part II • Designing a Scenario

Specifying a Results Location

When you run a scenario, by default the run-time files are stored locally on
each load generator. After the scenario, the results are collated together and
processed on the Controller machine. Alternatively, you can instruct
LoadRunner to save the results on a shared network drive. For information
about specifying a file storage method, see the Run-Time File Storage
settings in Chapter 10, “Configuring a Scenario.”

LoadRunner allows you to give descriptive names to each result set. This is
especially useful for cross results analysis, in which LoadRunner
superimposes the results of several scenario runs in a single graph and lets
you compare the results of multiple scenario runs. The descriptive graph
names enable you to distinguish between the results of the multiple runs.

In the example below, the results of two scenario runs are superimposed.
The result sets are res12, and res15.

For more details on cross result graphs, see the LoadRunner Analysis User’s
Guide.

186
 Chapter 11 • Preparing to Run a Scenario

Note: You can also use Mercury’s Web-based test management program,
Quality Center, to store results to a project. For information, see Chapter 12,
“Managing Scenarios Using Quality Center.”

To specify where results are stored:

1 Choose Results > Results Settings. The Set Results Directory dialog box
opens.

2 In the Results Name box, enter a name for the results. Avoid using the same
name with different paths, since the names will appear identical on the
graphs.
3 In the Directory box, type the full path of the results directory. If you are
using the default file storage setting (local machine), specify a directory in
which to store all of the collated results after the scenario run. If you
specified a shared network drive as the file storage method, specify the
directory to which Vuser groups should write during scenario execution.
4 Select the appropriate check box for subsequent executions: Automatically
create a results directory for each scenario execution or Automatically
overwrite existing results directory without prompting for confirmation.
5 Click OK to save the results directory setting.

187
Part II • Designing a Scenario

Understanding the Set Results Directory Dialog Box

The Set Results Directory dialog box lets you set the location in which the
Controller saves scenario results.

Note: If you have an open connection to a Quality Center project, the

Controller saves the results to a test set. You can also save the results directly
to disk using the standard file system.

Results Name: Specify a name for the results. The Controller saves the results
using the name that you specify.

Directory: Specify a location in the file system where the Controller will save
the results. Click Browse to find the desired location. The Controller creates
a subdirectory in the results directory. All results are saved within this
subdirectory.

Results Path: Displays the specified location for the results.

Automatically create a results directory for each scenario execution:

Instructs LoadRunner to create a unique results directory for each scenario
execution. By default, the result names are res1, res2, res3, etc.

Automatically overwrite existing results directory without prompting for

confirmation: Instructs LoadRunner to automatically overwrite previous
result sets, without prompting the user.

Quality Center (only when connected to Quality Center): Enables you to

save the results to a Quality Center test set.

File System (only when connected to Quality Center): Displays the default
LoadRunner directory path.

188
 Chapter 11 • Preparing to Run a Scenario

Results Directory File Structure

When you set the results directory, you also specify a results name.
LoadRunner creates a subdirectory using the results name, and places all of
the data it gathers in that directory. Every set of results contains general
information about the scenario in a result file (.lrr) and an event (.eve) file.

During scenario execution, LoadRunner creates a directory for each group in

the scenario and a subdirectory for each Vuser. A typical result directory has
the following structure:

Results directory
Results name
Event file
Collate file

Collate log file

Host event file
Offline data file
Definition file
Output database
Remote results file
Result file
Vuser cfg file
Vuser usp file
Vuser log directories
Summary data directory

➤ t_rep.eve in the main result directory contains Vuser and rendezvous

information.
➤ collate.txt contains the file paths of the result files, and Analysis collation
information.
➤ collateLog.txt contains the status (succeeded, failed) of result, diagnostics,
and log file collation from each load generator.
➤ local_host.eve contains information from each agent host.
➤ offline.dat contains sample monitor information.

189
Part II • Designing a Scenario

➤ *.def are definition files for graphs that describe the online and other
custom monitors.
➤ output.mdb is the database created by the Analysis (from the results files)
that stores the output information.
➤ remote_results.txt contains the file paths for the host event files.
➤ results_name.lrr is the LoadRunner Analysis document file.
➤ *.cfg files contain a listing of the script’s run-time settings as defined in the
VuGen application (think time, iterations, log, Web).
➤ *.usp files contain the script’s run logic, including how the actions sections
run.
➤ Log directory contains output information generated during replay for each
Vuser. A separate directory exists for each Vuser group that runs in the
scenario. Each group directory consists of Vusers subdirectories.
➤ Sum data directory. A directory containing the graph summary data (.dat)
files.

When you generate analysis graphs and reports, the LoadRunner Analysis
engine copies all of the scenario result files (.eve and .lrr) to a database.
Once the database is created, the Analysis works directly with the database
and does not use the result files.

For information on LoadRunner Analysis, see the LoadRunner Analysis User’s

Guide

190
 Chapter 11 • Preparing to Run a Scenario

Collating Results
When you run a scenario, by default all Vuser information is stored locally
on each load generator. After scenario execution, the results are
automatically collated or consolidated—results from all of the load
generators are transferred to the results directory. You set the location of the
results directory as described in “Specifying a Results Location” on page 186.

Note: If you have selected to store all the scenario results directly to a shared
network drive, then collation of the results is not required. See “About
Configuring a Scenario” on page 173 for details on changing how results are
stored.

To enable/disable automatic collation:

Choose Results > Auto Collate Results to enable automatic collation. When
this feature is enabled, the Auto Collate Results icon is displayed in the
status bar. To disable automatic collation, clear the check mark adjacent to
the option.

Note: If you are using the diagnostics modules, results must be collated even
if the load generator is localhost.

191
Part II • Designing a Scenario

To manually collate results:

Choose Results > Collate Results > Collate Results. The Collate Results dialog
box opens, and displays the progress of result, diagnostics, and log file
collation from each load generator.

General Status: The Collate Results files display the status and file size of the
Event, Diagnostics, and Log files.

Note: The file size shown is before compression. After compression, the
result files are smaller in size.

Progress Details: Displays the status (succeeded, failed) of result, diagnostics,

and log file collation from each load generator. This information is stored in
the collateLog.txt file.

192
 Chapter 11 • Preparing to Run a Scenario

Close automatically: Automatically close the Collate Results dialog box after
collation is completed.

To stop collating the results:

Click Stop and then Close. To resume collating the results, select
Results > Collate Results > Continue stopped collation.

Note: You can choose to disable log file collation. For more information, see
“Options - General Settings” on page 424.

The log and result directories are only deleted from a load generator once
LoadRunner successfully collates the results from the machine. You can
therefore close the Controller after saving a scenario, and collate the results
once you reopen the scenario in the Controller.

If collation fails due to a lack of disk space, select Results > Collate
Results > Recollate. LoadRunner attempts to collate the results again,
without compressing the .eve file.

Before generating the analysis data, LoadRunner automatically collates the

results if they were not previously collated.

Note: If you enabled the Auto Load Analysis option in the Results menu, the
Analysis may open during a lengthy collation process, displaying Analysis
summary data.

193
Part II • Designing a Scenario

Setting Scenario Summary Information

The Controller allows you to provide a detailed description of the scenario.
In addition, you can specify the author’s name and a subject title for the
scenario. Whenever you open this scenario, the summary information is
available to you.

You can open the Summary Information box from Scenario > Summary
Information.

Scenario Path: Displays the name and location of the scenario definition file
(.lrs).

Author: Enter the name of the scenario’s author.

Subject: Enter a subject name or short title for the scenario.

Description: Enter a description of the scenario.

194
12
Managing Scenarios Using Quality Center

LoadRunner’s integration with Quality Center lets you manage LoadRunner

scenarios using Quality Center. Quality Center helps you organize and
manage your scripts, scenarios, and results.

This chapter describes:

➤ About Managing Scenarios Using Quality Center

➤ Connecting to and Disconnecting from Quality Center
➤ Opening Scenarios from a Quality Center Project
➤ Saving Scenarios to a Quality Center Project
➤ Saving Results to a Quality Center Project
➤ Adding Vuser Scripts from a Quality Center Project

About Managing Scenarios Using Quality Center

LoadRunner works together with Quality Center, Mercury’s Web-based test
management tool. Quality Center provides an efficient method for storing
and retrieving scenarios and collecting results. You store scenarios and
results in a Quality Center project and organize them into unique groups.

For LoadRunner to access a Quality Center project, you must connect it to

the Web server on which Quality Center is installed. You can connect to
either a local or remote Web server.

For more information on working with Quality Center, refer to the Quality
Center User’s Guide.

195
Part II • Designing a Scenario

Connecting to and Disconnecting from Quality Center

If you are working with both LoadRunner and Quality Center, LoadRunner
can communicate with your Quality Center project. You can connect or
disconnect LoadRunner from a Quality Center project at any time during
the testing process.

Connecting LoadRunner to Quality Center

The connection process has two stages. First, you connect LoadRunner to a
local or remote Quality Center Web server. This server handles the
connections between LoadRunner and the Quality Center project.

Next, you choose the project you want LoadRunner to access. The project
stores scenarios and results for the application you are testing. Note that
Quality Center projects are password protected, so you must provide a user
name and a password.

To connect LoadRunner to Quality Center:

1 In the Controller, choose Tools > Quality Center Connection. The Quality
Center Connection dialog box opens.

196
 Chapter 12 • Managing Scenarios Using Quality Center

2 In the Server box, type the URL address of the Web server on which Quality
Center is installed.

Note: You can choose a Web server accessible via a Local Area Network
(LAN) or a Wide Area Network (WAN).

3 Click Connect. When the connection to the server is established, the server’s
name is displayed in read-only format in the Server box.
4 Enter the relevant information in the Project Connection section and click
Connect to connect LoadRunner to the selected project. When the
connection to the selected project is established, the project’s name is
displayed in read-only format in the Project box.
5 To automatically reconnect to the Quality Center server and the selected
project on startup, select the Reconnect on startup check box.
6 If you select Reconnect on startup, you can save the specified password to
reconnect on startup. Select the Save password for reconnection on startup
check box.
If you do not save your password, you will be prompted to enter it when
LoadRunner connects to Quality Center on startup.
7 Click Close to close the Quality Center Connection dialog box.
The status bar indicates that LoadRunner is currently connected to a Quality
Center project.

197
Part II • Designing a Scenario

Disconnecting LoadRunner from Quality Center

You can disconnect LoadRunner from a selected Quality Center project and
Web server.

To disconnect LoadRunner from Quality Center:

1 In the Controller, choose Tools > Quality Center Connection. The Quality
Center Connection dialog box opens.

2 To disconnect LoadRunner from the selected project, click Disconnect in the

Project Connection section.
3 To disconnect LoadRunner from the selected server, click Disconnect in the
Server Connection section.
4 Click Close to close the Quality Center Connection dialog box.

198
 Chapter 12 • Managing Scenarios Using Quality Center

Understanding the Quality Center Connection Dialog Box

The Quality Center Connection dialog box lets you open a connection to a
Quality Center project. Quality Center uses a project repository to help you
to organize and manage your scenarios, scenario results, and Vuser scripts.

Server Connection: Before you can work with a Quality Center project, you
must open a connection to the server that hosts the project.

➤ Server: Type the name of the server that hosts the Quality Center project.
➤ Connect: Connects to the specified server.
Project Connection: After connecting the Controller to the Quality Center
Database Server, enter the domain name, select a project, and enter the user
name and password for the project. The project stores scenario execution
information.

➤ Domain: Enter the domain name.

➤ Project: Select the project to which you want to connect. The list
includes all projects that are registered with the selected server.
➤ User Name: Enter your user name.
➤ Password: Enter your user password.
➤ Connect: Connects to the selected project.
Reconnect on startup: When selected, LoadRunner automatically opens the
connection to the Quality Center server and the specified project when you
start the Controller.

Save password for reconnection on startup: When selected, the Controller

saves the specified password in the registry to automate the login process.

199
Part II • Designing a Scenario

Opening Scenarios from a Quality Center Project

When LoadRunner is connected to a Quality Center project, you can open
your scenarios from Quality Center. You locate tests according to their
position in the test plan tree, rather than by their actual location in the file
system.

To open a scenario from a Quality Center project:

1 Connect to the Quality Center server (see “Connecting LoadRunner to
Quality Center” on page 196).
2 In the Controller, choose File > Open or click File Open. The Open Scenario
from Quality Center Project dialog box opens and displays the test plan tree.

To open a scenario directly from the file system, click File System. The Open
Scenario dialog box opens. (From the Open Scenario dialog box, you may
return to the Open Scenario from Quality Center Project dialog box by
clicking Quality Center.)

200
 Chapter 12 • Managing Scenarios Using Quality Center

3 Click the relevant subject in the test plan tree. To expand the tree and view
sublevels, double-click closed folders. To collapse the tree, double-click open
folders.
Note that when you select a subject, the scenarios that belong to the subject
appear in the Test Name list.
4 Select a scenario from the Test Name list. The scenario appears in the read-
only Test Name box.
5 Click OK to open the scenario. LoadRunner loads the scenario. The name of
the scenario appears in the Controller’s title bar. The Design tab shows the
scripts, the load generators, the Vusers, and the Vuser groups in the scenario.

Note: You can also open scenarios from the recent scenarios list in the File
menu. If you select a scenario located in a Quality Center project, but
LoadRunner is currently not connected to that project, the Quality Center
Connection dialog box opens. Enter your user name and password to log in
to the project, and click OK.

Saving Scenarios to a Quality Center Project

When LoadRunner is connected to a Quality Center project, you can create
new scenarios in LoadRunner and save them directly to your project. To save
a scenario, you give it a descriptive name and associate it with the relevant
subject in the test plan tree. This helps you to keep track of the scenarios
created for each subject and to quickly view the progress of test planning
and creation.

To save a scenario to a Quality Center project:

1 Connect to the Quality Center server (see “Connecting LoadRunner to
Quality Center” on page 196).

201
Part II • Designing a Scenario

2 In the Controller, choose File > Save As. The Save Scenario to Quality Center
Project dialog box opens and displays the test plan tree.

To save a scenario directly in the file system, click File System. The Save
Scenario dialog box opens. (From the Save Scenario dialog box, you may
return to the Save Scenario to Quality Center Project dialog box by clicking
Quality Center.)
3 Select the relevant subject in the test plan tree. To expand the tree and view
a sublevel, double-click a closed folder. To collapse a sublevel, double-click
an open folder.
4 In the Test Name box, enter a name for the scenario. Use a descriptive name
that will help you easily identify the scenario.
5 Click OK to save the scenario and close the dialog box.
The next time you start Quality Center, the new scenario will appear in
Quality Center’s test plan tree.

202
 Chapter 12 • Managing Scenarios Using Quality Center

Saving Results to a Quality Center Project

Before you run a scenario, you set the results location. When LoadRunner is
connected to a Quality Center project, results are saved to a test set. You can
also save the results to disk using the standard file system.

To save results to a Quality Center project:

1 Connect to the Quality Center server (see “Connecting LoadRunner to
Quality Center” on page 196).
2 In the Controller, choose Results > Results Settings. The Set Results
Directory dialog box opens.

3 Click Quality Center. The Directory box changes to Test Sets.

4 In the Results Name box, enter a name for the results.

5 In the Test Sets list, accept the default test set name or select a different
name.

203
Part II • Designing a Scenario

6 Select the appropriate check box:

➤ Automatically create a results directory for each scenario execution:
Instructs LoadRunner to create a unique results directory for each
scenario execution. By default, the result names are res1, res2, res3, etc.
➤ Automatically overwrite existing results directory without prompting for
confirmation: Instructs LoadRunner to automatically overwrite previous
result sets, without prompting the user.
7 Click OK to save the results settings.

Adding Vuser Scripts from a Quality Center Project

You can add Vuser scripts from a Quality Center project to the Controller’s
script list. You can add the script to either a manual or a goal-oriented
scenario.

Adding a Vuser Script to a Manual Scenario

When you create a manual scenario, you use the Add Group dialog box to
add Vuser scripts.

To add a Vuser script to a manual scenario:

1 Connect to the Quality Center server (see “Connecting LoadRunner to
Quality Center” on page 196).

204
 Chapter 12 • Managing Scenarios Using Quality Center

2 In the Scenario Groups pane, click the Add Group button. The Add Group
dialog box opens.

3 Click Browse. The Open Test from Quality Center Project dialog box opens
and displays the test plan tree.
4 Select the script and click OK. The Script Path field displays [TD], the full
subject path, and the script name. For example:
[TD]\Subject\System\test_qc
5 Click OK to close the Add Group dialog box. The script is displayed in the
Scenario Groups pane.

205
Part II • Designing a Scenario

Adding a Vuser Script to a Goal-Oriented Scenario

When you create a goal-oriented scenario, you use the Add Script dialog box
to add scripts.

To add a Vuser script to a goal-oriented scenario:

1 Connect to the Quality Center server (see “Connecting LoadRunner to
Quality Center” on page 196).
2 In the Scenario Scripts pane, click the Add Script button. The Add Script
dialog box opens.

3 Click Browse. The Open Test from Quality Center Project dialog box opens
and displays the test plan tree opens.
4 Select the script and click OK. The Script Path field displays [TD], the full
subject path, and the script name. For example:
[TD]\Subject\System\test_qc
5 Click OK to close the Add Script dialog box. The script appears in the Script
Path column in the Scenario Scripts pane.

206
 Part III
Executing a Scenario
208
13
Running a Scenario

When you run a scenario, LoadRunner generates load on the application

you are testing, and measures the system’s performance.

This chapter describes:

➤ About Running a Scenario

➤ Running an Entire Scenario
➤ Controlling Vuser Groups
➤ Controlling Individual Vusers
➤ Manually Releasing Vusers from a Rendezvous
➤ Manually Adding Vusers to a Running Scenario

About Running a Scenario

When you run a scenario, the Vuser groups are assigned to their load
generators and execute their Vuser scripts. During scenario execution,
LoadRunner:

➤ records the durations of the transactions you defined in the Vuser scripts
➤ performs the rendezvous included in the Vuser scripts
➤ collects error, warning, and notification messages generated by the Vusers

You can run an entire scenario unattended, or you can interactively select
the Vuser groups and Vusers that you want to run. When the scenario starts
running, the Controller first checks the scenario configuration information.
Next, it invokes the applications that you selected to run with the scenario.

209
Part III • Executing a Scenario

Then, it distributes each Vuser script to its designated load generator. When
the Vuser groups are ready, they start executing their scripts.

While the scenario runs, you can monitor each Vuser, view the error,
warning, and notification messages generated by the Vusers, and stop both
Vuser groups and individual Vusers. You can instruct LoadRunner to allow
an individual Vuser or the Vusers in a group to complete the iterations they
are running before stopping, to complete the actions they are running
before stopping, or to stop running immediately. For more information, see
“Configuring Scenario Run-Time Settings” on page 177.

Note: When automatically stopping Vusers in a goal-oriented scenario,

LoadRunner stops running the Vusers immediately.

You can also activate additional Vusers while the scenario is running, using
the Run/Stop Vusers dialog box. For more information, see “Manually
Adding Vusers to a Running Scenario” on page 222.

The scenario ends when all the Vusers have completed their scripts, when
the duration runs out, or when you terminate it.

The following procedure outlines how to run a scenario:

1 Open an existing scenario or create a new one.
2 Configure and schedule the scenario.
3 Set the results directory.
4 Run and monitor the scenario.

210
 Chapter 13 • Running a Scenario

Running an Entire Scenario

You can run all the Vusers and Vuser groups in a scenario, or you can select
the specific Vuser groups and Vusers that you want to run. Note that when
you run an entire scenario, LoadRunner does not begin running Vusers until
they all have reached the Ready state. However, if you run individual groups
or Vusers, LoadRunner runs each Vuser as soon as it reaches the Ready state.

The following section describes how to run an entire scenario. “Controlling

Vuser Groups” on page 212 and “Controlling Individual Vusers” on
page 219 describe how to manipulate Vuser groups and individual Vusers.

To run an entire scenario:

1 Open an existing scenario or create a new one. Select the Run tab. The
Scenario Groups pane appears in the top left corner of the screen.

2 Select Scenario > Start, or click Start Scenario. The Controller starts
initializing the Vusers and distributing them to their designated load
generators, where they begin to execute their Vuser scripts.

Note: The Controller begins running the scenario according to the start time
set in the Scenario Start dialog box.

211
Part III • Executing a Scenario

If you have not specified a results directory for the scenario, the Set Results
Directory dialog box opens.
During scenario execution, you can manipulate individual Vusers and Vuser
groups. This is described in “Controlling Vuser Groups” below and
“Controlling Individual Vusers” on page 219.
3 Select Scenario > Stop/Resume Ramp Up to stop the ramp up process. Select
it again to resume the ramping up of Vusers.
4 Select Scenario > Stop/Resume Ramp Down to stop the ramp down process.
Select it again to resume the ramping down of Vusers.
5 Select Scenario > Stop, or click Stop to terminate the scenario. If you
selected the Stop immediately option in the Run-Time Settings tab of the
Options dialog box, all of the Vusers in the scenario move to the Exiting
status.
If you selected the Wait for the current iteration to end before exiting or
Wait for the current action to end before exiting options in the Run-Time
Settings tab of the Options dialog box, the Vusers in the scenario move to
the Gradual Exiting status and exit the scenario gradually. To stop the Vusers
immediately, click Stop Now.
6 Select Scenario > Reset, or click Reset to reset all Vusers to their pre-scenario
Down status.

Controlling Vuser Groups

You can run an entire scenario as described above, or you can manipulate
individual Vuser groups in the scenario. This section describes how to
initialize, run, pause, stop and reset Vuser groups.

Initializing Vuser Groups

Initializing a Vuser group distributes the Vusers in the group to their
designated load generators so that they are ready to execute their script(s).
By initializing all of the Vusers in a group before running them, you can
ensure that they all begin executing the scenario at the same time.

To initialize a Vuser group:

1 Select the Vuser group or groups that you want to initialize.

212
 Chapter 13 • Running a Scenario

2 Click Initialize Vusers, or right-click the Vuser group or groups that you want
to initialize and select Initialize Group/s. The Vuser group’s status changes
from Down to Pending to Initializing to Ready. If a Vuser group fails to
initialize, the Vuser group status changes to Error.

Running Vuser Groups

Running a Vuser group tells the Vuser group to execute its script.

To run a Vuser group:

1 Select the Vuser group or groups that you want to run.
2 Click Run Vusers, or right-click the Vuser group or groups that you want to
run and select Run Group/s. The Vuser groups execute their scripts. If you
run a Vuser group in the Down or Error state, LoadRunner initializes and
then runs the Vuser group.

Note: You can instruct LoadRunner to randomly run only one Vuser in a
group by right-clicking the Vuser group and selecting Run One Vuser. A
Vuser script log opens, displaying run-time information about the Vuser. For
more information about the Vuser log, see “Viewing the Vuser Script Log”
on page 239.

Pausing Vuser Groups

Pausing a Vuser group temporarily stops script execution. The Pause
command changes the status of a Vuser group from Running to Paused.

Note: Pausing a Vuser group will affect its transaction response time.

To pause a Vuser:
1 Select the Vuser group or groups that you want to pause.
2 Select Pause from the right-click menu. The Vusers groups temporarily stop
script execution.

213
Part III • Executing a Scenario

Stopping Vuser Groups

Stopping a Vuser group stops script execution. If you stop a Vuser group, the
group still appears in the Vuser group list.

To stop a Vuser group:

1 Select the Vuser group or groups that you want to stop.
2 Click Stop Vusers, or right-click the Vuser group or groups and select Stop.
The Vuser groups stop executing their scripts immediately.
If you selected the Wait for the current iteration to end before exiting or
Wait for the current action to end before exiting options in the Run-Time
Settings tab of the Options dialog box and want to gradually stop a Vuser
group in the Run state, click the Gradual Stop button, or right-click the
Vuser group and select Gradual Stop. The Vusers in the group move to the
Gradual Exiting status and exit the scenario gradually.

Note: If the Vusers are not in the Run state, the Gradual Stop option is
disabled.

Resetting Vuser Groups

Resetting causes all of the Vusers in a group to revert to their pre-scenario
Down status.

To reset a Vuser group:

1 Select the Vuser group or groups that you want to stop.
2 Right-click the Vuser group or groups that you want to stop, and select
Reset. The Vuser groups revert to their pre-scenario Down status.

214
 Chapter 13 • Running a Scenario

Understanding the Run View Tab

The Run tab displays the Scenario Groups window, a scenario status
summary, and graphs with online information generated during script
execution.

Scenario Groups: Displays each Vuser group and its current status.

➤ Start Scenario: Instructs the Controller to start initializing the Vusers in

the scenario and distributing them to their designated load generators,
where they begin to execute their Vuser scripts.

Note: The Controller begins running the scenario at the time stipulated in
the Scenario Start dialog box.

We do not recommend changing the Time/Date and Time Zone settings on

the Controller and Load Generator machines during the load test run.

➤ Stop: Instructs the Controller to stop running the scenario. If you

selected the Stop immediately option in the Run-Time Settings tab of the
Options dialog box, all of the Vusers in the scenario move to the Exiting
status. If you selected the Wait for the current iteration to end before
exiting or Wait for the current action to end before exiting options in
the Run-Time Settings tab of the Options dialog box, the Vusers in the
scenario move to the Gradual Exiting status and exit the scenario
gradually.
➤ Stop Now: Instructs the Controller to stop running the scenario
immediately.
➤ Reset: Resets all the Vuser groups in the scenario to their pre-scenario
DOWN status.

➤ Vusers: Opens the Vusers dialog box, enabling you to view the status of
each of the Vusers in a Vuser group.
➤ Run/Stop Vusers: Opens the Run/Stop Vusers dialog box, enabling you to
activate additional Vusers.

215
Part III • Executing a Scenario

You can perform the following actions on individual Vuser groups in the
scenario by right-clicking a group in the Scenario Groups window:

➤ Renumber: Renumbers the Vusers in the group, changing their ID

numbers.
➤ Initialize Group/s: Distributes the Vusers in the group to their designated
load generators so that they are ready to execute their script. The Vuser
group’s status changes from Down to Pending to Initializing to Ready. If a
Vuser group fails to initialize, the Vuser group status changes to Error.

By initializing all of the Vusers in a group before running them, you can
ensure that they all begin executing the scenario at the same time.
➤ Run Group/s: The Vuser group executes its script(s). If you run a Vuser
group in the Down or Error state, LoadRunner initializes and then runs
the Vuser group.
➤ Run One Vuser: Instructs the Controller to randomly run one of the
Vusers in the Vuser group. Note that the Vuser Log opens, displaying run-
time information about the Vuser.
➤ Pause: Temporarily pauses scenario execution. The status of the Vuser
group changes from Running to Paused.

Note: Pausing a Vuser group will affect its transaction response time.

➤ Gradual Stop: Instructs the Controller to complete the current iteration

or action before stopping the Vuser group. Note that this option is only
available when the Vuser group is in the Run state, if you selected the
Wait for the current iteration to end before exiting or Wait for the
current action to end before exiting options in the Run-Time Settings tab
of the Options dialog box.
➤ Stop: Instructs the Controller to stop running the Vuser group
immediately.
➤ Reset Group/s: Resets all Vusers in the group to their pre-scenario Down
status.
➤ Enable: Enables the Vuser group to participate in the scenario.

216
 Chapter 13 • Running a Scenario

➤ Disable: Disables the Vuser group so that it no longer participates in the

scenario.
➤ Show Vuser: Opens a Run-Time Viewer for each Vuser in the group.
➤ Hide Vuser: Closes the Run-Time Viewers that were opened.
➤ Show Vuser Log: Opens a script log containing run-time information for
each Vuser in the group. The Vuser script log is refreshed, by default,
every 1000 milliseconds.
➤ Hide Vuser Log: Closes the Vuser script log(s).
➤ Sort By Name: Sorts the groups alphabetically, by name.
Scenario Status: Displays a synopsis of the running scenario. You can view
details of individual transactions and errors by clicking the icon.

Note: You can detach the Scenario Status window from the Run view by
clicking the button in the upper-right corner. This enlarges the Scenario
Groups window.

Graphs: To view a list of the available graphs, select View > Show Available
Graphs. To hide the graph tree view, select View > Hide Available Graphs, or
click the X button in the top right corner of the Available Graphs list.

To display a graph, click it in the left pane and drag it to the right pane. By
default, four graphs are displayed. To customize your online graph display,
click View > View Graphs and select the number of graphs you want to view.
You can view up to 16 graphs simultaneously. To display only one graph,
double-click the graph in the right pane. To return to the previous view,
double-click the graph again. Below the graphs, a legend displays the
statistics of the selected graph: color, scale, measurement/status, machine,
maximum, minimum, average, standard deviation, and last.

217
Part III • Executing a Scenario

You can perform the following actions on a graph by using the Monitors
menu or right-clicking the graph:

➤ Graph configuration
➤ Graph duplication
➤ Freeze/Release graph
➤ Export graph to HTML
➤ Overlay graphs
You can perform the following actions on a measurement by right-clicking
it:

➤ Add/Delete measurement
➤ Show/Hide measurement
➤ Measurement configuration
➤ Measurement description

218
 Chapter 13 • Running a Scenario

Controlling Individual Vusers

You can also manipulate individual Vusers within the Vuser groups you
have defined. This section describes how to initialize, run, and stop
individual Vusers.

To control an individual Vuser:

1 Select a Vuser group and click the Vusers button. The Vusers dialog box
opens with a list of the ID, Status, Script, Load Generator, and Elapsed Time
(since the beginning of the scenario) for each of the Vusers in the group.

You can control an individual Vuser using the following utilities:

➤ Select a Vuser and click Run to run it.
➤ Select a Vuser and click Stop to stop it immediately from running.
➤ If you selected the Wait for the current iteration to end before exiting or
Wait for the current action to end before exiting options in the Run-
Time Settings tab of the Options dialog box, and want to gradually stop a
Vuser in the RUN state, click the Gradual Stop button. The Vuser moves to
the Gradual Exiting status and exits the scenario gradually.

219
Part III • Executing a Scenario

➤ To pause a Vuser, right-click it and select Pause. Pausing a Vuser will

affect its transaction response time.
➤ To revert a Vuser’s status to DOWN, Select it and click Reset.
➤ To initialize a Vuser, right-click it and select Initialize Vuser/s.
➤ To renumber the Vusers in a group, right-click the Vusers you want to
renumber and select Renumber.
➤ To filter the Vusers listed, right-click in one of the columns and select
Filter Vusers. Select the way in which you want to filter the Vusers.
Alternatively, you can select the filter option you want to use from the
filter selector in the upper-right corner of the Vusers dialog box.
➤ To sort the Vusers listed, right-click in one of the columns and select Sort
Vusers. Select the way in which you want to sort the Vusers.
➤ To view a Vuser executing its assigned script, select the Vuser and click
the Show button. The Run-Time Viewer opens and displays snapshots of
the pages returned to a Vuser, allowing you to see the Vuser executing the
script. The Run-Time Viewer does not function as a browser, so the
displayed images are snapshots and do not present all aspects of the
replay.
➤ The Options menu items allow you to select the types of controls to
display.
➤ The View menu items allow you to open various toolbars and views.
➤ To close the Run-Time Viewer, click the Hide button.

220
 Chapter 13 • Running a Scenario

➤ To view the Vuser script log, click the Vuser log button. A script log, such
as the following, appears.

➤ To close the Vuser script log, click the Close button. For more
information on the Vuser script log, see page 239.
2 Click Close to close the Vusers dialog box.

Manually Releasing Vusers from a Rendezvous

While you run a scenario, you can manually release Vusers from a
rendezvous before the Controller releases them.

To manually release Vusers from a rendezvous:

1 Choose Scenario > Rendezvous. The Rendezvous Information dialog box
opens.
2 Select a rendezvous from the Rendezvous list.
3 Click Release. The Vusers in the rendezvous are released.

221
Part III • Executing a Scenario

Manually Adding Vusers to a Running Scenario

During a running scenario, you can manually control the addition of new
Vusers using the Run/Stop Vusers dialog box. The dialog box differs
depending on the scenario mode you are running:

➤ If you are running a scenario in the Vuser Group Mode, you control the
number of new Vusers that can be added to each Vuser Group, and the load
generators on which these additional Vusers will run.
➤ If you are running a scenario in the Percentage Mode, you control the
number of new Vusers that can be distributed among the Vuser scripts
according to the percentage you define, and the load generators on which
these additional Vusers will run.

Note: If you are running a scenario or Vuser group using Schedule Builder
settings, these settings will be applied to all Vusers that are manually added
to the scenario or Vuser group during the scenario run. For more
information, see “Adding Vusers to a Scheduled Scenario” on page 159.

To add Vusers to a running scenario:

1 Select Scenario > Run/Stop Vusers, or click Run/Stop Vusers in the Scenario
Groups pane of the Run view. The Run/Stop Vusers dialog box opens. If you
are in the Vuser Group Mode, the dialog box displays the Vuser groups
included in the scenario.

222
 Chapter 13 • Running a Scenario

If you are in the Percentage Mode, the Run/Stop Vusers dialog box displays
the Vuser scripts included in the scenario.

2 If you are in the Vuser Group Mode, enter the number of Vusers you want to
run for each group in the Quantity column.
If you are in the Percentage Mode, enter the number of Vusers and the
percentage in which you want these Vusers to be distributed among the
checked Vuser scripts. LoadRunner automatically distributes the number of
Vusers you entered.
3 To disable a Vuser group/script, clear the check box to the left of the
group/script name. Note that a group/script will automatically appear
disabled if it is disabled in the Design view.

Note: If you disable a Vuser group in the Vuser Group Mode, no Vusers will
be distributed to it. If you disable a Vuser script in the Percentage Mode, no
Vusers will be distributed to it, and the unused percentage of the Vusers will
not be distributed among the remaining scripts, unless you define a zero
percent value for the disabled script.

223
Part III • Executing a Scenario

4 To change the load generator on which the Vuser group/script will run,
select a different load generator from the Load Generator column.
To use a load generator that does not appear, select Add from the Load
Generator Name list. The Add New Load GEnerator dialog box opens. Add
the name, platform, and temporary directory of the new load generator and
click OK.

If you are in the Percentage Mode, you can select more than one load
generator to run the Vuser script. From the Load Generator Name list, select
the load generator(s) and click OK. To use all the load generators in the list,
click the All Generators button.

Note: If you defined more than one load generator for a script, the added
Vusers are proportionally distributed among the defined load generators.

5 Click Init to initialize the number of Vusers you added.

6 Click Run, and select a run option.
7 Click Stop to stop the Vusers that are running on the load generator(s)
defined in the Run/Stop Vusers dialog box.
8 Click Close to close the Run/Stop Vusers dialog box.

224
 Chapter 13 • Running a Scenario

Example of a Manually Controlled Scenario

The example below shows the Run/Stop Vusers dialog box from a scenario
running in the Percentage Mode.

The number of Vusers that are distributed among the checked scripts is 15.
The % column indicates that 60% of these Vusers are distributed to the
script flights2002, and 20% to both travel and test1. In accordance with
these percentages, the # column indicates that nine Vusers are distributed to
flights2002 and three to travel and test1.

Note: The unused percentage of the Vusers from the disabled test1 script are
not distributed among the remaining scripts, because a percentage value has
been defined for this script.

When an action (Init, Run, Stop) is selected from the Run/Stop Vusers dialog
box, the Controller runs only the number of Vusers that appear in the #
column. In this example, nine Vuser are initialized, run, or stopped in the
flights2002 script, and three in the travel script.

All Vusers distributed to the flights2002 script are run on the localhost load
generator. For the travel script, Vusers are proportionally distributed among
all defined load generators.

225
Part III • Executing a Scenario

Note: Load generator balancing is applied to a manually controlled scenario

in the Percentage Mode where there are other load generators assigned to
Vuser scripts. For more information, see “Load Balancing” on page 138.

Understanding the Run/Stop Vusers Dialog Box

The Run/Stop Vusers dialog box lets you manually activate additional
Vusers. This dialog box differs depending on whether you are running a
scenario in the Vuser Group Mode or in the Percentage Mode.

Specify a quantity of Vusers for every group: Enter the number of Vusers
you want to run for each group in the Quantity column "#" (Vuser Group
Mode).

Distribute X Vusers among the checked scripts: Enter the number of Vusers
you want to distribute by percentage among the checked Vuser scripts.
LoadRunner automatically distributes the number of Vusers you entered
(Percentage Mode).

Run/Stop Vusers table:

➤ Group/Script Name: Displays the names of the Vuser groups or scripts

running in the scenario.
➤ %: Indicates the percentage of Vusers distributed to each Vuser script
(Percentage mode only).
➤ #: Indicates the number of Vusers distributed to each Vuser script.
➤ Load Generators: Indicates the load generators on which the Vusers will
be run. Note that if more than one load generator is defined for a script,
the added Vusers are proportionally distributed among the defined load
generators.

226
 Chapter 13 • Running a Scenario

Note: To disable a Vuser group/script, clear the check box to the left of the
group/script name. Note that a group/script will automatically appear
disabled if it is disabled in the Design view.

If you disable a Vuser script, no Vusers will be distributed to it. However, 100
percent of the Vusers will not be distributed among the remaining scripts,
unless you define a 0 percent value for the disabled script.

Init: Distributes the Vusers that you added to their designated load
generators so that they are ready to execute their scripts. The Controller first
initializes the Vusers in your scenario that have not yet been run, on the
load generator(s) defined in the current dialog box. It then adds additional
Vusers, as required, to reach the quantity defined in the current dialog box.

Run: Select one of the following options:

➤ Run Initialized: Runs the Vusers in the scenario that have already been
initialized on the load generators defined in the current dialog box. The
Controller runs only those Vusers that have already been initialized,
regardless of their quantity.
➤ Run New: Runs the number of Vusers you specified. The Controller first
runs the Vusers in your scenario that have not yet been run, on the load
generator(s) defined in the current dialog box. It then adds additional
Vusers, as required, to reach the quantity defined in the current dialog
box.
Stop: Stops the Vusers that are running on the load generator(s) defined in
the current dialog box. The Controller stops the Vusers according to the
settings you defined in the “Configuring Scenario Run-Time Settings” on
page 177.

227
Part III • Executing a Scenario

228
14
Viewing Vusers During Execution

During scenario execution, you can view the actions that are performed by
Vusers.

This chapter describes:

➤ About Viewing Vusers During Execution

➤ Monitoring Vuser Status
➤ Viewing the Output Window
➤ Viewing the Vuser Script Log
➤ Logging Execution Notes
➤ Viewing the Agent Summary

About Viewing Vusers During Execution

LoadRunner lets you view Vuser activity during a scenario:

➤ On the Controller load generator machines, you can view the Output
window, monitor Vuser performance online, and check the status of Vusers
executing the scenario.
➤ On remote machines, you can view the Agent summary with information
about the active Vusers.

229
Part III • Executing a Scenario

Monitoring Vuser Status

During scenario execution, you can use the Scenario Groups pane in the
Run view to monitor the actions of all the Vusers and Vuser groups in the
scenario.

The Status field of each Vuser group displays the current state of each Vuser
in the group. The following table describes the possible Vuser states during a
scenario.

Status Description

Down The Vuser is down.

Pending The Vuser is ready to be initialized and is waiting for an

available load generator, or is transferring files to the load
generator. The Vuser will run when the conditions set in its
scheduling attributes are met.

Initializing The Vuser is being initialized on the remote machine.

Ready The Vuser already performed the init section of the script
and is ready to run.

Running The Vuser is running. The Vuser script is being executed on

a load generator.

Rendezvous The Vuser has arrived at the rendezvous and is waiting to be

released by LoadRunner.

Done. Passed The Vuser has finished running. The script passed.

Done. Failed The Vuser has finished running. The script failed.

Error A problem occurred with the Vuser. Check the Status field
in the Vuser dialog box or the output window for a
complete explanation of the error.

Gradual Exiting The Vuser is completing the iteration or action it is running

(as defined in Tools > Options > Run-Time Settings) before
exiting.

Exiting The Vuser has finished running or has been stopped, and is
now exiting.

Stopped The Vuser stopped when the Stop command was invoked.

230
 Chapter 14 • Viewing Vusers During Execution

You can also view a synopsis of the running scenario in the box in the
upper-right corner of the Run view.

Note: You can detach the Scenario Status window from the Run view by
clicking the button in the upper-right corner. This enlarges the Scenario
Groups pane.

Status Summary Description

Scenario Status indicates whether the scenario is RUNNING or DOWN

Running Vusers indicates how many Vusers are being executed on a

load generator machine

Elapsed Time indicates how much time has elapsed since the
beginning of the scenario

Hits/Second indicates how many hits (HTTP requests) there have

been to the Web site being tested per second that each
Vuser has been running

Passed Transactions indicates how many transactions have been executed

successfully

Failed Transactions indicates how many transactions have been executed

unsuccessfully

errors indicates how many problems have occurred with the

Vusers

231
Part III • Executing a Scenario

Transactions
You can view details of individual transactions in the Transactions dialog
box. To open Transactions dialog box, click the Show Snapshot button to
the right of the Passed Transactions or Failed Transactions in the Scenario
Status window.

Name: Lists the names of the individual transactions in a script.

TPS: Displays the number of transactions per second.

Passed: Lists the number of transactions that passed.

Failed: Lists the number of transactions that failed.

Stopped: Lists the number of transactions that stopped.

232
 Chapter 14 • Viewing Vusers During Execution

Viewing the Output Window

While the scenario runs, the Vusers and load generators send error,
notification, warning, debug, and batch messages to the Controller. You can
view these messages in the Output window.

LoadRunner clears the messages in the Output window at the start of each
scenario execution. If you reset a scenario, messages remain in the Output
window unless you instruct LoadRunner to delete messages from the Output
window upon reset. For more information, see “Options - Output Settings”
on page 428.

To view messages in the Output window:

1 Choose View > Show Output or click the Show Snapshot button to the right
of the Errors listing. The Output window opens, displaying error
information.

2 In the Type of Message box, select a message type to filter.

233
Part III • Executing a Scenario

3 To view a message in detail, select the message and click Details. The
Detailed Message Text box opens in the Output window displaying the
complete sample message text.

4 To view details of the log information by message, Vuser, script, or load

generator, click the blue link in the respective column. For more
information, see “Viewing Log Information Details” on page 235.

234
 Chapter 14 • Viewing Vusers During Execution

Viewing Log Information Details

You can view details of each message, Vuser, script, and load generator
associated with an error code by clicking the blue link in the respective
column. The Output window displays a drilled-down view by Vuser,
message, script, or load generator in the Filtered tab.

For example, if you drill down on the Vusers column, the Output window
displays all the messages with the code you selected, grouped by the Vusers
that sent the messages.

Note that the message type, the message code, and the column that you
selected to drill down on, are displayed above the grid.

You can drill down further on the entries displayed in blue. Note that when
you drill down on a Vuser, the Vuser log opens. When you drill down on a
load generator, the Load Generators dialog box opens, displaying the load
generator you selected. When you drill down on a script (or Action or Line
Number), VuGen opens, displaying the script you selected.

235
Part III • Executing a Scenario

Note: To limit the number of rows displayed when you drill down, open the
wlrun7.ini file in any text editor, and located the following line:
MaxOutputUIRowsToShow=0
Change the 0 (no limit) to the number of rows you want to view.

When new messages arrive in the Output window, the Refresh button is
enabled. Click Refresh to add the new log information to the Filtered tab
view.

To move between the various drill down levels, click the Previous view and
Next view buttons in the upper-left corner of the Output window.

Understanding the Output Window

Displays information about the error, notification, warning, debug, and
batch messages that Vusers and load generators send to the Controller
during scenario execution. Note that the total number of messages sent is
displayed in the title bar.

Note: You can also specify

the maximum number of Vuser logs that may
be displayed simultaneously on the Controller machine. For more
information, see Appendix C, “Working in Expert Mode.”

Summary Tab
The Summary tab displays summary information about the messages sent
during scenario execution. To view details of each message, Vuser, script,
and load generator associated with an error code, click the blue link in the
respective column.

236
 Chapter 14 • Viewing Vusers During Execution

Type of Message: Filters the output messages to display only certain

message types. Select one of the following filters:

Icon Message Type Description

All Messages Displays all message types.

Notifications Provides run-time information, such as

messages sent using lr_output_message.

Errors Usually indicate that the script failed.

Warnings Indicates that the Vuser encountered a

problem, but test execution continued.

Debug Will be sent only if you enable the debugging

feature in Tools > Options > Debug
Information (Expert Mode). See Options -
Debug Information Tab (Expert Mode Only)
for more information.

Batch Sent instead of message boxes appearing in

the Controller, if you are using automation.

Details: Displays the full text of the selected output message in the Output
window.

Export the view: Saves the Output view to a specified file.

Remove all messages: Clears all log information from the Output window.

Freeze/Resume: Stops updating the Output window with messages. To

instruct LoadRunner to resume updating the Output window, click Resume.
The newly updated log information is displayed in a red frame.

Message Code: Displays the code assigned to all similar messages. The
number in parentheses indicates the number of different codes displayed in
the Output window.

Sample Message Text: Displays an example of the text of a message with the
specified code.

237
Part III • Executing a Scenario

Total Messages: Displays the total number of sent messages with the
specified code.

Vusers: Displays the number of Vusers that generated messages with the
specified code.

Scripts: Displays the number of scripts whose execution caused messages

with the specified code to be generated.

Generators: Displays the number of load generators from which messages

with the specified code were generated.

Note: To sort the log information, click the appropriate column header. The
messages are sorted in descending/ascending order.

Filtered Tab
The Filtered tab displays a drilled down view by Vuser, message, script, or
load generator. For example, if you drill down on the Vusers column, the
Filtered tab displays all the messages with the code you selected, grouped by
the Vusers that sent the messages.

Previous view/Next view: Enables you to move between the various drill
down levels.

<Type of Message Icon>: Displays an icon indicating the type of message by

which the current Output view is filtered.

Active Filter: Displays the category or categories by which the current

Output view is filtered.

Viewed by: Displays the name of the column on which you selected to drill
down.

Export the view: Saves the Output view to a specified file.

Refresh: Adds new log information that arrived in the Output window to
the Filtered tab view.

238
 Chapter 14 • Viewing Vusers During Execution

Viewing the Vuser Script Log

During scenario execution, you can view a log containing run-time
information about each running Vuser.

To view the Vuser script log for a particular Vuser:

1 In the Vusers dialog box, select the Vuser whose log you want to view, and
click Show Vuser Log, or right-click the Vuser and select Show Vuser Log.
The Vuser script log opens, displaying run-time information about the
Vuser. This information is refreshed, by default, every 1000 milliseconds.

To change the default refresh settings, see “Options - Output Settings” on

page 428.

2 Click Close to close the Vuser script log.

239
Part III • Executing a Scenario

Understanding the Vuser Script Log

The Vuser Script Log displays run-time information about the Vuser. This
information is refreshed, by default, every 1000 milliseconds.

Note: If you disabled the logging feature in the Run-Time Settings Log tab,
the Vuser script log will contain output only if your script contains the
lr_output_message or lr_message function. If you selected the Send
messages only when an error occurs option in the Log tab, the Vuser script
log will contain output only if there are script errors.

Show Text View: Displays the run-time information in text format. To revert
to the tree view, click the same button again.

Show Tree View: Displays the run-time information in tree format. To revert
to the text view, click the same button again.

Display: Displays a snapshot of the Web page where an error occurred, when
the error is highlighted in the Vuser log.

Note: To view a snapshot of the Web page where an error occurred, you
must select the Activate snapshot on error option in the General tab of the
Run-Time Settings dialog box before running the scenario.

Find Text: Enter the text you want to search for in the Vuser log.

Expand Node: Expands the node so that you can view additional run-time
information details about the Vuser. To revert to the collapsed tree view,
click this button again.

Collapse Node: Collapses the node. To revert to the expanded tree view,
click this button again.

240
 Chapter 14 • Viewing Vusers During Execution

Refresh (every 1000 milliseconds): Instructs LoadRunner to refresh the run-

time information displayed every 1000 milliseconds. Clear the Refresh
check box to disable the log refreshing.

Note: You can change the default refresh settings in the “Options - Output
Settings” on page 428.

Copy: Enables you to copy text from the Vuser log. Right-click the selected
text in the Vuser log, and select Copy.

Copy path from status bar: Enables you to copy the path of the Vuser log.
Right-click the path in the status bar, and select Copy path from status bar.

Vuser Log Message Icons:

Start User Script: Indicates the start of the virtual user script.

Start Iteration: Indicates the start of an iteration.

End Iteration: Indicates the end of an iteration.

Start/End Transaction: Indicates the start or the end of a transaction.

Action: Displays the name and description of an action.

Notifications: Provides action information.

Errors: Indicates that the Vuser encountered a problem, but test execution
continued. Displays the error code and a description of the error.

241
Part III • Executing a Scenario

Logging Execution Notes

The Controller provides you with a dialog box in which you can log
comments while a scenario is running.

To log execution notes:

1 Select Scenario > Execution Notes. The Execution Notes dialog box opens.
2 Enter the note or notes that you want to log.
3 Click OK to close the dialog box. LoadRunner saves the note(s) you
recorded.

242
 Chapter 14 • Viewing Vusers During Execution

Viewing the Agent Summary

When you run a scenario with non-GUI Vusers, the machine running the
Vusers invokes an agent that controls the Vuser execution on that load
generator. During scenario execution, the agent displays a summary of the
Ready, Running, and Paused Vusers.

The Agent window opens at the start of the scenario. You can minimize and
restore it at any time.

243
Part III • Executing a Scenario

244
 Part IV
Working with Firewalls
246
15
Using Firewalls in LoadRunner

You can run Vusers and monitor your servers within a firewall, while the
Controller is outside of the firewall.

This chapter describes:

➤ About Using Firewalls in LoadRunner

➤ Configuring Your System
➤ Overview of Running or Monitoring Vusers over a Firewall
➤ Checking Connectivity

About Using Firewalls in LoadRunner

Working with a firewall means that you can prevent unauthorized access to
or from a private network, on specific port numbers.

For example, you can specify that there is no access to any port from the
outside world, with the exception of the mail port (23), or you can specify
that there is no outside connection to any ports except for the mail port and
WEB port (80). The port settings are configured by the system administrator.

247
Part IV • Working with Firewalls

In a regular LoadRunner scenario (not over the firewall), the Controller has
direct access to the LoadRunner agents running on remote machines. This
enables the Controller to connect directly to those machines.

When running Vusers or monitoring servers over the firewall, this direct
connection is blocked by the firewall. The connection cannot be established
by the Controller, because it does not have permissions to make an opening
in the firewall.

LoadRunner solves this problem by using a communication mechanism

based on HTTPS or secured TCP/IP that uses the standard SSL port on the
firewall (port 443). For more information on HTTPS and TCP/IP system
configuration, see “Configuring Your System” on page 250.

A LoadRunner agent is installed inside the firewall on either load generator

machines running Vusers, or on agent machines acting as mediators for the
servers to be monitored (referred to as “mediators”). The agent
communicates with the Mercury Interactive listener machine, MI Listener,
through port 443 in the firewall.

248
 Chapter 15 • Using Firewalls in LoadRunner

The MI Listener is a component that serves as router between the Controller

and the LoadRunner agent.

When the LoadRunner agent makes a connection to the MI Listener, the MI

Listener keeps a listing of the connection to the agent using a symbolic
name that the agent passed to it. When the Controller connects to the MI
Listener, it communicates to the MI Listener through port 50500.

The Controller uses a symbolic name for the agent, and gives the MI
Listener machine’s name. If there has been a connection from the agent
with the same symbolic name to this MI Listener, the connection is made.
Once you have a connection with the agent, you can run or monitor Vusers
over a firewall.

249
Part IV • Working with Firewalls

Configuring Your System

To run Vusers or monitor servers over the firewall, configure your system
according to the HTTPS or secured TCP/IP configuration. Note that these
configurations contain a firewall on each LAN. There may also be
configurations where there is a firewall only for LAN1.

TCP Configuration
The TCP configuration requires every LoadRunner agent machine behind
the firewall to be allowed to open a port in the firewall for outgoing
communication.

250
 Chapter 15 • Using Firewalls in LoadRunner

HTTPS Configuration
In the HTTPS configuration, only one machine (the proxy server) is allowed
to open a port in the firewall. Therefore it is necessary to route all outgoing
communications through the proxy server.

Note: You can connect the Controller to load generators over a firewall
without using the MI Listener and LoadRunner agent. To do so, open port
54345 on a firewall in the load generator’s LAN and in the Controller’s LAN
to allow incoming and outgoing data.

251
Part IV • Working with Firewalls

Overview of Running or Monitoring Vusers over a Firewall

The ability to run Vusers and monitor servers over a firewall is critical for
successful load testing. To prepare LoadRunner for running Vusers or
monitoring servers over the firewall, perform the relevant installation,
configuration, and connection procedures. These procedures are explained
in detail in Chapter 16, “Running Vusers Over a Firewall” and Chapter 17,
“Monitoring Over a Firewall”. Note that procedures 4 and 8 are required
only if you are monitoring over a firewall.

1 Install the LoadRunner agent on the machines running Vusers, or on

the servers to be monitored inside the firewall.
Check that the agent is installed on the machines running Vusers, or on the
servers to be monitored inside the firewall. LoadRunner agents can run on
Windows or Unix machines. See “Installing LoadRunner Agents Inside the
Firewall” on page 259.
2 Configure the LoadRunner agent to operate over the firewall.
Configure the LoadRunner agent on the machines running Vusers, or acting
as mediators for the servers to be monitored. See “Configuring LoadRunner
Agents Inside the Firewall” on page 260 for instructions.
3 Configure the firewall(s).
Configure the firewall to allow communication between the agents inside
the firewall, and the machines outside the firewall. See “Configuring the
Firewall to Allow Agent Access” on page 269.
4 Install the Monitoring over Firewall Component (monitoring over a
firewall only).
To monitor a server over the firewall, install this component on the agent
machine that sits inside the firewall. This machine acts as a mediator
between the Controller and the monitored server. See the diagrams in
“Configuring Your System” on page 250 for information about where to
install the Monitoring over the Firewall component. For configuration
instructions, see “Installing Monitors over Firewall” on page 276.

252
 Chapter 15 • Using Firewalls in LoadRunner

5 Install the MI Listener on a machine outside the firewall.

For information about installing the MI Listener, refer to the LoadRunner
Installation Guide. See the diagrams in “Configuring Your System” on
page 250 for information about where to install the MI Listener.
6 Configure the MI Listener machines.
Configure the security attributes on each MI Listener machine. See
“Installing and Configuring the MI Listener Outside the Firewall” on
page 270.
7 Configure the Controller machine.
Configure the Controller machine to recognize the agent and MI Listener
machines. See “Configuring the Controller to Run or Monitor Vusers over a
Firewall,” on page 272.
8 Configure Server Monitor Properties (monitoring over a firewall only).
Configure the Server Monitor Properties and measurement frequency. See
“Configuring Server Monitor Properties” on page 277, “Adding and
Removing Measurements” on page 280, and “Configuring Measurement
Frequency” on page 281.

253
Part IV • Working with Firewalls

Checking Connectivity
To run Vusers or monitor servers over a firewall, you must be able to
establish a connection between the LoadRunner agent, MI Listener, and the
Controller machine.

If you encounter connectivity problems after installing and configuring all

the necessary components, check the table below for troubleshooting tips.

Check Solution

To check that the Firewall There should be a traffic light on the right
service was activated on the side of the LoadRunner Agent icon on the
agent machine: machine running/ monitoring Vusers over a
firewall. If there is no traffic light, this
indicates that the ‘FirewallServiceActive=1’ is
not set in the [FireWall] section of the Agent
Settings. See “Configuring and Running the
Windows LoadRunner Agent” on page 260.

To check that port 443 is On the agent machine, open a Command

open: Prompt window, and type the following:
telnet <MI_Listener_IP>443.
For example: telnet 111.111.111.1111 443.
If port 443 is open, a new Telnet window will
open. If port 443 is not open, contact your
network administrator.

Note: Running Vusers over a firewall requires

bi-directional communications. Therefore,
you must also run this test from the MI
Listener. Type: telnet <agent_IP>443.

To check that port 443 is If a Web server is running on the MI Listener

available: or Monitor over Firewall machine, port 443
will not allow the access required by the
listening and monitoring processes. Contact
your network administrator to change the
Web server port.

254
 Chapter 15 • Using Firewalls in LoadRunner

Check Solution

To check connectivity If there is a red light on the right side of the

between the agent and the MI LoadRunner Agent icon when running the
Listener, when running the LoadRunner agent as a service, do the
LoadRunner agent as a following:
service:
• Check that port 443 is open. See the
troubleshooting tip above.
• Check that the Agent Settings and Agent
Configuration are correctly set. See
“Configuring and Running the Windows
LoadRunner Agent” on page 260.
• Run the agent as a Process. Launch
<LoadRunner
Installation>\Launch_service\bin\magent
proc.exe. If this works, this indicates an
authentication issue with the LoadRunner
Agent Service. Browse to the Service >
LoadRunner Agent Service, and change
the properties of this service to ‘System
User Account’ or provide the username
and password of someone who has
administrative privileges on this machine.

255
Part IV • Working with Firewalls

Check Solution

To check connectivity • Check that you entered the servers that

between the agent and the you want to monitor in the Monitor
Controller, when monitoring Configuration dialog box. (See
over a firewall “Configuring Server Monitor Properties”
on page 277).
• Start the LoadRunnerAgent Process on the
mediator machine. (See “Configuring
LoadRunner Agents Inside the Firewall”
on page 260).
• On the Controller, enter the name of the
mediator machine in the Load Generators
dialog box, and click Connect. After about
a minute, data should start streaming in
from the mediator through the MI
Listener to the Controller. (See
“Configuring the Controller to Run or
Monitor Vusers over a Firewall,” on
page 272).
• If no data arrives at the Controller, try
connecting the Controller to the MI
Listener as if the Listener were used as a
load generator. This will help identify the
cause of the problem. Examine the log file
on the mediator machine by right-clicking
the LoadRunnerAgent icon. There should
be no error messages.
• Start the MI Listener, and then manually
start the LoadRunnerAgent Process by
running <LoadRunner
installation>\launch_service\bin\magnet
proc.exe on the mediator machine. Allow
the mediator machine sufficient time to
connect to the MI Listener, then connect
the Controller to the mediator machine. If
the LoadRunnerAgent Process crashes,
either restart the agent or reboot the
mediator machine.

For additional firewall troubleshooting, see “Troubleshooting Firewalls” on

page 450.

256
16
Running Vusers Over a Firewall

LoadRunner enables you to run Vusers over a firewall while the Controller is
outside of the firewall.

This chapter describes:

➤ About Running Vusers Over a Firewall

➤ Overview of Running Vusers Over a Firewall
➤ Installing LoadRunner Agents Inside the Firewall
➤ Configuring LoadRunner Agents Inside the Firewall
➤ Configuring the Firewall to Allow Agent Access
➤ Installing and Configuring the MI Listener Outside the Firewall
➤ Configuring the Controller to Run or Monitor Vusers over a Firewall

About Running Vusers Over a Firewall

To prepare LoadRunner for running Vusers over the firewall, perform all the
procedures in “Overview of Running Vusers Over a Firewall” on page 258.
To enable monitoring of your servers from outside the firewall, you must
also complete the procedures in Chapter 17, “Monitoring Over a Firewall”.

For a complete overview of the installation, configuration, and connection

requirements when working with firewalls, see “Overview of Running or
Monitoring Vusers over a Firewall” on page 252.

257
Part IV • Working with Firewalls

Overview of Running Vusers Over a Firewall

1 Install the LoadRunner agent on the machines running Vusers inside
the firewall.
See “Installing LoadRunner Agents Inside the Firewall” on page 259.
2 Configure the LoadRunner agent to operate over the firewall.
See “Configuring LoadRunner Agents Inside the Firewall” on page 260.
3 Configure the firewall(s) to allow communication between the agents
inside the firewall, and the machines outside the firewall.
See “Configuring the Firewall to Allow Agent Access” on page 269.
4 Install the MI Listener on a machine outside the firewall.
For installation information, refer to the LoadRunner Installation Guide.
5 Configure the security attributes on each MI Listener machine.
See “Installing and Configuring the MI Listener Outside the Firewall” on
page 270.
6 Configure the Controller machine to recognize the agent and MI
Listener machines.
See “Configuring the Controller to Run or Monitor Vusers over a Firewall,”
on page 272.

258
 Chapter 16 • Running Vusers Over a Firewall

Installing LoadRunner Agents Inside the Firewall

To run or monitor Vusers over a firewall, a LoadRunner agent must be
installed on the load generator machines running Vusers, or on the servers
to be monitored inside the firewall. The agent is added either as a Windows
service or as an executable run from the Startup folder.

Running Vusers over a Firewall

A LoadRunner agent may already be installed on load generator machines
inside the firewall if you ran the Load Generator installation from setup.
Click Start > Programs > Mercury LoadRunner > LoadRunner Agent
Service/Process to check whether it is installed. If Agent Service or Agent
Process appears on the list of LoadRunner options, then the agent was
already installed.

If there is no agent installed, install the Load Generator component from

the LoadRunner installation CD on the machine(s) running Vusers inside
the firewall. See the diagrams in “Configuring Your System” on page 250 for
information about where to install the Load Generator component.

Monitoring over a Firewall

Install the Monitors over Firewall component on the servers to be
monitored inside the firewall. For more information, see “Installing
Monitors over Firewall” on page 276. See the diagrams in “Configuring Your
System” on page 250 for information about where to install the Monitors
over the Firewall component.

259
Part IV • Working with Firewalls

Configuring LoadRunner Agents Inside the Firewall

The machines inside the firewall can either be Load Generator machines
running Vusers, or mediator machines connected to the servers to be
monitored by the Controller. You configure the LoadRunner agents inside
the firewall to operate over the firewall. The Controller machine resides
outside the firewall.

Configuring and Running the Windows LoadRunner Agent

To configure the LoadRunner agent on Windows machines:
1 Stop the LoadRunner agent by right-clicking its icon in the system tray and
selecting Close.
2 Run Agent Configuration from Start > Programs > Mercury
LoadRunner > Advanced Settings, or run <LoadRunner
root>\launch_service\bin\AgentConfig.exe.
3 Select the Enable Firewall Agent check box, and then click Settings.

260
 Chapter 16 • Running Vusers Over a Firewall

The Agent Configuration dialog box opens.

4 Set each option as described in “Agent Configuration Settings” on page 266.

5 Click OK to save your changes, or Cancel to cancel them.
6 Restart the LoadRunner agent by double-clicking the shortcut on the
desktop, or from Start > Programs > Mercury LoadRunner > LoadRunner
Agent Service/Process.
7 Check the connection status between the LoadRunner agent and the MI
Listener.
A green light illuminated next to the LoadRunner Agent icon in the system
tray indicates a successful connection between the LoadRunner agent and
the MI Listener. A red light indicates that there is no connection between
the agent and the MI Listener.

261
Part IV • Working with Firewalls

Configuring and Running the UNIX LoadRunner Agent

To configure the LoadRunner agent on UNIX machines:
1 Open <LoadRunner root folder>/dat/br_lnch_server.cfg in a text editor.
2 In the Firewall section, set FireWallServiceActive to 1 and save your changes.
3 Run agent_config from the <LoadRunner root folder>/bin directory to
display the following menu:

4 Enter 1 to display the current settings:

262
 Chapter 16 • Running Vusers Over a Firewall

5 To change a setting, enter 2 to display the settings menu:

Enter the setting and continue according to the menu instructions. Set each
option according to the “Agent Configuration Settings” on page 266.

Examples of Changing Agent Settings in UNIX

To change the MI Listener Name:
1 Enter 1 in the Settings menu to display the following screen:

Line 1 is a description of the setting. Line 2 shows the current value of the
setting.

263
Part IV • Working with Firewalls

2 Enter the new value, (for example, bunji) to display the following:

3 To keep the new value and return to the menu, enter 1.

To discard the new value and return to the menu, enter 2.
To discard the new value and change the setting once more, enter 3.

To change the Connection Type:

1 Enter 4 in the Settings menu to display the following screen:

Line 1 is a description of the setting. Line 2 shows the current value of the
setting.
2 Enter 1 to set the connection type to TCP, or enter 2 to set it to HTTP and
display the following:

3 To keep the new value and return to the menu, enter 1.

To discard the new value and return to the menu, enter 2.

264
 Chapter 16 • Running Vusers Over a Firewall

Viewing the Settings and Restarting the Agent

To view the current settings:
1 Return to the main menu by entering 1.
2 Enter 1 to display the settings. The following example includes the new
settings for MI Listener Name and Connection Type:

3 To save your changes, enter 3 from the main menu.

To cancel your changes, enter 4.
To use the default values supplied by LoadRunner (as described in “Agent
Configuration Settings” on page 266), enter 5.

265
Part IV • Working with Firewalls

To start or remove the LoadRunner agent:

1 To start the LoadRunner agent, run the command m_daemon_setup -install
from the <LoadRunner root folder>/bin directory.
2 To remove the LoadRunner agent, run the command m_daemon_setup -
remove from the <LoadRunner root folder>/bin directory.

Note: When the LoadRunner agent is configured to run over a firewall, and
the agent is connected to the MI Listener, a file called
<local_machine_key>_connected_to_MI_Listener is created in the temporary
directory of the LoadRunner agent machine. The file is removed when the
LoadRunner agent disconnects from the MI Listener.

For more information about running the LoadRunner agent, refer to “UNIX
Shell,” on page 441.

Agent Configuration Settings

Option Default Value Description

MI Listener name none The name, full name, or IP

address of the Mercury Interactive
listener machine, MI Listener.

Local Machine Key none A symbolic string identifier used

to establish a unique connection
between the Controller host
behind the firewall, and the agent
machine (via the MI Listener
machine).

Connection Timeout 20 seconds The length of time you want the

(seconds) agent to wait before retrying to
connect to the MI Listener
machine. If zero, the connection
is kept open from the time the
agent is run.

266
 Chapter 16 • Running Vusers Over a Firewall

Option Default Value Description

MI Listener User Name none The username needed to connect

to the MI Listener machine.

MI Listener Password none The password needed to connect

to the MI Listener machine.

Server Domain none The domain name needed to

connect to the MI Listener
machine. This field is only
required if NTLM is used.

Connection Type - TCP TCP Choose either TCP or HTTP,

depending on the configuration
you are using.

Connection Type - HTTP <IE proxy The name of the proxy server.
Proxy Name server name> This option is mandatory if the
or None Connection Type option is set to
HTTP.

Connection Type - HTTP <IE proxy The proxy server connection port.
Proxy Port server name> This option is mandatory if the
or None Connection Type option is set to
HTTP.

Connection Type - HTTP None The username of a user with

Proxy User Name connection rights to the proxy
server.

Connection Type - HTTP None The user’s password.

Proxy Password

Connection Type - HTTP None The user’s domain if defined in

Proxy Domain the proxy server configuration.
This option is required only if
NTLM is used.

Use Secure Connection Disabled Enable to connect using the

(SSL) Secure Sockets Layer protocol.

267
Part IV • Working with Firewalls

Option Default Value Description

Use Secure Connection None Authenticates the SSL certificates

(SSL) - Check Server that are sent by the server. Choose
Certificates Medium to verify that the server
certificate is signed by a trusted
Certification Authority. Choose
High to verify that the sender IP
matches the certificate
information. This setting is only
available if Use Secure
Connection is set to True.

Use Secure Connection None The password that may be

(SSL) - Private Key required during the SSL certificate
Password authentication process. This
option is relevant only if the
Client Certificate Owner option is
enabled.

Use Secure Connection Disabled Enable to load the SSL certificate

(SSL) - Use Client (if required by the server to allow
Certificate the connection to be made). This
option is relevant only if the Use
Secure Connection option is
enabled.

268
 Chapter 16 • Running Vusers Over a Firewall

Configuring the Firewall to Allow Agent Access

You modify your firewall settings to enable communication between the
machine(s) inside the firewall and machines outside the firewall.

TCP configuration
The LoadRunner agent tries to establish a connection with the MI Listener
using port 443. To enable this connection, allow an outgoing connection for
HTTPS service on the firewall for port 443. As a result, the agent will keep
trying to connect to the MI Listener at an interval of the number of seconds
specified in the Connection Timeout field in the agent configuration. Then
the MI Listener connects back to the agent. From this point on, the agent
listens to commands from the MI Listener.

HTTPS configuration
The LoadRunner agent tries to establish a connection with the MI Listener
using the proxy port specified in the Proxy Port field. To enable this
connection, allow an outgoing connection for HTTPS service on the firewall
for port 443. The agent will keep trying to connect to the MI Listener at an
interval of the number of seconds specified in the Connection Timeout field
in the agent configuration. On successful connection, the agent on the
proxy server connects to the MI Listener, and the MI Listener connects back
to the agent through the proxy server. From this point on, the agent listens
to commands from the MI Listener.

Note: You can connect the Controller to load generators over a firewall
without using the MI Listener and LoadRunner agent. To do so, open port
54345 on a firewall in the Controller’s LAN and in the load generator’s LAN
to allow incoming and outgoing data.

269
Part IV • Working with Firewalls

Installing and Configuring the MI Listener Outside the

Firewall
To enable running Vusers or monitoring over a firewall, you need to install
the MI Listener on one or more machines in the same LAN as the Controller
outside the firewall. For installation instructions, refer to the LoadRunner
Installation Guide. Note that the Controller installation automatically
includes the MI Listener, so you can designate the Controller as the MI
Listener machine.

Note: MI Listener can only be installed on Windows machines.

To configure the MI Listener security attributes:

1 Open incoming HTTPS service for port 443. The port settings are set by your
system administrator.
2 Stop the LoadRunner agent on the MI Listener machine by right-clicking its
icon in the system tray and selecting Close from the popup menu.
3 Run MI Listener Configuration from
Start > Programs > Mercury LoadRunner > Advanced Settings, or run
<LoadRunner root folder>\launch_service\bin\MILsnConfig.exe.

270
 Chapter 16 • Running Vusers Over a Firewall

4 Set each option as described in “MI Listener Configuration Settings” below.

5 Click OK to save your changes, Cancel to cancel them, or Use Defaults.
6 Restart the LoadRunner agent by double-clicking the shortcut on the
desktop, or running it from Start > Programs > Mercury LoadRunner.
7 Make sure that port 443 is free on the MI Listener machine.

Note: Ensure that no Web Servers are running on the MI Listener or Monitor
over Firewall machine. These servers use port 443 and will not allow the
access required by the listening and monitoring processes.

MI Listener Configuration Settings

Option Default Value Description

Check Client Certificates False Choose True to request that the

client send an SSL certificate when
connecting, and to authenticate the
certificate.

Private Key Password None The password that may be required

during the SSL certificate
authentication process.

271
Part IV • Working with Firewalls

Configuring the Controller to Run or Monitor Vusers

over a Firewall
To run Vusers or monitor servers inside the firewall, you need to create a
unique connection between the Controller and the agent machine. This
connection is made through the MI Listener, which serves as router between
the Controller and the LoadRunner agent. To establish this connection, you
configure the Controller machine to define the agent machine as a load
generator.

To configure the Controller for running vusers or monitoring over the

firewall:
1 Run the Controller from
Start > Programs > Mercury LoadRunner > Applications > Controller and
create a new scenario, or load an existing one.
2 Click Generators to display the Load Generators window. In the Name field,
enter the symbolic name of the server. This is the same name that you
entered in the Local Machine Key setting in the Agent Configuration. (See
“Agent Configuration Settings” on page 266). In the example below, the
server name is gumbi.
If the server is a UNIX server, change the Platform field to UNIX.

272
 Chapter 16 • Running Vusers Over a Firewall

3 Select the Load Generator, and click Details to display the Load Generator
Information.

4 In the Firewall tab, enter the MI Listener machine’s name in the MI Listener
field. This is the same name that you entered in the MI Listener Name
setting of the Agent Configuration dialog box. In this example, the MI
Listener is bunji.
5 In the Firewall Settings section, choose one of the following options:
➤ Enable running Vusers over Firewall: To run Vusers over the firewall.
➤ Enable Monitoring over Firewall: To monitor Vusers over the firewall.

Note: If you are using WAN emulation, you should add the IP address of the
MI Listener machine to the WAN emulation Exclude IP list. For more
information, refer to “Excluding Hosts from WAN Emulation,” on page 103.

273
Part IV • Working with Firewalls

6 Click OK to return to the Load Generators dialog box.

7 Select the Load Generator and click Connect.

Note: Remember that you cannot change the temporary directory on the
host running or monitoring Vusers over the firewall.

If you encounter connectivity problems, see “Checking Connectivity” on

page 254. For other firewall troubleshooting, see “Troubleshooting
Firewalls” on page 450.

274
17
Monitoring Over a Firewall

You can monitor your servers within a firewall while the Controller is
outside of the firewall.

This chapter describes:

➤ About Monitoring over a Firewall

➤ Installing Monitors over Firewall
➤ Preparing for Data Collection
➤ Configuring Server Monitor Properties
➤ Configuring the Network Delay Monitor over a Firewall

About Monitoring over a Firewall

To enable monitoring of your servers from outside the firewall, you must
complete all the steps outlined in “Overview of Running Vusers Over a
Firewall” on page 258, and perform the following procedures:

➤ Install the Monitoring over Firewall component

➤ Configure the Server Monitor Properties

275
Part IV • Working with Firewalls

The Monitors over Firewall component must be installed on designated

machines inside the firewall. The installation sets up the Server Monitor
mediator (referred to as the “mediator”) as well as the Server Monitor
configuration tool. You then configure the servers to monitor, and define
the specific measurements that the LoadRunner mediator machine collects
for each monitored server.

Note: For a complete overview of the installation, configuration, and

connection requirements when working with firewalls, see “Overview of
Running or Monitoring Vusers over a Firewall” on page 252.

For information on running Vusers over a firewall, see “Running Vusers

Over a Firewall” on page 257.

Installing Monitors over Firewall

Monitors over Firewall may have been installed during the LoadRunner
installation. To check whether it is installed, click
Start > Programs > Mercury LoadRunner > Advanced Settings. If the
Monitor Configuration option appears on the list of LoadRunner options,
then Monitors over Firewall was already installed, and you can proceed to
“Preparing for Data Collection” on page 277.

If there is no installation, install Monitors over Firewall on the mediator

machine using one of the following:

➤ Perform a custom installation of LoadRunner from the LoadRunner CD,

choosing only the Monitors over Firewall option.
➤ Obtain the Monitors over Firewall file from the Mercury Customer Support
Web site (http://support.mercuryinteractive.com). Monitors over Firewall is a
stand-alone downloadable installation. It comes as a self-extracting installer
file.
For instructions on performing a custom installation of LoadRunner, refer to
the LoadRunner Installation Guide.

276
 Chapter 17 • Monitoring Over a Firewall

Preparing for Data Collection

After installing the Monitors over Firewall component, you need to prepare
for data collection. Check that you have completed all the steps outlined in
“Running Vusers Over a Firewall” on page 257 before continuing.

To configure the Controller for data collection:

1 You should already have configured the LoadRunner agent and the
Controller to operate over the firewall as described in “Configuring the
Controller to Run or Monitor Vusers over a Firewall,” on page 272.
2 Remember that in the Firewall tab of the Load Generator Information dialog
box, you should check Enable Monitoring over Firewall and enter the IP
address of the MI Listener machine.
3 Connect to the load generator. Select Scenario > Load Generators, and click
Connect. Make sure that you obtain information for the monitors
configured inside the firewall.

Configuring Server Monitor Properties

After you have installed and configured the LoadRunner agent, the
Monitors over Firewall component, the MI Listener, and the Controller
machine, you need to choose the server measurements that you want the
mediator machine to monitor.

You configure the server monitor properties from the mediator machine,
using the Monitor Configuration dialog box. You can select the type of
monitors to run and the server whose resources you want to monitor, add
the measurements to monitor for each server, and specify the frequency
with which you want the monitored measurements to be reported.

277
Part IV • Working with Firewalls

To configure server monitor properties:

1 Select Start > Programs > Mercury LoadRunner > Advanced Settings >
Monitor Configuration. For machines without the complete LoadRunner
installation, select Start > Programs > Server Monitor >
Monitor Configuration. The Monitor Configuration dialog box opens.

278
 Chapter 17 • Monitoring Over a Firewall

2 Click the Add Server button. The New Monitored Server Properties dialog
box opens.

3 In the Monitored Server box, type the name or IP address of the server
whose resources you want to monitor.

Note: To add several servers simultaneously, separate the server names or IP

ranges with commas. For example: 255.255.255.0-255.255.255.5, server1,
server2.

4 From the Available Monitors list, select the monitors appropriate for the
server being monitored.

279
Part IV • Working with Firewalls

Note: Data can only be viewed for the monitors that are enabled with your
LoadRunner license key. To preview your license key information, click
Start > Programs > Mercury LoadRunner. Mercury LoadRunner opens. Click
the License button to display the LoadRunner license information.

5 Click OK to close the New Monitored Server Properties dialog box. The
Monitored Servers list is displayed in the Monitor Configuration dialog box.

Note that for certain monitors, LoadRunner displays default measurements

in the Measurements to be Monitored section.You can specify the frequency
at whichLoadRunner reports the measurement in the Measurement
Properties section. For details on selecting measurements, see “Adding and
Removing Measurements” below.
6 To add additional monitored servers to the list, repeat steps 1-5.
7 To edit the monitor configuration properties for a server, click the Edit
button. The Monitored Server Properties dialog box opens enabling you to
edit the monitors for the server whose resources you are monitoring.
8 Click Apply to save your settings.

Adding and Removing Measurements

After you configure one or more server machines to monitor, you add
measurements to monitor for each server. If LoadRunner added default
measurements, you can edit them as required.

To add a measurement to monitor:

1 Select a server from the Monitored Servers list.

280
 Chapter 17 • Monitoring Over a Firewall

2 Click the Add Measurement button. Select the appropriate monitor. A

dialog box opens, enabling you to choose measurements for the monitor
you selected.
3 Select the measurements that you want to monitor, and click OK.
4 Click Apply to save your settings.
For information on configuring measurements for each server monitor, see
the relevant chapter in the LoadRunner Monitor Reference.

To remove a measurement from the measurements list:

1 Select the measurement, and click the Delete button.
2 Click Apply to save your settings.

Configuring Measurement Frequency

Once you have configured monitor measurements, you configure
measurement frequency.

In the Measurement Properties section, you set a measurement schedule for

each measurement to be reported.

To set a measurement schedule for a measurement:

1 Select the configured server measurement you want to schedule.
2 Specify the frequency at which you want LoadRunner to report the
measurement.
3 Click Apply to save your settings.

281
Part IV • Working with Firewalls

Cloning a Monitored Server’s Properties

If you want to monitor the same properties on different server machines,
you can clone a selected server’s properties using the Clone Monitored
Server Properties dialog box.

To clone a monitored server’s properties:

1 In the Monitor Configuration dialog box, right-click the server you want to
clone, and select Clone. The Clone Monitored Server Properties dialog box
opens.

2 In the Monitored Server box, type the name or IP address of the clone server
you want to create.

Note: To create several servers simultaneously, separate the server names or

IP ranges with commas. For example: 255.255.255.0-255.255.255.5, server1,
server2.

282
 Chapter 17 • Monitoring Over a Firewall

3 The Available Monitors list displays the monitors that were selected for the
server being cloned. Select additional appropriate monitors for the clone
server.
4 Click OK to close the Clone Monitored Server Properties dialog box. The
cloned server is displayed in the Monitored Servers list.
5 Click Apply to save your settings.

Configuring the Network Delay Monitor over a Firewall

To run the Network Delay Monitor when there are firewalls between the
Controller machine and the source machine, you must configure the
Network Delay Monitor (refer to “Configuring the Network Delay Time
Monitor” in the LoadRunner Monitor Reference), and add the following to step
3:

In the Monitor the network delay from machine section, enter the server
name or IP address of the source machine according to the following format:

<MI Listener machine>:<source machine local key>.

where source machine local key is the Local Machine Key that you chose
when configuring the LoadRunner agent on the source machine. (See
“Agent Configuration Settings” on page 266.)

For example: 12.12.12.3:vds

283
Part IV • Working with Firewalls

284
 Part V
Working with Diagnostics
286
18
J2EE Diagnostics Module

LoadRunner’s J2EE diagnostics module provides a monitor that traces, times,

and troubleshoots individual transactions through J2EE Web, application,
and database servers. It also enables you to quickly pinpoint problem
servlets and JDBC calls to maximize business process performance,
scalability, and efficiency.

The J2EE Diagnostics module monitor comes with a set of customized

Analysis reports. Using these reports, you can communicate your insights to
developers and managers, ultimately accelerating problem resolution, while
avoiding expensive hardware upgrades.

This chapter describes:

➤ About J2EE Diagnostics Monitoring

➤ J2EE Diagnostics Module Architecture
➤ Setting up the Monitoring Environment
➤ Configuring J2EE Diagnostics on the Client Machine
➤ Viewing J2EE Diagnostics Data
➤ Examples of Modifying Application Server Configurations
➤ Troubleshooting the J2EE Diagnostics Module Monitor

287
Part V • Working with Diagnostics

About J2EE Diagnostics Monitoring

The J2EE Diagnostics module monitor provides the following information
for each transaction:

➤ Average response time per method/query

➤ Number of method calls per second
➤ Breakdown information by layer, class, and method
➤ Chain of calls and call stack statistics
With this level of detail, you can get an overview of the entire chain of
activity within the system. At the same time, you can break down J2EE
layers into classes and methods to enable you to pinpoint the exact location
where time is consumed. You can also view the transaction call chain to
track the percent of time spent for each part of the transaction.

You can correlate the end user response time with the Web server activity
(Servlets and JSPs data), application server activity (JNDI), and back-end
activity of database requests (JDBC methods and SQL queries).

You can also monitor a class that is of special interest to you by defining a
custom layer. To enable the Diagnostics for J2EE to display custom classes or
packages, you must set up the J2EE probe to monitor the classes and
packages.

The J2EE Diagnostics monitor enables you to analyze J2EE component

metrics during a scenario run by using an agent— installed on the
application server—to collect information on the J2EE components. These
measurements are sent from the application server back to the Controller
through a channel contained in the J2EE Diagnostics monitor. The J2EE
Diagnostics monitor supports the leading application servers, such as IBM
WebSphere and BEA WebLogic. For information about the supported
application servers, see the “Support Matrix” on page 291.

288
 Chapter 18 • J2EE Diagnostics Module

Note: The J2EE Diagnostics module monitor requires MSXML 3.0 or later
(included in Internet Explorer 6.0). You can install MSXML 3.0 from the
Microsoft MSDN Web site
(http://msdn.microsoft.com/library/default.asp?url=/downloads/list/
xmlgeneral.asp).

J2EE Diagnostics Module Architecture

The J2EE Diagnostics architecture is composed of the following
components:

Probe: The Probe resides on the application server. It gathers information

about the monitored transactions and passes data to the mediator.

Mediator: The Mediator component is used to connect between the probe

(on the application server) and the Controller machine. The Mediator
processes the transaction data, and then passes it to the Controller. Note
that the Mediator should be installed on a load generator machine that
resides in the same LAN as the Controller and Probe machines. If you are
monitoring over a firewall, the Controller can be outside the firewall
provided you open port 54345 on the firewall in the Probe/Mediator LAN
and in the Contoller’s LAN to allow incoming and outgoing data.

289
Part V • Working with Diagnostics

Controller: Displays the online transaction data.

Analysis: Displays detailed diagnostics graphs and reports. For more

information about the diagnostic graphs, see the LoadRunner Analysis User’s
Guide.

Note: You can install the Mediator and Probe components on one machine,
or you can distribute them over multiple machines. We do not recommend
installing the Mediator on the application server machine, since this can
affect the load test results.

Setting up the Monitoring Environment

To use the J2EE Diagnostics module monitor, you must first install the J2EE
Transaction Breakdown Probe and Mediator from the LoadRunner
installation CD. For installation information, see the LoadRunner Installation
Guide.

After installing the Probe and Mediator components, you configure the J2EE
Diagnostics monitor on the application server. You then enable the J2EE
Diagnostics (from the Controller) and select the default measurements you
want to display, before running the scenario.

This section describes the following topics:

➤ Configuring the J2EE Diagnostics Module Monitor on the Application

Server
➤ Initial Configuration Settings
➤ Configuring JDBC Information Retrieval

290
 Chapter 18 • J2EE Diagnostics Module

Support Matrix
The following servers are supported:

Application Server Version Platform

WebLogic 6.x; 7.0; 8.1 Windows; Solaris

WebSphere 4.x; 5.x Windows; AIX

Oracle 9i 1.0.2.2 Windows; Solaris; AIX

JBoss 2.4.x;3.04 Windows; Solaris; AIX

Sun ONE Application 6; 6.5; 7 Windows; Solaris; AIX

Server

Sun ONE Web Server 6 Windows; Solaris; AIX

Configuring the J2EE Diagnostics Module Monitor on the

Application Server
To monitor J2EE objects, you configure the J2EE Diagnostics module
monitor on the application server machine. This section explains these steps
in general. For examples of how to perform these steps for different
application servers, see “Examples of Modifying Application Server
Configurations” on page 309.

Note: Before making any changes, back up all startup scripts.

This chapter uses <mercprobe> to denote the J2EE probe home directory.

291
Part V • Working with Diagnostics

To update the application server configuration:

1 Update the Java command line that starts the application server. Add the
following parameter at the beginning of the line:

-Xbootclasspath/p:<mercprobe>/classes/boot

For example,

-Xbootclasspath/p:/bea/mercprobe/classes/boot

Note: If your JVM uses a JIT option, such as -hotspot or -classic, make sure
that the -Xbootclasspath option is entered following the JIT option.

2 Restart the application server instance for which you configured the probe.

Note: Your site administrator may configure the application server using an
alternative, site-specific method. If this is the case, the generic procedure
may be sufficient for the administrator to understand what changes need to
be done.

292
 Chapter 18 • J2EE Diagnostics Module

Initial Configuration Settings

The following settings are automatically configured during the installation
of the J2EE Diagnostics Module monitor on the application server:

Hooking mechanism: The J2EE Diagnostics Module monitor uses the

Mercury J2EE Transaction Breakdown Monitor Initializer and Java hooking
library.

Operation mode: The J2EE Diagnostics Module monitor uses the Auto
Discovery operating mode. In this mode, the system automatically discovers
the J2EE components (Servlet, JSP, EJB, JNDI, and JDBC) that actually
participate in the business process.

JDBC information retrieval: The JDBC information retrieval setting

determines which data to return from the JDBC call. By default, the J2EE
Diagnostics Module monitor aggregates the measured data according to the
JDBC operation, for example: SELECT,UPDATE,CREATE. To modify this
configuration, see “Configuring JDBC Information Retrieval” below.

Note: For information about alternative configuration settings, contact

Mercury Customer Support.

Configuring JDBC Information Retrieval

1 Open <J2EE Transaction Breakdown Home Directory>
\etc\dispatcher.properties.
2 In the property sql.parsing.mode, enter one of the following:
➤ “1” to measure the JDBC method calls, like any other (non-JDBC)
measured method calls.
➤ “2” to aggregate the measured data according to the JDBC operation, for
example: SELECT,UPDATE,CREATE. If the sql.mode property does not
exist, this is the default mode.
➤ “3” to aggregate the measured data according to specific SQL statement
(including the operation, the tables it acted on, and other parameters of
this statement).

293
Part V • Working with Diagnostics

Note: SQL Statements that exceed 3000 characters in length are not
supported.

Configuring J2EE Diagnostics on the Client Machine

To monitor J2EE transactions, you must connect between the application
server (with the probe) and the mediator. The application server and the
Controller connect via the mediator.

The settings that you configure are per scenario. All scripts in the scenario
will run under the same diagnostics configuration.

Note: Ensure that the application server has finished launching before
attempting to connect the Controller to the Probe/Mediator.

Setting Up the J2EE Diagnostics Module

You configure J2EE diagnostics settings using the J2EE Transaction
Breakdown dialog box. You can then enable J2EE transaction breakdown
using the Diagnostics Distribution dialog box.

294
 Chapter 18 • J2EE Diagnostics Module

To set up the J2EE Diagnostics module:

1 From the Controller menu, choose Diagnostics > Configuration > J2EE. The
J2EE Transaction Breakdown dialog box opens.

2 Enter the name or IP address of the application server and the mediator. The
mediator default is localhost.
3 Click Connect. The J2EE Diagnostics module monitor attempts to connect
the mediator and the application server.
4 When the connection is successful, click Close.
If the connection is not successful, see the Output window for more
information. You can view the Output window from the J2EE Diagnostics
tab by clicking the Errors link in the status bar.

Note: Only Vusers that start running after the connection has been
established will participate in the breakdown.

295
Part V • Working with Diagnostics

To enable J2EE diagnostics on the Controller:

1 Choose Diagnostics > Distribution. The Diagnostics Distribution dialog box
opens.

Note: The Diagnostics Distribution dialog box is disabled during scenario

execution.

2 To enable transaction breakdown monitoring, select Enable the following

diagnostics and set the percent of users to participate in the monitoring as
described in “Understanding the Diagnostics Distribution Dialog Box” on
page 355.

Note: You can only enable transaction breakdown monitoring after the
connection to the mediator and the application server has been established.

During a scenario run, you cannot change the percentage value.

3 Select J2EE Diagnostics and click OK.

296
 Chapter 18 • J2EE Diagnostics Module

Viewing J2EE Diagnostics Data

This section describes the following topics:

➤ Viewing J2EE Diagnostics Data

➤ Showing J2EE Measurement Breakdown
➤ Example Transaction Breakdown
➤ J2EE Transaction Breakdown Diagnostics Graphs

Viewing J2EE Diagnostics Data

You view transaction breakdown data using the J2EE Diagnostics tab in the
Controller.

To open the J2EE Diagnostics tab, perform one of the following:

➤ From the Transaction Response Time graph in the Run tab, right-click
and choose Show J2EE server side.
➤ Select the J2EE Diagnostics tab.

297
Part V • Working with Diagnostics

The J2EE Diagnostics tab opens.

To display the list of available diagnostics graphs, right-click in the graph

and choose Show Available Graphs. The list of available graphs is displayed
with the current graph outlined.

Note: The J2EE Transaction Breakdown Diagnostics Module graphs are only
available if there is an active connection between the application server and
the mediator.

298
 Chapter 18 • J2EE Diagnostics Module

Understanding the J2EE Diagnostics Tab View

The J2EE Diagnostics tab displays the following J2EE transaction breakdown
information:

J2EE Transaction Breakdown graphs: Display the J2EE transaction

breakdown information in graph format.

Connection Statistics/Status bar: Displays the name of the application

server and the mediator, their connection status, and the number of errors
in this scenario.

Transaction for breakdown: Enables you to choose a transaction for

breakdown. You can use this to switch from any level of detail within one
transaction to the same level of detail in a different transaction without
requiring you to move up and down the entire breakdown chain.

Legend: The legend displays statistics on the data displayed in the graph. By
default, the legend is sorted according to descending average response time.
As this value is updated at every refresh period, the component order can
change often, making it difficult to track components. To keep the
components sorted in the current order, right-click in the legend area and
choose Keep the Legend Sorted, or choose J2EE > Keep Legend Sorted.

Showing J2EE Measurement Breakdown

You can break down the transactions displayed in the Transaction Response
Time - whole scenario graph. From the transaction level, you can break
down successively to the layer, class, and method level.

To view transaction breakdown graphs:

1 On the Run tab or the J2EE Diagnostics tab, display the Transaction
Response Time - whole scenario graph.
2 Right-click a transaction, and choose Show J2EE server side.
A graph showing the next level of breakdown is displayed in the J2EE
Diagnostics tab.

299
Part V • Working with Diagnostics

➤ To view successive breakdown graphs, right-click in the relevant graph area

and choose Show Measurement Breakdown, or choose
J2EE > Show Measurement Breakdown. Each time you change the
breakdown level, the selected graph is outlined in the Available Graphs list.
➤ To return to the previous breakdown level, right-click in the graph and
choose Undo Measurement Breakdown, or choose
J2EE > Undo Measurement Breakdown.
For information on the available graphs, see “J2EE Transaction Breakdown
Diagnostics Graphs” on page 308.

Note: For nested transactions, for example when transaction B is a

subtransaction within transaction A, the subtransaction finishes earlier than
the parent, and is therefore, reported to the Controller earlier than the
parent transaction. This may cause data that is displayed for a parent
transaction and a subtransaction not to be vertically aligned on the graph.

Viewing Call Chains and Call Stack Statistics

You can view the chain of calls for transactions and methods. The chain of
calls answers the question “Who did I call?”

You can also view the call stack statistics for methods. Call stack statistics
answer the question “Who called me?”

Chain of call and call stack statistics data are shown in the Calls window.
The title of the window changes depending on which kind of data you are
viewing.

➤ To view call chains, right-click a component, and choose Show

<Component> Chain of Calls, or choose J2EE > Show chain of calls. The Calls
window opens displaying the components that this component called.
➤ To view stack statistics, right-click a method, and choose Show Method Call
Stack Statistics, or choose J2EE > Method call stack. The Calls window opens
displaying all the components that called the selected method.

300
 Chapter 18 • J2EE Diagnostics Module

To change the point to which the Calls window relates, drag the red time
line to the desired spot.

Understanding the Call Windows

You use the Call Chain window to view the components that the selected
transaction called. In the following figure, all the calls in the critical path of
the Action_Transaction.look_at_fish transaction are displayed.

301
Part V • Working with Diagnostics

You use the Call Stack Statistics window to view which components called
the selected component. In the following figure, the executeQuery.SELECT
COUNT query was called by __product._jspService, which was called by
__template._jspService, and so on, down to the transaction at the bottom of
the chain.

Switch to Method Chain of Calls: When the Call Stack Statistics data is
displayed, displays the method Chain of calls data (only if the root is a
method).

Switch to Method Call Stack Statistics: When the method Chain of calls
data is displayed, displays the method Call Stack Statistics data (only if the
root is a method).

Show Method Chain of Calls: Displays the Chain of Calls window.

Show Method Call Stack Statistics: Displays the Call Stack Statistics window.

Properties: Hides or displays the properties area (lower pane).

302
 Chapter 18 • J2EE Diagnostics Module

Columns: Enables you to select the columns shown in the Calls window. To
display additional fields, drag them to the desired location in the Calls
window. To remove fields, drag them from the Calls window back to the
Columns chooser.

Measurement: Name of the method, displayed as

classname.methodname. In the case of a database call, query
information is also displayed. The percent shown indicates the percent of
calls to this component from its parent.
% of Transaction (or Root Method): Percentage of the total time of the
transaction (or method) from the total time of the root tree item.
No of Calls: Displays the amount of times that this transaction or method
was executed.
Avg Response Time: Response time is the time from the beginning of
execution until the end. Average response time is the total response time
divided by the number of hits.
STD Response Time: The standard deviation response time.
Min Response Time: The minimum response time.
Max Response Time: The maximum response time.
% of Called: Displays the execution time, as a portion of the time of the
calling component.
Total time: Displays the total method execution time, including the child
execution time.
Expand Tree: Expands the entire tree.

Contract Tree: Contracts the entire tree.

Expand Worst Path: Expands only the parts of the path on the critical path.

Method Properties Area: Displays the full properties of the selected method.

SQL Query: Displays the SQL query for the selected method. (For Database
only.)

303
Part V • Working with Diagnostics

Example Transaction Breakdown

The following graphs illustrate the breakdown of a transaction to its layer,
class, and methods.

Transaction Level
The following figure displays the top level Transaction Response Time
graph. The graph displays three transactions:

304
 Chapter 18 • J2EE Diagnostics Module

Layer Level
The following figure displays the breakdown of the
Action_Transaction.look_at_fish transaction into its layers:

The top of each breakdown graph displays the name of the graph and the
name of the parent component. In this Time Spent on Each Layer graph, the
Action_Transaction.look_at_fish transaction has been broken down to its
layers (DB, EJB, JNDI, and Web). In Web transactions, the database (DB)
layer is generally the largest.

305
Part V • Working with Diagnostics

Class Level
The following figure displays the breakdown of the DB layer into classes:

In this Time Spent on Each JDBC Component graph, the DB layer of the
Action_Transaction.look_at_fish transaction has been broken down to its
classes. The Legend displays data on the classes.

306
 Chapter 18 • J2EE Diagnostics Module

Method/Query Level
The following figure displays the breakdown of a class into its methods:

In this Time Spent in Component Method graph, the SerialStatement class

of the DB layer of the Action_Transaction.look_at_fish transaction has been
broken down to its methods. The Legend displays numerous method lines,
differentiated by their SQL statements.

When you point to a method line, its properties are displayed in a pop-up
window.

307
Part V • Working with Diagnostics

J2EE Transaction Breakdown Diagnostics Graphs

You can view J2EE transaction breakdown data in the following graphs:

Transaction Graphs
➤ Transaction Response Time - Server Side: Shows the transaction server
response time of transactions that include steps that cause activity on the
J2EE backend. The reported times, measured from the point when the
transaction reached the Web server to the point it left the Web server,
include only the time that was spent in the J2EE backend.
➤ Nested Transaction Response Time - Server Side: Shows all the
transactions within the selected transaction, including the selected
transaction.
➤ Transactions per Second - Server Side: Shows the amount of times per
second that the transaction was executed.

Transaction Layer Graphs

➤ Time Spent In Each Method: Shows the time spent in each monitored
method.
➤ Time Spent On Each Layer: Shows, for a specific transaction, the total
time for each layer.
➤ Calls per layer: Shows, for a specific transaction how many times each
layer was called per second.

Class Graphs
The class graphs can be displayed for Web server (SERVLET), application
server (EJB), database (JDBC), or naming server (JNDI) classes:

➤ Time Spent in Each <Class> Component: Shows, for a specific transaction

the total class time in the different components.
➤ Calls per <Class> Component: Shows how many times each component
was called per second.

308
 Chapter 18 • J2EE Diagnostics Module

Method Graphs
The method graphs can be displayed for Web server (SERVLET), application
server (EJB), database (JDBC), or naming server (JNDI) methods.

➤ Time Spent In Each Component Method: Shows the breakdown of the

total layer time into the different methods/queries in a specific
transaction.
➤ Component Method Calls per Sec: Shows how many times each method
was called per second in a specific transaction.
➤ Average Component Method Response Time: Shows the average time
spent in the method.

Examples of Modifying Application Server Configurations

This section provides examples modifying the configuration of the
following application servers:

➤ Configuring the WebSphere Application Server

➤ Configuring the WebLogic Application Server
➤ Configuring the Oracle9i Application Server
➤ Configuring the JBoss Application Server

309
Part V • Working with Diagnostics

Configuring the WebSphere Application Server

WebSphere servers are controlled from an Administrative Console. The
Console has control over the JVM command line and allows you to add
classpath elements, define runtime variables (-D variables), and configure
the bootclasspath for WebSphere 4.x versions. You may also add any
additional arguments to the JVM command line that may be needed.

Note that the appearance of the Console for each WebSphere version differ.
The examples shown in this section may not correspond exactly to your
WebSphere version, but the principle is the same, that is, the parameters
must be inserted in the appropriate fields.

Note: You must click Apply in each tab in the Administrative Console before
moving to another tab in order to make the changes effective.

310
 Chapter 18 • J2EE Diagnostics Module

To configure the probe on a WebSphere application server:

1 Access the WebSphere Administrative Console, and display the General tab
for the application server that you want to configure.

Note: This screen shows WebSphere version 4. Your console may appear
different if you are running another version.

311
Part V • Working with Diagnostics

2 Click the JVM Settings tab.

Note: If your JVM uses a JIT option, such as -hotspot or -classic, make sure
(in the Java Command Line arguments on the console) that the
-Xbootclasspath option is entered following the JIT option.

3 Click Advanced JVM Settings, to open the Advanced JVM Settings box.

312
 Chapter 18 • J2EE Diagnostics Module

4 Add the boot classpath elements to the prepend field, as in the following
example:

313
Part V • Working with Diagnostics

5 In the Generated Command Line Arguments area, verify that the settings
are the same as in the following example:

6 Restart the application server.

314
 Chapter 18 • J2EE Diagnostics Module

Configuring the WebLogic Application Server

These procedures explain how to configure the WebLogic application server
so that it recognizes the J2EE probe, when WebLogic is running either as a
script or a service.

To configure the WebLogic server, running as a script:

WebLogic application servers are started by running shell scripts (UNIX) or
cmd scripts (Windows). While the standard installation comes with default
scripts, it is very common for a site manager to heavily modify these scripts.
For this reason, detailed instructions can not be given, and these guidelines
should be used instead:

The J2EE probe is controlled through several command line arguments and,
possibly, a few environment variables. The command line arguments that
might be used are -Xbootclasspath. You must add these command line
arguments in a place that is appropriate to the specific installation. This
could be in the actual file that launches the Java virtual machine, but may
also be in a file that sets up a generic environment to be used by several
WebLogic installed bases. It is important to understand the structure of the
scripts that actually launch the application server when selecting the proper
place to apply these changes.

You must take extra care when modifying environment variables since these
may be changed by other parts of the script architecture after being set to
reflect the probe installation.

Typical Locations of WebLogic Scripts

The following examples are provided to show some typical locations of the
startup scripts for a Windows installation of WebLogic 6.1 and 7 along with
the changes that need to be made to each script:

Weblogic 6.1
Script location example:
D:\bea\wlserver6.1\config\petstore\startPetStore.cmd.

Modify the Java command-line, and add the

-Xbootclasspath/p:<mercprobe>/classes/boot argument.

315
Part V • Working with Diagnostics

Weblogic 7
Script location example: D:\bea\user_projects\petstore\startPetStore.cmd.

To change the script, add the following immediately before the call to
startWLS.cmd (at the end of the file):

set JAVA_OPTIONS=-Xbootclasspath/p:d:\bea\user_projects\
petstore\mercprobe\classes\boot ;%JAVA_OPTIONS%

To configure the WebLogic server versions 7.x, 6.x or 5.x SP10 or later,
when running as a service:
1 Locate the command file that is being used by the customer to install the
WebLogic service (for example, installNtService.cmd).
2 Backup this file.

Tip: It is recommended that you check that the *.cmd file you found installs
the service successfully, before you modify it. To verify that the *.cmd file
installs the service successfully, run the file before making any changes to it.

3 On the line that begins with set CMDLINE=, add:

-Xbootclasspath/p:<mercprobe>/classes/boot

For example:

set CMDLINE=" -Xbootclasspath/p:D:/bea/Weblogic/

mercprobe/classes/boot -ms64m -mx64m -classpath..."

Note: If your JVM uses a JIT option, such as -hotspot or -classic, make sure
that the -Xbootclasspath option is entered following the JIT option.

4 Save the file, and then run it. This installs the service.

316
 Chapter 18 • J2EE Diagnostics Module

Weblogic 8 .1
To load the probe with the JRockit JVM:
1 Locate the command file that the user uses to invoke the WebLogic
application server (for example, startWebLogic.cmd).
2 Create a new copy of the command file (for example,
startWebLogicWithJRockit.cmd).
3 Check that the JAVA executable used with WebLogic is JRockit. To do this,
check the following environment variable setting in
startWebLogicWithJRockit.cmd (the newly-saved file]:
set JAVA_HOME=c:\bea\jrockit. For example, for WebLogic 8.1 it might be:
set JAVA_HOME=<BEA_HOME_DIR>\jrockit81sp1_141_03]
4 Check that JAVAPROBE_HOME is set. For example:
set JAVAPROBE_HOME=c:\JavaProbe
5 Find the JAVA invocation that starts the WebLogic application server. It
should look something like this:
%JAVA_HOME%\bin\java %JAVA_VM% %JAVA_OPTIONS% .....
weblogic.Server
6 Add the following lines to the application server startup command line after
%JAVA_OPTIONS%:

-Xmanagement:class=com.mercury.opal.capture.proxy.JRockitManagement
-Xbootclasspath/p:%JAVAPROBE_HOME%/classes/boot

Configuring the Oracle9i Application Server

To configure the Oracle9i Application Server:
1 Configure the probe through the Oracle9i administration console (the
Enterprise Manager):
➤ Access the URL http://<application server>:<adminport>.
➤ Click Instance.
➤ Click Application.
➤ At the bottom of the page, click Server Properties.

317
Part V • Working with Diagnostics

2 Enter the location of the Java executable that was specified during
installation of the probe.
3 Add the following line to the Java options:

-Xbootclasspath/p:<mercprobe>/classes/boot

4 Click Apply.
5 Use the navigation path at the top of the page to return to the application
server, and start or restart the application.
6 Verify that the Application Server instance starts correctly in the console.
Log files for the Application Server are typically located under
<oracle-home>/opmn/logs/<application><instance>.
If the Application Server does not start properly, review the changes made in
the previous steps.

Configuring the JBoss Application Server

This section explains how to configure the JBoss 3.2.1 application server so
that it recognizes the J2EE probe.

To configure the JBoss server, running as a script:

JBoss application servers are started by running shell scripts (UNIX) or cmd
scripts (Windows). While the standard installation comes with default
scripts, it is very common for a site manager to modify these scripts heavily.
For this reason, detailed instructions cannot be given, and these guidelines
should be used instead:

The J2EE probe is controlled through several command line arguments and,
possibly, a few environment variables. The command line arguments that
might be used are -Xbootclasspath.

You must add these command line arguments in a place that is appropriate
to the specific installation. This could be in the actual file that launches the
Java virtual machine, but may also be in a file that sets up a generic
environment to be used by several JBoss installed bases. It is important to
understand the structure of the scripts that actually launch the application
server when selecting the proper place to apply these changes.

318
 Chapter 18 • J2EE Diagnostics Module

You must take extra care when modifying environment variables since these
may be changed by other parts of the script architecture after being set to
reflect the probe installation.

Typical Location of JBoss Scripts

Here is an example of a startup script location on a Windows installation of
the JBoss application server, and the needed changes in the script: Script
location example: D:\JBoss\EJBContainer\bin\run.bat.

Note: <mercprobe>/etc must be added to the beginning of the line.

1 Copy <Jboss Home>\bin\run.bat (or .sh) to <Jboss Home>\runMercury.bat (or

.sh).
2 Open the new file runMercury.bat (or .sh).
3 Just before the Java command line used to start the server, add the following
variables:
For Windows platforms:

set merc_probe=<J2EE Transaction Breakdown Home Directory>

For UNIX platforms:

merc_probe=<J2EE Transaction Breakdown Home Directory>

4 In the same section of the file, add a parameter to the command line:

-Xbootclasspath/p:%merc_probe%\classes\boot

Example:

"%JAVA%" -Xbootclasspath/p:%merc_probe%\classes\boot
%JAVA_OPTS% -classpath "%CLASSPATH%" org.jboss.Main %ARGS%

319
Part V • Working with Diagnostics

5 To start the application server with the probe, run runMercury.bat.

Troubleshooting the J2EE Diagnostics Module Monitor

Initialization Errors
If you are getting application server initialization errors such as:
“UnsupportedClassVersionError”, “NoSuchMethodError” or
“NoClassDefFoundError”, there might be a conflict between the JDK version
specified using the Mercury J2EE Transaction Breakdown Monitor Initializer,
and the actual JDK version used in application server launch.

Make sure that you selected the correct JDK that is currently being used by
the application server. Note that if you switched the application server to
work with a different JDK, you must run the Mercury J2EE Transaction
Breakdown Monitor Initializer again.

Error Message Displayed When Running the Mediator on Localhost

When running the mediator on localhost, the following error may be
displayed in the Controller output window:

"Error: Communication error: An error occurred while calling the

VirtualAlloc function. (sys error message - Attempt to access invalid
address.)[MsgId: MERR-10343]"

This is caused by a high number of Vusers relative to the available resources

of the machine on which they are running. To resolve this, run the mediator
on a more powerful machine, reduce the number of Vusers, or reduce the
percentage of Vusers being monitored (as described in “Setting Up the J2EE
Diagnostics Module” on page 294).

No Data in the J2EE Diagnostics Monitor Graphs

If there is no data displayed in the J2EE Diagnostics Module monitor graphs,
check the following:

➤ Ensure that you have installed all the J2EE Diagnostics Module monitor
components and that the probe is properly configured. For more
information, see “Configuring the J2EE Diagnostics Module Monitor on
the Application Server” on page 291.

320
 Chapter 18 • J2EE Diagnostics Module

➤ Ensure that the connection between the Controller and the probe is
active. For more information, see “Examples of Modifying Application
Server Configurations” on page 309.
➤ Ensure that you selected a transaction in the Transaction Response Time -
whole scenario graph. If a transaction is not selected, the J2EE graph will
be blank.
➤ In some cases, a single iteration of a script may not provide enough data
to be displayed. Increase the number of iterations.

Only One Transaction is Being Displayed in the Graphs

If only one transaction is being displayed in the diagnostics graphs, ensure
that you have not used the same transaction name within multiple scripts
in the same scenario.

The most common example of this is two scripts that define no inner
transactions. In this case, only one transaction, the Action_transaction will
appear in the diagnostics graphs, and measurement data will be combined
for both transactions.

321
Part V • Working with Diagnostics

322
19
ERP/CRM Diagnostics Modules

LoadRunner’s ERP/CRM diagnostics modules provide detailed performance

information to help you rapidly identify and pinpoint performance
problems in Siebel and Oracle environments.

The ERP/CRM Transaction Breakdown Diagnostics modules come with a set

of customized Analysis reports. Using these reports, you can communicate
your insights to developers and managers to accelerate resolution, while
avoiding expensive hardware upgrades.

This chapter describes:

➤ About LoadRunner ERP/CRM Diagnostics Modules

➤ ERP/CRM Diagnostics Module Architecture
➤ LoadRunner ERP/CRM Diagnostics Types
➤ Working With LoadRunner ERP/CRM Diagnostics
➤ Configuring Siebel Diagnostics
➤ Configuring Siebel DB Diagnostics
➤ Configuring Oracle DB Diagnostics
➤ Enabling Diagnostics
➤ Viewing Diagnostics Results

323
Part V • Working with Diagnostics

About LoadRunner ERP/CRM Diagnostics Modules

During a performance test, LoadRunner’s diagnostics modules trace, time,
and troubleshoot individual transactions across the Web, application, and
database servers. You can drill-down from a slow end-user transaction all the
way to the bottle necked method or SQL statement. The LoadRunner
Diagnostics Modules enable organizations to:

➤ Trace the application components exercised by business processes.

➤ Rapidly isolate application components that have a significant impact on
end-user experience
➤ Provide developers with precise data on how to make performance
improvements
Such precision pinpointing of performance problems directly translates into
significant business value:

➤ Quicker and more efficient performance testing cycles

➤ Decreased time to problem resolution by development
➤ Better performing applications that are optimized to meet the needs of the
business

324
 Chapter 19 • ERP/CRM Diagnostics Modules

ERP/CRM Diagnostics Module Architecture

The ERP/CRM Diagnostics architecture is composed of the following
components:

ERP/CRM Mediator: The ERP/CRM Mediator (“mediator”) gathers and

correlates offline transaction data from the Web, database, and application
servers. The mediator must be installed on a machine that resides in the
same LAN as the monitored ERP/CRM server, and preferably on a dedicated
server. We do not recommend installing the mediator on a Siebel or Oracle
server that is involved in the load test. For more information on installing
the mediator, see the LoadRunner Installation Guide.

Note: By default, the mediator agent is installed to run as a process. We

recommend configuring the mediator agent to run as a service.

If you run the agent as a process, you may encounter the following
Microsoft Windows networking limitation: “Failed to establish connection.
System error 1219“. You can either:

1. Run the agent as a service. For more information, see “Running the
LoadRunner Agent as a Service” on page 459.
2. Disconnect all previous connections to the server and try again.

325
Part V • Working with Diagnostics

Note: For Siebel DB diagnostics, it may take a long time to copy the files
from the application server to the mediator, and then from the mediator to
the results directory. During the first copying stage, the Summary Data
Processing window is displayed. To minimize copying time in the second
stage (if you are not working over a firewall), we recommend using localhost
as the mediator machine. This reduces the time it takes to copy the Siebel
DB diagnostics files to the results directory, since the diagnostics files are
already on the Controller machine.

Controller: Before scenario execution, the Controller transfers all server

information to the mediators and distributes the percentage of users that
will participate in the monitoring. After scenario execution, the Controller
collects the aggregated transaction data files from the mediators and collates
the results. Siebel results are transferred to the \sbl_bd directory, and Oracle
DB diagnostics are transferred to the \ora_bd directory. You can view the
status of diagnostics file collation in the Collate Results dialog box. For more
information, see “Collating Results” on page 191.

Load Generator: When you execute a scenario, the Controller distributes

each Vuser to a load generator, and the load generator executes the Vuser
script.

Analysis: Displays detailed diagnostics graphs and reports. For more

information about the diagnostics graphs, see the LoadRunner Analysis User’s
Guide.

326
 Chapter 19 • ERP/CRM Diagnostics Modules

LoadRunner ERP/CRM Diagnostics Types

LoadRunner provides the following ERP/CRM Diagnostics solutions:

➤ Siebel Diagnostics
The diagram below shows transaction breakdown on a Siebel CRM system.

LoadRunner’s Siebel diagnostics are split into the following modules:

Siebel Diagnostics Module enables you to breakdown Siebel transactions

into layers, areas, sub-areas, servers, and scripts. You can also view the
transaction chain of calls and call stack statistics to track the percent of time
spent for each part of the transaction. Siebel-Web Vusers support Siebel
Diagnostics. For more information, see “Configuring Siebel Diagnostics” on
page 329.

Siebel DB Diagnostics Module helps you to rapidly identify and resolve

database performance problems. You can view the SQLs for each
transaction, identify the problematic SQL queries of each script, and identify
at what point problems occurred. Siebel-Web Vusers support Siebel DB
Diagnostics. For more information, see “Configuring Siebel DB Diagnostics”
on page 338.

➤ Oracle DB Diagnostics
Oracle Transaction Breakdown helps pinpoint performance problems on
Oracle NCA systems. The diagnostics information drills down from the
transaction, to the SQL statements and the SQL stages of each statement.
Oracle NCA Vusers support Oracle DB Diagnostics. For more information,
see “Configuring Oracle DB Diagnostics” on page 346.

327
Part V • Working with Diagnostics

Working With LoadRunner ERP/CRM Diagnostics

To use LoadRunner’s ERP/CRM diagnostics, follow these steps:

1 Prepare for generating diagnostics data.

Make sure that the ERP/CRM Mediator is installed. The mediator collects
and processes the diagnostics data.
The ERP/CRM Mediator is installed on the Controller machine as part of the
LoadRunner Full Setup. For information on installing the ERP/CRM
Mediator on a dedicated machine, see the LoadRunner Installation Guide.
2 Configure the server machine to enable the diagnostics feature.
For more information, see “Configuring Siebel Diagnostics on the
Application and Web Servers” on page 329, “Enabling Server Logging on the
Siebel Server” on page 339, “Enabling Server Logging on the Oracle Server”
on page 346, and “Selecting the Oracle NCA Application Version” on
page 348.
3 Prepare the Controller machine to generate diagnostics data and
communicate with the mediator machines.
For more information, see “Configuring Siebel Diagnostics” on page 329,
“Configuring Siebel DB Diagnostics” on page 338, “Configuring Oracle DB
Diagnostics” on page 346, and “Enabling Diagnostics” on page 354.
4 Collect and prepare the diagnostics data.
During the load test, the mediator collects the data and processes the
diagnostics information.
5 Create the results.
After the load test, the Controller collects the aggregated data from the
mediator machines and collates the results. For more information on result
collation, see “Collating Results” on page 191.
6 Present the data.
Use the analysis graphs to view the diagnostics data and drill down to the
problematic areas. For more information about ERP/CRM Transaction
Breakdown graphs, see the LoadRunner Analysis User’s Guide.

328
 Chapter 19 • ERP/CRM Diagnostics Modules

Configuring Siebel Diagnostics

Siebel Diagnostics (Siebel Application Response Measurements) supports
Siebel application servers version 7.53.

To generate Siebel transaction breakdown data, perform the following:

➤ Configure Siebel Diagnostics on the Application and Web Servers

➤ Configure Diagnostics (where the Web Server is Inside a DMZ)
➤ Copy files from the Siebel server to the ERP/CRM Mediator machine
➤ Set Up Siebel Diagnostics from the Controller
➤ Enable Siebel Diagnostics from the Controller
➤ Run the Load Tests
➤ View Diagnostics Results

Configuring Siebel Diagnostics on the Application and Web

Servers
To configure Siebel Application and Web servers for transaction breakdown,
you perform the following:

➤ enable Siebel diagnostics on all Siebel Application and Web servers

involved in the load test
➤ optimize server performance settings
➤ generate a list of Siebel server IDs (required for Siebel Application servers
only)

To enable Siebel diagnostics:

1 Set the environment variable on the Siebel server to:
SIEBEL_SarmEnabled=true
2 Restart the server.

329
Part V • Working with Diagnostics

To optimize server performance:

You can change the maximum memory caching and file size using the
following variables:

SIEBEL_SarmMaxMemory= <bytes>

SIEBEL_SarmMaxFileSize = <bytes>

SIEBEL_SarmMaxMemory controls the size of the buffer that Siebel keeps in

the memory before writing the information to the Siebel log files. You can
improve server performance by increasing the parameter value, however
information from the end of the run will be missing from the Analysis
graphs. We recommend setting SIEBEL_SarmMaxMemory= 50000 for low
loads on the server and SIEBEL_SarmMaxMemory= 1000000 for high loads
on the server. A low load on the server is 20 Vusers or less, and a high load is
more than 100 Vusers.

The recommended file size for SIEBEL_SarmMaxFileSize is from 5000000 for

low loads on the server to 25000000 for high loads on the server. If more
than one Siebel log file is generated on the server every 10 seconds, you
should increase the SIEBEL_SarmMaxFileSize.

Note: Before running a load test, delete Siebel diagnostics logs from all
servers involved in the load test.

To generate Siebel Server IDs:

On the Siebel application server, open a command window and run the
command:

<Siebel bin directory>\srvrmgr /u <username> /p <password> /g <gateway

server> /e <entrpr server> /c "list servers show SBLSRVR_NAME, SV_SRVRID"

where:

/u <username> is the server administrator username

/p <password> is the server administrator password

330
 Chapter 19 • ERP/CRM Diagnostics Modules

/g <gateway server> is the gateway server address

/e <entrpr server> is the enterprise server name

/c <command> is the execute a single command

This command generates a list of all the Siebel application servers and their
IDs. Keep a record of the server IDs, since this information is required in the
Siebel Server Configuration dialog box. For more information, see step 6 of
“Setting Up the Siebel Diagnostics Module” on page 333.

Configuring Diagnostics where the Web Server is Inside a DMZ

If you are using an application server in the internal network and a Web
(file) server in a DMZ (a "neutral zone" that separates an internal network
from a public one that is used to prevent outside access to a company’s
private data), you must install the mediator on the internal (over firewall)
LAN, and enable SMB/CIFS communication from the internal machine to
the file server in the DMZ. SMB/CIFS are the file sharing services that use the
NBT (NetBIOS over TCP/IP) as the transport protocol.

To enable the NBT protocol between the client (over firewall machine) and
the file server, use the following port configuration:

File Sharing Service Port

SMB/CIFS over NBT TCP 139 (SMB)

CIFS over TCP/IP (Direct SMB) TCP 445

For example, configure the firewall settings as follows:

Service enabled: "nbsession" for TCP 139 connection.

Service enabled: "Microsoft-ds" for TCP 445 connection.

331
Part V • Working with Diagnostics

Note: CIFS over TCP 445 (direct SMB over TCP/IP) is optional with Windows
2000 and above (since it is a more secure way of communicating with the
file server). To enable CIFS over TCP/IP, you must disable the NetBIOS over
TCP/IP protocol using the operating system configuration.

Copying Files from the Siebel Application Server to the

Mediator
After configuring the application server, you need to copy the files listed
below from the Siebel Application server \bin directory to either the <LR
mediator installation>\bin directory, <Windows>\System32 directory, or any
other directory in PATH on the Siebel mediator machine:

• sarmanalyzer.exe • sslcshar.dll
• sslcver.dll • sslcosa.dll
• sslcsym.dll

332
 Chapter 19 • ERP/CRM Diagnostics Modules

Setting Up the Siebel Diagnostics Module

To generate transaction breakdown data, you set up the Siebel Diagnostics
module to communicate with the mediator machine and define the servers
that you want to monitor. You can then enable the diagnostics module and
specify the sampling percentage of transaction data to include in the
diagnostics graphs, as described in “Enabling Diagnostics” on page 354.

Note: The settings that you configure are per scenario. All scripts in the
scenario will run under the same diagnostics configuration.

To set up the Siebel Diagnostics module:

1 From the Controller menu, choose Diagnostics > Configuration > Siebel.
The Siebel Configuration dialog box opens.

2 Enter the Mediator information as described in “Understanding the Siebel

Configuration Dialog Box” on page 335.
3 If you are monitoring over a firewall, select Enable Firewall and enter the
name or IP address of the Mercury listener machine. For more information,
see Chapter 15, “Using Firewalls in LoadRunner.”

333
Part V • Working with Diagnostics

4 To test the connection between the Controller and the mediator, click Test
Connection. The Siebel Diagnostics module attempts to connect to the
mediator.
If the connection is not successful, see the Output window for more
information. You can view the Output window by clicking the Errors link in
the status bar.
5 Click Add to add Siebel servers. The Siebel Server Configuration dialog box
opens.

6 Enter the Siebel server information as described in “Understanding the

Siebel Server Configuration Dialog Box” on page 336, and then click OK.
The Siebel Configuration dialog box is redisplayed.
7 To show server information for a selected Siebel server, click Details.
8 Click OK to close the Siebel Configuration dialog box.

334
 Chapter 19 • ERP/CRM Diagnostics Modules

Understanding the Siebel Configuration Dialog Box

You use the Siebel Configuration dialog box to define the mediator
machine, provide details of the monitored servers, and test the connection
between the Controller and the mediator machines.

Mediator

Name: Enter the name of the mediator machine used to collect and process
the Siebel diagnostics data. Only one mediator machine is supported for
each diagnostics module.

Note: If you are using a mediator that is over a firewall, enter the local
machine key of the mediator instead of the mediator machine name.

Enable Firewall: Select if you are monitoring over a firewall.

MI Listener: Enter the name, full name, or IP address of the Mercury listener
machine if you are monitoring over a firewall.

Test Connection: Tests the connections between the Siebel Diagnostics

module and the mediator machine.

Note: The test connection does not check the connections to the Siebel
servers.

335
Part V • Working with Diagnostics

Servers

Server Name: The name of the Siebel CRM server.

Server ID: The Siebel server ID (for Siebel application servers only).

Platform: The platform of the Siebel CRM server.

Log Directory: The Siebel server directory where Siebel log files are written.

Add: Opens the Siebel Server Configuration dialog box enabling you to
enter Siebel server information.

Delete: Deletes a server from the server list.

Details: Displays information for a selected server.

Understanding the Siebel Server Configuration Dialog Box

You use the Siebel Server Configuration dialog box to enter the Siebel server
information.

Server Name: Enter the name of the Siebel server.

Server Type: Select the Siebel server type.

OS: Select the Siebel server platform.

App Server ID: Enter the Siebel server ID (required for Siebel application
servers only). For information on generating server IDs, see “Configuring
Siebel Diagnostics on the Application and Web Servers” on page 329.

Log Directory: Enter a location where the Siebel application saves the log
files. The log files can be saved in a shared log directory on the Siebel server
or in a separate folder.

336
 Chapter 19 • ERP/CRM Diagnostics Modules

User Name: Enter the user name of the machine where log files are stored.

Note: For Windows platforms, the user should have administrator

privileges. For UNIX platforms, you should verify the following:

1. RSH and RCP daemons should be running on the UNIX server.

2. The user should have permission to run remote shell commands. To

check this, type the following at the DOS command prompt: rsh <server
machine name> -l <UNIX user login name> -n <command>. For example: rsh
my_unix -l my_name -n “cd ~;pwd”. For more information on using UNIX
shell commands, see “UNIX Shell” on page 441.

3. No output should be generated after executing the RSH command. Due to

a bug in the RCP UNIX command, you should not generate output from the
.login, .profile, and .cshrc files, (for example by echo, or by any other form
including commands that generate output indirectly, such as biff). Where
an existing user generates output in the RSH step that cannot be deleted,
you should create a new user that does not generate output and that has
permissions to run RSH and RCP commands on the server machine.

User Password: Enter the user password.

Domain: Enter the Siebel server domain.

337
Part V • Working with Diagnostics

Configuring Siebel DB Diagnostics

To generate Siebel DB transaction breakdown data, perform the following:

➤ Prepare the Script

➤ Synchronize Times
➤ Enable Server Logging on the Siebel Server
➤ Set Up Siebel DB Diagnostics from the Controller
➤ Enable Siebel DB Diagnostics from the Controller
➤ Run the Load Tests
➤ View Diagnostics Results

Preparing the Script

When preparing your script for transaction breakdown, it is recommended
that you add think time at the end of each transaction using the ratio of one
second per hour of testing.

To avoid session ID conflicts, make sure that the Vusers log off from the
database at the end of each session.

Synchronizing Times
Synchronizing times before performing transaction breakdown ensures that
the correlation of SQLs to transactions is correct. From the Controller
machine, synchronize the time with the Siebel Gateway server by running
the following command:

net time \ <Gateway name> /set /y

Replace <Gateway name> with the name of the Siebel Gateway.

338
 Chapter 19 • ERP/CRM Diagnostics Modules

Enabling Server Logging on the Siebel Server

Before you set up the Siebel DB diagnostics module on the Controller, you
must configure the Siebel server to create the database log files.

To enable logging on the Siebel server:

1 On the Siebel server, open a command window and run the command:
<Siebel bin directory>\srvrmgr /g <gateway server> /s <Siebel server> /e
<enterprise server name> /u <username> /p <password>
2 Enter the following commands:
change evtloglvl ObjMgrsqllog=4 for comp <component name>

evtloglvl EventContext=3 for comp <component name>

evtloglvl ObjMgrSessionInfo =3 for comp <component name>

For the Call Center, enter sccobjmgr_enu as the component name. For
example:

change evtloglvl ObjMgrsqllog=4 for comp sccobjmgr_enu

To disable logging on the Siebel server:

On the Siebel server, enter the following commands:

change evtloglvl ObjMgrsqllog=0 for comp <component name>

change evtloglvl EventContext=0 for comp <component name>

change evtloglvl ObjMgrSessionInfo =0 for comp <component name>

Note: Before running a load test, delete log files from all servers involved in
the load test.

339
Part V • Working with Diagnostics

Setting Up the Siebel DB Diagnostics Module

To generate transaction breakdown data, you set up the Siebel DB
Diagnostics module to communicate with the mediator machine and define
the servers that you want to monitor. You can then enable the diagnostics
module and specify the sampling percentage of transaction data to include
in the diagnostics graphs, as described in “Enabling Diagnostics” on
page 354.

Note: The settings that you configure are per scenario. All scripts in the
scenario will run under the same diagnostics configuration.

For meaningful transaction breakdown results, you should define every

action as a transaction in the Vuser script Run-time Settings. If you want
VuGen to define each action as a transaction, run the script with Automatic
Transactions at the action level (enabled by default). To check this setting,
open Run-Time Settings, General:Miscellaneous node, and ensure that
Define each action as a transaction is enabled.

340
 Chapter 19 • ERP/CRM Diagnostics Modules

To set up the Siebel DB Diagnostics module:

1 From the Controller menu, choose Diagnostics > Configuration > Siebel DB.
The Siebel DB Configuration dialog box opens.

2 Enter the Mediator information as described in “Understanding the Siebel

DB Configuration Dialog Box” on page 343.
3 If you are monitoring over a firewall, select Enable Firewall and enter the
name or IP address of the Mercury listener machine. For more information,
see Chapter 15, “Using Firewalls in LoadRunner.”
4 To test the connection between the Controller and the mediator, click Test
Connection. The Siebel Diagnostics module attempts to connect to the
mediator.
If the connection is not successful, see the Output window for more
information. You can view the Output window by clicking the Errors link in
the status bar.

341
Part V • Working with Diagnostics

5 To add Siebel servers, click Add. The Siebel DB Server Configuration dialog
box opens.

6 Enter the Siebel DB server information as described in “Understanding the

Siebel DB Server Configuration Dialog Box” on page 344, and then click OK.
The Siebel DB Configuration dialog box is redisplayed.
7 To show server information for a selected Siebel server, click Details.
8 Click OK to close the Siebel DB Configuration dialog box.

342
 Chapter 19 • ERP/CRM Diagnostics Modules

Understanding the Siebel DB Configuration Dialog Box

You use the Siebel DB Configuration dialog box to define the mediator
machine, provide details of monitored servers, and test the connection
between the Controller and the mediator machines.

Mediator

Name: Enter the name of the mediator machine used to collect and process
the Siebel diagnostics data. Only one mediator machine is supported for
each diagnostics module.

Note: It may take a long time to copy the Siebel diagnostics files from the
application server to the mediator, and then from the mediator to the
results directory. During the first copying stage, the Summary Data
Processing window is displayed. To minimize copying time in the second
stage (if you are not working over a firewall), we recommend using localhost
as the mediator machine. This reduces the time it takes to copy the Siebel
DB diagnostics files to the results directory, since the diagnostics files are
already on the Controller machine.

If you are using a mediator that is over a firewall, enter the local machine
key of the mediator instead of the mediator machine name.

Enable Firewall: Select if you are monitoring over a firewall.

MI Listener: Enter the name, full name, or IP address of the Mercury listener
machine if you are monitoring over a firewall.

Test Connection: Tests the connections between the Siebel DB Diagnostics

module and the mediator machine.

Note: The test connection does not check the connections to the Siebel
servers.

343
Part V • Working with Diagnostics

Servers

Server: The name of the Siebel server.

Platform: The platform of the Siebel server.

Log Directory: The directory where Siebel log files are written.

Add: Opens the Siebel DB Server Configuration dialog box enabling you to
enter Siebel server information.

Delete: Deletes a server from the server list.

Details: Displays information for a selected server.

Understanding the Siebel DB Server Configuration Dialog Box

You use the Siebel DB Server Configuration dialog box to enter the Siebel
server information.

Server Name: Enter the name of the Siebel server.

Server Platform: Select the Siebel server platform.

Log Directory: Enter a location where the Siebel application saves the log
files. The log files can be saved in a shared log directory on the Siebel server
or in a separate folder.

344
 Chapter 19 • ERP/CRM Diagnostics Modules

User Name: Enter the user name of the machine where log files are stored.

Note: For Windows platforms, the user should have administrator

privileges. For UNIX platforms, you should verify the following:

1. RSH and RCP daemons should be running on the UNIX server.

2. The user should have permission to run remote shell commands. To

check this, type the following at the DOS command prompt: rsh <server
machine name> -l <UNIX user login name> -n <command>. For example: rsh
my_unix -l my_name -n “cd ~;pwd”. For more information on using UNIX
shell commands, see “UNIX Shell” on page 441.

3. No output should be generated after executing the RSH command. Due to

a bug in the RCP UNIX command, you should not generate output from the
.login, .profile, and .cshrc files, (for example by echo, or by any other form
including commands that generate output indirectly, such as biff). Where
an existing user generates output in the RSH step that cannot be deleted,
you should create a new user that does not generate output and that has
permissions to run RSH and RCP commands on the server machine.

User Password: Enter the user password.

Domain: Enter the Siebel server domain.

345
Part V • Working with Diagnostics

Configuring Oracle DB Diagnostics

To generate Oracle DB transaction breakdown data, perform the following:

➤ Enable Server Logging on the Oracle Server

➤ Select the version of your Oracle NCA server (in VuGen)
➤ Set Up Oracle DB Diagnostics from the Controller
➤ Enable Oracle DB Diagnostics from the Controller
➤ Run the Load Tests
➤ View Diagnostics Results

Enabling Server Logging on the Oracle Server

To enable server logging on the Oracle server, verify that the trace
diagnostics are enabled and set the trace file size to unlimited. By default,
trace diagnostics are enabled on the Oracle server during installation. In
addition, to help LoadRunner deal with the Oracle application diagnostics
password, you can either set the diagnostics password in the Vuser script or
disable the password request on the application server.

To check that trace diagnostics are enabled:

1 Log on to the Oracle application server with administrator privileges, and
select the module you want in the Oracle Application. The Responsibilities
dialog box opens.
2 Select System Administrator and click OK.
3 In the Functions tab, select Profile > System and click Open. The System
Profile Values dialog box opens.
4 In the Display section, select Site and Profiles with No Values, enter
%Diagnostics% in the Profiles field, and then click Find.
5 If any diagnostics profiles are disabled (denoted by a “Yes” in the Site
column), change the setting to “No”.
6 Save your settings.

346
 Chapter 19 • ERP/CRM Diagnostics Modules

To set the trace file size to unlimited:

For Oracle 9i:

On the Oracle server, run the following command in the SQL editor:

Alter system set max_dump_file_size=UNLIMITED scope=both;

For Oracle 8i:

1 On the Oracle server, run the following command in the SQL editor:
Alter system set max_dump_file_size=2048000;
2 Edit the init*.ora file on $ORACLE_HOME\admin\<sid>\pfile\init<sid>.ora.
Find the line of the parameter, change its value, and then save the file.

Note: Verify that you have enough disk space on the database server since
these trace file can be very large.

To set the diagnostics password in the Vuser script:

In VuGen, add the nca_set_diagnostics_password(<password>) function
to your script and select a password.

Note: The nca_set_diagnostics_password function must come after the

nca_connect_server function.

347
Part V • Working with Diagnostics

To disable the diagnostics password request on the application server:

1 Log on to the Oracle application server with administrator privileges, and
select the module you want in the Oracle Application. The Responsibilities
dialog box opens.
2 Select System Administrator and click OK.
3 In the Functions tab, select Profile > System and click Open. The System
Profile Values dialog box opens.
4 In the Display section, select User, and enter the required user name. In the
Profile field, enter %Utilities:Diagnostics% and click Find. The
Utilities:Diagnostics profile values are displayed.
5 In the User column of the Utilities:Diagnostics profile, set the value to Yes.
6 Save your settings.

Selecting the Oracle NCA Application Version

The Oracle DB diagnostics module supports Oracle NCA versions 11.5.0 and
later. Enter the version of your Oracle application server in VuGen’s run-
time settings to enable the built-in trace mechanism. To check the version of
your Oracle server, log in to the Oracle server and click Help > About Oracle.
The version of your Oracle server is displayed in the Oracle Application
field.

To enter your Oracle application version:

Open the script in VuGen and select Vuser > Run-Time Settings. In the
Oracle NCA: Client Emulation node, select the version of Oracle NCA that
you are using in the Diagnostics > Application Version field.

Note: If the Oracle DB trace cannot be enabled using the built-in

mechanism, you can enable it manually in the Vuser script using the
nca_set_custom_dbtrace and nca_set_dbtrace_file_index functions. This
may occur if you are using a custom application that does not have a
standard UI.

348
 Chapter 19 • ERP/CRM Diagnostics Modules

Note: Before running a load test, delete trace log files from all servers
involved in the load test.

Real users should not work on the Oracle server while the diagnostics
module is running, as this may affect transaction breakdown results.

Setting Up the Oracle DB Diagnostics Module

To generate transaction breakdown data, you set up the Oracle DB
Diagnostics module to communicate with the mediator machine and define
the servers that you want to monitor. You can then enable the diagnostics
module and specify the sampling percentage of transaction data to include
in the diagnostics graphs, as described in “Enabling Diagnostics” on
page 354.

Note: The settings that you configure are per scenario. All scripts in the
scenario will run under the same diagnostics configuration.

For meaningful transaction breakdown results, you should define every

action as a transaction in the Vuser script Run-time Settings. If you want
VuGen to define each action as a transaction, run the script with Automatic
Transactions at the action level (enabled by default). To check this setting,
open Run-Time Settings, General:Miscellaneous node, and ensure that
Define each action as a transaction is enabled.

349
Part V • Working with Diagnostics

To set up the Oracle DB Diagnostics module:

1 From the Controller menu, choose Diagnostics > Configuration > Oracle DB.
The Oracle Configuration dialog box opens.

2 Enter the Mediator information as described in “Understanding the Oracle

Configuration Dialog Box” on page 352.
3 If you are monitoring over a firewall, select Enable Firewall and enter the
name or IP address of the Mercury listener machine. For more information,
see Chapter 15, “Using Firewalls in LoadRunner.”
4 To test the connection between the Controller and the mediator, click Test
Connection. The Oracle DB diagnostics module attempts to connect to the
mediator.
If the connection is not successful, see the Output window for more
information. You can view the Output window by clicking the Errors link in
the status bar.

350
 Chapter 19 • ERP/CRM Diagnostics Modules

5 Click Add to add Oracle servers. The Oracle Server Configuration dialog box
opens.

6 Enter the Oracle server information as described in “Understanding the

Oracle Server Configuration Dialog Box” on page 353, and then click Ok.
The Oracle Configuration dialog box is redisplayed.
7 To show server information for a selected Oracle server, click Details.
8 Click OK to close the Oracle Configuration dialog box.

351
Part V • Working with Diagnostics

Understanding the Oracle Configuration Dialog Box

You use the Oracle Configuration dialog box to define the mediator
machine, provide details of monitored servers, and test the connection
between the Controller and the mediator machines.

Mediator

Name: Enter the name of the mediator machine used to collect and process
the Oracle DB diagnostics data. Only one mediator machine is supported for
each diagnostics module.

Note: If you are using a mediator that is over a firewall, enter the local
machine key of the mediator instead of the mediator machine name.

Enable Firewall: Select if you are monitoring over a firewall.

MI Listener: Enter the name, full name, or IP address of the Mercury listener
machine if you are monitoring over a firewall.

Test Connection: Tests the connections between the Oracle DB diagnostics

module and the mediator machine.

Note: The test connection does not check the connections to the Oracle
servers.

Servers

Server: The name of the Oracle server.

Platform: The platform of the Oracle server.

Log Directory: The directory where Oracle trace files are written.

Add: Opens the Oracle Server Configuration dialog box enabling you to
enter Oracle server information.

352
 Chapter 19 • ERP/CRM Diagnostics Modules

Delete: Deletes a server from the server list.

Details: Displays information for a selected server.

Understanding the Oracle Server Configuration Dialog Box

You use the Oracle Server Configuration dialog box to enter the Oracle
server information.

Server Name: Enter the name of the Oracle server.

Server Platform: Select the Oracle server platform.

Log Directory: Enter a location where the Oracle application saves the trace
files. The trace files can be saved in a shared directory on the Oracle server or
in a separate folder.

User Name: Enter the user name of the machine where trace files are stored.

Note: For Windows platforms, the user should have administrator

privileges. For UNIX platforms, you should verify the following:

1. RSH and RCP daemons should be running on the UNIX server.

2. The user should have permission to run remote shell commands. To

check this, type the following at the DOS command prompt: rsh <server
machine name> -l <UNIX user login name> -n <command>. For example: rsh
my_unix -l my_name -n “cd ~;pwd”. For more information on using UNIX
shell commands, see “UNIX Shell” on page 441.

3. No output should be generated after executing the RSH command. Due to

a bug in the RCP UNIX command, you should not generate output from the
.login, .profile, and .cshrc files, (for example by echo, or by any other form
including commands that generate output indirectly, such as biff). Where
an existing user generates output in the RSH step that cannot be deleted,
you should create a new user that does not generate output and that has
permissions to run RSH and RCP commands on the server machine.

353
Part V • Working with Diagnostics

User Password: Enter the user password.

Domain: Enter the Oracle server domain.

Enabling Diagnostics
After setting up the diagnostics module and successfully testing the
connection between the Controller and the mediator machines, you enable
the diagnostics module and specify the sampling percentage of transaction
data to include in the diagnostics graphs.

Note: The Diagnostics Distribution dialog box is disabled during scenario

execution.

To enable transaction breakdown:

1 From the Controller menu, choose Diagnostics > Distribution. The
Diagnostics Distribution dialog box opens.

354
 Chapter 19 • ERP/CRM Diagnostics Modules

2 To enable transaction breakdown monitoring, select Enable the following

diagnostics and set the percent of Vusers to participate in the monitoring as
described in “Understanding the Diagnostics Distribution Dialog Box” on
page 355.

Note: If you run a script containing Vusers that are supported by more than
one diagnostics type (for example Siebel-Web), the same Vusers will be
monitored by all the diagnostics modules which support that Vuser type.
This enables you to compare results generated in different diagnostics
modules.

3 Select the diagnostics types for which you want transaction breakdown to be
performed and click OK.

Understanding the Diagnostics Distribution Dialog Box

➤ Enable the following breakdown: Enables LoadRunner to generate offline
Web Page, Siebel, Siebel DB, and Oracle DB breakdown graphs, and online
and offline J2EE breakdown graphs.
➤ For X % of all the relevant Vusers in the current scenario: Specify the
percentage of Vusers for which you want transaction breakdown to be
performed. The percent determines how many of the transactions on the
application server are reported to the Controller. Reducing this number
will reduce the overhead on the application server for Web Page and
Oracle DB diagnostics.

Note: The minimum transaction breakdown is 1% or 1 virtual user per

script, whichever is more. The maximum is the lowest of the maximum
percent of all the selected diagnostics types. For example, if you enter a
sampling value of 25% and run 12 Vusers in script1, 8 Vusers in script2, and 1
Vuser in script3, transaction breakdown will be performed on 3 Vusers in
script1, 2 Vusers in script2, and 1 Vuser in script3.

355
Part V • Working with Diagnostics

Offline Diagnostics

➤ Web Page Diagnostics: Generates Web Page Breakdown graphs, which

provide you with performance information for each transaction and sub-
transaction defined in your script. The maximum number of Vusers for
which transaction breakdown can be performed is 10%.
➤ Siebel Diagnostics: Generates Siebel Breakdown graphs that allow you to
breakdown Siebel transactions into layers, areas, sub-areas, servers, and
scripts. This enables you to pinpoint the exact location where time is
consumed. You can also view the transaction chain of calls and call stack
statistics to track the percent of time spent for each part of the transaction.
The maximum number of Vusers for which transaction breakdown can be
performed is 10%, or not more than 100 Vusers.
➤ Siebel DB Diagnostics: Generates Siebel DB Breakdown graphs that allow
you to breakdown transactions to their SQLs statements and stages. This
enables you to pinpoint problem areas in any layer of the Siebel database
calls. The maximum number of Vusers for which transaction breakdown can
be performed is 10%.
➤ Oracle DB Diagnostics: Generates Oracle DB Breakdown graphs that allow
you to breakdown transactions to their SQLs statements and stages. This
enables you to pinpoint problem areas in any layer of the Oracle database
calls. The maximum number of Vusers for which transaction breakdown can
be performed is 5%.

Online and Offline Diagnostics

➤ J2EE Diagnostics: Provides online and offline J2EE transaction breakdown

diagnostic graphs. In the online diagnostics, you can view the entire chain
of activity on the server side of the system. You can break down J2EE layers
into components and methods to enable you to pinpoint the exact location
where time is consumed. You can also view the transaction chain of calls
and call stack statistics to track the percent of time spent for each part of the
transaction. The maximum number of Vusers for which transaction
breakdown can be performed is 100%. For more information, see
Chapter 18, “J2EE Diagnostics Module.”

356
 Chapter 19 • ERP/CRM Diagnostics Modules

After a scenario run, you can use the J2EE transaction breakdown graphs to
analyze server performance and generate reports. For more information,
refer to “J2EE Transaction Breakdown Graphs” in the LoadRunner Analysis
User’s Guide.

Viewing Diagnostics Results

To view transaction breakdown results, choose Diagnostics > Analyze
Diagnostics Results in the Run tab of the Controller. The LoadRunner
Analysis opens.

You can use the Analysis transaction breakdown graphs and reports to view
the performance data and drill down to pinpoint problem areas in any layer
of the application.

For more information about ERP/CRM Transaction Breakdown Diagnostics

graphs, see the LoadRunner Analysis User’s Guide.

357
Part V • Working with Diagnostics

358
 Part VI
Monitoring a Scenario
360
20
Online Monitoring

You can monitor scenario execution using the LoadRunner online monitors.

This chapter describes the online monitor user interface. The specific
monitors are discussed in the LoadRunner Monitor Reference.

➤ About Online Monitoring

➤ Setting Up the Monitoring Environment
➤ Monitor Types
➤ Choosing Monitors and Measurements in the Controller
➤ Starting the Monitors in the Controller
➤ Opening Online Monitor Graphs in the Controller
➤ Customizing the Online Monitor Display View
➤ Setting Monitor Options

About Online Monitoring

LoadRunner enables you to view data generated during scenario execution
using the online monitors. You specify the machines that the Controller will
monitor during a scenario execution, and view the data collected by the
monitors, using the LoadRunner online graphs.

361
Part VI • Monitoring a Scenario

A primary factor in a transaction’s response time is its resource usage. By

monitoring resources during a scenario run, you can determine why a
bottleneck occurred on a particular machine. LoadRunner’s server resource
monitors let you keep track of resources used during a scenario. LoadRunner
displays the selected resource monitors in real time during test execution.
Note that you can select the server resource measurements to monitor both
before and during the scenario.

Setting Up the Monitoring Environment

Before monitoring a scenario, you need to set up and configure the
LoadRunner monitoring components. Each monitor has different
configuration requirements which are explained in the specific monitoring
chapters in the LoadRunner Monitor Reference. The diagram below shows the
LoadRunner monitoring process.

Before monitoring a server, perform the following steps:

➤ configure the monitoring environment on the server machine (if necessary)

➤ configure the monitor on the Controller or Console machine

362
 Chapter 20 • Online Monitoring

Configuring the Monitoring Environment on the Server

Machine
To use the following monitors, you must first install or configure
monitoring components on the server machine:

• COM+ • SAPGUI
• Citrix • SAP Portal
• DB2 • SAP CCMS
• IBM WebSphere MQ • Siebel Server Manager
• iPlanet (NAS) • Siebel Web Server
• J2EE • SiteScope
• J2EE Transaction • Sybase
Breakdown • Tuxedo
• .NET CLR • UNIX
• Network Delay • WebLogic (JMX)
• Oracle • WebSphere (EPM)
• PeopleSoft (Tuxedo) • WebSphere
• SAP

Configuring the Monitor on the Controller Machine

To obtain performance data for a monitor, you need to enable the monitor
(from the Controller), and indicate which statistics and measurements you
want to monitor. You select these counters using the monitor’s Add
Measurements dialog box.

For more information on setting up the monitoring environment and

configuring a monitor, see the specific monitoring chapter in the
LoadRunner Monitor Reference.

363
Part VI • Monitoring a Scenario

Monitor Types
The online monitors are divided into the following categories:

➤ Run-Time Monitors
Display the number and status of Vusers participating in the scenario, as
well as the number and types of errors that the Vusers generate. For more
information, see refer to the chapter “Run-Time and Transaction
Monitoring” in the LoadRunner Monitor Reference.
➤ Transaction Monitors
Display the transaction rate and response time during scenario
execution. For more information, see refer to the chapter “Run-Time and
Transaction Monitoring” in the LoadRunner Monitor Reference.
➤ Web Resource Monitors
Provide information about the number of Web connections, throughput
volume, HTTP responses, server retries, and pages downloaded to the
Web servers during the scenario. For more information, refer to the
chapter “Web Resource Monitoring” in the LoadRunner Monitor Reference.
➤ System Resource Monitors
Measure the Windows, UNIX, Tuxedo, SNMP, Antara FlameThrower, and
SiteScope resources used during a scenario. For more information, refer to
the chapter “System Resource Monitoring” in the LoadRunner Monitor
Reference.
➤ Network Delay Monitor
Displays information about the network delays on your system. For more
information, refer to the chapter “Network Monitoring” in the
LoadRunner Monitor Reference.
➤ Firewall Monitor
Measures statistics of the firewall servers during the scenario. For more
information, refer to the chapter “Firewall Server Performance
Monitoring” in the LoadRunner Monitor Reference.
➤ Web Server Resource Monitors
Measure statistics of the Apache, Microsoft IIS, iPlanet (SNMP), and
iPlanet/Netscape Web servers during the scenario. For more information,
refer to the chapter “Web Server Resource Monitoring” in the LoadRunner
Monitor Reference.

364
 Chapter 20 • Online Monitoring

➤ Web Application Server Resource Monitors

Measure statistics of the Ariba, ATG Dynamo, BroadVision, ColdFusion,
Fujitsu INTERSTAGE, iPlanet (NAS), Microsoft ASP, Oracle9iAS HTTP,
SilverStream, WebLogic (SNMP), WebLogic (JMX), and WebSphere
application servers during the scenario. For more information, refer to
the chapter “Web Application Server Resource Monitoring” in the
LoadRunner Monitor Reference.
➤ Database Server Resource Monitors
Measure statistics of the SQL server, Oracle, Sybase, and DB2 databases
during the scenario. For more information, refer to the chapter “Database
Resource Monitoring” in the LoadRunner Monitor Reference.
➤ Streaming Media Monitors
Measure statistics of the Windows Media Server and RealPlayer
audio/video servers, as well as the RealPlayer client during the scenario.
For more information, refer to the chapter “Streaming Media
Monitoring” in the LoadRunner Monitor Reference.
➤ ERP/CRM Server Resource Monitors
Measure statistics of the SAP R/3 system, SAP Portal, Siebel Server
Manager, Siebel Web Server, and PeopleSoft (Tuxedo) servers during the
scenario. For more information, refer to the chapter “ERP/CRM Server
Resource Monitoring” in the LoadRunner Monitor Reference.
➤ Java Performance Monitors
Measure statistics of Java 2 Platform, Enterprise Edition (J2EE) objects,
and Java-based applications, using J2EE machines. For more information,
refer to the chapter “J2EE Performance Monitoring” in the LoadRunner
Monitor Reference.
➤ J2EE Transaction Breakdown Monitors
Provide information to trace, time, and troubleshoot individual
transactions through J2EE Web, application, and database servers. For
more information, refer to the chapter “J2EE Diagnostics Module” in the
LoadRunner Controller User’s Guide.
➤ Application Component Monitors
Measure statistics of the Microsoft COM+ and Microsoft .NET CLR servers
during a scenario run. For more information, refer to the chapter
“Application Component Monitoring” in the LoadRunner Monitor
Reference.

365
Part VI • Monitoring a Scenario

➤ Application Deployment Solutions Monitor

Measures statistics of the Citrix MetaFrame XP and 1.8 servers during a
scenario run. For more information, refer to the chapter “Application
Deployment Solutions” in the LoadRunner Monitor Reference.
➤ Middleware Performance Monitors
Measure statistics of the Tuxedo and IBM WebSphere MQ servers during a
scenario run. For more information, refer to the chapter “Middleware
Performance Monitoring” in the LoadRunner Monitor Reference.
➤ Infrastructure Resources Monitor
Measure statistics of the network client data points during a scenario run.
For more information, refer to the chapter “Infrastructure Resources
Monitoring” in the LoadRunner Monitor Reference.

For information on configuring graph settings and measurements, and

exporting graph data, see Chapter 21, “Configuring Online Graphs.”

All of the monitors allow you to view a summary of the collected data at the
conclusion of the scenario. Using LoadRunner Analysis, you can generate a
graph for any of the monitors. For more information, refer to the
LoadRunner Analysis User’s Guide.

Note: Application component monitors are available only in the

LoadRunner Controller. Application traffic and security monitors are
available only in the Mercury Tuning Module Console User’s Guide.

For a detailed list of LoadRunner’s monitors, see Mercury’s Web site

(http://www.mercuryinteractive.com/products/loadrunner/load_testing_monitors/
supported.html).

366
 Chapter 20 • Online Monitoring

Choosing Monitors and Measurements in the Controller

You specify the machines and measurements that the Controller will
monitor during a scenario execution, using the monitored server machine
dialog box.

To monitor a machine’s resources:

1 Open the graph that you want to monitor in the graph view area and
choose Monitors > Add Measurements, or right-click the graph and select
Add Measurements. The monitored server machine dialog box opens.

2 In the Monitored Server Machines section, click Add. The Add Machine
dialog box opens.

367
Part VI • Monitoring a Scenario

Note: For monitors that use SiteScope to monitor the server, an additional
SiteScope Server Information section is displayed. For more information, see
the relevant monitoring section.

3 Enter the server name or IP address of the machine you want to monitor,
select the platform on which the machine runs, and click OK.
The machine that was added is displayed in the Monitored Server Machines
box of the monitored server machine dialog box.

368
 Chapter 20 • Online Monitoring

4 Select the server machine that you want to monitor and, under the Resource
Measurements on <server> box, click Add.
The monitored server Add Measurements dialog box opens, displaying the
available measurements.

Note: The Add Measurements dialog box is different for each monitor. See
the relevant monitoring section for specific add measurement instructions.

5 Select the required measurements. You can select multiple measurements

using the CTRL key.

369
Part VI • Monitoring a Scenario

6 Click OK. The Add Measurements window closes, and the selected
measurements are displayed in the Resource Measurement on <server> box
of the monitored server machine dialog box.

7 Click OK in the monitored server machine dialog box to activate the

monitor.

Understanding the Add Machine Dialog Box

Adds the machine that you want to monitor to the Monitored Server
Machines list.

Monitored Machine Information

➤ Name: Enter the name or IP address of the machine that you want to
monitor.
➤ Platform: Enter the platform of the machine you want to monitor.

370
 Chapter 20 • Online Monitoring

SiteScope Server Information

For monitors that use SiteScope, enter the following SiteScope server
information:

➤ Name: Enter the name of the SiteScope server.

➤ Port: Enter the SiteScope port (default:8888).
➤ Version: Enter the version of SiteScope running.

Understanding the Monitored Server Machine Dialog Box

Monitored Server Machines: The machines whose resources are being
monitored.

➤ Add: Displays the Add Machine dialog box, which adds the machine that
you want to monitor to the existing list.
➤ Delete: Removes the selected machine from the list.

Note: In some cases, you can (or must) specify the server you want to
monitor using other formats. See the relevant monitoring section in the
LoadRunner Monitor Reference for more information.

Resource Measurements on <machine name>: Displays the resource

measurements being monitored on the selected machine.

➤ Add: Opens a dialog box that lets you create a list of resources to monitor
on the selected machine.
➤ Delete: Removes the selected resource measurement from the list.
Description: Displays a description of the selected resource measurement.

Note: For information about setting up a specific server monitor before

configuring its measurements, see the relevant monitoring section in the
LoadRunner Monitor Reference.

371
Part VI • Monitoring a Scenario

Starting the Monitors in the Controller

To start the online monitors:
1 Start the scenario. Select the Vuser groups you want to run and click Start
Scenario, or choose Scenario > Start.
2 Select the Run tab. The default graphs are displayed below the Scenario
Groups window.

3 Double-click a graph to maximize it. Repeat the operation to restore the

tiled view.

372
 Chapter 20 • Online Monitoring

4 If the graph tree is not displayed, choose View > Show Available Graphs.
Click the "+" in the left pane to expand the graph tree. To hide the graph
tree view, choose View > Hide Available Graphs, or click the X button in the
right corner of the Available Graphs list.
5 Select a graph from the tree and drag it into the right pane. You can also
drag graphs between panes.

Note: The Transaction Monitor graphs will not contain any data unless
transactions are being executed. In addition, the other graphs will not
contain any data unless you set up a list of resources to monitor before
running your scenario.

373
Part VI • Monitoring a Scenario

Opening Online Monitor Graphs in the Controller

By default, LoadRunner displays four graphs in the Run view: Running
Vusers, Transaction Response Time, Hits per Second, and Windows
Resources. You can display the other graphs by clicking and dragging them
from the graph tree view to the graph view area. Alternatively, you can open
a new graph using the Open a New Graph dialog box.

To open a new graph using the Open a New Graph dialog box:
1 Choose Monitors > Online Graphs > Open a New Graph, or right-click a
graph and select Open a New Graph. The Open a New Graph dialog box
opens.

2 Click the "+" in the left pane to expand the graph tree, and select a graph.
You can view a description of the graph in the Graph Description box.
3 Click Open Graph, or drag the selected graph into the right pane of the
Session view. The graph appears in the graph view area.

374
 Chapter 20 • Online Monitoring

Understanding the Open a New Graph Dialog Box

The Open a New Graph dialog box enables you to open a new graph and
view its description.

Select a graph: Click the "+" to the left of each category to expand the tree
view. Select a graph.

Note: You can open only one graph at a time.

Display only graphs containing data: Select this option to view graphs that
contain data only. To view the entire list of LoadRunner Analysis graphs,
clear this option.

Graph description: Displays the selected graph’s description.

Open Graph: Opens the selected graph and displays it in the graph tree
view.

Understanding the Select Online Graphs Dialog Box

The Select Online Graphs dialog box allows you to specify the graphs that
will be displayed in the Session tab, and the position that each graph will
occupy.

The graphs are specific to the step for which you define them. When you
save a session and subsequently reopen it, these are the graphs that are
displayed for the step.

To select a graph for display:

Click the graph in the Available Graphs section and then click the right-
arrow to move the graph to the Selected Graphs section.

To remove a graph from the list of graphs to display:

Click the graph in the Selected Graphs section and then click the left-arrow.
The graph is removed from the Selected Graphs section.

375
Part VI • Monitoring a Scenario

To change the order in which the graphs are displayed in the Session tab:
The graph at the top of the list in the Selected Graphs pane will be displayed
in the top row in the left-most position. The graph at the bottom of the list
will be displayed in the bottom row in the right-most position.

Select a graph in the Selected Graphs section and then use the up- and
down-arrows to change the graph’s position.

Repeat this process with the other graphs until you have positioned the
graphs correctly.

Customizing the Online Monitor Display View

LoadRunner lets you display up to 16 online monitor graphs
simultaneously.

To customize your online monitor display:

Right-click a graph, select View Graphs, (or you can choose View
> View Graphs in the Controller only), and then select the number of
graphs you want to view. You can choose from Show One Graph,
Show Two Graphs, Show Four Graphs, Show Eight Graphs, or
Custom Number. If you select Custom Number, enter the number of graphs
you want to view in the View Graphs dialog box, and click OK. The number
of graphs selected open in the graph view area.

To display only one graph, double-click the graph pane. To return to the
previous view, double-click the graph again.

376
 Chapter 20 • Online Monitoring

Setting Monitor Options

Before running your scenario, LoadRunner lets you configure the settings
for your online monitors. You can set the data sampling rate, error handling,
debugging, and frequency settings for the online monitors.

When you save a scenario, the online monitor configuration settings are
saved as well.

To set monitor options:

1 Choose Tools > Options and select the Monitors tab.

2 Ensure that Enable Transaction Monitor is selected (default setting), and

specify the frequency at which the monitor should send updates to the
Controller for the Transaction, Data Point, and Web Resource graphs.
To conserve resources, you can disable the Transaction monitor by clearing
the Enable Transaction Monitor check box.

377
Part VI • Monitoring a Scenario

Note: You cannot modify these settings during scenario execution; you
must stop the scenario before disabling the monitor or changing its
frequency.

3 Enter a sampling rate.

4 Set the desired Error Handling option.
5 To display debug messages in the Output window, select the Display debug
messages check box. For the Network monitor, specify a Debug level from
1-9.
6 Click OK to save your settings and close the Options dialog box.

You can configure an additional monitor setting while working in Expert

mode. For information on working in Expert mode, see Appendix C,
“Working in Expert Mode.”

Understanding the Options - Monitors Tab

The Monitors Tab lets you enable the Transaction monitor, configure the
behavior of the transaction data, and set the data sampling rate, error
handling, debugging, and frequency settings for the online monitors.

Transaction Data: Configures the behavior of data for the Transaction, Data
Point, and Web Resource online graphs.

➤ Enable Transaction Monitor: Enables the online Vuser Transaction

monitor to begin monitoring transactions at the start of a scenario.
➤ Frequency: Select the frequency, in seconds, at which the online monitor
samples the data to produce the Transaction, Data Point, and Web
Resource online graphs. The default is 5 seconds. For a small scenario, it
is recommended that you use a frequency of 1. For a large scenario, it is
recommended that you use a frequency of 3-5. The higher the frequency,
the less network traffic there will be. The data is averaged for the
frequency period defined, and only one value is sent to the Controller.

378
 Chapter 20 • Online Monitoring

For information on enabling and disabling the Transaction monitor and

Web page breakdown, refer to the chapter “Run-Time and Transaction
Monitoring” in the LoadRunner Monitor Reference.
Server Resource Monitors: Configures the behavior of the Server Resource
monitors.

➤ Data Sampling Rate: The sampling rate is the period of time (in seconds)
between consecutive samples. Enter the rate at which LoadRunner
samples the scenario for monitoring data. By default, the online monitor
samples the data at intervals of three seconds. If you increase the
sampling rate, the data is monitored less frequently. This setting applies
to all graphs. To set a sampling rate for a specific graph, see “Configuring
Graph Properties” on page 383.

Note: The data sampling rate you set is applied to all server monitors that
you subsequently activate. It is not applied to server monitors that have
already been activated. To apply the new data sampling rate to activated
server monitors, save your scenario and reopen it.

Each monitor has a different minimum sampling rate. If the default

sampling rate, or the rate set in the Options Monitors tab is less than a
monitor’s minimum sampling rate, the monitor will sample data at intervals
of its minimum sampling rate. For example, the minimum sampling rate for
the Oracle Monitor is 10 seconds. If the sampling rate in the Options
Monitors tab is set at less than 10 seconds, the Oracle Monitor will continue
to monitor data at 10 second intervals.

Error Handling: Controls the way in which LoadRunner issues error

messages. Select one of the following options:

➤ Send errors to the Output window: Sends all errors to the Output
window.
➤ Pop-up an error message box: Sends errors to a message box (default). To
dismiss the message box, click OK.

379
Part VI • Monitoring a Scenario

Debug: For debugging a scenario, you can set the following option:

Display debug messages: Sends debug-related messages to the output log.

You can also specify a debug level from 1-9. The debug level is only relevant
to the Network monitor.

380
21
Configuring Online Graphs

You can view the data collected by the monitors using the LoadRunner
online monitor graphs.

➤ About Online Monitor Graphs

➤ Configuring Graph Properties
➤ Configuring Graph Measurements
➤ Merging Graphs
➤ Exporting Online Monitor Graphs
➤ Viewing Data Offline
➤ Available Graphs Tree

About Online Monitor Graphs

Online monitor graphs display performance measurements for those
resources being monitored during scenario execution. Each measurement is
represented on the graph by a colored line. Information about the
measurements is listed in the legend below the graph. The legend displays
the measurements for the selected graph only.

381
Part VI • Monitoring a Scenario

For more information on opening monitor graphs and customizing the

display, see “Opening Online Monitor Graphs in the Controller” on
page 374, and “Setting Monitor Options” on page 377.

To get additional information about a measurement, right-click the

measurement and choose Description.

382
 Chapter 21 • Configuring Online Graphs

To focus on a particular line, you can:

➤ Highlight a measurement: To highlight a specific measurement, select it

in the legend. The corresponding line in the graph is displayed in bold.
➤ Hide a measurement: To hide a measurement, right-click the
measurement and choose Hide. To hide all measurements other than the
measurement selected, right-click the measurement and choose Show
Only Selected. To show a hidden measurement, right-click the
measurement and choose Show.
➤ Pause the monitor: To pause a specific graph during scenario execution,
select the graph and choose Monitors > Online Graph > Freeze, or right-
click the graph and select Freeze. To resume, repeat the above action.
When you resume, the graph displays the data for the paused period.
To maintain the sort order after the legend is refreshed, right-click the graph
and select Keep Legend Sorted. Click again to remove the sort order. The
legend is refreshed every five seconds.

Configuring Graph Properties

LoadRunner lets you configure the settings for your online monitor graphs.
You can customize your graph in the following areas:

➤ Refresh Rate
➤ Time
➤ Graph Time
➤ Display Type
➤ Bar Value
➤ Y-Axis Style
➤ Network Delay View

Note that these settings can be set globally—to apply to all graphs—or per
graph.

383
Part VI • Monitoring a Scenario

To customize your graphs:

1 Select the online graph you want to configure (in either the right or left
pane) and choose Monitors > Online Graphs > Configure. Alternatively,
right-click a graph and select Configure. The Graph Configuration dialog
box opens.

2 Enter the desired refresh rate—the time between graph updates—in the
Refresh Rate box.
3 Select a style for the x-axis from the Time box.
4 Select a value from the Graph Time box. The graph time is the time in
seconds displayed by the x-axis.
5 Select a graph style from the Display Type box.

384
 Chapter 21 • Configuring Online Graphs

6 If the selected display type is Bar, choose a value from the Bar Values Type
box. This determines the type of value that will be displayed in the bar
graph. You can choose between Average, Last Value, Minimum and
Maximum.
7 Select a maximum or minimum value for the y-axis, or choose Automatic to
view graphs using the default y-axis scale.
8 To apply the dialog box settings to all graphs, select Apply to all graphs.
9 For the Network Delay Time graph, you can select the following options:
➤ SubPaths: Displays the delay measurements from the source machine to
each of the nodes along the network path.
➤ DNS name: Displays the DNS names of the measurements in the legend.
10 Click OK to save your settings and close the Graph Configuration dialog
box.

Understanding the Graph Configuration Dialog Box

The Graph Configuration dialog box lets you customize the online graph
settings.

Refresh Rate: The interval at which the graph is refreshed with new data. By
default, the graph is refreshed every five seconds. If you increase the refresh
rate, the data is refreshed less frequently. Note that in a large load test, it is
recommended to use a refresh rate of three to five seconds. This enables you
to avoid problems with CPU resource usage.

Time: You can specify how the graph displays the x-axis time.

➤ Don’t Show: Instructs LoadRunner not to display values for the x-axis.
➤ Clock Time: Displays the absolute time, based on the system clock.
➤ Relative to Scenario Start: Displays the time relative to the beginning of
the scenario. Note that if no step is running, clock time is displayed.

385
Part VI • Monitoring a Scenario

In the following example, the graph is shown with the Don’t Show and
Clock Time options:

Don’t Show Clock Time

Graph Time: Indicate the scale for a graph’s x-axis when it is time-based. A
graph can show 60 to 3600 seconds of activity. To see the graph in greater
detail, decrease the graph time. To view the performance over a longer
period of time, increase the graph time. The available graph times are:
Whole Scenario, 60, 180, 600, and 3600 seconds.

Display Type: Specify whether LoadRunner displays a graph as a line graph

or a bar graph. By default, each graph is displayed as a line graph. Note that
for the Network Delay graph, if you select View Segments, you can view the
network segments of the graph as an area graph or a pie graph.

Bar Value: Choose a value from the Bar Values Type box (if the selected
display type is Bar). This determines the type of value that will be displayed
in the bar graph. You can choose between Average, Last Value, Minimum
and Maximum.

Y-Axis Style: Instruct LoadRunner to display graphs using the default y-axis
scale, or you specify a different y-axis scale. Click Automatic if you want
LoadRunner to use the default y-axis values. Specify a maximum or
minimum value for the y-axis if you want to modify the y-axis scale.

Network Delay View: This option only appears when you configure the
Network Delay Time graph. Click SubPaths to view the delay measurements
from the source machine to each of the nodes along the network path. Click

386
 Chapter 21 • Configuring Online Graphs

DNS name to view the DNS names of the measurements displayed in the
legend.

Configuring Graph Measurements

You can configure the following online measurement settings:

➤ Change Line Colors

➤ Set Measurement Scale
➤ Show and Hide Transactions

Changing Line Colors

LoadRunner assigns a unique color to each measurement. You can modify
the color using the configuration interface.

To change the line color of a measurement:

1 In the legend below the graphs, select the measurement you want to
configure. Right-click and choose Configure. The Measurement
Configuration dialog box opens.

387
Part VI • Monitoring a Scenario

2 To change the color of the line, select a color from the Color list.
3 Click OK to accept the settings and close the dialog box.
The specified color changes are reflected in the graph and in the legend
beneath the graph. The color is displayed in the first column of the legend.

Setting the Scale of the Measurement

You can modify the scale of a measurement—the relationship between the
y-axis and the graph’s actual value. For example, a scale set at 1 indicates
that the measurement’s value is the value of the y-axis. If you choose a scale
of 10, you must divide the y-axis value by 10 to obtain the true value of the
measurement.

To set the scale of a measurement:

1 Select the measurement you want to configure. Right-click and choose
Configure. The Measurement Configuration dialog box opens.
2 Clear the Autoscale check box and select the desired ratio from the Scale list.
3 Click OK to accept the settings and close the dialog box.
In the following example, the same graph is displayed with a scale of 1 and
10:

scale = 1 scale = 10

388
 Chapter 21 • Configuring Online Graphs

The actual graph values range from 0-1, as shown in the left graph. You can
view the information more accurately using a larger scale for the display, as
shown in the right graph. However, to obtain the actual values, you need to
divide the displayed value by the scale. In the example above, the highest
value shown in the graph is 5. Since the scale is 10, the actual value is 0.5.

The legend below the graph indicates the scale factor.

By default, LoadRunner uses the autoscale option, which automatically

scales the measurements by calculating the best ratio for displaying the
graph.

Hiding and Showing Transactions

By default, the Transaction Monitor displays a line for each item in the
transaction list. You can hide the line for any of the monitored transactions
to focus on a specific transaction.

To hide or show a transaction:

1 To hide a transaction, click Hide. To show a hidden resource, click Show. To
hide all transactions other than the transaction selected, right-click the
transaction and choose Show Only Selected.
2 Click OK to accept the settings and close the dialog box.
Note that you can also show and hide transactions without opening the
Measurement Configuration dialog box, by right-clicking a transaction in
the legend and selecting Show/Hide.

389
Part VI • Monitoring a Scenario

In the following example, a line is shown for each transaction:

In this example, the second item in the legend is hidden:

390
 Chapter 21 • Configuring Online Graphs

Understanding the Measurement Configuration -

Configuration Tab
The Measurement Configuration tab lets you change line colors, set the
scale of a measurement, and show or hide transactions.

Measurement: Displays the type of resource being monitored.

Machine: Displays the name of the machine whose resources are being
monitored (appears only in cases where a machine’s resources are being
monitored).

Note: When monitoring a network path, the Network Type will appear here
instead of Machine.

Color: Select a color to be assigned to the selected measurement.

Scale: Displays the relationship between the y-axis and the graph's actual
value. For example, a scale set at 1 indicates that the measurement's value is
the value of the y-axis. If you choose a scale of 10, you must multiply the y-
axis value by 10 to obtain the true value of the measurement.

Autoscale: Instructs LoadRunner to automatically scale the measurement by

calculating the best ratio for displaying the graph. For some graphs, this
option is not available.

Show: Shows the selected resource. The line for the selected resource
reappears in the graph. By default, all resource measurements are displayed
in the chart.

Hide: Hides the selected resource. The line for the selected resource
disappears from the graph. The hidden resources are displayed as unfilled
boxes.

391
Part VI • Monitoring a Scenario

Understanding the Measurement Configuration - Description

Tab
The Measurement Description tab displays information about the
measurement.

Measurement: Displays the type of resource being monitored.

Machine: Displays the name of the machine whose resources are being
monitored (appears only in cases where a machine’s resources are being
monitored).

Description: Displays a description of the selected measurement.

Merging Graphs
LoadRunner lets you merge the results of two graphs from the same scenario
into a single graph. The merging allows you to compare several different
measurements at once. For example, you can make a merged graph to
display the Web Throughput and Hits per Second, as a function of the
elapsed time. Note that in order to merge graphs, the x-axis of both must be
the same measurement.

When you overlay the contents of two graphs that share a common x-axis,
the left y-axis on the merged graph shows the current graph's values. The
right y-axis shows the values of the graph that was merged.

392
 Chapter 21 • Configuring Online Graphs

To overlay two graphs:

1 Right-click one of the graphs you want to overlay, and select Overlay
Graphs. The Overlay Graphs dialog box opens.

2 Select a graph with which you want to overlay the current graph. The drop-
down list shows only the active graphs that have a common x-axis with the
current graph.
3 Enter a title for the overlaid graph.
4 Click OK. The merged graph appears in the graph view area.

Exporting Online Monitor Graphs

LoadRunner allows you to export online graphs to HTML for viewing at a
later stage. When you export to HTML, the legend is also displayed with the
graph.

To export online graphs to HTML:

1 To export all graphs in the Online Monitor view, choose Monitors > Export
Online Graphs to HTML. The Select Filename and Path dialog box opens.
2 Specify a filename and path and click Save.

393
Part VI • Monitoring a Scenario

Viewing Data Offline

After monitoring resources during a scenario run, you can view a graph of
the data that was gathered using the LoadRunner Analysis. When you run
the Analysis utility, it processes the data and generates a graph for each
measurement that was monitored.

To view a graph, choose Graph > Add Graph in the Analysis window. For
more information about working with the LoadRunner Analysis at the
conclusion of the scenario, refer to the LoadRunner Analysis User’s Guide.

Available Graphs Tree

The Available Graphs Tree displays the LoadRunner graphs.

To open a graph, click the graph in the graph tree, and drag it into the right
pane of the Run view.

To select the measurements that you want to monitor on the graph, see the
monitor configuration instructions for the specified monitor in the
LoadRunner Monitor Reference.

394
22
Remote Performance Monitoring

Remote performance monitoring enables multiple viewers to monitor a

LoadRunner scenario from a remote location using a Web browser. This
allows a licensed number of participants to simultaneously view the online
test results without requiring access to the Controller machine. Each remote
viewer is able to select specific monitoring graphs from the same active load
test, and customize the graph settings to suit individual needs.

This chapter describes:

➤ About Remote Performance Monitoring

➤ Installing the Remote Performance Monitor Server
➤ Configuring the Remote Performance Monitor User Settings
➤ Connecting to the LoadRunner Remote Performance Monitor
➤ Monitoring Load Test Data
➤ Viewing Online Graphs
➤ Customizing Online Graph Settings

395
Part VI • Monitoring a Scenario

About Remote Performance Monitoring

During a load test run, the Remote Performance Monitor enables you to
view graphs that display information about the load the Vusers generate on
your server. The users view the load test data on a Web browser that
connects to the Web server.

The Remote Performance Monitor Server contains a Web site implemented

with ASP pages, and a file server that contains the load test graphs. It
interacts with the Controller online components and handles the number
of simultaneous users that can view the load test, according to the
appropriate license.

The Controller runs an application that communicates with the server

machine to produce online graphs on demand.

For more information about the available graphs and monitor

measurements, see Chapter 20, “Online Monitoring.”

Note: The Remote Performance Monitor is not supported if you access the
Controller through Terminal Services. Ensure that the Controller is started
locally.

396
 Chapter 22 • Remote Performance Monitoring

Installing the Remote Performance Monitor Server

To monitor the performance of your servers from a remote location, you
need to install the Remote Performance Monitor Server from the
LoadRunner installation CD.

For instructions on installing the Remote Performance Monitor Server, refer

to the LoadRunner Installation Guide.

Installation Requirements
The Remote Performance Monitor Server configures an IIS Web server for
the Remote Performance Monitor. This requires a machine with the
following components installed:

IIS Server 5.0

Operating system Windows 2000 Server; Windows 2000

Advanced Server

Client Browser Internet Explorer 5.0 and later;

Netscape 6.2 and later

The IIS Web server communicates with the Controller and the Remote
Performance Monitor to manage the user’s requests to produce online
graphs and graph legends.

397
Part VI • Monitoring a Scenario

Configuring the Remote Performance Monitor User

Settings
The Remote Performance Monitor User Configuration tool enables you to
change the default or used-defined user name and password that were used
during the Remote Performance Monitor installation process on the Web
server. This tool is also used to update the Remote Performance Monitor user
settings on the Controller machine. Ensure that the user name and
password are the same on both machines, since LoadRunner uses this
information for authentication between the Web Server and the Controller
machine.

User Configuration
You must use the Remote Performance Monitor User Configuration tool on
both the Controller and the Web server machines to configure the user
settings.

To change the user settings on the Controller side:

1 Choose Start > Programs > Mercury LoadRunner > Tools >
RPM User Configuration to open the Remote Performance Monitor User
Configuration tool on the Controller machine.

2 In the Remote Performance Monitor User Configuration dialog box, enter

your user name and password, and confirm the password.

398
 Chapter 22 • Remote Performance Monitoring

3 Click Replace User. The configuration program prompts you to restart the
machine. You can delay restarting to a later time.

Note: The changes are performed immediately after your click Replace User.
However, the system will only work properly after rebooting the machine.

To change the user settings on the Web server:

1 Choose Start > Programs > RPM Server to open the Remote Performance
Monitor User Configuration tool on the Web server.
2 In the Remote Performance Monitor User Configuration dialog box, enter
the same user name and password that you entered on the Controller
machine. Confirm the password.
3 Click Replace User. The configuration program prompts you to restart the
machine.

Note: The changes are performed immediately after your click Replace User.
However, the system will only work properly after rebooting the machine.

The Remote Performance Monitor user name and password are

automatically updated on the IIS Web server.

399
Part VI • Monitoring a Scenario

Using the Password Encoder

The Password Encoder tool lets you enter regular text and convert it to an
encoded string. This is used primarily for password fields.

Choose Start > Programs > Mercury LoadRunner > Tools >
Password Encoder to open the Password Encoder tool.

Password: Enter the password you want to encode, and then click Generate.

Encoded string: Displays the encoded password string.

Generate: Generates an encoded string after a password is entered.

Copy: Copies the encoded password string to the clipboard.

400
 Chapter 22 • Remote Performance Monitoring

Connecting to the LoadRunner Remote Performance

Monitor
To connect to the LoadRunner Remote Performance Monitor, type the
following path in your Web browser:
http://[name of IIS Web server machine]/remoteview

The LoadRunner Remote Performance Monitor log on page opens.

To log on to the LoadRunner Remote Performance Monitor:

1 In the UserID box, type Admin.
2 In the Password box, type Admin.
3 In the Controller Machine box, type the name or IP address of the
Controller machine you want to access.

401
Part VI • Monitoring a Scenario

4 Click Login. The LoadRunner Remote Performance Monitor page opens.

By default, the left graph is selected, and its measurements are displayed in
the measurements legend.

Note: If there is no browser activity for 20 minutes, the Remote Performance

monitoring session times out. You need to log in again to continue your
session.

To log out of the LoadRunner Remote Performance Monitor:

Click the Log Out button at the top of the page.

402
 Chapter 22 • Remote Performance Monitoring

Monitoring Load Test Data

You monitor load test data during the load test run to get a quick overview
of the test’s status and the effects of load on your Web server.

At the top of the Remote Performance Monitor page, you can view the status
of the test that is currently running.

The Remote Performance Monitor page displays the name of the running
test, the length of time the test has been running, and the name of the
Controller machine.

Viewing Online Graphs

The graphs are tiled to enable you to view five graphs simultaneously: two
large graphs and three small graphs. In addition, you can view graph
measurements in the legend.

To view graphs during the load test run:

1 To display a graph in the large graph pane, select a graph from the drop-
down graph list located above the large graph pane. The page reloads with
the selected graph.

403
Part VI • Monitoring a Scenario

Note: Available graphs appear in green in the drop-down graph list. If you
select an unavailable graph (black), an empty pane will appear.

2 To display a graph in the small graph pane, or to change any of the graphs
displayed on the screen, click the Select button located above the small
graphs. The Select Graphs window opens.

3 Choose any of the listed graphs and the corresponding position in which
they should be displayed. The diagram at the top shows the numbered
positions.
4 Click OK to close the Select Graphs window. The selected graphs appear in
the Remote Performance Monitor page.

404
 Chapter 22 • Remote Performance Monitoring

Graph Legend
You can view the measurements of any graph that is displayed in the large
graph window. By default, when the remote viewer opens, the left graph is
selected (denoted by a highlighted gray border), and its measurements are
displayed in the measurements legend.

Note: The measurements of a small graph cannot be displayed in the

legend. Therefore, open the resource you want to measure as a large graph.

To view a graph’s legend:

1 Click in the graph pane to select the graph. The graph is highlighted with a
gray border, and its measurements are displayed in the legend.
To view the measurements of two graphs, select both of the large graphs.
The legend splits vertically, displaying the measurements of both graphs.
2 The legend displays details about the maximum, average, minimum, and
last values for each measurement. To sort the measurements by one of these
values, click the column heading (Max, Avg, Min, or Last). An icon is
displayed beside the column heading, showing you whether the
measurements are sorted in ascending or descending order.
3 To close a graph’s legend, click anywhere in the graphs pane.

405
Part VI • Monitoring a Scenario

Customizing Online Graph Settings

You can modify the following online graph settings while a load test is
running from the Remote Performance Monitor:

➤ graph scale
➤ graph refresh rate
➤ graph configuration measurements
The changes to the default settings apply only to the current run and are not
saved for future runs of the load test.

Scaling Graphs
You can modify the scale of a measurement—the relationship between the
y-axis and the graph’s actual value. The x-axis represents Elapsed Time and
cannot be adjusted. By default, LoadRunner uses the Auto option, which
automatically sets the most suitable measurements for displaying the graph.

To scale the large graphs:

1 In the y-axis value section below the large graphs, select Set to, type a value
in the box, and click Refresh Graphs. The graph is redrawn with the
specified value as the upper limit of the y-axis.
2 To view the graph scaled normally, select Auto and click Refresh Graphs.

406
 Chapter 22 • Remote Performance Monitoring

To scale the small graphs:

1 Click the Scale button located above the small graphs. The Scale Graphs
dialog box opens.

You can change the y-axis measurement of the small graphs in positions
three, four, and five as shown in the Select Graphs window on page 404.
2 To use a different scale, select Set to, and type a value in the box.
3 To view the graph scaled normally, select Auto.
4 Click OK to close the Scale Graphs dialog box. The graph is redrawn with the
specified value as the upper limit of the y-axis.

Note: For more information on graph scale, refer to “Setting the Scale of the
Measurement” on page 388.

407
Part VI • Monitoring a Scenario

Refresh Rate
By default, graphs on the Remote Performance Monitor page are refreshed
every five seconds. You can use the Auto-Refresh option to change the
default refresh rate. If you increase the refresh rate, the graphs are refreshed
less frequently. In a large load test, it is recommended to use a slower refresh
rate for the small graphs. This enables you to avoid problems with CPU
resource usage.

To modify the default refresh rate:

1 Click the Refresh button located above the small graphs. The Refresh Rate
dialog box opens.

By default, the refresh option is enabled to automatically refresh all graphs

at 5 second intervals. To disable the auto-refresh option, select the Do not
refresh check box.
2 Select a frequency for refreshing the large graphs and small graphs.
3 Click OK to modify the auto-refresh rates and return to the LoadRunner
Remote Performance Monitor page.

Note: To refresh the graphs and the legends immediately, click Refresh
Graphs.

408
 Chapter 22 • Remote Performance Monitoring

Configure Graph Measurements

You can customize graphs to show, hide, or highlight selected graph
measurements.

To configure graph measurements:

1 Click the icon at the top of the large graph pane to configure the graph’s
measurements. The Configure Graph Measurements window opens.

2 Select the Show check box to show a measurement on the graph. By default,
all graph measurements are shown on the graph. To remove a measurement
from being displayed on the graph, clear the Show check box. To highlight a
measurement in bold on the graph, select the Bold check box.
Select the Select/Deselect all check box in the Show column to display all
measurements on the graph. Clear the Select/Deselect all check box to
remove all measurements from the graph.

409
Part VI • Monitoring a Scenario

To highlight all measurements in Bold on the graph, check the

Select/Deselect all check box in the Bold column. To remove the bold
highlights, clear the Select/Deselect all check box.
3 Click OK to close the Configure Graph Measurements window. The new
graph configuration settings appear on the refreshed graph.

410
Part VII
Appendixes
412
A
Interpreting LoadRunner Online Graphs

LoadRunner online monitor graphs present important information about

the performance of your scenario. This appendix describes some of the key
online graphs in greater depth, and shows how they can be used to identify
and pinpoint performance bottlenecks as your scenario is running.

Online Monitoring Graphs

Using the online monitor graphs, you can determine whether transactions
transpire within an acceptable amount of time, whether your bandwidth is
sufficient to keep download times to a minimum, and whether your
hardware and operating system can handle peak load.

Question 1: Do all transactions in my scenario transpire within an

acceptable amount of time? Which particular transactions take too long?
Answer: The Transaction Response Time graph shows the amount of time it
takes for each transaction to be completed. Note that in the graph below,
the transaction response time is quick, except for the login transaction. The
initial login did not take much time, but subsequent logins were quite slow.

413
Part VII • Appendixes

This indicates that the database is unable to process more than one login at
a time, which may be due to inefficient database querying.

Question 2: Is bandwidth sufficient to keep download times to a minimum?

Answer: The Throughput graph shows the amount of throughput on the
Web server during each second of the scenario run. Throughput represents
the amount of data received from the server at any given second.

414
 Appendix A • Interpreting LoadRunner Online Graphs

Note that in the above graph, the throughput scales upward as time
progresses and the number of users increases, indicating that the bandwidth
is sufficient. If the graph were to remain relatively flat as the number of
users increased, it would be reasonable to conclude that the bandwidth is
constraining the volume of data requested.

Question 3: Can the hardware and operating system handle peak load?
Answer: The Windows Resources graph displays Windows resource usage in
real time. You use this graph to monitor the resources used during a scenario
and locate a bottleneck on a particular machine.

The % Total Processor Time in the above graph shows the amount of data
processed by the server. File Data Operations/sec shows the rate at which
the server is issuing Read and Write operations to file system devices. Page
Faults/sec counts the number of page faults in the processor, representing
virtual memory and caching algorithm opportunities.

415
Part VII • Appendixes

It is commonly thought that newer and faster servers can resolve slow
download times. However, the above graph demonstrates that only a small
amount of data is processed by the server. The graph indicates that there is
adequate processor capacity, and additional server hardware will not result
in increased performance. There are cases, however, in which increased
performance can be achieved by optimizing the data file system.

416
B
Performing Path Translation

When you run a scenario, LoadRunner gathers run-time data from the
participating Vusers. By default, LoadRunner stores the data in temporary
files on each Vuser machine. After the scenario, the data is collated in the
general results directory.

Alternatively, you can instruct LoadRunner to write the run-time data

directly to a shared network drive. (See Chapter 10, “Configuring a
Scenario.”) This method is not recommended, since it increases network
traffic and necessitates path translation.

Understanding Path Translation

Path Translation is a mechanism used by LoadRunner to convert a remote
path name for the Controller. A typical scenario might have the LoadRunner
Controller running on a Windows-based machine and include multiple
Vusers running on both Windows-based and UNIX load generators. One
remote load generator may map the network drive as F, while another load
generator maps the same drive as H. In a complex scenario such as this, you
need to ensure that all participating machines recognize the same network
drive.

417
Part VII • Appendixes

You instruct LoadRunner to store scripts and run-time data results on a

shared network drive from the Run-Time File Storage tab of the Options
dialog box.

Result and script files stored on a shared network drive require you to
perform path translation.

The Scenario Groups/Scripts pane in the Design view contains a list of all
the Vuser scripts associated with a scenario—and their locations. A script’s
location (path) is always based on the Controller machine’s mapping of that
location. If a Vuser load generator maps to the script’s path using a different
name, path translation is required.

For example, assume that the Controller is running on a Windows-based

machine named pc2, and that a Vuser script is located on a network drive.
The Controller machine maps the network drive as m:\lr_tests. If the
remote Vuser machine (load generator) hosting the Vusers also maps the
path as m:\lr_tests, no translation is necessary. However, if the remote
machine maps the path as another drive or path, for example r:\lr_tests,
you must translate the path to enable the load generator to recognize the
script location.

418
 Appendix B • Performing Path Translation

Similarly, when saving run-time result files to a shared drive that is mapped
differently by the Controller and remote load generator, you must perform
path translation.

Path translation is also effective across platforms—between Windows and

UNIX. You use path translation to translate Windows-based paths (as seen
by the Controller) into paths recognized by the UNIX Vuser load generator.

Adding Entries to the Path Translation Table

To translate a path from one Windows-based computer to another, or
between Windows-based and UNIX machines, you create an entry in the
Path Translation table. This table contains a list of paths translated into
formats that can be recognized by different machines.

Each line of the Path Translation table has the following format:

<controller_host> <controller_path> <remote_path> [<remote_host>]

controller_host: The name or type of the machine that is running the

Controller. For example, if the Controller is running on a Windows-based
computer, you could type win in the host field. Alternatively, you could
enter the name of the machine running the Controller (for example,
LOADPC1).

The value of controller_host can be:

➤ hostname: the name of the machine running the Controller

➤ win: the Controller is running on a Windows-based computer
➤ unix: the Controller is running on a UNIX machine
➤ all: the Controller is running on a Windows-based or a UNIX machine

controller_path: The path of a specific directory—as recognized by the

Controller. For example, if the directory scripts is located on the network
drive r—as mapped by the Controller—type the path r:\scripts in the
controller_path field.

419
Part VII • Appendixes

remote_path: The path of a specific directory—as recognized by the remote

machine. For example, if the directory scripts is located on the network
drive n—as mapped by the remote load generator—type the path n:\scripts
in the remote_path field.

If a Vuser on the remote UNIX load generator recognizes the above path as
/m/tests, you would type this path in the remote_path field.

remote_host: The name or type of the remote load generator. For example,
if all the remote machines are UNIX workstations, you could type unix in the
remote_host field. The options for the remote_host field are the same as the
options for the controller_host field, listed above. The remote_host
parameter is optional.

Editing the Path Translation Table

You maintain the Path Translation table using the LoadRunner Controller.
LoadRunner saves the Path Translation table as an ASCII file, ppath.mnt.
This file, stored in LoadRunner_directory/dat, has a one–line entry for each
network path to translate.

To edit the Path Translation table:

1 Start the LoadRunner Controller.

420
 Appendix B • Performing Path Translation

2 Choose Tools > Options and select the Path Translation Table tab. The Path
Translation Table view opens.

3 Before you enter path translation information, consider using the Universal
Naming Convention method. If your machines are Windows machines, you
can tell the Controller to convert all paths to UNC, and all machines will be
able to recognize the path without requiring path translation. An example
of UNC format is \\machine_a\results.
Select the Convert to UNC check box to tell LoadRunner to ignore the path
translation table and to convert all paths to the Universal Naming
Convention.
4 If your machines are not Windows machines and you require path
translation, type the path information into the table. You can insert
comments by typing the “#” symbol at the start of a line in the table.
5 Click OK to close the table and save the information.

421
Part VII • Appendixes

Path Translation Examples

The following section illustrates sample Path Translation Table entries.

Note that when you translate a Windows-based path to a UNIX path, you
must enter the appropriate slashes—forward slashes for UNIX and back
slashes for Windows-based paths.

The examples below show the use of the Path Translation table for a
Windows-based Controller called Merlin.

In the first example, Vusers are running on a Windows 2000 machine,

Oasis. Merlin maps the network drive as f:, while Oasis maps it as g:\loadtest.

merlin f:\ g:\loadtest\ Oasis

In the second example, Vusers are running on a UNIX machine, Ultra. Ultra
maps the networks drive as /u/tests/load.

merlin f:\ /u/tests/load/ Ultra

In the third example, the mapping of the network drive by the remote load
generator Jaguar, is identical to the Controller’s mapping, so no translation
is required. This line can be excluded from the Path Translation table.

merlin n:\ n:\ Jaguar

In the fourth example, all Windows-based Vuser load generators map the
network drive as m:\loadtest.

merlin l:\mnt\ m:\loadtest\ win

422
C
Working in Expert Mode

Advanced users can fine-tune the LoadRunner configuration settings while

working in Expert Mode. In Expert mode, additional options are displayed
in the Options dialog box and in the Load Generator Information dialog
box. This appendix describes the additional settings that are available in the
Expert mode:

➤ Entering Expert Mode

➤ Options - General Settings
➤ Options - Debug Information Settings
➤ Options - Output Settings
➤ Options - Monitor Settings
➤ Load Generator Information - UNIX Environment Settings
➤ Load Generator Information - Connection Log Settings

Entering Expert Mode

The LoadRunner Controller Expert mode is intended to provide support
personnel with access to system information. When you work in the Expert
mode, the Controller dialog boxes contain additional options for fine
tuning the Controller operation.

To activate the Expert mode, choose Tools > Expert Mode. An active Expert
mode is indicated by a check mark.

To exit the Expert mode, repeat the above process.

423
Part VII • Appendixes

Options - General Settings

The General tab in the Options dialog box allows you to specify global
settings for data table storage and multiple IP address allocation, and
instruct LoadRunner not to collate log files. This tab is displayed only when
you operate the Controller in the Expert mode.

To set the General Expert mode settings:

1 Choose Tools > Options. The Options dialog box appears. Select the General
tab.

2 Select the Multiple IP address mode.

3 Enter the global directory for data tables.
4 If you want LoadRunner to collate only result files and not log files, select
Do not collate log files.
5 Click OK to accept the settings and close the dialog box.

424
 Appendix C • Working in Expert Mode

Understanding the Options - General Tab

The General tab allows you to specify global settings for data table storage,
log file collation, and multiple IP address allocation.

Multiple IP address mode: The mode used to allocate IP addresses when the
multiple IP address option is enabled (Scenario > Enable IP Spoofer). The
Controller can allocate an IP address per process or per thread. Allocation
per thread results in a more varied range of IP addresses in a scenario.

Data tables global directory: The network location for data tables used as a
source for parameter values. This setting is only required for scripts created
with earlier versions of LoadRunner.

Do not collate log files: Instructs LoadRunner to collate only result files, and
not log files.

425
Part VII • Appendixes

Options - Debug Information Settings

The Debug settings in the Options dialog box allow you to determine the
extent of the trace to be performed during scenario execution. The debug
information is written to the Output window. This tab is displayed only
when you operate the Controller in the Expert Mode.

To set the Debug Information settings:

1 Choose Tools > Options. The Options dialog box appears. Select the Debug
Information tab.

2 Select the check boxes for the desired trace flags.

3 To save the temporary run-time files, select Keep temporary files.
4 Click OK to accept the settings and close the dialog box.

426
 Appendix C • Working in Expert Mode

Understanding the Options - Debug Information Tab

Allows you to define the LoadRunner Debug configuration.

Trace flags: For debugging purposes, you can configure the type of trace
performed by LoadRunner during test execution. Select the appropriate
check box(es) to enable the detailed trace. The trace information appears in
the log file located in the specified Agent log directory. The available trace
flags are: General, File Transfer, Incoming Communication, and Outgoing
Communication. Select only the flags relating to your problem. For example,
if you encounter specific problems with the transfer of files, select the File
Transfer flag.

Keep temporary files: The Agent and Controller create temporary files that
collect information such as the parameter file sent to the Vuser, the output
compilation file, and the configuration file. The Agent files are saved in brr
folders in the TMP or TEMP directory of the Agent machine. The Controller
files are saved in lrr folders in the TMP or TEMP directory of the Controller
machine. At the end of the scenario, all these files are automatically deleted.
The Keep temporary files setting instructs the Agent and Controller not to
delete these files if you need them for debugging.

427
Part VII • Appendixes

Options - Output Settings

The Output tab in the Options dialog box allows you to configure how
running Vusers are displayed on the Controller machine.

To set the Output settings:

1 Choose Tools > Options. The Options dialog box appears. Select the Output
tab.

2 In the Max. simultaneously displayed box, specify the maximum number of

Vuser logs to be displayed simultaneously.
3 In the Refresh timeout box, specify the frequency at which LoadRunner
refreshes the Vuser log.
4 To clear the messages in the Output window when you reset a scenario,
select the Delete Output window messages upon Reset check box.
5 Click OK to accept the settings and close the dialog box.

428
 Appendix C • Working in Expert Mode

Understanding the Options - Output Tab

The Output tab enables you to configure the display of running Vusers on
the Controller machine.

Configuration of the ‘Show Vuser’ Operation:

➤ Max. simultaneously displayed: Specifies the maximum number of Vuser

logs that may be displayed simultaneously, as well as the maximum
number of active UNIX, GUI, RTE, or Web Vusers that the Controller
should display by opening up Run-Time Viewers on your machine. The
default number is ten.
➤ Refresh timeout (milliseconds): Defines how often to refresh the Vuser
log. The default is every 1000 milliseconds.
Delete Output window messages upon Reset: Instructs LoadRunner to clear
all messages in the Output window when you reset a scenario.

429
Part VII • Appendixes

Options - Monitor Settings

Expert Mode provides the following additional monitor setting:

Send Summary or Raw Data: Sends a summary of the collected data back to
the Controller, or sends all of the data in raw form. Sending the data in raw
form saves time because the data does not need to be processed. However,
since all of the data is being transferred to the Controller, it may cause more
network traffic. If the transfer speed is significant to you, it is recommended
that you choose Summary.

430
 Appendix C • Working in Expert Mode

Load Generator Information - UNIX Environment Settings

Expert mode provides the following additional UNIX Environment setting:

Local User: UNIX load generators that use the rsh shell establish a
connection as the current NT user (due to security considerations). To
“mislead” rsh and log in as a user other than the current NT login, select the
Local user check box and specify the desired UNIX login name. Since
modifying the local user name is a security breach for rsh, this option
should be used only when you encounter a problem connecting to the
remote machine.

431
Part VII • Appendixes

Load Generator Information - Connection Log Settings

The Connection Log tab in the Load Generator dialog box allows you to
view the standard output and standard errors generated as the Controller
connects to the selected UNIX load generator. You can also change the
command that the Controller sends to the remote bridge in order to
connect to the load generator.

Rsh standard output: Displays rsh standard output as the Controller

connects to the selected UNIX load generator.

Bridge cmd: Enter a new command if you want to change the default bridge
command being sent by the Controller to the remote bridge in order to
connect the UNIX load generator.

Rsh standard errors: Displays rsh standard errors as the Controller connects
to the selected UNIX load generator.

432
 Appendix C • Working in Expert Mode

To set the Connection Log settings:

1 Click the Generators button, or select Scenario > Load Generators. The Load
Generators dialog box opens.
2 Click Connect to change the status of a load generator from Down to Ready.
3 Click the Details button. The Load Generator Information dialog box opens.
Select the Connection Log tab.
4 View the rsh standard output and rsh standard errors, or enter a new
command in the Bridge cmd box to change the default bridge command.

433
Part VII • Appendixes

434
D
Troubleshooting the Controller

LoadRunner enables you to test entire applications. If one of the

components of the application is not configured properly, LoadRunner
scenarios will not run.

This appendix discusses the most common LoadRunner problems:

➤ About Troubleshooting
➤ LoadRunner Communications
➤ Failure to Communicate with a Load Generator
➤ Failure to Connect to the AUT Database
➤ Failure to Access Files
➤ Failed Vusers or Transactions
➤ Increasing the Number of Vusers on a Windows Machine
➤ Troubleshooting Firewalls
➤ Working With the LoadRunner Agent

About Troubleshooting
LoadRunner relies heavily upon communication between machines in a
network. If communication is not established properly, the Controller will
be unable to send commands to remote load generators and the scenario
will fail. By understanding the reason for the failure and determining when
the failure occurred, you can solve most network communication-related
problems.

435
Part VII • Appendixes

To ensure that the problem lies with your scenario and not your Vuser
script, you should verify that your script runs properly on all remote load
generators in stand-alone mode:

➤ Test your GUI Vuser scripts on Windows platforms using WinRunner.

➤ Test your Vuser scripts on UNIX platforms by running them from the
command line.
➤ Test all other types of Vuser scripts on Windows platforms by running them
from VuGen, or by running a single user from the Controller.

Note: When a test runs in VuGen, the full browser is used. This differs from
a test run in the Controller, where only the browser basics are used. There
may be occasions when a test passes its run in VuGen, but fails when it is
run in the Controller. Before running a scenario in the Controller with
multiple Vusers, run a single Vuser to ensure the test is bug free.

For more information on running Vuser scripts in stand-alone mode, refer to

the appropriate guide for creating Vuser scripts.

LoadRunner Communications
Most communication problems can be solved if you understand your
LoadRunner configuration. This knowledge helps you to determine the
source of the problem and perform the necessary actions to correct it.

The following diagram illustrates a sample network running LoadRunner.

There are five servers: The LoadRunner Controller, the Web server, the
application server, the database server, and the file server that stores the
scenario results (note that result files can also be saved on a non-dedicated
server). There are five remote load generators, each running multiple Vusers.

436
 Appendix D • Troubleshooting the Controller

The arrows indicate the type of communication necessary between the

elements of the network. The Vusers communicate with the Controller in
both directions (send/receive), but with the file server in one direction
(send). The Controller must have access to the file server. All Vusers
participating in the scenario must be able to communicate with the Web
server in both directions (send/receive). For a client machine to connect to
the server machine, it must be able to resolve the server machine name.

If any of the connections are broken, the scenario will fail.

Failure to Communicate with a Load Generator

The most common communication error is the failure of the Controller
machine to connect with a remote load generator. Check the following
items:

➤ TCP/IP setup
➤ TCP/IP connectivity
➤ Load generator connections
➤ UNIX shell

437
Part VII • Appendixes

Checking TCP/IP Setup

The first step in checking your configuration is to verify your machine’s
TCP/IP setup. LoadRunner includes a utility called Hostinfo (hostinfo.exe),
located under LoadRunner’s bin directory. This utility provides information
about the current machine—local name and local address. It also insures
that TCP/IP is properly installed on the current machine.

When you invoke Hostinfo, it automatically verifies the TCP stack by:

➤ retrieving and resolving the local machine name

➤ retrieving and resolving the IP address

To resolve the IP address, Hostinfo tries to communicate using two UDP

sockets on the same machine. It verifies that the IP address obtained while
resolving the machine name is the same as the actual IP address of this
machine.

To display the results of a test in the Details box, highlight the test name.

Note that the Edit menu in Hostinfo allows you to copy all machine
information to the clipboard for sending to support personnel.

438
 Appendix D • Troubleshooting the Controller

Checking TCP/IP Connectivity

Make sure that TCP/IP connectivity is functional on the Controller and
Vuser machines. Use a ping utility or type ping <server_name> from the DOS
command line to verify communication with a remote machine. Make sure
that the remote load generator and Controller machines can ping each
other by IP addresses and machine names.

If the ping does not respond, or fails with a timeout, then the machine
name is not recognized. To solve this problem, edit the hosts file located in
the WINNT\system32\drivers\etc directory, and add a line with both the IP
address and the name. For example:

# 102.54.94.97 rhino.acme.com # source server

# 38.25.63.10 x.acme.com # x client host

Load Generator Connections

To verify the load generator connectivity, connect to each one of the remote
load generators from the Controller’s Load Generators dialog box. In the
load generator’s Platform field, select a Windows or UNIX platform. Select
the load generator(s) and click Connect. The status changes to
“Connecting”.

If the Connection fails, the status changes to “Failed” and details are written
to the Details box. Double-click the Details box for more information about
a failure.

If a connection succeeds, the status changes to “Ready”, and the actual

platform name appears in the Platform box (such as WINNT, UNIX, etc.).

439
Part VII • Appendixes

If your scenario uses several domains (for example, Vusers on a different

domain than the Controller), the Controller may have trouble
communicating with the load generators. This occurs because the Controller
uses the short load generator name—not including the domain—by default.
To solve this, you must tell the Controller to determine the full load
generator names, including the domains.

Modify the miccomm.ini file in the Controller machine’s Windows directory

as follows:

[tcpnet]
LocalHostNameType= 1

The possible values for LocalHostNameType are:

0 - Attempt to use the full machine name.

1 - Use the short machine name. This is the default.

Note: In certain environments such as WINS, load generators are unable to

resolve machine names.

Connecting to a Controller with Multiple IP Addresses

If the load generator machine does not recognize the Controller machine by
its short name or full name, and the Controller machine has more than one
IP address, you can define an alias name for the Controller machine in the
load generator’s hosts file, located in the WINNT\system32\drivers\etc
directory. The alias name should point to the IP address you want the load
generator to recognize. For example: 255.0.0.1 delta.

440
 Appendix D • Troubleshooting the Controller

UNIX Shell
For UNIX Vusers, make sure that the Windows Controller can execute a
remote shell command. Type the following at the DOS command prompt:
rsh -l <UNIX user login name> <load generator name> <command>. If you get a
message indicating that permission is denied, make sure the .rhosts file in
your UNIX home directory contains Controller machine permission for the
user login name. In some cases, a “+” character must be added at the end of
the .rhosts file. For example, if you log on to the Controller as bill and
connect to the UNIX load generator as mike, you must ensure that mike
allows bill to log on using his name. This can be done by adding the line "+
bill" at the beginning of mike’s .rhosts file.

For more information on setting user login names, see “Configuring Load
Generator Settings” on page 78.

To use UNIX without RSH:

1 On the UNIX Load Generator machine, run the agent daemon by running
the following command from <LoadRunner directory>/bin:

m_daemon_setup -install

This runs a daemon called m_agent_daemon, and if successful you will

receive a message: m_agent_daemon installed successfully.
The agent will now keep running, even if the user is logged off. It will only
stop running using the command explained in step 3 below, or by rebooting
the machine.
➤ If you receive the message ERROR: File m_agent_daemon doesn’t exist,
this means that you are not in the same directory as the file (meaning
not in <LR_root>/bin directory, or the file really doesn't exist, which
indicates a problem with the installation).
➤ If a daemon of this name is already being run by the same user, you will
receive the following warning:
WARNING: Could not install m_agent_daemon, reason - user <user_name>
is already running m_agent_daemon on this machine.
➤ If an error occurred, you will receive the following error message:
ERROR: Could not install m_agent_daemon. Check log file
m_agent_daemon[xxx].log in your temp directory.

441
Part VII • Appendixes

➤ If you look at the log file m_agent_daemon[xxx].log in the temp

directory, you will see the following errors, even if the installation
succeeded:

These messages appear because the LoadRunner agent always tries to open
port number 443 (because any agent can be a MI Listener, and the MI
Listener always listens to this port), and in UNIX machines, this port cannot
be opened by any user except for the root user. However, this will not
interfere with using this agent for the Load Generator machine.
2 In the Controller, in the Generators > Load Generator Information > UNIX
Environment tab, select the Don’t use RSH option. Then connect as usual.
3 To stop the agent daemon, run the following command the <LR_root>/bin
directory: m_daemon_setup -remove
This stops the m_agent_daemon, and if successful, you will receive a
message: m_agent_daemon removed successfully.
➤ If no daemon of this name is being run by this user, you will receive the
following warning:
WARNING: Could not remove m_agent_daemon, reason - user
<user_name> is not running m_agent_daemon on this machine.
➤ If an error occurred, you will receive the following error message:
ERROR: Could not remove m_agent_daemon. Check log file
m_agent_daemon[xxx].log in your temp directory.

442
 Appendix D • Troubleshooting the Controller

Failure to Connect to the AUT Database

If you are running a database application, you must ensure that all remote
clients can connect with the database server. If network or configuration
errors occur when the client accesses the server, you must correct them
before running a scenario. To ensure that your client application can
connect with the database server, perform the following tests:

➤ Ping
➤ SQL utilities

Ping: Ensure that the client can communicate with the database server using
TCP/IP. Use a ping utility or type ping <server_name> from the DOS
command line.
SQL Utilities: Use a simple utility such as ISQL or SQLPLUS to log on to the
database server and perform several basic operations.

Failure to Access Files

A LoadRunner scenario will fail if the result path or Vuser script is
inaccessible to one or more of the participating machines. Check the
following items:

➤ Path Translation
➤ Vuser Script
➤ Result Path

Path Translation: A script’s location (path) is always based on the Controller

machine’s mapping of that location. If a Vuser load generator maps to the
script’s path using a different name, path translation is required. Path
translation translates the Controller’s mapping of a given location to the
Vuser load generator’s mapping. For example, if one machine maps the
script directory as g:\test, while another maps it as h:\test, the paths should
be translated.

443
Part VII • Appendixes

Path translation is also effective across platforms—between Windows and

UNIX. You use path translation to translate the Windows Controller paths
into paths recognized by UNIX.

Note: Path translation is required only if you chose to save all scripts and
results to a shared network drive. In the default setup, LoadRunner saves
files locally and collates them to the Controller machine; no path
translation is required.

Suppose that your script is in the /usr/jon/lr_test1 directory and runs on the
UNIX machine, sunny. To translate it from the Windows Controller
machine, pc1, where your UNIX directory is mapped as r, enter the
following line in the path translation table:

pc1 r:\ /usr/jon sunny

To translate the f:\qa Controller directory to all load generator machines

running /m/qa/lr_test2/lr_test2.usr on a UNIX platform, type:

win f:\qa /m/qa UNIX

If the paths are not translated properly, the scenario will fail. For more
information about path translation, see Appendix B, “Performing Path
Translation.”

Vuser Script: Make sure that the Vuser script is accessible to all load
generators participating in the scenario through path translation and
permissions. View or run the Vuser script in stand-alone mode on each of
the participating load generators.

Result Path: Make sure that the result path is accessible to all load generators
participating in the scenario through path translation and permissions.
Check the permissions of the result directory files and modify them if
necessary.

444
 Appendix D • Troubleshooting the Controller

Failed Vusers or Transactions

LoadRunner Vusers or transactions may fail for a variety of reasons relating
to the network, database, or actual script. You can find information about
scenario runs from the following sources:

➤ Run View
➤ Output Window
➤ Output File (excluding GUI Vusers)
➤ Analysis Reports and Graphs

Run View
The Run view is part of the LoadRunner Controller. The Scenario Groups
pane in the upper-left corner of the view indicates the status of the Vuser
groups during and after the scenario run. During the scenario run, the
columns will show a “Pending”, “Initializing”, “Ready”, “Running”, or
“Rendezvous” status. You can also view the status of each individual Vuser
in the Vusers dialog box. If a Vuser fails and does not complete the script
execution, LoadRunner displays an error status. If a Vuser completes the
script execution, LoadRunner indicates the transaction status of a completed
script run using the “Done.Failed” or “Done.Passed” status.

For more information about the Vuser states, see Chapter 13, “Running a
Scenario.”

445
Part VII • Appendixes

Output Window
View the Output window from the Controller. The output window contains
useful information for debugging a scenario. The output window lists five
types of messages: errors, warnings, notifications, debug, and batch. An
error message usually results in a failed script. A warning message indicates
that the Vuser encountered a problem, but test execution continued. A
notification provides useful information such as recorded think time values
and other run-time information. A debug message is sent if you enable the
debugging feature in Tools > Options > Debug Information (Expert Mode).
Batch messages are sent instead of message boxes appearing in the
Controller, if you are using automation.

For more information about the Output window, see Chapter 14, “Viewing
Vusers During Execution.”

446
 Appendix D • Troubleshooting the Controller

Output File
You can view information about script execution in an output file located in
the Vuser result directory. The output file, output.txt, contains:

➤ a list of the primary functions called during the scenario

➤ error messages from the database server
➤ transactions and rendezvous information

The extent of the information sent to the output file depends on the output
file settings. In the VuGen’s run-time settings, you specify a Brief or
Extended log. For the Extended log, you can specify a full trace, returned
data, or current parameter value. An extended log is helpful for debugging a
script, but if you are not debugging, Extended log is not recommended as it
introduces extra overhead. For more information about configuring run-
time settings, refer to the Mercury Virtual User Generator User’s Guide.

447
Part VII • Appendixes

Analysis Reports and Graphs

You can generate graphs and reports to view information about the scenario
run. For example, the Scenario Summary report displays a table containing
the scenario’s run-time data and provides links to the following graphs:
Running Vusers, Throughput (Web), Hits per Second (Web), HTTP Responses
per Second, Transaction Summary, and Average Transaction Response Time.

For more information on the available graphs and reports, refer to the
LoadRunner Analysis User’s Guide.

448
 Appendix D • Troubleshooting the Controller

Increasing the Number of Vusers on a Windows Machine

Under the normal settings of a Windows machine, you are limited to several
hundred Vusers. This limitation is related to the operating system and not to
the CPU or memory.

To work around the limitation of the Windows operating system, modify

the Windows kernel as follows:

1 Save a copy of the registry file in case you have trouble with these
modifications.
2 Run Regedit.
3 Go to following key in KEY_LOCAL_MACHINE:
System\CurrentControlSet\Control\Session Manager\SubSystems

4 Select the Windows key. The default Windows key for NT 4.0 looks like this:

%SystemRoot%\system32\csrss.exe ObjectDirectory=\Windows
SharedSection=1024,3072
Windows=On SubSystemType=Windows ServerDll=basesrv,1
ServerDll=winsrv:UserServerDllInitialization,3
ServerDll=winsrv:ConServerDllInitialization,2
ProfileControl=Off MaxRequestThreads=16

The SharedSection=1024,3072 key has the format xxxx,yyyy where:

xxxx defines the maximum size of the system-wide heap (in KB)
yyyy defines the size of the per desktop heap.

5 Increase the SharedSection parameter by changing the yyyy settings from

3072 to 8192 (which is 8 MB).

This setup successfully allowed 1250 Oracle Vusers to run on a Windows

machine using 2 Pentium PRO 200 MHz with 1 GB RAM.

Each Vuser in this setup used approximately 2MB memory. Other Vusers
may require more memory.

449
Part VII • Appendixes

LoadRunner was able to load over 2500 Vusers when the Windows terminal
server was run as the Operating System and the above registry setting was
changed.

The above registry changes enable you to run more threads, allowing you to
run more Vusers on the machine. This implies that you are not bound by
the Windows operating system; you are only bound by hardware and
internal scalability limitations.

Troubleshooting Firewalls
There are three log files that provide additional information about activity
over the firewall.

The LoadRunner agent log file contains information about communication

activity between the LoadRunner agent and the MI Listener.

➤ To open the file on Windows machines, right-click the LoadRunner agent

icon in the system tray of the LoadRunner agent machine, and select View
Log. Alternatively, open the latest
<temp_directory>\LoadRunner_agent_startup<unique identifier>.log file (if
the LoadRunner agent is a process), or
<temp_directory>\LoadRunner_agent_service<unique identifier>.log file (if
the LoadRunner agent is a service) in a text editor.
➤ To open the file on UNIX machines, open the
<temp_directory>/m_agent_daemon<unique identifier>.log file in a text
editor.

450
 Appendix D • Troubleshooting the Controller

The MI Listener log file contains information about MI Listener

communication with the LoadRunner agent and the Controller.

To open the file, right-click the MI Listener Agent icon in the system tray of
the MI Listener machine, and select View Log. Alternatively, open the latest
<temp_directory>\LoadRunner_agent_startup<unique identifier>.log file (if
the LoadRunner agent is a process), or
<temp_directory>\LoadRunner_agent_service<unique identifier>.log file (if
the LoadRunner agent is a service) in a text editor.

The Controller log file contains information about communication activity

between the Controller and the MI Listener.

To open the file on Windows machines, open the

<temp_directory>\drv_log.txt file in a text editor.

Verifying Connection Between LoadRunner Agent and MI

Listener
If there is a proper connection between the LoadRunner agent and the MI
Listener:

➤ On Windows platforms, the agent icon’s light in the system tray will turn
from red to green.
➤ On UNIX platforms, a file called
<Local_machine_key>_connected_to_MI_Listener will be created in the
temporary directory of the LoadRunner agent machine. Local_machine_key
is the value set in the Agent Configuration, as described in Chapter 16,
“Running Vusers Over a Firewall.” The file will be removed when the
LoadRunner agent disconnects from the MI Listener.
➤ On both UNIX and Windows platforms, the following message will appear
in the LoadRunner agent log file: Notify Connected to MI Listener.

451
Part VII • Appendixes

Note: The LoadRunner agent tries to connect to the MI Listener machine

every Timeout seconds (as defined in the Agent Configuration). After a
successful connection, if no Controller has connected through this MI
Listener to the agent after another Timeout, LoadRunner will disconnect
from the Controller.
On a Windows machine, the agent icon’s light in the system tray will turn
from green to red. On UNIX machines, the file
<Local_machine_key>_connected_to_MI_Listener will be removed from the
temporary directory in the LoadRunner agent machine.
In both Windows and UNIX, the message Disconnected from MI Listener will
appear in the LoadRunner agent log file.

UNIX Connection Errors

After installing the m_agent_daemon as described in Chapter 16, “Running
Vusers Over a Firewall,” you should receive a message: m_agent_daemon
installed successfully.

Agent Daemon Errors

ERROR: File m_agent_daemon doesn’t exist.

This error means that you are not in the same directory as the file (meaning
not in <LR_root>/bin directory, or the file really doesn't exist, which
indicates a problem with the installation).

WARNING: Could not install m_agent_daemon, reason - user <user_name> is

already running m_agent_daemon on this machine.

This warning message occurs when a daemon of this name is already being
run by the same user.

ERROR: Could not install m_agent_daemon. Check log file

m_agent_daemon[xxx].log in your temp directory.

This error indicates that some error has occurred when loading the daemon.
You should check the log file and consult the following troubleshooting
tips.

452
 Appendix D • Troubleshooting the Controller

LoadRunner Agent Log File Errors

Error - 10344 : Communication Error: -59961 : Failed to bind a socket while

calling bind function.

Error -10344 : Communication Error: -59927 : Failed to create a TCP server for
the HTTP channel’s server.

Warning -29974 : Failed to create "router" server.

These messages appear because the LoadRunner agent always tries to open
port number 443 (because any agent can be a MI Listener, and the MI
Listener always listens to this port), and in UNIX machines, this port cannot
be opened by any user except for the root user. However, this will not
interfere with using this agent for the Load Generator machine.

Error -10343 : Communication error : -59981 : Failed to connect to remote host -

<MI_Listener_name>.

The MI Listener is not being run at the time of the connection attempt on
the machine set in MI Listener Name in the Agent Configuration.

Error -10343 : Communication error: -59928 : Unresolved server name.

The name passed in MI Listener Name in the Agent Configuration is not a

name, full name, or IP address of a valid machine, or no value was set.

Error -10343 : Communication error: -59928 : Unresolved server name.

The name passed in Proxy Name in the Agent Configuration is not a name,
full name, or IP address of a valid machine.

Error -10343 : Communication error: -59945 : Client failed to connect to a

PROXY Server with the following settings:
(-server_port=<proxy_server_port>)(-server_fd_primary=2)(-server_type=8)(-
allowed_msg_size=0)(-allowed_msgs_num=0)(-proxy_configuration_on)(-
tcp_tunnel_configuration_on).

The Proxy Name field is empty.

453
Part VII • Appendixes

Error -10343 : Communication error: -59982 : Failed to connect to remote host -

<MI_Listener_Name>. The remote address is not a valid address.

Error -10343 : Communication error: -59945 : Client failed to connect to a

PROXY Server with the following settings:
(-server_name=<proxy_server_name>)(-server_port=<proxy_server_port>)(-
server_fd_primary=2)(-server_type=8)(-allowed_msg_size=0)(-
allowed_msgs_num=0)(-proxy_configuration_on)(-tcp_tunnel_configuration_on).

The Proxy Port set in Agent Configuration has been set to the wrong port
number.

Error -10343 : Communication error: -59913 : NTLM authentication to proxy

server error - connection to proxy refused.

The proxy server is configured for NTLM authentication, and the Proxy User
Name, Proxy Password and/or Proxy Domain are not set correctly in the
Agent Configuration.

Error -10343 : Communication error: - 59880 : Basic authentication to proxy

server error - connection to proxy refused.

The proxy server is configured in for Basic authentication and the Proxy
User Name and/or Proxy Password are not set correctly in the Agent
Configuration.

Error -10343 : Communication error: -59907 : SSL connect error : verify host failed
: wrong DNS test.

This error occurs when you have set the Check Server Certificates setting to
True, and have not issued a new certificate to the MI Listener machine (see
Appendix G, “Working with Digital Certificates” for more details).

Error -10343 : Communication error: -59907 : SSL connect error : certificate verify
failed.

Error -10343 : Communication error: -59907 : SSL connect error : sslv3 alert
handshake failure.

Error -10343 : Communication error: -59907 : SSL connect error : sslv3 alert bad
certificate.

454
 Appendix D • Troubleshooting the Controller

Error -10343 : Communication error: -59907 : SSL connect error : sslv3 alert
certificate expired.

These errors occur when you set the Check Server Certificates setting to
True. See Appendix G, “Working with Digital Certificates” to learn how to
issue a valid certificate.

Error -10343 : Communication error: -59910 : SSL initialization error : Certificate

not found.

Error -10343 : Communication error: -59910 : SSL initialization error : No such

file or directory.

Error -10343 : Communication error: -59910 : SSL initialization error : system lib.

These errors occur when the Client Certificate owner setting in the Agent
Configuration is set to True, but no certificate was installed in the
LoadRunner agent machine (see Appendix G, “Working with Digital
Certificates” for more details).

MI Listener Log File Errors

Error - 10344 : Communication Error: -59961 : Failed to bind a socket while

calling bind function.

Error -10344 : Communication Error: -59927 : Failed to create a TCP server for
the HTTP channel’s server.

Warning -29974 : Failed to create "router" server.

This error means that another process on the MI Listener machine is

occupying port 443 (for instance, the IIS service).

Error -10343 : Communication error: -59904 : SSL accept error : sslv3 alert
certificate expired.

These errors occur when you have set the Check Server Certificates setting to
True, and the MI Listener's certificate is expired.

Error -10343 : Communication error: -59904 : SSL accept error : sslv3 alert bad
certificate.

455
Part VII • Appendixes

These errors occur when you have set the Check Server Certificates setting to
True, and either:

➤ the MI Listener’s certificate does not have a signature that is included in

the LoadRunner agent’s CA List
➤ the MI Listener’s certificate has a future verification date
See Appendix G, “Working with Digital Certificates” to learn how to issue a
valid certificate and how to add a Certification Authority to a CA list, or
how to create a certificate with a new validation date.

Error -10343 : Communication error: -59904 : SSL accept error : peer did not
return a certificate.

These errors indicate that the Check Client Certificates setting in the MI
Listener Configuration is set to True, but the Client Certificate owner setting
in the Agent Configuration is set to False.

Error -10343 : Communication error: -59904 : SSL accept error : no certificate

returned.

These errors indicate that the Check Client Certificates setting in the MI
Listener Configuration is set to True, and the Client Certificate owner
setting in the Agent Configuration is set to True, but either:

➤ the LoadRunner agent’s certificate does not have a signature that is

included in the MI Listener's CA List
➤ the LoadRunner agent’s certificate has a future verification date.
See Appendix G, “Working with Digital Certificates” to learn how to issue a
valid certificate and how to add a Certification Authority to a CA list, or
how to create a certificate with a new validation date

Error -10343 : Communication error: -59904 : SSL accept error : no certificate

returned.

These errors indicate that the Check Client Certificates setting in the MI
Listener Configuration is set to True, and the Client Certificate Owner
setting in the Agent Configuration is set to True, but the LoadRunner agent’s
certificate has expired.

456
 Appendix D • Troubleshooting the Controller

General Connection Errors

These errors can occur when using all configurations.

If no errors appear both in the LoadRunner agent log and the MI Listener
log, but the agent does not connect to the MI Listener, make sure that the
FireWallServiceActive attribute in the Firewall section in the
<LR_Installation>\dat\br_lnch_server.cfg file on the LoadRunner agent
machine, is set to 1.

Verifying Connection Between the Controller and Agent through the

MI Listener
When there is a successful connection between the LoadRunner agent and
the MI Listener, and the Controller machine fails to connect, you should
check the following:

➤ The Name field in the Load Generators dialog in the Controller should
match the name set in the Local Machine Key in the Agent Configuration.
➤ The MI Listener field in the Load Generators > Details > Firewall tab of the
above host matches the name set in the MI Listener Name in the Agent
Configuration.
➤ In the Tools menu of the Controller, in the Options > Timeout tab, the Load
Generator Connect timeout might need to be increased because the
Firewalls may slow down the communication.
➤ Make sure that the Controller machine recognizes the LoadRunner agent
machine (e.g., by using the ping utility). If this fails, there is a configuration
problem in the system not related to LoadRunner, and it must be solved
before the connection can be made.
➤ Make sure that the Controller has successfully connected to the MI Listener
by checking port 50500 on the MI Listener machine (you can use the netstat
utility on the MI Listener machine).

457
Part VII • Appendixes

Working With the LoadRunner Agent

The LoadRunner Agent runs on the load generator machines and enables
communication between the Controller, load generators, and MI Listeners
(in firewall configurations). The agent receives instructions from the
Controller to initialize, run, pause, and stop Vusers. At the same time, the
agent also relays data on the status of the Vusers back to the Controller.

To check the agent’s current configuration, move your mouse over the
Agent’s icon in the Task bar area, and read the description. The description
will say either “LoadRunner Agent Process” or “LoadRunner Agent Service.”

Changing the LoadRunner Agent Password

To change the password of the LoadRunner Agent service:
1 Select LoadRunner Agent Service from Start > Settings > Control Panel >
Services.
2 Click Startup to open the Service dialog.
3 Enter a new user name and password, then click OK.
4 Stop and restart the service.

Running the LoadRunner Agent as a Process

In some cases, such as SAPGUI replay, running GUI Vusers on remote
machines, or Terminal sessions, the LoadRunner Agent must run as a
process.

To change the LoadRunner Agent from a service to a process:

1 To uninstall the service, run
<LR_dir>\launch_service\bin\magentservice.exe -remove
2 To install the process, make a shortcut of
<LR_dir>\launch_service\bin\magentproc.exe and place it in your system
startup folder.
3 To run the process, run magentproc.exe from the startup folder or from
<LR_dir>\launch_service\bin, or restart your machine.

458
 Appendix D • Troubleshooting the Controller

Running the LoadRunner Agent as a Service

In most cases, the LoadRunner Agent runs as a service.

To change the LoadRunner Agent from a process to a service:

1 Stop the agent process by right-clicking its icon in the system tray and
selecting Close.
2 To uninstall the process, delete its shortcut from the system startup folder.
3 To install the service, run <LR_dir>\launch_service\bin\magentservice.exe -
install <user_domain>\<user_name> <password>
This also runs the agent service.
4 To run the service later, after stopping it, start it from the Services dialog
box.

Mapping Network Drives when Running the Agent as a Service

For all Windows platforms, when the user is logged out, the service cannot
resolve the mapping of network drives. For Windows XP, the service also
cannot resolve the mapping of network drives when the user is logged on.

In cases when the service cannot work with mapped network drives, use the
full path to the directory, for example, <\\<machine-name>\<directory>\> .

459
Part VII • Appendixes

460
E
Configuring Multiple IP Addresses

When you run a scenario, the Vusers on each load generator machine use
the machine’s IP address. You can define multiple IP addresses on a load
generator machine to emulate a real-life situation in which users sit on
different machines.

This appendix describes:

➤ About Multiple IP Addresses

➤ Adding IP Addresses to a Load Generator
➤ Using the IP Wizard
➤ Configuring Multiple IP Addresses on UNIX
➤ Updating the Routing Table
➤ Enabling Multiple IP Addressing from the Controller

About Multiple IP Addresses

Application servers and network devices use IP addresses to identify clients.
The application server often caches information about clients coming from
the same machine. Network routers try to cache source and destination
information to optimize throughput. If many users have the same IP
address, both the server and the routers try to optimize. Since Vusers on the
same load generator machine have the same IP address, server and router
optimizations do not reflect real-life situations.

461
Part VII • Appendixes

LoadRunner’s multiple IP address feature enables Vusers running on a single

machine to be identified by many IP addresses. The server and router
recognize the Vusers as coming from different machines and as a result, the
testing environment is more realistic.

Note: The maximum number of IP addresses that can be spoofed per

network card for Windows NT SP3 is 35 IPs; Solaris (version 2.5.1) up to 255
IPs; Solaris (version 2.6 and higher) up to 8192 IPs.

Applicable Protocols
The multiple IP address feature is applicable to the following protocols:

➤ Client/Server: DNS, Windows Sockets

➤ Custom: Javascript Vuser, VB Vuser, VB Script Vuser
➤ E-business: FTP, Palm, SOAP, Web (HTTP/HTML), Web Services,
WinSock\Web Dual Protocol
➤ ERP/CRM: Oracle NCA, Oracle Web Applications 11i, PeopleSoft Enterprise,
SAP-Web, Siebel-Web
➤ Legacy: RTE
➤ Mailing Services: Internet Messaging (IMAP), POP3, SMTP
➤ Streaming Data: Real
➤ Wireless: i-Mode, VoiceXML, WAP
This feature can be implemented on Windows and UNIX platforms.

462
 Appendix E • Configuring Multiple IP Addresses

Adding IP Addresses to a Load Generator

LoadRunner includes an IP Wizard program that you run on each Windows
NT or Windows 2000 load generator machine to create multiple IP
addresses. You add new IP addresses to a machine once and use the
addresses for all scenarios. For information about adding IP addresses on
UNIX machines, see “Configuring Multiple IP Addresses on UNIX” on
page 468.

The following procedure summarizes how to add new IP addresses to a

load generator:
1 Run the IP Wizard on the load generator machine to add a specified number
of IP addresses. Manually configure the new IP addresses for UNIX load
generator machines.
2 Restart the machine.
3 Update the server’s routing table with the new addresses, if necessary.
4 Enable this feature from the Controller. Refer to “Enabling Multiple IP
Addressing from the Controller” on page 471.

463
Part VII • Appendixes

Using the IP Wizard

The IP Wizard resides on each load generator machine. You run this process
once to create and save new IP addresses on Windows machines. The new
addresses can be a range of addresses defined by the Internet Assignment
Numbers Authority. They are for internal use only, and cannot connect to
the Internet. This range of addresses is the default used by the IP Wizard.

To add new IP addresses to a load generator machine:

1 Invoke the IP Wizard from the LoadRunner program group.

2 If you have an existing file with IP address settings, select Load previous
settings from file and choose the file.
3 If you are defining new settings, select Create new settings.
4 Click Next to proceed to the next step. If you have more than one network
card, choose the card to use for IP addresses and click Next.

464
 Appendix E • Configuring Multiple IP Addresses

The optional Web server IP address step enables the IP Wizard to check the
server’s routing table to see if it requires updating after the new IP addresses
are added to the load generator.

5 To check the server’s routing table directly after adding the addresses, enter
the server IP address. See “Updating the Routing Table” on page 470 for
more information.
6 Click Next to see a list of the machine’s IP address(es). Click Add to define
the range of addresses.

465
Part VII • Appendixes

IP addresses include two components, a netid and hostid. The submask

determines where the netid portion of the address stops and where the
hostid begins.
7 Select a class that represents the correct submask for the machine’s IP
addresses.
8 Specify the number of addresses to create. Select Verify that new IP
addresses are not already in use to instruct the IP Wizard to check the new
addresses. The IP Wizard will only add the addresses not in use.
9 Click OK to proceed.
After the IP Wizard creates the new addresses, the summary dialog box lists
all of the IP addresses.

466
 Appendix E • Configuring Multiple IP Addresses

10 Click Finish to exit the IP Wizard. The IP Wizard Summary dialog box is
displayed.

11 Note the address of the .bat file, and see “Updating the Routing Table” on
page 470 for information about using the batch file to update the routing
table, if necessary.
12 After you update the routing table, check Reboot now to update routing
tables to initialize the NT device drivers with the new addresses.
13 Click OK.

467
Part VII • Appendixes

Configuring Multiple IP Addresses on UNIX

To configure multiple IP addresses on UNIX, manually configure the
addresses on the load generator machine.

➤ Solaris 2.5, 2.6, 7.0, 8.0

➤ Linux
➤ HP 11.0 or higher
➤ IBM AIX

Solaris 2.5, 2.6, 7.0, 8.0

To configure the hme0 device to support more than one IP address:
1 Create entries in /etc/hosts for each hostname on your physical machine:

128.195.10.31 myhost
128.195.10.46 myhost2
128.195.10.78 myhost3

2 Create /etc/hostname.hme0:n files that contain the hostname for the

virtual host n. Note that hostname.hme0:0 is the same as hostname.hme0.

/etc/hostname.hme0 (Contains name myhost)

/etc/hostname.hme0:1 (Contains name myhost2)
/etc/hostname.hme0:2 (Contains name myhost3)

The above changes will cause the virtual hosts to be configured at boot time.
3 You can also directly enable/modify a logical hosts configuration by running
ifconfig directly on one of the logical hosts, using the hme0:n naming
scheme:

% ifconfig hme0:1 up
% ifconfig hme0:1 129.153.76.72
% ifconfig hme0:1 down

To verify the current configuration, use ifconfig –a.

468
 Appendix E • Configuring Multiple IP Addresses

Linux
To define multiple IP addresses for a single Ethernet card, you need IP
Aliasing compiled into the kernel. To do this, use the ifconfig command:

/sbin/ifconfig eth0:0 x.x.x.x netmask 255.255.x.x up

Substitute the new IP address for x.x.x.x, and insert the correct information
for subnet mask. Place this command in the rc.local file so that it executes
upon boot.

HP 11.0 or higher
To define multiple IP addresses for a single Ethernet card, you need IP
Aliasing compiled into the kernel. To do this, use the ifconfig command:

/sbin/ifconfig lan1:0 x.x.x.x netmask 255.255.x.x up

Substitute the new IP address for x.x.x.x, and insert the correct information
for subnet mask. Place this command in the rc.local file so that it executes
upon boot.

IBM AIX
To define multiple IP addresses for a single Ethernet card, you need IP
Aliasing compiled into the kernel. To do this, use the ifconfig command:

/usr/sbin/ifconfig [int] [ip address] alias netmask [mask]

For example, if you want to add IP address 10.0.0.1 to the main interface,
you need to run, as root, the following:

/usr/sbin/ifconfig ne0 10.0.0.1 alias netmask 255.255.255.0

To execute this line upon boot, create a standard script in the appropriate
run level (/etc/rc.d/rc#.d).

469
Part VII • Appendixes

Updating the Routing Table

Once the client machine has new IP addresses, the server needs the
addresses in its routing table, so that it can recognize the route back to the
client. If the server and client share the same netmask, IP class, and network,
the server’s routing table does not require modification.

Note: If there is a router between the client and server machines, the server
needs to recognize the path via the router. Make sure to add the following to
the server routing table: route from the Web server to the router, and routes
from the router to all of the IP addresses on the load generator machine.

To update the Web server routing table:

1 Edit the batch file that appears in the IP Wizard Summary screen. An
example .bat file is shown below.

2 For each occurrence of [CLIENT_IP], insert your IP address instead.

3 Run the batch file on the server machine.

470
 Appendix E • Configuring Multiple IP Addresses

Enabling Multiple IP Addressing from the Controller

Once you define multiple IP addresses, you set an option to tell the
Controller to use this feature.

To enable multiple IP addressing from the Controller:

1 In the Controller Design view, select Scenario > Enable IP Spoofer.

Note: You must select this option before connecting to a load generator.

2 Use the General Options of the Controller Expert Mode to specify how the
Controller should implement this feature.
For more information, refer to Appendix C, “Working in Expert Mode.”

471
Part VII • Appendixes

472
F
Controller Command Line Arguments

When you invoke the Controller from the command line, you can pass
arguments to instruct the Controller how to behave. By passing arguments
in the command line, you configure Controller scenario settings without
the need to manually define them using the Controller UI.

This appendix describes:

➤ About Controller Command Line Arguments

➤ Invoking the Controller from the Command Line
➤ Quality Center Arguments
➤ Run-Time Arguments

About Controller Command Line Arguments

When invoked, the Controller checks all of the received arguments and sets
its start-up environment accordingly. If no arguments are passed, the
Controller uses its default settings.

For example, you can instruct Controller to Connect to Quality Center on

start-up, save results to a directory other than the directory defined in the
scenario, and invoke Analysis upon scenario termination.

473
Part VII • Appendixes

Invoking the Controller from the Command Line

To invoke the Controller, type wlrun in the command line, followed by the
arguments. Each argument should be preceded by a dash. Note that the
arguments are case-sensitive. For example:

wlrun -TestPath C:\LoadRunner\scenario\Scenario.lrs -Run

When you invoke the Controller from the command line, the following
rules apply:

➤ If the Controller is invoked with no arguments in the command line, the

Controller uses its default settings.
➤ The Controller will always overwrite results.
➤ The controller will automatically terminate upon scenario termination and
results will be collected. If you don’t want the controller to automatically
terminate upon scenario termination, add the flag -DontClose to the
command line.
➤ The Controller launched through the command line behaves normally
except when using the -Run option. Using the -Run option, dialogs and
message boxes that usually open and require the user to close them in a
usual launch, do not open in a command line launch.
➤ The Controller’s settings are loaded from wlrun5.ini, located in Windows
directory.

474
 Appendix F • Controller Command Line Arguments

Quality Center Arguments

These arguments define the LoadRunner integration with Quality Center.
For more information about the LoadRunner Quality Center integration,
refer to Chapter 12, “Managing Scenarios Using Quality Center.”

ConnectToQC Specifies whether the Controller should connect to

Quality Center on startup (0/1 or ON/OFF)

QCServer Quality Center server name. Must be a machine

where Quality Center is installed

QCDB Quality Center database name. Use the format:

"<Domain name>.<Project name>".

UserName User name for connecting to Quality Center

Password Password corresponding to the user name

TestPath Path to scenario in Quality Center database. For

example,
"[TD]\Subject\LoadRunner\Scenario1"
If path includes blank spaces, use quotation marks.

TestId Test ID (used by Quality Center only)

ResultCleanName For use with ResultCycle only. Example: "Res1"

ResultCycle Quality Center cycle. For example,

"LR_60_SP1_247"
Note: The ResultCycle and ResultCleanName
arguments are required if you wish to store
the results within the Quality Center
database.

475
Part VII • Appendixes

Run-Time Arguments
These arguments specify the run-time related scenario settings. For more
information on scenario settings, refer to Chapter 11, “Preparing to Run a
Scenario.”

TestPath Path to the scenario, for example,

C:\LoadRunner\scenario\Scenario.lrs
This argument can also be used for a scenario
residing in a Quality Center database. For example,
"[TD]\Subject\LoadRunner\Scenario1"
If the path includes blank spaces, use quotation
marks.

Run Runs the scenario, dumps all output messages into

res_dir\output.txt and closes Controller

InvokeAnalysis Instructs LoadRunner to invoke Analysis upon

scenario termination. If this argument is not
specified, LoadRunner uses the scenario default
setting.

ResultName Full results path. For example, "C:\Temp\Res_01"

ResultCleanName Results name. For example, "Res_01"

ResultLocation Results directory. For example, "C:\Temp"

Note: If the scenario doesn’t specify a results directory, and one of the
results arguments was not passed, the scenario will not run.

476
G
Working with Digital Certificates

A Digital Certificate is an electronic “credit card” that establishes your

credentials when doing business or other transactions on the Web. It is
issued by a Certification Authority (CA). It contains the IP address of the
machine for which it was issued, a validation date, and the digital signature
of the certificate-issuing authority.

This appendix describes:

➤ Using Digital Certificates with Firewalls

➤ Creating and Using Digital Certificates

Using Digital Certificates with Firewalls

When the MI Listener sends its Public Key to the LoadRunner agent, it
always sends its certificate as well (this is the server-side certificate). The
LoadRunner agent can be configured to authenticate the certificate which it
received, as described in Chapter 16, “Running Vusers Over a Firewall.” If
the agent is configured to authenticate the certificate, it can verify whether
the sender is really the machine that it claims to be by:

➤ Comparing the certificate's IP address with the sender’s IP address.

➤ Checking the validation date.
➤ Looking for the digital signature in its Certification Authorities list.

477
Part VII • Appendixes

The MI Listener may also require the LoadRunner agent to send a certificate
at any point in the session. This is called the client-side certificate, as
described in the MI Listener Configuration Settings in Chapter 16,
“Running Vusers Over a Firewall.” If the LoadRunner agent owns a
certificate, it sends it to the MI Listener for the same authentication process.
If the LoadRunner agent does not own a certificate, the communication
might not be continued.

An SSL CA list and an SSL Certificate are included in each LoadRunner

installation. This certificate is the same for all LoadRunner installations,
which means that it can be obtained by third parties. Therefore, if you are
interested in a more secure process, you should create your own Certificate
Authority and include it in the list, and issue matching certificates for your
machines.

Creating and Using Digital Certificates

You create a Certification Authority using the gen_ca_cert.exe (on UNIX
platforms gen_ca_cert) utility, and a Digital Certificate using the
gen_cert.exe (on UNIX platforms gen_cert) utility. Both utilities can be used
on UNIX and Windows platforms, using a command-line interface.

To create a Certificate Authority using gen_ca_cert:

1 To view the format and usage, run the gen_ca_cert utility from the
<LoadRunner root folder>\launch_service\bin directory.

478
 Appendix G • Working with Digital Certificates

2 Create a new Certificate Authority by running the gen_ca_cert command

with at least one of the options: -country_name <country name>
-organization_name <organization name> and -common_name <the name of
the CA>.
This process creates two files in the directory from which the utility was run:
the CA Certificate (cacert.cer), and the CA Private Key (capvk.cer). To
provide different file names, use the -CA_cert_file_name and the
-CA_pk_file_name options respectively.
By default, the CA is valid for three years, from the time that the CA is
generated. To change the validation dates, use the options -nb_time
<beginning of validity in dd/mm/yyyy format> and/or -na_time <ending of validity
in dd/mm/yyyy format>.
The following example creates two files: ca_igloo_cert.cer and
ca_igloo_pk.cer in the current directory:

3 To install this CA, use the -install <name of certificate file> option. This option
replaces any previous CA list and creates a new one that includes only this
CA.
To add the new CA to the existing CA list, use the -install_add <name of
certificate file>.

4 The -install and -install_add options install the certificate file only. Keep the
private key file in a safe place and use it only for issuing certificates.

479
Part VII • Appendixes

To create a Digital Certificate using gen_cert:

1 To view the format and usage, run the gen_cert utility from the
<LoadRunner root folder>\launch_service\bin directory.

2 Create a new Digital Certificate by running the gen_cert command with at

least one of the options: -country_name <country name>,
-organization_name <organization name>, -organization_unit_name
<organization unit name>, -eMail <email address> and -common_name <the
name, full name or IP address of the machine>.
The CA Certificate and the CA Private Key files are necessary for the creation
of the certificate. By default, it is assumed that they are in the current
directory, and are named cacert.cer and capvk.cer respectively. In any other
case, use the -CA_cert_file_name and -CA_pk_file_name options to give the
correct files and locations.
In this process, the certificate file is created in the directory from which the
utility was run. By default, the file name is cert.cer. To provide a different
name, use the -cert_file_name option.
By default, the CA is valid for three years, from the time that the CA is
generated. To change the validation dates, use the -nb_time <beginning of
validity in dd/mm/yyyy format> and/or -na_time <ending of validity in
dd/mm/yyyy format> options .

480
 Appendix G • Working with Digital Certificates

The following example creates the igloo_cert.cer file in the current

directory:

3 If you wish to install this certificate, use the -install <name of certificate file>
option. This option replaces any previous certificate, as it is possible to own
only one certificate per machine.

481
Part VII • Appendixes

482
Index
A configuring (cont’d)
script (Percentage Mode) 118–122
Acrobat Reader xi
Vusers 64
Add Group dialog box 57
connecting
Add Load Generator dialog box 74
to database 443
Add Script dialog box 139
to Quality Center 196
Add Vusers dialog box 69
Connection Log tab 433
adding measurements 280
Context Sensitive Help xii
agent
Controller 40
daemon 442
defined 6
defined 7
invoking 37
summary window 243
managing scenario files 44
troubleshooting 458
overview 40
application
quick tour 37–48
analyzing 22–24
running from the command line 474
configuration 23
Controller window
usage model 24
Design view 40
menu bar 40
B Run view 46
Books Online xi Status bar 40
breaking down J2EE transactions, example title bar 40
304 Toolbar 42
controller_host 419
controller_path 419
C converting a scenario
CA 477 to Percentage mode 112
Collate Results dialog box 192 to Vuser Group mode 123
collating scenario results 191 creating
command line goal-oriented scenario 125–143
arguments 473 manual scenario 51–110
options, Vuser script 106 manual scenario in Percentage Mode
configuring 381–394 111–124
load generator 53, 74–77 Vuser groups 55–61
load generator settings 78–104 Vuser scripts 18
scenario 173–183
script 105–109
script (goal-oriented scenario)
139–143

483
Index

D ERP/CRM Diagnostics 323

about 324
database
breakdown distribution 354
connecting to 443
enabling 354
debug
mediator 325
information settings 426
module architecture 325
level 380
module types 327
Design tab
Oracle DB 346
manual scenario 55
setting up 328
Percentage mode 113
Siebel 329
Details button 237
Siebel DB 338
diagnostics
ERP/CRM Mediator 325
configuring Oracle DB 346
Error - Vuser state
configuring Siebel 329
Scenario Groups pane 230
configuring Siebel DB 338
error handling 379
enabling Oracle DB logging 346
Execution Notes dialog box 242
enabling Siebel DB logging 339
Exiting - Vuser state
ERP/CRM Mediator 325
Scenario Groups pane 230
Diagnostics Distribution dialog box 354
Expert mode 423–433
digital certificate
connecting to UNIX load generator
agent configuration settings 268
432
MI Listener configuration settings 271
debug settings 426
overview 477
general settings 424
disabling
monitor settings 430
Vuser groups 60
output settings 428
Vuser scripts (goal-oriented) 143
Vuser scripts (manual scenario) 122
disconnecting from Quality Center 198 F
documentation set xii files, Vuser script 107
Done.Failed - Vuser state firewalls
Scenario Groups pane 230 configuration overview 252
Done.Passed - Vuser state configuring agent to operate over
Scenario Groups pane 230 firewall 266
Down - Vuser state configuring the Controller 272
Scenario Groups pane 230 installation configurations 250
Duration 153 installing MI_Listener 270
installing Monitors over Firewall 276
E monitoring over 275–283
preparing for data collection 277
Edit Scenario Goal
running Vusers 257–274
Load Behavior tab 134
troubleshooting 254, 450
Load Preview 130
understanding 247
Scenario Settings tab 133
Function Reference xi
Edit Scenario Goal dialog box 130
Edit Schedule 148
encoder
Password Encoder 400

484
 Index

G IP addresses (cont’d)
configuring on HP 469
goal-oriented scenario 125–143
configuring on Linux 469
assigning load generators to scripts
configuring on Solaris 468
137
enabling from the Controller 471
assigning percentage of target to
hostid 466
scripts 137
IP Wizard 464
defining goals 130
load generator machine 461
Design tab 128
netid 466
Select Scenario Type 38
submask 466
Gradual Exiting - Vuser state
Scenario Groups pane 230
Graph Configuration dialog box 384 J
graph time 386 J2EE
graphs, See online graphs Mediator 289
Group Information dialog box 61 Probe 289
GUI Vusers, defined 10 J2EE Diagnostics
example 304
H Mediator 289
J2EE Diagnostics monitor
hardware
activating on the client machine 294
checking communications 436
Call window 301
selecting for testing 30–32
class graph data 308
hme0 device 468
class graphs 306
hostid, IP address component 466
configuring JDBC information
Hostinfo utility 438
retrieval 293
hosts file 439
configuring on the application server
HP, configuring IP addresses 469
291
initial configuration settings 293
I method/query graphs 307
increasing number of Vusers 449 transaction graphs 304
initialization quota 85 transaction layer graphs 305
Initialize 219 troubleshooting 320
Initializing - Vuser state viewing call chain statistics 300
Scenario Groups pane 230 viewing call stack statistics 300
installing viewing data 297
LoadRunner, See the LoadRunner J2EE Diagnostics monitors 287–321
Installation Guide J2EE Diagnostics tab 297
Installing Monitors over Firewall 275 J2EE probe
installing Monitors over Firewall 276 configuring the JBoss application
interpreting online graphs 413–416 server 318
invoking the Controller 37 configuring the Oracle9i application
IP addresses server 317
adding to a load generator 463 configuring the WebLogic application
class 466 server 315
configuring multiple 461–471

485
Index

J2EE probe (cont’d) Load Generator Information dialog box

configuring the WebShere application (cont’d)
server 310 WAN Emulation Advanced options
JBoss, configuring for J2EE Diagnostics 318 101
JDBC information retrieval, configuring 293 WAN Emulation tab 98
JDBC information retrieval, initial load generators 6
configuration settings 293 adding 77
adding an IP address 463
balancing 138
L
configuration 53, 74–77
license information 14 defined 6
Linux modifying 77
configuring IP addresses 469 multiple IP addresses 425
lists 18 selecting 70
load generator list 74–77 selecting (Percentage Mode) 116
rendezvous list 161–169 setting attributes 78–104
script list 105–109 viewing load generator details 75
script list (goal-oriented scenario) Load Generators window 74
139–143 load testing, defined 3
script list (Percentage Mode) 118–122 LoadRunner
Vuser group list 55–61 application testing 3
load balancing 138 emulating human users with Vusers 5
load generator configuration 74 implementation planning 27
checking Controller communication overview 3–16
437 testing process, See testing process
connecting load generators 75 working with LoadRunner 6
disabling load generators 74 LoadRunner license information 14
disconnecting load generators 75
enabling load generators 74
Expert mode 431 M
firewall 87 manual scenario
initializing quota 85 creating 51–110
limiting of Vusers 86 defined 38
run-time files 81 Design tab 55
selecting load generators 70 Percentage mode 111–124
Terminal Services 95 Measurement Configuration dialog box
UNIX shell 82 Configuration tab 387
WAN emulation 97 Description tab 387
Load Generator Information dialog box 79 measurement frequency, setting 281
Firewall tab 87 MI_Listener 270
Run-Time File Storage tab 81 middleware
Run-Time Quota tab 85 response time measurements 29
Status tab 80 system configuration 23
Terminal Services tab 95 modifying license information 16
Unix Environment tab 82 Monitor Configuration dialog box 278
Vuser Limits tab 86 monitoring over a firewall 275–283
Vuser Status tab 89

486
 Index

monitors online monitors (cont’d)

J2EE Diagnostics 287–321 graph time 386
online 361–366 graphs 381
monitors over firewall interpreting online monitoring
adding and removing measurements graphs 413
280 line color 387
configuring measurement frequency pausing 383
281 show/hide lines 389
configuring properties 277 starting 372
installing 275 viewing data offline 394
preparing for data collection 277 Open a New Graph dialog box 374
multiple IP addresses 425 Open Scenario from Quality Center project
connecting to Controller 440 dialog box 200
enabling 425 Options dialog box
Debug Information tab 426
General tab 424
N
Path Translation Table tab 420
netid, IP address component 466 Run-Time File Storage tab 181
Network Run-Time Settings tab 177
Network Delay options 386 Timeout tab 175
New Monitored Server Properties dialog box Oracle Configuration dialog box 350
278, 282 Oracle DB Diagnostics
New Scenario dialog box 37 configuring 346
disabling diagnostics password
O request 348
enabling logging 346
online graphs 381–394 enabling trace diagnostics 346
bar value 386 setting diagnostics password 347
customizing display view 376 setting trace file limits 347
exporting 393 setting up on the Controller 349
interpreting 413–416 Oracle Server Configuration dialog box 351
merging two graphs 392 Oracle9i, configuring for J2EE Diagnostics
modifying a measurement scale 388 317
opening graphs 374 output file 447
refresh rate 385 Output window 233–238
remote monitoring 395 clearing 237
sampling rate 379 debugging information 446
transaction data 378 drilling down on log information 235
viewing data offline 394 filtering messages 237
x-axis style 385 refreshing 236
y-axis style 386 saving messages to a file 237
online monitors 361–366 sorting messages 238
configuring measurements 387 viewing message detail 237
debugging 380 Overlay Graphs dialog box 393
display type 386
error handling 379

487
Index

P R
Password Encoder 400 Ramp Down 154
path translation Ramp Up 152
debugging file locations 443 Ready - Vuser state
defined 417 Scenario Groups pane 230
editing the Path Translation Table 420 Refresh button 106
examples 422 registry, modifying 449
scenario configuration 183 relative script paths 109
script path 110 Remote Agent Dispatcher (Process) 7
using the Path Translation Table 419 Remote Performance monitoring 395–410
pausing configuring graph measurements 409
monitors 383 configuring graph settings 406
Vusers 220 configuring the user settings 398
Pending - Vuser state connecting to the monitor 401
Scenario Groups pane 230 installing the monitor 397
Percentage mode refreshing graphs 408
assigning load generators to scripts scaling graphs 406
116 viewing online graphs 403
assigning percentage of total Vusers to remote_host 420
scripts 116 remote_path 420
converting a scenario to Percentage removing measurements 280
Mode 112 rendezvous 161–169
converting to Vuser Group mode 123 attributes 163
creating a scenario 111–124 defined 5
defining the total number of Vusers disabling Vusers 167
114 enabling Vusers 167
Design tab 113 information 169
performance analysis, defined 6 manually releasing Vusers 221
performance measurement scope 27 overview 161
planning load tests 21–35 setting release policy 166
Probe 289 setting the attributes 163
setting timeout policy 166
Vuser state 230
Q
Rendezvous Information dialog box 169
Quality Center renumbering Vusers 220
adding Vuser scripts 204 response time measurement
command line arguments 475 end-to-end 27
connecting to 196 GUI 28
disconnecting from 198 middleware-to-server 29
integration 195–206 network and server 27
managing scripts 195 server 28
opening a scenario 200 results 186
saving results to Quality Center 203 collating 191
saving scenarios to Quality Center directory file structure 189
201 files for debugging 443
Quality Center Connection dialog box 196 location in Quality Center project 203

488
 Index

results (cont’d) scenario (cont’d)

naming 186 manual scenario defined 38
specifying location for 186 New Scenario dialog box 53
routing table 470 opening 44
rsh opening from Quality Center 200
checking Controller connection 441 overview 52
running UNIX without 441 overview of running 46–48
RTE Vuser scripts preparing to run 185–194
in the Controller 13 result directory 189
Run/Stop Vusers dialog box 222 running 209–221
Running - Vuser state saving 45
Scenario Groups pane 230 saving to Quality Center 201
running over firewall 257–274 Scenario Goal window 128, 130
Run-Time graphs Scenario Scripts pane 128, 130
interpreting 413 Scenario Start dialog box 147
run-time settings scheduling 151
configuring (Controller) 71 summary information 194
setting in a goal-oriented scenario viewing output messages 233
(Controller) 141 scenario configuration
setting in a manual scenario path translation 183
(Controller) 105 run-time file location 179
shared (Controller) 72 run-time settings 177
run-time viewer specifying results location 186
view replay from Controller 220 timeout intervals 174
scenario execution 209–221
activating additional Vusers 222
S
controlling individual Vuser groups
sampling rate 379 212
Save Scenario to Quality Center project controlling individual Vusers 219
dialog box 201 delaying 147, 151
scenario limiting duration 151
closing 45 loading Vuser groups 212
collating results 191 loading Vusers 220
configuring 173–183 manually releasing Vusers from a
conversion to Percentage mode 112 rendezvous 221
conversion to Vuser Group mode 123 messages 233
creating a goal-oriented scenario monitoring active Vusers 230
125–143 overview 46–48, 209
creating a manual scenario 51–110 pausing Vuser groups 213
creating a manual scenario in running scenarios unattended 211
Percentage Mode 111–124 running Vuser groups 213
creating a new scenario 44 stopping Vuser groups 214
defined 5 Schedule Builder 145–159
defining scenario goals 130 creating a schedule 149
goal-oriented scenario defined 38 deleting a schedule 149
managing scenario files 44–45, 46 modifying a schedule 149

489
Index

Schedule Builder (cont’d) Siebel DB Server Configuration dialog box

renaming a schedule 149 342
scenario execution 151 Siebel Diagnostics
Schedule Builder dialog box 149 configuring 329
selecting a schedule 148, 148–159 configuring application server 329
Vuser groups 155 configuring where Web server inside a
Schedule Definition dialog box DMZ 331
Duration tab 153 copying files from the application
Ramp Down tab 154 server to the mediator 332
Ramp Up tab 152 enabling Siebel diagnostics 329
Schedule Definition dialog box (Group) generating application server IDs 330
Duration tab 157 optimizing server performance
Ramp Down tab 158 settings 330
Ramp Up tab 156 setting up on the Controller 333
Start Time tab 155 Siebel Server Configuration dialog box 334
Script Information dialog box 140 Solaris
script paths, relative 109 configuring IP addresses 468
scripts, See Vuser scripts SSL
server monitors agent configuration settings 268
adding and removing measurements MI Listener configuration settings 271
280 overview 477
cloning a server 282 Status bar 40
configuring properties 277 Stopped - Vuser state
setting a measurement frequency 281 Scenario Groups pane 230
server routing table 470 stopping
Set Results Directory dialog box Vuser groups 214
local or remote location 187 Vusers 219
Quality Center project 203 Summary Information dialog box 194
settings Support Information xii
debug 426 Support Online xii
general 424
load generator 78–104
T
measurement frequency 281
monitors 430 TCP/IP setup 438
output 428 Terminal Services 90
timeout 174 agent 91
show/hide a measurement distributing Vusers 95
online monitors 383 launching a client 93
Transaction monitor 389 test objectives
Siebel Configuration dialog box 333 defining 25–26
Siebel DB Configuration dialog box 341 summary of common objectives
Siebel DB Diagnostics 33–35
configuring 338 testing process
enabling logging 339 analyzing test results 20
setting up on the Controller 340 creating the scenario 18
creating the Vuser scripts 18

490
 Index

testing process (cont’d) Vuser groups (cont’d)

monitoring a scenario 20 scheduling 155
planning the test 18 stopping 214
running the scenario 19 Vuser scripts 5
timeout adding (goal-oriented scenario) 139
Controller settings 174 adding (Percentage Mode) 118
Toolbar 42 adding from Quality Center 204
transaction data 378 assigning load generators to (goal-
transactions 5 oriented scenario) 137
deciding which to define 29 assigning load generators to
defined 5 (Percentage mode) 116
failed 445 assigning percentage of defined target
Transactions dialog box 232 to (goal-oriented scenario) 137
troubleshooting assigning percentage of total Vusers to
agent 458 (Percentage mode) 116
Controller 435–459 command line options 106
firewalls 450 configuring 105–109
creating 18
defined 5
U
deleting (goal-oriented scenario) 143
UNIX deleting (Percentage Mode) 122
connection to load generator 432 editing 108
rsh 441 enabling/disabling (goal-oriented
shell 441 scenario) 143
without rsh 441 enabling/disabling (manual scenario)
UNIX LoadRunner agent 262 122
files 107
V modifying script details 105, 108
selecting for group 70
viewing diagnostics results 357 selecting for load generator 58
viewing Vusers 229–243 selecting for scenario 39
agent summary 243 Vusers
Output window 233 activating additional during scenario
overview 229 execution 222
Virtual users, See Vusers adding to a group 69, 70
Vuser configuring 64
group list 55–61 deciding how many to run 29
Vuser groups defined 5
adding Vusers to 69, 70 emulating maximum user load 161
creating 55–61 error, warning, and notification
deleting 60 messages 233
enabling/disabling 60 GUI Vusers 10
loading 212 loading 220
modifying 60 monitoring 230
pausing 213 pausing 220
running 213 renumbering 220

491
Index

Vusers (cont’d)
RTE Vusers 13
running 219
status in Scenario Groups window 230
stopping 219
types of 8
viewing 229–243
Vuser Information dialog box 108
Vuser Log 239
Vuser script log 221
Vuser window 47
Vusers window 64

W
WAN emulation 97
advanced options 101
configuring the settings 98
excluding Hosts 103
predefined profile settings 99
setting up 98
stopping and starting 104
WebLogic Version 6.1, configuring for J2EE
Diagnostics 315
WebLogic Version 7.x, configuring for J2EE
Diagnostics 316
WebLogic Version 8.1, configuring for J2EE
Diagnostics 317
working with firewalls 247

492
Host Resolution Functions Copyright Agreement
Copyright (c) 1980, 1983, 1985, 1987, 1988, 1989, 1990, 1993
The Regents of the University of California. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that 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. All advertising materials mentioning features or use of this software must display the following
acknowledgement:
This product includes software developed by the University of California, Berkeley and its contributors.
4. Neither the name of the University nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
Portions Copyright (c) 1993 by Digital Equipment Corporation.
Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted,
provided that the above copyright notice and this permission notice appear in all copies, and that the name of
Digital Equipment Corporation not be used in advertising or publicity pertaining to distribution of the document
or software without specific, written prior permission.
THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP. DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
IN NO EVENT SHALL DIGITAL EQUIPMENT CORPORATION BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Copyright (c) 1996 by Internet Software Consortium.
Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted,
provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
494