summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 12:17:50 -0300
committerGabriel Schneider <[email protected]>2026-11-10 12:19:28 -0300
commit2e01933dc5c0c1903c1b7f86e453829fee9a541b (patch)
treee3f1599a7c7bfafc4ebbc6a0b13e0134b4436706
parent297943b01e18bb3d1dd41a8d3e220811de25228b (diff)
downloadcomputeranim-2e01933dc5c0c1903c1b7f86e453829fee9a541b.tar.gz
computeranim-2e01933dc5c0c1903c1b7f86e453829fee9a541b.zip
kernel: smaller BPF records, syscall tracepoints sorted out in place, the README
Syscall entries and kprobes send the event alone (a kernel function's registers are not the thread's; a syscall's are its arguments), a probe's event is not inherited (it failed the target's clone). The per-syscall tracepoints are told entry from exit on the events themselves, not on a second set. The VM has two CPUs and a time limit. README: the kernel's view, with what each mode costs. Co-Authored-By: Claude Fable 5.2 <[email protected]>
-rw-r--r--README.md63
-rw-r--r--build/kernel_vm.sh2
-rw-r--r--src/cli/probe.zig7
-rw-r--r--src/trace/bpf.zig67
-rw-r--r--src/trace/kernel_test.zig5
-rw-r--r--src/trace/perf.zig18
6 files changed, 117 insertions, 45 deletions
diff --git a/README.md b/README.md
index 9f94bab..cb4cce5 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,8 @@ ztrace record --syscalls --strace -- ls / # ... or a syscall, printed as strac
ztrace dbg -- ./fib 10 # step, break, look, and go back
ztrace run --preload libztrace-agent.so -- ./prog # in-process, no ptrace
ztrace cc -- clang sort.c -o sort && ztrace run -- ./sort # compiled in: lines, calls, variables, stores
+ztrace perf --faults --syscalls --watch counter -- ./prog # the kernel's view, at full speed
+ztrace probe --dry-run --usdt provider:name -- ./prog # ... with BPF, for root
ztrace dump fib.ztrace
```
@@ -34,7 +36,7 @@ ztrace dump fib.ztrace
| `src/trace/Symbols.zig`, `syscalls.zig` | what an address means (modules, ELF symbols, DWARF lines); syscalls by name and shape |
| `src/agent/`, `include/ztrace.h` | the in-process backend: a library preloaded or linked into the target, and what the target can say through it |
| `llvm/pass.cpp`, `src/instr/` | compiler instrumentation: the LLVM pass, the runtime it calls, the type descriptions |
-| `src/trace/kernel*` | perf events and BPF |
+| `src/trace/perf.zig`, `bpf.zig`, `usdt.zig` | the kernel's view: perf events for any user, BPF programs for root, the static probes of `<sys/sdt.h>` |
| `anim/` | canim, a package of its own (it needs sketchbook and pardes; ztrace does not): the animation library and its scenes |
| `design/` | the visual system the animations follow, with mock frames |
| `src/cli/` | the `ztrace` command, a file a subcommand |
@@ -313,6 +315,65 @@ EFAULT faults in the handler; syscalls made from the vDSO never enter the
kernel and are not seen, as under ptrace; a target that needs SIGSYS or its
own alternate signal stack is told it has them.
+## The kernel's view
+
+Two tiers, by what a machine lets its user do. Both hold the program at its
+first instruction until they are attached, then let it run at full speed:
+no stops, records out of a kernel ring buffer, stamped with the clock every
+other backend uses.
+
+**`ztrace perf`** needs no privilege: `perf_event_open` as
+`kernel.perf_event_paranoid=2` allows it, which is user space only, on one's
+own processes. `perf.Session.open(gpa, pid, options, sink)` is the same for
+a tracer that has its own target (stopped, or it misses the start).
+
+| option | events | costs the program | bytes an event |
+| --- | --- | --- | --- |
+| `-e`, `--interval MS` | `sample`: a counter's total | nothing measurable | 27 |
+| `--sample HZ`, `--callchain` | `sample`: pc, callers | 3% at 40 kHz with callers | 24, 48 |
+| `--faults` | `fault` and the registers | 0.3 us a fault (the fault itself: 0.9) | 40 |
+| `--switches` | `sched` | nothing measurable | 10 |
+| `--syscalls` | `syscall_enter` with the path or bytes, `syscall_exit` | 0.4 us a syscall (ptrace: 10), and a second at the end | 23 |
+| `--watch SYMBOL` | `mem_write` or `mem_read`, and the pc | 0.9 us a hit | 17 |
+| `--break SYMBOL` | `probe`, five arguments, the registers | 1.3 us a hit | 73 |
+| always | `map`, `thread_start`, `thread_exit`, `mark` (comm), `exit` | | |
+
+(Release build, an i7-11700; a ptrace stop is 5 us. It decodes and records
+one to four million events a second; what the kernel could not put in its
+ring is counted as lost: `--ring`.) `--threads` follows threads and
+children, a ring per CPU merged by time. Moments end where the recorder
+ends them anyway, a syscall's exit or a megabyte of events, unless `--cut`
+asks for one at every fault and hit. What to know:
+
+- Only user space is seen. A page the kernel touches first (`read()` into
+ fresh memory) faults unseen; context switches and migrations cannot be
+ counted, only reported as events.
+- A huge page is one fault for 2 MiB. An anonymous mapping the kernel
+ merges with its neighbour is reported as the merged whole.
+- Syscalls come from the 736 per-syscall tracepoints, the only ones a user
+ may read: found by trying every id, closed at a millisecond each.
+- There are four debug registers; a watchpoint covers 1, 2, 4 or 8 aligned
+ bytes; the record comes after the access, so the value is read when it
+ is decoded, later (or not at all, once the program is gone).
+
+**`ztrace probe`** is for root (CAP_BPF and CAP_PERFMON) and says so
+otherwise; `--dry-run` builds everything and lists it. BPF programs, built
+here as instruction arrays for one process, on the raw tracepoints
+`sys_enter`, `sys_exit` and `sched_switch` (both threads of a switch,
+through the kernel's BTF), on kprobes, on uprobes, and on USDT probes,
+whose arguments are read in the kernel at the probe. They write `Event`s
+into one BPF ring buffer and count what did not fit. A syscall costs 0.15
+us, a probe 0.5 to 0.8 (in a VM), 22 to 73 bytes an event.
+
+**USDT**, the static probes of DTrace: `usdt.probes(gpa, elf, bias)` reads
+the notes `<sys/sdt.h>` leaves (provider, name, pc, semaphore, arguments)
+and `usdt.Arg.parse(spec).fetch(regs, memory)` gets an argument at a
+stopped thread. No BPF in it: a ptrace breakpoint on the nop does as well.
+
+`zig build test-kernel` runs the first tier and USDT on `targets/kernel_*`,
+and the BPF programs in a small BPF machine. `zig build test-kernel-vm`
+runs them for real: this machine's kernel in QEMU, where we are root.
+
## Depends on
- [sketchbook](../sketchbook): window, drawing, shaders, hot reload, the
diff --git a/build/kernel_vm.sh b/build/kernel_vm.sh
index ac7c576..55ad73c 100644
--- a/build/kernel_vm.sh
+++ b/build/kernel_vm.sh
@@ -14,6 +14,6 @@ cp "$@" "$stage/"
cp /lib64/ld-linux-x86-64.so.2 "$stage/lib64/"
cp /usr/lib/libc.so.6 "$stage/usr/lib/"
(cd "$stage" && find . | cpio -o -H newc --quiet) >"$stage.cpio"
-timeout 120 qemu-system-x86_64 -enable-kvm -cpu host -m 512 -display none -serial stdio -no-reboot \
+timeout 120 qemu-system-x86_64 -enable-kvm -cpu host -smp 2 -m 1024 -display none -serial stdio -no-reboot \
-kernel "/usr/lib/modules/$(uname -r)/vmlinuz" -initrd "$stage.cpio" \
-append "console=ttyS0 quiet panic=-1"
diff --git a/src/cli/probe.zig b/src/cli/probe.zig
index f0e2d12..539af5c 100644
--- a/src/cli/probe.zig
+++ b/src/cli/probe.zig
@@ -16,7 +16,7 @@ pub const usage =
\\kernel, into a recording (default out.ztrace). Needs CAP_BPF and
\\CAP_PERFMON, which root has.
\\
- \\ --syscalls every syscall, with the registers at its entry
+ \\ --syscalls every syscall
\\ --sched every switch of a CPU to or from one of its threads
\\ --kprobe FUNCTION
\\ every call of a kernel function it makes: five arguments
@@ -95,7 +95,7 @@ pub fn run(init: std.process.Init, args: []const [:0]const u8) !void {
const maps: bpf.Maps = .{ .ring = 0, .drops = 0 };
std.debug.print("for the process started from {s}:\n", .{path});
if (syscalls) {
- list("raw tracepoint sys_enter: a syscall_enter and the registers", bpf.sysEnter(maps, 0));
+ list("raw tracepoint sys_enter: a syscall_enter", bpf.sysEnter(maps, 0));
list("raw tracepoint sys_exit: a syscall_exit", bpf.sysExit(maps, 0));
}
if (sched) {
@@ -107,7 +107,7 @@ pub fn run(init: std.process.Init, args: []const [:0]const u8) !void {
if (p.usdt) |u| std.debug.print(", semaphore at +{x}, arguments {s}", .{ if (u.semaphore == 0) 0 else p.elf.?.offset(u.semaphore) orelse 0, u.args });
std.debug.print("\n", .{});
const id = zt.perf.stringId(p.name);
- list("its program: a probe and the registers", if (p.usdt) |u| bpf.usdtProgram(maps, 0, id, u.args) catch fail("{s}: an argument of this probe ({s}) is in a form not understood yet\n", .{ p.name, u.args }) else bpf.probe(maps, 0, id, null));
+ list("its program: a probe", if (p.usdt) |u| bpf.usdtProgram(maps, 0, id, u.args) catch fail("{s}: an argument of this probe ({s}) is in a form not understood yet\n", .{ p.name, u.args }) else bpf.probe(maps, 0, id, null, p.kind != .kprobe));
}
std.debug.print("{s}\n", .{if (missing) |m| m else "nothing is missing to attach them"});
return;
@@ -172,6 +172,7 @@ fn refused(err: anyerror, tracer: ?*bpf.Tracer) noreturn {
const log = if (tracer) |t| std.mem.sliceTo(t.log, 0) else "";
switch (err) {
error.PermissionDenied => fail("ztrace probe: bpf() refused though the capabilities are there: inside a user namespace or a container they do not count, the kernel wants them in the initial namespace\n", .{}),
+ error.SystemResources => fail("ztrace probe: the kernel has no memory to spare for a ring that large (--ring)\n", .{}),
error.UnsafeProgram, error.InvalidProgram => fail("ztrace probe: the kernel's verifier refused a program ({t}):\n{s}\n", .{ err, log }),
else => fail("ztrace probe: {t}\n{s}", .{ err, log }),
}
diff --git a/src/trace/bpf.zig b/src/trace/bpf.zig
index 4069b01..5dad4c6 100644
--- a/src/trace/bpf.zig
+++ b/src/trace/bpf.zig
@@ -1,7 +1,7 @@
//! The kernel's view with privilege: BPF programs on the raw tracepoints
//! sys_enter, sys_exit and sched_switch, and on any kprobe, uprobe or USDT
//! probe. Needs CAP_BPF and CAP_PERFMON (root). Each program writes an
-//! `Event`, and for a syscall's entry and a probe the registers after it,
+//! `Event`, and for a probe in user space the thread's registers after it,
//! into one BPF ring buffer; `Tracer.poll` moves them into a `Sink`.
//!
//! The programs are instruction arrays built here, for one process (its id
@@ -156,20 +156,21 @@ pub const Program = struct {
pub const Maps = struct { ring: linux.fd_t, drops: linux.fd_t };
/// raw tracepoint sys_enter(struct pt_regs *regs, long id): a
-/// `syscall_enter` and the registers.
+/// `syscall_enter`.
pub fn sysEnter(maps: Maps, tgid: u32) Program {
var p: Program = .{};
+ // The registers are read to below the event, for the six that are arguments.
p.enter(tgid);
p.add(Insn.ldx(.double_word, .r3, .r6, 0));
- p.read(large_at + @sizeOf(Event), pt_regs_bytes);
- p.stamp(large_at, .syscall_enter);
+ p.read(large_at, pt_regs_bytes);
+ p.stamp(small_at, .syscall_enter);
p.add(Insn.ldx(.double_word, .r1, .r6, 8));
- p.add(Insn.stx(.half_word, .r10, large_at + field("aux"), .r1));
+ p.add(Insn.stx(.half_word, .r10, small_at + field("aux"), .r1));
inline for (.{ "rdi", "rsi", "rdx", "r10", "r8", "r9" }, 0..) |name, i| {
- p.add(Insn.ldx(.double_word, .r1, .r10, large_at + @sizeOf(Event) + reg(name)));
- p.add(Insn.stx(.double_word, .r10, large_at + arg(i), .r1));
+ p.add(Insn.ldx(.double_word, .r1, .r10, large_at + reg(name)));
+ p.add(Insn.stx(.double_word, .r10, small_at + arg(i), .r1));
}
- p.send(maps, large_at, @sizeOf(Event) + pt_regs_bytes);
+ p.send(maps, small_at, @sizeOf(Event));
return p;
}
@@ -224,30 +225,32 @@ pub fn schedSwitch(maps: Maps, tgid: u32, pid_at: u32, tgid_at: u32) Program {
}
/// A kprobe or uprobe (the context is the registers there): a `probe`
-/// named `id`, and the registers. Its a1..a5 are the first five arguments
-/// of a function call, or with `args` those of a USDT probe, read there
-/// and then.
-pub fn probe(maps: Maps, tgid: u32, id: u64, args: ?[]const usdt.Arg) Program {
+/// named `id`. Its a1..a5 are the first five arguments of a function call,
+/// or with `args` those of a USDT probe, read there and then. In `user`
+/// space the registers follow the event: they are the thread's, which a
+/// kernel function's are not.
+pub fn probe(maps: Maps, tgid: u32, id: u64, args: ?[]const usdt.Arg, user: bool) Program {
var p: Program = .{};
+ const at: i16 = if (user) large_at else small_at;
p.enter(tgid);
- p.stamp(large_at, .probe);
- p.add(Insn.st(.half_word, .r10, large_at + field("aux"), 0));
+ p.stamp(at, .probe);
+ p.add(Insn.st(.half_word, .r10, at + field("aux"), 0));
p.add(Insn.ld_dw1(.r1, id));
p.add(Insn.ld_dw2(id));
- p.add(Insn.stx(.double_word, .r10, large_at + arg(0), .r1));
+ p.add(Insn.stx(.double_word, .r10, at + arg(0), .r1));
inline for (.{ "rdi", "rsi", "rdx", "rcx", "r8" }, 1..) |name, i| {
if (args == null) {
p.add(Insn.ldx(.double_word, .r1, .r6, reg(name)));
- p.add(Insn.stx(.double_word, .r10, large_at + arg(i), .r1));
+ p.add(Insn.stx(.double_word, .r10, at + arg(i), .r1));
} else if (i <= args.?.len) {
- p.usdtArg(args.?[i - 1], large_at + arg(i));
- } else p.add(Insn.st(.double_word, .r10, large_at + arg(i), 0));
+ p.usdtArg(args.?[i - 1], at + arg(i));
+ } else p.add(Insn.st(.double_word, .r10, at + arg(i), 0));
}
- for (0..pt_regs_bytes / 8) |i| {
+ if (user) for (0..pt_regs_bytes / 8) |i| {
p.add(Insn.ldx(.double_word, .r1, .r6, @intCast(8 * i)));
- p.add(Insn.stx(.double_word, .r10, large_at + @sizeOf(Event) + @as(i16, @intCast(8 * i)), .r1));
- }
- p.send(maps, large_at, @sizeOf(Event) + pt_regs_bytes);
+ p.add(Insn.stx(.double_word, .r10, at + @sizeOf(Event) + @as(i16, @intCast(8 * i)), .r1));
+ };
+ p.send(maps, at, if (user) @sizeOf(Event) + pt_regs_bytes else @sizeOf(Event));
return p;
}
@@ -262,7 +265,7 @@ pub fn usdtProgram(maps: Maps, tgid: u32, id: u64, specs: []const u8) !Program {
args[count] = try .parse(spec);
count += 1;
}
- return probe(maps, tgid, id, args[0..count]);
+ return probe(maps, tgid, id, args[0..count], true);
}
/// Where `member` is in the struct `name`, in bytes, from the kernel's
@@ -469,13 +472,13 @@ pub const Tracer = struct {
/// Every call of a kernel function by the process: a `probe` named
/// `function` (define the string yourself: its id is `id`).
pub fn kprobe(t: *Tracer, function: [*:0]const u8, id: u64) !void {
- try t.attach("kprobe", function, 0, 0, probe(t.maps, @intCast(t.pid), id, null));
+ try t.attach("kprobe", function, 0, 0, probe(t.maps, @intCast(t.pid), id, null, false));
}
/// Every time the process runs the instruction at `offset` of the
/// file `path`.
pub fn uprobe(t: *Tracer, path: [*:0]const u8, offset: u64, id: u64) !void {
- try t.attach("uprobe", path, offset, 0, probe(t.maps, @intCast(t.pid), id, null));
+ try t.attach("uprobe", path, offset, 0, probe(t.maps, @intCast(t.pid), id, null, true));
}
/// A static probe of the file `path` (`p` from `usdt.probes` with no
@@ -611,9 +614,8 @@ test "the syscall programs: the right process only, the event the tracer expects
const enter_context = [2]u64{ @intFromPtr(&regs), 257 };
var m: Machine = .{ .pid_tgid = 1000 << 32 | 1001, .now = 77 };
try m.run(sysEnter(test_maps, 1000).code(), &enter_context);
- try std.testing.expectEqual(@as(?usize, @sizeOf(Event) + pt_regs_bytes), m.sent_len);
+ try std.testing.expectEqual(@as(?usize, @sizeOf(Event)), m.sent_len);
try std.testing.expectEqual(Event{ .ts = 77, .tid = 1001, .kind = .syscall_enter, .aux = 257, .a = .{ 1, 2, 3, 4, 5, 6 } }, m.sentEvent());
- try std.testing.expectEqualSlices(u8, std.mem.asBytes(&regs)[0..pt_regs_bytes], m.sent[@sizeOf(Event)..][0..pt_regs_bytes]);
const exit_context = [2]u64{ @intFromPtr(&regs), @bitCast(@as(i64, -2)) };
try m.run(sysExit(test_maps, 1000).code(), &exit_context);
@@ -656,7 +658,12 @@ test "the probe program and its record decoded; a USDT probe's arguments as usdt
for (&memory, 0..) |*b, i| b.* = @truncate(0xf0 + i);
const regs: Regs = .{ .rdi = 11, .rsi = 0xffff_fffe, .rdx = @intFromPtr(&memory), .rcx = 3, .r8 = 15, .rbp = @intFromPtr(&memory) + 32, .rip = 0x401234, .rsp = 0x7000, .r10 = 0x1_0000_00ff };
var m: Machine = .{ .pid_tgid = 1000 << 32 | 1000, .now = 5 };
- try m.run(probe(test_maps, 1000, 0xfeed, null).code(), &regs);
+ // In the kernel: the event alone. In user space: the registers too.
+ try m.run(probe(test_maps, 1000, 0xfeed, null, false).code(), &regs);
+ try std.testing.expectEqual(@as(?usize, @sizeOf(Event)), m.sent_len);
+ try std.testing.expectEqual(Event{ .ts = 5, .tid = 1000, .kind = .probe, .a = .{ 0xfeed, 11, regs.rsi, regs.rdx, 3, 15 } }, m.sentEvent());
+ try m.run(probe(test_maps, 1000, 0xfeed, null, true).code(), &regs);
+ try std.testing.expectEqual(@as(?usize, @sizeOf(Event) + pt_regs_bytes), m.sent_len);
try std.testing.expectEqual(Event{ .ts = 5, .tid = 1000, .kind = .probe, .a = .{ 0xfeed, 11, regs.rsi, regs.rdx, 3, 15 } }, m.sentEvent());
// A sink that keeps the last event.
@@ -688,11 +695,11 @@ test "the probe program and its record decoded; a USDT probe's arguments as usdt
for (specs) |five| {
var args: [5]usdt.Arg = undefined;
for (&args, five) |*a, spec| a.* = try .parse(spec);
- try m.run(probe(test_maps, 1000, 0xfeed, &args).code(), &regs);
+ try m.run(probe(test_maps, 1000, 0xfeed, &args, true).code(), &regs);
for (args, m.sentEvent().a[1..]) |a, got| try std.testing.expectEqual(a.fetch(&regs, here).?, got);
}
// Fewer than five: the rest is 0.
- try m.run(probe(test_maps, 1000, 0xfeed, &.{try .parse("4@%edi")}).code(), &regs);
+ try m.run(probe(test_maps, 1000, 0xfeed, &.{try .parse("4@%edi")}, true).code(), &regs);
try std.testing.expectEqual([6]u64{ 0xfeed, 11, 0, 0, 0, 0 }, m.sentEvent().a);
}
diff --git a/src/trace/kernel_test.zig b/src/trace/kernel_test.zig
index 6098c58..1905771 100644
--- a/src/trace/kernel_test.zig
+++ b/src/trace/kernel_test.zig
@@ -166,8 +166,9 @@ test "debug registers: a watchpoint sees every write of a global, a breakpoint e
try expectEqual(@as(u64, 8), item.ev.a[1]);
// The pc is the instruction after the store, a few bytes into step.
try expect(item.ev.a[2] > step_pc and item.ev.a[2] < step_pc + 32);
- // The value is read when the record is: what was written, or something later.
- if (item.payload.len == 8) try expect(std.mem.readInt(u64, item.payload[0..8], .little) >= sum);
+ // The value is read when the record is decoded: one the global
+ // had then or since, or nothing once the program is gone.
+ try expect(item.payload.len == 8 or item.payload.len == 0);
writes += 1;
},
else => {},
diff --git a/src/trace/perf.zig b/src/trace/perf.zig
index c251741..36eaaf8 100644
--- a/src/trace/perf.zig
+++ b/src/trace/perf.zig
@@ -281,17 +281,19 @@ pub const Session = struct {
}
// shortcut: ids below 4096; scan further if a kernel has more trace events than that.
for (0..4096) |id| {
- var attr: linux.perf_event_attr = .{ .type = .TRACEPOINT, .config = id, .sample_period_or_freq = 1, .sample_type = PERF.SAMPLE.RAW };
- // Only a syscall's exit has a field `ret`: a filter on it is
- // accepted there and nowhere else. On an event of its own, since
- // a filter cannot be taken off again.
- const probe = perfOpen(&attr, s.pid, -1) catch |err| switch (err) {
+ s.add(.{ .type = .TRACEPOINT, .config = id, .sample_period_or_freq = 1, .sample_type = PERF.SAMPLE.RAW }, .syscall_enter) catch |err| switch (err) {
error.PerfAccess, error.PerfNoSuchEvent => continue,
else => |e| return e,
};
- const is_exit = linux.errno(linux.ioctl(probe, PERF.EVENT_IOC.SET_FILTER, @intFromPtr("ret==0"))) == .SUCCESS;
- _ = linux.close(probe);
- try s.add(attr, if (is_exit) .syscall_exit else .syscall_enter);
+ // Entry or exit? Only an exit has a field `ret`: a filter on it
+ // is accepted there and nowhere else. It cannot be taken off
+ // again, so it is one that every exit passes.
+ for (s.fds.items[s.fds.items.len - s.rings.len ..]) |fd| {
+ if (linux.errno(linux.ioctl(fd, PERF.EVENT_IOC.SET_FILTER, @intFromPtr("ret >= 0 || ret < 0"))) != .SUCCESS) break;
+ var event_id: u64 = 0;
+ _ = linux.ioctl(fd, PERF.EVENT_IOC.ID, @intFromPtr(&event_id));
+ try s.sources.put(s.gpa, event_id, .syscall_exit);
+ }
}
}