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 For example, the following line shows how to use named parameter
31 {"statement":"SELECT RAW meta().id FROM `travel-sample` WHERE type=$type LIMIT 1", "$type":"airline"}
35 There is also special query option, "n1qlback", which is stripped be‐
39 fore sending the payload. Currently it allows to tell if the particular
40 query must be prepared before execution:
41 {"statement":"SELECT * FROM `travel-sample` WHERE type=$type LIMIT 10", "$type":"airline", "n1qlback": {"prepare": true}}
45 n1qlback requires that any resources (data items, indexes) are already
49 defined.
50
52 The following options control workload generation:
53 -f --queryfile=PATH
55 Path to a file containing the query bodies to execute in JSON
56 format, one query per line. See above for the format.
57 -t, --num-threads=NTHREADS
59 Set the number of threads (and thus the number of client in‐
60 stances) to run concurrently. Each thread is assigned its own
61 client object.
62 The following options control how cbc-n1qlback connects to the cluster
64 -U, --spec=SPEC
66 A string describing the cluster to connect to. The string is in
67 a URI-like syntax, and may also contain other options. See the
68 EXAMPLES section for information. Typically such a URI will look
69 like couchbase://host1,host2,host3/bucket.
70 The default for this option is couchbase://localhost/default
72 -u, --username=USERNAME
74 Specify the username for the bucket. Since Couchbase 5.x this is
75 mandatory switch, and it must specify the name of the user ex‐
76 isiting on cluster (read more at "Security/Authorization" sec‐
77 tion of the server manual). For older servers this field should
78 be either left empty or set to the name of the bucket itself.
79 -P, --password=PASSWORD:
81 -P -, --password=-
84 Specify the password for the bucket. As for servers before 5.x
85 this was only needed if the bucket is protected with a password.
86 For cluster version after 5.x, the password is mandatory, and
87 should match the selected account (read more at "Security/Autho‐
88 rization" section of the server manual).
89 Specifying the - as the password indicates that the program
91 should prompt for the password. You may also specify the pass‐
92 word on the commandline, directly, but is insecure as command
93 line arguments are visible via commands such as ps.
94 -T, --timings
96 Dump command timings at the end of execution. This will display
97 a histogram showing the latencies for the commands executed.
98 -v, --verbose
100 Specify more information to standard error about what the client
101 is doing. You may specify this option multiple times for in‐
102 creased output detail.
103 -D, --cparam=OPTION=VALUE
105 Provide additional client options. Acceptable options can also
106 be placed in the connection string, however this option is pro‐
107 vided as a convenience. This option may be specified multiple
108 times, each time specifying a key=value pair (for example, -Dop‐
109 eration_timeout=10 -Dconfig_cache=/foo/bar/baz). See ADDITIONAL
110 OPTIONS for more information
111 -y, --compress
113 Enable compressing of documents. When the library is compiled
114 with compression support, this option will enable Snappy com‐
115 pression for outgoing data. Incoming compressed data handled au‐
116 tomatically regardless of this option. Note, that because the
117 compression support have to be negotiated with the server, first
118 packets might be sent uncompressed even when this switch was
119 specified. This is because the library might queue data commands
120 before socket connection has been established, and the library
121 will negotiate compression feature. If it is known that all
122 server support compression repeating the switch (like -yy) will
123 force compression for all outgoing mutations, even scheduled be‐
124 fore establishing connection.
125 --truststorepath=PATH
127 The path to the server´s SSL certificate. This is typically re‐
128 quired for SSL connectivity unless the certificate has already
129 been added to the OpenSSL installation on the system (only ap‐
130 plicable with couchbases:// scheme)
131 --certpath=PATH
133 The path to the server´s SSL certificate. This is typically re‐
134 quired for SSL connectivity unless the certificate has already
135 been added to the OpenSSL installation on the system (only ap‐
136 plicable with couchbases:// scheme). This also should contain
137 client certificate when certificate authentication used, and in
138 this case other public certificates could be extracted into
139 truststorepath chain.
140 --keypath=PATH
142 The path to the client SSL private key. This is typically re‐
143 quired for SSL client certificate authentication. The certifi‐
144 cate itself have to go first in chain specified by certpath
145 (only applicable with couchbases:// scheme)
146 --dump Dump verbose internal state after operations are done.
148 -e, --error-log=PATH
150 Path to a file, where the command will write failed queries
151 along with error details. Use this option to figure out why ER‐
152 RORS metric is not zero.
153
155 The following options may be included in the connection string (via the
156 -U option) as URI-style query params (e.g. couchbase://host/bucket?op‐
157 tion1=value1&option2=value2) or as individual key=value pairs passed to
158 the -D switch (e.g. -Doption1=value1 -Doption2=value). The -D will in‐
159 ternally build the connection string, and is provided as a convenience
160 for options to be easily passed on the command-line
161 • operation_timeout=SECONDS: Specify the operation timeout in sec‐
163 onds. This is the time the client will wait for an operation to
164 complete before timing it out. The default is 2.5
165 • config_cache=PATH: Enables the client to make use of a file based
167 configuration cache rather than connecting for the bootstrap opera‐
168 tion. If the file does not exist, the client will first connect to
169 the cluster and then cache the bootstrap information in the file.
170 • truststorepath=PATH: The path to the server´s SSL certificate. This
172 is typically required for SSL connectivity unless the certificate
173 has already been added to the OpenSSL installation on the system
174 (only applicable with couchbases:// scheme)
175 • certpath=PATH: The path to the server´s SSL certificate. This is
177 typically required for SSL connectivity unless the certificate has
178 already been added to the OpenSSL installation on the system (only
179 applicable with couchbases:// scheme). This also should contain
180 client certificate when certificate authentication used, and in
181 this case other public certificates could be extracted into trust‐
182 storepath chain.
183 • keypath=PATH: The path to the client SSL private key. This is typi‐
185 cally required for SSL client certificate authentication. The cer‐
186 tificate itself have to go first in chain specified by certpath
187 (only applicable with couchbases:// scheme)
188 • ipv6=allow: Enable IPv6.
190 • ssl=no_verify: Temporarily disable certificate verification for SSL
192 (only applicable with couchbases:// scheme). This should only be
193 used for quickly debugging SSL functionality.
194 • sasl_mech_force=MECHANISM: Force a specific SASL mechanism to be
196 used when performing the initial connection. This should only need
197 to be modified for debugging purposes. The currently supported
198 mechanisms are PLAIN and CRAM-MD5
199 • bootstrap_on=<both,http,cccp>: Specify the bootstrap protocol the
201 client should use when attempting to connect to the cluster. Op‐
202 tions are: cccp: Bootstrap using the Memcached protocol (supported
203 on clusters 2.5 and greater); http: Bootstrap using the HTTP REST
204 protocol (supported on any cluster version); and both: First at‐
205 tempt bootstrap over the Memcached protocol, and use the HTTP pro‐
206 tocol if Memcached bootstrap fails. The default is both
207 • enable_tracing=true/false: Activate/deactivate end-to-end tracing.
209 • tracing_orphaned_queue_flush_interval=SECONDS: Flush interval for
211 orphaned spans queue in default tracer. This is the time the tracer
212 will wait between repeated attempts to flush most recent orphaned
213 spans. Default value is 10 seconds.
214 • tracing_orphaned_queue_size=NUMBER: Size of orphaned spans queue in
216 default tracer. Queues in default tracer has fixed size, and it
217 will remove information about older spans, when the limit will be
218 reached before flushing time. Default value is 128.
219 • tracing_threshold_queue_flush_interval=SECONDS: Flush interval for
221 spans with total time over threshold in default tracer. This is the
222 time the tracer will wait between repeated attempts to flush
223 threshold queue. Default value is 10 seconds.
224 • tracing_threshold_queue_size=NUMBER: Size of threshold queue in de‐
226 fault tracer. Queues in default tracer has fixed size, and it will
227 remove information about older spans, when the limit will be
228 reached before flushing time. Default value is 128.
229 • tracing_threshold_kv=SECONDS: Minimum time for the tracing span of
231 KV service to be considered by threshold tracer. Default value is
232 0.5 seconds.
233 • tracing_threshold_query=SECONDS: Minimum time for the tracing span
235 of QUERY service to be considered by threshold tracer. Default
236 value is 1 second.
237 • tracing_threshold_view=SECONDS: Minimum time for the tracing span
239 of VIEW service to be considered by threshold tracer. Default value
240 is 1 second.
241 • tracing_threshold_search=SECONDS: Minimum time for the tracing span
243 of SEARCH service to be considered by threshold tracer. Default
244 value is 1 second.
245 • tracing_threshold_analytics=SECONDS: Minimum time for the tracing
247 span of ANALYTICS service to be considered by threshold tracer. De‐
248 fault value is 1 second.
249
253 The following will create a file with 3 queries and 5 threads alternat‐
254 ing between them. It also creates indexes on the travel-sample bucket
255 cbc n1ql ´CREATE INDEX ix_name ON `travel-sample`(name)´
259 cbc n1ql ´CREATE INDEX ix_country ON `travel-sample`(country)´
260 Crete text file queries.txt with the following content (note that
264 fourth query has parameter)
265 {"statement":"SELECT country FROM `travel-sample` WHERE `travel-sample`.country = \"United States\""}
269 {"statement":"SELECT name FROM `travel-sample` LIMIT 10"}
270 {"statement":"SELECT country, COUNT(country) FROM `travel-sample` GROUP BY country"}
271 {"statement":"SELECT RAW meta().id FROM `travel-sample` WHERE type=$type LIMIT 1", "$type":"airline", "n1qlback": {"prepare": true}}
272 Run the test load
276 cbc-n1qlback --num-threads 5 --queryfile queries.txt
280
284 This command´s options are subject to change.
285
287 cbc(1), cbc-pillowfight(1), cbcrc(4)
288
290 The cbc-n1qlback tool was first introduced in libcouchbase 2.4.10
291 December 2020 CBC-N1QLBACK(1)