tiny.profiling.host.counters

1const std = @import("std");2const capture = @import("capture");3const sys = @import("sys");45const root = @import("root.zig");67pub const tool = "perf";8pub const kind = "perf_stat";9pub const default_events =10    "page-faults,{cycles,instructions,task-clock},{branches,branch-misses}";11pub const energy_events = "duration_time,power/energy-pkg/";12pub const default_repeat: u32 = 3;13pub const max_group_size: u32 = 100;14const max_capture_bytes = 64 * 1024 * 1024;1516pub const Options = struct {17    events: []const u8 = default_events,18    repeat: u32 = default_repeat,19    group_size: u32 = 0,20    system_wide: bool = false,2122    pub fn validate(self: Options) !void {23        if (std.mem.trim(u8, self.events, " \t\r\n").len == 0) return error.InvalidCounterEvents;24        if (!root.process.validRepeat(self.repeat)) return error.InvalidCounterRepeat;25        if (self.group_size > max_group_size) return error.InvalidCounterGroupSize;26    }27};2829pub const Run = struct {30    group_index: u32,31    repetition_index: u32,32    events: []const u8,33    csv_path: []const u8,34};3536pub const Lane = struct {37    csv_path: []const u8,38    summary_path: []const u8,39    event_groups: []const capture.perfstat.EventGroup,40    event_expression: []const u8,41    kernel_event_groups: []const capture.perfstat.KernelEventGroup,42    runs: []const Run,43    repetition_csv_paths: []const []const u8,44    system_wide: bool,45};4647pub fn plan(allocator: std.mem.Allocator, options: Options, workload_root: []const u8) !Lane {48    try options.validate();49    const csv_path = try std.fs.path.join(allocator, &.{ workload_root, "perf.stat.csv" });50    const event_expression = try capture.perfstat.normalizeEventExpression(51        allocator,52        options.events,53    );54    const groups = try capture.perfstat.eventGroups(55        allocator,56        event_expression,57        options.group_size,58    );59    const grouped = groups.len > 1;60    const repeated = options.repeat > 1;61    const runs = try planRuns(allocator, options, workload_root, groups);62    const repetition_csv_paths = try planRepetitionCsvPaths(63        allocator,64        workload_root,65        runs,66        options.repeat,67        grouped,68        repeated,69    );70    try attachGroupCsvPaths(71        allocator,72        workload_root,73        csv_path,74        groups,75        runs,76        grouped,77        repeated,78    );79    return .{80        .csv_path = csv_path,81        .summary_path = try std.fs.path.join(82            allocator,83            &.{ workload_root, "perf.stat.summary.json" },84        ),85        .event_groups = groups,86        .event_expression = event_expression,87        .kernel_event_groups = try capture.perfstat.kernelEventGroups(88            allocator,89            event_expression,90        ),91        .runs = runs,92        .repetition_csv_paths = repetition_csv_paths,93        .system_wide = options.system_wide,94    };95}9697fn planRuns(98    allocator: std.mem.Allocator,99    options: Options,100    workload_root: []const u8,101    groups: []const capture.perfstat.EventGroup,102) ![]const Run {103    const execution_count = std.math.mul(104        usize,105        groups.len,106        @as(usize, options.repeat),107    ) catch return error.TooManyCounterExecutions;108    if (execution_count > root.process.max_executions) return error.TooManyCounterExecutions;109    const grouped = groups.len > 1;110    const repeated = options.repeat > 1;111    const runs = try allocator.alloc(Run, execution_count);112    var run_index: usize = 0;113    for (0..options.repeat) |repetition_index| {114        for (groups) |group| {115            const name = try runCsvName(116                allocator,117                grouped,118                repeated,119                group.index,120                @intCast(repetition_index + 1),121            );122            runs[run_index] = .{123                .group_index = group.index,124                .repetition_index = @intCast(repetition_index + 1),125                .events = group.events,126                .csv_path = try std.fs.path.join(allocator, &.{ workload_root, name }),127            };128            run_index += 1;129        }130    }131    return runs;132}133134fn planRepetitionCsvPaths(135    allocator: std.mem.Allocator,136    workload_root: []const u8,137    runs: []const Run,138    repeat: u32,139    grouped: bool,140    repeated: bool,141) ![]const []const u8 {142    const repetition_csv_paths = try allocator.alloc(143        []const u8,144        if (repeated) repeat else 0,145    );146    for (repetition_csv_paths, 0..) |*csv_path, repetition_index| {147        if (grouped) {148            const name = try std.fmt.allocPrint(149                allocator,150                "perf.stat.repeat.{d}.csv",151                .{repetition_index + 1},152            );153            csv_path.* = try std.fs.path.join(allocator, &.{ workload_root, name });154        } else {155            csv_path.* = runs[repetition_index].csv_path;156        }157    }158    return repetition_csv_paths;159}160161fn attachGroupCsvPaths(162    allocator: std.mem.Allocator,163    workload_root: []const u8,164    csv_path: []const u8,165    groups: []capture.perfstat.EventGroup,166    runs: []const Run,167    grouped: bool,168    repeated: bool,169) !void {170    for (groups, 0..) |*group, group_index| {171        if (!grouped) {172            group.csv_path = csv_path;173        } else if (!repeated) {174            group.csv_path = runs[group_index].csv_path;175        } else {176            const name = try std.fmt.allocPrint(177                allocator,178                "perf.stat.group.{d}.csv",179                .{group.index},180            );181            group.csv_path = try std.fs.path.join(allocator, &.{ workload_root, name });182        }183    }184}185186fn runCsvName(187    allocator: std.mem.Allocator,188    grouped: bool,189    repeated: bool,190    group_index: u32,191    repetition_index: u32,192) ![]const u8 {193    if (grouped and repeated) return try std.fmt.allocPrint(194        allocator,195        "perf.stat.group.{d}.repeat.{d}.csv",196        .{ group_index, repetition_index },197    );198    if (grouped) return try std.fmt.allocPrint(199        allocator,200        "perf.stat.group.{d}.csv",201        .{group_index},202    );203    if (repeated) return try std.fmt.allocPrint(204        allocator,205        "perf.stat.repeat.{d}.csv",206        .{repetition_index},207    );208    return "perf.stat.csv";209}210211pub fn wrapArgv(allocator: std.mem.Allocator, options: Options, argv: []const []const u8, lane: Lane) ![]const []const u8 {212    return try wrapRunArgv(allocator, options, argv, lane, 0);213}214215pub fn wrapRunArgv(216    allocator: std.mem.Allocator,217    options: Options,218    argv: []const []const u8,219    lane: Lane,220    run_index: usize,221) ![]const []const u8 {222    try options.validate();223    std.debug.assert(run_index < lane.runs.len);224    const run = lane.runs[run_index];225    return try capture.perfstat.command(226        allocator,227        tool,228        argv,229        run.csv_path,230        run.events,231        .{ .system_wide = options.system_wide },232    );233}234235pub fn summarize(236    allocator: std.mem.Allocator,237    lane: Lane,238    exit_code: i64,239    stderr_path: []const u8,240    tool_available: bool,241) !root.Capture {242    if (!tool_available) return missingTool(lane);243    var summaries: std.ArrayList(capture.perfstat.Summary) = .empty;244    for (lane.runs) |run| {245        const summary = capture.perfstat.parseCsv(allocator, run.csv_path) catch |err| switch (err) {246            error.FileNotFound => return try failed(allocator, lane, exit_code, stderr_path),247            else => |actual| return actual,248        };249        if (summary.counters.len == 0) return try failed(allocator, lane, exit_code, stderr_path);250        try summaries.append(allocator, summary);251    }252    var summary = try mergeLaneSummaries(allocator, lane, summaries.items);253    summary.event_expression = lane.event_expression;254    summary.kernel_event_groups = lane.kernel_event_groups;255    if (lane.system_wide) summary = try addSystemWideCaveat(allocator, summary);256    try capture.perfstat.writeSummaryFile(lane.summary_path, summary);257    const evidence_caveat = capture.perfstat.counterEvidenceCaveat(summary);258    return .{259        .kind = kind,260        .tool = tool,261        .capture_path = lane.csv_path,262        .summary_path = lane.summary_path,263        .state = "summary_written",264        .caveat_kind = if (evidence_caveat) |row| row.kind else null,265        .caveat_message = if (evidence_caveat) |row| row.message else null,266    };267}268269fn mergeLaneSummaries(270    allocator: std.mem.Allocator,271    lane: Lane,272    summaries: []const capture.perfstat.Summary,273) !capture.perfstat.Summary {274    const grouped = lane.event_groups.len > 1;275    const repeated = lane.repetition_csv_paths.len > 1;276    if (!grouped and !repeated) return summaries[0];277    try writeCombinedCsv(allocator, lane.csv_path, summaries);278    if (!grouped) return try capture.perfstat.mergeRepeatedSummaries(279        allocator,280        lane.csv_path,281        summaries,282    );283    if (!repeated) return try capture.perfstat.mergeSummaries(284        allocator,285        lane.csv_path,286        lane.event_groups,287        summaries,288    );289    return try mergeGroupedRepetitions(allocator, lane, summaries);290}291292fn mergeGroupedRepetitions(293    allocator: std.mem.Allocator,294    lane: Lane,295    summaries: []const capture.perfstat.Summary,296) !capture.perfstat.Summary {297    const group_count = lane.event_groups.len;298    var repetition_summaries: std.ArrayList(capture.perfstat.Summary) = .empty;299    for (lane.repetition_csv_paths, 0..) |csv_path, repetition_index| {300        const start = repetition_index * group_count;301        const end = start + group_count;302        try writeCombinedCsv(allocator, csv_path, summaries[start..end]);303        try repetition_summaries.append(304            allocator,305            try capture.perfstat.mergeSummaries(306                allocator,307                csv_path,308                try repetitionGroups(allocator, lane, repetition_index),309                summaries[start..end],310            ),311        );312    }313    var group_summaries: std.ArrayList(capture.perfstat.Summary) = .empty;314    for (lane.event_groups, 0..) |group, group_index| {315        group_summaries.clearRetainingCapacity();316        for (0..lane.repetition_csv_paths.len) |repetition_index| {317            try group_summaries.append(318                allocator,319                summaries[repetition_index * group_count + group_index],320            );321        }322        try writeCombinedCsv(allocator, group.csv_path, group_summaries.items);323    }324    return try capture.perfstat.mergeGroupedRepeatedSummaries(325        allocator,326        lane.csv_path,327        lane.event_groups,328        repetition_summaries.items,329    );330}331332fn addSystemWideCaveat(333    allocator: std.mem.Allocator,334    summary: capture.perfstat.Summary,335) !capture.perfstat.Summary {336    var result = summary;337    const caveats = try allocator.alloc(capture.perfstat.Caveat, summary.caveats.len + 1);338    @memcpy(caveats[0..summary.caveats.len], summary.caveats);339    caveats[summary.caveats.len] = .{340        .event = "perf.stat",341        .kind = "system_wide_scope",342        .message = "system-wide counters include concurrent host activity and " ++343            "are not attributed exclusively to the workload process",344        .value_text = "",345        .running_percent = null,346    };347    result.caveats = caveats;348    return result;349}350351fn repetitionGroups(352    allocator: std.mem.Allocator,353    lane: Lane,354    repetition_index: usize,355) ![]const capture.perfstat.EventGroup {356    const groups = try allocator.alloc(capture.perfstat.EventGroup, lane.event_groups.len);357    const start = repetition_index * lane.event_groups.len;358    for (groups, lane.event_groups, 0..) |*destination, source, group_index| {359        destination.* = source;360        destination.csv_path = lane.runs[start + group_index].csv_path;361    }362    return groups;363}364365fn writeCombinedCsv(366    allocator: std.mem.Allocator,367    path: []const u8,368    summaries: []const capture.perfstat.Summary,369) !void {370    var file = try sys.fs.cwd().createFile(std.Options.debug_io, path, .{ .truncate = true });371    defer file.close(std.Options.debug_io);372    var buffer: [8192]u8 = undefined;373    var file_writer = file.writer(std.Options.debug_io, &buffer);374    const writer = &file_writer.interface;375    for (summaries) |summary| {376        const text = try sys.fs.readFileAlloc(allocator, summary.csv_path, max_capture_bytes);377        defer allocator.free(text);378        try writer.writeAll(text);379        if (text.len == 0 or text[text.len - 1] != '\n') try writer.writeByte('\n');380    }381    try writer.flush();382}383384fn missingTool(lane: Lane) root.Capture {385    return .{386        .kind = kind,387        .tool = tool,388        .capture_path = lane.csv_path,389        .summary_path = lane.summary_path,390        .state = "tool_missing",391        .caveat_kind = "tool_unavailable",392        .caveat_message = "perf is not runnable on this host; counters were not captured",393    };394}395396fn failed(allocator: std.mem.Allocator, lane: Lane, exit_code: i64, stderr_path: []const u8) !root.Capture {397    const row = try capture.caveat.classifyCommandCapture(allocator, .{398        .phase = kind,399        .exit_code = if (exit_code == 0) 1 else exit_code,400        .timed_out = false,401        .capture_path = stderr_path,402    }) orelse capture.caveat.classifyCommandText(.{403        .phase = kind,404        .exit_code = exit_code,405        .timed_out = false,406        .capture_path = stderr_path,407    }, "");408    return .{409        .kind = kind,410        .tool = tool,411        .capture_path = lane.csv_path,412        .summary_path = lane.summary_path,413        .state = "tool_failed",414        .caveat_kind = row.kind,415        .caveat_message = row.message,416    };417}418419test "profiling counters wrap workload argv in perf stat" {420    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);421    defer arena_state.deinit();422    const allocator = arena_state.allocator();423    try std.testing.expectEqualStrings(424        "page-faults,{cycles,instructions,task-clock},{branches,branch-misses}",425        default_events,426    );427    try std.testing.expectEqual(@as(u32, 3), default_repeat);428    const lane = try plan(allocator, .{}, "zig-out/profiling/run/workloads/w");429    const argv = [_][]const u8{ "zig", "build", "bench" };430    const wrapped = try wrapArgv(allocator, .{}, &argv, lane);431    try std.testing.expectEqualStrings("perf", wrapped[0]);432    try std.testing.expectEqualStrings("stat", wrapped[1]);433    try std.testing.expectEqual(@as(usize, default_repeat), lane.runs.len);434    try std.testing.expectEqualStrings(default_events, lane.runs[0].events);435    try std.testing.expectEqualStrings(default_events, lane.event_expression);436    try std.testing.expectEqual(@as(usize, 2), lane.kernel_event_groups.len);437    try std.testing.expectEqual(438        capture.perfstat.KernelGroupConstraint.strong,439        lane.kernel_event_groups[0].constraint,440    );441    try std.testing.expectEqualStrings(default_events, wrapped[5]);442    try std.testing.expectEqualStrings(lane.runs[0].csv_path, wrapped[7]);443    try std.testing.expectEqualStrings("zig", wrapped[wrapped.len - 3]);444    try std.testing.expectEqualStrings("zig-out/profiling/run/workloads/w/perf.stat.csv", lane.csv_path);445}446447test "profiling energy counters use system wide perf scope" {448    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);449    defer arena_state.deinit();450    const allocator = arena_state.allocator();451    const options = Options{452        .events = energy_events,453        .system_wide = true,454    };455    const lane = try plan(allocator, options, "zig-out/profiling/run/workloads/w");456    const argv = [_][]const u8{"workload"};457    const wrapped = try wrapArgv(allocator, options, &argv, lane);458    try std.testing.expect(lane.system_wide);459    try std.testing.expectEqualStrings("-a", wrapped[2]);460    try std.testing.expectEqualStrings(energy_events, wrapped[6]);461    try std.testing.expectEqualStrings("workload", wrapped[wrapped.len - 1]);462}463464test "profiling counters plan bounded default repetitions" {465    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);466    defer arena_state.deinit();467    const allocator = arena_state.allocator();468    const options = Options{};469    const lane = try plan(allocator, options, "zig-out/profiling/run/workloads/w");470    try std.testing.expectEqual(@as(usize, default_repeat), lane.runs.len);471    try std.testing.expectEqualStrings(472        "zig-out/profiling/run/workloads/w/perf.stat.repeat.1.csv",473        lane.runs[0].csv_path,474    );475    try std.testing.expectEqualStrings(476        "zig-out/profiling/run/workloads/w/perf.stat.repeat.3.csv",477        lane.runs[2].csv_path,478    );479    const argv = [_][]const u8{ "zig", "build", "bench" };480    const wrapped = try wrapRunArgv(allocator, options, &argv, lane, 1);481    try std.testing.expectEqualStrings(lane.runs[1].csv_path, wrapped[7]);482    try std.testing.expectError(error.InvalidCounterRepeat, (Options{ .repeat = 0 }).validate());483    try std.testing.expectError(error.InvalidCounterRepeat, (Options{ .repeat = root.process.max_repeat + 1 }).validate());484}485486test "profiling counters plan bounded event group repetition matrix" {487    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);488    defer arena_state.deinit();489    const allocator = arena_state.allocator();490    const options = Options{491        .events = "task-clock,{cycles,instructions},branches",492        .repeat = 2,493        .group_size = 1,494    };495    const lane = try plan(allocator, options, "zig-out/profiling/run/workloads/w");496    try std.testing.expectEqual(@as(usize, 3), lane.event_groups.len);497    try std.testing.expectEqual(@as(usize, 1), lane.kernel_event_groups.len);498    try std.testing.expectEqualStrings(499        "cycles,instructions",500        lane.kernel_event_groups[0].events,501    );502    try std.testing.expectEqual(@as(usize, 6), lane.runs.len);503    try std.testing.expectEqualStrings("task-clock", lane.runs[0].events);504    try std.testing.expectEqualStrings("{cycles,instructions}", lane.runs[1].events);505    try std.testing.expectEqual(@as(u32, 2), lane.runs[3].repetition_index);506    try std.testing.expectEqualStrings(507        "zig-out/profiling/run/workloads/w/perf.stat.group.3.repeat.2.csv",508        lane.runs[5].csv_path,509    );510    try std.testing.expectEqualStrings(511        "zig-out/profiling/run/workloads/w/perf.stat.group.2.csv",512        lane.event_groups[1].csv_path,513    );514    try std.testing.expectEqualStrings(515        "zig-out/profiling/run/workloads/w/perf.stat.repeat.2.csv",516        lane.repetition_csv_paths[1],517    );518    try std.testing.expectError(519        error.TooManyCounterExecutions,520        plan(allocator, .{ .events = "a,b", .repeat = root.process.max_repeat, .group_size = 1 }, "root"),521    );522    try std.testing.expectError(523        error.InvalidCounterGroupSize,524        (Options{ .group_size = max_group_size + 1 }).validate(),525    );526    try std.testing.expectError(527        error.InvalidCounterEvents,528        (Options{ .events = " \t" }).validate(),529    );530}531532test "profiling counters summarize a captured csv" {533    var tmp = std.testing.tmpDir(.{});534    defer tmp.cleanup();535    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);536    defer arena_state.deinit();537    const allocator = arena_state.allocator();538    const dir = try std.fs.path.join(allocator, &.{ ".zig-cache", "tmp", tmp.sub_path[0..] });539    const lane = try plan(allocator, .{ .repeat = 1 }, dir);540    try sys.fs.writeFile(lane.csv_path,541        \\# started on Fri Jul  4 10:00:00 2026542        \\1000.50,msec,task-clock,1000500000,100.00,1.000,CPUs utilized543        \\2000000,,instructions,1000500000,100.00,2.00,insn per cycle544        \\545    );546    const stderr_path = try std.fs.path.join(allocator, &.{ dir, "stderr.txt" });547    try sys.fs.writeFile(stderr_path, "");548    const row = try summarize(allocator, lane, 0, stderr_path, true);549    try std.testing.expectEqualStrings("summary_written", row.state);550    try std.testing.expectEqualStrings("add_counter_repetitions", row.caveat_kind.?);551    try std.testing.expectEqualStrings(552        "perf counter values are single-execution point estimates; add repetitions",553        row.caveat_message.?,554    );555    try std.testing.expect(sys.fs.exists(lane.summary_path));556    const summary = try capture.perfstat.parseSummaryFile(allocator, lane.summary_path);557    const schedule = capture.perfstat.counterSchedule(summary);558    try std.testing.expectEqualStrings("strong_kernel_groups", schedule.status);559    try std.testing.expectEqualStrings(default_events, schedule.event_expression.?);560    try std.testing.expectEqual(@as(u64, 2), schedule.strong_group_count);561    try std.testing.expectEqual(@as(u64, 5), schedule.grouped_event_count);562}563564test "profiling system wide counters retain attribution caveat" {565    var tmp = std.testing.tmpDir(.{});566    defer tmp.cleanup();567    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);568    defer arena_state.deinit();569    const allocator = arena_state.allocator();570    const dir = try std.fs.path.join(allocator, &.{ ".zig-cache", "tmp", tmp.sub_path[0..] });571    const lane = try plan(allocator, .{572        .events = energy_events,573        .repeat = 1,574        .system_wide = true,575    }, dir);576    try sys.fs.writeFile(lane.csv_path,577        \\1000000000,,duration_time,1,100.00,,578        \\10,Joules,power/energy-pkg/u,0,100.00,,579        \\580    );581    const stderr_path = try std.fs.path.join(allocator, &.{ dir, "stderr.txt" });582    try sys.fs.writeFile(stderr_path, "");583    _ = try summarize(allocator, lane, 0, stderr_path, true);584    const summary = try capture.perfstat.parseSummaryFile(allocator, lane.summary_path);585    try std.testing.expectEqualStrings("system_wide_scope", summary.caveats[0].kind);586    try std.testing.expect(std.mem.indexOf(587        u8,588        summary.caveats[0].message,589        "not attributed exclusively",590    ) != null);591}592593test "profiling counters surface excluded kernel evidence caveats" {594    var tmp = std.testing.tmpDir(.{});595    defer tmp.cleanup();596    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);597    defer arena_state.deinit();598    const allocator = arena_state.allocator();599    const dir = try std.fs.path.join(allocator, &.{ ".zig-cache", "tmp", tmp.sub_path[0..] });600    const lane = try plan(allocator, .{601        .events = "context-switches,cpu-migrations,page-faults",602        .repeat = 1,603    }, dir);604    try sys.fs.writeFile(lane.runs[0].csv_path,605        \\0,,context-switches:u,100,100.00,,606        \\0,,cpu-migrations:u,100,100.00,,607        \\90,,page-faults:u,100,100.00,,608        \\609    );610    const stderr_path = try std.fs.path.join(allocator, &.{ dir, "stderr.txt" });611    try sys.fs.writeFile(stderr_path, "");612    const row = try summarize(allocator, lane, 0, stderr_path, true);613    try std.testing.expectEqualStrings("summary_written", row.state);614    try std.testing.expectEqualStrings("excluded_kernel_events", row.caveat_kind.?);615    try std.testing.expect(std.mem.indexOf(616        u8,617        row.caveat_message.?,618        "request kernel access",619    ) != null);620}621622test "profiling counters leave ready repeated evidence uncaveated" {623    var tmp = std.testing.tmpDir(.{});624    defer tmp.cleanup();625    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);626    defer arena_state.deinit();627    const allocator = arena_state.allocator();628    const dir = try std.fs.path.join(allocator, &.{ ".zig-cache", "tmp", tmp.sub_path[0..] });629    const lane = try plan(allocator, .{ .events = "instructions", .repeat = 3 }, dir);630    for (lane.runs) |run| try sys.fs.writeFile(631        run.csv_path,632        "100,,instructions:u,100,100.00,,\n",633    );634    const stderr_path = try std.fs.path.join(allocator, &.{ dir, "stderr.txt" });635    try sys.fs.writeFile(stderr_path, "");636    const row = try summarize(allocator, lane, 0, stderr_path, true);637    try std.testing.expectEqualStrings("summary_written", row.state);638    try std.testing.expect(row.caveat_kind == null);639    try std.testing.expect(row.caveat_message == null);640}641642test "profiling counters summarize separate event groups" {643    var tmp = std.testing.tmpDir(.{});644    defer tmp.cleanup();645    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);646    defer arena_state.deinit();647    const allocator = arena_state.allocator();648    const dir = try std.fs.path.join(allocator, &.{ ".zig-cache", "tmp", tmp.sub_path[0..] });649    const lane = try plan(allocator, .{650        .events = "instructions,branches",651        .repeat = 1,652        .group_size = 1,653    }, dir);654    for (lane.runs, [_]u64{ 100, 40 }) |run, value| {655        try sys.fs.writeFile(656            run.csv_path,657            try std.fmt.allocPrint(allocator, "{d},,{s},100,100.00,,\n", .{ value, run.events }),658        );659    }660    const stderr_path = try std.fs.path.join(allocator, &.{ dir, "stderr.txt" });661    try sys.fs.writeFile(stderr_path, "");662    const row = try summarize(allocator, lane, 0, stderr_path, true);663    try std.testing.expectEqualStrings("summary_written", row.state);664    const summary = try capture.perfstat.parseSummaryFile(allocator, lane.summary_path);665    try std.testing.expectEqual(@as(usize, 2), summary.event_groups.len);666    try std.testing.expectEqual(@as(usize, 0), summary.repetitions.len);667    try std.testing.expectEqual(@as(usize, 2), summary.counters.len);668    try std.testing.expectEqual(@as(usize, 1), summary.caveats.len);669    try std.testing.expectEqualStrings(670        "grouped_point_estimates_separate_executions",671        capture.perfstat.measurementDesign(summary).status,672    );673}674675test "profiling counters summarize raw repetitions" {676    var tmp = std.testing.tmpDir(.{});677    defer tmp.cleanup();678    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);679    defer arena_state.deinit();680    const allocator = arena_state.allocator();681    const dir = try std.fs.path.join(allocator, &.{ ".zig-cache", "tmp", tmp.sub_path[0..] });682    const lane = try plan(allocator, .{ .repeat = 2 }, dir);683    try sys.fs.writeFile(lane.runs[0].csv_path,684        \\100,,instructions,100,100.00,,685        \\686    );687    try sys.fs.writeFile(lane.runs[1].csv_path,688        \\120,,instructions,100,100.00,,689        \\690    );691    const stderr_path = try std.fs.path.join(allocator, &.{ dir, "stderr.txt" });692    try sys.fs.writeFile(stderr_path, "");693    const row = try summarize(allocator, lane, 0, stderr_path, true);694    try std.testing.expectEqualStrings("summary_written", row.state);695    try std.testing.expect(sys.fs.exists(lane.csv_path));696    const summary = try capture.perfstat.mergeRepeatedSummaries(allocator, lane.csv_path, &.{697        try capture.perfstat.parseCsv(allocator, lane.runs[0].csv_path),698        try capture.perfstat.parseCsv(allocator, lane.runs[1].csv_path),699    });700    try std.testing.expectEqual(@as(u64, 2), summary.counter_stability[0].samples);701    try std.testing.expectEqual(@as(f64, 110), summary.counters[0].value.?);702}703704test "profiling counters summarize grouped raw repetitions" {705    var tmp = std.testing.tmpDir(.{});706    defer tmp.cleanup();707    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);708    defer arena_state.deinit();709    const allocator = arena_state.allocator();710    const dir = try std.fs.path.join(allocator, &.{ ".zig-cache", "tmp", tmp.sub_path[0..] });711    const lane = try plan(allocator, .{712        .events = "instructions,branches",713        .repeat = 2,714        .group_size = 1,715    }, dir);716    const values = [_]u64{ 100, 40, 120, 60 };717    for (lane.runs, values) |run, value| {718        try sys.fs.writeFile(719            run.csv_path,720            try std.fmt.allocPrint(allocator, "{d},,{s},100,100.00,,\n", .{ value, run.events }),721        );722    }723    const stderr_path = try std.fs.path.join(allocator, &.{ dir, "stderr.txt" });724    try sys.fs.writeFile(stderr_path, "");725    const row = try summarize(allocator, lane, 0, stderr_path, true);726    try std.testing.expectEqualStrings("summary_written", row.state);727    const summary = try capture.perfstat.parseSummaryFile(allocator, lane.summary_path);728    try std.testing.expectEqual(@as(usize, 2), summary.event_groups.len);729    try std.testing.expectEqual(@as(usize, 2), summary.repetitions.len);730    try std.testing.expectEqual(@as(usize, 2), summary.repetitions[0].counters.len);731    try std.testing.expectEqual(@as(u64, 2), summary.counter_stability[0].samples);732    try std.testing.expectEqual(@as(usize, 1), summary.caveats.len);733    try std.testing.expectEqualStrings(734        "grouped_repeated_separate_executions",735        capture.perfstat.measurementDesign(summary).status,736    );737    try std.testing.expectEqual(@as(u64, 4), capture.perfstat.measurementDesign(summary).execution_count);738    try std.testing.expect(sys.fs.exists(lane.event_groups[0].csv_path));739    try std.testing.expect(sys.fs.exists(lane.repetition_csv_paths[0]));740}741742test "profiling counters classify a failed capture" {743    var tmp = std.testing.tmpDir(.{});744    defer tmp.cleanup();745    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);746    defer arena_state.deinit();747    const allocator = arena_state.allocator();748    const dir = try std.fs.path.join(allocator, &.{ ".zig-cache", "tmp", tmp.sub_path[0..] });749    const lane = try plan(allocator, .{}, dir);750    const stderr_path = try std.fs.path.join(allocator, &.{ dir, "stderr.txt" });751    try sys.fs.writeFile(stderr_path, "perf stat: Permission denied\n");752    const row = try summarize(allocator, lane, 1, stderr_path, true);753    try std.testing.expectEqualStrings("tool_failed", row.state);754    try std.testing.expectEqualStrings("permission_denied", row.caveat_kind.?);755}756757test "profiling counters report missing tools as caveats" {758    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);759    defer arena_state.deinit();760    const allocator = arena_state.allocator();761    const lane = try plan(allocator, .{}, "zig-out/profiling/run/workloads/w");762    const row = try summarize(allocator, lane, 0, "missing-stderr.txt", false);763    try std.testing.expectEqualStrings("tool_missing", row.state);764    try std.testing.expectEqualStrings("tool_unavailable", row.caveat_kind.?);765}

1pub const counters = runtime.counters;