Zero-Knowledge Database Library Test Tools

$Id: zkDB_TestTools,v 1.0
2000/05/24 16:16:36 sam Exp $
Revision
|
Comments
|
1.1
|
Author(s): Sam Sanjabi (sam@zks.net),
Initial draft.
|
Contents
Introduction
dbperf
- Database Performance Test Tool
dbcreate
- Random Test Database Creation Tool
dbpopulate
- Test Database Creation from File
Appendix: zkConfig file format
1
- Introduction
Goto : [top]
This document gives an overview of the usage of some available
test tools for the Zero-Knowledge Database Library. These tools are
located in the CVS source tree at
/freedom/ndb/test/. It is assumed that the reader has some
knowledge of the zkDB API. Documentation of the API can also be found
in the source tree at /freedom/ndb/doc/zkdbAPI.html.
2
- dbperf: Database Performance Test Tool
Goto: [top]
SYNOPSIS
dbperf
|
[--help] [--config file] [--database
file] [--iteration int] [--maxKey int] [--keySize
int] [--recordSize int] [--process int]
[--multiOpen] [--operation string]
|
A
more detailed description of the functionality of these options
follows below.
DESCRIPTION
dbperf is a tool to test the performance of the zkDB
database library by assigning a number of processes to perform a set
of operations on the database many times. For example the user can
instruct dbperf to generate 20 child processes that will
each perform 300 updates on a given database. Upon completion of
these processes, dbperf reports the total real, user, and
system time used, as well as the average number of queries per second
performed by the database. If the performed operation was specified
as a fetch, dbperf also reports the number
of successfully found records.
OPTIONS
- --help
-
Displays the usage information and a short summary of each option to
stdout.
-
--config file
-
Allows the user to specify a configuration file (not the database
config file, but one used by dbperf directly) to load the
parameters instead of using the command line. The format of this
config file is as that specified by zkConfig. I've included
a description of this format below.
-
--database file
-
Specifies the database to test, where file is the name of
the Zero-Knowledge Database Configuration File associated with the
desired database. To learn more about database configuration go see
the docs at
http://caesar.zks.net/devnet/cvs/freedom/ndb/doc/zkdb-conf.html.
-
--iteration int
-
Specifies the number of times each child process performs the
operation(s) requested using the operation option. The
default value is 1000. Also, if the maxKey option is not
specified, this also sets the maximum key value to use in database
queries.
-
--maxKey int
-
Specifies the maximum key value to use in database queries. If this
option isn't explicitly specified, the maximum key value becomes the
same as the number of iterations undergone by each process (as
specified by the iteration option above).
-
--keySize int
-
Specifies the size of the keys (in bytes) generated randomly to
query the database. The default value is 64, and the keys must
be at least 12 bytes long.
-
--recordSize int
-
Specifies the size of the records (in bytes) generated to insert
into the database. By record we mean the data part of the
key/data pair stored by the databases. The default value is
64.
-
--process int
-
Specifies the number of child processes that will each do the
operation(s) requested by the operation option the required
number of times (as requested by the iteration option).
-
--multiOpen
-
If this option is specified, dbperf will open and close the
database interaction (using zkDB_Open and zkDB_close)
between each operation performed by the child processes. If this
option isn't specified, then the database interaction is opened once
for each child process and closed once when the process has
completed all the iterations it was was supposed to. Note that if
operation is set to sequence, then it is the
user's responsibility to request open and close operations himself
(this will not be done automatically in multiOpen mode).
-
--operation string
-
Specify the operation to perform (fetch, update, delete or
sequence). In case of a sequence, the expected format is --operation
seq:string where string contains the operations to
be performed. For example, --operation seq:ufdu describes a sequence
of update, fetch, delete and update. When used in multiple open
mode, the database open and close operations must be specified
expilictly (example: "odcofudc"). The possible values for
string are summarized in the following table:
string value (as regexp)
|
Function Behaviour
|
fetch
|
child process fetches random records from the database
|
update
|
child process updates random records in the database
|
delete
|
child process deletes random records from the database
|
seq:[o|c|f|u|d]*
|
child process performs sequence of operation defined by the
string of characters that follow "seq:" where:
o denotes opening the
interaction with the database
c denotes closing the
interaction with the database
f denotes fetching a
record from the database
u denotes updating a
record in the database
d denotes deleteing a record from the database
|
FILES
- Database Configuration File
-
Configuration file used to specify the desired test database. The
format for this file is available at
http://caesar.zks.net/devnet/cvs/freedom/ndb/doc/zkdb-conf.html.
-
Parameter Configuration File
-
As stated above, the parameters for the performance test can also be
specified using a configuration file of the format specified by
zkConfig (see the appendix for a
description of this format).
EXAMPLES
40 Processes doing 1500 updates with 64 byte keys and 80 byte
records in single-open mode would be initiated by:
%% dbperf --database testdb.conf --iteration 1500 --recordSize 80
--process 40 --operation update
75 processes doing a sequence of
open,delete,fetch,update,update,close 700 times with default sized
keys and records in multi-open mode would be initiated by:
%% dbperf --database testdb.conf --iteration 700
--multiOpen --operation seq:odfuuc
20 processes each doing 3000 updates in multi-open mode would
be initiated by:
%% dbperf --database testdb.conf --iteration 3000
--multiOpen --operation update
Note that the same functionality could be achieved with the sequence
notation as follows:
%% dbperf --database testdb.conf --iteration 3000
--multiOpen --operation seq:ouc
Observe that in order to use the sequence notation, the user had to
explicitly open and close the database interaction himself. If the
'o' and the 'c' had been left out of the operation, the underlying
zkDB interface would have returned an error. In single open
mode, the opening and closing of the database is handled
automatically.
3
- dbcreate: Random Test Database Creation Tool
Goto: [top]
SYNOPSIS
dbcreate
|
[--help] [--config file] [--database
file] [--size int] [--keySize int] [--recordSize
int] [--scan] [--verbose]
|
DESCRIPTION
dbcreate performs one of two functions:
Filling in a database with a
number of records so that it can be tested
Scanning a database in order to find the number of records in
it
Using the options, the user can specify how many records are to be
filled and how large the key and data fields of these records should
be.
OPTIONS
- --help
-
Displays the usage information and a short summary of each option to
stdout.
-
--config file
-
Allows the user to specify a configuration file (not the database
config file, but one used by dbperf directly) to load the
parameters instead of using the command line. The format of this
config file is as that specified by zkConfig. I've included
a description of this format below.
-
--database file
-
Specifies the database to test, where file is the name of
the Zero-Knowledge Database Configuration File associated with the
desired database. To learn more about database configuration go see
the docs at
http://caesar.zks.net/devnet/cvs/freedom/ndb/doc/zkdb-conf.html.
-
--size int
-
Specifies the number of records to be filled into the test database
when that is the required function. If scan option is
enabled, this parameter is ignored.
-
--keySize int
-
Specifies the size of the keys (in bytes) generated to insert into
the database. The default value is 64, and the keys must be
at least 12 bytes long.
-
--recordSize int
-
Specifies the size of the records (in bytes) generated to insert
into the database. By record we mean the data part of the
key/data pair stored by the databases. The default value is
64.
-
--scan
-
If this option is enabled, dbcreate will not insert any
records into the database at all. It will simply scan the entire
database and report the number of records stored in it to stdout.
If the verbose option is used, dbcreate will also
print each key/data pair it encounters to stdout as it
scans.
-
--verbose
-
Set this option to get dbcreate to report more information
about what it is doing. If the scan option is active, it
will report each encountered key/data pair in the database.
Otherwise (if we are filling in the database with records), the
program will report its percentage completion to stdout
FILES
- Database Configuration File
-
Configuration file used to specify the desired test database. The
format for this file is available at
http://caesar.zks.net/devnet/cvs/freedom/ndb/doc/zkdb-conf.html.
-
Parameter Configuration File
-
As stated above, the parameters for the performance test can also be
specified using a configuration file of the format specified by
zkConfig (see the appendix for a
description of this format).
EXAMPLES
Inserting 900 records into the database specified by
"testdb.conf" with 32 byte keys and 80 byte records.
%% dbcreate --database testdb.conf --size 900 --keySize 32
--recordSize 80
List the records in the database and report their number
%% dbperf --database testdb.conf --scan --verbose
4
- dbpopulate: Test Database Creation from File
Goto: [top]
SYNOPSIS
dbpopulate
|
[--help] [--config file] [--database
file] [--size int] [--startKey int] [--keySize
int] [--recordSize int] [--source file] [--scan]
[--fetch] [--output file] [--verbose]
|
DESCRIPTION
dbpopulate performs the same function as dbcreate,
but reads and outputs database record to and from files.
OPTIONS
- --help
-
Displays this information
-
-
--config <filename>
-
Specify which configuration file you wish to use (you can specify a
configuration file in which the other parameters can be specified).
-
-
--database <filename>
-
Name and location of the database configuration file.
-
-
--size <int>
-
Number of entries to add to database (default 1000).
-
-
--startKey <int>
-
Key number to use first key for the numbering sequence (default 1).
-
-
--keySize <int>
-
Specifies the key size (default 64 bytes). Minimum key size is 12
bytes.
-
-
--recordSize <int>
-
Specifies the record size (default 64 bytes).
-
-
--scan
-
Scan the database with a cursor and dump the records to an output
file. Reports number of records found. Can't be set if --fetch
is set.
-
-
--fetch
-
Do an ordered fetch of all records in the database one by one, and
dump them to the output file. Can't be set if --scan
is set.
-
-
--source <filename>
-
Populate database from the source file.
-
-
--output <filename>
-
Write data from the scan or fetch operations to the file
-
-
--verbose
-
Toggle verbosity on/off. The verbosity can also be toggled by
sending the SIGUSR1 signal to a running dbpopulate process.
FILES
- Database Configuration File
-
Configuration file used to specify the desired test database. The
format for this file is available at
http://caesar.zks.net/devnet/cvs/freedom/ndb/doc/zkdb-conf.html.
-
Parameter Configuration File
-
As stated above, the parameters for the performance test can also be
specified using a configuration file of the format specified by
zkConfig (see the appendix for a
description of this format).
EXAMPLES
Inserting 1000 records into the database specified by
"testdb.conf" from the file "testdb.src" with 32
byte keys and 80 byte records.
%% dbpopulate --database testdb.conf --size 1000 --keySize 32
--recordSize 80 --source testdb.src
Dump the records in order of increasing keys to "testdb.out"
%% dbpopulate --database testdb.conf --fetch --output testdb.out --verbose
5
- Appendix: zkConfig file format
Goto: [top]
The zkConfig file format is the same as that of a windows
.INI file. To save you the trouble of going out and figuring
out what that is, I will present the format of this file here. The
file is split into sections demarkated by [SECTION_NAME],
with each section containing parameter/value pairs. Lines whose first
non-white space character is a ';' are considered comment lines. Here
is the general format:
; Comment line
[SECTION_NAME_1]
PARM_NAME_11 = PARM_VALUE_11
PARM_NAME_12 = PARM_VALUE_12
...
PARM_NAME_1n = PARM_VALUE_1n
[SECTION_NAME_2]
PARM_NAME_21 = PARM_VALUE_21
PARM_NAME_22 = PARM_VALUE_22
...
PARM_NAME_2n = PARM_VALUE_2n
. . .
[SECTION_NAME_m]
PARM_NAME_m1 = PARM_VALUE_m1
PARM_NAME_m2 = PARM_VALUE_m2
...
PARM_NAME_mn = PARM_VALUE_mn
In the case of these tools (dbperf say), section names are
omitted since there is only one. For example, a configuration file that
would run dbperf on database "testdb"
in multiOpen mode with 20 child processes each doing 300 fetches with
128 byte keys would be:
; Filename: configtest.conf
; Filetype: dbperf configuration file
database = "testdb.conf"
iteration = 300
keySize = 128
process = 20
multiOpen = 1
operation = fetch
and the operation would be invoked with the command line dbperf
--config configtest.conf.