diff options
| -rw-r--r-- | README.md | 82 |
1 files changed, 80 insertions, 2 deletions
@@ -12,7 +12,9 @@ zig build # zig-out/bin/ztrace zig build test # everything; test-<area> for one zig build bench-store # what a recording costs a moment ztrace record -o fib.ztrace -- ./fib 10 # under ptrace, an instruction a moment -ztrace record --syscalls -- ls / # ... or a syscall 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 +ztrace dbg -- ./fib 10 # step, break, look, and go back ztrace run --preload libztrace-agent.so -- ./prog # in-process, no ptrace ztrace dump fib.ztrace ``` @@ -25,7 +27,9 @@ ztrace dump fib.ztrace | `src/trace/Ring.zig` | events from the target to the tracer through shared memory; a producer can be held at a kind (`stop_mask`) until `resumeAll` | | `src/trace/client.zig`, `host.zig` | the ring's two ends: inside the target, inside the tracer | | `src/trace/store.zig` | `Recorder` (a `Sink`) and `Trace`: the recording, in xitdb | -| `src/trace/ptrace.zig` | the out-of-process backend | +| `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 | | `llvm/` | compiler instrumentation and its runtime | | `src/trace/kernel*` | perf events and BPF | @@ -83,6 +87,80 @@ 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. +## The debugger + +`ztrace dbg -- PROGRAM` starts a program stopped and reads commands (from a +script when stdin is no terminal): `run`/`r`, `continue`/`c`, `step`/`s` (a +source line), `stepi`/`si`, `break`/`b` (a function, `file:line`, +`*address`), `syscalls on|off|NAME`, `watch`, `regs`, `x`, `bt`, `quit`. +Every stop is a moment of a recording, and `back [N]`, `forward [N]` and +`goto MOMENT` look into it: `regs`, `x` and `bt` then answer from the +recording, while the program stays where it stopped. + +``` +$ printf 'b fib\nr\nbt\ns\nback 1\nx $rsp 16\n' | ztrace dbg -- zig-out/targets/fib 10 +[0] step at 7f82d095e7e0 ld-linux-x86-64.so.2!217e0 +(ztrace) b fib +breakpoint 1 at 563f798b1814 fib+4 (fib.c:4) +(ztrace) r +[1] breakpoint 1 at 563f798b1814 fib+4 (fib.c:4) +(ztrace) bt +#0 563f798b1814 fib+4 (fib.c:4) +#1 563f798b17ea main+42 (fib.c:10) +#2 7f82d0627781 libc.so.6!27781 +#3 7f82d06278b9 libc.so.6!__libc_start_main+137 +#4 563f798b16e5 _start+37 +(ztrace) s +[2] step at 563f798b181c fib+12 (fib.c:5) +(ztrace) back 1 +[1] breakpoint 1 at 563f798b1814 fib+4 (fib.c:4) +(ztrace) x $rsp 16 +7ffc89ca6570 90 65 ca 89 fc 7f 00 00 ea 17 8b 79 3f 56 00 00 .e.........y?V.. +(ztrace) out.ztrace: 3 moments +``` + +`ztrace record` is the same debugger left to run: `--by insn|line|syscall|break` +says where it stops, `-b` adds breakpoints, `-w` watches, `--strace` prints +the syscalls. In a program, it is `zt.Debugger`: + +```zig +var d = try zt.Debugger.spawn(gpa, io, path, argv, envp, recorder.sink()); +defer d.deinit(); +d.syscalls = .record; // or .stop, or a hook: d.on_syscall +try d.watch(d.symbol("dist").?.addr, 8); // recorded at every stop, the changed words only +_ = try d.breakAt(try d.resolve("list_done"), .{ .func = hook }); // a hook says .go or .stop +while (true) switch (try d.step()) { // or stepi(), cont() + .exited => break, + else => {}, // d.regs, d.read, d.write, d.setRegs, d.snapshot +}; +``` + +Of memory it records what is asked for and no more: the watched regions, +a window above the stack pointer, and at most 256 bytes of what a syscall +points at (`-s`), each as the 8-byte words that changed since the stop +before. What it costs (`zig build bench-debugger`; release, this machine): + +| | a second | µs | bytes a moment | +| --- | --- | --- | --- | +| an instruction: ptrace step and wait | 273 000 | 3.7 | | +| ... as `Debugger.stepi` with events, the source line looked up | 260 000 | 3.9 | | +| ... and 128 bytes of stack watched | 212 000 | 4.7 | | +| ... recorded (`ztrace record`) | 189 000 | 5.3 | 55 | +| a source line (16 instructions here), recorded | 16 000 | 62 | 60 | +| a breakpoint hit, recorded | 82 000 | 12 | 94 | +| a syscall, entry and exit: native 0.1 µs; stopped at | 120 000 | 8.3 | | +| ... recorded (`--by syscall`) | 100 000 | 10 | 208 | + +Memory is read with `process_vm_readv`: 64 bytes in 0.3 µs where +`PTRACE_PEEKDATA` takes 2.2, a megabyte at 22 GiB/s against 28 MiB/s. It is +written the same way, and through `/proc/pid/mem` where the page is +read-only (a breakpoint in code: 0.5 µs). + +Limits: `bt` walks frame pointers, so a function without a frame hides its +caller. Threads are followed, each stop is one thread's and the others run +on; stepping by line in a threaded program reports the other threads' +instructions too. A target that execs is not followed into the new program. + ## Depends on - [sketchbook](../sketchbook): window, drawing, shaders, hot reload, the |
