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 -t, --num-threads=NTHREADS
83 Set the number of threads (and thus the number of client in‐
84 stances) 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 re‐
90 trievals.
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 in‐
129 crease the lower limit of the items. This is useful to resume a
130 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 ex‐
154 isiting 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 in‐
180 creased 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 au‐
194 tomatically 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 be‐
202 fore establishing connection.
203 --truststorepath=PATH
205 The path to the server´s SSL certificate. This is typically re‐
206 quired for SSL connectivity unless the certificate has already
207 been added to the OpenSSL installation on the system (only ap‐
208 plicable with couchbases:// scheme)
209 --certpath=PATH
211 The path to the server´s SSL certificate. This is typically re‐
212 quired for SSL connectivity unless the certificate has already
213 been added to the OpenSSL installation on the system (only ap‐
214 plicable 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 re‐
221 quired 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 d, --durability=LEVEL
228 Specify durability level for mutation operations. Known values
229 are: "none", "majority", "majority_and_persist_to_active", "per‐
230 sist_to_majority".
231 p, --persist-to=NUMNODES
233 Wait until the item has been persisted to at least NUMNODES
234 nodes´ disk. If NUMNODES is 1 then wait until only the master
235 node has persisted the item for this key. You may not specify a
236 number greater than the number of nodes actually in the cluster.
237 -1 is special value, which mean to use all available nodes.
238 r --replicate-to=NREPLICAS
240 Wait until the item has been replicated to at least NREPLICAS
241 replica nodes. The bucket must be configured with at least one
242 replica, and at least NREPLICAS replica nodes must be online. -1
243 is special value, which mean to use all available replicas.
244 --lock=TIME
246 This will retrieve and lock an item before update, making it in‐
247 accessible for modification until the update completed, or TIME
248 has passed.
249 --json Make pillowfight store document as JSON rather than binary. This
251 will allow the documents to nominally be analyzed by other
252 Couchbase services such as Query and MapReduce.
253 JSON documents are created by creating an empty JSON object ({})
255 and then repeated populating it with Field_%d property names
256 (where %d is 1 and higher), and setting its value to a repeating
257 asterisk * up to 16 times:
258 {
262 "Field_1": "****************",
263 "Field_2": "****************",
264 "Field_3": "****************",
265 "Field_4": "****************",
266 "Field_5": "********"
267 }
268 When using document size constraints, be aware that the minimum and
272 maximum sizes (--min-size and --max-size) are not strict limits, and
273 that the resultant sizes may be bigger or smaller by a few bytes in or‐
274 der to satisfy the requirements of proper JSON syntax.
275 --noop
277 Use couchbase NOOP operations when running the workload. This mode ig‐
278 nores population, and all other document operations. Useful as the most
279 lightweight workload.
280 --subdoc
282 Use couchbase sub-document operations when running the workload. In
283 this mode pillowfight will use Couchbase sub-document operations
284 http://blog.couchbase.com/2016/february/subdoc-explained to perform
285 gets and sets of data. This option must be used with --json
286 --pathcount
288 Specify the number of paths a single sub-document operation should con‐
289 tain. By default, each subdoc operation operates on only a single path
290 within the document. You can specify multiple paths to atomically exe‐
291 cuted multiple subdoc operations within a single command.
292 This option does not affect the --batch-size option as a subdoc command
294 is considered as a single command (with respect to batching) regardless
295 of how many operations it contains.
296
298 The following options may be included in the connection string (via the
299 -U option) as URI-style query params (e.g. couchbase://host/bucket?op‐
300 tion1=value1&option2=value2) or as individual key=value pairs passed to
301 the -D switch (e.g. -Doption1=value1 -Doption2=value). The -D will in‐
302 ternally build the connection string, and is provided as a convenience
303 for options to be easily passed on the command-line
304 • operation_timeout=SECONDS: Specify the operation timeout in sec‐
306 onds. This is the time the client will wait for an operation to
307 complete before timing it out. The default is 2.5
308 • config_cache=PATH: Enables the client to make use of a file based
310 configuration cache rather than connecting for the bootstrap opera‐
311 tion. If the file does not exist, the client will first connect to
312 the cluster and then cache the bootstrap information in the file.
313 • truststorepath=PATH: The path to the server´s SSL certificate. This
315 is typically required for SSL connectivity unless the certificate
316 has already been added to the OpenSSL installation on the system
317 (only applicable with couchbases:// scheme)
318 • certpath=PATH: The path to the server´s SSL certificate. This is
320 typically required for SSL connectivity unless the certificate has
321 already been added to the OpenSSL installation on the system (only
322 applicable with couchbases:// scheme). This also should contain
323 client certificate when certificate authentication used, and in
324 this case other public certificates could be extracted into trust‐
325 storepath chain.
326 • keypath=PATH: The path to the client SSL private key. This is typi‐
328 cally required for SSL client certificate authentication. The cer‐
329 tificate itself have to go first in chain specified by certpath
330 (only applicable with couchbases:// scheme)
331 • ipv6=allow: Enable IPv6.
333 • ssl=no_verify: Temporarily disable certificate verification for SSL
335 (only applicable with couchbases:// scheme). This should only be
336 used for quickly debugging SSL functionality.
337 • sasl_mech_force=MECHANISM: Force a specific SASL mechanism to be
339 used when performing the initial connection. This should only need
340 to be modified for debugging purposes. The currently supported
341 mechanisms are PLAIN and CRAM-MD5
342 • bootstrap_on=<both,http,cccp>: Specify the bootstrap protocol the
344 client should use when attempting to connect to the cluster. Op‐
345 tions are: cccp: Bootstrap using the Memcached protocol (supported
346 on clusters 2.5 and greater); http: Bootstrap using the HTTP REST
347 protocol (supported on any cluster version); and both: First at‐
348 tempt bootstrap over the Memcached protocol, and use the HTTP pro‐
349 tocol if Memcached bootstrap fails. The default is both
350 • enable_tracing=true/false: Activate/deactivate end-to-end tracing.
352 • tracing_orphaned_queue_flush_interval=SECONDS: Flush interval for
354 orphaned spans queue in default tracer. This is the time the tracer
355 will wait between repeated attempts to flush most recent orphaned
356 spans. Default value is 10 seconds.
357 • tracing_orphaned_queue_size=NUMBER: Size of orphaned spans queue in
359 default tracer. Queues in default tracer has fixed size, and it
360 will remove information about older spans, when the limit will be
361 reached before flushing time. Default value is 128.
362 • tracing_threshold_queue_flush_interval=SECONDS: Flush interval for
364 spans with total time over threshold in default tracer. This is the
365 time the tracer will wait between repeated attempts to flush
366 threshold queue. Default value is 10 seconds.
367 • tracing_threshold_queue_size=NUMBER: Size of threshold queue in de‐
369 fault tracer. Queues in default tracer has fixed size, and it will
370 remove information about older spans, when the limit will be
371 reached before flushing time. Default value is 128.
372 • tracing_threshold_kv=SECONDS: Minimum time for the tracing span of
374 KV service to be considered by threshold tracer. Default value is
375 0.5 seconds.
376 • tracing_threshold_query=SECONDS: Minimum time for the tracing span
378 of QUERY service to be considered by threshold tracer. Default
379 value is 1 second.
380 • tracing_threshold_view=SECONDS: Minimum time for the tracing span
382 of VIEW service to be considered by threshold tracer. Default value
383 is 1 second.
384 • tracing_threshold_search=SECONDS: Minimum time for the tracing span
386 of SEARCH service to be considered by threshold tracer. Default
387 value is 1 second.
388 • tracing_threshold_analytics=SECONDS: Minimum time for the tracing
390 span of ANALYTICS service to be considered by threshold tracer. De‐
391 fault value is 1 second.
392
396 CONNECTION EXAMPLES
397 The following examples show how to connect pillowfight to different
398 types of cluster configurations.
399 Connect to a bucket (a_bucket) on a cluster on a remote host (for
401 servers version 5.x+). It uses account ´myname´ and asks password in‐
402 teractively:
403 cbc-pillowfight -U couchbase://192.168.33.101/a_bucket -u myname -P-
407 Run against a password-less bucket (a_bucket) on a cluster on a remote
411 host (for servers older than 5.x):
412 cbc-pillowfight -U couchbase://192.168.33.101/a_bucket
416 Connect to an SSL cluster at secure.net. The certificate for the clus‐
420 ter is stored locally at /home/couchbase/couchbase_cert.pem:
421 cbc-pillowfight -U couchbases://secure.net/topsecret_bucket?certpath=/home/couchbase/couchbase_cert.pem
425 Connect to an SSL cluster at secure.net, ignoring certificate verifica‐
429 tion. This is insecure but handy for testing:
430 cbc-pillowfight -U couchbases://secure.net/topsecret_bucket?ssl=no_verify
434 Connect to a password protected bucket (protected) on a remote host
438 (for servers older than 5.x):
439 cbc-pillowfight -U couchbase://remote.host.net/protected -P -
443 Bucket password:
444 ...
445 Connect to a password protected bucket (for servers older than 5.x),
449 specifying the password on the command line (INSECURE, but useful for
450 testing dummy environments)
451 cbc-pillowfight -U couchbase://remote.host.net/protected -P t0ps3cr3t
455 Connect to a bucket running on a cluster with a custom REST API port
459 cbc-pillowfight -U http://localhost:9000/default
463 Connec to bucket running on a cluster with a custom memcached port
467 cbc-pillowfight -U couchbase://localhost:12000/default
471 Connect to a memcached (http://memcached.org) cluster using the binary
475 protocol. A vanilla memcached cluster is not the same as a memcached
476 bucket residing within a couchbase cluster (use the normal couchbase://
477 scheme for that):
478 cbc-pillowfight -U memcached://host1,host2,host3,host4
482 Connect to an SSL cluster at secure.net:
486 cbc-pillowfight -U couchbases://secure.net/topsecret_bucket
490 Run against a bucket (a_bucket) on a cluster on a remote host:
494 cbc-pillowfight -U couchbase://192.168.33.101/a_bucket
498 BENCHMARK EXAMPLES
502 The following examples show how to configure different types of work‐
503 loads with pillowfight.
504 Run with 20 threads/instances, each doing one operation at a time:
506 cbc-pillowfight -t 20 -B 1
510 Run 100 iterations of 2MB item sizes, using a dataset of 50 items
514 cbc-pillowfight -M $(1024*1024) -m $(1024*1024) -c 100 -I 50
518 Use JSON documents of 100k each
522 cbc-pillowfight --json -m 100000 -M 100000
526 Stress-test sub-document mutations
530 cbc-pillowfight --json --subdoc --set-pct 100
534
538 Rather than spawning threads for multiple instances, offer a way to
539 have multiple instances function cooperatively inside an event loop.
540
542 This command´s options are subject to change.
543
545 cbc(1), cbcrc(4)
546
548 The cbc-pillowfight tool was first introduced in libcouchbase 2.0.7
549 April 2019 CBC-PILLOWFIGHT(1)