---
title: "Profile the slow path before you change it · Agent Wranglers"
url: https://agentwranglers.se/playbook/scaling/measure-before-you-scale/profile-first
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Profile the slow path before you change it

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Measure before you scale](https://agentwranglers.se/playbook/scaling/measure-before-you-scale.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- ID: SCL-2
- Level: Recommended
- Chapter: [Measure before you scale](https://agentwranglers.se/playbook/scaling/measure-before-you-scale)
- Rule: Before you rewrite slow code, record a CPU profile of the slow route under load. Change the function that takes the most time, then profile again.
- How: Guesses about slow code are often wrong. A sampling profiler records where time goes with little overhead, so it can run on staging during a load test. Examples are Node's `--cpu-prof`, Python 3.15's `profiling.sampling`, Go's `pprof` and Java Flight Recorder. Read the result as a flame graph, where the widest bar takes the most time. Time spent waiting on the database shows in a trace instead, as [Trace requests across services](https://agentwranglers.se/playbook/operations/metrics-and-traces/distributed-tracing) explains. Slow queries go to [Read the query plan](https://agentwranglers.se/playbook/data/queries-and-indexes/query-plans).
- Check: The change notes for each speed fix show the top function in the profile before and after. They give its share of CPU time, such as "from 41% to 6%".

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Shell example

```sh
# Node: write a .cpuprofile file when the process exits
node --cpu-prof --cpu-prof-dir=./profiles server.js
# Python 3.15: sample a running process for 30 seconds into a flame graph
python -m profiling.sampling attach --flamegraph -d 30 -o profile.html 12345
# Go: fetch a 30-second profile from net/http/pprof
go tool pprof -http=:8081 'http://localhost:6060/debug/pprof/profile?seconds=30'
```

## Sources

- [Node.js command-line options](https://nodejs.org/api/cli.html)
- [Python profiling.sampling](https://docs.python.org/3/library/profiling.sampling.html)

## Related rules

- [Trace requests across services](https://agentwranglers.se/playbook/operations/metrics-and-traces/distributed-tracing) in Operations
- [Read the query plan](https://agentwranglers.se/playbook/data/queries-and-indexes/query-plans) in Data

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/scaling/measure-before-you-scale/profile-first">Agent Wranglers scaling playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Find the bottleneck before you add servers](https://agentwranglers.se/playbook/scaling/measure-before-you-scale/find-the-bottleneck)
- Next: [Write down the load you plan for](https://agentwranglers.se/playbook/scaling/measure-before-you-scale/load-model)
- [Measure before you scale](https://agentwranglers.se/playbook/scaling/measure-before-you-scale)