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 re‐
23 trieval and storage operations are controlled via the --set-pct op‐
24 tion).
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. Ad‐
41 ditionally, 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 ex‐
54 tremely 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 --collection=scopeName.collectionName
83 Access data based on full collection name path. Multiple --col‐
84 lection filters can specify the different scopes with different
85 collection names. Note that default collection will not be used
86 if the collection was specified, to enable default collection
87 along with the named ones, it should be specified explicitly
88 --collection=_default._default.
89 -t, --num-threads=NTHREADS
91 Set the number of threads (and thus the number of client in‐
92 stances) to run concurrently. Each thread is assigned its own
93 client object.
94 -r, --set-pct=PERCENTAGE
96 The percentage of operations which should be mutations. A value
97 of 100 means only mutations while a value of 0 means only re‐
98 trievals.
99 -n, --no-population
101 By default cbc-pillowfight will load all the items (see
102 --num-items) into the cluster and then begin performing the nor‐
103 mal workload. Specifying this option bypasses this stage. Useful
104 if the items have already been loaded in a previous run.
105 --populate-only
107 Stop after population. Useful to populate buckets with large
108 amounts of data.
109 -m, --min-size=MINSIZE:
111 -M, --max-size=MAXSIZE
114 Specify the minimum and maximum value sizes to be stored into
115 the cluster. This is typically a range, in which case each value
116 generated will be between --min-size and --max-size bytes.
117 -E, --pause-at-end
119 When the workload completes, do not exit immediately, but wait
120 for user input. This is helpful for analyzing open socket con‐
121 nections and state.
122 -c, --num-cycles
124 Specify the number of times the workload should cycle. During
125 each cycle an amount of --batch-size operations are executed.
126 Setting this to -1 will cause the workload to run infinitely.
127 --sequential
129 Specify that the access pattern should be done in a sequential
130 manner. This is useful for bulk-loading many documents in a sin‐
131 gle server.
132 --start-at
134 This specifies the starting offset for the items. The items by
135 default are generated with the key prefix (--key-prefix) up to
136 the number of items (--num-items). The --start-at value will in‐
137 crease the lower limit of the items. This is useful to resume a
138 previously cancelled load operation.
139 -T, --timings
141 Enabled timing recorded. Timing histogram will be dumped to
142 STDERR on SIGQUIT (CTRL-/). When specified second time, it will
143 dump a histogram of command timings and latencies to the screen
144 every second.
145 -e, --expiry=SECONDS
147 Set the expiration time on the document for SECONDS when per‐
148 forming each operation. Note that setting this too low may cause
149 not-found errors to appear on the screen.
150 -U, --spec=SPEC
152 A string describing the cluster to connect to. The string is in
153 a URI-like syntax, and may also contain other options. See the
154 EXAMPLES section for information. Typically such a URI will look
155 like couchbase://host1,host2,host3/bucket.
156 The default for this option is couchbase://localhost/default
158 -u, --username=USERNAME
160 Specify the username for the bucket. Since Couchbase 5.x this is
161 mandatory switch, and it must specify the name of the user ex‐
162 isiting on cluster (read more at "Security/Authorization" sec‐
163 tion of the server manual). For older servers this field should
164 be either left empty or set to the name of the bucket itself.
165 -P, --password=PASSWORD:
167 -P -, --password=-
170 Specify the password for the bucket. As for servers before 5.x
171 this was only needed if the bucket is protected with a password.
172 For cluster version after 5.x, the password is mandatory, and
173 should match the selected account (read more at "Security/Autho‐
174 rization" section of the server manual).
175 Specifying the - as the password indicates that the program
177 should prompt for the password. You may also specify the pass‐
178 word on the commandline, directly, but is insecure as command
179 line arguments are visible via commands such as ps.
180 -T, --timings
182 Dump command timings at the end of execution. This will display
183 a histogram showing the latencies for the commands executed.
184 -v, --verbose
186 Specify more information to standard error about what the client
187 is doing. You may specify this option multiple times for in‐
188 creased output detail.
189 -D, --cparam=OPTION=VALUE
191 Provide additional client options. Acceptable options can also
192 be placed in the connection string, however this option is pro‐
193 vided as a convenience. This option may be specified multiple
194 times, each time specifying a key=value pair (for example, -Dop‐
195 eration_timeout=10 -Dconfig_cache=/foo/bar/baz). See ADDITIONAL
196 OPTIONS for more information
197 -y, --compress
199 Enable compressing of documents. When the library is compiled
200 with compression support, this option will enable Snappy com‐
201 pression for outgoing data. Incoming compressed data handled au‐
202 tomatically regardless of this option. Note, that because the
203 compression support have to be negotiated with the server, first
204 packets might be sent uncompressed even when this switch was
205 specified. This is because the library might queue data commands
206 before socket connection has been established, and the library
207 will negotiate compression feature. If it is known that all
208 server support compression repeating the switch (like -yy) will
209 force compression for all outgoing mutations, even scheduled be‐
210 fore establishing connection.
211 --truststorepath=PATH
213 The path to the server´s SSL certificate. This is typically re‐
214 quired for SSL connectivity unless the certificate has already
215 been added to the OpenSSL installation on the system (only ap‐
216 plicable with couchbases:// scheme)
217 --certpath=PATH
219 The path to the server´s SSL certificate. This is typically re‐
220 quired for SSL connectivity unless the certificate has already
221 been added to the OpenSSL installation on the system (only ap‐
222 plicable with couchbases:// scheme). This also should contain
223 client certificate when certificate authentication used, and in
224 this case other public certificates could be extracted into
225 truststorepath chain.
226 --keypath=PATH
228 The path to the client SSL private key. This is typically re‐
229 quired for SSL client certificate authentication. The certifi‐
230 cate itself have to go first in chain specified by certpath
231 (only applicable with couchbases:// scheme)
232 --dump Dump verbose internal state after operations are done.
234 d, --durability=LEVEL
236 Specify durability level for mutation operations. Known values
237 are: "none", "majority", "majority_and_persist_to_active", "per‐
238 sist_to_majority".
239 p, --persist-to=NUMNODES
241 Wait until the item has been persisted to at least NUMNODES
242 nodes´ disk. If NUMNODES is 1 then wait until only the master
243 node has persisted the item for this key. You may not specify a
244 number greater than the number of nodes actually in the cluster.
245 -1 is special value, which mean to use all available nodes.
246 r --replicate-to=NREPLICAS
248 Wait until the item has been replicated to at least NREPLICAS
249 replica nodes. The bucket must be configured with at least one
250 replica, and at least NREPLICAS replica nodes must be online. -1
251 is special value, which mean to use all available replicas.
252 --lock=TIME
254 This will retrieve and lock an item before update, making it in‐
255 accessible for modification until the update completed, or TIME
256 has passed.
257 --json Make pillowfight store document as JSON rather than binary. This
259 will allow the documents to nominally be analyzed by other
260 Couchbase services such as Query and MapReduce.
261 JSON documents are created by creating an empty JSON object ({})
263 and then repeated populating it with Field_%d property names
264 (where %d is 1 and higher), and setting its value to a repeating
265 asterisk * up to 16 times:
266 {
270 "Field_1": "****************",
271 "Field_2": "****************",
272 "Field_3": "****************",
273 "Field_4": "****************",
274 "Field_5": "********"
275 }
276 When using document size constraints, be aware that the minimum and
280 maximum sizes (--min-size and --max-size) are not strict limits, and
281 that the resultant sizes may be bigger or smaller by a few bytes in or‐
282 der to satisfy the requirements of proper JSON syntax.
283 --noop
285 Use couchbase NOOP operations when running the workload. This mode ig‐
286 nores population, and all other document operations. Useful as the most
287 lightweight workload.
288 --subdoc
290 Use couchbase sub-document operations when running the workload. In
291 this mode pillowfight will use Couchbase sub-document operations
292 http://blog.couchbase.com/2016/february/subdoc-explained to perform
293 gets and sets of data. This option must be used with --json
294 --pathcount
296 Specify the number of paths a single sub-document operation should con‐
297 tain. By default, each subdoc operation operates on only a single path
298 within the document. You can specify multiple paths to atomically exe‐
299 cuted multiple subdoc operations within a single command.
300 This option does not affect the --batch-size option as a subdoc command
302 is considered as a single command (with respect to batching) regardless
303 of how many operations it contains.
304
306 The following options may be included in the connection string (via the
307 -U option) as URI-style query params (e.g. couchbase://host/bucket?op‐
308 tion1=value1&option2=value2) or as individual key=value pairs passed to
309 the -D switch (e.g. -Doption1=value1 -Doption2=value). The -D will in‐
310 ternally build the connection string, and is provided as a convenience
311 for options to be easily passed on the command-line
312 • operation_timeout=SECONDS: Specify the operation timeout in sec‐
314 onds. This is the time the client will wait for an operation to
315 complete before timing it out. The default is 2.5
316 • config_cache=PATH: Enables the client to make use of a file based
318 configuration cache rather than connecting for the bootstrap opera‐
319 tion. If the file does not exist, the client will first connect to
320 the cluster and then cache the bootstrap information in the file.
321 • truststorepath=PATH: The path to the server´s SSL certificate. This
323 is typically required for SSL connectivity unless the certificate
324 has already been added to the OpenSSL installation on the system
325 (only applicable with couchbases:// scheme)
326 • certpath=PATH: The path to the server´s SSL certificate. This is
328 typically required for SSL connectivity unless the certificate has
329 already been added to the OpenSSL installation on the system (only
330 applicable with couchbases:// scheme). This also should contain
331 client certificate when certificate authentication used, and in
332 this case other public certificates could be extracted into trust‐
333 storepath chain.
334 • keypath=PATH: The path to the client SSL private key. This is typi‐
336 cally required for SSL client certificate authentication. The cer‐
337 tificate itself have to go first in chain specified by certpath
338 (only applicable with couchbases:// scheme)
339 • ipv6=allow: Enable IPv6.
341 • ssl=no_verify: Temporarily disable certificate verification for SSL
343 (only applicable with couchbases:// scheme). This should only be
344 used for quickly debugging SSL functionality.
345 • sasl_mech_force=MECHANISM: Force a specific SASL mechanism to be
347 used when performing the initial connection. This should only need
348 to be modified for debugging purposes. The currently supported
349 mechanisms are PLAIN and CRAM-MD5
350 • bootstrap_on=<both,http,cccp>: Specify the bootstrap protocol the
352 client should use when attempting to connect to the cluster. Op‐
353 tions are: cccp: Bootstrap using the Memcached protocol (supported
354 on clusters 2.5 and greater); http: Bootstrap using the HTTP REST
355 protocol (supported on any cluster version); and both: First at‐
356 tempt bootstrap over the Memcached protocol, and use the HTTP pro‐
357 tocol if Memcached bootstrap fails. The default is both
358 • enable_tracing=true/false: Activate/deactivate end-to-end tracing.
360 • tracing_orphaned_queue_flush_interval=SECONDS: Flush interval for
362 orphaned spans queue in default tracer. This is the time the tracer
363 will wait between repeated attempts to flush most recent orphaned
364 spans. Default value is 10 seconds.
365 • tracing_orphaned_queue_size=NUMBER: Size of orphaned spans queue in
367 default tracer. Queues in default tracer has fixed size, and it
368 will remove information about older spans, when the limit will be
369 reached before flushing time. Default value is 128.
370 • tracing_threshold_queue_flush_interval=SECONDS: Flush interval for
372 spans with total time over threshold in default tracer. This is the
373 time the tracer will wait between repeated attempts to flush
374 threshold queue. Default value is 10 seconds.
375 • tracing_threshold_queue_size=NUMBER: Size of threshold queue in de‐
377 fault tracer. Queues in default tracer has fixed size, and it will
378 remove information about older spans, when the limit will be
379 reached before flushing time. Default value is 128.
380 • tracing_threshold_kv=SECONDS: Minimum time for the tracing span of
382 KV service to be considered by threshold tracer. Default value is
383 0.5 seconds.
384 • tracing_threshold_query=SECONDS: Minimum time for the tracing span
386 of QUERY service to be considered by threshold tracer. Default
387 value is 1 second.
388 • tracing_threshold_view=SECONDS: Minimum time for the tracing span
390 of VIEW service to be considered by threshold tracer. Default value
391 is 1 second.
392 • tracing_threshold_search=SECONDS: Minimum time for the tracing span
394 of SEARCH service to be considered by threshold tracer. Default
395 value is 1 second.
396 • tracing_threshold_analytics=SECONDS: Minimum time for the tracing
398 span of ANALYTICS service to be considered by threshold tracer. De‐
399 fault value is 1 second.
400
404 CONNECTION EXAMPLES
405 The following examples show how to connect pillowfight to different
406 types of cluster configurations.
407 Connect to a bucket (a_bucket) on a cluster on a remote host (for
409 servers version 5.x+). It uses account ´myname´ and asks password in‐
410 teractively:
411 cbc-pillowfight -U couchbase://192.168.33.101/a_bucket -u myname -P-
415 Run against a password-less bucket (a_bucket) on a cluster on a remote
419 host (for servers older than 5.x):
420 cbc-pillowfight -U couchbase://192.168.33.101/a_bucket
424 Connect to an SSL cluster at secure.net. The certificate for the clus‐
428 ter is stored locally at /home/couchbase/couchbase_cert.pem:
429 cbc-pillowfight -U couchbases://secure.net/topsecret_bucket?certpath=/home/couchbase/couchbase_cert.pem
433 Connect to an SSL cluster at secure.net, ignoring certificate verifica‐
437 tion. This is insecure but handy for testing:
438 cbc-pillowfight -U couchbases://secure.net/topsecret_bucket?ssl=no_verify
442 Connect to a password protected bucket (protected) on a remote host
446 (for servers older than 5.x):
447 cbc-pillowfight -U couchbase://remote.host.net/protected -P -
451 Bucket password:
452 ...
453 Connect to a password protected bucket (for servers older than 5.x),
457 specifying the password on the command line (INSECURE, but useful for
458 testing dummy environments)
459 cbc-pillowfight -U couchbase://remote.host.net/protected -P t0ps3cr3t
463 Connect to a bucket running on a cluster with a custom REST API port
467 cbc-pillowfight -U http://localhost:9000/default
471 Connec to bucket running on a cluster with a custom memcached port
475 cbc-pillowfight -U couchbase://localhost:12000/default
479 Connect to a memcached (http://memcached.org) cluster using the binary
483 protocol. A vanilla memcached cluster is not the same as a memcached
484 bucket residing within a couchbase cluster (use the normal couchbase://
485 scheme for that):
486 cbc-pillowfight -U memcached://host1,host2,host3,host4
490 Connect to an SSL cluster at secure.net:
494 cbc-pillowfight -U couchbases://secure.net/topsecret_bucket
498 Run against a bucket (a_bucket) on a cluster on a remote host:
502 cbc-pillowfight -U couchbase://192.168.33.101/a_bucket
506 Run against a bucket (a_bucket) and use collections app.users and
510 backup.stage:
511 cbc-pillowfight --spec couchbase://127.0.0.1/a_bucket --username Administrator --password password \
515 --collection app.users --collection backup.stage
516 BENCHMARK EXAMPLES
520 The following examples show how to configure different types of work‐
521 loads with pillowfight.
522 Run with 20 threads/instances, each doing one operation at a time:
524 cbc-pillowfight -t 20 -B 1
528 Run 100 iterations of 2MB item sizes, using a dataset of 50 items
532 cbc-pillowfight -M $(1024*1024) -m $(1024*1024) -c 100 -I 50
536 Use JSON documents of 100k each
540 cbc-pillowfight --json -m 100000 -M 100000
544 Stress-test sub-document mutations
548 cbc-pillowfight --json --subdoc --set-pct 100
552
556 Rather than spawning threads for multiple instances, offer a way to
557 have multiple instances function cooperatively inside an event loop.
558
560 This command´s options are subject to change.
561
563 cbc(1), cbcrc(4)
564
566 The cbc-pillowfight tool was first introduced in libcouchbase 2.0.7
567 August 2023 CBC-PILLOWFIGHT(1)