From ec276240375fcce4be223c82ff62ff36616063b9 Mon Sep 17 00:00:00 2001
From: David Peter <mail@david-peter.de>
Date: Tue, 6 Oct 2026 09:04:29 +0200
Subject: [PATCH] Support hardware counters in plotting scripts

---
 scripts/README.md         | 8 ++++++++
 scripts/plot_histogram.py | 4 ++--
 scripts/plot_utils.py     | 7 ++++++-
 3 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/scripts/README.md b/scripts/README.md
index 038a055..0b635b4 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -7,6 +7,14 @@ hyperfine 'sleep 0.020' 'sleep 0.021' 'sleep 0.022' --export-json sleep.json
 uv run plot_whisker.py sleep.json
 ```
 
+All plotting scripts accept `--metric` to select a metric. Hardware counters
+(`cpu_cycles`, `instructions`, `cache_references`, `cache_misses`, and `branch_misses`)
+are plotted as unscaled counts when available in the JSON export. For example:
+
+```bash
+uv run plot_histogram.py benchmark.json --metric instructions
+```
+
 ### Prerequisites
 
 Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) and run the
diff --git a/scripts/plot_histogram.py b/scripts/plot_histogram.py
index 5d7be2a..c757ce2 100755
--- a/scripts/plot_histogram.py
+++ b/scripts/plot_histogram.py
@@ -54,14 +54,14 @@ parser.add_argument(
     "--t-min",
     dest="value_min",
     type=float,
-    help="Minimum value to display (seconds, or MiB for memory)",
+    help="Minimum metric value to display",
 )
 parser.add_argument(
     "--max",
     "--t-max",
     dest="value_max",
     type=float,
-    help="Maximum value to display (seconds, or MiB for memory)",
+    help="Maximum metric value to display",
 )
 parser.add_argument(
     "--log-count",
diff --git a/scripts/plot_utils.py b/scripts/plot_utils.py
index 0ed0b2e..842ded9 100644
--- a/scripts/plot_utils.py
+++ b/scripts/plot_utils.py
@@ -5,6 +5,11 @@ METRICS = {
     "time_user": ("User CPU time [s]", 1),
     "time_system": ("System CPU time [s]", 1),
     "memory_peak_resident": ("Peak resident memory [MiB]", 1024**2),
+    "cpu_cycles": ("CPU cycles", 1),
+    "instructions": ("Completed CPU instructions", 1),
+    "cache_references": ("Cache references", 1),
+    "cache_misses": ("Cache misses", 1),
+    "branch_misses": ("Mispredicted branches", 1),
 }
 
 
@@ -14,7 +19,7 @@ def add_metric_argument(parser):
         choices=METRICS,
         default="time_wall_clock",
         help="Metric to plot (default: time_wall_clock). "
-        "Times are in seconds; memory is in MiB.",
+        "Times are in seconds; memory is in MiB; hardware counters are unscaled counts.",
     )