From a7504c6bb2ec9e906891e42bc3df28b276e67143 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 12:09:27 -0300 Subject: the backends together: a ring under the debugger, strings that do not collide ztrace record and dbg take --ring, --preload and --alloc: the target gets the ring ztrace run gives it, and the debugger drains it while the target runs (polling for the stop, so a full ring cannot hold both) and before it reports a stop. A program compiled by ztrace cc, with the agent preloaded, stopped at breakpoints, is one recording in order; test-together checks it. Recording such a program showed the debugger's file names and the pass's strings both counted from 1: event.stringId (a hash, top bit set) is now what every producer without a table of its own uses. --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 8ce505d..9f94bab 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,30 @@ it back is 178 000 moments a second in order, a millisecond to any one. Scattered writes and new bulk data are what cost: each chunk of 64 bytes that changed is written at the next keyframe with its path in the tree. +## Together + +The backends are not modes to choose between: they feed one sink. A +program compiled by `ztrace cc`, with the agent preloaded, run under the +debugger, gives one recording, in order: the stops and their registers +(ptrace), the allocations (the agent), the lines, calls, stores and named +variables (the pass). + +```sh +ztrace cc -- clang -O0 targets/instr_list.c -o list +ztrace record --by break -b push -b reverse --alloc --preload zig-out/lib/libztrace-agent.so -- ./list +ztrace dbg --ring -- ./list # breakpoints and time travel over what the program says of itself +ztrace show out.ztrace 40 # the thread's line and calls, the live heap, each variable's bytes +zig build test-together +``` + +`--ring` (implied by `--preload` and `--alloc`) gives a target under +ptrace the ring `ztrace run` gives it; the debugger drains it while the +target runs and before it reports a stop. The agent's hooks and syscall +tracing are signals, which a debugger takes first: under ptrace, use +breakpoints and the debugger's own syscall stops. Strings never collide: +the pass counts its from 1, a symbol's name has its address as its id, and +every other producer uses `event.stringId`, a hash with the top bit set. + ## The debugger `ztrace dbg -- PROGRAM` starts a program stopped and reads commands (from a -- cgit v1.3