tiny.profiling.cycle

1const std = @import("std");2const pretty_usage = @import("pretty_usage");3const sys = @import("sys");45const analyze = @import("analyze/root.zig");6const baseline = @import("baseline.zig");7const catalog = @import("catalog.zig");8const driver = @import("driver/root.zig");9const execute = @import("execute.zig");10const host = @import("host/root.zig");11const perturbation = @import("perturbation.zig");12const record = @import("record.zig");1314pub const run_id_prefix = "cycle";15pub const default_step_baseline = "cycle";16pub const default_binary_baseline = "cycle-binary";17pub const default_mixed_baseline = "cycle-mixed";1819pub const Options = struct {20    suite: catalog.Suite = .smoke,21    filters: []const []const u8 = &.{},22    output_dir: []const u8 = record.default_output_dir,23    baseline_name: []const u8 = default_binary_baseline,24    keep: usize = 7,25    threshold_percent: f64 = 10,26    top: usize = 10,27    stop_on_failure: bool = false,28    host_lanes: host.Options = .{},29    execution_scope: execute.Scope = .binary,30    warmup_repeat: u32 = 0,31    measure_repeat: u32 = 1,32    interleave_seed: ?u64 = null,33    capture_control: perturbation.Options = .{},34    forwarded: []const []const u8 = &.{},35};3637pub fn defaultBaselineName(scope: execute.Scope) []const u8 {38    return switch (scope) {39        .step => default_step_baseline,40        .binary => default_binary_baseline,41        .mixed => default_mixed_baseline,42    };43}4445pub fn run(46    memory: driver.Memory,47    process_io: std.Io,48    environ_map: ?*const sys.process.Environ.Map,49    options: Options,50) !u8 {51    const allocator = memory.command;52    if (options.host_lanes.requiresDirect()) return error.DirectLaneInCycle;53    const stderr_terminal = pretty_usage.Terminal.stderr(allocator, .{});54    const previous = resolvePrevious(allocator, options.baseline_name);55    if (previous == null) {56        try stderr_terminal.writeTextFmt("profile cycle: no baseline named {s}; this cycle records the first one\n", .{options.baseline_name});57    }5859    const run_id = try record.prefixedRunId(allocator, process_io, run_id_prefix);60    const outcome = try driver.executeRun(memory, process_io, environ_map, .{61        .selection = .{ .suite = options.suite, .filters = options.filters },62        .run_id = run_id,63        .output_dir = options.output_dir,64        .forwarded = options.forwarded,65        .continue_on_failure = !options.stop_on_failure,66        .host_lanes = options.host_lanes,67        .execution_scope = options.execution_scope,68        .warmup_repeat = options.warmup_repeat,69        .measure_repeat = options.measure_repeat,70        .interleave_seed = options.interleave_seed,71        .capture_control = options.capture_control,72    });7374    const candidate = try analyze.loadRun(allocator, outcome.paths.root);75    const baseline_run: ?analyze.Run = if (previous) |ref|76        analyze.loadRun(allocator, ref.root) catch |err| blk: {77            try stderr_terminal.writeTextFmt("profile cycle: baseline {s} unreadable ({s}); analyzing without a baseline\n", .{ ref.run_id, @errorName(err) });78            break :blk null;79        }80    else81        null;8283    const analyze_options = analyze.Options{84        .input = outcome.paths.root,85        .top = options.top,86        .regression_threshold_percent = options.threshold_percent,87    };88    try writeAnalysisArtifacts(allocator, outcome.paths.root, candidate, baseline_run, analyze_options);89    try analyze.writeText(allocator, pretty_usage.Terminal.stdout(allocator, .{}), candidate, baseline_run, analyze_options);9091    const entry = try baseline.save(allocator, options.baseline_name, outcome.paths.root);92    try stderr_terminal.writeTextFmt("profile cycle: baseline {s} -> {s}\n", .{ entry.name, entry.run.run_id });9394    const pruned = try pruneRuns(allocator, options.output_dir, options.keep);95    for (pruned) |name| {96        try stderr_terminal.writeTextFmt("profile cycle: pruned run {s}\n", .{name});97    }9899    return outcome.exit_code;100}101102fn resolvePrevious(allocator: std.mem.Allocator, baseline_name: []const u8) ?baseline.RunRef {103    return baseline.resolveRun(allocator, baseline_name) catch null;104}105106fn writeAnalysisArtifacts(107    allocator: std.mem.Allocator,108    run_root: []const u8,109    candidate: analyze.Run,110    baseline_run: ?analyze.Run,111    options: analyze.Options,112) !void {113    const json_path = try std.fs.path.join(allocator, &.{ run_root, "analysis.json" });114    var json_file = try sys.fs.createFile(json_path, .{ .truncate = true });115    defer json_file.close(sys.fs.debugIo());116    var json_buffer: [64 * 1024]u8 = undefined;117    var json_writer = json_file.writer(sys.fs.debugIo(), &json_buffer);118    try analyze.writeJson(allocator, &json_writer.interface, candidate, baseline_run, options);119    try json_writer.interface.flush();120121    const text_path = try std.fs.path.join(allocator, &.{ run_root, "analysis.md" });122    const text_file = try sys.fs.createFile(text_path, .{ .truncate = true });123    defer sys.fs.closeHandle(text_file);124    try analyze.writeText(allocator, pretty_usage.Terminal.init(allocator, text_file, .{}), candidate, baseline_run, options);125}126127fn pruneRuns(allocator: std.mem.Allocator, output_dir: []const u8, keep: usize) ![]const []const u8 {128    const entries = sys.fs.listDirAlloc(allocator, output_dir) catch |err| switch (err) {129        error.FileNotFound => return &.{},130        else => |actual| return actual,131    };132    var names: std.ArrayList([]const u8) = .empty;133    for (entries) |entry| {134        if (entry.kind != .directory) continue;135        if (!isCycleRun(entry.name)) continue;136        try names.append(allocator, try allocator.dupe(u8, entry.name));137    }138    const doomed = try pruneSelection(allocator, names.items, keep);139    for (doomed) |name| {140        const path = try std.fs.path.join(allocator, &.{ output_dir, name });141        try sys.fs.deleteTree(path);142    }143    return doomed;144}145146fn run_name_descending(_: void, left: []const u8, right: []const u8) bool {147    return std.mem.order(u8, left, right) == .gt;148}149150fn pruneSelection(allocator: std.mem.Allocator, names: []const []const u8, keep: usize) ![]const []const u8 {151    const kept_count = @max(keep, 1);152    if (names.len <= kept_count) return &.{};153    const sorted = try allocator.dupe([]const u8, names);154    std.mem.sort([]const u8, sorted, {}, run_name_descending);155    return sorted[kept_count..];156}157158fn isCycleRun(name: []const u8) bool {159    if (!std.mem.startsWith(u8, name, run_id_prefix)) return false;160    if (name.len == run_id_prefix.len) return false;161    return name[run_id_prefix.len] == '-';162}163164test "profiling cycle prune keeps the newest runs" {165    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);166    defer arena_state.deinit();167    const allocator = arena_state.allocator();168    const names = [_][]const u8{169        "cycle-1700000000003-ccc",170        "cycle-1700000000001-aaa",171        "cycle-1700000000002-bbb",172    };173    const doomed = try pruneSelection(allocator, &names, 2);174    try std.testing.expectEqual(@as(usize, 1), doomed.len);175    try std.testing.expectEqualStrings("cycle-1700000000001-aaa", doomed[0]);176}177178test "profiling cycle prune never deletes the last kept run" {179    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);180    defer arena_state.deinit();181    const allocator = arena_state.allocator();182    const names = [_][]const u8{"cycle-1700000000001-aaa"};183    try std.testing.expectEqual(@as(usize, 0), (try pruneSelection(allocator, &names, 0)).len);184    try std.testing.expectEqual(@as(usize, 0), (try pruneSelection(allocator, &names, 7)).len);185}186187test "profiling cycle only prunes cycle-prefixed run directories" {188    try std.testing.expect(isCycleRun("cycle-1700000000001-aaa"));189    try std.testing.expect(!isCycleRun("cycle"));190    try std.testing.expect(!isCycleRun("cyclex-1700000000001"));191    try std.testing.expect(!isCycleRun("run-1700000000001-aaa"));192    try std.testing.expect(!isCycleRun("baselines"));193}194195test "profiling cycle rejects timing-perturbing direct lanes" {196    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);197    defer arena_state.deinit();198    const allocator = arena_state.allocator();199    const memory = driver.Memory{ .command = allocator, .workload = allocator };200    try std.testing.expectError(201        error.DirectLaneInCycle,202        run(memory, std.Options.debug_io, null, .{ .host_lanes = .{ .dhat = .{} } }),203    );204    try std.testing.expectError(205        error.DirectLaneInCycle,206        run(memory, std.Options.debug_io, null, .{ .host_lanes = .{ .offcpu = .{} } }),207    );208}

1pub const cycle = @import("cycle.zig");