1DC_TEST(1) distcache DC_TEST(1)
2
6 dc_test - Distributed session cache testing and benchmarking tool
7
9 dc_test -connect <addr> [options]
10
12 dc_test runs a configurable number of session caching operations
13 against a given network address using the distcache(8) protocol. This
14 is typically to verify an installation, to help diagnose problems, and
15 to measure latency and/or throughput. The given address could be for an
16 instance of dc_client or directly to a running instance of dc_server.
17 Note that whenever the service is running over TCP/IPv4, use of the
18 -persistent flag is advised because many systems will fairly quickly
19 exhaust the limit of available file-descriptors and stop allowing new
20 sockets until the closed connections finish with the TIME_WAIT state.
21 dc_test runs one cache operation at a time, so it provides an accurate
23 measurement of latency in the distcache architecture being tested. How‐
24 ever if one wants to test the potential throughput of the architecture
25 when multiple cache operations occur in parallel (and distcache tools
26 are asynchronous to scale well in such circumstances), it makes sense
27 to launch multiple instances of dc_test in parallel.
28 dc_test attempts to verify correctness of any optimisation caching
30 tricks in distcache tools by creating an array of ``sessions'' in
31 advance and then sending sending ADD, GET, and REMOVE requests on these
32 sessions chosen completely at random. As such, many of these requests
33 should fail, and dc_test will itself immediately halt with an error if
34 any operation that should succeed fails or any operation that should
35 fail succeeds.
36
38 -connect address
39 This flag specifies the address dc_test should connect and send
40 cache operation requests to.
41 -progress num
43 Normally dc_test will remain silent while testing is in progress
44 and will only produce output when complete (whether it is because
45 an error was detected or because the required number of operations
46 have completd). With this flag, a line of output is produced each
47 time another num operations have been completed. This can be useful
48 for giving an intuitive idea of the latency in the architecture and
49 to verify that neither dc_test nor the tools it connects to have
50 deadlocked.
51 The default value for this flag is 0, which leaves dc_test silent
53 until it has completed.
54 -sessions num
56 This flag controls the number of sample sessions created by dc_test
57 before testing begins. The default value is 10.
58 -datamin num
60 -datamax num
61 The sessions created by dc_test during initialisation have random
62 session IDs between 10 and 63 bytes in length, and random session
63 data of varying length also. The minimum length of the session
64 data is set by the -datamin switch, and the maximum length is set
65 by the -datamax switch. The default value for -datamin is 50, and
66 the default for -datamax is 2100.
67 -timeout secs
69 -timevar secs
70 The sessions created by dc_test during initialisation have random
71 timeouts associated with them, so as to better probe for potential
72 expiry-ordering bugs in a cache server. Each session addition to a
73 cache server must specify an expiry period after which the cache
74 will be automatically removed if it hasn't already been removed
75 explicitly or implicitly because of the FIFO behaviour of a full
76 cache. The -timeout switch specifies the average timeout for creat‐
77 ing sessions with, and the -timevar switch specifies the range
78 above or below the average that session timeouts should be (ran‐
79 domly) chosen from.
80 The default value for -timeout is 60 seconds, and the default value
82 for -timevar is 5 seconds.
83 If dc_server is not running as a daemon, then it can also be useful
85 to watch it's behaviour after testing has finished (or in the mid‐
86 dle of subsequent testing) because it should automatically scroll
87 out test sessions as their expiry period runs out. See also the
88 BUGS section.
89 -ops num
91 dc_test does not (yet) support running indefinitely (see the BUGS
92 section for the primary reason), so it will run until any error has
93 been observed or until it has successfully performed a configurable
94 number of operations. The -ops switch can be used to set this num‐
95 ber of operations.
96 If -ops is not supplied on the command-line, it's default value
98 will be calculated from the number of sessions created (which is
99 itself controlled by -sessions). This default is 10*(sessions^2).
100 As the default number of sessions is 10, the default number of
101 operations is thus 1000.
102 -persistent
104 The default behaviour of dc_test is to open and close a connection
105 to the target address (controlled by -connect) for every operation.
106 This is the logical choice when connecting to an instance of
107 dc_client as it is the mode of operation employed by most applica‐
108 tions that integrate with distcache. However, it can be desirable
109 to measure the behaviour of the architecture when all operations
110 are taking place over a single established ``persistent'' connec‐
111 tion. This is more certainly the case when connecting directly to
112 an instance of dc_server over TCP/IPv4, as dc_server forks a child
113 process for each connection and TCP/IPv4 does not react well to
114 thousands of connections being opened and closed in a short space
115 of time.
116 Using the -persistent switch, a single connection will be opened to
118 the target address when dc_test initialises, and all cache opera‐
119 tions will use this connection.
120 -h, -help, -?
122 Any of these flags will cause dc_test to display a brief usage sum‐
123 mary to the console and exit cleanly. Any other flags are ignored.
124
126 dc_test will monitor each of the sessions it creates during intialisa‐
127 tion to determine whether it thinks it should already be present in the
128 destination session cache or not. Using this state, it determines
129 whether it expects a corresponding ADD, GET, or DELETE operation on the
130 session to succeed or fail. GET and DELETE should fail if the session
131 is not supposed to be in the cache (if it has never been added or was
132 last seen in a DELETE operation). Likewise, ADD should fail if the ses‐
133 sion is supposed to be in the cache. None of this logic, however, pays
134 any attention to the expiry period in each of these sessions and so if
135 a long enough test is run (high value of ops or a slow architecture)
136 and/or short session timeouts are used, it becomes possible for this
137 state to become incorrect when the cache itself expires sessions that
138 dc_test thinks should still be in the cache. This bug should be hard to
139 trigger even with long tests or short timeouts, because a session needs
140 to be added to the cache and then not DELETE'd during a long enough
141 period that the server gets a chance to expire it.
142
144 dc_client(1)
145 Distributed caching client proxy.
146 dc_server(1)
148 Distributed cache server.
149 dc_snoop(1)
151 Distcache protocol analyser and debugging tool.
152 distcache(8)
154 Overview of the distcache architecture.
155 http://www.distcache.org/
157 Distcache home page.
158
160 This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
161 graphic Appliances Incorporated. Since the project was released into
162 open source, it has a home page and a project environment where devel‐
163 opment, mailing lists, and releases are organised. For problems with
164 the software or this man page please check for new releases at the
165 project web-site below, mail the users mailing list described there, or
166 contact the author at geoff@geoffthorpe.net.
167 Home Page: http://www.distcache.org
1691.4.5 2004.03.23 DC_TEST(1)