Benchmark Factory for Database 8.1 - User Guide

About Agents

The Benchmark Factory Agent is a component used in Benchmark Factory to create virtual users which simulate real-world user activity by placing transactions against the database-under-test. The Benchmark Factory Agent is installed when the Benchmark Factory Console is installed. In addition, you can install additional agents on other remote machines. Each Benchmark Factory agent can spawn multiple virtual-user sessions and Benchmark Factory can control hundreds of Agent machines.

After installing additional agents, use your Benchmark Factory Console to define a connection to each agent machine. When you create a new benchmark test through the Console, you can select which of the defined agents to use to generate the user load.

Each virtual user is a separate thread, acting independently of the other virtual users, with its own connection to the system-under-test. Each virtual user tracks its own statistics, including transaction times and the number of times a transaction executes.

View Agent Information

The Benchmark Factory Console allows you to view information about all currently running agents, provides a way to connect to and manage remote agents, and allows you to specify some global agent settings. In addition, the primary Agent, Agent.exe, includes a GUI which displays transaction and virtual user statistics during test execution.

• Select View | Agent to open the Agents pane where you can view information about agents that are currently running.
• Select Edit | Settings | Agent to view a list of all the configured agents which are available to be used in testing, as well as platform information about each agent machine. Use this page to view the agent global settings, as well.
• Double-click Agent.exe in the bin directory to open the Benchmark Factory Agent. The GUI displays virtual user statistics during test execution. Select Options | Settings to configure options for this agent.

Types of Agent Components

Benchmark Factory provides several types of agent components:

• Agent.exe—(Windows) The primary agent. This agent is installed with the Benchmark Factory client application and can be found in the bin directory. This component includes a GUI.

• BMFAgent.exe—(Windows or Linux) The non-GUI agent. You can use BMFAgent.exe to integrate Benchmark Factory into your continuous integration or continuous testing process. See BMFAgent.exe for more information.

  • (Windows) The Windows version of this agent is installed with the Benchmark Factory client application and can be found in the bin directory.
  • (Linux) For a Linux platform, you can download a Linux version of this agent from the Benchmark Factory Community on Toad World. See Install Remote Agent on Linux for more information.

Using Agents

Review the following topics to learn how to use the Benchmark Factory Agent.

• Set Up New User Agent—To set up a remote agent
• Agent Settings —To view configured agents and specify default settings
• Install Remote Agent on Windows—To install a remote agent on a Windows platform
• Running Benchmark Factory with Multiple Agents—To learn how to run a test using multiple agents
• BMFAgent.exe—To learn about the non-GUI agent
• Install Remote Agent on Linux—To install a remote agent on a Linux platform

Set Up New User Agent

You must define a connection to each agent machine before you can use that agent in a Benchmark Factory test. The local Benchmark Factory Agent is defined by default. After installing a remote agent however, use this procedure to define a connection to the remote agent machine from the console.

For information about installing remote agents, see Install Remote Agent on Windows and Install Remote Agent on Linux

To setup a new user agent

1. Select Edit | Settings | Agent.
2. Click Setup New User Agent.
3. Select which type of agent to set up, Windows or Linux, based on the platform on which the agent is installed.

4. In the Setup Windows/Linux Agent dialog, enter the name or IP address of the computer where the agent is installed.

   Tip: If you want to install an agent on a Windows platform, enter the name or IP address of the computer on which you want to install an agent. Then see Install Remote Agent on Windows for more instructions.

5. Enter the connection information.
6. Specify the number of agents.
7. (Linux) If the agent is on a Linux platform, enter the path where the Benchmark Factory Agent files are located on the agent machine.
8. Click OK.
9. Benchmark Factory connects to the computer and then checks if the agent is installed.
10. If agent installation is verified, the agent is added to the list. Select the agent to display platform information.
11. To learn how to use multiple agents when running a test in Benchmark Factory, see Running Benchmark Factory with Multiple Agents.

