strawberry/scripts/perf_kpi_runtime.py
trvon a5f2dbedfc
KPI: bound collection and reject incomplete measurements
Use suspend-aware BOOTTIME waits and owned-container cleanup without changing the workload. Reject missing coverage and preserve producer/report failures. Include runtime/helper regressions, constrained build-job support and live exec-guard crash safety. Document the failed live/idle gates without relaxing thresholds or claiming production acceptance.
2026-11-03 06:57:00 -07:00

143 lines
5.3 KiB
Python

"""Linux-only, event-driven BOOTTIME deadlines for trusted KPI subprocesses.
Python 3.12+; timerfd via libc avoids adding a dependency to the Ubuntu image.
Not a sandbox/wake alarm: cancellation is observable on next scheduling after
resume. Only callers' own child process groups may be stopped.
"""
import ctypes
import errno
import math
import os
import selectors
import signal
import subprocess
import tempfile
import time
from contextlib import ExitStack
class Timespec(ctypes.Structure):
_fields_ = [("seconds", ctypes.c_long), ("nanoseconds", ctypes.c_long)]
class Itimerspec(ctypes.Structure):
_fields_ = [("interval", Timespec), ("value", Timespec)]
def boot():
return time.clock_gettime(time.CLOCK_BOOTTIME)
def clocks():
return {"realtime_ns": time.time_ns(), "monotonic_ns": time.monotonic_ns(),
"boottime_ns": time.clock_gettime_ns(time.CLOCK_BOOTTIME)}
def seconds(value):
value = float(value)
if not math.isfinite(value) or not 0 < value <= 3600:
raise ValueError("duration must be finite, positive and <=3600 seconds")
return value
def timestamp_value(value):
ns = int(value * 1_000_000_000)
return Timespec(ns // 1_000_000_000, ns % 1_000_000_000)
class Timer:
def __init__(self, deadline, interval: float = 0):
if ctypes.sizeof(ctypes.c_long) != 8:
raise OSError("KPI timer ABI requires Linux with 64-bit long")
if not math.isfinite(deadline) or not 0 < deadline <= boot() + 3600 or not math.isfinite(interval) or interval < 0:
raise ValueError("invalid absolute BOOTTIME timer")
spec = Itimerspec(timestamp_value(interval), timestamp_value(deadline))
libc = ctypes.CDLL(None, use_errno=True)
create = libc.timerfd_create
create.argtypes = [ctypes.c_int, ctypes.c_int]
create.restype = ctypes.c_int
arm = libc.timerfd_settime
arm.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.POINTER(Itimerspec), ctypes.c_void_p]
arm.restype = ctypes.c_int
self.fd = create(time.CLOCK_BOOTTIME, os.O_NONBLOCK | os.O_CLOEXEC)
if self.fd < 0:
raise OSError(ctypes.get_errno(), "timerfd_create")
if arm(self.fd, 1, ctypes.byref(spec), None) < 0: # TFD_TIMER_ABSTIME
error = ctypes.get_errno()
os.close(self.fd)
raise OSError(error, "timerfd_settime")
def close(self):
os.close(self.fd)
def until(deadline, process=None, tick=None, interval: float = 2, deadline_is_error=True):
"""Return child's exit code, or None when a phase timer elapses.
No periodic process polling. A pidfd and BOOTTIME timerfds drive epoll.
Tick callbacks must themselves be bounded (all KPI CLI calls are).
"""
if deadline <= boot():
if process is not None and deadline_is_error:
raise subprocess.TimeoutExpired(process.args, 0)
return None
with ExitStack() as stack:
selector = stack.enter_context(selectors.DefaultSelector())
timer = Timer(deadline)
stack.callback(timer.close)
selector.register(timer.fd, selectors.EVENT_READ, "deadline")
if process is not None:
code = process.poll()
if code is not None:
return code
pidfd = os.pidfd_open(process.pid)
stack.callback(os.close, pidfd)
selector.register(pidfd, selectors.EVENT_READ, "child")
if tick is not None:
ticker = Timer(boot() + interval, interval)
stack.callback(ticker.close)
selector.register(ticker.fd, selectors.EVENT_READ, "tick")
while True:
events = selector.select()
if not events:
raise OSError(errno.EINTR, "event wait returned no events")
if boot() >= deadline or any(key.data == "deadline" for key, _ in events):
if process is not None and deadline_is_error:
raise subprocess.TimeoutExpired(process.args, 0)
return None
if any(key.data == "child" for key, _ in events):
assert process is not None
return process.wait() # readable pidfd: already exited
if tick is not None:
for key, _ in events:
if key.data == "tick":
os.read(key.fd, 8)
tick()
def stop(process):
if process.poll() is None:
try:
os.killpg(process.pid, signal.SIGKILL)
except ProcessLookupError:
process.poll() # exit race; collect status below
return until(boot() + 2, process)
def capture(command, timeout: float = 5):
"""Small trusted metadata commands only; output is bounded after exit."""
duration = seconds(timeout)
with tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err:
process = subprocess.Popen(command, stdout=out, stderr=err, start_new_session=True)
try:
code = until(boot() + duration, process)
except BaseException:
stop(process)
raise
out.seek(0)
err.seek(0)
stdout, stderr = out.read(1_048_577), err.read(1_048_577)
if len(stdout) > 1_048_576 or len(stderr) > 1_048_576:
raise ValueError("metadata output exceeds 1MiB cap")
assert code is not None
return subprocess.CompletedProcess(command, code, stdout, stderr)