//! 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. \\ ; 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 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, "--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. var proc = try zt.ptrace.Process.spawn(path, argv, 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; // 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, rec.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 }; 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, &rec, 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, rec: *zt.Recorder, interval_ms: u32) !u64 { var next_read = zt.event.now(); while (true) { var wait_ms: i32 = 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 = @intCast((next_read -| now) / std.time.ns_per_ms + 1); } if (!try session.poll(wait_ms)) break; } try session.readCounters(); return exited(session.pid, rec.sink()); } /// 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); }