anti
319c1dbb61
New `profile` optional-deps group, opt-in Pyinstrument ASGI middleware gated by DECNET_PROFILE_REQUESTS, bench marker + tests/perf/ micro-benchmarks for repository hot paths, and scripts/profile/ helpers for py-spy/cProfile/memray.
70 lines
2.0 KiB
Markdown
70 lines
2.0 KiB
Markdown
# DECNET Profiling
|
|
|
|
Five complementary lenses. Pick whichever answers the question you have.
|
|
|
|
## 1. Whole-process sampling — py-spy
|
|
|
|
Attach to a running API and record a flamegraph for 30s. Requires `sudo`
|
|
(Linux ptrace scope).
|
|
|
|
```bash
|
|
./scripts/profile/pyspy-attach.sh # auto-finds uvicorn pid
|
|
sudo py-spy record -o profile.svg -p <PID> -d 30 --subprocesses
|
|
```
|
|
|
|
If py-spy "doesn't work", it is almost always one of:
|
|
- Attached to the Typer CLI PID, not the uvicorn worker PID (use `pgrep -f 'uvicorn decnet.web.api'`).
|
|
- `kernel.yama.ptrace_scope=1` — run with `sudo` or `sudo sysctl kernel.yama.ptrace_scope=0`.
|
|
- The API isn't actually running (a `--dry-run` deploy starts nothing).
|
|
|
|
## 2. Per-request flamegraphs — Pyinstrument
|
|
|
|
Set the env flag, hit endpoints, find HTML flamegraphs under `./profiles/`.
|
|
|
|
```bash
|
|
DECNET_PROFILE_REQUESTS=true decnet deploy --mode unihost --deckies 1
|
|
# in another shell:
|
|
curl http://127.0.0.1:8000/api/v1/health
|
|
open profiles/*.html
|
|
```
|
|
|
|
Off by default — zero overhead when the flag is unset.
|
|
|
|
## 3. Deterministic call graph — cProfile + snakeviz
|
|
|
|
For one-shot profiling of CLI commands or scripts.
|
|
|
|
```bash
|
|
./scripts/profile/cprofile-cli.sh services # profiles `decnet services`
|
|
snakeviz profiles/cprofile.prof
|
|
```
|
|
|
|
## 4. Micro-benchmarks — pytest-benchmark
|
|
|
|
Regression-gate repository hot paths.
|
|
|
|
```bash
|
|
pytest -m bench tests/perf/ -n0 # SQLite backend (default)
|
|
DECNET_DB_TYPE=mysql pytest -m bench tests/perf/ -n0
|
|
```
|
|
|
|
Note: `-n0` disables xdist. `pytest-benchmark` refuses to measure under
|
|
parallel workers, which is the project default (`-n logical --dist loadscope`).
|
|
|
|
## 5. Memory allocation — memray
|
|
|
|
Hunt leaks and allocation hot spots in the API / workers.
|
|
|
|
```bash
|
|
./scripts/profile/memray-api.sh # runs uvicorn under memray
|
|
memray flamegraph profiles/memray.bin
|
|
```
|
|
|
|
## Load generation
|
|
|
|
Pair any of the in-process lenses (2, 5) with Locust for realistic traffic:
|
|
|
|
```bash
|
|
pytest -m stress tests/stress/
|
|
```
|