tiny.profiling.capture.memtrace

1const std = @import("std");2const memtrace = @import("memtrace");3const pretty_json = @import("pretty").json;4const sys = @import("sys");56const host = @import("../root.zig").host;78const fs_io = sys.fs.debugIo();9const max_repetition_row_bytes = 8 * 1024;10const fixture_version = std.fmt.comptimePrint(11    "{d}",12    .{memtrace.event.format_version},13);1415pub const kind = "allocation_trace";16pub const tool = "lib/memtrace";17pub const repetition_schema = "tiny.profiling.allocation-repetition/v1";1819pub const Options = struct {20    enabled: bool,21    exit_code: i64,22    capture_path: []const u8,23    summary_path: []const u8,24};2526pub const RepetitionOptions = struct {27    enabled: bool,28    exit_code: i64,29    execution_index: usize,30    capture_path: []const u8,31    repetitions_path: []const u8,32};3334const RenderedSummary = struct {35    bytes: []const u8,36    integrity: memtrace.CaptureIntegrity,37};3839pub fn appendCapture(40    allocator: std.mem.Allocator,41    captures: []const host.Capture,42    options: Options,43) ![]const host.Capture {44    if (!options.enabled or options.exit_code != 0) return captures;45    const integrity = summarize(allocator, options) catch |err| switch (err) {46        error.OutOfMemory => return err,47        error.FileNotFound => return try appendRow(48            allocator,49            captures,50            missingCapture(options),51        ),52        else => return try appendRow(allocator, captures, invalidCapture(options)),53    };54    return try appendRow(allocator, captures, captureForIntegrity(options, integrity));55}5657pub fn recordRepetition(58    allocator: std.mem.Allocator,59    options: RepetitionOptions,60) !void {61    if (!options.enabled) return;62    std.debug.assert(options.execution_index > 0);63    if (options.exit_code != 0) {64        return writeRepetition(options, "workload_failed", null);65    }66    var summary_storage: [max_repetition_row_bytes]u8 = undefined;67    const rendered = renderSummary(68        allocator,69        options.capture_path,70        &summary_storage,71    ) catch |err| switch (err) {72        error.OutOfMemory => return err,73        error.FileNotFound => return writeRepetition(options, "capture_missing", null),74        else => return writeRepetition(options, "summary_invalid", null),75    };76    try writeRepetition(options, "summary_written", rendered.bytes);77}7879fn summarize(80    allocator: std.mem.Allocator,81    options: Options,82) !memtrace.CaptureIntegrity {83    var storage: [max_repetition_row_bytes]u8 = undefined;84    const rendered = try renderSummary(allocator, options.capture_path, &storage);85    try sys.fs.writeFile(options.summary_path, rendered.bytes);86    return rendered.integrity;87}8889fn renderSummary(90    allocator: std.mem.Allocator,91    capture_path: []const u8,92    storage: *[max_repetition_row_bytes]u8,93) !RenderedSummary {94    var output = std.Io.Writer.fixed(storage);95    const integrity = try memtrace.analysis.writeSummaryJsonlFromJsonlPath(96        allocator,97        capture_path,98        &output,99        .{ .top = 0, .include_zero_live = true },100    );101    return .{102        .bytes = output.buffered(),103        .integrity = integrity,104    };105}106107fn writeRepetition(108    options: RepetitionOptions,109    state: []const u8,110    summary_bytes: ?[]const u8,111) !void {112    var storage: [max_repetition_row_bytes]u8 = undefined;113    var output = std.Io.Writer.fixed(&storage);114    var stream = pretty_json.Writer.init(&output, .minified);115    const object = try stream.object();116    try object.field("schema", repetition_schema);117    try object.field("execution_index", options.execution_index);118    try object.field("exit_code", options.exit_code);119    try object.field("state", state);120    if (summary_bytes) |bytes| {121        const summary = std.mem.trim(u8, bytes, " \t\r\n");122        std.debug.assert(std.mem.indexOfScalar(u8, summary, '\n') == null);123        try object.raw("summary", summary);124    } else {125        try object.field("summary", null);126    }127    try object.endLine();128    if (options.execution_index == 1) {129        try sys.fs.writeFile(options.repetitions_path, output.buffered());130    } else {131        try sys.fs.appendFile(options.repetitions_path, &.{output.buffered()});132    }133}134135fn appendRow(136    allocator: std.mem.Allocator,137    captures: []const host.Capture,138    row: host.Capture,139) ![]const host.Capture {140    const result = try allocator.alloc(host.Capture, captures.len + 1);141    @memcpy(result[0..captures.len], captures);142    result[captures.len] = row;143    return result;144}145146fn captureForIntegrity(147    options: Options,148    integrity: memtrace.CaptureIntegrity,149) host.Capture {150    const complete = std.mem.eql(u8, integrity.status, "complete");151    return .{152        .kind = kind,153        .tool = tool,154        .scope = host.direct_scope,155        .capture_path = options.capture_path,156        .summary_path = options.summary_path,157        .state = "summary_written",158        .caveat_kind = if (complete) null else integrity.status,159        .caveat_message = if (complete) null else integrity.message,160    };161}162163fn missingCapture(options: Options) host.Capture {164    return .{165        .kind = kind,166        .tool = tool,167        .scope = host.direct_scope,168        .capture_path = options.capture_path,169        .summary_path = options.summary_path,170        .state = "capture_missing",171        .caveat_kind = "allocation_trace_missing",172        .caveat_message = "allocation tracing was requested but produced no trace artifact",173    };174}175176fn invalidCapture(options: Options) host.Capture {177    return .{178        .kind = kind,179        .tool = tool,180        .scope = host.direct_scope,181        .capture_path = options.capture_path,182        .summary_path = options.summary_path,183        .state = "summary_invalid",184        .caveat_kind = "invalid_allocation_trace",185        .caveat_message = "allocation trace does not contain valid memtrace evidence",186    };187}188189test "allocation trace capture writes complete canonical integrity" {190    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);191    defer arena_state.deinit();192    const allocator = arena_state.allocator();193    var tmp = std.testing.tmpDir(.{});194    defer tmp.cleanup();195    const trace =196        "{\"v\":" ++ fixture_version ++ ",\"seq\":1,\"kind\":\"trace.start\"}\n" ++197        "{\"v\":" ++ fixture_version ++ ",\"seq\":2,\"kind\":\"allocator\",\"allocator_id\":0}\n" ++198        "{\"v\":" ++ fixture_version ++ ",\"seq\":3,\"kind\":\"trace.stop\"}\n";199    try tmp.dir.writeFile(fs_io, .{ .sub_path = "allocations.jsonl", .data = trace });200    const root = try tmp.dir.realPathFileAlloc(fs_io, ".", allocator);201    const capture_path = try std.fs.path.join(allocator, &.{ root, "allocations.jsonl" });202    const summary_path = try std.fs.path.join(allocator, &.{ root, "summary.jsonl" });203    const rows = try appendCapture(allocator, &.{}, .{204        .enabled = true,205        .exit_code = 0,206        .capture_path = capture_path,207        .summary_path = summary_path,208    });209    try std.testing.expectEqualStrings("summary_written", rows[0].state);210    try std.testing.expect(rows[0].caveat_kind == null);211    const summary = try sys.fs.readFileAlloc(allocator, summary_path, 64 * 1024);212    try std.testing.expect(std.mem.indexOf(u8, summary, "\"status\":\"complete\"") != null);213}214215test "allocation trace capture surfaces tail truncation and missing artifacts" {216    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);217    defer arena_state.deinit();218    const allocator = arena_state.allocator();219    var tmp = std.testing.tmpDir(.{});220    defer tmp.cleanup();221    const trace =222        "{\"v\":" ++ fixture_version ++ ",\"seq\":1,\"kind\":\"trace.start\"}\n" ++223        "{\"v\":" ++ fixture_version ++ ",\"seq\":2,\"kind\":\"allocator\",\"allocator_id\":0}\n";224    try tmp.dir.writeFile(fs_io, .{ .sub_path = "truncated.jsonl", .data = trace });225    const root = try tmp.dir.realPathFileAlloc(fs_io, ".", allocator);226    const capture_path = try std.fs.path.join(allocator, &.{ root, "truncated.jsonl" });227    const summary_path = try std.fs.path.join(allocator, &.{ root, "summary.jsonl" });228    const partial = try appendCapture(allocator, &.{}, .{229        .enabled = true,230        .exit_code = 0,231        .capture_path = capture_path,232        .summary_path = summary_path,233    });234    try std.testing.expectEqualStrings("missing_stop_event", partial[0].caveat_kind.?);235    const missing = try appendCapture(allocator, &.{}, .{236        .enabled = true,237        .exit_code = 0,238        .capture_path = "missing.jsonl",239        .summary_path = summary_path,240    });241    try std.testing.expectEqualStrings("capture_missing", missing[0].state);242}243244test "allocation trace retains every process repetition summary" {245    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);246    defer arena_state.deinit();247    const allocator = arena_state.allocator();248    var tmp = std.testing.tmpDir(.{});249    defer tmp.cleanup();250    const trace =251        "{\"v\":" ++ fixture_version ++ ",\"seq\":1,\"kind\":\"trace.start\"}\n" ++252        "{\"v\":" ++ fixture_version ++ ",\"seq\":2,\"kind\":\"allocator\",\"allocator_id\":0}\n" ++253        "{\"v\":" ++ fixture_version ++ ",\"seq\":3,\"kind\":\"trace.stop\"}\n";254    try tmp.dir.writeFile(fs_io, .{ .sub_path = "allocations.jsonl", .data = trace });255    const root = try tmp.dir.realPathFileAlloc(fs_io, ".", allocator);256    const capture_path = try std.fs.path.join(allocator, &.{ root, "allocations.jsonl" });257    const repetitions_path = try std.fs.path.join(258        allocator,259        &.{ root, "allocations.repetitions.jsonl" },260    );261    for (1..3) |execution_index| try recordRepetition(allocator, .{262        .enabled = true,263        .exit_code = 0,264        .execution_index = execution_index,265        .capture_path = capture_path,266        .repetitions_path = repetitions_path,267    });268    const rows = try sys.fs.readFileAlloc(allocator, repetitions_path, 16 * 1024);269    try std.testing.expectEqual(@as(usize, 2), std.mem.count(u8, rows, repetition_schema));270    try std.testing.expect(std.mem.indexOf(u8, rows, "\"execution_index\":1") != null);271    try std.testing.expect(std.mem.indexOf(u8, rows, "\"execution_index\":2") != null);272    try std.testing.expect(std.mem.indexOf(u8, rows, "\"resizes\":0") != null);273    try std.testing.expect(std.mem.indexOf(u8, rows, "\"remaps\":0") != null);274}275276test "allocation repetition summarization survives every allocation failure" {277    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);278    defer arena_state.deinit();279    const allocator = arena_state.allocator();280    var tmp = std.testing.tmpDir(.{});281    defer tmp.cleanup();282    const trace =283        "{\"v\":" ++ fixture_version ++ ",\"seq\":1,\"kind\":\"trace.start\"}\n" ++284        "{\"v\":" ++ fixture_version ++ ",\"seq\":2,\"kind\":\"allocator\",\"allocator_id\":0}\n" ++285        "{\"v\":" ++ fixture_version ++ ",\"seq\":3,\"kind\":\"trace.stop\"}\n";286    try tmp.dir.writeFile(fs_io, .{ .sub_path = "allocations.jsonl", .data = trace });287    const root = try tmp.dir.realPathFileAlloc(fs_io, ".", allocator);288    const capture_path = try std.fs.path.join(allocator, &.{ root, "allocations.jsonl" });289    const repetitions_path = try std.fs.path.join(allocator, &.{ root, "repetitions.jsonl" });290    try std.testing.checkAllAllocationFailures(291        std.testing.allocator,292        recordRepetition,293        .{RepetitionOptions{294            .enabled = true,295            .exit_code = 0,296            .execution_index = 1,297            .capture_path = capture_path,298            .repetitions_path = repetitions_path,299        }},300    );301}

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