yams/tests/benchmarks/TRACY_PROFILING.md
Trevon 777e35adae
feat(profiling): Tracy for every library, zones on p2p and memory-sync, per-test CPU/RSS (#294)
* feat(profiling): Tracy zones on p2p and memory-sync background paths

Zone the memory-sync cycle (publish, sync, reconcile, apply, backfill,
delete-outbox drain), the p2p reconnect cycle, accept loop, per-session
worker and frame read, and the delta send/apply/bootstrap stages. Plot the
retained session count and pending erase intents. No behavior change; the
macros are no-ops without Tracy.

Signed-off-by: trvon <me@trevon.dev>

* test(infra): per-test-case CPU and peak RSS accounting for Catch2 binaries

A Catch2 listener in the shared test main records getrusage (GetProcessTimes
on Windows) CPU per case and prints the five heaviest cases plus the run's
peak RSS to stderr at run end. YAMS_TEST_RUSAGE=1 adds one line per case.
The measurement helpers are header-only and unit tested.

Signed-off-by: trvon <me@trevon.dev>

* fix(vector): make vector_database.cpp compile with Tracy enabled

The Profiling lane did not build: eight YAMS_PLOT sites in
vector_database.cpp used -> on a Result<T>, and two passed an int that is
ambiguous between Tracy's PlotData overloads. Use .value() and int64_t
casts. No behavior change outside TRACY_ENABLE builds.

Signed-off-by: trvon <me@trevon.dev>

* build: enable Tracy for every yams library in the Profiling lane

Define yams_tracy_args/yams_tracy_deps once in the root meson.build
(Tracy found, optional rocprofiler hooks, link check) and apply them to
every library and executable under src/, replacing the per-library copies
in search, topology, vector, daemon and tests/benchmarks. Empty when
enable-profiling is off.

Make YAMS_PLOT accept any numeric type and fix a Result deref in
search_service so the newly instrumented TUs compile with Tracy.

Signed-off-by: trvon <me@trevon.dev>

---------

Signed-off-by: trvon <me@trevon.dev>
2026-10-14 08:32:56 -06:00

31 lines
1.4 KiB
Markdown

# Tracy profiling
## Profiling lane
Build with Tracy in every yams library (`yams_tracy_args`/`yams_tracy_deps` in
the root `meson.build`; clients are built with `TRACY_ON_DEMAND`):
./setup.sh Profiling --with-tests # build/profiling
meson compile -C build/profiling -j12 catch2_memory_sync yams-daemon
Capture (client listens on 8086 by default; if taken it falls back to the next
free port, so find it with `ss -ltnp | grep <pid>`):
TRACY_NO_EXIT=1 build/profiling/tests/catch2_memory_sync &
tracy-capture -o run.tracy -a 127.0.0.1 -p <port> -f
tracy-csvexport -e run.tracy > zones.csv
Columns: `name,src_file,src_line,total_ns,total_perc,counts,mean_ns,min_ns,max_ns,std_ns`.
With `-e` (`--self`) the time columns hold self time instead of inclusive time;
export twice to get both.
Clients are `TRACY_ON_DEMAND`: zones fired before `tracy-capture` connects are
lost, so short tests need `TRACY_NO_EXIT=1` and a capture started while the
process is still alive, and the workload must run after the connect.
`tracy-capture` and `tracy-csvexport` must come from the same Tracy release as
the Conan client (`conan list "tracy/*"`); a mismatched protocol version is
rejected on connect. On grim they live in `/data/tracy-tools`, built with
`-DNO_FILESELECTOR=ON -DDOWNLOAD_CAPSTONE=OFF`.
With `enable-profiling=false` nothing changes: no args, no deps.