memtier_benchmark.1

.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
.TH MEMTIER_BENCHMARK "1" "June 2026" "memtier_benchmark v=255.255.255 sha=e69fc22c:0 bits=64 libevent=2.1.12-stable openssl=OpenSSL 3.0.13 30 Jan 2024 prometheus=yes" "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\-\-cluster\-mode\fR
Run client in cluster mode
.TP
\fB\-\-transaction\fR
In \fB\-\-cluster\-mode\fR, pin one full rotation of \fB\-\-command\fR entries to
a single shard connection so that keyless commands (MULTI/EXEC/
UNWATCH) stay on the same connection as the keyed ones. Hash\-tag
your keys so they map to the same slot, otherwise the cross\-slot
keyed commands of the same rotation will get MOVED back. In
standalone mode this flag is a no\-op (each client already runs
through a single connection). Requires at least one \fB\-\-command\fR.
\fB\-\-pipeline\fR > 1 is supported: each rotation is sent contiguously
on its pinned connection, so multiple whole transactions can be
in flight without interleaving MULTI/EXEC blocks.
Note: if \fB\-\-reconnect\-on\-error\fR triggers mid\-rotation, the
interrupted rotation's stats will be inaccurate (server\-side
WATCH/MULTI state is lost on reconnect).
.TP
\fB\-h\fR, \fB\-\-help\fR
Display this help
.TP
\fB\-v\fR, \fB\-\-version\fR
Display version information
.SS "Results Output Options:"
.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\-\-client\-stats\fR=\fI\,FILE\/\fR
Produce per\-client stats file
.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\-\-realtime\-latencies\fR
Replace the periodic single\-line progress output with a per\-tick block: line 1 = throughput + miss ratio, then one or more latency lines carrying the percentiles configured by \fB\-\-print\-percentiles\fR (immediate and overall, side\-by\-side). Redraws in place on a TTY; appends cleanly when stderr is redirected to a file.
.TP
\fB\-\-command\-stats\-breakdown\fR=\fI\,command\/\fR|line
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
.TP
\fB\-\-command\-miss\-tracking\fR=\fI\,auto\/\fR|off
Track per\-key cache misses for arbitrary commands (default: auto)
auto: enable for commands with known reply shape (GET, MGET, HGET, HMGET, GETEX, EXISTS, ...)
off:  disable; mb.json will not contain per\-arbitrary\-command Hits/Misses fields
.TP
\fB\-\-miss\-rate\-threshold\fR=\fI\,PERCENTAGE\/\fR
Warn when miss rate exceeds this percentage (default: 1.0).
Accepts fractional values, e.g. 0.5 for half a percent.
0 warns on any miss.
.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\-\-prometheus\-port\fR=\fI\,PORT\/\fR
Serve Prometheus metrics on this port at \fI\,/metrics\/\fP (default: disabled; 0 = ephemeral port)
.TP
\fB\-\-prometheus\-bind\-addr\fR=\fI\,ADDR\/\fR
Numeric IPv4/IPv6 address to bind the Prometheus exporter to (default: 127.0.0.1; hostnames not supported)
.TP
\fB\-\-prometheus\-run\-label\fR=\fI\,KEY=VALUE\/\fR
Add a constant label to every Prometheus metric (repeatable; max 16)
.TP
\fB\-\-prometheus\-latency\-buckets\fR=\fI\,LIST\/\fR
Comma\-separated, strictly ascending latency histogram bounds in seconds (default: built\-in 26\-bound list). Bounds closer than 1% of their value collapse to the same histogram slot and are rejected
.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)
.HP
\fB\-\-max\-reconnect\-attempts\fR=\fI\,NUM\/\fR Maximum number of reconnection attempts (default: 0, unlimited)
.HP
\fB\-\-reconnect\-backoff\-factor\fR=\fI\,NUM\/\fR Backoff factor for reconnection delays (default: 0, no backoff)
.TP
\fB\-\-retry\-on\-error\fR
Resend a request when the server returns a transient error or the
connection drops mid\-flight. Excludes permanent errors (WRONGTYPE,
NOAUTH, NOPERM, syntax/argcount/unknown\-command). Default: disabled.
.TP
\fB\-\-max\-retries\fR=\fI\,N\/\fR
Maximum retries per request when \fB\-\-retry\-on\-error\fR is set.
\fB\-1\fR = unlimited (default), 0 = disable retries even with the master
switch on, N>0 = bounded. MOVED/ASK redirects count toward this.
.TP
\fB\-\-retry\-backoff\-ms\fR=\fI\,NUM\/\fR
Delay between retries in milliseconds (default: 0, immediate).
.TP
\fB\-\-retry\-backoff\-factor\fR=\fI\,NUM\/\fR Exponential multiplier applied to retry\-backoff\-ms on each
successive retry (default: 0, constant backoff).
.TP
\fB\-\-retry\-on\fR=\fI\,LIST\/\fR
Restrict retries to error\-status prefixes in this comma list
(e.g. LOADING,BUSY,TRYAGAIN). Default: retry everything not
classified as permanent.
.TP
\fB\-\-max\-retry\-queue\fR=\fI\,NUM\/\fR
Hard cap on per\-connection retry queue depth. When full, the
pipeline stops accepting new work until the queue drains.
Default: 0 (auto = max(pipeline * 4, 64)).
.TP
\fB\-\-failed\-keys\-file\fR=\fI\,PATH\/\fR
Append every request that ultimately fails (retries exhausted or
permanent error) as CSV: timestamp,command,key,status,retries.
Off by default. The benchmark continues if the file is unwritable.
.TP
\fB\-\-connection\-timeout\fR=\fI\,SECS\/\fR
Connection timeout in seconds, 0 to disable (default: 0)
.TP
\fB\-\-connection\-stage\-timeout\fR=\fI\,SECS\/\fR
Abort with exit code 2 if no thread reaches steady state within
SECS, or if connection\-setup failures (AUTH / HELLO / SELECT /
CLUSTER SLOTS / \fB\-ERR\fR during initial probe) persist for SECS
without a successful handshake. Bounds the *startup* phase;
\fB\-\-test\-time\fR still bounds the steady\-state run. Default: 30,
0 disables the supervisor.
.HP
\fB\-\-thread\-conn\-start\-min\-jitter\-micros\fR=\fI\,NUM\/\fR Minimum jitter in microseconds between connection creation (default: 0)
.HP
\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).
In cluster mode, keys are probed from the key space so that all
keys in one batch route to the same shard (no hash\-tag prefix).
.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.
Z for zipf distribution (will limit keys to positive).
S for Sequential.
P for Parallel (Sequential were each client has a subset of the key\-range).
.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=\fI\,R\/\fR for random.
For example: \fB\-\-monitor\-input\fR=\fI\,monitor\/\fR.txt \fB\-\-command=\fR"__monitor_line1__"
.TP
\fB\-\-monitor\-pattern\fR=\fI\,S\/\fR|R
Pattern for selecting monitor commands (default: S for Sequential)
S for Sequential selection.
R for Random selection.
.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\-\-command\-is\-read\fR
Mark the preceding \fB\-\-command\fR as a read operation for
\fB\-\-read\-preference\fR routing (per\-command override).
.SS "Read Preference Options:"
.TP
\fB\-\-read\-preference\fR=\fI\,MODE\/\fR
Which node class receives read commands (default: primary).
primary           \- all reads go to the master/primary node
secondary         \- all reads go to replica nodes only
secondaryPreferred \- replicas preferred; fall back to primary
nearest           \- EWMA\-based selection: seed cold replicas
.TP
round\-robin until warm, then route reads
to the lowest\-EWMA endpoint among warm
replicas (primary may participate if it
has accumulated samples)
.TP
\fB\-\-read\-server\fR=\fI\,HOST\/\fR:PORT
Replica endpoint for standalone (non\-cluster) mode.
Repeatable; each occurrence adds one replica endpoint.
IPv6 addresses may be given as [::1]:6380.
NOTE: parsed but read dispatch is currently cluster\-only;
see README "Read Preference" section.
.TP
\fB\-\-replica\-clients\fR=\fI\,N\/\fR
Connections per replica per client thread (default: 0 = inherit
\fB\-\-clients\fR) (parsed but not yet wired \- see README
"Read Preference" section).
.TP
\fB\-\-replicas\-per\-shard\fR=\fI\,K\/\fR
Cap on replicas used per shard (default: 0 = all) (parsed but
not yet wired \- see README "Read Preference" section).
.TP
\fB\-\-read\-preference\-fallback\fR=\fI\,MODE\/\fR
What to do when the target node class is unavailable
(default: error).
error   \- return an error
queue   \- (reserved; currently treated as 'error' \- request
.TP
queuing not yet implemented)
primary \- fall back silently to the primary
.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.
R for uniform Random.
Z for zipf distribution (will limit keys to positive).
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)
Higher exponents result in higher concentration in top keys
(default is 1, though any number >2 seems insane)
.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\-2026 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.