/usr/bin/memtier_benchmark

Usage: memtier_benchmark [options]
A memcache/redis NoSQL traffic generator and performance benchmarking tool.

Connection and General Options:
  -h, --host=ADDR                Server address (default: localhost)
  -s, --server=ADDR              Same as --host
  -p, --port=PORT                Server port (default: 6379)
  -S, --unix-socket=SOCKET       UNIX Domain socket name (default: none)
  -4, --ipv4                     Force IPv4 address resolution.
  -6  --ipv6                     Force IPv6 address resolution.
  -P, --protocol=PROTOCOL        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.
  -a, --authenticate=CREDENTIALS 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.
  -u, --uri=URI                  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'.
      --tls                      Enable SSL/TLS transport security
      --cert=FILE                Use specified client certificate for TLS
      --key=FILE                 Use specified private key for TLS
      --cacert=FILE              Use specified CA certs bundle for TLS
      --tls-skip-verify          Skip verification of server certificate
      --tls-protocols            Specify the tls protocol version to use, comma delemited. Use a combination of 'TLSv1', 'TLSv1.1', 'TLSv1.2' and 'TLSv1.3'.
      --sni=STRING               Add an SNI header
  -x, --run-count=NUMBER         Number of full-test iterations to perform
  -D, --debug                    Print debug output
      --cluster-mode             Run client in cluster mode
      --transaction              Treat one full rotation of --command entries as a transactional
                                 unit (e.g. WATCH/GET/MULTI/SETEX/EXEC/UNWATCH). Every __key__ in
                                 a rotation resolves to the same key (taken from the first keyed
                                 command's --command-key-pattern), so all keyed commands hit one
                                 key and one slot: the WATCH guards the key the SETEX writes and
                                 the unit runs without CROSSSLOT errors -- no hash-tag needed.
                                 This same-key behavior applies in every mode, so it also works
                                 against a single endpoint fronting a sharded backend (e.g. a
                                 Redis Enterprise proxy) where keyed commands must share a slot.
                                 In --cluster-mode it additionally pins the whole rotation to the
                                 owning shard connection so the keyless commands (MULTI/EXEC/
                                 UNWATCH) stay with the keyed ones. Caveat: keep the literal text
                                 around __key__ (including any {tag}) identical across keyed
                                 commands; differing affixes still hash to different slots.
                                 Requires at least one --command.
                                 --pipeline > 1 is supported: in --cluster-mode each rotation is
                                 sent contiguously on its pinned connection, so multiple whole
                                 transactions can be in flight without interleaving MULTI/EXEC.
                                 Note: if --reconnect-on-error triggers mid-rotation, the
                                 interrupted rotation's stats will be inaccurate (server-side
                                 WATCH/MULTI state is lost on reconnect).
  -h, --help                     Display this help
  -v, --version                  Display version information

Results Output Options:
  -o, --out-file=FILE            Name of output file (default: stdout)
      --json-out-file=FILE       Name of JSON output file, if not set, will not print to json
      --client-stats=FILE        Produce per-client stats file
      --hdr-file-prefix=FILE     Prefix of HDR Latency Histogram output files, if not set, will not save latency histogram files
      --show-config              Print detailed configuration before running
      --hide-histogram           Don't print detailed latency histogram
      --print-percentiles        Specify which percentiles info to print on the results table (by default prints percentiles: 50,99,99.9)
      --print-all-runs           When performing multiple test iterations, print and save results for all iterations
      --realtime-latencies       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 --print-percentiles (immediate and overall, side-by-side). Redraws in place on a TTY; appends cleanly when stderr is redirected to a file.
      --command-stats-breakdown=command|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
      --command-miss-tracking=auto|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
      --miss-rate-threshold=PERCENTAGE
                                 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.
      --cpu-warn-threshold=PERCENTAGE
                                 Warn when a memtier worker thread's CPU exceeds this percentage of a
                                 core (default: 95.0), indicating memtier itself may be the bottleneck
                                 and results may be unreliable. 0 warns on any CPU usage.
      --statsd-host=HOST         StatsD server hostname to send real-time metrics (default: none, disabled)
      --statsd-port=PORT         StatsD server UDP port (default: 8125)
      --statsd-prefix=PREFIX     Prefix for StatsD metric names (default: memtier)
      --statsd-run-label=LABEL   Label for this benchmark run, used to distinguish runs in dashboards (default: default)
      --graphite-port=PORT       Graphite HTTP port for event annotations (default: 8080 for host access; use 80 when running inside the Docker network)
      --prometheus-port=PORT     Serve Prometheus metrics on this port at /metrics (default: disabled; 0 = ephemeral port)
      --prometheus-bind-addr=ADDR  Numeric IPv4/IPv6 address to bind the Prometheus exporter to (default: 127.0.0.1; hostnames not supported)
      --prometheus-run-label=KEY=VALUE  Add a constant label to every Prometheus metric (repeatable; max 16)
      --prometheus-latency-buckets=LIST  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

