diff --git a/README.md b/README.md index b71acb4..f88b7a3 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,52 @@ # kvbench ![GitHub Workflow](https://github.com/nerdroychan/kvbench/actions/workflows/test.yml/badge.svg) -![GitHub Commit](https://img.shields.io/github/last-commit/nerdroychan/kvbench) ![GPLv3](https://img.shields.io/github/license/nerdroychan/kvbench) A benchmarking framework designed for testing key-value stores with easily customizable workloads. -With `kvbench`, you can define the details of a benchmark using the TOML format, such as the -proportions of mixed operations, the key access pattern, and key space size, just to name a -few. In addition to regular single-process benchmarks, `kvbench` also integrates a key-value -client/server implementation that works with a dedicated server thread/machine. +## Intro -You can also incorporate `kvbench` into your own key-value store implementations and run it -against the built-in stores. All you need is implementing the [`KVMap`] or the [`AsyncKVMap`] -trait, depending on the type of the store. After registering your store, simply reuse the -exported [`cmdline()`] in your `main` function and it will work seamlessly with your own store. +This Rust crate enables the execution of tailored benchmarks on various key-value stores. Users +have the flexibility to adjust benchmark and key-value store parameters and store them in a +TOML-formatted file. The default command line interface is capable of loading these files and +running the benchmarks as specified. -More detailed usage could be found in the module-level rustdocs. +In addition to standard single-process benchmarks, kvbench seamlessly incorporates a key-value +client/server setup that operates with a dedicated server thread/machine. + +## Usage + +Without any changes, you can run the default command line interface with three modes: + +- `kvbench bench -s -b ` runs a (group of) benchmark using the parameters +stored in `` and ``. +- `kvbench server -h -p -s -n ` boots up a key-value server +with `` workers, listening on `:`, and uses the key-value stores specified in +``. +- `kvbench list` lists all registered key-value stores that can be used. + +See [examples](examples/) for more examples. + +## Configuration + +See the documentation of the modules `stores` and `bench` for available options. + +## Integration + +You can incorporate `kvbench` into your own key-value store implementations and run it +against the built-in stores. All you need is implementing the necessary traits, depending on the +type of the store, and call the default command line interface provided by this crate. + +See [examples/your-kv-store](examples/your-kv-store) for a minimal but concrete example. + +## Development + +The missing pieces that are currently under active development: + +- Latency measurement (incl. CDF and tail/avg. latency metrics). +- Atomic Read-modify-write (RMW) support. +- More key-distributions (e.g., latest key, composite-zipfian). +- Ordered key-value stores support (range query workloads). +- Extra built-ins (e.g., YCSB workloads).