Chapter 14 The Modify Performance Measurement Tool

The modrate tool measures the performance of modify operations in a Lightweight Directory Access Protocol (LDAP) v3 directory. This chapter provides instructions on how to use the modrate tool. It contains the following sections:

Overview

The modrate tool measures the performance of modify operations in an LDAP v3 directory. It is similar to the rsearch functionality described Chapter 12, "The rsearch Search Tool," except that it performs modifications on random user-defined attributes. The DSRK and its updates include the latest version of the tool in the DSRK_base/bin/dsrk52 directory.


Note	As with all measures of performance, results depend upon many factors, such as the options and parameter values given, directory configuration, machine load, and network traffic, and should be analyzed accordingly. In order to obtain accurate performance measurements, both client and server machines should be dedicated to the performance test and properly tuned. (See Chapter 10, "The idsktune Optimization Tool" for tuning information.)

Command Usage

Using multiple threads, the modrate tool repeatedly performs modify operations on a directory server. Threads may be configured to open connections and perform LDAP bind operations with every modification. The command-line options let you specify the target entries and attributes to be modified. The modrate tool has the following built-in defaults:

The tool displays performance results at regular intervals. In general, when the modrate tool encounters an error, it displays a message and continues running. It will attempt to bind again or modify again indefinitely, even after encountering an error.

Syntax

modrate -D "bindDN" -w password -b "baseDN" [ options ] \
-M "attribute:length:charSet" ...

bindDN and password are bind credentials with write permission to the target entry or entries. The bind DN is usually in double quotes ("") for the shell.

baseDN is the DN of the entry to be modified, usually in double quotes ("") for the shell. The target entry should support the attributes given by the -M option, either for modification or for addition when not already present. The base DN may use either of the following placeholders:

%d to include random numbers up to the value given by the -r option.

%s to include a random string from the file given with the -i option.



Note	See Randomly Generated Target Entries for more information.

options are the command-line options and their parameters described in Options.

The -M parameter gives the information needed to generate random attribute values. There can be any number of -M parameters on the command-line.

attribute is the name of an existing attribute of the target entry or entries given by the base DN. If this attribute does not exist on the target entry, it will be added and be subject to schema checking if it is enabled in the directory.

length is an integer giving the desired number of characters in random attribute string values.

charSet specifies a set of individual ASCII characters (c) and ranges of characters, according to the following syntax:

(c*([c-c])*)* for example: [A-Z][a-z][0-9]

Options

The modrate options and parameters are described in Table 14-1. Running the modrate command on the command-line without any options or parameters will display brief descriptions of all the command-line options.

Table 14-1 Command-Line Options for modrate
Option	Parameter	Purpose
-h	hostname	Specify the hostname of the directory server. The default is localhost.
-p	port	Specify the port number when accessing the directory server host. The default is 389.
-D	bindDN	Specify a bind DN for accessing the directory, usually in double quotes ("") for the shell. Depending on its write permissions, the bind DN may influence authentication and modify performance.
-w	password	Specify the password for the bind DN.
-b	baseDN	Specify the base DN of the target entry, usually in double quotes ("") for the shell. See Randomly Generated Target Entries on how to include %s or %d placeholders for random strings or numbers with the -i or -r options, respectively.
-M	modString	Specify the name of an attribute to modify and how to randomly generate a new value for it. The modString format (attribute:length:charSet) is described in Syntax.
-i	inputFile	Give the name of the file containing strings that will be randomly substituted into %s placeholders in the base DN. Each line of the input file will be treated as a separate string. See Randomly Generated Target Entries for more information. CAUTION: This option is incompatible with the -r option.
-r	maxRand	Give the maximum range for random numbers to be substituted into %d placeholders in the base DN. You may specify this option twice: the first random number will be in the range [0, maxRand1-1], the second will be in the range [1, maxRand2]. See Randomly Generated Target Entries for more information. CAUTION: This option is incompatible with the -i option.
-k		Keep connections open between modify operations. With this option, the modrate tool will measure only the execution time of bind and modify operations. When this option is omitted, the initialization and freeing of the connection is also measured as part of each modification sequence.
-K		Keep connections and binds open between modify operations. With this option, the modrate tool will measure only the execution time of modify operations. When this option is omitted, the initialization, binding, unbinding, and freeing of the connection is also measured as part of each sequence.
-u		Specify that the tool should not unbind from the server and just close the socket for the connection. This option has no effect when either -k or -K options are specified.
-O	hopLimit	(Capital letter O) Specify the maximum number of referral hops to follow while finding an entry to modify. By default, there is no limit.
-R		Specify that referrals should not be followed. By default, referrals are followed automatically.
-a		Specify asynchronous modification mode. This option is currently not working.
-t	threads	Specify the number of threads that modrate will run in parallel. The output displays the average performance of all threads combined. The default is a single thread.
-j	seconds	Specify the measurement and display interval, in seconds; the default is 5. modrate repeats the modify operation sequence as many times as possible during the interval and prints results after each interval elapses.
-m	modifyops	Specify the maximum, cumulated number of modify operations for each thread to perform. When this option is not specified, all threads will repeat the modify sequence indefinitely.
-q		Quiet output mode: the measurements for each interval will not be displayed.
none		Display the usage help text that briefly describes all options.

