Chapter 13 The Search Performance Measurement Tool

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

Overview

The searchrate tool measures the performance of search operations in an LDAP v3 directory. The DSRK and its updates include the latest version of the tool in the DSRK_base/bin/dsrk52 directory. Unlike the rsearch tool described in Chapter 12, it performs searches only.


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 searchrate tool simulates a search load on a directory server. Each thread performs LDAP bind and search operations repeatedly as quickly as possible, and the tool displays average results at regular intervals. The command-line options let you configure the binding sequence and the scope of the searches. The searchrate tool has the following built-in defaults:

In general, when the searchrate tool encounters an error, it displays a message and continues running. It will attempt to bind again or search again indefinitely, even after encountering an error.

Syntax

Options

The searchrate options and parameters are described in Table 13-1. Running the searchrate command on the command-line without any options or parameters will display the usage help text that briefly describes all options.

Table 13-1 Command-Line Options for searchrate
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 access permissions, the bind DN may influence authentication and search performance. If the bind DN and its password are omitted, the tool will perform search operations without binding (as permitted by LDAP v3). For anonymous binding, you must explicitly specify an empty bind DN and password (-D "" -w "").
-w	password	Specify the password for the bind DN.
-b	baseDN	Specify the base DN for the search operations, usually in double quotes ("") for the shell. See Randomly Generated Numbers on how to use %s or %d placeholders for including random strings or numbers with the -i or -r options, respectively.
-s	scope	Specify the scope of a search with one of the following values: base - For searching only the base entry. one - For searching one level below the base entry. sub - For searching all levels below the entry. This is the default.
-f	filter	Specify the filter for all search operations. See Randomly Generated Numbers on how to use %s or %d placeholders for including random strings or numbers with the -i or -r options, respectively.
-g	seconds	Specify the time limit in seconds for each search operation. The default is 10 seconds. You may need to set the limit higher if you specify a broad search, such as (cn=*) over a large directory.
-i	inputFile	Give the name of the file containing strings that will be randomly substituted into %s placeholders in the base DN and filter. Each line of an input file is treated as a separate string. Use this option as many times as you have %s placeholders in the filter. See Randomly Generated Numbers for more information.
-r	maxRand	Give the maximum range for random numbers to be substituted into %d placeholders in the base DN and filter. 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 Numbers for more information.
-A	attribute	Specify an attribute to be retrieved during search operations. You may use this option any number of times on the command-line: only the specified attributes will be retrieved. When omitted, all searches will return all attributes for all matching entries. Whether or not this attribute is used, no attribute values are ever displayed. However, retrieving different attributes may influence search performance.
-k		Keep connections open between searches. With this option, the searchrate tool will measure only the execution time of the bind and search operations. When this option is omitted, the initialization and freeing of the connection are also measured as part of each search sequence.
-K		Keep connections and binds open between searches. With this option, the searchrate tool will measure only the execution time of the search operation. When this option is omitted, the initialization, binding, unbinding, and freeing of the connection is also measured as part of each search sequence.
-u		When used with the -D -w options, specify that the tool should not unbind from the sever, just close the socket for the connection. This option has no effect when either -k or -K options are specified.
-a		Specify asynchronous search mode. With this option, the searchrate tool will not wait for search results before starting the next search. As a result, performance measurements will reflect searchrate execution speed, not directory server search speed. This option cannot be used when the -D and -w options are given.
-t	threads	Specify the number of threads that searchrate 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. searchrate repeats the search sequence as many times as possible during the interval and prints results after each interval elapses.
-m	searchOps	Specify the maximum, cumulated number of search operations for each thread to perform. When this option is not specified, all threads will repeat the search 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 Numbers

One concern for accurate performance measurements is to simulate real usage conditions and reduce any artifacts due to the repetitive nature of the tests. For example, when the same entry is retrieved for every search, it will be cached by the directory server and returned without performing a full search. Under normal usage conditions, only a certain percentage of searches will be resolved quickly through the entry cache, so the test results will be skewed.

Syntax

To simulate real usage conditions, the searchrate tool has a mechanism for randomizing both the base DN and the search filter used for each search. Both the base DN and filter strings may use the following syntax:

To include either randomly generated numbers or random strings from an input file, specify the following placeholders in the base DN, in the filter parameters, or in both 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. File contents should be adapted to the intended substitutions: either in the base DN, in the search filter, or in both. For example, the following input file could be used with the option -f "sn%s" for performing different searches on surnames:

