---
name: perf-profile
description: Profiles a slow function, endpoint, script or test using a profiler suited to the stack, identifies hotspots from the profile data, applies one change at a time, and reports before and after measurements from the same benchmark. Use when the user says something is slow, asks to optimize performance, reduce latency, CPU or memory, or to profile code.
---

# Performance profiling

Target: `$ARGUMENTS`

Rule: no optimization without a measurement before and after. Store artifacts in `.perf/`.

## 1. Define and benchmark

- Restate the target as a measurable thing: "median wall time of X with input Y".
- Find or write the smallest repeatable benchmark: an existing benchmark, a test, a script that calls the function with realistic input, or a local HTTP request loop. Use local or test environments only.
- Run it at least 5 times after one warm-up run. Record median and spread. If spread is large, fix the benchmark first.

## 2. Profile

Pick the tool for the stack:

- **Node.js**: `node --cpu-prof --cpu-prof-dir=.perf <script>` produces `.cpuprofile` files. Summarize the top functions by reading the file, or load it in Chrome DevTools. For heap: `node --heap-prof`.
- **Python**: `python -m cProfile -o .perf/out.prof <script>` then
  `python -c "import pstats; pstats.Stats('.perf/out.prof').sort_stats('cumulative').print_stats(25)"`.
  For a running process or lower overhead: `py-spy record -o .perf/profile.svg -- python <script>` (if installed).
- **Go**: `go test -run '^$' -bench <Name> -benchmem -cpuprofile .perf/cpu.out ./<pkg>` then `go tool pprof -top .perf/cpu.out`. Use `-memprofile` for allocations.
- **JVM**: Java Flight Recorder: `java -XX:StartFlightRecording=duration=60s,filename=.perf/rec.jfr ...`, then `jfr print --events jdk.ExecutionSample .perf/rec.jfr` or open in JDK Mission Control.
- **Database-bound**: log or count queries per request; run `EXPLAIN` (Postgres `EXPLAIN (ANALYZE, BUFFERS)` on a non-production copy) for the slowest ones.
- **Browser**: explain to the user how to record a Performance trace in DevTools and ask them to share the summary or the exported trace; you cannot record it.

## 3. Read the profile

List the top 5 to 10 entries by self time and by cumulative time. Map each to `file:line`. Ignore framework internals unless your code calls them in a loop.

Common causes to look for:
- N+1 queries or a query inside a loop.
- Repeated work: parsing, regex compilation, JSON serialization, or reading the same file in a loop.
- Quadratic algorithms: nested loops over the same data, `includes`/`in` on a list inside a loop.
- Excess allocation or copying of large objects.
- Synchronous I/O on a hot path; sequential awaits that could run concurrently.
- Missing index or full table scan.

## 4. Change one thing

Make the smallest change that addresses the top hotspot. Keep behavior identical; run the relevant tests.

## 5. Re-measure

Run the exact same benchmark the same number of times. If the median did not improve beyond the spread, revert the change and say so.

## 6. Report

```
Target: <metric and input>
Benchmark: <command>
Before: median <x> (n=<runs>, range <a>-<b>)
Hotspot: <function> <self/cumulative %> (`file:line`)
Change: <what and why>
After: median <y> (n=<runs>, range <a>-<b>)
Tests: <command> - <result>
Next candidates: <remaining hotspots>
```