# 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- 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 list of immutable **moments**. A moment is the state of the program then, 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. | `Moment` | from the events | | --- | --- | | `regs(tid)` | any event carrying `Regs` as its payload | | `read(addr, buf, known)` | `mem_write`: every byte seen so far, and which are known | | `heap()`, `allocation(addr)` | `alloc`, `free`: the live allocations | | `stack(tid)` | `call`, `ret`: the calls a thread is inside | | `variables()` | `variable`: the live named variables; a local goes with its call | | `line(tid)` | `line` | | `mappings()`, `mapping(addr)` | `map`, `unmap` | | `string(id)` | `string` | | `events()` | everything, as it came | 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; moments are written 256 a transaction. Measured (release, this machine): a moment holding one small event is 284 bytes and about 1 µs (936 000 a second through the ring); an instruction-level recording of `fib(12)` under ptrace, 142 000 moments each with the registers, is 111 MB at 165 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.