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. : 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 ..." until the cursor returns 0, then restarts. Requires --pipeline 1. Stats are reported separately for "SCAN 0" and "SCAN ". --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)