Support hardware counters in plotting scripts (#984)

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

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",

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.",
     )