contrib: plot getMemoryLoad()

Add Python script to make plots.

Assisted-by: GitHub Copilot
Assisted-by: OpenAI GPT-5.1-Codex

Author: Sjors

.gitignore

@@ -26,3 +26,5 @@ target/
 /guix-build-*
 
 /ci/scratch/
+
+plots

contrib/devtools/plot_memory_load.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""Plot getMemoryLoad durations and template memory footprints over time."""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import re
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+from matplotlib.ticker import NullFormatter
+
+MEMORY_LOAD_COMPLETED = re.compile(
+    r"^(?P<ts>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z).*getMemoryLoad:.*completed \((?P<ms>\d+\.\d+)ms\)"
+)
+UPDATE_TIP = re.compile(
+    r"^(?P<ts>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z).*UpdateTip:.*height=(?P<height>\d+) "
+)
+FOOTPRINT_ENTRY = re.compile(
+    r"^(?P<ts>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})Z.*Template memory footprint (?P<mib>\d+(?:\.\d+)?) MiB"
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "bitcoin_log",
+        type=Path,
+        help="Path to bitcoin debug log containing getMemoryLoad entries",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path("getmemoryload-scatter.png"),
+        help="Destination image path (default: ./getmemoryload-scatter.png)",
+    )
+    parser.add_argument(
+        "--show",
+        action="store_true",
+        help="Display the plot interactively instead of saving it",
+    )
+    parser.add_argument(
+        "footprint_log",
+        type=Path,
+        nargs="?",
+        help="Optional SV2 log path with 'Template memory footprint' lines",
+    )
+    return parser.parse_args()
+
+
+def parse_timestamp(raw: str) -> dt.datetime:
+    return dt.datetime.fromisoformat(raw.replace("Z", "+00:00"))
+
+
+def load_events(log_path: Path):
+    mem_points = []
+    tip_events = []
+    with log_path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            mem_match = MEMORY_LOAD_COMPLETED.search(line)
+            if mem_match:
+                mem_points.append(
+                    (parse_timestamp(mem_match.group("ts")), float(mem_match.group("ms")))
+                )
+                continue
+            tip_match = UPDATE_TIP.search(line)
+            if tip_match:
+                tip_events.append(
+                    (parse_timestamp(tip_match.group("ts")), int(tip_match.group("height")))
+                )
+    mem_points.sort(key=lambda item: item[0])
+    tip_events.sort(key=lambda item: item[0])
+    return mem_points, tip_events
+
+
+def load_footprints(log_path: Path | None):
+    footprints = []
+    if log_path is None:
+        return footprints
+
+    if not log_path.exists():
+        raise SystemExit(f"Footprint log '{log_path}' not found")
+
+    with log_path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            match = FOOTPRINT_ENTRY.search(line)
+            if match:
+                mib_val = float(match.group("mib"))
+                footprints.append((parse_timestamp(match.group("ts")), mib_val))
+
+    footprints.sort(key=lambda item: item[0])
+    return footprints
+
+
+def plot_memory_load(
+    mem_points,
+    tip_events,
+    footprint_points,
+    output: Path,
+    show_plot: bool,
+) -> None:
+    if not mem_points:
+        raise SystemExit("No getMemoryLoad() completion records found in log")
+
+    times, durations = zip(*mem_points)
+    fig, ax = plt.subplots(figsize=(10, 5))
+    ax.scatter(
+        times,
+        durations,
+        s=5,
+        color="tab:blue",
+        label="getMemoryLoad duration",
+        zorder=3,
+    )
+
+    ax.set_ylabel("Duration (ms)")
+    ax.set_xlabel("Time")
+    ax.set_title("")
+    ax.xaxis.set_major_formatter(NullFormatter())
+    ax.set_ylim(bottom=0)
+
+    twin_ax = None
+    if footprint_points:
+        footprint_times, footprint_mib = zip(*footprint_points)
+        twin_ax = ax.twinx()
+        twin_ax.vlines(
+            footprint_times,
+            [0] * len(footprint_times),
+            footprint_mib,
+            color="#4fbf73",
+            alpha=0.5,
+            linewidth=1,
+            zorder=1,
+            label="Template memory footprint",
+        )
+        twin_ax.set_ylabel("Memory footprint (MiB)", color="#2b8a46")
+        twin_ax.tick_params(axis="y", colors="#2b8a46")
+        twin_ax.set_ylim(bottom=0)
+
+    if tip_events:
+        tip_color = "tab:red"
+        for ts, height in tip_events:
+            ax.axvline(ts, linestyle=":", color=tip_color, alpha=0.8)
+            ax.annotate(
+                str(height),
+                xy=(ts, 1),
+                xycoords=("data", "axes fraction"),
+                xytext=(0, 3),
+                textcoords="offset points",
+                rotation=90,
+                ha="center",
+                va="bottom",
+                color=tip_color,
+                fontsize=8,
+            )
+
+    handles, labels = ax.get_legend_handles_labels()
+    if twin_ax is not None:
+        twin_handles, twin_labels = twin_ax.get_legend_handles_labels()
+        handles += twin_handles
+        labels += twin_labels
+    ax.legend(handles, labels, loc="upper left")
+    ax.grid(True, axis="y", linestyle="--", alpha=0.3)
+
+    if show_plot:
+        plt.show()
+    else:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        fig.savefig(output, bbox_inches="tight", dpi=150)
+        print(f"Wrote {output}")
+
+    plt.close(fig)
+
+
+def main() -> None:
+    args = parse_args()
+    mem_points, tip_events = load_events(args.bitcoin_log)
+    footprint_points = load_footprints(args.footprint_log)
+    plot_memory_load(mem_points, tip_events, footprint_points, args.output, args.show)
+
+
+if __name__ == "__main__":
+    main()