DC_TEST(1) distcache DC_TEST(1)
NAME
dc_test - Distributed session cache testing and benchmarking tool
SYNOPSIS
dc_test -connect [options]
DESCRIPTION
dc_test runs a configurable number of session caching operations against a given network
address using the distcache(8) protocol. This is typically to verify an installation, to
help diagnose problems, and to measure latency and/or throughput. The given address could
be for an instance of dc_client or directly to a running instance of dc_server. Note that
whenever the service is running over TCP/IPv4, use of the -persistent flag is advised
because many systems will fairly quickly exhaust the limit of available file-descriptors
and stop allowing new sockets until the closed connections finish with the TIME_WAIT
state.
dc_test runs one cache operation at a time, so it provides an accurate measurement of
latency in the distcache architecture being tested. However if one wants to test the
potential throughput of the architecture when multiple cache operations occur in parallel
(and distcache tools are asynchronous to scale well in such circumstances), it makes sense
to launch multiple instances of dc_test in parallel.
dc_test attempts to verify correctness of any optimisation caching tricks in distcache
tools by creating an array of ''sessions'' in advance and then sending sending ADD, GET,
and REMOVE requests on these sessions chosen completely at random. As such, many of these
requests should fail, and dc_test will itself immediately halt with an error if any opera-
tion that should succeed fails or any operation that should fail succeeds.
OPTIONS
-connect address
This flag specifies the address dc_test should connect and send cache operation
requests to.
-progress num
Normally dc_test will remain silent while testing is in progress and will only produce
output when complete (whether it is because an error was detected or because the
required number of operations have completd). With this flag, a line of output is pro-
duced each time another num operations have been completed. This can be useful for
giving an intuitive idea of the latency in the architecture and to verify that neither
dc_test nor the tools it connects to have deadlocked.
The default value for this flag is 0, which leaves dc_test silent until it has com-
pleted.
-sessions num
This flag controls the number of sample sessions created by dc_test before testing
begins. The default value is 10.
-datamin num
-datamax num
The sessions created by dc_test during initialisation have random session IDs between
10 and 63 bytes in length, and random session data of varying length also. The mini-
mum length of the session data is set by the -datamin switch, and the maximum length
is set by the -datamax switch. The default value for -datamin is 50, and the default
for -datamax is 2100.
-timeout secs
-timevar secs
The sessions created by dc_test during initialisation have random timeouts associated
with them, so as to better probe for potential expiry-ordering bugs in a cache server.
Each session addition to a cache server must specify an expiry period after which the
cache will be automatically removed if it hasn't already been removed explicitly or
implicitly because of the FIFO behaviour of a full cache. The -timeout switch speci-
fies the average timeout for creating sessions with, and the -timevar switch specifies
the range above or below the average that session timeouts should be (randomly) chosen
from.
The default value for -timeout is 60 seconds, and the default value for -timevar is 5
seconds.
If dc_server is not running as a daemon, then it can also be useful to watch it's
behaviour after testing has finished (or in the middle of subsequent testing) because
it should automatically scroll out test sessions as their expiry period runs out. See
also the BUGS section.
-ops num
dc_test does not (yet) support running indefinitely (see the BUGS section for the pri-
mary reason), so it will run until any error has been observed or until it has suc-
cessfully performed a configurable number of operations. The -ops switch can be used
to set this number of operations.
If -ops is not supplied on the command-line, it's default value will be calculated
from the number of sessions created (which is itself controlled by -sessions). This
default is 10*(sessions^2). As the default number of sessions is 10, the default num-
ber of operations is thus 1000.
-persistent
The default behaviour of dc_test is to open and close a connection to the target
address (controlled by -connect) for every operation. This is the logical choice when
connecting to an instance of dc_client as it is the mode of operation employed by most
applications that integrate with distcache. However, it can be desirable to measure
the behaviour of the architecture when all operations are taking place over a single
established ''persistent'' connection. This is more certainly the case when connecting
directly to an instance of dc_server over TCP/IPv4, as dc_server forks a child process
for each connection and TCP/IPv4 does not react well to thousands of connections being
opened and closed in a short space of time.
Using the -persistent switch, a single connection will be opened to the target address
when dc_test initialises, and all cache operations will use this connection.
-h, -help, -?
Any of these flags will cause dc_test to display a brief usage summary to the console
and exit cleanly. Any other flags are ignored.
BUGS
dc_test will monitor each of the sessions it creates during intialisation to determine
whether it thinks it should already be present in the destination session cache or not.
Using this state, it determines whether it expects a corresponding ADD, GET, or DELETE
operation on the session to succeed or fail. GET and DELETE should fail if the session is
not supposed to be in the cache (if it has never been added or was last seen in a DELETE
operation). Likewise, ADD should fail if the session is supposed to be in the cache. None
of this logic, however, pays any attention to the expiry period in each of these sessions
and so if a long enough test is run (high value of ops or a slow architecture) and/or
short session timeouts are used, it becomes possible for this state to become incorrect
when the cache itself expires sessions that dc_test thinks should still be in the cache.
This bug should be hard to trigger even with long tests or short timeouts, because a ses-
sion needs to be added to the cache and then not DELETE'd during a long enough period that
the server gets a chance to expire it.
SEE ALSO
dc_client(1)
Distributed caching client proxy.
dc_server(1)
Distributed cache server.
dc_snoop(1)
Distcache protocol analyser and debugging tool.
distcache(8)
Overview of the distcache architecture.
http://www.distcache.org/
Distcache home page.
AUTHOR
This toolkit was designed and implemented by Geoff Thorpe for Cryptographic Appliances
Incorporated. Since the project was released into open source, it has a home page and a
project environment where development, mailing lists, and releases are organised. For
problems with the software or this man page please check for new releases at the project
web-site below, mail the users mailing list described there, or contact the author at
.
Home Page: http://www.distcache.org
1.4.5 2004.03.23 DC_TEST(1)
|