The size and contents of the file should be adapted to the directory that you are testing. Generally, the type and number of different searches that can be chosen randomly from the input file should resemble the expected usage of your directory. For example, to test the performance of complex searches, use several input files with a compound filter string such as "(|(cn=%s)(cn=%s))".

Sample Output

Code Example 13-1 is sample output that might be retreived from the searchrate tool. When running, the searchrate 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 will measure bind and search performance in your directory server in various scenarios. Results will be meaningful only if factors such as machine load and network traffic remain constant during and between tests.

In these examples, you will need to provide the base DN and filter strings for valid entries in your test directory. You will also need to adapt them to your environment:

Simple Search

$ searchrate -h hostname -p port -b "dc=example,dc=com" \
-f "cn=*john*" -t 3 -j 60

This command will launch 3 threads (-t 3), each of which will repeatedly open a connection(but not bind), search for entries under the "dc=example,dc=com" suffix that contain the "cn=*john*" substring, and close the connection (no -D -w -k -K options). The tool will display combined results for all threads at one minute intervals (-j 60).

Search Using an Input File

Because every search uses the same filter and returns the same entries, entry caching in the directory server will influence results. In all of the following examples, the use of an input file containing filter strings helps provide more realistic measurements. During each iteration, the tool will search for a different, random surname taken from the input file such as the one in Randomly Generated Numbers (-f "sn%s" -i inputFile).

Open, Bind, and Search Rate


Note	Input files might also contain different kinds of filter strings that could give different performance results: Strings containing wildcards will give measurements that reflect substring search speed. Strings without wildcards will give measurements that reflect the search speed for exact matches. Filter strings may also include operators other than equality, such as ranges that are greater than (>=) or less than (<=) a given value, or approximate spelling searches (~=).

This first command will use a single thread to repeatedly open a connection, bind with the given credentials (-D "bindDN" -w password), perform a search under the "dc=example,dc=com" suffix and then unbind. The unbinding operation also closes the connection.

$ searchrate -h hostname -p port -b "dc=example,dc=com" \
-D "bindDN" -w password -f "sn%s" -i inputFile

This second command is similar to the previous one, except that at each iteration, the connection and binding will simply be dropped by closing the socket (-u). This behavior is allowed by the LDAP protocol, and this test verifies that connections that are not unbound are properly handled by the directory server.

$ searchrate -h hostname -p port -b "dc=example,dc=com" \
-D "bindDN" -w password -u -f "sn%s" -i inputFile

Bind and Search Rate


Note	Both of the commands may also use anonymous binding (-D "" -w "") that may give different performance results due to handling anonymous access permissions.

This command will use a single thread to keep a connection open (-k) to repeatedly bind with the given credentials and perform a search under the "dc=example,dc=com" suffix. The LDAP protocol allows clients to bind multiple times without unbinding, and this test measures performance in this situation.

$ searchrate -h hostname -p port -b "dc=example,dc=com" \
-D "bindDN" -w password -k -f "sn%s" -i inputFile

Search Rate Alone


Note	You may also use anonymous binding (-D "" -w "") to test the performance results using anonymous access.

This command will use a single thread to keep the connection and the bind open (-K) and repeatedly perform a search under the "dc=example,dc=com" suffix. This will isolate the performance measurements of the search operation alone. You may also use anonymous binding (-D "" -w "") to test the performance results using anonymous access.

$ searchrate -h hostname -p port -b "dc=example,dc=com" \
-D "bindDN" -w password -K -f "sn%s" -i inputFile

In this command, the single thread will only open a connection without binding (-k but no -D -w) and repeatedly perform search operations. Unbound search operations are allowed by the LDAP v3 protocol, and this test isolates the performance of the search operation alone in this situation.

$ searchrate -h hostname -p port -b "dc=example,dc=com" \
-k -f "sn%s" -i inputFile

Complex Searches

Searches that use compound filters having multiple terms are common and take longer to perform. To create realistic tests of complex search performance, use several placeholders in the filter string and specify multiple input files.

$ searchrate -h hostname -p port -b "dc=example,dc=com" \
-k -f "(|(cn=%s)(cn=%s)))" -i cnFile -i cnFile

Note that you must specify as many -i options as %s placeholders, even if the input filename is the same for both.

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