# 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 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.