//! ztrace perf: a program at full speed, the kernel taking notes (perf //! events). No privilege needed, no ptrace once it runs. const std = @import("std"); const linux = std.os.linux; const zt = @import("ztrace"); const util = @import("util.zig"); const fail = util.fail; const Kind = zt.Kind; pub const usage = \\usage: ztrace perf [-o FILE] [OPTIONS] -- PROGRAM [ARGS] \\ \\Runs PROGRAM at full speed while the kernel records it through perf \\events, as any user may on their own processes, into a recording \\(default out.ztrace). Always recorded: its memory maps, the threads it \\starts and ends, its exit. \\ \\ -e NAME,... counters, read when it ends (default instructions,cycles): \\ instructions cycles branches branch-misses \\ cache-references cache-misses page-faults task-clock \\ --interval MS ... and every MS milliseconds \\ --sample HZ a profile: where it is, HZ times a second \\ --callchain ... and who called that (needs frame pointers) \\ --faults every page fault: address, pc, registers \\ --switches every time it leaves or gets a CPU \\ --syscalls every syscall: arguments, result, the path it names \\ --watch WHAT[:LEN][:rw] \\ a debug register on a symbol or an address: every \\ write to its LEN bytes (1, 2, 4, 8; default the symbol's \\ size) with the value found there; with :rw every access \\ --break WHAT ... on code: every time it runs, with the registers \\ --threads also the threads and children it creates \\ --cut end a moment at every fault and every hit of --watch and \\ --break: the state at each can be gone back to, for more bytes \\ --max-size BYTES stop when the recording is this large (default 1 GiB) \\ --ring BYTES the kernel's buffer, per CPU (a power of two, default 512 KiB) \\ \\There are four debug registers. Only user space is seen: a page the \\kernel touches first (a read() into fresh memory) faults unseen. \\Moments end where the recorder ends them anyway (a syscall's exit, a \\megabyte of events), so that a profile or a storm of faults stays small. \\ \\--preload LIB puts the agent into PROGRAM and --alloc has it record \\allocations: what the program says of itself and what the kernel sees \\of it are then one recording, in the order they happened (a malloc, \\the brk it makes, the page faults of its first touch). \\ ; const Spec = struct { what: []const u8, len: ?u8 = null, mode: zt.perf.Watch.Mode }; 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.perf.Options = .{ .counters = &.{ .instructions, .cycles } }; var interval_ms: u32 = 0; var cut = false; var max_bytes: ?u64 = null; var specs: std.ArrayList(Spec) = .empty; var producer: util.Producer = .{}; var i: usize = 0; while (i < args.len) : (i += 1) { const arg = args[i]; const value: ?[]const u8 = if (i + 1 < args.len) args[i + 1] else null; if (std.mem.eql(u8, arg, "--")) { i += 1; break; } else if (!std.mem.eql(u8, arg, "--ring") and producer.take(args, &i)) { // --ring is the kernel's here; the target's comes with --preload. } else if (std.mem.eql(u8, arg, "--callchain")) { options.callchain = true; } else if (std.mem.eql(u8, arg, "--faults")) { options.faults = true; } else if (std.mem.eql(u8, arg, "--switches")) { options.switches = true; } else if (std.mem.eql(u8, arg, "--syscalls")) { options.syscalls = true; } else if (std.mem.eql(u8, arg, "--threads")) { options.follow = true; } else if (std.mem.eql(u8, arg, "--cut")) { cut = true; } else if (value == null) { fail(usage, .{}); } else if (std.mem.eql(u8, arg, "-o")) { out = value.?; i += 1; } else if (std.mem.eql(u8, arg, "-e")) { var counters: std.ArrayList(zt.perf.Counter) = .empty; var names = std.mem.tokenizeScalar(u8, value.?, ','); while (names.next()) |name| try counters.append(arena, std.meta.stringToEnum(zt.perf.Counter, name) orelse fail("-e {s}: no such counter\n", .{name})); options.counters = counters.items; i += 1; } else if (std.mem.eql(u8, arg, "--interval")) { interval_ms = std.fmt.parseInt(u32, value.?, 0) catch fail("--interval needs milliseconds\n", .{}); i += 1; } else if (std.mem.eql(u8, arg, "--sample")) { options.sample_hz = std.fmt.parseInt(u32, value.?, 0) catch fail("--sample needs a rate\n", .{}); i += 1; } else if (std.mem.eql(u8, arg, "--max-size")) { max_bytes = std.fmt.parseInt(u64, value.?, 0) catch fail("--max-size needs bytes\n", .{}); i += 1; } else if (std.mem.eql(u8, arg, "--ring")) { options.ring_bytes = std.fmt.parseInt(usize, value.?, 0) catch 0; if (!std.math.isPowerOfTwo(options.ring_bytes) or options.ring_bytes < 4096) fail("--ring needs a power of two, 4096 or more\n", .{}); i += 1; } else if (std.mem.eql(u8, arg, "--break")) { try specs.append(arena, .{ .what = value.?, .mode = .exec }); i += 1; } else if (std.mem.eql(u8, arg, "--watch")) { var spec: Spec = .{ .what = value.?, .mode = .write }; var parts = std.mem.splitScalar(u8, value.?, ':'); spec.what = parts.first(); while (parts.next()) |part| { if (std.mem.eql(u8, part, "rw")) spec.mode = .access else spec.len = std.fmt.parseInt(u8, part, 0) catch fail("--watch {s}: {s} is neither a length nor rw\n", .{ value.?, part }); } try specs.append(arena, spec); i += 1; } else fail(usage, .{}); } if (i >= args.len) fail(usage, .{}); const path = try util.resolve(init, args[i]); const argv = try util.targetArgv(arena, args[i..]); // Held at its first instruction until the events are on it. const produced = try producer.start(arena, init.minimal.environ.block.slice); var proc = try zt.ptrace.Process.spawn(path, argv, if (produced) |p| p.envp.ptr else init.minimal.environ.block.slice.ptr); errdefer proc.close(); var rec = try zt.Recorder.create(init.gpa, init.io, out); if (max_bytes) |bytes| rec.max_bytes = bytes; // With the target's own ring there are two sources: merged by time. var sorted: zt.perf.Sorted = .{ .gpa = init.gpa, .to = rec.sink() }; defer sorted.deinit(); const sink = if (produced != null) sorted.sink() else rec.sink(); // What changes the state a moment holds (registers, memory) ends one. if (cut) rec.cut |= Kind.fault.bit() | Kind.probe.bit() | Kind.mem_write.bit() | Kind.mem_read.bit(); var session = zt.perf.Session.open(init.gpa, proc.pid, options, sink) catch |err| switch (err) { error.PerfAccess => fail("perf_event_open was refused: kernel.perf_event_paranoid is above 2, or a security module forbids it\n", .{}), error.PerfNoSuchEvent => fail("perf_event_open: this CPU or kernel lacks one of the events asked for (in a VM without a PMU, try -e task-clock; --sample takes at most kernel.perf_event_max_sample_rate)\n", .{}), else => |e| return e, }; defer session.close(); // Symbols: the program's own from the start, a library's once the // loader has mapped it, which is at the program's entry point. var symbols: zt.Symbols = .{ .gpa = init.gpa, .io = init.io, .demangle = util.demangle }; defer symbols.deinit(); symbols.free(try symbols.refresh(proc.pid)); var at_entry = false; for (specs.items) |spec| { const addr, const size = if (std.fmt.parseInt(u64, spec.what, 0)) |addr| .{ addr, 8 } else |_| found: { if (symbols.find(spec.what) == null and !at_entry) { try runTo(&proc, symbols.entryPoint() orelse fail("{s}: no symbols to be had from the program\n", .{spec.what})); at_entry = true; symbols.free(try symbols.refresh(proc.pid)); } const sym = symbols.find(spec.what) orelse fail("{s}: no such symbol in what the program has mapped\n", .{spec.what}); break :found .{ sym.addr, sym.size }; }; const len = spec.len orelse if (std.mem.indexOfScalar(u64, &.{ 1, 2, 4 }, size)) |_| @as(u8, @intCast(size)) else 8; session.watch(.{ .addr = addr, .len = len, .mode = spec.mode, .name = spec.what }) catch |err| switch (err) { error.NoFreeBreakpoint => fail("{s}: no debug register left, there are four\n", .{spec.what}), error.PerfNoSuchEvent => fail("{s}: a watchpoint covers 1, 2, 4 or 8 bytes at an address aligned to that, not {d} at {x}\n", .{ spec.what, len, addr }), else => |e| return e, }; } zt.perf.release(proc); const start = zt.event.now(); const exit_code: ?u64 = pump(&session, sink, if (produced) |p| .{ .ring = p.ring, .sorted = &sorted } else null, interval_ms) catch |err| switch (err) { error.RecordingFull => null, else => |e| return e, }; if (exit_code == null) proc.close(); const ns = zt.event.now() - start; try finish(init, &rec, out, exit_code, session.lost, ns, options.counters, session.counts); } /// Decodes until the target ends; its exit code. `error.RecordingFull` /// when the recording reaches its limit first. fn pump(session: *zt.perf.Session, sink: zt.Sink, own: ?struct { ring: *zt.Ring, sorted: *zt.perf.Sorted }, interval_ms: u32) !u64 { var next_read = zt.event.now(); // What both sources have reported past: the start of the round before. var past: u64 = 0; while (true) { // A target with a ring of its own waits when that is full: look often. var wait_ms: i32 = if (own != null) 5 else 100; if (interval_ms != 0) { const now = zt.event.now(); if (now >= next_read) { try session.readCounters(); next_read += @as(u64, interval_ms) * std.time.ns_per_ms; } wait_ms = @min(wait_ms, @as(i32, @intCast((next_read -| now) / std.time.ns_per_ms + 1))); } const now = zt.event.now(); const alive = try session.poll(wait_ms); if (own) |o| { _ = try o.ring.drain(sink); try o.sorted.flush(past); past = now; } if (!alive) break; } try session.readCounters(); const code = try exited(session.pid, sink); if (own) |o| { // What it emitted on its way out. _ = try o.ring.drain(sink); try o.sorted.flush(std.math.maxInt(u64)); } return code; } /// Waits for the target's end and records it. The exit code. pub fn exited(pid: linux.pid_t, sink: zt.Sink) !u64 { var status: u32 = 0; _ = linux.waitpid(pid, @ptrCast(&status), 0); const code: u64 = if (linux.W.IFEXITED(status)) linux.W.EXITSTATUS(status) else 128 + @as(u64, @backingInt(linux.W.TERMSIG(status))); try sink.emit(.{ .ts = zt.event.now(), .tid = @intCast(pid), .kind = .exit, .a = .{ code, 0, 0, 0, 0, 0 } }, ""); return code; } /// Closes the recording and says what it holds; `exit_code` is null when /// it filled up and the target was stopped for it. pub fn finish(init: std.process.Init, rec: *zt.Recorder, out: []const u8, exit_code: ?u64, lost: u64, ns: u64, counters: []const zt.perf.Counter, counts: []const u64) !void { const events = rec.count; const moments = rec.moments + @intFromBool(rec.delta.items.len > 0); try rec.close(); const size = (try std.Io.Dir.cwd().statFile(init.io, out, .{})).size; const code = exit_code orelse fail("{s} is full at {d} bytes ({d} events) and the program was stopped: record fewer kinds of event, or allow more with --max-size BYTES\n", .{ out, size, events }); for (counters, counts) |c, count| std.debug.print("{d:>16} {t}\n", .{ count, c }); std.debug.print("{s}: {d} moments, {d} events ({d} lost), {d} bytes ({d:.1} an event), {d:.1} ms, {d:.0} events/s, exit {d}\n", .{ out, moments, events, lost, size, @as(f64, @floatFromInt(size)) / @as(f64, @floatFromInt(@max(events, 1))), @as(f64, @floatFromInt(ns)) / 1e6, @as(f64, @floatFromInt(events)) / (@as(f64, @floatFromInt(ns)) / 1e9), code, }); } /// Runs the held target up to `addr`, through a breakpoint there. fn runTo(proc: *zt.ptrace.Process, addr: u64) !void { var saved: [1]u8 = undefined; if (proc.read(addr, &saved) != 1) return error.BadAddress; try proc.write(addr, &.{0xcc}); while (true) switch (try proc.cont()) { .trap => break, .exited, .killed => fail("the program ended before its entry point\n", .{}), else => {}, }; try proc.write(addr, &saved); var regs = try proc.regs(); regs.rip = addr; try proc.setRegs(®s); }