Make benchmarks and flame graphs more visible (#1454)

Also: add summary in performance section

docs/index.md

@@ -165,6 +165,9 @@ Want to see your company here? [Submit a PR](https://github.com/zio/zio-kafka/ed
 
 ## Performance
 
+Often, _zio-kafka programs consume with a higher throughput_ than programs that use the java-kafka client directly.
+Read on for the details.
+
 By default, zio-kafka programs process partitions in parallel. The default java-kafka client does not provide parallel
 processing. Of course, there is some overhead in buffering records and distributing them to the fibers that need them.
 On 2024-11-23, we estimated that zio-kafka consumes faster than the java-kafka client when processing takes more than
@@ -174,3 +177,7 @@ details.
 
 If you do not care for the convenient ZStream based API that zio-kafka brings, and latency is of absolute importance,
 using the java based Kafka client directly is still the better choice.
+
+## Developers
+
+* [Benchmarks and Flame graphs](https://github.com/zio/zio-kafka/blob/master/zio-kafka-bench/README.md)

zio-kafka-bench/README.md

@@ -1,12 +1,21 @@
-# Comparison Benchmarks
+# Benchmarks and Flame graphs
 
-## Results
+## Benchmark results
 
-The benchmark are run from a GitHub action on every commit. The results are published
+The benchmarks are run from a GitHub action on every commit. The results are published
 on https://zio.github.io/zio-kafka/dev/bench/.
 
 The results are automatically pruned by [a scala script](https://github.com/zio/zio-kafka/blob/gh-pages/scripts/prune-benchmark-history.sc) on the `gh-pages` branch.
 
+## Flame graphs results
+
+Flame graphs are created by the `profile` GitHub action which runs on every release (it can also be started manually).
+The results are published on https://zio.github.io/zio-kafka/dev/profile/.
+
+The results are automatically pruned by [a scala script](https://github.com/zio/zio-kafka/blob/gh-pages/scripts/prune-flame-graph.sc) on the `gh-pages` branch.
+
+# Benchmark descriptions
+
 ## The consumer benchmarks
 
 When comparing the zio-kafka benchmarks against the regular Kafka clients, keep in mind that these benchmarks represent
@@ -59,7 +68,7 @@ Sequentially produces 100 small records.
 
 Produces 100 small records from 4 fibers.
 
-## How to run the benchmarks
+# How to run the benchmarks
 
 To run these "comparison" benchmarks, in a sbt console, run:
 
@@ -72,7 +81,7 @@ zioKafkaBench/Jmh/run -wi 10 -i 10 -r 1 -w 1 -t 1 -f 5 -foe true .*comparison.*
 The `.*comparison.*` part is the selector telling to JMH which benchmarks to run.
 Here, we're only selecting the ones living in the `comparison` package.
 
-## Tuning JMH runs
+# Tuning JMH runs
 
 To list all possible options and understand these configurations, see run `sbt "zioKafkaBench/Jmh/run -h"`