simplify example, document it

Author: lovromazgon

README.md

@@ -40,20 +40,35 @@ curl https://raw.githubusercontent.com/ConduitIO/benchi/main/install.sh | sh
 
 ### Running Benchmarks
 
-To run the example benchmark, use the following command:
+The repository includes an [example benchmark](./example). Use the following
+command to run the benchmark:
 
 ```sh
 benchi -config ./example/bench-kafka-kafka/bench.yaml
 ```
 
+Running the benchmark will store the results in the `results` folder. Inside the
+results folder, you will find a folder named after the current date and time
+(e.g. `results/20060102_150405`). This folder will contain logs and results:
+
+- `benchi.log`: Log file containing the output of the benchmark run.
+- `infra.log`: Log file containing the output of the infrastructure docker containers.
+- `tools.log`: Log file containing the output of the tools docker containers.
+- `conduit.csv`: Metrics collected using the [Conduit](#conduit) collector.
+- `docker.csv`: Metrics collected using the [Docker](#docker) collector.
+- `kafka.csv`: Metrics collected using the [Kafka](#kafka) collector.
+
+For details about the example benchmark, see the
+[example README](./example/README.md).
+
 ### Command-Line Flags
 
 - `-config`: Path to the benchmark config file (required).
 - `-out`: Path to the output folder (default: `./results/${now}`*).
 - `-tool`: Filter tool to be tested (can be provided multiple times).
 - `-tests`: Filter test to run (can be provided multiple times).
 
-\* `${now}` is replaced with the current time formatted as `YYYYMMDDHHMMSS`.
+\* `${now}` is replaced with the current time formatted as `YYYYMMDD_HHMMSS`.
 
 ### Docker network
 

example/README.md

@@ -0,0 +1,42 @@
+# Benchi example
+
+This folder includes an example of how to use Benchi. We use the following
+folder structure:
+
+- `infra`: Contains the Docker compose files for any infrastructure needed for
+  the benchmarks. These are supposed to contain configurations that are common
+  to all benchmarks. The specifics will be overridden by the benchmarks
+  themselves.
+- `tools`: Contains the Docker compose files for the tools being benchmarked.
+  Same as `infra`, these are supposed to contain configurations common to all
+  benchmarks.
+- `bench-kafka-kafka`: Contains a specific benchmark configuration
+  ([`bench.yml`](./bench-kafka-kafka/bench.yml)) for testing a kafka->kafka
+  data pipeline. It also includes any overrides for the `infra` and `tools`
+  configurations.
+
+You can run the example benchmark by running the following command:
+
+```sh
+benchi -config example/bench-kafka-kafka/bench.yml
+```
+
+Running this benchmark will start a Kafka instance, create two test topics
+(`benchi-in` and `benchi-out`), produce test messages to one topic and then
+start a Conduit data pipeline configured to consume messages from the first
+topic and produce them to the second topic. The benchmark will run for 1 minute.
+While the benchmark is running, benchi will collect metrics from Kafka, Conduit
+and Docker, displaying them in the CLI. After the benchmark is complete, the
+metrics will be exported to CSV files in the output folder (e.g.
+`results/20060102_150405`).
+
+Benchi will store the results in the `results` folder. Inside the results folder,
+you will find a folder named after the current date and time (e.g.
+`results/20060102_150405`). This folder will contain logs and results:
+
+- `benchi.log`: Log file containing the output of the benchmark run.
+- `infra.log`: Log file containing the output of the infrastructure docker containers.
+- `tools.log`: Log file containing the output of the tools docker containers.
+- `conduit.csv`: Metrics collected using the [Conduit](../README.md#conduit) collector.
+- `docker.csv`: Metrics collected using the [Docker](../README.md##docker) collector.
+- `kafka.csv`: Metrics collected using the [Kafka](../README.md##kafka) collector.

example/bench-kafka-kafka/bench.yml

@@ -3,8 +3,6 @@ infrastructure:
     compose: ../infra/compose-kafka.yml
 
 tools:
-  kafka-connect:
-    compose: ../tools/compose-kafka-connect.yml
   conduit:
     compose: ../tools/compose-conduit.yml
 
@@ -26,8 +24,6 @@ metrics:
         - "benchi-out"
   docker:
     collector: docker
-    tools:
-      - conduit
     settings:
       containers:
         - "benchi-kafka"