summaryrefslogtreecommitdiff
path: root/build/agent.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:44:48 -0300
committerGabriel Schneider <[email protected]>2026-11-10 12:09:34 -0300
commitce7c0abf14e7ab056d5479adc3f05df9976e94e4 (patch)
tree8931de9a55b3d7c2ec2d52d3b3817c6f7eb5db5a /build/agent.zig
parente7aa7801c10ed34194b7fe3f5ca8722a72404e65 (diff)
downloadcomputeranim-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 'build/agent.zig')
-rw-r--r--build/agent.zig119
1 files changed, 118 insertions, 1 deletions
diff --git a/build/agent.zig b/build/agent.zig
index d3c7eb3..bdb9317 100644
--- a/build/agent.zig
+++ b/build/agent.zig
@@ -1,5 +1,122 @@
+//! The in-process agent: the library in its two forms, the header, and
+//! real targets recorded through it.
+const std = @import("std");
const Ctx = @import("../build.zig").Ctx;
+const Compile = std.Build.Step.Compile;
pub fn add(ctx: Ctx) void {
- _ = ctx;
+ const b = ctx.b;
+ const imports: []const std.Build.Module.Import = &.{.{ .name = "ztrace", .module = ctx.ztrace }};
+
+ // For Zig programs: the agent compiled in.
+ const module = b.addModule("ztrace-agent", .{ .root_source_file = b.path("src/agent/agent.zig"), .target = ctx.target, .optimize = ctx.optimize, .imports = imports });
+ // `ztrace run` reads its child with the code the agent reads itself with.
+ ctx.exe.root_module.addImport("ztrace-agent", module);
+
+ // For everything else: libztrace-agent.so to preload, libztrace-agent.a to link in.
+ var libs: [2]*Compile = undefined;
+ for (&libs, [_]std.builtin.LinkMode{ .dynamic, .static }) |*lib, linkage| {
+ // LLVM always: the agent has inline assembly the self-hosted backend does not take.
+ lib.* = b.addLibrary(.{ .name = "ztrace-agent", .linkage = linkage, .use_llvm = true, .root_module = b.createModule(.{
+ .root_source_file = b.path("src/agent/lib.zig"),
+ .target = ctx.target,
+ .optimize = ctx.optimize,
+ .imports = imports,
+ .pic = true,
+ }) });
+ b.installArtifact(lib.*);
+ }
+ b.getInstallStep().dependOn(&b.addInstallHeaderFile(b.path("include/ztrace.h"), "ztrace.h").step);
+
+ const t: Tests = .{
+ .ctx = ctx,
+ .step = ctx.areaTest("test-agent", "The in-process agent on real targets"),
+ .preload = libs[0],
+ .check = b.addExecutable(.{ .name = "agent-check", .root_module = b.createModule(.{ .root_source_file = b.path("src/agent/check.zig"), .target = ctx.target, .optimize = ctx.optimize, .imports = imports }) }),
+ };
+ t.step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = module, .use_llvm = true })).step);
+
+ // Programs that know nothing of the tracer, with the agent preloaded.
+ const list = ctx.cTarget("agent_list", &.{"agent_list.c"});
+ const fib = ctx.cTarget("agent_fib", &.{"agent_fib.c"});
+ const sort = ctx.cTarget("agent_sort", &.{"agent_sort.c"});
+ const sys = ctx.cTarget("agent_sys", &.{"agent_sys.c"});
+ for ([_]*Compile{ list, fib, sort, sys }) |exe| b.installArtifact(exe);
+ t.expect("list", "100", t.record(list, true, &.{"--alloc"}, &.{"100"}));
+ t.expect("fib", "10", t.record(fib, true, &.{ "--hook", "fib" }, &.{"10"}));
+ t.expect("sort", "numbers", t.record(sort, true, &.{ "--hook", "swap", "--watch", "numbers" }, &.{}));
+ t.expect("syscalls", "", t.record(sys, true, &.{"--syscalls"}, &.{}));
+ // Everything at once.
+ t.expect("list", "100", t.record(list, true, &.{ "--alloc", "--syscalls", "--hook", "main", "--watch", "stdout" }, &.{"100"}));
+
+ // Stops: the target held at each return of swap while the tracer reads the array from outside.
+ t.expect("sort", "numbers", t.record(sort, true, &.{ "--hook", "swap", "--stop-at", "ret", "--read", "numbers" }, &.{}));
+ const asked = t.record(fib, true, &.{ "--hook", "fib", "--stop-at", "call", "-i" }, &.{"3"}).run;
+ asked.setStdIn(.{ .bytes = "s\n\nx 8 4\nc\n" });
+ asked.expectStdOutMatch("call tid=");
+ asked.expectStdOutMatch("not readable");
+ asked.expectStdOutMatch("fib(3) = 2");
+
+ // With no tracer the preloaded agent is not there.
+ const alone = b.addSystemCommand(&.{"env"});
+ alone.addPrefixedArtifactArg("LD_PRELOAD=", libs[0]);
+ alone.addArtifactArg(list);
+ alone.expectStdOutEqual("sum 4950 of 100\n");
+ t.step.dependOn(&alone.step);
+
+ // Programs that annotate themselves, with the agent linked in: against
+ // glibc, statically against musl, and as a module of a Zig program.
+ const api = ctx.cTarget("agent_api", &.{"agent_api.c"});
+ const musl = b.resolveTargetQuery(.{ .cpu_arch = ctx.target.result.cpu.arch, .os_tag = .linux, .abi = .musl });
+ const api_static_module = b.createModule(.{ .target = musl, .optimize = .Debug, .link_libc = true });
+ api_static_module.addCSourceFiles(.{ .root = b.path("targets"), .files = &.{"agent_api.c"}, .flags = &.{ "-O1", "-g" } });
+ const api_static = b.addExecutable(.{ .name = "agent_api_static", .root_module = api_static_module, .linkage = .static });
+ for ([_]*Compile{ api, api_static }) |exe| {
+ exe.root_module.addIncludePath(b.path("include"));
+ exe.root_module.linkLibrary(libs[1]);
+ t.expect("api", "", t.record(exe, false, &.{}, &.{}));
+ }
+ const api_zig = ctx.zigTarget("agent_zig", "targets/agent_zig.zig");
+ api_zig.root_module.addImport("ztrace-agent", module);
+ api_zig.use_llvm = true;
+ t.expect("api", "", t.record(api_zig, false, &.{}, &.{}));
+ for ([_]*Compile{ api, api_static, api_zig }) |exe| b.installArtifact(exe);
}
+
+const Recording = struct { run: *std.Build.Step.Run, file: std.Build.LazyPath };
+
+const Tests = struct {
+ ctx: Ctx,
+ step: *std.Build.Step,
+ preload: *Compile,
+ check: *Compile,
+
+ /// `ztrace run OPTIONS -- TARGET ARGS`, which has to end with the target's exit 0.
+ fn record(t: Tests, target: *Compile, preload: bool, options: []const []const u8, args: []const []const u8) Recording {
+ const run = t.ctx.b.addRunArtifact(t.ctx.exe);
+ run.addArgs(&.{ "run", "-o" });
+ const file = run.addOutputFileArg("agent.ztrace");
+ if (preload) {
+ run.addArg("--preload");
+ run.addArtifactArg(t.preload);
+ }
+ run.addArgs(options);
+ run.addArg("--");
+ run.addArtifactArg(target);
+ run.addArgs(args);
+ run.expectStdErrMatch("(0 dropped)");
+ run.expectStdErrMatch("exit 0");
+ t.step.dependOn(&run.step);
+ return .{ .run = run, .file = file };
+ }
+
+ /// The recording `run` made holds what `scenario` says (src/agent/check.zig).
+ fn expect(t: Tests, scenario: []const u8, argument: []const u8, recording: Recording) void {
+ const check = t.ctx.b.addRunArtifact(t.check);
+ check.addArg(scenario);
+ check.addFileArg(recording.file);
+ check.addArg(argument);
+ check.expectExitCode(0);
+ t.step.dependOn(&check.step);
+ }
+};