Previous     Contents     Index     Next     
iPlanet Directory Server Resource Kit 5.1 Tools Reference



Chapter 11   searchrate


The searchrate tool measures the performance of search operations in an LDAP v3 directory. It is similar to the rsearch tool described previously, except that it performs searches only.

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 8 "idsktune").

This chapter contains the following sections:



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:

  • All operations use the LDAP v3 protocol. The tool cannot be used to test directories that only support LDAP v2.

  • The tool uses simple or anonymous binding. No secure binding is possible.

  • Referrals are never followed.

  • The time and size limits for search results are not modifiable. The default time limit for a synchronous search is 10 seconds. All other default values are those defined by the directory server.

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

The searchrate command has the following syntax:

searchrate -b "baseDN " -f "filter " [ options ]

Where:

Both the base DN and filter strings may use the following syntax (see "Random Searches"):

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

    • %s to include random strings from the files given by the -i option.

Running the searchrate command without any options or parameters will display the usage help text that briefly describes all options.


Options

The searchrate options and parameters are described in the following table.


Table 11-1    Command-Line Options for the searchrate Tool 

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 "Random Searches" 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 "Random Searches" 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 "Random Searches" 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 ].  

-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.  


Random Searches

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.

To simulate real usage conditions, the searchrate tool includes a mechanism for randomizing both the base DN and the search filter used for each search. You can include either randomly generated numbers or random strings from an input file. To do this, specify the following placeholders in the base DN, in the filter parameters, or in both on the command line:

  • The first occurrence of %d will be replaced by a random number in the range [0, maxRand1 -1], where maxRand1 is given by the first occurrence of the -r option on the command line.

  • The second occurrence of %d will be replaced by a random number in the range [1, maxRand2 ], where maxRand2 is given by the second occurrence of the -r option on the command line.

  • The %s placeholders will be replaced by a random string from the input files given by -i options. The first placeholder in each of the base DN and the filter will be replaced by a random string from the input file specified by the first -i option, the second placeholder in each by a random string from the second file, and so on. Each line of an input file is treated as a complete string.

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

  • You must specify at least as many -r options as %d placeholders you use, and as many -i options as %s placeholders.

  • Placeholder substitution will occur only in the base DN and search filter parameters. To use the literal strings "%d" and "%s" within these parameters, you must use "%%d" and "%%s", respectively.

  • Within a DN or filter, you may use only one type of placeholder. However, each parameter may use a different type.

  • When both parameters specify the same type of placeholder, the same value or values will be substituted in both for a given search.

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:

=C*
=Jones
=Smith
>=Jones
<=Jones
~=Turner

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



$ searchrate -h hostname -b "dc=siroe,dc=com" -f "cn=a*" -t 4

Avg r= 74.75/thr ( 59.80/sec), total= 299
Avg r= 76.00/thr ( 60.80/sec), total= 304
Avg r= 74.50/thr ( 59.60/sec), total= 298
Avg r= 56.00/thr ( 44.80/sec), total= 224
Avg r= 73.50/thr ( 58.80/sec), total= 294
Avg r= 75.25/thr ( 60.20/sec), total= 301
^C

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. Reading an output line backwards, it shows:

  • The total number of search operations completed by all threads during the full interval.

  • The rate in parentheses is the average number of searches per second for all threads (the total divided by the number of seconds in the interval).

  • The given Avg is the average number of operations per thread during the interval (the total divided by the number of threads).



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 need to adapt these examples to your environment:

  • The hostname and port placeholders should be replaced with the hostname and port number of your directory. The baseDN should represent the root of the directory or subtree you wish to test.

  • For realistic results, thread numbers and time limit options should be scaled according to your directory's expected load.

  • You will also need to provide input files that correspond to the contents of your directory (see "Random Searches").

Input files may also contain different kinds of filter strings that may 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 (~=).


Simple Search

$ searchrate -h hostname -p port -b "dc=Siroe,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=Siroe,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).

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.


Open, Bind, and Search Rate

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

This 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=Siroe,dc=com" suffix and then unbind. The unbinding operation also closes the connection. During each iteration, the tool will search for a different, random surname taken from the input file such as the one in "Random Searches" (-f "sn%s" -i inputFile ).

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

This 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.

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


Bind and Search Rate

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

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=Siroe,dc=com" suffix. The LDAP protocol allows clients to bind multiple times without unbinding, and this test measures performance in this situation.

During each iteration, the tool will search for a different, random surname taken from the input file such as the one in "Random Searches" (-f "sn%s" -i inputFile ). You may also use anonymous binding (-D "" -w "") to test the performance results using anonymous access.


Search Rate Alone

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

This command will use a single thread to keep the connection and the bind open (-K) and repeatedly perform a search under the "dc=Siroe,dc=com" suffix. During each iteration, the tool will search for a different, random surname taken from the input file such as the one in "Random Searches" (-f "sn=%s" -i inputFile ). 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=Siroe,dc=com" \
             -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.


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=Siroe,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     
Copyright 2002 Sun Microsystems, Inc.. All rights reserved.

Last Updated April 15, 2002