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
23           retrieval and storage operations are controlled via  the  --set-pct
24           option).
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.
41           Additionally, 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
54           extremely 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
84              instances)  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
90              retrievals.
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
129              increase  the lower limit of the items. This is useful to resume
130              a 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
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
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
180              increased 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
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
204       --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
210       --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
219       --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
225       --dump Dump verbose internal state after operations are done.
226
227       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
234       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
240       --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
245       --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
249              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
254
255
256             {
257                 "Field_1": "****************",
258                 "Field_2": "****************",
259                 "Field_3": "****************",
260                 "Field_4": "****************",
261                 "Field_5": "********"
262             }
263
264
265
266       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
271       --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
276       --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
282       --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
288       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

ADDITIONAL OPTIONS

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
301       ·   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
305       ·   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
310       ·   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
315       ·   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
323       ·   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
328       ·   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
332       ·   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
337       ·   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
345       ·   enable_tracing=true/false: Activate/deactivate end-to-end tracing.
346
347       ·   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
352       ·   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
357       ·   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
362       ·   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
367       ·   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
371       ·   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
375       ·   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
379       ·   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
383       ·   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
387
388

EXAMPLES

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

TODO

532       Rather than spawning threads for multiple instances,  offer  a  way  to
533       have multiple instances function cooperatively inside an event loop.
534

BUGS

536       This command´s options are subject to change.
537

SEE ALSO

539       cbc(1), cbcrc(4)
540

HISTORY

542       The cbc-pillowfight tool was first introduced in libcouchbase 2.0.7
543
544
545
546                                 October 2018               CBC-PILLOWFIGHT(1)
Impressum