profiler-analysis

Profiler Analysis

Deterministic Extraction (run this first when the format matches)

For the three formats a script can parse exactly, run scripts/parse-profiler.py before attempting any manual interpretation. Computing percentages, aggregating recursive call sites, and walking a query plan tree by eye is exactly the kind of arithmetic a script gets right every time and a model can get subtly wrong once — the script computes, this skill interprets:

• Chrome DevTools / Node.js --cpu-prof output (.cpuprofile files — JSON with nodes + samples)
• go tool pprof -top <profile> text output (piped or saved to a file)
• PostgreSQL EXPLAIN (ANALYZE, FORMAT JSON) <query> output

python3 "$CLAUDE_PLUGIN_ROOT/scripts/parse-profiler.py" <path-or-'-'-for-stdin> [--format cpuprofile|pprof-top|pg-explain] [--top N]

Format auto-detects from content when --format is omitted. --top defaults to 15. The script exits non-zero with a plain-language error on unreadable/malformed input or unrecognized format — when it fails, fall back to the manual interpretation guidance below for whatever runtime the artifact came from, rather than guessing at numbers the script refused to compute.

Every format returns the same JSON shape on stdout, so downstream reasoning is identical regardless of which profiler produced the input:

{
  "format": "cpuprofile | pprof-top | pg-explain",
  "summary": { "...format-specific totals, e.g. total_samples, duration_ms, execution_time_ms..." },
  "top": [
    {
      "rank": 1,
      "name": "function or plan-node name",
      "location": "file:line, relation/index name, or null",
      "self_pct": 34.39,
      "self_time_ms": 980.0,
      "total_pct": 34.39,
      "total_time_ms": 980.0,
      "extra": { "...format-specific fields, see below..." }
    }
  ]
}

• self_pct/self_time_ms — exclusive time/share for this function or plan node alone, not its callees. This is the primary sort key and the number to lead with when identifying "the" hotspot.
• total_pct/total_time_ms — inclusive of children (cumulative time for a function, or a plan node's time including its subtree). A node can rank low on self_pct but high on total_pct if it's a thin orchestration layer over expensive children — call this out explicitly rather than only reporting the self-time leaderboard, since both numbers matter for different fix strategies (optimize the node itself vs. optimize/parallelize what it calls).
• self_time_ms/total_time_ms can be null — this happens for pprof-top when the profile type isn't time-based (e.g. a heap/allocation profile using bytes or object counts instead of seconds). self_pct/ total_pct are always populated regardless of unit; fall back to extra.flat_raw/extra.cum_raw (the original unit string) when the absolute numbers are null.
• extra carries format-specific detail worth surfacing in a finding, notably pg-explain's actual_vs_estimated_rows_ratio — the planner's estimated rows vs. what actually came back. A ratio far from 1.0 (e.g. 40x under-estimated) is itself a root-cause finding: a bad plan usually traces back to a bad estimate, and ANALYZE-ing the underlying table's statistics is often the actual fix, not the query itself.