Test Options:
  -n, --requests=NUMBER          Number of total requests per client (default: 10000)
                                 use 'allkeys' to run on the entire key-range
      --rate-limiting=NUMBER     The max number of requests to make per second from an individual connection (default is unlimited rate).
                                 If you use --rate-limiting and a very large rate is entered which cannot be met, memtier will do as many requests as possible per second.
  -c, --clients=NUMBER           Number of clients per thread (default: 50)
  -t, --threads=NUMBER           Number of threads (default: 4)
      --test-time=SECS           Number of seconds to run the test
      --clients-start=NUMBER     Starting number of clients per thread for staircase ramp-up.
                                 Must be less than --clients. Requires --clients-step and --step-duration.
      --clients-step=NUMBER      Number of clients to add per step in staircase ramp-up.
      --step-duration=SECS       Duration in seconds of each step before adding more clients.
      --ratio=RATIO              Set:Get ratio (default: 1:10)
      --pipeline=NUMBER          Number of concurrent pipelined requests (default: 1)
      --reconnect-interval=NUM   Number of requests after which re-connection is performed
      --reconnect-on-error       Enable automatic reconnection on connection errors (default: disabled)
      --max-reconnect-attempts=NUM Maximum number of reconnection attempts (default: 0, unlimited)
      --reconnect-backoff-factor=NUM Backoff factor for reconnection delays (default: 0, no backoff)
      --retry-on-error           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.
      --max-retries=N            Maximum retries per request when --retry-on-error is set.
                                 -1 = unlimited (default), 0 = disable retries even with the master
                                 switch on, N>0 = bounded. MOVED/ASK redirects count toward this.
      --retry-backoff-ms=NUM     Delay between retries in milliseconds (default: 0, immediate).
      --retry-backoff-factor=NUM Exponential multiplier applied to retry-backoff-ms on each
                                 successive retry (default: 0, constant backoff).
      --retry-on=LIST            Restrict retries to error-status prefixes in this comma list
                                 (e.g. LOADING,BUSY,TRYAGAIN). Default: retry everything not
                                 classified as permanent.
      --max-retry-queue=NUM      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)).
      --failed-keys-file=PATH    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.
      --connection-timeout=SECS  Connection timeout in seconds, 0 to disable (default: 0)
      --connection-stage-timeout=SECS
                                 Abort with exit code 2 if no thread reaches steady state within
                                 SECS, or if connection-setup failures (AUTH / HELLO / SELECT /
                                 CLUSTER SLOTS / -ERR during initial probe) persist for SECS
                                 without a successful handshake. Bounds the *startup* phase;
                                 --test-time still bounds the steady-state run. Default: 30,
                                 0 disables the supervisor.
      --thread-conn-start-min-jitter-micros=NUM Minimum jitter in microseconds between connection creation (default: 0)
      --thread-conn-start-max-jitter-micros=NUM Maximum jitter in microseconds between connection creation (default: 0)
      --multi-key-get=NUM        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).
      --select-db=DB             DB number to select, when testing a redis server
      --distinct-client-seed     Use a different random seed for each client
      --randomize                random seed based on timestamp (default is constant value)

