tiny.profiling.capture.tracy

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

1const std = @import("std");2const capture = @import("capture");3const sys = @import("sys");45const host = @import("../root.zig").host;67const fs_io = sys.fs.debugIo();89pub const kind = "tracy_trace";10pub const tool = "lib/tracy";1112pub const Options = struct {13    enabled: bool,14    exit_code: i64,15    capture_path: []const u8,16    summary_path: []const u8,17};1819pub fn appendCapture(20    allocator: std.mem.Allocator,21    captures: []const host.Capture,22    options: Options,23) ![]const host.Capture {24    if (!options.enabled or options.exit_code != 0) return captures;25    const integrity = capture.tracy.parseSummaryFile(26        allocator,27        options.summary_path,28    ) catch |err| switch (err) {29        error.OutOfMemory => return err,30        else => return try appendRow(allocator, captures, invalidCapture(options)),31    };32    return try appendRow(allocator, captures, captureForIntegrity(options, integrity));33}3435fn appendRow(36    allocator: std.mem.Allocator,37    captures: []const host.Capture,38    row: host.Capture,39) ![]const host.Capture {40    const result = try allocator.alloc(host.Capture, captures.len + 1);41    @memcpy(result[0..captures.len], captures);42    result[captures.len] = row;43    return result;44}4546fn captureForIntegrity(options: Options, integrity: capture.tracy.Integrity) host.Capture {47    const complete = std.mem.eql(u8, integrity.status, "complete");48    return .{49        .kind = kind,50        .tool = tool,51        .scope = host.direct_scope,52        .capture_path = options.capture_path,53        .summary_path = options.summary_path,54        .state = "summary_written",55        .caveat_kind = if (complete) null else integrity.status,56        .caveat_message = if (complete) null else integrity.message,57    };58}5960fn invalidCapture(options: Options) host.Capture {61    return .{62        .kind = kind,63        .tool = tool,64        .scope = host.direct_scope,65        .capture_path = options.capture_path,66        .summary_path = options.summary_path,67        .state = "summary_invalid",68        .caveat_kind = "invalid_trace_summary",69        .caveat_message = "Tracy summary does not contain valid capture integrity evidence",70    };71}7273fn testIntegrity(status: []const u8, message: ?[]const u8) capture.tracy.Integrity {74    return .{75        .status = status,76        .action = if (message == null) "none" else "inspect_trace_transport",77        .message = message,78        .event_count = 3,79        .sequenced_event_count = 3,80        .unsequenced_event_count = 0,81        .first_sequence = 1,82        .last_sequence = 3,83        .sequence_gap_count = if (message == null) 0 else 1,84        .missing_sequence_event_count = if (message == null) 0 else 1,85        .sequence_regression_count = 0,86        .start_event_count = 1,87        .stop_event_count = 1,88        .start_sequence = 1,89        .stop_sequence = 3,90        .unbalanced_event_count = 0,91    };92}9394test "tracy trace capture maps complete and partial canonical integrity" {95    const options: Options = .{96        .enabled = true,97        .exit_code = 0,98        .capture_path = "bench.tracy.jsonl",99        .summary_path = "bench.tracy.summary.jsonl",100    };101    const complete = captureForIntegrity(options, testIntegrity("complete", null));102    try std.testing.expectEqualStrings("summary_written", complete.state);103    try std.testing.expect(complete.caveat_kind == null);104    try std.testing.expect(complete.caveat_message == null);105    try std.testing.expectEqualStrings(host.direct_scope, complete.scope);106107    const message = "Tracy event sequence has gaps; treat the summary as partial evidence";108    const partial = captureForIntegrity(options, testIntegrity("sequence_gaps", message));109    try std.testing.expectEqualStrings("sequence_gaps", partial.caveat_kind.?);110    try std.testing.expectEqualStrings(message, partial.caveat_message.?);111}112113test "tracy trace capture appends an offline integrity summary" {114    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);115    defer arena_state.deinit();116    const allocator = arena_state.allocator();117    var tmp = std.testing.tmpDir(.{});118    defer tmp.cleanup();119    const text =120        "{\"kind\":\"summary\",\"capture_integrity\":{" ++121        "\"method\":\"tracy_event_sequence_and_lifecycle_v1\"," ++122        "\"status\":\"sequence_gaps\",\"action\":\"inspect_trace_transport\"," ++123        "\"message\":\"partial trace\",\"event_count\":3," ++124        "\"sequenced_event_count\":3,\"unsequenced_event_count\":0," ++125        "\"first_sequence\":1,\"last_sequence\":4,\"sequence_gap_count\":1," ++126        "\"missing_sequence_event_count\":1,\"sequence_regression_count\":0," ++127        "\"start_event_count\":1,\"stop_event_count\":1," ++128        "\"start_sequence\":1,\"stop_sequence\":4," ++129        "\"unbalanced_event_count\":0}}\n";130    try tmp.dir.writeFile(fs_io, .{ .sub_path = "summary.jsonl", .data = text });131    const root = try tmp.dir.realPathFileAlloc(fs_io, ".", allocator);132    const summary_path = try std.fs.path.join(allocator, &.{ root, "summary.jsonl" });133    const rows = try appendCapture(allocator, &.{}, .{134        .enabled = true,135        .exit_code = 0,136        .capture_path = "trace.jsonl",137        .summary_path = summary_path,138    });139    try std.testing.expectEqual(@as(usize, 1), rows.len);140    try std.testing.expectEqualStrings("summary_written", rows[0].state);141    try std.testing.expectEqualStrings("sequence_gaps", rows[0].caveat_kind.?);142    try std.testing.expectEqualStrings("partial trace", rows[0].caveat_message.?);143}144145test "tracy trace capture marks invalid summaries and skips unsuccessful capture" {146    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);147    defer arena_state.deinit();148    const allocator = arena_state.allocator();149    var tmp = std.testing.tmpDir(.{});150    defer tmp.cleanup();151    try tmp.dir.writeFile(fs_io, .{ .sub_path = "invalid.jsonl", .data = "{}\n" });152    const root = try tmp.dir.realPathFileAlloc(fs_io, ".", allocator);153    const path = try std.fs.path.join(allocator, &.{ root, "invalid.jsonl" });154    const options: Options = .{155        .enabled = true,156        .exit_code = 0,157        .capture_path = "trace.jsonl",158        .summary_path = path,159    };160    const invalid = try appendCapture(allocator, &.{}, options);161    try std.testing.expectEqualStrings("summary_invalid", invalid[0].state);162    try std.testing.expectEqualStrings("invalid_trace_summary", invalid[0].caveat_kind.?);163164    var failed = options;165    failed.exit_code = 1;166    try std.testing.expectEqual(@as(usize, 0), (try appendCapture(allocator, &.{}, failed)).len);167    var disabled = options;168    disabled.enabled = false;169    try std.testing.expectEqual(@as(usize, 0), (try appendCapture(allocator, &.{}, disabled)).len);170}