diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 11:44:48 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 12:09:34 -0300 |
| commit | ce7c0abf14e7ab056d5479adc3f05df9976e94e4 (patch) | |
| tree | 8931de9a55b3d7c2ec2d52d3b3817c6f7eb5db5a /src/agent/agent.zig | |
| parent | e7aa7801c10ed34194b7fe3f5ca8722a72404e65 (diff) | |
| download | computeranim-ce7c0abf14e7ab056d5479adc3f05df9976e94e4.tar.gz computeranim-ce7c0abf14e7ab056d5479adc3f05df9976e94e4.zip | |
agent: the in-process backend, and ztrace run's options for it
libztrace-agent.so (preloaded) and libztrace-agent.a (linked in), one
source: map and thread_start at startup; alloc/free from the interposed
allocator; syscall_enter/exit through Syscall User Dispatch; call/ret
from int3 hooks; mem_write from watched regions diffed in-process; the
target-side API (include/ztrace.h, and the ztrace-agent module for Zig).
ztrace run turns each on (--alloc --syscalls --hook --watch), chooses the
moments (--cut), and stops the target at event kinds without ptrace
(--stop-at, --read, -i). test-agent records real targets and checks the
recordings.
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'src/agent/agent.zig')
| -rw-r--r-- | src/agent/agent.zig | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/src/agent/agent.zig b/src/agent/agent.zig new file mode 100644 index 0000000..ecf2768 --- /dev/null +++ b/src/agent/agent.zig @@ -0,0 +1,164 @@ +//! The in-process backend: code that lives inside the target, preloaded +//! (libztrace-agent.so), linked in (libztrace-agent.a), or imported by a Zig +//! program (this module). When the process starts it attaches the ring its +//! tracer handed it and turns on what `ztrace run` asked for through +//! ZTRACE_* variables; with no ring it does nothing. +//! +//! Raw syscalls only, no libc, no allocation: this code runs inside malloc +//! and inside signal handlers. +const std = @import("std"); +const linux = std.os.linux; +const zt = @import("ztrace"); +const client = zt.client; +const Kind = zt.Kind; +pub const symbols = @import("symbols.zig"); +pub const signal = @import("signal.zig"); +pub const sud = @import("sud.zig"); +pub const hook = @import("hook.zig"); +pub const regions = @import("watch.zig"); + +/// Null when nothing traces the process: every entry point returns at once. +pub var ring: ?*zt.Ring = null; +/// `alloc` and `free` events wanted (the library's interposed malloc asks). +pub var allocations = false; +/// The kinds that end a moment in the recording (ZTRACE_CUT): watched memory +/// is brought up to date before each. +var cut: u64 = 0; +/// 0 not started, 1 starting, 2 started. +var state: std.atomic.Value(u8) = .init(0); +threadlocal var started = false; + +/// The most bytes an event of ours carries; more is cut short, or split. +pub const max_payload = 1024; + +/// Every entry point comes through here first. A Zig program that wants its +/// hooks and syscalls from the start calls it at the top of main; for the +/// rest the library has a constructor. +pub fn init() void { + if (state.load(.acquire) != 0 or state.cmpxchgStrong(0, 1, .acquire, .monotonic) != null) return; + defer state.store(2, .release); + const r = client.get() orelse return; + var buf: [1 << 16]u8 = undefined; + const env = client.environ(&buf); + cut = if (client.getenv(env, "ZTRACE_CUT")) |v| std.fmt.parseInt(u64, v, 0) catch 0 else 0; + ring = r; + + var maps = symbols.Maps.open(null) orelse return; + while (maps.next()) |m| emit(.map, 0, .{ m.start, m.end - m.start, m.prot, m.offset, 0, 0 }, text(m.path)); + maps.close(); + threadStart(); + + if (client.getenv(env, "ZTRACE_WATCH")) |list| { + var specs = std.mem.tokenizeScalar(u8, list, ','); + while (specs.next()) |spec| { + const region = symbols.find(null, spec) orelse symbols.Symbol{ .addr = 0, .size = 0 }; + if (region.size != 0) watch(@as([*]const u8, @ptrFromInt(region.addr))[0..region.size], spec) else unknown(spec); + } + } + if (client.getenv(env, "ZTRACE_HOOKS")) |list| { + var specs = std.mem.tokenizeScalar(u8, list, ','); + while (specs.next()) |spec| { + if (symbols.find(null, spec)) |function| hook.add(function.addr) else unknown(spec); + } + } + allocations = client.getenv(env, "ZTRACE_ALLOC") != null; + if (client.getenv(env, "ZTRACE_SYSCALLS") != null) { + sud.enable(); + sud.selector = sud.block; + } +} + +/// The user asked for something that is not there: say so where they will see it. +fn unknown(spec: []const u8) void { + for ([_][]const u8{ "ztrace agent: nothing called ", spec, "\n" }) |part| _ = linux.write(2, part.ptr, part.len); +} + +pub fn threadId() u32 { + return client.threadId(); +} + +/// The calling thread's first sign of life. Once per thread, whoever notices it first. +pub fn threadStart() void { + if (started) return; + started = true; + emit(.thread_start, 0, .{ threadId(), 0, 0, 0, 0, 0 }, ""); + sud.arm(); +} + +/// In a forked child, which remembers being its parent. +pub fn forked() void { + const tid: u32 = @intCast(linux.gettid()); + if (tid == client.tid) return; + client.tid = tid; + started = false; + threadStart(); +} + +pub fn emit(kind: Kind, aux: u16, a: [6]u64, payload: []const u8) void { + const r = ring orelse return; + // What the agent does to get an event out (a futex when the ring is + // full, or to wake the tracer) is not the target's doing. + const was = sud.selector; + sud.selector = sud.allow; + defer sud.selector = was; + if (cut & kind.bit() != 0) regions.diff(); + r.emit(.{ .ts = zt.event.now(), .tid = threadId(), .kind = kind, .aux = aux, .a = a }, payload); +} + +/// A string's id is its hash: no backend needs to ask another which are taken. +pub fn stringId(string: []const u8) u64 { + return std.hash.Wyhash.hash(0, string); +} + +/// `bytes` as a payload: cut to `max_payload`, and never the length of +/// `Regs`, which the recorder would take for registers. +pub fn text(bytes: []const u8) []const u8 { + const len = @min(bytes.len, max_payload); + return bytes[0 .. len - @intFromBool(len == @sizeOf(zt.Regs))]; +} + +/// `mem_write` events: `bytes` is what is at `addr` now. +pub fn write(addr: u64, bytes: []const u8) void { + var at: usize = 0; + while (at < bytes.len) : (at += max_payload) { + const part = bytes[at..@min(bytes.len, at + max_payload)]; + emit(.mem_write, 0, .{ addr + at, part.len, 0, 0, 0, 0 }, part); + } +} + +// The target's side: what a program that links the agent calls. The same +// three are in include/ztrace.h for C. + +/// A point in the run worth a moment: a `mark` event with a text and a value. +pub fn mark(label: []const u8, value: u64) void { + init(); + emit(.mark, 0, .{ value, 0, 0, 0, 0, 0 }, text(label)); +} + +/// Names `memory` (a `variable` event), records it, and keeps recording what +/// changes in it: only the bytes that changed, before each event that ends a +/// moment. It must stay mapped. Watched from inside a hooked call, it is +/// forgotten when that call returns. +pub fn watch(memory: []const u8, name: []const u8) void { + init(); + if (ring == null) return; + const was = sud.selector; + sud.selector = sud.allow; + defer sud.selector = was; + const id = stringId(name); + emit(.string, 0, .{ id, 0, 0, 0, 0, 0 }, text(name)); + emit(.variable, 0, .{ @intFromPtr(memory.ptr), memory.len, id, 0, 0, 0 }, ""); + write(@intFromPtr(memory.ptr), memory); + regions.add(memory, threadId(), hook.open()); +} + +/// Records `memory` as it is now, once. +pub fn snapshot(memory: []const u8) void { + init(); + write(@intFromPtr(memory.ptr), memory); +} + +test { + _ = symbols; + _ = regions; +} |
