|
| 1 | +"""Build a per-run step waterfall and find the run's bottleneck steps. |
| 2 | +
|
| 3 | +The action profiler aggregates timings by step *name* across many runs — great for |
| 4 | +"which action is slow on average", useless for "why was *this* run slow". A single |
| 5 | +run is an ordered timeline: step A ran, then B, then C, and one of them dominated. |
| 6 | +``step_timeline`` turns one run's steps into a waterfall (each step's offset from |
| 7 | +the start, duration and share of the total) and ranks the bottleneck steps, so you |
| 8 | +can read a single slow run instead of an average. |
| 9 | +
|
| 10 | +A step is any dict with a name (default ``"name"``) and a ``duration``; an optional |
| 11 | +``start`` places it on an absolute timeline (overlapping / parallel steps), else |
| 12 | +steps are laid out back-to-back. Pure standard library; no device, no ``PySide6``. |
| 13 | +""" |
| 14 | +from typing import Any, Dict, List, Sequence |
| 15 | + |
| 16 | +Step = Dict[str, Any] |
| 17 | + |
| 18 | + |
| 19 | +def _normalize(steps: Sequence[Step], name_key: str, start_key: str, |
| 20 | + duration_key: str) -> List[Dict[str, Any]]: |
| 21 | + """Resolve each step to ``{name, start, end, duration}`` (sequential if no start).""" |
| 22 | + resolved, cursor = [], 0.0 |
| 23 | + for step in steps: |
| 24 | + duration = float(step.get(duration_key, 0.0) or 0.0) |
| 25 | + raw_start = step.get(start_key) |
| 26 | + start = float(raw_start) if raw_start is not None else cursor |
| 27 | + end = start + duration |
| 28 | + cursor = max(cursor, end) |
| 29 | + resolved.append({"name": str(step.get(name_key, "")), "start": start, |
| 30 | + "end": end, "duration": duration}) |
| 31 | + return resolved |
| 32 | + |
| 33 | + |
| 34 | +def build_timeline(steps: Sequence[Step], *, name_key: str = "name", |
| 35 | + start_key: str = "start", |
| 36 | + duration_key: str = "duration") -> Dict[str, Any]: |
| 37 | + """Return a waterfall timeline for one run. |
| 38 | +
|
| 39 | + ``{steps:[{name, offset, duration, pct}], total, busy, bottleneck, |
| 40 | + parallelism}`` — ``total`` is the wall-clock span, ``busy`` the summed step |
| 41 | + time, ``parallelism`` = busy / total (1.0 for a purely sequential run), |
| 42 | + ``bottleneck`` the longest single step. |
| 43 | + """ |
| 44 | + resolved = _normalize(steps, name_key, start_key, duration_key) |
| 45 | + if not resolved: |
| 46 | + return {"steps": [], "total": 0.0, "busy": 0.0, "bottleneck": None, |
| 47 | + "parallelism": 0.0} |
| 48 | + base = min(step["start"] for step in resolved) |
| 49 | + span = max(step["end"] for step in resolved) - base |
| 50 | + busy = sum(step["duration"] for step in resolved) |
| 51 | + rows = [{"name": step["name"], "offset": round(step["start"] - base, 6), |
| 52 | + "duration": step["duration"], |
| 53 | + "pct": round(step["duration"] / span * 100, 1) if span > 0 else 0.0} |
| 54 | + for step in resolved] |
| 55 | + bottleneck = max(resolved, key=lambda step: step["duration"]) |
| 56 | + return {"steps": rows, "total": round(span, 6), "busy": round(busy, 6), |
| 57 | + "bottleneck": {"name": bottleneck["name"], |
| 58 | + "duration": bottleneck["duration"]}, |
| 59 | + "parallelism": round(busy / span, 3) if span > 0 else 1.0} |
| 60 | + |
| 61 | + |
| 62 | +def critical_steps(steps: Sequence[Step], *, name_key: str = "name", |
| 63 | + start_key: str = "start", duration_key: str = "duration", |
| 64 | + top: int = 3) -> List[Dict[str, Any]]: |
| 65 | + """Return the ``top`` steps that dominate the run, longest first. |
| 66 | +
|
| 67 | + Each entry is ``{name, duration, pct}`` where ``pct`` is the step's share of |
| 68 | + the total step time — the bottlenecks worth optimising. |
| 69 | + """ |
| 70 | + resolved = _normalize(steps, name_key, start_key, duration_key) |
| 71 | + busy = sum(step["duration"] for step in resolved) or 1.0 |
| 72 | + ranked = sorted(resolved, key=lambda step: step["duration"], reverse=True) |
| 73 | + return [{"name": step["name"], "duration": step["duration"], |
| 74 | + "pct": round(step["duration"] / busy * 100, 1)} |
| 75 | + for step in ranked[:max(1, int(top))]] |
0 commit comments