1CBC-PILLOWFIGHT(1) CBC-PILLOWFIGHT(1)
2
6 cbc-pillowfight - Stress Test for Couchbase Client and Cluster
7
9 cbc-pillowfight [OPTIONS]
10
12 cbc-pillowfight creates a specified number of threads each looping and
13 performing get and set operations within the cluster.
14 The stress test operates in the following order
16 1. It will pre-load the items in the cluster (set by the --num-items
18 option)
19 2. Once the items are all loaded into the cluster, it will access all
21 the items (within the --num-items) specification, using a combina‐
22 tion of storage and retrieval operations (the proportion of
23 retrieval and storage operations are controlled via the --set-pct
24 option).
25 3. Operations are scheduled in batches. The batches represent a single
27 pipeline (or network buffer) which is filled with a certain amount
28 of operations (see the --batch-size option). These batch sizes are
29 then sent over to the cluster and the requests are serviced by it.
30 Tuning
34 Getting the right benchmark numbers highly depends on the type of envi‐
35 ronment the client is being run in. The following provides some infor‐
36 mation about specific settings which may make pillowfight generate more
37 operations.
38 · Increasing the batch size will typically speed up operations, but
40 increasing the batch size too much will actually slow it down.
41 Additionally, very high batch sizes will cause high memory usage.
42 · Adding additional threads will create additional client objects and
44 connections, potentially increasing performance. Adding too many
45 threads will cause local and network resource congestion.
46 · Decreasing the item sizes (the --min-size and --max-size options)
48 will always yield higher performance in terms of opera‐
49 tiond-per-second.
50 · Limiting the working set (i.e. --num-items) will decrease the work‐
52 ing set within the cluster, thereby increasing the chance that a
53 given item will be inside the server´s CPU cache (which is
54 extremely fast), rather than in main memory (slower), or disk (much
55 slower)
56 The benchmark tool sets up SIGQUIT (CTRL-/) handler and dumps useful
60 diagnostics and metrics to STDERR on this signal.
61
63 Options may be read either from the command line, or from a configura‐
64 tion file (see cbcrc(4)):
65 The following options control workload generation:
67 -B, --batch-size=BATCHSIZE
69 This controls how many commands are scheduled per cycles. To
70 simulate one operation at a time, set this value to 1.
71 -I, --num-items=NUMITEMS
73 Set the total number of items the workload will access within
74 the cluster. This will also determine the working set size at
75 the server and may affect disk latencies if set to a high num‐
76 ber.
77 -p, --key-prefix=PREFIX
79 Set the prefix to prepend to all keys in the cluster. Useful if
80 you do not wish the items to conflict with existing data.
81 -t, --num-threads=NTHREADS
83 Set the number of threads (and thus the number of client
84 instances) to run concurrently. Each thread is assigned its own
85 client object.
86 -r, --set-pct=PERCENTAGE
88 The percentage of operations which should be mutations. A value
89 of 100 means only mutations while a value of 0 means only
90 retrievals.
91 -n, --no-population
93 By default cbc-pillowfight will load all the items (see
94 --num-items) into the cluster and then begin performing the nor‐
95 mal workload. Specifying this option bypasses this stage. Useful
96 if the items have already been loaded in a previous run.
97 --populate-only
99 Stop after population. Useful to populate buckets with large
100 amounts of data.
101 -m, --min-size=MINSIZE:
103 -M, --max-size=MAXSIZE
106 Specify the minimum and maximum value sizes to be stored into
107 the cluster. This is typically a range, in which case each value
108 generated will be between --min-size and --max-size bytes.
109 -E, --pause-at-end
111 When the workload completes, do not exit immediately, but wait
112 for user input. This is helpful for analyzing open socket con‐
113 nections and state.
114 -c, --num-cycles
116 Specify the number of times the workload should cycle. During
117 each cycle an amount of --batch-size operations are executed.
118 Setting this to -1 will cause the workload to run infinitely.
119 --sequential
121 Specify that the access pattern should be done in a sequential
122 manner. This is useful for bulk-loading many documents in a sin‐
123 gle server.
124 --start-at
126 This specifies the starting offset for the items. The items by
127 default are generated with the key prefix (--key-prefix) up to
128 the number of items (--num-items). The --start-at value will
129 increase the lower limit of the items. This is useful to resume
130 a previously cancelled load operation.
131 -T, --timings
133 Enabled timing recorded. Timing histogram will be dumped to
134 STDERR on SIGQUIT (CTRL-/). When specified second time, it will
135 dump a histogram of command timings and latencies to the screen
136 every second.
137 -e, --expiry=SECONDS
139 Set the expiration time on the document for SECONDS when per‐
140 forming each operation. Note that setting this too low may cause
141 not-found errors to appear on the screen.
142 -U, --spec=SPEC
144 A string describing the cluster to connect to. The string is in
145 a URI-like syntax, and may also contain other options. See the
146 EXAMPLES section for information. Typically such a URI will look
147 like couchbase://host1,host2,host3/bucket.
148 The default for this option is couchbase://localhost/default
150 -u, --username=USERNAME
152 Specify the username for the bucket. Since Couchbase 5.x this is
153 mandatory switch, and it must specify the name of the user
154 exisiting on cluster (read more at "Security/Authorization" sec‐
155 tion of the server manual). For older servers this field should
156 be either left empty or set to the name of the bucket itself.
157 -P, --password=PASSWORD:
159 -P -, --password=-
162 Specify the password for the bucket. As for servers before 5.x
163 this was only needed if the bucket is protected with a password.
164 For cluster version after 5.x, the password is mandatory, and
165 should match the selected account (read more at "Security/Autho‐
166 rization" section of the server manual).
167 Specifying the - as the password indicates that the program
169 should prompt for the password. You may also specify the pass‐
170 word on the commandline, directly, but is insecure as command
171 line arguments are visible via commands such as ps.
172 -T, --timings
174 Dump command timings at the end of execution. This will display
175 a histogram showing the latencies for the commands executed.
176 -v, --verbose
178 Specify more information to standard error about what the client
179 is doing. You may specify this option multiple times for
180 increased output detail.
181 -D, --cparam=OPTION=VALUE
183 Provide additional client options. Acceptable options can also
184 be placed in the connection string, however this option is pro‐
185 vided as a convenience. This option may be specified multiple
186 times, each time specifying a key=value pair (for example, -Dop‐
187 eration_timeout=10 -Dconfig_cache=/foo/bar/baz). See ADDITIONAL
188 OPTIONS for more information
189 -y, --compress
191 Enable compressing of documents. When the library is compiled
192 with compression support, this option will enable Snappy com‐
193 pression for outgoing data. Incoming compressed data handled
194 automatically regardless of this option. Note, that because the
195 compression support have to be negotiated with the server, first
196 packets might be sent uncompressed even when this switch was
197 specified. This is because the library might queue data commands
198 before socket connection has been established, and the library
199 will negotiate compression feature. If it is known that all
200 server support compression repeating the switch (like -yy) will
201 force compression for all outgoing mutations, even scheduled
202 before establishing connection.
203 --truststorepath=PATH
205 The path to the server´s SSL certificate. This is typically
206 required for SSL connectivity unless the certificate has already
207 been added to the OpenSSL installation on the system (only
208 applicable with couchbases:// scheme)
209 --certpath=PATH
211 The path to the server´s SSL certificate. This is typically
212 required for SSL connectivity unless the certificate has already
213 been added to the OpenSSL installation on the system (only
214 applicable with couchbases:// scheme). This also should contain
215 client certificate when certificate authentication used, and in
216 this case other public certificates could be extracted into
217 truststorepath chain.
218 --keypath=PATH
220 The path to the client SSL private key. This is typically
221 required for SSL client certificate authentication. The certifi‐
222 cate itself have to go first in chain specified by certpath
223 (only applicable with couchbases:// scheme)
224 --dump Dump verbose internal state after operations are done.
226 p, --persist-to=NUMNODES
228 Wait until the item has been persisted to at least NUMNODES
229 nodes´ disk. If NUMNODES is 1 then wait until only the master
230 node has persisted the item for this key. You may not specify a
231 number greater than the number of nodes actually in the cluster.
232 -1 is special value, which mean to use all available nodes.
233 r --replicate-to=NREPLICAS
235 Wait until the item has been replicated to at least NREPLICAS
236 replica nodes. The bucket must be configured with at least one
237 replica, and at least NREPLICAS replica nodes must be online. -1
238 is special value, which mean to use all available replicas.
239 --lock=TIME
241 This will retrieve and lock an item before update, making it
242 inaccessible for modification until the update completed, or
243 TIME has passed.
244 --json Make pillowfight store document as JSON rather than binary. This
246 will allow the documents to nominally be analyzed by other
247 Couchbase services such as Query and MapReduce.
248 JSON documents are created by creating an empty JSON object ({})
250 and then repeated populating it with Field_%d property names
251 (where %d is 1 and higher), and setting its value to a repeating
252 asterisk * up to 16 times:
253 {
257 "Field_1": "****************",
258 "Field_2": "****************",
259 "Field_3": "****************",
260 "Field_4": "****************",
261 "Field_5": "********"
262 }
263 When using document size constraints, be aware that the minimum and
267 maximum sizes (--min-size and --max-size) are not strict limits, and
268 that the resultant sizes may be bigger or smaller by a few bytes in
269 order to satisfy the requirements of proper JSON syntax.
270 --noop
272 Use couchbase NOOP operations when running the workload. This mode
273 ignores population, and all other document operations. Useful as the
274 most lightweight workload.
275 --subdoc
277 Use couchbase sub-document operations when running the workload. In
278 this mode pillowfight will use Couchbase sub-document operations
279 http://blog.couchbase.com/2016/february/subdoc-explained to perform
280 gets and sets of data. This option must be used with --json
281 --pathcount
283 Specify the number of paths a single sub-document operation should con‐
284 tain. By default, each subdoc operation operates on only a single path
285 within the document. You can specify multiple paths to atomically exe‐
286 cuted multiple subdoc operations within a single command.
287 This option does not affect the --batch-size option as a subdoc command
289 is considered as a single command (with respect to batching) regardless
290 of how many operations it contains.
291
293 The following options may be included in the connection string (via the
294 -U option) as URI-style query params (e.g. couch‐
295 base://host/bucket?option1=value1&option2=value2) or as individual
296 key=value pairs passed to the -D switch (e.g. -Doption1=value1 -Dop‐
297 tion2=value). The -D will internally build the connection string, and
298 is provided as a convenience for options to be easily passed on the
299 command-line
300 · operation_timeout=SECONDS: Specify the operation timeout in sec‐
302 onds. This is the time the client will wait for an operation to
303 complete before timing it out. The default is 2.5
304 · config_cache=PATH: Enables the client to make use of a file based
306 configuration cache rather than connecting for the bootstrap opera‐
307 tion. If the file does not exist, the client will first connect to
308 the cluster and then cache the bootstrap information in the file.
309 · truststorepath=PATH: The path to the server´s SSL certificate. This
311 is typically required for SSL connectivity unless the certificate
312 has already been added to the OpenSSL installation on the system
313 (only applicable with couchbases:// scheme)
314 · certpath=PATH: The path to the server´s SSL certificate. This is
316 typically required for SSL connectivity unless the certificate has
317 already been added to the OpenSSL installation on the system (only
318 applicable with couchbases:// scheme). This also should contain
319 client certificate when certificate authentication used, and in
320 this case other public certificates could be extracted into trust‐
321 storepath chain.
322 · keypath=PATH: The path to the client SSL private key. This is typi‐
324 cally required for SSL client certificate authentication. The cer‐
325 tificate itself have to go first in chain specified by certpath
326 (only applicable with couchbases:// scheme)
327 · ssl=no_verify: Temporarily disable certificate verification for SSL
329 (only applicable with couchbases:// scheme). This should only be
330 used for quickly debugging SSL functionality.
331 · sasl_mech_force=MECHANISM: Force a specific SASL mechanism to be
333 used when performing the initial connection. This should only need
334 to be modified for debugging purposes. The currently supported
335 mechanisms are PLAIN and CRAM-MD5
336 · bootstrap_on=<both,http,cccp>: Specify the bootstrap protocol the
338 client should use when attempting to connect to the cluster.
339 Options are: cccp: Bootstrap using the Memcached protocol (sup‐
340 ported on clusters 2.5 and greater); http: Bootstrap using the HTTP
341 REST protocol (supported on any cluster version); and both: First
342 attempt bootstrap over the Memcached protocol, and use the HTTP
343 protocol if Memcached bootstrap fails. The default is both
344 · enable_tracing=true/false: Activate/deactivate end-to-end tracing.
346 · tracing_orphaned_queue_flush_interval=SECONDS: Flush interval for
348 orphaned spans queue in default tracer. This is the time the tracer
349 will wait between repeated attempts to flush most recent orphaned
350 spans. Default value is 10 seconds.
351 · tracing_orphaned_queue_size=NUMBER: Size of orphaned spans queue in
353 default tracer. Queues in default tracer has fixed size, and it
354 will remove information about older spans, when the limit will be
355 reached before flushing time. Default value is 128.
356 · tracing_threshold_queue_flush_interval=SECONDS: Flush interval for
358 spans with total time over threshold in default tracer. This is the
359 time the tracer will wait between repeated attempts to flush
360 threshold queue. Default value is 10 seconds.
361 · tracing_threshold_queue_size=NUMBER: Size of threshold queue in
363 default tracer. Queues in default tracer has fixed size, and it
364 will remove information about older spans, when the limit will be
365 reached before flushing time. Default value is 128.
366 · tracing_threshold_kv=SECONDS: Minimum time for the tracing span of
368 KV service to be considered by threshold tracer. Default value is
369 0.5 seconds.
370 · tracing_threshold_n1ql=SECONDS: Minimum time for the tracing span
372 of N1QL service to be considered by threshold tracer. Default value
373 is 1 second.
374 · tracing_threshold_view=SECONDS: Minimum time for the tracing span
376 of VIEW service to be considered by threshold tracer. Default value
377 is 1 second.
378 · tracing_threshold_fts=SECONDS: Minimum time for the tracing span of
380 FTS service to be considered by threshold tracer. Default value is
381 1 second.
382 · tracing_threshold_analytics=SECONDS: Minimum time for the tracing
384 span of ANALYTICS service to be considered by threshold tracer.
385 Default value is 1 second.
386
390 CONNECTION EXAMPLES
391 The following examples show how to connect pillowfight to different
392 types of cluster configurations.
393 Connect to a bucket (a_bucket) on a cluster on a remote host (for
395 servers version 5.x+). It uses account ´myname´ and asks password
396 interactively:
397 cbc-pillowfight -U couchbase://192.168.33.101/a_bucket -u myname -P-
401 Run against a password-less bucket (a_bucket) on a cluster on a remote
405 host (for servers older than 5.x):
406 cbc-pillowfight -U couchbase://192.168.33.101/a_bucket
410 Connect to an SSL cluster at secure.net. The certificate for the clus‐
414 ter is stored locally at /home/couchbase/couchbase_cert.pem:
415 cbc-pillowfight -U couchbases://secure.net/topsecret_bucket?certpath=/home/couchbase/couchbase_cert.pem
419 Connect to an SSL cluster at secure.net, ignoring certificate verifica‐
423 tion. This is insecure but handy for testing:
424 cbc-pillowfight -U couchbases://secure.net/topsecret_bucket?ssl=no_verify
428 Connect to a password protected bucket (protected) on a remote host
432 (for servers older than 5.x):
433 cbc-pillowfight -U couchbase://remote.host.net/protected -P -
437 Bucket password:
438 ...
439 Connect to a password protected bucket (for servers older than 5.x),
443 specifying the password on the command line (INSECURE, but useful for
444 testing dummy environments)
445 cbc-pillowfight -U couchbase://remote.host.net/protected -P t0ps3cr3t
449 Connect to a bucket running on a cluster with a custom REST API port
453 cbc-pillowfight -U http://localhost:9000/default
457 Connec to bucket running on a cluster with a custom memcached port
461 cbc-pillowfight -U couchbase://localhost:12000/default
465 Connect to a memcached (http://memcached.org) cluster using the binary
469 protocol. A vanilla memcached cluster is not the same as a memcached
470 bucket residing within a couchbase cluster (use the normal couchbase://
471 scheme for that):
472 cbc-pillowfight -U memcached://host1,host2,host3,host4
476 Connect to an SSL cluster at secure.net:
480 cbc-pillowfight -U couchbases://secure.net/topsecret_bucket
484 Run against a bucket (a_bucket) on a cluster on a remote host:
488 cbc-pillowfight -U couchbase://192.168.33.101/a_bucket
492 BENCHMARK EXAMPLES
496 The following examples show how to configure different types of work‐
497 loads with pillowfight.
498 Run with 20 threads/instances, each doing one operation at a time:
500 cbc-pillowfight -t 20 -B 1
504 Run 100 iterations of 2MB item sizes, using a dataset of 50 items
508 cbc-pillowfight -M $(1024*1024) -m $(1024*1024) -c 100 -I 50
512 Use JSON documents of 100k each
516 cbc-pillowfight --json -m 100000 -M 100000
520 Stress-test sub-document mutations
524 cbc-pillowfight --json --subdoc --set-pct 100
528
532 Rather than spawning threads for multiple instances, offer a way to
533 have multiple instances function cooperatively inside an event loop.
534
536 This command´s options are subject to change.
537
539 cbc(1), cbcrc(4)
540
542 The cbc-pillowfight tool was first introduced in libcouchbase 2.0.7
543 October 2018 CBC-PILLOWFIGHT(1)