tiny.profiling.host

1pub const Capture = struct {2    kind: []const u8,3    tool: []const u8,4    tool_version: ?[]const u8 = null,5    scope: []const u8 = scope,6    capture_path: []const u8,7    summary_path: []const u8,8    state: []const u8,9    caveat_kind: ?[]const u8 = null,10    caveat_message: ?[]const u8 = null,11};

1pub const Lane = union(enum) {2    counters: counters.Lane,3    sampling: sampling.Lane,4    dhat: dhat.Lane,5    offcpu: offcpu.Lane,6    coverage: coverage.Lane,7};

1pub const Options = struct {2    counters: ?counters.Options = null,3    sampling: ?sampling.Options = null,4    dhat: ?dhat.Options = null,5    offcpu: ?offcpu.Options = null,6    coverage: ?coverage.Options = null,78    pub fn validate(self: Options) !void {9        var enabled: usize = 0;10        if (self.counters != null) enabled += 1;11        if (self.sampling != null) enabled += 1;12        if (self.dhat != null) enabled += 1;13        if (self.offcpu != null) enabled += 1;14        if (self.coverage != null) enabled += 1;15        if (enabled > 1) return error.ConflictingHostProfilers;16        if (self.counters) |options| try options.validate();17        if (self.sampling) |options| try options.validate();18    }1920    pub fn any(self: Options) bool {21        return self.counters != null or self.sampling != null or self.dhat != null or self.offcpu != null or self.coverage != null;22    }2324    pub fn requiresDirect(self: Options) bool {25        return self.dhat != null or self.offcpu != null or self.coverage != null;26    }2728    pub fn tool(self: Options) ?[]const u8 {29        if (self.counters != null) return counters.tool;30        if (self.sampling != null) return sampling.tool;31        if (self.dhat != null) return dhat.tool;32        if (self.offcpu) |options| return options.toolName();33        if (self.coverage != null) return coverage.tool;34        return null;35    }3637    pub fn kind(self: Options) ?[]const u8 {38        if (self.counters != null) return counters.kind;39        if (self.sampling != null) return sampling.kind;40        if (self.dhat != null) return dhat.kind;41        if (self.offcpu != null) return offcpu.kind;42        if (self.coverage != null) return coverage.kind;43        return null;44    }4546    pub fn probeRequest(47        self: Options,48        allocator: std.mem.Allocator,49    ) !?ProbeRequest {50        if (self.counters != null or51            self.sampling != null or52            self.dhat != null or53            self.coverage != null)54        {55            return .{56                .argv = try allocator.dupe(57                    []const u8,58                    &.{ self.tool().?, "--version" },59                ),60                .version_output = true,61            };62        }63        if (self.offcpu) |options| {64            const probe_flag = switch (options.mode) {65                .time => "-h",66                .stacks => "--version",67            };68            return .{69                .argv = try allocator.dupe(70                    []const u8,71                    &.{ options.toolName(), probe_flag },72                ),73                .version_output = options.mode == .stacks,74            };75        }76        return null;77    }7879    pub fn buildArgs(self: Options) []const []const u8 {80        if (self.dhat != null and builtin.cpu.arch == .x86_64) {81            return &.{"-Dcpu=x86_64_v3"};82        }83        return &.{};84    }85};

1pub const ProbeRequest = struct {2    argv: []const []const u8,3    version_output: bool,4};

1pub const ToolProbe = struct {2    available: bool = false,3    version: ?[]const u8 = null,4};

1pub const Wrapped = struct {2    argv: []const []const u8,3    lane: ?Lane = null,4};

1pub const direct_scope = "workload-binary";

1pub fn missingBinary(2    allocator: std.mem.Allocator,3    options: Options,4    workload_root: []const u8,5    tool_probe: ToolProbe,6) ![]const Capture {7    const lane = try descriptor(allocator, options, workload_root) orelse return &.{};8    const rows = try allocator.alloc(Capture, 1);9    rows[0] = .{10        .kind = lane.kind,11        .tool = lane.tool,12        .tool_version = tool_probe.version,13        .capture_path = lane.capture_path,14        .summary_path = lane.summary_path,15        .state = "binary_missing",16        .caveat_kind = "no_direct_binary",17        .caveat_message = "workload declares no benchmark binary in the catalog; direct-binary evidence needs bin metadata",18    };19    return rows;20}

