From db8fbc7a5f873b3bc9ea8050fc0c3b1e845e92d6 Mon Sep 17 00:00:00 2001
From: Bodigrim <andrew.lelechenko@gmail.com>
Date: Wed, 3 Jul 2024 00:07:38 +0100
Subject: [PATCH] Explain what GC numbers mean

---
 README.md               | 22 ++++++++++++++++++++--
 src/Test/Tasty/Bench.hs | 25 +++++++++++++++++++++++--
 2 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 0deb8aa..07ecc21 100644
--- a/README.md
+++ b/README.md
@@ -227,8 +227,26 @@ All
 All 3 tests passed (7.25s)
 ```
 
-This data is reported as per `RTSStats` fields: `allocated_bytes`, `copied_bytes`
-and `max_mem_in_use_bytes`.
+This data is reported as per [`GHC.Stats.RTSStats`](https://hackage.haskell.org/package/base/docs/GHC-Stats.html#t:RTSStats) fields:
+
+* `allocated_bytes`
+
+  Total size of data ever allocated since the start
+  of the benchmark iteration. Even if data was immediately
+  garbage collected and freed, it still counts.
+
+* `copied_bytes`
+
+  Total size of data ever copied by GC (because it was alive and kicking)
+  since the start of the benchmark iteration. Note that zero bytes often mean
+  that the benchmark was too short to trigger GC at all.
+
+* `max_mem_in_use_bytes`
+
+  Peak size of live data since the very start of the process.
+  This is a global metric, it cumulatively grows and does not say much
+  about individual benchmarks, but rather characterizes heap
+  environment in which they are executed.
 
 ## Combining tests and benchmarks
 
diff --git a/src/Test/Tasty/Bench.hs b/src/Test/Tasty/Bench.hs
index fa357e0..555bef5 100644
--- a/src/Test/Tasty/Bench.hs
+++ b/src/Test/Tasty/Bench.hs
@@ -204,8 +204,29 @@ report memory usage:
 >
 > All 3 tests passed (7.25s)
 
-This data is reported as per 'RTSStats' fields: 'allocated_bytes',
-'copied_bytes' and 'max_mem_in_use_bytes'.
+This data is reported as per
+<https://hackage.haskell.org/package/base/docs/GHC-Stats.html#t:RTSStats GHC.Stats.RTSStats>
+fields:
+
+-   'allocated_bytes'
+
+    Total size of data ever allocated since the start of the benchmark
+    iteration. Even if data was immediately garbage collected and freed,
+    it still counts.
+
+-   'copied_bytes'
+
+    Total size of data ever copied by GC (because it was alive and
+    kicking) since the start of the benchmark iteration. Note that zero
+    bytes often mean that the benchmark was too short to trigger GC at
+    all.
+
+-   'max_mem_in_use_bytes'
+
+    Peak size of live data since the very start of the process. This is
+    a global metric, it cumulatively grows and does not say much about
+    individual benchmarks, but rather characterizes heap environment in
+    which they are executed.
 
 === Combining tests and benchmarks