dreadis

Overview ¶

Command dreadis is an automated tester of RESP-compatible, Redis-like servers.

It supports JSON files that describe the commands to execute, and can run those scenarios concurrently, with or without pipelining, repeatedly for a given duration or a given number of iterations.

It can optionnally print the replies from the server, so that they can be consulted, redirected to a file or piped to a hashing command for quick verification of the correctness of the results.

Usage ¶

An example command-line usage is:

dreadis -c 10 -n 5 -t 30s FILES...

dreadis supports the following flags:

-c : number of concurrent client connections, defaults to 1.
-n : number of iterations over the commands in the source files, defaults to 0, which
     means run each command once, or until -t is reached, if a timeout is set.
-t : maximum duration of the test, defaults to 0 (no time limit).
-o : output file to log the replies, defaults to stdout.
-f : format of the output, using the syntax of the Go package text/template.
     Defaults to the predefined stats output.

-net   : network type, defaults to "tcp".
-addr  : network address, defaults to ":6379".
-flush : flush the DB before running the test. Issues a FLUSHALL command.

If -n is 0 (its default) and -t is specified, each client will iterate over its source file for this duration. If both -n and -t are specified, it will stop at the first threshold that is reached. If only -n is specified, it will run this number of iterations for each source file, without time limit.

FILES are JSON command files. Any number of source files may be specified, and they will be spread across the -c concurrent clients. The logic is simply to assign the first file to the first client, second file to the second client, etc. until all clients have at least one file, and all files are executed by at least one client.

So if -c = 1 and there is more than one file specified, the same client will execute all files in sequence. Conversely, if there are many clients and just one file, all clients will run the same file.

JSON command files ¶

The JSON command files have the following format:

[
    {"command": ["arg1", "arg2", 2, 3.45]},
    [
        {"pipelined_cmd1": ["arg1", "arg2"]},
        {"pipelined_cmd2": ["arg1"]}
    ]
]

Objects on the top-level array are straight commands, executed without pipelining. The object must have a single key, the command name, and its value is an array of arguments to pass to the command.

Array values on the top-level array hold the same kind of object values, each representing a command to execute, but those commands are pipelined.

Special placeholders can be used in the string arguments. Those placeholders have the following meaning:

%c : replaced with the client id.
%u : replaced with a random UUID, newly generated on each execution of the command.
%d : a random integer, newly generated on each execution of the command.

Results ¶

Each client stores the replies from the server, and since clients and commands within a client are created and executed in a well-defined order, results can be deterministic and so can be validated against a reference implementation (i.e. against the official Redis server).

There are caveats to be aware of when comparing results. When the -t flag is set, commands may stop at an arbitrary position. When dynamic placeholders %u or %d are used, the results are very likely to be different from one execution to another. Also, some commands such as TIME will return different results at different times, by definition.

The command produces various statistics, available for the -f output format and printed by the stats predefined format:

Clients: <number of concurrent clients, the -c flag>
Duration: <actual execution duration, which may be different than the -t flag>
Iterations: <number of iteration in the files, the -n flag>
Commands: <number of commands executed>
Errors: <number of errors received from the server>