Skip to content
  1. How-to
  2. In real projects
  3. Too slow? Prove it got faster, with numbers

Too slow? Prove it got faster, with numbers

In one lineStart with a measured number. It measures, changes, and measures again, then shows a before-and-after you can trust.

One or two conversations to diagnose and fixFor: Something feels slow, and you want the real cause and a before-and-after you can trustFull guide step 6: Verify and ship

Copy this first

The shortest version
/pstack:poteto-mode startup takes 1.8s on this fixture. trace it, fix the measured cause, show me before and after.

This is the example from pstack’s own docs.

  • “1.8s on this fixture”: a measured number on fixed test data. It can’t compare “feels a bit laggy.”
  • “trace it”: a trace records how long each step of the program takes.
  • “the measured cause”: it fixes what the trace shows, not what it guesses.
Performance only counts measured numbers.
  1. 1Measure a baselinep50 about 900ms
  2. 2See where time goesTake a trace
  3. 3Fix the measured causeNot the guessed one
  4. 4Measure again, same datap50 under 200ms, same results

Not faster? Revert and go again

DiagramBoth numbers use the same data, alternating runs several times each, and compare medians.

A member site example

A member site runs on Cloudflare Workers, with data in D1. The member list endpoint keeps getting slower.

Workers and D1 example
/pstack:poteto-mode The member list endpoint /api/members has a p50 of about 900ms under local wrangler dev, with 5000 test members imported.
Measure a baseline first and tell me where the time goes. Fix the measured cause.
It's fixed when, with the same data, p50 is under 200ms and the members returned (count and content) are exactly the same as before the fix.
Alternate the two sides 7 runs each, give me the median and range, then run /pstack:benchmark-checklist.
  • “Exactly the same members returned”: faster but missing data means it isn’t fixed.
  • “Alternate 7 runs each”: a number from one run could be luck.
  • 5000 members: a scenario you can repeat. With too little data, the problem may not show up.

Where to look after you send it

At the start: the baseline number. If it says “this will be faster” without measuring, stop it.

At the end: four things. The baseline, the number after the fix, the difference, and where the data files are. If a result is inconclusive, it says so. That isn’t a pass.

A number that looks too good: /pstack:benchmark-checklist

Copy this
/pstack:benchmark-checklist Check this 40% speedup before it goes into the PR description

The perf playbook runs it on its own. For a number someone gave you, run it yourself. Seven questions, each backed by a real run:

  1. Why isn’t it twice as fast? Name the bottleneck holding it there.
  2. Are both sides set up like production? No debug build against a release build.
  3. Does it beat a physical limit? Faster than the disk means it measured something else.
  4. Were there errors? Rejected requests are often fast. Count them.
  5. Can you repeat it? Alternate the sides, at least 5 runs each. Report the median and range.
  6. Does it matter to users? A function that takes 1% of the time can save at most 1%.
  7. Did the timed work really happen? A promise nobody awaits runs very fast.

There are four verdicts: faster, slower, no measurable difference, or inconclusive.

Just tell me where it’s slow

Diagnosis only
/pstack:poteto-mode This is a cpuprofile I recorded during a slow startup. Tell me where the time goes and which lines of code are responsible. Don't fix anything yet.
  • You have a recorded file (cpuprofile, trace, heap snapshot): it reads only that file and finds the slowest lines.
  • It’s happening right now (memory keeps growing, CPU busy while idle, the UI flickers): it records the running program. Then a small experiment confirms the cause.

Both hand back only a sourced diagnosis. Then you decide how to fix it.

Keep pushing one number down

For a number you want to keep improving, like bundle size or first-screen time, use Hillclimb. Give it a metric, a target, and a minimum number of rounds.

Hillclimb
/pstack:poteto-mode hillclimb the side panel's first-open time. Target: at least 50% faster than baseline, and try at least 10 rounds. Log one line in the decision log per round.
  • “At least 10 rounds”: stops it from hitting the target by luck in round one and quitting.
  • One change and one measurement per round. Faster means it’s kept and committed alone. Not faster means it’s reverted.
  • One line per round. It goes in decision.tsv, so you can see every attempt.

Stuck?

It says “this will make it faster” without measuring.

Reply: “Measure first. Give me the baseline number and the trace file path, then tell me what to change.”

The improvement is absurdly large. I don't believe it.

Run /pstack:benchmark-checklist. Look hardest at questions 3 and 7. This matches explain-the-number. It means: say what limits the number, and rule out that it measured the wrong thing. It’s the name of a pstack principle.

It ran once and drew a conclusion.

Reply: “Alternate the two sides at least 5 runs each, and report the median and range. If the gap is smaller than the run-to-run variation, there’s no difference.”

Hillclimb is stuck on one number, and it wants to stop.

It should try a different approach first. It can’t loosen the target to call it done. If it’s truly stuck, it should tell you what’s going on.

An unofficial beginner's guide to pstack, not its official docs. pstack is made by poteto; the official repo is the source of truth for commands and behavior. The original guide source is on GitHub.

Hosted by airali. Adapted from Xiaoxiaodong's MIT-licensed guide.