summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:58:00 -0300
committerGabriel Schneider <[email protected]>2026-11-10 11:58:53 -0300
commit62183e7ce8e6da7d22be451683376066a8bcd282 (patch)
tree9fce93e505b705151ee81fae7deeecbf10f1b12e
parent8beab959b633e6641d07aba053a55e6e8e61eb00 (diff)
downloadcomputeranim-62183e7ce8e6da7d22be451683376066a8bcd282.tar.gz
computeranim-62183e7ce8e6da7d22be451683376066a8bcd282.zip
README: the debugger
Co-Authored-By: Claude Fable 5.2 <[email protected]>
-rw-r--r--README.md82
1 files changed, 80 insertions, 2 deletions
diff --git a/README.md b/README.md
index 38c7658..2d94ed2 100644
--- a/README.md
+++ b/README.md
@@ -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