1CBC-PILLOWFIGHT(1)                                          CBC-PILLOWFIGHT(1)
2
3
4

NAME

6       cbc-pillowfight - Stress Test for Couchbase Client and Cluster
7

SYNOPSIS

9       cbc-pillowfight [OPTIONS]
10

DESCRIPTION

12       cbc-pillowfight  creates a specified number of threads each looping and
13       performing get and set operations within the cluster.
14
15       The stress test operates in the following order
16
17       1.  It will pre-load the items in the cluster (set by  the  --num-items
18           option)
19
20       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
26       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
31
32
33   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
39       •   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
43       •   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
47       •   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
51       •   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
57
58
59       The  benchmark  tool  sets up SIGQUIT (CTRL-/) handler and dumps useful
60       diagnostics and metrics to STDERR on this signal.
61

OPTIONS

63       Options may be read either from the command line, or from a  configura‐
64       tion file (see cbcrc(4)):
65
66       The following options control workload generation:
67
68       -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
72       -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
78       -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
82       -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
87       -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
92       -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
98       --populate-only
99              Stop  after  population.  Useful  to populate buckets with large
100              amounts of data.
101
102       -m, --min-size=MINSIZE:
103
104
105       -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
110       -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
115       -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
120       --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
125       --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
132       -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
138       -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
143       -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
149              The default for this option is couchbase://localhost/default
150
151       -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
158       -P, --password=PASSWORD:
159
160
161       -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
168              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
173       -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
177       -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
182       -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
190       -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
204       --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
210       --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
219       --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
225       --dump Dump verbose internal state after operations are done.
226
227       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
232       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
239       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
245       --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
250       --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
254              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
259
260
261             {
262                 "Field_1": "****************",
263                 "Field_2": "****************",
264                 "Field_3": "****************",
265                 "Field_4": "****************",
266                 "Field_5": "********"
267             }
268
269
270
271       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
276       --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
281       --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
287       --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
293       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

ADDITIONAL OPTIONS

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
305operation_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
309config_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
314truststorepath=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
319certpath=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
327keypath=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
332ipv6=allow: Enable IPv6.
333
334ssl=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
338sasl_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
343bootstrap_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
351enable_tracing=true/false: Activate/deactivate end-to-end tracing.
352
353tracing_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
358tracing_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
363tracing_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
368tracing_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
373tracing_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
377tracing_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
381tracing_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
385tracing_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
389tracing_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
393
394

EXAMPLES

396   CONNECTION EXAMPLES
397       The following examples show how to  connect  pillowfight  to  different
398       types of cluster configurations.
399
400       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
404
405
406           cbc-pillowfight -U couchbase://192.168.33.101/a_bucket -u myname -P-
407
408
409
410       Run  against a password-less bucket (a_bucket) on a cluster on a remote
411       host (for servers older than 5.x):
412
413
414
415           cbc-pillowfight -U couchbase://192.168.33.101/a_bucket
416
417
418
419       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
422
423
424           cbc-pillowfight -U couchbases://secure.net/topsecret_bucket?certpath=/home/couchbase/couchbase_cert.pem
425
426
427
428       Connect to an SSL cluster at secure.net, ignoring certificate verifica‐
429       tion. This is insecure but handy for testing:
430
431
432
433           cbc-pillowfight -U couchbases://secure.net/topsecret_bucket?ssl=no_verify
434
435
436
437       Connect to a password protected bucket (protected)  on  a  remote  host
438       (for servers older than 5.x):
439
440
441
442           cbc-pillowfight -U couchbase://remote.host.net/protected -P -
443           Bucket password:
444           ...
445
446
447
448       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
452
453
454           cbc-pillowfight -U couchbase://remote.host.net/protected -P t0ps3cr3t
455
456
457
458       Connect to a bucket running on a cluster with a custom REST API port
459
460
461
462           cbc-pillowfight -U http://localhost:9000/default
463
464
465
466       Connec to bucket running on a cluster with a custom memcached port
467
468
469
470           cbc-pillowfight -U couchbase://localhost:12000/default
471
472
473
474       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
479
480
481           cbc-pillowfight -U memcached://host1,host2,host3,host4
482
483
484
485       Connect to an SSL cluster at secure.net:
486
487
488
489           cbc-pillowfight -U couchbases://secure.net/topsecret_bucket
490
491
492
493       Run against a bucket (a_bucket) on a cluster on a remote host:
494
495
496
497           cbc-pillowfight -U couchbase://192.168.33.101/a_bucket
498
499
500
501   BENCHMARK EXAMPLES
502       The following examples show how to configure different types  of  work‐
503       loads with pillowfight.
504
505       Run with 20 threads/instances, each doing one operation at a time:
506
507
508
509           cbc-pillowfight -t 20 -B 1
510
511
512
513       Run 100 iterations of 2MB item sizes, using a dataset of 50 items
514
515
516
517           cbc-pillowfight -M $(1024*1024) -m $(1024*1024) -c 100 -I 50
518
519
520
521       Use JSON documents of 100k each
522
523
524
525           cbc-pillowfight --json -m 100000 -M 100000
526
527
528
529       Stress-test sub-document mutations
530
531
532
533           cbc-pillowfight --json --subdoc --set-pct 100
534
535
536

TODO

538       Rather  than  spawning  threads  for multiple instances, offer a way to
539       have multiple instances function cooperatively inside an event loop.
540

BUGS

542       This command´s options are subject to change.
543

SEE ALSO

545       cbc(1), cbcrc(4)
546

HISTORY

548       The cbc-pillowfight tool was first introduced in libcouchbase 2.0.7
549
550
551
552                                  April 2019                CBC-PILLOWFIGHT(1)
Impressum