1pub fn probe(2    allocator: std.mem.Allocator,3    process_io: std.Io,4    request: ProbeRequest,5) !ToolProbe {6    const result = sys.process.run(allocator, process_io, .{7        .argv = request.argv,8        .stdout_limit = .limited(max_probe_output_bytes),9        .stderr_limit = .limited(max_probe_output_bytes),10    }) catch |err| switch (err) {11        error.OutOfMemory => return err,12        else => return .{},13    };14    defer allocator.free(result.stdout);15    defer allocator.free(result.stderr);16    if (sys.process.exitCode(result.term) != 0) return .{};17    return .{18        .available = true,19        .version = if (request.version_output)20            try probeVersion(allocator, result.stdout, result.stderr)21        else22            null,23    };24}

1pub fn resetCaptureArtifacts(wrapped: Wrapped) !void {2    const lane = wrapped.lane orelse return;3    switch (lane) {4        .counters => |value| {5            try deleteFileIfPresent(value.csv_path);6            for (value.runs) |run| try deleteFileIfPresent(run.csv_path);7            for (value.repetition_csv_paths) |path| try deleteFileIfPresent(path);8            for (value.event_groups) |group| try deleteFileIfPresent(group.csv_path);9        },10        .sampling => |value| try deleteFileIfPresent(value.data_path),11        .dhat => |value| {12            try deleteFileIfPresent(value.capture_path);13            try deleteFileIfPresent(value.out_path);14        },15        .offcpu => |value| {16            try deleteFileIfPresent(value.capture_path);17            try deleteFileIfPresent(value.diagnostics_path);18        },19        .coverage => |value| try sys.fs.deleteTree(value.directory_path),20    }21}

1pub const scope = "whole-step";

1pub fn setupFailed(2    allocator: std.mem.Allocator,3    options: Options,4    workload_root: []const u8,5    tool_probe: ToolProbe,6) ![]const Capture {7    const lane = try descriptor(allocator, options, workload_root) orelse return &.{};8    const rows = try allocator.alloc(Capture, 1);9    rows[0] = .{10        .kind = lane.kind,11        .tool = lane.tool,12        .tool_version = tool_probe.version,13        .scope = direct_scope,14        .capture_path = lane.capture_path,15        .summary_path = lane.summary_path,16        .state = "setup_failed",17        .caveat_kind = "workload_build_failed",18        .caveat_message = "the benchmark binary failed to build; inspect setup stderr before interpreting missing evidence",19    };20    return rows;21}

1pub fn summarize(2    allocator: std.mem.Allocator,3    process_io: std.Io,4    wrapped: Wrapped,5    exit_code: i64,6    stderr_path: []const u8,7    tool_probe: ToolProbe,8    scope_label: []const u8,9    workload_name: []const u8,10    max_benchmark_allocated_bytes: ?u64,11) ![]const Capture {12    const lane = wrapped.lane orelse return &.{};13    var row = switch (lane) {14        .counters => |value| try counters.summarize(15            allocator,16            value,17            exit_code,18            stderr_path,19            tool_probe.available,20        ),21        .sampling => |value| try sampling.summarize(22            allocator,23            process_io,24            value,25            exit_code,26            stderr_path,27            tool_probe.available,28        ),29        .dhat => |value| try dhat.summarize(30            allocator,31            value,32            exit_code,33            stderr_path,34            tool_probe.available,35            max_benchmark_allocated_bytes,36        ),37        .offcpu => |value| try offcpu.summarize(38            allocator,39            value,40            exit_code,41            stderr_path,42            tool_probe.available,43        ),44        .coverage => |value| try coverage.summarize(45            allocator,46            value,47            exit_code,48            stderr_path,49            tool_probe.available,50            workload_name,51        ),52    };53    row.tool_version = tool_probe.version;54    row.scope = scope_label;55    const rows = try allocator.alloc(Capture, 1);56    rows[0] = row;57    return rows;58}