Randomly Generated Target Entries

To simulate real usage conditions and reduce artifacts due to the repetitive nature of the tests, the modrate tool provides a mechanism for choosing a random target entry.

Syntax

To simulate real usage conditions, the modrate tool has a mechanism for generating random numbers or random strings from an input file. To do this, specify the following placeholders in the base DN parameter on the command-line:

Substitution Rules

The tool applies the following rules for substitutions. An incorrect command-line will return a usage error:

Input File

The input file is a plain text file that contains the strings for substitution. Each line, including any whitespace, is taken to be one string. Depending on how the placeholder is used, the file may contain full or partial DNs. For example, the -b "uid=%s,ou=people,dc=example,dc=com" option could be used with the input file detailed in Code Example 14-1.

The size and contents of the file should be adapted to the directory that you are testing. Generally, the number of possible target entries should be as large as possible to ensure performance is being measured across the whole directory.

Sample Output

Code Example 14-2 is sample output that might be retreived from the modrate tool. When running, the modrate tool displays one line of measurements every interval (5 seconds by default). All data on an output line concerns only the elapsed interval. Use the -j seconds option to specify a different interval length.

Command-Line Examples

The examples in this section measure bind and modify performance in your directory server in various scenarios. Results are meaningful only if factors such as machine load and network traffic remain constant during and between tests.

In these examples, you should provide DNs for modifiable entries in your test directory. You will need to adapt these examples to your environment:

Open, Bind and Modify Rate

The following command will launch 3 threads (-t 3), each of which will repeatedly open a connection, bind with the given credentials (-D "bindDN" -w password), modify the telephonenumber attribute of the bjensen entry, unbind, and close the connection (no -u -k -K options). The new attribute value for each modification is a sequence of 10 random digits (-M telephonenumber:10:[0-9]) that simulate a telephone number. The tool will display combined results for all threads at one minute intervals (-j 60).

$ modrate -h hostname -p port -D "bindDN" -w password \
-b "uid=bjensen,ou=people,dc=example,dc=com" \
-M ’telephonenumber:10:[0-9]’ -t 3 -j 60

Adding the -u option to this command-line will test whether the directory server handles clients that don’t unbind before disconnecting.

Searches with an Input File

Because every modify operation applies to the same entry, entry caching in the directory server will influence results. In the following examples, the use of an input file containing UID strings helps provide more realistic measurements. (See Randomly Generated Target Entries for more information.)

Bind and Modify Rate

The following command will use a single thread to keep a connection open (-k) to repeatedly bind with the given credentials and perform a modify operation on an entry whose UID is randomly chosen from the inputFile. The LDAP protocol allows clients to bind multiple times without unbinding, and this test measures performance in this situation.

$ modrate -h hostname -p port -D "bindDN" -w password \
-b "uid=%s,ou=people,dc=example,dc=com" -i inputFile \
-k -M ’telephonenumber:10:[0-9]’

Modify Rate Alone

The following command will use a single thread to keep the connection and the bind open (-K) and repeatedly perform a modify operation on an entry whose UID is randomly chosen from the inputFile at each iteration. This will isolate the performance measurements of the modify operation alone.

$ modrate -h hostname -p port -D "bindDN" -w password \
-b "uid=%s,ou=people,dc=example,dc=com" -i inputFile \
-K -M ’telephonenumber:10:[0-9]’

Previous Contents Index Next
Sun ONE Directory Server Resource Kit 5.2 Tools Reference