//! The in-process backend: code that lives inside the target, preloaded //! (libztrace-agent.so), linked in (libztrace-agent.a), or imported by a Zig //! program (this module). When the process starts it attaches the ring its //! tracer handed it and turns on what `ztrace run` asked for through //! ZTRACE_* variables; with no ring it does nothing. //! //! Raw syscalls only, no libc, no allocation: this code runs inside malloc //! and inside signal handlers. const std = @import("std"); const linux = std.os.linux; const zt = @import("ztrace"); const client = zt.client; const Kind = zt.Kind; pub const symbols = @import("symbols.zig"); pub const signal = @import("signal.zig"); pub const sud = @import("sud.zig"); pub const hook = @import("hook.zig"); pub const regions = @import("watch.zig"); /// Null when nothing traces the process: every entry point returns at once. pub var ring: ?*zt.Ring = null; /// `alloc` and `free` events wanted (the library's interposed malloc asks). pub var allocations = false; /// The kinds that end a moment in the recording (ZTRACE_CUT): watched memory /// is brought up to date before each. var cut: u64 = 0; /// 0 not started, 1 starting, 2 started. var state: std.atomic.Value(u8) = .init(0); threadlocal var started = false; /// The most bytes an event of ours carries: a label is cut to it, memory is /// split at it. A record with it fits the smallest ring. pub const max_payload = 2048; /// The most bytes of a syscall's path or buffer that go into its event /// (ZTRACE_CAPTURE): recordings are meant to stay small. pub var capture: usize = 256; /// The most memory one `watch` or `snapshot` takes: more is a mistake (a /// whole heap, a whole mapping), refused with a line on stderr. pub const max_region = 1 << 20; /// Every entry point comes through here first. A Zig program that wants its /// hooks and syscalls from the start calls it at the top of main; for the /// rest the library has a constructor. pub fn init() void { if (state.load(.acquire) != 0 or state.cmpxchgStrong(0, 1, .acquire, .monotonic) != null) return; defer state.store(2, .release); const r = client.get() orelse return; var buf: [1 << 16]u8 = undefined; const env = client.environ(&buf); cut = if (client.getenv(env, "ZTRACE_CUT")) |v| std.fmt.parseInt(u64, v, 0) catch 0 else 0; if (client.getenv(env, "ZTRACE_CAPTURE")) |v| capture = @min(std.fmt.parseInt(usize, v, 0) catch capture, max_payload); ring = r; var maps = symbols.Maps.open(null) orelse return; while (maps.next()) |m| emit(.map, 0, .{ m.start, m.end - m.start, m.prot, m.offset, 0, 0 }, text(m.path, max_payload)); maps.close(); threadStart(); if (client.getenv(env, "ZTRACE_WATCH")) |list| { var specs = std.mem.tokenizeScalar(u8, list, ','); while (specs.next()) |spec| { const region = symbols.find(null, spec) orelse symbols.Symbol{ .addr = 0, .size = 0 }; if (region.size != 0) watch(@as([*]const u8, @ptrFromInt(region.addr))[0..region.size], spec) else complain(&.{ "nothing called ", spec }); } } if (client.getenv(env, "ZTRACE_HOOKS")) |list| { var specs = std.mem.tokenizeScalar(u8, list, ','); while (specs.next()) |spec| { if (symbols.find(null, spec)) |function| hook.add(function.addr) else complain(&.{ "nothing called ", spec }); } } allocations = client.getenv(env, "ZTRACE_ALLOC") != null; if (client.getenv(env, "ZTRACE_SYSCALLS") != null) { sud.enable(); sud.selector = sud.block; } } /// What the user asked for cannot be done: said where they will see it. fn complain(parts: []const []const u8) void { const was = sud.selector; sud.selector = sud.allow; defer sud.selector = was; _ = linux.write(2, "ztrace agent: ", 14); for (parts) |part| _ = linux.write(2, part.ptr, part.len); _ = linux.write(2, "\n", 1); } /// Memory too large to record whole: said, and refused. fn tooLarge(memory: []const u8, what: []const u8) bool { if (memory.len <= max_region) return false; var buf: [32]u8 = undefined; complain(&.{ what, " of ", std.fmt.bufPrint(&buf, "{d}", .{memory.len}) catch "", " bytes refused: more than 1 MiB. Watch the part that matters." }); return true; } pub fn threadId() u32 { return client.threadId(); } /// The calling thread's first sign of life. Once per thread, whoever notices it first. pub fn threadStart() void { if (started) return; started = true; emit(.thread_start, 0, .{ threadId(), 0, 0, 0, 0, 0 }, ""); sud.arm(); } /// In a forked child, which remembers being its parent. pub fn forked() void { const tid: u32 = @intCast(linux.gettid()); if (tid == client.tid) return; client.tid = tid; started = false; threadStart(); } pub fn emit(kind: Kind, aux: u16, a: [6]u64, payload: []const u8) void { const r = ring orelse return; // What the agent does to get an event out (a futex when the ring is // full, or to wake the tracer) is not the target's doing. const was = sud.selector; sud.selector = sud.allow; defer sud.selector = was; if (cut & kind.bit() != 0) regions.diff(); r.emit(.{ .ts = zt.event.now(), .tid = threadId(), .kind = kind, .aux = aux, .a = a }, payload); } /// A string's id is its hash: no backend needs to ask another which are taken. pub fn stringId(string: []const u8) u64 { return std.hash.Wyhash.hash(0, string); } /// `bytes` as a payload: cut to `max`, and never the length of `Regs`, which /// the recorder would take for registers. pub fn text(bytes: []const u8, max: usize) []const u8 { const len = @min(bytes.len, max); return bytes[0 .. len - @intFromBool(len == @sizeOf(zt.Regs))]; } /// `mem_write` events: `bytes` is what is at `addr` now. pub fn write(addr: u64, bytes: []const u8) void { var at: usize = 0; while (at < bytes.len) : (at += max_payload) { const part = bytes[at..@min(bytes.len, at + max_payload)]; emit(.mem_write, 0, .{ addr + at, part.len, 0, 0, 0, 0 }, part); } } // The target's side: what a program that links the agent calls. The same // three are in include/ztrace.h for C. /// A point in the run worth a moment: a `mark` event with a text and a value. pub fn mark(label: []const u8, value: u64) void { init(); emit(.mark, 0, .{ value, 0, 0, 0, 0, 0 }, text(label, max_payload)); } /// Names `memory` (a `variable` event), records it, and keeps recording what /// changes in it: only the bytes that changed, before each event that ends a /// moment. At most `max_region` bytes, which must stay mapped. Watched from /// inside a hooked call, it is forgotten when that call returns. pub fn watch(memory: []const u8, name: []const u8) void { init(); if (ring == null or tooLarge(memory, "watch")) return; const was = sud.selector; sud.selector = sud.allow; defer sud.selector = was; const id = stringId(name); emit(.string, 0, .{ id, 0, 0, 0, 0, 0 }, text(name, max_payload)); emit(.variable, 0, .{ @intFromPtr(memory.ptr), memory.len, id, 0, 0, 0 }, ""); write(@intFromPtr(memory.ptr), memory); regions.add(memory, threadId(), hook.open()); } /// Records `memory` as it is now, once. At most `max_region` bytes. pub fn snapshot(memory: []const u8) void { init(); if (ring == null or tooLarge(memory, "snapshot")) return; write(@intFromPtr(memory.ptr), memory); } test { _ = symbols; _ = regions; }