1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
|
# computeranim
Two things that meet at a file:
- **ztrace**, a small tracer/debugger: many ways to watch a program run, one
event format, one recording.
- **canim**, animations of what was recorded (registers, memory, syscalls,
data structures, source), written as code, exported as frames for ffmpeg.
```sh
zig build # zig-out/bin/ztrace
zig build test # everything; test-<area> for one
ztrace record -o fib.ztrace -- ./fib 10 # under ptrace, an instruction a moment
ztrace record --syscalls -- ls / # ... or a syscall a moment
ztrace run --preload libztrace-agent.so -- ./prog # in-process, no ptrace
ztrace dump fib.ztrace
```
## The pieces
| Where | What |
| --- | --- |
| `src/trace/event.zig` | `Event` (64 bytes: time, thread, kind, six words) plus a payload; `Kind`; `Regs`; `Sink` |
| `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/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 |
| `src/anim/`, `scenes/` | the animation library and its scenes |
| `src/cli/` | the `ztrace` command, a file a subcommand |
| `targets/` | programs to trace |
| `build/` | each area's part of the build |
Every backend produces `Event`s into a `Sink`. The recorder is one; the ring
is another, with the recorder at its far end.
## A recording
An xitdb file: a history of immutable **moments**. A moment is the state
then (registers per thread, every byte of memory seen so far, the strings
defined), sharing what did not change with the moment before, and the
events that led to it. `Trace.moment(i)` is any of them, in any order: time
travel is an index.
The recorder ends a moment at the kinds in `Recorder.cut` (by default a
step, a breakpoint, a syscall's exit, a signal, a source line, a mark), so
the cost of time travel is chosen per recording. Measured (release, this
machine): a moment costs about 10 µs and 1 KB before its own data; an
instruction-level recording of `fib(12)`, 145 000 moments, is 245 MB at
56 000 moments a second; events inside a moment cost their own bytes only.
## Depends on
- [sketchbook](../sketchbook): window, drawing, shaders, hot reload, the
manim-style `anim` module, frame export.
- [pardes](../02-pardes-code): tree-sitter parsing, highlighting, themes.
- [xitdb](https://github.com/xit-vcs/xitdb): the recording.
x86-64 Linux, Zig 0.17.
|