10 - CodeGreen vs perf¶

Cross-validate CodeGreen's reported mean energy against perf stat power/energy-pkg/ on the same workload. If the two disagree by more than a few percent, something is wrong on this host.

What you learn¶

How to read perf stat -j -e power/energy-pkg/ Joules.
How to compare it to codegreen run --json energy_j.mean.
The expected relative error on a well-behaved RAPL system (< 1% on Skylake-SP and EPYC Zen 4 from our benchmark suite).

Prerequisites¶

pip install codegreen
perf on PATH (sudo apt install linux-tools-common linux-tools-generic).
Either sudo (recommended) or kernel.perf_event_paranoid <= 2.

Source¶

examples/10_codegreen_vs_perf/main.py

"""10 Cross-check: codegreen vs `perf stat -e power/energy-pkg/`.

Runs the same Python workload twice, once instrumented via codegreen and
once wrapped in perf stat, then prints the percentage delta. Useful for
sanity-checking that codegreen agrees with the kernel's perf counters
within a few percent.

Skips cleanly if `perf` or the `power/energy-pkg/` event are unavailable.
"""
import json
import re
import shutil
import subprocess
import sys


WORKLOAD = "x=0\nfor i in range(2_000_000): x+=i*i\nprint(x)"


def _codegreen_run() -> float:
    out = subprocess.run(
        ["codegreen", "run", "--repeat", "3", "--warmup", "1", "--json", "--",
         "python3", "-c", WORKLOAD],
        capture_output=True, text=True, check=True,
    )
    return float(json.loads(out.stdout)["energy_j"]["mean"])


def _perf_run() -> float:
    if not shutil.which("perf"):
        return float("nan")
    p = subprocess.run(
        ["perf", "stat", "-x", ",", "-e", "power/energy-pkg/",
         "python3", "-c", WORKLOAD],
        capture_output=True, text=True,
    )
    for ln in p.stderr.splitlines():
        m = re.match(r"^([0-9.,]+),Joules,power/energy-pkg/", ln)
        if m:
            return float(m.group(1).replace(",", "."))
    return float("nan")


def main() -> int:
    cg_j = _codegreen_run()
    perf_j = _perf_run()
    if perf_j != perf_j:
        print(f"SKIP: perf or power/energy-pkg/ unavailable; codegreen_j={cg_j:.4f}")
        return 0
    delta_pct = 100.0 * (cg_j - perf_j) / perf_j
    print(f"OK: codegreen_vs_perf; codegreen_j={cg_j:.4f}; perf_j={perf_j:.4f}; delta_pct={delta_pct:.2f}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

Run¶

python examples/10_codegreen_vs_perf/main.py

Expected output¶

OK: codegreen_vs_perf; codegreen_j=0.8123; perf_j=0.8087; delta_pct=0.45

Why it matters¶

perf stat is the kernel's own RAPL frontend. If CodeGreen's number diverges from perf by more than 5%, you're likely seeing one of:

a multi-Monitor double-count (another codegreen monitor running),
a DRAM domain mismatch (perf includes DRAM, CodeGreen excludes it or vice versa -- check meta.domain_topology),
a wraparound bug in the AMD provider (if you're not on a recent release).

This script is the canonical "is my measurement actually correct?" probe. Run it after any kernel update, BIOS update, or CodeGreen upgrade.