From a10e1691dbe5b944812dc8761a450636bc247e3d Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 12:07:53 -0300 Subject: agent: bench-agent and its numbers, hooks with names, an archive cc can link zig build bench-agent runs each capability against its native loop and prints what it costs and writes; README has the table. ztrace run looks at the ring a little longer before sleeping (a target that finds the tracer asleep pays a futex wake an event). A hooked function's name is defined as the string of its address, so the recorder's call stack reads fib. A static link without libc's malloc says which -u to add. The archive carries no stack probes, so cc links it in debug builds too. Tests for --wrap (musl, zig cc) and for a recording that fills. Co-Authored-By: Claude Fable 5.2 --- README.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 73 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 7a7c622..8ce505d 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ Two things that meet at a file: zig build # zig-out/bin/ztrace zig build test # everything; test- for one zig build bench-store # what a recording costs a moment +zig build bench-agent -Doptimize=ReleaseFast # what the agent costs the target ztrace record -o fib.ztrace -- ./fib 10 # under ptrace, an instruction a moment ztrace record --by line -w dist -- ./graph # ... or a source line, a global watched ztrace record --syscalls --strace -- ls / # ... or a syscall, printed as strace does @@ -31,7 +32,7 @@ ztrace dump fib.ztrace | `src/trace/ptrace.zig` | the out-of-process backend: a process and its threads under ptrace | | `src/trace/Debugger.zig` | on top of it: continue, step, breakpoints, hooks, watches, every stop an event | | `src/trace/Symbols.zig`, `syscalls.zig` | what an address means (modules, ELF symbols, DWARF lines); syscalls by name and shape | -| `src/agent/` | the in-process backend: a library preloaded or linked into the target | +| `src/agent/`, `include/ztrace.h` | the in-process backend: a library preloaded or linked into the target, and what the target can say through it | | `llvm/pass.cpp`, `src/instr/` | compiler instrumentation: the LLVM pass, the runtime it calls, the type descriptions | | `src/trace/kernel*` | perf events and BPF | | `anim/` | canim, a package of its own (it needs sketchbook and pardes; ztrace does not): the animation library and its scenes | @@ -217,6 +218,77 @@ is declared, not dumped, and a global is written once, at the start. 400 times slower traced at `-O0`. Recording at a moment a line takes 1.9 million events a second. +## The agent + +`libztrace-agent.so` is preloaded into a program (`ztrace run --preload`); +`libztrace-agent.a` is linked into one, which can then say things about +itself (`include/ztrace.h`; a Zig program imports the `ztrace-agent` module +instead). Inside the target it has no libc and makes raw syscalls only, so +the same library serves glibc and musl, dynamic and static. With no tracer +it does nothing: a preloaded malloc costs 2 ns more. + +```sh +ztrace run --preload zig-out/lib/libztrace-agent.so --alloc -- ./agent_list 100 +ztrace run --preload ... --syscalls -- ls / +ztrace run --preload ... --hook fib -- ./agent_fib 10 # ztrace show FILE 6: the call stack then +ztrace run --preload ... --hook swap --watch numbers -- ./agent_sort +ztrace run --preload ... --hook swap --stop-at ret --read numbers -- ./agent_sort +ztrace run --preload ... --hook fib --stop-at call -i -- ./agent_fib 5 +ztrace run -- ./agent_api # the agent linked in, annotating itself +zig build test-agent +zig build bench-agent -Doptimize=ReleaseFast +``` + +| | events | how | +| --- | --- | --- | +| startup | `map` a mapping, `thread_start` a thread | /proc/self/maps; pthread_create and fork interposed | +| `--alloc` | `alloc`, `free`, with the caller's pc | malloc and its family interposed (`dlsym(RTLD_NEXT)`; `--wrap` when linked statically) | +| `--syscalls` | `syscall_enter` (path, bytes written: `--capture`, 256), `syscall_exit` | Syscall User Dispatch: SIGSYS, handled in the target | +| `--hook SYM` | `call` with the registers, `ret` with the value | int3 at the entry, the return address swapped | +| `--watch SYM` | `mem_write`: the bytes that changed, before each event that ends a moment | compared in place against a shadow copy | +| `ztrace_mark`, `ztrace_watch`, `ztrace_snapshot` | `mark`; `variable` and the watch; `mem_write` | the target's own calls | +| `--stop-at KIND` | the target held at each, while the tracer reads (`--read`) or asks (`-i`) | the ring's `stop_mask`, a futex | + +Why these. **Hooks** are breakpoints because a breakpoint needs to know +nothing about the code it lands on: an inline jump needs an x86-64 length +decoder to move the prologue, and patching the PLT misses calls inside a +module. The price is a signal a call; the return costs none. **Watches** +compare memory in the target's own address space because that is exact at +any size, needs no syscall, and does not disturb the target: page +protection makes the kernel refuse syscalls that write there, and soft-dirty +bits still need the compare, a page at a time. **Syscalls** go through +SIGSYS because the kernel then needs no second process: the cost is two +signal frames, on a stack of the agent's so that it works on threads with +almost none. + +Measured (`zig build bench-agent -Doptimize=ReleaseFast`, an i7-11700, each +loop 10^5 to 5 10^6 times; bytes are the recording's): + +| | native | traced | recorded | +| --- | --- | --- | --- | +| a malloc and a free, `--alloc` | 4 ns | 168 ns (11.7 M events/s) | 14 bytes an event | +| ... each a moment (`--cut alloc,free`) | | 4.9 µs, the recorder's | 65 bytes a moment | +| a syscall, `--syscalls` | 73 ns | 950 ns; 830 ns is the two signal frames | 87 bytes a syscall, a moment | +| a syscall under ptrace (`ztrace record --syscalls`) | | 9000 ns | 129 bytes | +| a hooked call | 1 ns | 990 ns | 77 bytes: two moments, with registers | +| ... watching 1 KiB, 64 KiB, 1 MiB | | +43 ns, +1.5 µs, +17.5 µs a moment | what changed | +| ... held at its return (`--stop-at ret`) | | +1.3 µs | | +| ... the tracer reading 1 KiB, 64 KiB, 1 MiB from outside | | +2.5 µs, +6.5 µs, +66 µs a stop | what changed | +| events that end no moment, through the ring | | 11 M a second | 8 bytes an event | +| marks, each a moment | | 2.5 M a second | 32 bytes a moment | + +`ztrace run` ends a moment at the recorder's kinds and at `call` and `ret` +(hooks are asked for by name, and a call and its return are the steps of +such a recording); `alloc` and `free` end none unless `--cut` says so. A +recording that reaches `--max-size` (1G) ends the run. + +Limits: a hooked function called with SIGTRAP blocked dies (not under +`--syscalls`, which keeps the target's masks clear of it); C++ exceptions +do not unwind through a hooked call; a pointer the kernel would answer with +EFAULT faults in the handler; syscalls made from the vDSO never enter the +kernel and are not seen, as under ptrace; a target that needs SIGSYS or its +own alternate signal stack is told it has them. + ## Depends on - [sketchbook](../sketchbook): window, drawing, shaders, hot reload, the -- cgit v1.3