1CBC-N1QLBACK(1) CBC-N1QLBACK(1)
2
6 cbc-n1qlback - Stress Test for Couchbase Query (N1QL)
7
9 cbc-n1qlback -f QUERYFILE [OPTIONS]
10
12 cbc-n1qlback creates a specified number of threads each executing a set
13 of user defined queries.
14 cbc-n1qlback requires that it be passed the path to a file containing
16 the queries to execute; one per line. The query should be in the format
17 of the actual HTTP POST body (in JSON format) to be sent to the server.
18 For simple queries, only the statement field needs to be set:
19 {"statement":"SELECT country FROM `travel-sample`"}
23 {"statement":"SELECT country, COUNT(country) FROM `travel-sample` GROUP BY country"}
24 For more complex queries (for example, placeholders, custom options),
28 you may refer to the N1QL REST API reference.
29 n1qlback requires that any resources (data items, indexes) are already
31 defined.
32
34 The following options control workload generation:
35 -f --queryfile=PATH
37 Path to a file containing the query bodies to execute in JSON
38 format, one query per line. See above for the format.
39 -t, --num-threads=NTHREADS
41 Set the number of threads (and thus the number of client
42 instances) to run concurrently. Each thread is assigned its own
43 client object.
44 The following options control how cbc-n1qlback connects to the cluster
46 -U, --spec=SPEC
48 A string describing the cluster to connect to. The string is in
49 a URI-like syntax, and may also contain other options. See the
50 EXAMPLES section for information. Typically such a URI will look
51 like couchbase://host1,host2,host3/bucket.
52 The default for this option is couchbase://localhost/default
54 -u, --username=USERNAME
56 Specify the username for the bucket. Since Couchbase 5.x this is
57 mandatory switch, and it must specify the name of the user
58 exisiting on cluster (read more at "Security/Authorization" sec‐
59 tion of the server manual). For older servers this field should
60 be either left empty or set to the name of the bucket itself.
61 -P, --password=PASSWORD:
63 -P -, --password=-
66 Specify the password for the bucket. As for servers before 5.x
67 this was only needed if the bucket is protected with a password.
68 For cluster version after 5.x, the password is mandatory, and
69 should match the selected account (read more at "Security/Autho‐
70 rization" section of the server manual).
71 Specifying the - as the password indicates that the program
73 should prompt for the password. You may also specify the pass‐
74 word on the commandline, directly, but is insecure as command
75 line arguments are visible via commands such as ps.
76 -T, --timings
78 Dump command timings at the end of execution. This will display
79 a histogram showing the latencies for the commands executed.
80 -v, --verbose
82 Specify more information to standard error about what the client
83 is doing. You may specify this option multiple times for
84 increased output detail.
85 -D, --cparam=OPTION=VALUE
87 Provide additional client options. Acceptable options can also
88 be placed in the connection string, however this option is pro‐
89 vided as a convenience. This option may be specified multiple
90 times, each time specifying a key=value pair (for example, -Dop‐
91 eration_timeout=10 -Dconfig_cache=/foo/bar/baz). See ADDITIONAL
92 OPTIONS for more information
93 -y, --compress
95 Enable compressing of documents. When the library is compiled
96 with compression support, this option will enable Snappy com‐
97 pression for outgoing data. Incoming compressed data handled
98 automatically regardless of this option. Note, that because the
99 compression support have to be negotiated with the server, first
100 packets might be sent uncompressed even when this switch was
101 specified. This is because the library might queue data commands
102 before socket connection has been established, and the library
103 will negotiate compression feature. If it is known that all
104 server support compression repeating the switch (like -yy) will
105 force compression for all outgoing mutations, even scheduled
106 before establishing connection.
107 --truststorepath=PATH
109 The path to the server´s SSL certificate. This is typically
110 required for SSL connectivity unless the certificate has already
111 been added to the OpenSSL installation on the system (only
112 applicable with couchbases:// scheme)
113 --certpath=PATH
115 The path to the server´s SSL certificate. This is typically
116 required for SSL connectivity unless the certificate has already
117 been added to the OpenSSL installation on the system (only
118 applicable with couchbases:// scheme). This also should contain
119 client certificate when certificate authentication used, and in
120 this case other public certificates could be extracted into
121 truststorepath chain.
122 --keypath=PATH
124 The path to the client SSL private key. This is typically
125 required for SSL client certificate authentication. The certifi‐
126 cate itself have to go first in chain specified by certpath
127 (only applicable with couchbases:// scheme)
128 --dump Dump verbose internal state after operations are done.
130 -e, --error-log=PATH
132 Path to a file, where the command will write failed queries
133 along with error details. Use this option to figure out why
134 ERRORS metric is not zero.
135
137 The following options may be included in the connection string (via the
138 -U option) as URI-style query params (e.g. couch‐
139 base://host/bucket?option1=value1&option2=value2) or as individual
140 key=value pairs passed to the -D switch (e.g. -Doption1=value1 -Dop‐
141 tion2=value). The -D will internally build the connection string, and
142 is provided as a convenience for options to be easily passed on the
143 command-line
144 · operation_timeout=SECONDS: Specify the operation timeout in sec‐
146 onds. This is the time the client will wait for an operation to
147 complete before timing it out. The default is 2.5
148 · config_cache=PATH: Enables the client to make use of a file based
150 configuration cache rather than connecting for the bootstrap opera‐
151 tion. If the file does not exist, the client will first connect to
152 the cluster and then cache the bootstrap information in the file.
153 · truststorepath=PATH: The path to the server´s SSL certificate. This
155 is typically required for SSL connectivity unless the certificate
156 has already been added to the OpenSSL installation on the system
157 (only applicable with couchbases:// scheme)
158 · certpath=PATH: The path to the server´s SSL certificate. This is
160 typically required for SSL connectivity unless the certificate has
161 already been added to the OpenSSL installation on the system (only
162 applicable with couchbases:// scheme). This also should contain
163 client certificate when certificate authentication used, and in
164 this case other public certificates could be extracted into trust‐
165 storepath chain.
166 · keypath=PATH: The path to the client SSL private key. This is typi‐
168 cally required for SSL client certificate authentication. The cer‐
169 tificate itself have to go first in chain specified by certpath
170 (only applicable with couchbases:// scheme)
171 · ssl=no_verify: Temporarily disable certificate verification for SSL
173 (only applicable with couchbases:// scheme). This should only be
174 used for quickly debugging SSL functionality.
175 · sasl_mech_force=MECHANISM: Force a specific SASL mechanism to be
177 used when performing the initial connection. This should only need
178 to be modified for debugging purposes. The currently supported
179 mechanisms are PLAIN and CRAM-MD5
180 · bootstrap_on=<both,http,cccp>: Specify the bootstrap protocol the
182 client should use when attempting to connect to the cluster.
183 Options are: cccp: Bootstrap using the Memcached protocol (sup‐
184 ported on clusters 2.5 and greater); http: Bootstrap using the HTTP
185 REST protocol (supported on any cluster version); and both: First
186 attempt bootstrap over the Memcached protocol, and use the HTTP
187 protocol if Memcached bootstrap fails. The default is both
188 · enable_tracing=true/false: Activate/deactivate end-to-end tracing.
190 · tracing_orphaned_queue_flush_interval=SECONDS: Flush interval for
192 orphaned spans queue in default tracer. This is the time the tracer
193 will wait between repeated attempts to flush most recent orphaned
194 spans. Default value is 10 seconds.
195 · tracing_orphaned_queue_size=NUMBER: Size of orphaned spans queue in
197 default tracer. Queues in default tracer has fixed size, and it
198 will remove information about older spans, when the limit will be
199 reached before flushing time. Default value is 128.
200 · tracing_threshold_queue_flush_interval=SECONDS: Flush interval for
202 spans with total time over threshold in default tracer. This is the
203 time the tracer will wait between repeated attempts to flush
204 threshold queue. Default value is 10 seconds.
205 · tracing_threshold_queue_size=NUMBER: Size of threshold queue in
207 default tracer. Queues in default tracer has fixed size, and it
208 will remove information about older spans, when the limit will be
209 reached before flushing time. Default value is 128.
210 · tracing_threshold_kv=SECONDS: Minimum time for the tracing span of
212 KV service to be considered by threshold tracer. Default value is
213 0.5 seconds.
214 · tracing_threshold_n1ql=SECONDS: Minimum time for the tracing span
216 of N1QL service to be considered by threshold tracer. Default value
217 is 1 second.
218 · tracing_threshold_view=SECONDS: Minimum time for the tracing span
220 of VIEW service to be considered by threshold tracer. Default value
221 is 1 second.
222 · tracing_threshold_fts=SECONDS: Minimum time for the tracing span of
224 FTS service to be considered by threshold tracer. Default value is
225 1 second.
226 · tracing_threshold_analytics=SECONDS: Minimum time for the tracing
228 span of ANALYTICS service to be considered by threshold tracer.
229 Default value is 1 second.
230
234 The following will create a file with 3 queries and 5 threads alternat‐
235 ing between them. It also creates indexes on the travel-sample bucket
236 cbc n1ql -U couchbase://192.168.72.101/a_bucket ´CREATE INDEX ix_name ON `travel-sample`(name)´
240 cbc n1ql -U couchbase://192.168.72.101/a_bucket ´CREATE INDEX ix_country ON `travel-sample`(country)´
241 cat queries.txt <<EOF
243 {"statement":"SELECT country FROM `travel-sample` WHERE `travel-sample`.country = \"United States\""}
244 {"statement":"SELECT name FROM `travel-sample` LIMIT 10"}
245 {"statement":"SELECT country, COUNT(country) FROM `travel-sample` GROUP BY country"}
246 EOF
247 cbc-n1qlback -U couchbase://192.168.72.101/a_bucket -t 5 -f queries.txt
249
253 This command´s options are subject to change.
254
256 cbc(1), cbc-pillowfight(1), cbcrc(4)
257
259 The cbc-n1qlback tool was first introduced in libcouchbase 2.4.10
260 October 2018 CBC-N1QLBACK(1)