summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md74
1 files changed, 73 insertions, 1 deletions
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-<area> 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