1pub fn warmupFailed(2    allocator: std.mem.Allocator,3    options: Options,4    workload_root: []const u8,5    tool_probe: ToolProbe,6) ![]const Capture {7    const lane = try descriptor(allocator, options, workload_root) orelse return &.{};8    const rows = try allocator.alloc(Capture, 1);9    rows[0] = .{10        .kind = lane.kind,11        .tool = lane.tool,12        .tool_version = tool_probe.version,13        .scope = direct_scope,14        .capture_path = lane.capture_path,15        .summary_path = lane.summary_path,16        .state = "warmup_failed",17        .caveat_kind = "workload_warmup_failed",18        .caveat_message = "an unmeasured warmup failed; measurement and profiler capture were suppressed",19    };20    return rows;21}

1pub fn wrap(2    allocator: std.mem.Allocator,3    options: Options,4    argv: []const []const u8,5    workload_root: []const u8,6    tool_available: bool,7) !Wrapped {8    try options.validate();9    if (options.counters) |lane_options| {10        const lane = try counters.plan(allocator, lane_options, workload_root);11        if (!tool_available) return .{ .argv = argv, .lane = .{ .counters = lane } };12        return .{ .argv = try counters.wrapArgv(allocator, lane_options, argv, lane), .lane = .{ .counters = lane } };13    }14    if (options.sampling) |lane_options| {15        const lane = try sampling.plan(allocator, lane_options, workload_root);16        if (!tool_available) return .{ .argv = argv, .lane = .{ .sampling = lane } };17        return .{ .argv = try sampling.wrapArgv(allocator, lane_options, argv, lane), .lane = .{ .sampling = lane } };18    }19    if (options.dhat) |lane_options| {20        const lane = try dhat.plan(allocator, lane_options, workload_root);21        if (!tool_available) return .{ .argv = argv, .lane = .{ .dhat = lane } };22        return .{ .argv = try dhat.wrapArgv(allocator, lane_options, argv, lane), .lane = .{ .dhat = lane } };23    }24    if (options.offcpu) |lane_options| {25        const lane = try offcpu.plan(allocator, lane_options, workload_root);26        if (!tool_available) return .{ .argv = argv, .lane = .{ .offcpu = lane } };27        return .{ .argv = try offcpu.wrapArgv(allocator, lane_options, argv, lane), .lane = .{ .offcpu = lane } };28    }29    if (options.coverage) |lane_options| {30        const lane = try coverage.plan(allocator, lane_options, workload_root);31        if (!tool_available) return .{ .argv = argv, .lane = .{ .coverage = lane } };32        return .{ .argv = try coverage.wrapArgv(allocator, lane_options, argv, lane), .lane = .{ .coverage = lane } };33    }34    return .{ .argv = argv };35}

1const runtime = @import("runtime.zig");23pub const counters = runtime.counters;4pub const coverage = runtime.coverage;5pub const dhat = runtime.dhat;6pub const offcpu = runtime.offcpu;7pub const process = runtime.process;8pub const sampling = runtime.sampling;9pub const state = @import("state.zig");1011pub const scope = runtime.scope;12pub const direct_scope = runtime.direct_scope;13pub const ProbeRequest = runtime.ProbeRequest;14pub const ToolProbe = runtime.ToolProbe;15pub const Options = runtime.Options;16pub const Capture = runtime.Capture;17pub const Wrapped = runtime.Wrapped;18pub const Lane = runtime.Lane;19pub const wrap = runtime.wrap;20pub const resetCaptureArtifacts = runtime.resetCaptureArtifacts;21pub const summarize = runtime.summarize;22pub const missingBinary = runtime.missingBinary;23pub const setupFailed = runtime.setupFailed;24pub const warmupFailed = runtime.warmupFailed;25pub const probe = runtime.probe;

1pub const host = @import("host/root.zig");