memtier_benchmark.1

.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
.TH MEMTIER_BENCHMARK "1" "November 2024" "memtier_benchmark 2.1.2" "User Commands"
.SH NAME
memtier_benchmark \- NoSQL benchmark tool
.SH SYNOPSIS
.B memtier_benchmark
[\fI\,options\/\fR]
.SH DESCRIPTION
A memcache/redis NoSQL traffic generator and performance benchmarking tool.
.SS "Connection and General Options:"
.TP
\fB\-h\fR, \fB\-\-host\fR=\fI\,ADDR\/\fR
Server address (default: localhost)
.TP
\fB\-s\fR, \fB\-\-server\fR=\fI\,ADDR\/\fR
Same as \fB\-\-host\fR
.TP
\fB\-p\fR, \fB\-\-port\fR=\fI\,PORT\/\fR
Server port (default: 6379)
.TP
\fB\-S\fR, \fB\-\-unix\-socket\fR=\fI\,SOCKET\/\fR
UNIX Domain socket name (default: none)
.TP
\fB\-4\fR, \fB\-\-ipv4\fR
Force IPv4 address resolution.
.TP
\fB\-6\fR  \fB\-\-ipv6\fR
Force IPv6 address resolution.
.TP
\fB\-P\fR, \fB\-\-protocol\fR=\fI\,PROTOCOL\/\fR
Protocol to use (default: redis).
other supported protocols are resp2, resp3, memcache_text and memcache_binary.
when using one of resp2 or resp3 the redis protocol version will be set via HELLO command.
.TP
\fB\-a\fR, \fB\-\-authenticate\fR=\fI\,CREDENTIALS\/\fR Authenticate using specified credentials.
A simple password is used for memcache_text
and Redis <= 5.x. <USER>:<PASSWORD> can be
specified for memcache_binary or Redis 6.x
or newer with ACL user support.
.TP
\fB\-u\fR, \fB\-\-uri\fR=\fI\,URI\/\fR
Server URI on format redis://user:password@host:port/dbnum
User, password and dbnum are optional. For authentication
without a username, use username 'default'. For TLS, use
the scheme 'rediss'.
.TP
\fB\-\-tls\fR
Enable SSL/TLS transport security
.TP
\fB\-\-cert\fR=\fI\,FILE\/\fR
Use specified client certificate for TLS
.TP
\fB\-\-key\fR=\fI\,FILE\/\fR
Use specified private key for TLS
.TP
\fB\-\-cacert\fR=\fI\,FILE\/\fR
Use specified CA certs bundle for TLS
.TP
\fB\-\-tls\-skip\-verify\fR
Skip verification of server certificate
.TP
\fB\-\-tls\-protocols\fR
Specify the tls protocol version to use, comma delemited. Use a combination of 'TLSv1', 'TLSv1.1', 'TLSv1.2' and 'TLSv1.3'.
.TP
\fB\-\-sni\fR=\fI\,STRING\/\fR
Add an SNI header
.TP
\fB\-x\fR, \fB\-\-run\-count\fR=\fI\,NUMBER\/\fR
Number of full\-test iterations to perform
.TP
\fB\-D\fR, \fB\-\-debug\fR
Print debug output
.TP
\fB\-\-client\-stats\fR=\fI\,FILE\/\fR
Produce per\-client stats file
.TP
\fB\-o\fR, \fB\-\-out\-file\fR=\fI\,FILE\/\fR
Name of output file (default: stdout)
.TP
\fB\-\-json\-out\-file\fR=\fI\,FILE\/\fR
Name of JSON output file, if not set, will not print to json
.TP
\fB\-\-hdr\-file\-prefix\fR=\fI\,FILE\/\fR
Prefix of HDR Latency Histogram output files, if not set, will not save latency histogram files
.TP
\fB\-\-show\-config\fR
Print detailed configuration before running
.TP
\fB\-\-hide\-histogram\fR
Don't print detailed latency histogram
.TP
\fB\-\-print\-percentiles\fR
Specify which percentiles info to print on the results table (by default prints percentiles: 50,99,99.9)
.TP
\fB\-\-print\-all\-runs\fR
When performing multiple test iterations, print and save results for all iterations
.TP
\fB\-\-cluster\-mode\fR
Run client in cluster mode
.TP
\fB\-\-statsd\-host\fR=\fI\,HOST\/\fR
StatsD server hostname to send real\-time metrics (default: none, disabled)
.TP
\fB\-\-statsd\-port\fR=\fI\,PORT\/\fR
StatsD server UDP port (default: 8125)
.TP
\fB\-\-statsd\-prefix\fR=\fI\,PREFIX\/\fR
Prefix for StatsD metric names (default: memtier)
.TP
\fB\-\-statsd\-run\-label\fR=\fI\,LABEL\/\fR
Label for this benchmark run, used to distinguish runs in dashboards (default: default)
.TP
\fB\-\-graphite\-port\fR=\fI\,PORT\/\fR
Graphite HTTP port for event annotations (default: 8080 for host access; use 80 when running inside the Docker network)
.TP
\fB\-h\fR, \fB\-\-help\fR
Display this help
.TP
\fB\-v\fR, \fB\-\-version\fR
Display version information
.SS "Test Options:"
.TP
\fB\-n\fR, \fB\-\-requests\fR=\fI\,NUMBER\/\fR
Number of total requests per client (default: 10000)
use 'allkeys' to run on the entire key\-range
.TP
\fB\-\-rate\-limiting\fR=\fI\,NUMBER\/\fR
The max number of requests to make per second from an individual connection (default is unlimited rate).
If you use \fB\-\-rate\-limiting\fR and a very large rate is entered which cannot be met, memtier will do as many requests as possible per second.
.TP
\fB\-c\fR, \fB\-\-clients\fR=\fI\,NUMBER\/\fR
Number of clients per thread (default: 50)
.TP
\fB\-t\fR, \fB\-\-threads\fR=\fI\,NUMBER\/\fR
Number of threads (default: 4)
.TP
\fB\-\-test\-time\fR=\fI\,SECS\/\fR
Number of seconds to run the test
.TP
\fB\-\-clients\-start\fR=\fI\,NUMBER\/\fR
Starting number of clients per thread for staircase ramp\-up.
Must be less than \fB\-\-clients\fR. Requires \fB\-\-clients\-step\fR and \fB\-\-step\-duration\fR.
.TP
\fB\-\-clients\-step\fR=\fI\,NUMBER\/\fR
Number of clients to add per step in staircase ramp\-up.
.TP
\fB\-\-step\-duration\fR=\fI\,SECS\/\fR
Duration in seconds of each step before adding more clients.
.TP
\fB\-\-ratio\fR=\fI\,RATIO\/\fR
Set:Get ratio (default: 1:10)
.TP
\fB\-\-pipeline\fR=\fI\,NUMBER\/\fR
Number of concurrent pipelined requests (default: 1)
.TP
\fB\-\-reconnect\-interval\fR=\fI\,NUM\/\fR
Number of requests after which re\-connection is performed
.TP
\fB\-\-reconnect\-on\-error\fR
Enable automatic reconnection on connection errors (default: disabled)
.TP
\fB\-\-max\-reconnect\-attempts\fR=\fI\,NUM\/\fR
Maximum number of reconnection attempts, 0 for unlimited (default: 0)
.TP
\fB\-\-reconnect\-backoff\-factor\fR=\fI\,NUM\/\fR
Backoff factor for reconnection delays, 0 for no backoff (default: 0)
.TP
\fB\-\-connection\-timeout\fR=\fI\,SECS\/\fR
Connection timeout in seconds, 0 to disable (default: 0)
.TP
\fB\-\-thread\-conn\-start\-min\-jitter\-micros\fR=\fI\,NUM\/\fR
Minimum jitter in microseconds between connection creation (default: 0)
.TP
\fB\-\-thread\-conn\-start\-max\-jitter\-micros\fR=\fI\,NUM\/\fR
Maximum jitter in microseconds between connection creation (default: 0)
.TP
\fB\-\-multi\-key\-get\fR=\fI\,NUM\/\fR
Enable multi\-key get commands, up to NUM keys (default: 0)
.TP
\fB\-\-select\-db\fR=\fI\,DB\/\fR
DB number to select, when testing a redis server
.TP
\fB\-\-distinct\-client\-seed\fR
Use a different random seed for each client
.TP
\fB\-\-randomize\fR
random seed based on timestamp (default is constant value)
.SS "Arbitrary command:"
.TP
\fB\-\-command\fR=\fI\,COMMAND\/\fR
Specify a command to send in quotes.
Each command that you specify is run with its ratio and key\-pattern options.
For example: \fB\-\-command=\fR"set __key__ 5" \fB\-\-command\-ratio\fR=\fI\,2\/\fR \fB\-\-command\-key\-pattern\fR=\fI\,G\/\fR
To use a generated key or object, enter:
.TP
__key__: Use key generated from Key Options.
__data__: Use data generated from Object Options.
.TP
\fB\-\-command\-ratio\fR
The number of times the command is sent in sequence.(default: 1)
.TP
\fB\-\-command\-key\-pattern\fR
Key pattern for the command (default: R):
G for Gaussian distribution.
R for uniform Random.
S for Sequential.
P for Parallel (Sequential were each client has a subset of the key\-range).
.TP
\fB\-\-scan\-incremental\-iteration\fR
Enable SCAN cursor iteration mode. When used with
\fB\-\-command\fR="SCAN 0 [MATCH pattern] [COUNT count] [TYPE type]",
automatically follows the cursor returned by each SCAN response.
Sends "SCAN 0 ..." initially, then "SCAN <cursor> ..." until the cursor
returns 0, then restarts. Requires \fB\-\-pipeline\fR 1.
Stats are reported separately for "SCAN 0" and "SCAN <cursor>".
.TP
\fB\-\-scan\-incremental\-max\-iterations\fR=\fI\,NUMBER\/\fR
Maximum number of continuation SCANs per iteration cycle
(default: 0, follow cursor until it returns 0).
.TP
\fB\-\-monitor\-input\fR=\fI\,FILE\/\fR
Read commands from Redis MONITOR output file.
Commands can be referenced as __monitor_line1__, __monitor_line2__, etc.
Use __monitor_line@__ to select commands from the file.
By default, selection is sequential; use \fB\-\-monitor\-pattern\fR=R for random.
For example: \fB\-\-monitor\-input\fR=monitor.txt \fB\-\-command\fR="__monitor_line1__"
.TP
\fB\-\-monitor\-pattern\fR=\fI\,S|R\/\fR
Pattern for selecting monitor commands (default: S for Sequential).
S for Sequential selection.
R for Random selection.
.TP
\fB\-\-command\-stats\-breakdown\fR=\fI\,command|line\/\fR
How to group command statistics in the output (default: command).
command: aggregate by command name (first word, e.g., SET, GET).
line: show each command line separately.
.SS "Object Options:"
.TP
\fB\-d\fR  \fB\-\-data\-size\fR=\fI\,SIZE\/\fR
Object data size in bytes (default: 32)
.TP
\fB\-\-data\-offset\fR=\fI\,OFFSET\/\fR
Actual size of value will be data\-size + data\-offset
Will use SETRANGE / GETRANGE (default: 0)
.TP
\fB\-R\fR  \fB\-\-random\-data\fR
Indicate that data should be randomized
.TP
\fB\-\-data\-size\-range\fR=\fI\,RANGE\/\fR
Use random\-sized items in the specified range (min\-max)
.TP
\fB\-\-data\-size\-list\fR=\fI\,LIST\/\fR
Use sizes from weight list (size1:weight1,..sizeN:weightN)
.TP
\fB\-\-data\-size\-pattern\fR=\fI\,R\/\fR|S
Use together with data\-size\-range
when set to R, a random size from the defined data sizes will be used,
when set to S, the defined data sizes will be evenly distributed across
the key range, see \fB\-\-key\-maximum\fR (default R)
.TP
\fB\-\-expiry\-range\fR=\fI\,RANGE\/\fR
Use random expiry values from the specified range
.SS "Imported Data Options:"
.TP
\fB\-\-data\-import\fR=\fI\,FILE\/\fR
Read object data from file
.TP
\fB\-\-data\-verify\fR
Enable data verification when test is complete
.TP
\fB\-\-verify\-only\fR
Only perform \fB\-\-data\-verify\fR, without any other test
.TP
\fB\-\-generate\-keys\fR
Generate keys for imported objects
.TP
\fB\-\-no\-expiry\fR
Ignore expiry information in imported data
.SS "Key Options:"
.TP
\fB\-\-key\-prefix\fR=\fI\,PREFIX\/\fR
Prefix for keys (default: "memtier\-")
.TP
\fB\-\-key\-minimum\fR=\fI\,NUMBER\/\fR
Key ID minimum value (default: 0)
.TP
\fB\-\-key\-maximum\fR=\fI\,NUMBER\/\fR
Key ID maximum value (default: 10000000)
.TP
\fB\-\-key\-pattern\fR=\fI\,PATTERN\/\fR
Set:Get pattern (default: R:R)
G for Gaussian distribution.
Z for Zipfian distribution (will limit keys to positive).
R for uniform Random.
S for Sequential.
P for Parallel (Sequential were each client has a subset of the key\-range).
.TP
\fB\-\-key\-stddev\fR
The standard deviation used in the Gaussian distribution
(default is key range / 6)
.TP
\fB\-\-key\-median\fR
The median point used in the Gaussian distribution
(default is the center of the key range)
.TP
\fB\-\-key\-zipf\-exp\fR
The exponent used in the zipf distribution, limit to (0, 5)
(default is 1, though any number >2 seems insane)\n
.SS "WAIT Options:"
.TP
\fB\-\-wait\-ratio\fR=\fI\,RATIO\/\fR
Set:Wait ratio (default is no WAIT commands \- 1:0)
.TP
\fB\-\-num\-slaves\fR=\fI\,RANGE\/\fR
WAIT for a random number of slaves in the specified range
.TP
\fB\-\-wait\-timeout\fR=\fI\,RANGE\/\fR
WAIT for a random number of milliseconds in the specified range (normal
distribution with the center in the middle of the range)
.SH COPYRIGHT
Copyright \(co 2011\-2024 Redis Ltd.
.br
This is free software.  You may redistribute copies of it under the terms of
the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
There is NO WARRANTY, to the extent permitted by law.