Arbitrary command:
      --command=COMMAND          Specify a command to send in quotes.
                                 Each command that you specify is run with its ratio and key-pattern options.
                                 For example: --command="set __key__ 5" --command-ratio=2 --command-key-pattern=G
                                 To use a generated key or object, enter:
                                   __key__: Use key generated from Key Options.
                                   __data__: Use data generated from Object Options.
      --command-ratio            The number of times the command is sent in sequence.(default: 1)
      --command-key-pattern      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).
      --monitor-input=FILE       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 --monitor-pattern=R for random.
                                 For example: --monitor-input=monitor.txt --command="__monitor_line1__"
      --monitor-pattern=S|R      Pattern for selecting monitor commands (default: S for Sequential)
                                 S for Sequential selection.
                                 R for Random selection.
      --scan-incremental-iteration
                                 Enable SCAN cursor iteration mode. When used with
                                 --command="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 --pipeline 1.
                                 Stats are reported separately for "SCAN 0" and "SCAN <cursor>".
      --scan-incremental-max-iterations=NUMBER
                                 Maximum number of continuation SCANs per iteration cycle
                                 (default: 0, follow cursor until it returns 0).
      --command-is-read          Mark the preceding --command as a read operation for
                                 --read-preference routing (per-command override).

Read Preference Options:
      --read-preference=MODE     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
                                                     round-robin until warm, then route reads
                                                     to the lowest-EWMA endpoint among warm
                                                     replicas (primary may participate if it
                                                     has accumulated samples)
      --read-server=HOST: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.
      --replica-clients=N        Connections per replica per client thread (default: 0 = inherit
                                 --clients) (parsed but not yet wired - see README
                                 "Read Preference" section).
      --replicas-per-shard=K     Cap on replicas used per shard (default: 0 = all) (parsed but
                                 not yet wired - see README "Read Preference" section).
      --read-preference-fallback=MODE
                                 What to do when the target node class is unavailable
                                 (default: error).
                                 error   - return an error
                                 queue   - (reserved; currently treated as 'error' - request
                                           queuing not yet implemented)
                                 primary - fall back silently to the primary

Object Options:
  -d  --data-size=SIZE           Object data size in bytes (default: 32)
      --data-offset=OFFSET       Actual size of value will be data-size + data-offset
                                 Will use SETRANGE / GETRANGE (default: 0)
  -R  --random-data              Indicate that data should be randomized
      --data-size-range=RANGE    Use random-sized items in the specified range (min-max)
      --data-size-list=LIST      Use sizes from weight list (size1:weight1,..sizeN:weightN)
      --data-size-pattern=R|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 --key-maximum (default R)
      --expiry-range=RANGE       Use random expiry values from the specified range

Imported Data Options:
      --data-import=FILE         Read object data from file
      --data-verify              Enable data verification when test is complete
      --verify-only              Only perform --data-verify, without any other test
      --generate-keys            Generate keys for imported objects
      --no-expiry                Ignore expiry information in imported data

Key Options:
      --key-prefix=PREFIX        Prefix for keys (default: "memtier-")
      --key-minimum=NUMBER       Key ID minimum value (default: 0)
      --key-maximum=NUMBER       Key ID maximum value (default: 10000000)
      --key-pattern=PATTERN      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).
      --key-stddev               The standard deviation used in the Gaussian distribution
                                 (default is key range / 6)
      --key-median               The median point used in the Gaussian distribution
                                 (default is the center of the key range)
      --key-zipf-exp             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)

WAIT Options:
      --wait-ratio=RATIO         Set:Wait ratio (default is no WAIT commands - 1:0)
      --num-slaves=RANGE         WAIT for a random number of slaves in the specified range
      --wait-timeout=RANGE       WAIT for a random number of milliseconds in the specified range (normal
                                 distribution with the center in the middle of the range)