tiny.profiling.question
Defined in tiny.profiling.
API (8)
Actions
Public operations.
Types and contracts
Public types and contracts.
Values and defaults
Public values and defaults.
Source
Source: src/profiling/question.zig
zig
const std = @import("std");const pretty = @import("pretty");const catalog = @import("catalog.zig");const pretty_json = pretty.json;pub const schema = "tiny.profiling.question-route/v1";pub const Kind = enum { regression, latency, rss, allocation, hotspot, blocked, energy, history, build, pub fn parse(value: []const u8) ?Kind { return std.meta.stringToEnum(Kind, value); }};pub const Options = struct { kind: Kind, workload: ?[]const u8 = null, plan: ?[]const u8 = null, baseline: ?[]const u8 = null, run_id: ?[]const u8 = null,};pub const Command = struct { cwd: ?[]const u8 = null, argv: []const []const u8,};pub const Route = struct { kind: Kind, owner: []const u8, evidence: []const u8, capture: Command, followups: []const Command, caveat: []const u8, placeholders: []const []const u8,};pub fn route( allocator: std.mem.Allocator, options: Options,) !Route { try validateOptions(options); if (options.workload) |name| { if (catalog.find(name) == null) return error.UnknownProfilingWorkload; } return switch (options.kind) { .regression => try experimentRoute(allocator, options), .latency => try runRoute( allocator, options, "ordinary repeated wall-clock process observations", &.{ "--execution-scope", "binary", "--warmup-repeat", "3", "--measure-repeat", "15" }, "wall-clock distributions remain observational until compared with a compatible baseline or paired experiment", false, ), .rss => try runRoute( allocator, options, "per-process wait4 maximum resident set size observations", &.{ "--execution-scope", "binary", "--warmup-repeat", "1", "--measure-repeat", "15" }, "max RSS is a process high-water mark and does not identify retaining owners", false, ), .allocation => try runRoute( allocator, options, "in-process allocation trace counts, bytes, lifetimes, and scopes", &.{ "--execution-scope", "binary", "--warmup-repeat", "1", "--measure-repeat", "5", "--trace-allocations" }, "allocation tracing can perturb the workload; retained every-execution summaries expose that lane explicitly", true, ), .hotspot => try runRoute( allocator, options, "perf sampled instruction-pointer attribution with a minimum support floor", &.{ "--execution-scope", "binary", "--sampled", "--sampled-min-samples", "1000" }, "unsupported sampling permissions or too few samples must remain unsupported rather than inferred", false, ), .blocked => try runRoute( allocator, options, "off-CPU blocked-time attribution", &.{ "--execution-scope", "binary", "--offcpu", "--offcpu-mode", "time" }, "off-CPU attribution requires the configured host tracing privileges and records tool support", false, ), .energy => try runRoute( allocator, options, "repeated system-wide hardware energy-domain joules and watts", &.{ "--execution-scope", "binary", "--energy", "--counter-repeat", "5" }, "energy is system-wide and must be interpreted with host-state and variability evidence", false, ), .history => try historyRoute(allocator, options), .build => try iterationRoute(allocator, options), };}pub fn writeJson( out: *pretty_json.Writer, value: Route,) !void { try out.beginObject(); try field(out, "schema", schema); try field(out, "question", @tagName(value.kind)); try field(out, "owner", value.owner); try field(out, "evidence", value.evidence); try out.objectField("capture"); try writeCommand(out, value.capture); try out.objectField("followups"); try out.beginArray(); for (value.followups) |command| try writeCommand(out, command); try out.endArray(); try field(out, "caveat", value.caveat); try out.objectField("placeholders"); try out.write(value.placeholders); try out.endObject();}fn experimentRoute( allocator: std.mem.Allocator, options: Options,) !Route { const plan = options.plan orelse "<experiment-plan.json>"; return .{ .kind = .regression, .owner = "profile-experiment", .evidence = "resettable paired baseline/candidate observations with runner-owned fixed evaluation N and a supported verdict", .capture = .{ .argv = try planArguments( allocator, "profile-experiment", plan, options.run_id, ), }, .followups = &.{}, .caveat = "the typed plan must own variant identity, reset, oracle, metric, and practical effect", .placeholders = if (options.plan == null) &.{"experiment-plan.json"} else &.{}, };}fn iterationRoute( allocator: std.mem.Allocator, options: Options,) !Route { const plan = options.plan orelse "<iteration-plan.json>"; return .{ .kind = .build, .owner = "profile-iteration", .evidence = "one resident semantic edit/revert lane checked against an isolated clean build", .capture = .{ .argv = try planArguments( allocator, "profile-iteration", plan, options.run_id, ), }, .followups = &.{}, .caveat = "duration fields are observational; deterministic test counts, semantic digests, clean equivalence, and exact revert are the gate", .placeholders = if (options.plan == null) &.{"iteration-plan.json"} else &.{}, };}fn historyRoute( allocator: std.mem.Allocator, options: Options,) !Route { const workload = options.workload orelse "<workload>"; const followups = try allocator.alloc(Command, 1); followups[0] = .{ .cwd = "analysis", .argv = try duplicateArguments( allocator, &.{ "uv", "run", "perf", "plot", workload }, ), }; return .{ .kind = .history, .owner = "analysis perf", .evidence = "catalog-derived benchmark measurements at sampled commits on one host", .capture = .{ .cwd = "analysis", .argv = try duplicateArguments( allocator, &.{ "uv", "run", "perf", "sweep", workload }, ), }, .followups = followups, .caveat = "historical points from different hosts do not mix; current specs come from the profiling catalog and only historical eras are overridden", .placeholders = if (options.workload == null) &.{"workload"} else &.{}, };}fn runRoute( allocator: std.mem.Allocator, options: Options, evidence: []const u8, flags: []const []const u8, caveat: []const u8, memory_followup: bool,) !Route { const workload = options.workload orelse "<workload>"; const run_id = options.run_id orelse "<run-id>"; var capture: std.ArrayList([]const u8) = .empty; try capture.appendSlice( allocator, &.{ "zig", "build", "profile-run", "--", "--workload", workload, "--run-id", run_id, }, ); try capture.appendSlice(allocator, flags); var followups: std.ArrayList(Command) = .empty; const run_path = try std.fmt.allocPrint( allocator, "zig-out/profiling/{s}", .{run_id}, ); if (memory_followup) { try followups.append(allocator, .{ .argv = try duplicateArguments( allocator, &.{ "zig", "build", "profile-memory", "--", run_path, }, ), }); } if (!memory_followup or options.baseline != null) { var analyze: std.ArrayList([]const u8) = .empty; try analyze.appendSlice( allocator, &.{ "zig", "build", "profile-analyze", "--", run_path, }, ); if (options.baseline) |baseline| { try analyze.appendSlice( allocator, &.{ "--baseline", baseline }, ); } try followups.append(allocator, .{ .argv = try analyze.toOwnedSlice(allocator), }); } var placeholders: std.ArrayList([]const u8) = .empty; if (options.workload == null) { try placeholders.append(allocator, "workload"); } if (options.run_id == null) { try placeholders.append(allocator, "run-id"); } return .{ .kind = options.kind, .owner = "profile-run", .evidence = evidence, .capture = .{ .argv = try capture.toOwnedSlice(allocator), }, .followups = try followups.toOwnedSlice(allocator), .caveat = caveat, .placeholders = try placeholders.toOwnedSlice(allocator), };}fn validateOptions(options: Options) !void { switch (options.kind) { .regression, .build => { if (options.workload != null or options.baseline != null) { return error.IncompatibleProfilingQuestionInput; } }, .history => { if (options.plan != null or options.baseline != null or options.run_id != null) { return error.IncompatibleProfilingQuestionInput; } }, .latency, .rss, .allocation, .hotspot, .blocked, .energy, => if (options.plan != null) { return error.IncompatibleProfilingQuestionInput; }, }}fn planArguments( allocator: std.mem.Allocator, step: []const u8, plan: []const u8, run_id: ?[]const u8,) ![]const []const u8 { var arguments: std.ArrayList([]const u8) = .empty; try arguments.appendSlice( allocator, &.{ "zig", "build", step, "--", plan }, ); if (run_id) |value| { try arguments.appendSlice( allocator, &.{ "--run-id", value }, ); } return try arguments.toOwnedSlice(allocator);}fn duplicateArguments( allocator: std.mem.Allocator, arguments: []const []const u8,) ![]const []const u8 { const result = try allocator.alloc([]const u8, arguments.len); @memcpy(result, arguments); return result;}fn writeCommand( out: *pretty_json.Writer, command: Command,) !void { try out.beginObject(); try field(out, "cwd", command.cwd); try out.objectField("argv"); try out.write(command.argv); try out.endObject();}fn field( out: *pretty_json.Writer, name: []const u8, value: anytype,) !void { try out.objectField(name); try out.write(value);}test "profiling questions route to existing evidence owners" { var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena_state.deinit(); const allocator = arena_state.allocator(); const cases = [_]struct { kind: Kind, owner: []const u8, needle: []const u8, }{ .{ .kind = .regression, .owner = "profile-experiment", .needle = "profile-experiment" }, .{ .kind = .latency, .owner = "profile-run", .needle = "--measure-repeat" }, .{ .kind = .rss, .owner = "profile-run", .needle = "--measure-repeat" }, .{ .kind = .allocation, .owner = "profile-run", .needle = "--trace-allocations" }, .{ .kind = .hotspot, .owner = "profile-run", .needle = "--sampled" }, .{ .kind = .blocked, .owner = "profile-run", .needle = "--offcpu" }, .{ .kind = .energy, .owner = "profile-run", .needle = "--energy" }, .{ .kind = .history, .owner = "analysis perf", .needle = "sweep" }, .{ .kind = .build, .owner = "profile-iteration", .needle = "profile-iteration" }, }; for (cases) |case| { const result = try route(allocator, .{ .kind = case.kind }); try std.testing.expectEqualStrings(case.owner, result.owner); var found = false; for (result.capture.argv) |argument| { if (std.mem.eql(u8, argument, case.needle)) found = true; } try std.testing.expect(found); }}test "profiling question workloads must belong to the catalog" { try std.testing.expectError( error.UnknownProfilingWorkload, route(std.testing.allocator, .{ .kind = .latency, .workload = "missing", }), );}test "profiling questions reject silently ignored inputs" { try std.testing.expectError( error.IncompatibleProfilingQuestionInput, route(std.testing.allocator, .{ .kind = .history, .plan = "ignored.json", }), ); var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena_state.deinit(); const result = try route(arena_state.allocator(), .{ .kind = .build, .plan = "iteration.json", .run_id = "build-check", }); try std.testing.expectEqualStrings( "build-check", result.capture.argv[result.capture.argv.len - 1], );}Source: src/profiling/root.zig:38
zig
pub const question = @import("question.zig");Audit
| Definitions | 9 |
|---|---|
| Public names | 9 |
| Members | 23 |
| Version | 26.7.0 |
| Revision | daab053ee433 |