Lotus Server.Load is the IBM Lotus Domino feature-based load generation tool that you can use to measure and characterize various Lotus Domino server capacity and response metrics. The load is generated by running workloads (also called scripts) that simulate the behavior of Lotus Domino client-to-server operations. The workloads allow you to use a common tool to apply a consistent, repeatable load against the Lotus Domino or IBM Lotus Sametime server so that you can assess the effects of various operating system, hardware, and configuration changes.
There are two different kinds of workloads: built-in and custom. Most built-in workloads are written to simulate different types of mail user activities. You are not limited, though, to those workloads that are built in. You can modify built-in workloads, or you can write your own workloads to best meet your needs. For an overview of Lotus Server.Load, see the developerWorks Lotus article, "Introduction to Domino performance tuning."
Lotus Server.Load is an installation option in the IBM Lotus Domino Administrator client. You can select it as part of the Lotus Domino Administrator client installation. Figure 1 shows the Server Load Utility option in the Custom Setup window of the Administrator client installation.
Figure 1. Lotus Notes client installation options
When you select the Server Load Utility option, the installation program puts a file called sload.exe and a database called namagent.nsf in the Lotus Domino Administrator's Notes directory. The program sload.exe is in the client's executable directory (notes), and the database namagent.nsf is in the client's data directory (notes\data). If you plan to run anything related to Lotus Sametime, make sure that CstClientTest.jar and stjavatk.jar are also copied to your executable directory, where sload.exe resides. These two files are necessary for running Lotus Sametime-enabled workloads.
This is the environment you should use for testing:
- Server Under Test (SUT). This is the test system running Lotus Domino to which Lotus Server.Load simulated users connect. The agents in the database (namagent.nsf) need to be copied to the Domino Directory of this server. These agents create test user Person documents, set ACL values, and more.
- Clients/drivers. These systems run Lotus Server.Load and the workload scripts simulating user activity against the SUT. These systems need to have a Lotus Notes client installed on them because Lotus Server.Load uses the Lotus Notes API to do its work. You may need to have several of these clients, based on the desired user load. Each client can usually run 512 to 1,500 simulated users (depending upon the client's hardware). Lotus Server.Load can also be used to collect Lotus Domino server statistics to a file. Use a separate client to run the server statistics collection script (more on this later). Client machines don't all need to be administration clients. You can use a standard Lotus Notes client as long as the necessary files are copied into the client's executable directory (usually the Notes directory ). Before running Lotus Server.Load, the clients need to connect to the SUT using the Lotus Notes client. We recommend setting up a test user ID and creating Location documents on the clients that point to the SUT.
Figure 2 shows the IBM Lotus Domino Designer client with both namagent.nsf and SUT's Domino Directory open, ready to copy the agents from the .nsf database to the directory. Agents, shown in the right pane, need to be selected, copied, and pasted in the same folder (Shared Code - Agents ) in the SUT's Domino Directory.
Figure 2. Lotus Server.Load setup agents
Now that the agents are copied to the SUT's Domino Directory, they can be used to set up the Mail Person documents. Follow these steps:
- In Lotus Domino Designer, choose Actions - Other.
- The Run Agent dialog box opens in which you can select the agents to run. Select the "Create NotesBench Mail Person Documents" agent to create the Person documents. Click Run.
- In the "Enter A Number 1-9 to Select Workload Setup" dialog box, enter 1 to select NRPC Mail. Click OK.
- In the "Create NotesBench Mail Person Documents" dialog box, enter 1 in the "Starting Value to Create Mail Users" field. Click OK.
- Next, enter 1000 in the "Number of Users to Create" field to add users to the Domino Directory. You can add as many users as you want, but keep in mind that to run a given user in the workload, that user needs to have a corresponding Person document. Click OK.
- Next, enter the same number you entered in step 5 in the "Number of Mailn.NSF Files to Use" field. In this case, enter 1000. Click OK.
- Enter 1 in the "Starting Mailn.NSF File" field. Be sure to enter the same value in this field that you did in step 4 in the "Starting Value to Create Mail Users" field. Click OK.
- In the "Location for Mail Databases (relative to Notes Data directory, blank = root)" field, enter mail\. Click OK.
- In the "Mail Domain (example: notebnch)" field, enter your server’s domain as the SUT's domain name. Click OK.
- In the "Mail Server (example: sut1/notebnch)" field, enter yourserver/yourdomain (filling in your server’s name and domain) as the SUT's name with its domain. Click OK.
- In the "Create Person Documents for NRPC Mail" dialog box, enter the SUT's fully qualified host name, yourserver.yourdomain.com for example, in the Internet Host Name field. Click OK.
- In the "Create NotesBench Mail Person Documents" dialog box that opens, enter a value in the "Message Storage Format" field. This value depends upon which format the users keep. For Notes format, select 0; for no preference, select 1; and for Internet/Web format, select 2. In most cases, for example running the N8Mail workload, select 0. Click OK.
- Enter 1 in the "Mail System" field, and then click OK.
- In the final dialog box, enter y in the "Click OK to run Create Notesbench Person Documents Agent with the following settings" field, and then click OK.
After you configure the environment on the SUT, you can configure the client side. The workloads run over databases, which need to be populated. Next, decide which workload suits your need. Many workloads are built in with Lotus Server.Load. These workloads accommodate user models that are representative of an average user and the actions that user may perform. The workloads delivered with Lotus Server.Load may not encompass everything your test environment demands, though, so Lotus Server.Load can input custom workloads as well. Refer to the documentation section about Lotus Server.Load in the Lotus Domino Administrator help to find in-depth details about the various built-in workloads.
Figure 3 shows a drop-down list of the various workloads in Lotus Server.Load.
Figure 3. Lotus Server.Load workloads
Let's start by running a built-in workload. Run the program sload.exe, which is one of the files loaded with the Lotus Server.Load option selected in the Lotus Domino Administrator client installation. By default, Lotus Server.Load selects the type of workload to build in. With this option, you can use the drop-down box to browse the workloads and to find the one that you want to run.
As we mentioned previously, we need to create and initialize mail databases on the server (SUT) to run our workload against. To do this, run a workload's initialization workload; when it's finished, you can run the actual workload. The initialization step is used for most workloads. More details on this process can be found in the Lotus Domino Administrator documentation.
Remember if the workloads provided do not match your needs, you can select Custom as the test type. Lotus Server.Load has a variety of commands from which to choose (refer to the documentation), and you can view the built-in workloads, copy those sets of commands, and edit them as you like. This approach makes it easier to quickly edit your own custom workload. After you write your custom workload, you can store it on your machine, and Lotus Server.Load gives you the option to open the script. You can view the script by clicking the Edit Script button, which allows you to modify and make changes to your custom script as necessary.
You can also select manual as the test type as shown in figure 3. The manual mode is used to run the various workload commands. When you select the manual mode, you can enter the commands using the Command-Line Screen tab. This mode is useful for testing parts of a script before running through it in its entirety.
Figure 4 shows four different tabs underneath the workload type area. The tabs, used to customize your workload further, each have a number of settings that you can edit. In the first tab, Test Parameters, you can edit the number of users that are simulated and the number of times you want your script to run. A thread creation interval (which delays starting each user/thread by that many seconds) is also given along with the starting thread number. Sometimes you may want your script to run for a certain time period; Lotus Server.Load allows you to do this with the test time parameter option. Last, you can use a name and address book to build a recipient list and to store your test output to a specified file.
Figure 4. The customization tabs in the Lotus Server.Load dialog box
Sometimes a script may time out or the response time may be too long. The Stop Conditions tab, shown in figure 5, lets you customize these conditions. Lotus Server.Load allows you to manually input the high value for both of these occurrences. If this number is reached, your test immediately stops, sending output on which the condition was met.
Figure 5. The Stop Conditions tab of the Lotus Server.Load dialog box
Almost all workloads rely on a script variable to drive the script. The third tab, Script Variables, shown in figure 6, lets you modify the values for each variable. (For details on what the variables are and their recommended values, see the Lotus Domino Administrator help.)
Figure 6. The Script Variables tab of the Lotus Server.Load dialog box
The last tab, Command Line Screen, is useful only in manual mode. As mentioned previously, you can use manual mode to manually input commands you may use for your script.
Now that everything is customized the way you like it, you can execute the workload.
The last thing you should do before you run a script is determine which metrics you want to record for the test. After you click the Execute button, you get a chance to choose your metrics as shown in figure 7. Lotus Server.Load allows you to select script metrics as well as a limited set of server stat metrics. It also keeps track of thread statistics for every minute. You can specify an optional storage for the metrics as well.
Figure 7. Specifying script metrics and server stat metrics
Now you can run the workload. The output is displayed in the window shown in figure 8. Lotus Server.Load keeps track of the start and end time, and it informs you when the test has completed.
Figure 8. The Output Monitor window
This is an example for creating mail databases to be used with the N8Mail workload. The screenshot in figure 9 shows a users/threads selection of 1; this creates one database, mail1.nsf. You can then write an O/S script to copy this database multiple times, incrementing the file name as mail2.nsf, mail3.nsf, and so on to get to the number of databases that match the test users you created. You can also let Lotus Server.Load build all the databases by entering the total number of databases in the "Number of Users/Threads" field.
Figure 9. Creating mail databases
This example shows the settings for running the N8Mail workload for which you previously created the mail databases. It is configured to run 1,000 simulated users. See figure 10.
Figure 10. Specifying the number of users
Figure 11 shows the variables used in this workload. Most of them were pre-loaded. You have to add two variables:
- The value for nb-dbdir. This is the subdirectory of the Lotus Domino data directory on the server that contains the simulated users mail databases - n this case the mail subdirectory.
- The MailTemplate variable. In this example, you want to use the mail template that is on the server (SUT) Dolly. The name of the mail template is mail8.ntf. The !! characters indicate that Lotus Server.Load should use the file on the server preceded by these marks. Therefore, construct this variable as Dolly!!mail8.ntf.
Figure 11. Variables used to run workloads
NOTE: Clients should be staggered to allow each client to come up fully before the next client starts. (The exception is the client that runs the server statistics collection script; this client should start with the first client.)
Although we have just barely scratched the surface of what Lotus Server.Load can do, this article provides enough information to let you start working with it. We aimed to take the mystery out of Lotus Server.Load so that you can read the documentation and take full advantage of this tool's capabilities.
Get started with IBM Lotus Notes and Domino V8 technical content.
Visit the developerWorks Lotus Performance page for even more performance information.
Read the developerWorks article, "IBM Lotus Notes V8: Taking performance to a new level."
Read the developerWorks article, "Introduction to Domino performance tuning."
Read the "Lotus Notes and Domino 8 Reviewer's Guide."
Refer to the Lotus Domino documentation.
Get products and technologies
Download a trial of IBM Lotus Domino V8.
Download a trial of IBM Lotus Notes, Domino Designer, and Domino Administrator clients V8.
Daniel Dumouchel is a Software Engineer for the IBM Lotus Domino performance team. He currently focuses on assisting performance engineers and testing performance tools. He joined IBM in June 2007 as an intern.
Joe Malek is a developer for the IBM Lotus Domino performance team. His current focus involves developing performance tools for the Lotus Domino performance team working on various platforms such as Microsoft Windows, Linux, IBM AIX, and Sun Solaris. Joe joined Iris Associates in October 2000.