Specify Agent Settings

Use this page of the Settings dialog to do the following:

• Install remote agents on Windows
• Set up a new agent by creating a connection to the agent machine
• Specify default settings (error handling and communication timeout) for each agent
• Specify the default agent/agents to use when creating a new job.

To specify Agent settings

1. Select Edit | Settings. The Settings dialog opens.

2. Select Agent. Review the following for additional information:

   Setup New User Agent	Click to setup a new agent or to install a remote agent on Windows. To learn how to set up an agent, see Set Up New User Agent. To learn about installing a remote agent (Windows), see Install Remote Agent on Windows.
   List of agents	Displays the list of agents that have been set up in the console. Select an agent to display platform information for the agent machine. Double-click an agent to open the Edit User Agent dialog. Use this area to specify the default agent machines to use by selecting the check box for each default agent. Also, specify the number of agents. These default settings are used when you create a new job. If you do not select a default agent, the local agent is automatically selected when you create a new job in the New Job wizard. Note: When you run a job using one or more local agents, if Agent utilization of resources on the local machine is too high, errors could occur.
   Remove	Click to remove the selected agent.
   Verify Selected Agent	Verifies that the selected agent starts and communicates with console.
   Error Handling	Stop job when agent cannot be started/connected—Cancels job if agent does not start or connection is lost. Do not select this option if you want to run a job using multiple agents AND you want the job to run even if one or more agents do not start.
   Agent communication timeout	Specify timeout duration in seconds.
   Agent refresh interval	Specify how often each agent should refresh its status.

Tips:

• In the New/Edit Job Wizard, select Agent in the left pane of the wizard to access agent options for the selected job. You can select agents or set up new agents from this page of the wizard.
• To open the Agent console, go to Program Files\Quest Software\Benchmark Factory <version>\bin and double-click Agent.exe. See The Benchmark Factory Agent Console for more information.

Install Remote Agent on Windows

You can install agents to remote computers from your Benchmark Factory console. You must be able to connect to the remote machine.

This procedure is designed for installing the agent on a Windows platform. To install the Benchmark Factory agent in a Linux environment, see Install Remote Agent on Linux.

To install remote agents from the console

1. Select Edit | Settings | Agent.
2. On the Agent Settings page, click Setup New User Agent.
3. Select Windows and click OK. The Setup Windows Agent dialog opens.

4. Enter the connection information for the remote machine. Review the following for additional information:

   IP Address / Name	Enter the IP address or name of the remote machine.
   User Name	Enter the user name to use to connect. Note: Only accounts in the Administrators group on the remote machine can install or launch remote Agents. If in a domain, connect using a domain account in the Administrators group.
   Password	Enter the password to use to connect.
   Use Windows session credentials	Select to use Windows credentials.
   # of Agents	Specify the number of agents to deploy on this machine.

5. Click OK. Benchmark Factory checks the remote machine for an installed agent.
6. If no agent is found, Benchmark Factory prompts you to install the agent. Click Yes in the prompt window. The Setup User Agent dialog opens.

7. In the Installer field, browse to and select the Benchmark Factory installer.

   Note: The Installer can be located on your local machine or on the remote machine.

8. Click OK. The installer installs the agent component on the remote machine.

   Note: If the agent fails to install, you may need to configure the firewall or attempt one of the troubleshooting techniques. See Configure Firewall for Remote Agent Install/Start-Up.

9. When the agent is successfully installed, the progress window closes and the new remote agent displays in the list.
10. After the remote agent is installed, you can double-click the agent name in the list to modify agent options.

Configure Firewall

In order to install remote agents and allow communication with remote agents after installation, you may need to configure the firewall on the console machine and on each agent machine. See Configure Firewall for Remote Agent Install/Start-Up to learn more.

If you configure the firewall and then encounter an error when attempting to install a remote agent, find some troubleshooting techniques here: Troubleshooting.