# Profiling artifacts
These are diagnostic profiles, not throughput benchmark results. No profiling
process is active during the repeated comparisons in `bench/results`.
- `before-raw`, `before-fastapi`: py-spy native/Python stack samples. They include
startup; do not treat import activity as steady-state request overhead. The raw
profile had 6,195 accepted samples and 53 stack-unwinding/merge errors.
- `perf-before-raw`, `perf-before-fastapi`: original release binary, user-space
cycles only, sampling delayed three seconds to exclude application startup.
- `perf-readiness-raw`: after read-buffer and readiness changes.
- `perf-optimized-*`: intermediate implementation before the vectored-write change.
- `perf-final-*`: retained source after all optimizations. Build hashes are in
metadata.json; benchmark wheel hashes are recorded separately in results.json.
- `before-source.tar.gz`: original source and original tested release extension,
retained for repeatable before/after comparisons. No production code is fetched
from this archive at runtime.
Each perf directory contains exclusive/inclusive text reports, command line,
loaded mappings, profiler diagnostics and its load-generator output. Raw perf.data
files are temporary files under `/tmp`, named after each profile directory.
Perf reports record zero lost samples. Unknown/unresolved symbols remain visible;
they are not silently assigned to a guessed function.
Example, from the project directory with perf already permitted for your process:
```bash
python bench/profile.py --kind perf --profiler /usr/bin/perf \
--path /bytes --output bench/profiles/my-bulk
```
The script runs server CPU 0, client CPUs 4–7 (four threads, 64 connections by default; override with --connections). It uses
`cycles:u`, 499 Hz, DWARF call chains, a three-second sampling delay, and eleven
seconds of diagnostic load. Commands and output paths are saved. Python/native
stack sampling instead uses `--profiler /path/to/py-spy` with the default kind.
Profiling required temporarily changing this machine's perf_event_paranoid from
4 to 2. The user performed the privileged change; restoring it to 4 is also a
user action. The server itself never changes kernel profiling or application GC
settings. Security-setting changes are not required to run normal benchmarks.
## Peregrine comparison round
`peregrine-{tiny,upload,fastapi}` profile the installed Peregrine 1.1.7 binary.
`skirr-round2-{tiny,upload,fastapi}` are the saved Skirr baseline;
`skirr-round2-final-*` are the retained release wheel. The exact Peregrine source
archive, hash and reviewed files are recorded in `peregrine-source.json`.
Swift symbols in `exclusive-readable.txt` were demangled with the installed
Peregrine wheel's `libswiftCore.so` / `swift_demangle`; original reports remain.
See [the comparison analysis](peregrine-study.md).
`syscalls-{before,after,peregrine}` record 1,001 sequential tiny requests under
strace, including readiness and shutdown. Use `bench/syscalls.py` to reproduce;
the output is diagnostic and must not be used as throughput data. The retained
Skirr before-source for this round is `round2-before-source.tar.gz`.
`rejected-token-channel.patch` records the discarded vectorcall experiment;
its workload measurements are in `bench/results/channel-experiment`.
## FastAPI and p99 study
See [fastapi-study.md](fastapi-study.md) for the third-round findings and provenance.
`fastapi-round3-before`, `fastapi-round3-peregrine` and `fastapi-round3-retained`
are validated native profiles. `python-only-round3-*-workers` samples Python
worker stacks; `tail-round3-*-c64` measures instrumented loop delays and send yields.
Only `retained` names identify the final release binary. Earlier `final` and
`pre-intern` names are intermediate experiments, not final performance evidence.
`invalid-404-*`, the parent-only Peregrine Python profile, and the py-spy native
profile with merge errors are excluded evidence. Their limitations are recorded
in the study. `round3-before-source.tar.gz` preserves this round's starting code
and binary. `wrk2-round3-source.json` records the temporary fixed-rate generator.
## Fourth-round final-write and allocation study
[latency-round4-study.md](latency-round4-study.md) describes the current wheel,
qualification and remaining FastAPI costs. `round4-final-native` and
`round4-final-peregrine-native` contain delayed user-cycle profiles at 256
connections. `round4-final-python` and `round4-final-peregrine-python` contain
Python-only worker stacks and last-frame summaries. Actual serving-worker
affinity is verified. `round4-final-*-syscalls` traces sequential FastAPI requests.
`round4-before-source.tar.gz` is this user turn's starting release (09140253...).
`round4-adaptive-checkpoint-source.tar.gz` preserves the rejected adaptive
checkpoint (18449600...), described separately in
`latency-round4-checkpoint-study.md`; its 75-run comparisons are intermediate.
The final comparison uses only `latency-round4-final-*` matrices and the
qualified extension a126b0fb... . Component trials with `round4-*` names can
have different before candidates; consult their recorded baseline hashes.
The optional CPython perf trampoline mode requires --python-perf and the
monotonic clock configured by profile.py. It is diagnostic only and not used
for comparative function percentages because eager and ordinary Task paths
have unequal Python-frame coverage. Invalid JIT clock/unwind outputs are
explicitly excluded in the study. No compiler, sanitizer or profiler runs
concurrently with the final performance comparisons.