//! ztrace run: a program that carries a ring producer (the preloaded agent, //! or instrumentation linked in), recorded at full speed, no ptrace. The //! agent's capabilities are chosen here and reach it through ZTRACE_* //! variables; stops are the ring's (`stop_mask`), not the kernel's. const std = @import("std"); const linux = std.os.linux; const zt = @import("ztrace"); const agent = @import("ztrace-agent"); const util = @import("util.zig"); const fail = util.fail; pub const usage = \\usage: ztrace run [-o FILE] [--preload LIB] [--ring BYTES] [OPTIONS] -- PROGRAM [ARGS] \\ \\Runs PROGRAM with a shared-memory ring in its environment and records \\what it emits (default out.ztrace). --preload puts a library (the agent, \\libztrace-agent.so) into it with LD_PRELOAD. --ring sizes the ring (a \\power of two, default 16M). --max-size stops the run when the recording \\reaches that size (default 1G). Sizes take K, M or G. \\ \\What the agent records, preloaded or linked into PROGRAM: \\ --alloc malloc, free and their family: alloc, free \\ --syscalls every syscall, with paths and written bytes: \\ syscall_enter, syscall_exit \\ --capture BYTES how much of a path or a written buffer to keep \\ (default 256, at most 2048) \\ --hook SYM|ADDR a function's entry (with registers) and return \\ (with its value): call, ret \\ --watch SYM|ADDR:LEN memory: the bytes that changed in it, before each \\ event that ends a moment \\--hook and --watch repeat, or take a comma-separated list. \\ \\ --cut KIND,... the kinds that end a moment (default: the \\ recorder's, and call and ret) \\ \\Stops, with the target otherwise at full speed: \\ --stop-at KIND,... hold the target at each event of these kinds \\ until the tracer is done with it \\ --read SYM|ADDR:LEN at each stop read this memory from outside and \\ record what changed (repeats) \\ -i at each stop ask what next: s (step to the next \\ stop), c (continue to the end), x ADDR [LEN], q \\ ; pub fn run(init: std.process.Init, args: []const [:0]const u8) !void { const arena = init.arena.allocator(); var out: []const u8 = "out.ztrace"; var options: zt.host.Options = .{}; var env: std.ArrayList(?[*:0]const u8) = .empty; var hooks: []const u8 = ""; var watches: []const u8 = ""; var cut: ?u64 = null; var max_bytes: ?u64 = null; var stops: Stops = .{ .io = init.io, .arena = arena }; var i: usize = 0; while (i < args.len) : (i += 1) { const arg = args[i]; const value: [:0]const u8 = if (i + 1 < args.len) args[i + 1] else ""; if (std.mem.eql(u8, arg, "--")) { i += 1; break; } else if (std.mem.eql(u8, arg, "--alloc")) { try env.append(arena, "ZTRACE_ALLOC=1"); continue; } else if (std.mem.eql(u8, arg, "--syscalls")) { try env.append(arena, "ZTRACE_SYSCALLS=1"); continue; } else if (std.mem.eql(u8, arg, "-i")) { stops.interactive = true; continue; } else if (i + 1 == args.len) { fail(usage, .{}); } else if (std.mem.eql(u8, arg, "-o")) { out = value; } else if (std.mem.eql(u8, arg, "--preload")) { options.preload = value; } else if (std.mem.eql(u8, arg, "--ring")) { options.ring_bytes = sized(value); if (!std.math.isPowerOfTwo(options.ring_bytes) or options.ring_bytes < 4096) fail("--ring needs a power of two, 4096 or more\n", .{}); } else if (std.mem.eql(u8, arg, "--max-size")) { max_bytes = sized(value); } else if (std.mem.eql(u8, arg, "--capture")) { try env.append(arena, try std.fmt.allocPrintSentinel(arena, "ZTRACE_CAPTURE={d}", .{sized(value)}, 0)); } else if (std.mem.eql(u8, arg, "--hook")) { hooks = try std.mem.concat(arena, u8, &.{ hooks, ",", value }); } else if (std.mem.eql(u8, arg, "--watch")) { watches = try std.mem.concat(arena, u8, &.{ watches, ",", value }); } else if (std.mem.eql(u8, arg, "--read")) { try stops.reads.append(arena, .{ .spec = value }); } else if (std.mem.eql(u8, arg, "--cut")) { cut = kinds(value); } else if (std.mem.eql(u8, arg, "--stop-at")) { stops.mask = kinds(value); } else fail(usage, .{}); i += 1; } if (i >= args.len) fail(usage, .{}); var rec = try zt.Recorder.create(init.gpa, init.io, out); // A hooked call and its return are the steps of a run recorded from inside. rec.cut = cut orelse rec.cut | zt.Kind.call.bit() | zt.Kind.ret.bit(); rec.max_bytes = max_bytes orelse rec.max_bytes; stops.rec = &rec; if (hooks.len > 0) try env.append(arena, try std.fmt.allocPrintSentinel(arena, "ZTRACE_HOOKS={s}", .{hooks}, 0)); if (watches.len > 0) try env.append(arena, try std.fmt.allocPrintSentinel(arena, "ZTRACE_WATCH={s}", .{watches}, 0)); try env.append(arena, try std.fmt.allocPrintSentinel(arena, "ZTRACE_CUT=0x{x}", .{rec.cut}, 0)); for (init.minimal.environ.block.slice) |v| { if (!std.mem.startsWith(u8, std.mem.span(v.?), "ZTRACE_")) try env.append(arena, v); } const path = try util.resolve(init, args[i]); const argv = try util.targetArgv(arena, args[i..]); var session = try zt.host.Session.spawn(arena, path, argv, try env.toOwnedSliceSentinel(arena, null), options); defer session.close(); // Set before the target has had time to load, let alone emit. session.ring.hdr.stop_mask.store(stops.mask, .release); stops.session = &session; const start = zt.event.now(); var full = false; // An idle wait is how late the target's exit is noticed: a millisecond. while (session.pump(stops.sink(), std.time.ns_per_ms) catch |err| switch (err) { error.RecordingFull => full: { full = true; break :full false; }, else => |e| return e, }) { // Everything pumped is recorded and read: whoever waits at it may go on. if (stops.held) session.ring.resumeAll(); stops.held = false; // Look again for a while before sleeping: a target that finds the // tracer asleep pays a futex wake for the event, more than the event. var spins: usize = 0; while (session.ring.peek() == null and spins < 2000) : (spins += 1) std.atomic.spinLoopHint(); } const ns = zt.event.now() - start; if (full) { // Nobody empties the ring any more: the target would wait at it for ever. _ = linux.kill(session.pid, .KILL); var status: u32 = 0; _ = linux.waitpid(session.pid, @ptrCast(&status), 0); session.exit_code = 128 + @as(u8, @intFromEnum(linux.SIG.KILL)); std.debug.print("{s}: full at {d} bytes, the target was killed. Record less (fewer kinds in --cut, less --watch, a smaller --capture) or raise --max-size.\n", .{ out, rec.max_bytes }); } const events = rec.count; const moments = rec.moments + @intFromBool(rec.delta.items.len > 0); const dropped = session.ring.hdr.dropped.load(.monotonic); try rec.close(); const size = (try std.Io.Dir.cwd().statFile(init.io, out, .{})).size; std.debug.print("{s}: {d} moments, {d} events ({d} dropped), {d} bytes, {d:.1} ms, {d:.0} events/s, exit {d}\n", .{ out, moments, events, dropped, size, @as(f64, @floatFromInt(ns)) / 1e6, @as(f64, @floatFromInt(events)) / (@as(f64, @floatFromInt(ns)) / 1e9), session.exit_code.?, }); if (full) std.process.exit(1); } /// "4096", "64K", "16M", "1G". fn sized(text: []const u8) u64 { const shift: u6 = switch (if (text.len > 0) text[text.len - 1] else 0) { 'K' => 10, 'M' => 20, 'G' => 30, else => 0, }; const number = std.fmt.parseInt(u64, text[0 .. text.len - @intFromBool(shift != 0)], 0) catch fail("{s}: not a size\n", .{text}); return number << shift; } /// "call,ret" as a set of `Kind.bit`s. fn kinds(list: []const u8) u64 { var set: u64 = 0; var names = std.mem.tokenizeScalar(u8, list, ','); while (names.next()) |name| { const kind = std.meta.stringToEnum(zt.Kind, name) orelse fail("{s}: not an event kind\n", .{name}); set |= kind.bit(); } return set; } /// Between the ring and the recorder: at an event of a kind in `mask` the /// thread that emitted it waits inside the target, so the tracer can take its /// time: read memory from outside, ask the user. const Stops = struct { io: std.Io, arena: std.mem.Allocator, rec: *zt.Recorder = undefined, session: *zt.host.Session = undefined, mask: u64 = 0, reads: std.ArrayList(Read) = .empty, interactive: bool = false, /// Some thread waits at an event already pumped. held: bool = false, stdin: ?std.Io.File.Reader = null, stdin_buf: [256]u8 = undefined, /// Memory read from outside at each stop: `old` is what the recording has. const Read = struct { spec: []const u8, addr: u64 = 0, old: []u8 = &.{}, new: []u8 = &.{} }; fn sink(s: *Stops) zt.Sink { return .{ .ctx = s, .emitFn = emit }; } fn emit(ctx: *anyopaque, ev: *const zt.Event, payload: []const u8) anyerror!void { const s: *Stops = @ptrCast(@alignCast(ctx)); if (s.mask & ev.kind.bit() == 0) return s.rec.emit(ev.*, payload); s.held = true; for (s.reads.items) |*r| try s.read(r, ev); try s.rec.emit(ev.*, payload); if (s.interactive) try s.ask(ev, payload); } /// The memory first (it belongs to the moment the event ends), and only what changed. fn read(s: *Stops, r: *Read, ev: *const zt.Event) !void { if (r.old.len == 0) { // The first stop: by now the target's libraries are mapped, and a name means something. const found = agent.symbols.find(s.session.pid, r.spec) orelse fail("{s}: nothing called that in the target\n", .{r.spec}); if (found.size == 0) fail("{s}: how many bytes? (ADDR:LEN)\n", .{r.spec}); r.addr = found.addr; r.old = try s.arena.alloc(u8, found.size); r.new = try s.arena.alloc(u8, found.size); const id = agent.stringId(r.spec); try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .string, .a = .{ id, 0, 0, 0, 0, 0 } }, r.spec); try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .variable, .a = .{ r.addr, found.size, id, 0, 0, 0 } }, ""); try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .mem_write, .a = .{ r.addr, found.size, 0, 0, 0, 0 } }, r.old[0..s.peek(r.addr, r.old)]); return; } var changes: agent.regions.Changes = .{ .old = r.old, .new = r.new[0..s.peek(r.addr, r.new)] }; while (changes.next()) |change| try s.rec.emit(.{ .ts = ev.ts, .tid = ev.tid, .kind = .mem_write, .a = .{ r.addr + change.at, change.bytes.len, 0, 0, 0, 0 } }, change.bytes); } /// The target's memory: it is our child, so no ptrace is needed to read it. fn peek(s: *Stops, addr: u64, buf: []u8) usize { const local = [1]std.posix.iovec{.{ .base = buf.ptr, .len = buf.len }}; const remote = [1]std.posix.iovec_const{.{ .base = @ptrFromInt(addr), .len = buf.len }}; const rc = linux.process_vm_readv(s.session.pid, &local, &remote, 0); return if (linux.errno(rc) == .SUCCESS) rc else 0; } fn ask(s: *Stops, ev: *const zt.Event, payload: []const u8) !void { var out_buf: [4096]u8 = undefined; var stdout = std.Io.File.stdout().writer(s.io, &out_buf); // One reader for the whole run: it holds the lines read ahead. if (s.stdin == null) s.stdin = std.Io.File.stdin().reader(s.io, &s.stdin_buf); const w = &stdout.interface; try w.print("{t} tid={d} aux={d} a={x} {x} {x} {x} {x} {x} +{d}\n", .{ ev.kind, ev.tid, ev.aux, ev.a[0], ev.a[1], ev.a[2], ev.a[3], ev.a[4], ev.a[5], payload.len }); while (true) { try w.writeAll("> "); try w.flush(); // The end of input ends the asking, not the run. const line = try s.stdin.?.interface.takeDelimiter('\n') orelse "c"; var words = std.mem.tokenizeAny(u8, line, " \t\r"); const command = words.next() orelse "s"; if (std.mem.eql(u8, command, "s")) { return; } else if (std.mem.eql(u8, command, "c")) { s.mask = 0; s.session.ring.hdr.stop_mask.store(0, .release); return; } else if (std.mem.eql(u8, command, "q")) { try s.rec.close(); s.session.close(); std.process.exit(0); } else if (std.mem.eql(u8, command, "x")) { var bytes: [256]u8 = undefined; const addr = std.fmt.parseInt(u64, words.next() orelse "", 0) catch 0; const len = @min(bytes.len, std.fmt.parseInt(usize, words.next() orelse "64", 0) catch 64); const got = bytes[0..s.peek(addr, bytes[0..len])]; var at: usize = 0; while (at < got.len) : (at += 16) try w.print("{x:0>12} {x}\n", .{ addr + at, got[at..@min(got.len, at + 16)] }); if (got.len < len) try w.print("{x:0>12} not readable\n", .{addr + got.len}); } else try w.writeAll("s: step to the next stop c: continue to the end x ADDR [LEN]: memory q: quit\n"); } } };