Add README.md

benchmark/runall.sh

@@ -16,9 +16,9 @@ cargo bench --features stack_walking_tests -- --noplot
 # Run Trace Benchmarks
 cd ..
 make composer_tests_update
-## Non-OPCache Benchmarks > tests/Benchmarks/results.csv
+## Non-OPCache Benchmarks
 make benchmarks
-cp tests/Benchmarks/tracer-bench-results.csv "$ARTIFACTS_DIR"
-## OPCache Benchmarks > tests/Benchmarks/results-opcache.csv
+cp tests/Benchmarks/reports/tracer-bench-results.csv "$ARTIFACTS_DIR"
+## OPCache Benchmarks
 make benchmarks_opcache
-cp tests/Benchmarks/tracer-bench-results-opcache.csv "$ARTIFACTS_DIR"
+cp tests/Benchmarks/reports/tracer-bench-results-opcache.csv "$ARTIFACTS_DIR"

tests/Benchmarks/README.md

@@ -1 +1,45 @@
 # Benchmarks
+
+## How to run benchmarks
+
+First refer to the [CONTRIBUTING.md](../../CONTRIBUTING.md) file to setup the environment.
+
+Then you can run the benchmarks with the following command from the root of the repository:
+
+```bash
+make benchmarks
+```
+
+or if you want to run the benchmarks with OPcache enabled:
+
+```bash
+make benchmarks_opcache
+```
+
+## How to add a new benchmark
+
+The benchmarks are located in the [tests/Benchmarks](.) folder and are written using [PHPBench](https://github.com/phpbench/phpbench).
+
+To add a new benchmark, create a new file under the [tests/Benchmarks](.) folder. In order for the benchmarks to be executed, the file name and class name must be suffixed with `Bench`, and each benchmark method must be prefixed with `bench`.
+
+Then you can write your benchmark using the [PHPBench](https://phpbench.readthedocs.io/en/latest/quick-start.html#create-a-benchmark) syntax.
+
+## How to run a single benchmark
+
+You can run a single benchmark with the following command:
+
+```bash
+make benchmarks FILTER=<benchmark_name>
+```
+
+## How to run a single benchmark suite
+
+You can run a single benchmark suite with the following command:
+
+```bash
+make benchmarks FILTER=<benchmark_class_name>
+```
+
+## Results
+
+The results of the benchmarks, as defined in the [phpbench.json](../phpbench.json) (resp. [phpbench-opcache.json](../phpbench-opcache.json)) file, are store in the [tests/Benchmarks/reports](./reports) folder.

tests/phpbench-opcache.json

@@ -24,7 +24,7 @@
     "report.outputs": {
         "file": {
             "extends": "csv",
-            "file": "tests/Benchmarks/tracer-bench-results-opcache.csv",
+            "file": "tests/Benchmarks/reports/tracer-bench-results-opcache.csv",
             "delimiter": ","
         }
     }

tests/phpbench.json

@@ -17,7 +17,7 @@
     "report.outputs": {
         "file": {
             "extends": "csv",
-            "file": "tests/Benchmarks/tracer-bench-results.csv",
+            "file": "tests/Benchmarks/reports/tracer-bench-results.csv",
             "delimiter": ","
         }
     }