tiny.profiling.help

1const std = @import("std");2const pretty_usage = @import("pretty_usage");3const sys = @import("sys");45const Allocator = std.mem.Allocator;67const profile_options = [_]pretty_usage.Option{8    .{ .flags = "--suite smoke|standard|all", .summary = "Select a workload suite." },9    .{ .flags = "--workload name", .summary = "Select a workload by catalog name or build step." },10    .{ .flags = "--json", .summary = "Render machine-readable JSON." },11};1213const run_options = [_]pretty_usage.Option{14    .{ .flags = "--suite smoke|standard|all", .summary = "Select a workload suite." },15    .{ .flags = "--workload name", .summary = "Select a workload by catalog name or build step." },16    .{ .flags = "--dry-run", .summary = "Print the plan without running child build steps." },17    .{ .flags = "--continue-on-failure", .summary = "Continue after a workload exits nonzero." },18    .{ .flags = "--output-dir path", .summary = "Write run artifacts under a profiling output directory." },19    .{ .flags = "--run-id id", .summary = "Use a stable run artifact directory name." },20    .{ .flags = "--save-baseline name", .summary = "Save the completed run as a named baseline." },21    .{ .flags = "--execution-scope binary|step|mixed", .summary = "Measure binaries, whole build steps, or whole steps except for workloads that require direct child configuration." },22    .{23        .flags = "--warmup-repeat count",24        .summary = "Run the prepared process 0-100 times before measurement; " ++25            "warmups are unprofiled and retain only the last output artifacts.",26    },27    .{28        .flags = "--measure-repeat count",29        .summary = "Repeat the ordinary measured process 1-100 times. Every " ++30            "measured execution retains stdout, stderr, benchmark JSONL, and " ++31            "its structured receipt. Values above one conflict with host, " ++32            "Tracy, or causal lanes.",33    },34    .{ .flags = "--bench-filter fragment", .summary = "Run only suite benchmarks whose name contains the fragment." },35    .{36        .flags = "--interleave-seed seed",37        .summary = "Randomly interleave ordinary process repetitions with a " ++38            "reproducible seed; requires 2+ workloads, --measure-repeat > 1, " ++39            "and --continue-on-failure.",40    },41    .{42        .flags = "--capture-control-repeat count",43        .summary = "Measure active capture perturbation with 1-50 binary-scope " ++44            "same-build control/capture pairs; requires a capture lane.",45    },46    .{47        .flags = "--capture-control-seed seed",48        .summary = "Set the reproducible within-pair order seed for capture controls.",49    },50    .{ .flags = "--counters", .summary = "Wrap the selected execution scope in perf stat and summarize counters." },51    .{52        .flags = "--energy",53        .summary = "Capture repeated system hardware-domain joules and watts; " ++54            "requires a supported and permitted perf energy PMU.",55    },56    .{57        .flags = "--counter-events list",58        .summary = "Perf stat expression; defaults to page faults plus strongly " ++59            "grouped IPC and branch-miss inputs; implies --counters.",60    },61    .{ .flags = "--counter-group-size count", .summary = "Limit events per separate perf stat workload execution; 0 keeps one execution; implies --counters." },62    .{63        .flags = "--counter-repeat count",64        .summary = "Retain and summarize repeated perf stat workload executions; " ++65            "defaults to 3; implies --counters.",66    },67    .{ .flags = "--sampled", .summary = "Wrap the selected execution scope in perf record and summarize hot symbols." },68    .{69        .flags = "--sampled-frequency hz",70        .summary = "Set the perf sampling frequency; implies --sampled.",71    },72    .{73        .flags = "--sampled-min-samples count",74        .summary = "Require this many samples before attribution is supported; implies --sampled.",75    },76    .{ .flags = "--coverage", .summary = "Run benchmark binaries under kcov for source-line coverage; defaults the build to Debug." },77    .{ .flags = "--causal", .summary = "Start the Coz experiment worker inside each benchmark for causal speedup evidence." },78    .{ .flags = "--causal-min-time seconds", .summary = "Stretch each selected benchmark to at least this wall time so experiment rounds complete; implies --causal." },79    .{ .flags = "--causal-filter fragment", .summary = "Run only suite benchmarks whose name contains the fragment; implies --causal." },80    .{ .flags = "--dhat", .summary = "Build each workload's benchmark binary and run it under valgrind DHAT for heap evidence." },81    .{ .flags = "--tracy", .summary = "Build direct benchmark binaries with Tracy and retain raw and summary JSONL traces." },82    .{ .flags = "--trace-allocations", .summary = "Force lib/bench allocation trace events for every selected workload." },83    .{ .flags = "--offcpu", .summary = "Build each workload's benchmark binary and attach an offcputime sidecar for blocked-time evidence." },84    .{ .flags = "--offcpu-mode time|stacks", .summary = "Blocked-time flavor: offcputime durations or bpftrace stack counts; implies --offcpu." },85    .{ .flags = "--offcpu-tool name", .summary = "Off-CPU profiler executable; implies --offcpu (defaults offcputime-bpfcc or bpftrace by mode)." },86    .{ .flags = "--json", .summary = "Print the selected plan as JSON without running child build steps." },87};8889const compare_options = [_]pretty_usage.Option{90    .{ .flags = "--output path, -o path", .summary = "Write comparison JSON to a file." },91};9293const experiment_options = [_]pretty_usage.Option{94    .{ .flags = "--output-dir path", .summary = "Write experiment artifacts under a profiling output directory." },95    .{ .flags = "--run-id id", .summary = "Use a stable experiment artifact directory name." },96    .{ .flags = "--dry-run", .summary = "Validate and print the typed plan without building or executing variants." },97    .{ .flags = "--json", .summary = "Print the validated plan for a dry run or the completed receipt." },98};99100const iteration_options = [_]pretty_usage.Option{101    .{ .flags = "--output-dir path", .summary = "Write iteration artifacts under a profiling output directory." },102    .{ .flags = "--run-id id", .summary = "Use a stable iteration artifact directory name." },103    .{ .flags = "--dry-run", .summary = "Validate and print the typed iteration plan without editing or building." },104    .{ .flags = "--json", .summary = "Print the validated plan for a dry run or the completed receipt." },105};106107const question_options = [_]pretty_usage.Option{108    .{ .flags = "regression|latency|rss|allocation|hotspot|blocked|energy|history|build", .summary = "Select the performance question." },109    .{ .flags = "--workload name", .summary = "Bind a catalog workload for run and history questions." },110    .{ .flags = "--plan path", .summary = "Bind a typed experiment or iteration plan." },111    .{ .flags = "--baseline name|path", .summary = "Add a compatible analysis baseline to run-based routes." },112    .{ .flags = "--run-id id", .summary = "Bind the capture and follow-up artifact path." },113    .{ .flags = "--json", .summary = "Render the typed route as JSON." },114};115116const analyze_options = [_]pretty_usage.Option{117    .{ .flags = "--baseline name|path", .summary = "Compare against a saved baseline, manifest, results stream, or run directory." },118    .{ .flags = "--threshold percent", .summary = "Report wall, metric, memory, and priority regressions above a percent threshold." },119    .{ .flags = "--top count", .summary = "Limit slowest and memory-heavy rankings." },120    .{ .flags = "--json", .summary = "Render machine-readable JSON." },121};122123const memory_options = [_]pretty_usage.Option{124    .{ .flags = "--top count", .summary = "Limit workload, memory metric, and scope rows." },125    .{ .flags = "--min-bytes count", .summary = "Hide memtrace scopes below this retained/live byte floor." },126    .{ .flags = "--json", .summary = "Render machine-readable JSON." },127};128129const cycle_options = [_]pretty_usage.Option{130    .{ .flags = "--suite smoke|standard|all", .summary = "Select the workload suite for this cycle." },131    .{ .flags = "--workload name", .summary = "Cycle only the named workloads instead of a whole suite." },132    .{ .flags = "--baseline name", .summary = "Rolling baseline pointer to compare against and rotate." },133    .{ .flags = "--output-dir path", .summary = "Write cycle run artifacts under a profiling output directory." },134    .{ .flags = "--keep count", .summary = "Retain at most this many cycle run directories." },135    .{ .flags = "--threshold percent", .summary = "Report regressions above a percent threshold." },136    .{ .flags = "--top count", .summary = "Limit ranking rows in the written analysis." },137    .{ .flags = "--execution-scope binary|step|mixed", .summary = "Measure binaries, whole build steps, or direct-configured workloads within an otherwise whole-step cycle; cycle defaults to binary." },138    .{139        .flags = "--warmup-repeat count",140        .summary = "Run each prepared process 0-100 unprofiled times before measurement.",141    },142    .{143        .flags = "--measure-repeat count",144        .summary = "Repeat each ordinary measured process 1-100 times. Every " ++145            "measured execution retains stdout, stderr, benchmark JSONL, and " ++146            "its structured receipt. Values above one conflict with host " ++147            "capture lanes.",148    },149    .{150        .flags = "--interleave-seed seed",151        .summary = "Randomly interleave ordinary process repetitions with a " ++152            "reproducible seed; requires 2+ workloads, --measure-repeat > 1, " ++153            "and completion-on-failure.",154    },155    .{156        .flags = "--capture-control-repeat count",157        .summary = "Measure active host-capture perturbation with 1-50 " ++158            "binary-scope same-build control/capture pairs.",159    },160    .{161        .flags = "--capture-control-seed seed",162        .summary = "Set the reproducible within-pair order seed for capture controls.",163    },164    .{ .flags = "--counters", .summary = "Wrap the selected execution scope in perf stat and summarize counters." },165    .{166        .flags = "--energy",167        .summary = "Capture repeated system hardware-domain joules and watts; " ++168            "requires a supported and permitted perf energy PMU.",169    },170    .{171        .flags = "--counter-events list",172        .summary = "Perf stat expression; defaults to page faults plus strongly " ++173            "grouped IPC and branch-miss inputs; implies --counters.",174    },175    .{ .flags = "--counter-group-size count", .summary = "Limit events per separate perf stat workload execution; 0 keeps one execution; implies --counters." },176    .{177        .flags = "--counter-repeat count",178        .summary = "Retain and summarize repeated perf stat workload executions; " ++179            "defaults to 3; implies --counters.",180    },181    .{ .flags = "--sampled", .summary = "Wrap the selected execution scope in perf record and summarize hot symbols." },182    .{183        .flags = "--sampled-frequency hz",184        .summary = "Set the perf sampling frequency; implies --sampled.",185    },186    .{187        .flags = "--sampled-min-samples count",188        .summary = "Require this many samples before attribution is supported; implies --sampled.",189    },190    .{ .flags = "--stop-on-failure", .summary = "Stop at the first failing workload instead of completing the suite." },191};192193const baseline_options = [_]pretty_usage.Option{194    .{ .flags = "save name run", .summary = "Save a run directory, manifest, or results stream as a named baseline." },195    .{ .flags = "show name|path", .summary = "Resolve and print a baseline or run reference." },196    .{ .flags = "list", .summary = "List saved profiling baselines." },197    .{ .flags = "delete name", .summary = "Delete a saved profiling baseline." },198    .{ .flags = "prune --keep-last N [--older-than 14d] [--dry-run]", .summary = "Prune saved baseline pointers by age or count." },199};200201const check_options = [_]pretty_usage.Option{202    .{ .flags = "package", .summary = "Check root registration and profiling steps for this package." },203    .{ .flags = "--all", .summary = "Check root registration and profiling steps for every package." },204    .{ .flags = "--json", .summary = "Render machine-readable JSON." },205};206207const code_layout_options = [_]pretty_usage.Option{208    .{ .flags = "--json", .summary = "Render machine-readable JSON." },209};210211const web_options = [_]pretty_usage.Option{212    .{ .flags = "--profiling-dir path", .summary = "Read run artifacts from a profiling output directory." },213    .{ .flags = "--output path", .summary = "Write the static site to this directory instead of <profiling-dir>/site." },214    .{ .flags = "--serve", .summary = "Serve the site over HTTP and regenerate when new runs land." },215    .{ .flags = "--port n", .summary = "Listen on this port in serve mode (default 8787)." },216    .{ .flags = "--address host", .summary = "Bind this address in serve mode (default 127.0.0.1)." },217    .{ .flags = "--json", .summary = "Render machine-readable JSON." },218};219220const plan_help = pretty_usage.Help{221    .name = "tiny-profile-tests plan",222    .summary = "Print the selected monorepo profiling plan.",223    .usages = &.{224        .{ .command = .{ .name = "tiny-profile-tests", .args = "plan [options]" } },225        .{ .build = .{ .step = "profile-plan", .args = "[options]" } },226    },227    .options = profile_options[0..],228};229230const catalog_help = pretty_usage.Help{231    .name = "tiny-profile-tests catalog",232    .summary = "Print every registered profiling workload.",233    .usages = &.{234        .{ .command = .{ .name = "tiny-profile-tests", .args = "catalog [--json]" } },235        .{ .build = .{ .step = "profile-catalog", .args = "[--json]" } },236    },237    .options = &.{238        .{ .flags = "--json", .summary = "Render machine-readable JSON." },239    },240};241242const run_help = pretty_usage.Help{243    .name = "tiny-profile-tests run",244    .summary = "Run selected profiling workloads through package-owned build steps.",245    .usages = &.{246        .{ .command = .{ .name = "tiny-profile-tests", .args = "run [options] [-- forwarded args]" } },247        .{ .build = .{ .step = "profile-run", .args = "[options] [-- forwarded args]" } },248    },249    .options = run_options[0..],250};251252const compare_help = pretty_usage.Help{253    .name = "tiny-profile-tests compare",254    .summary = "Compare two profile summary artifacts using lib/capture evidence.",255    .usages = &.{256        .{ .command = .{ .name = "tiny-profile-tests", .args = "compare BASE SUMMARY [--output path]" } },257        .{ .build = .{ .step = "profile-compare", .args = "BASE SUMMARY [--output path]" } },258    },259    .options = compare_options[0..],260};261262const experiment_help = pretty_usage.Help{263    .name = "tiny-profile-tests experiment",264    .summary = "Run a resettable paired baseline/candidate experiment from a typed plan.",265    .usages = &.{266        .{ .command = .{ .name = "tiny-profile-tests", .args = "experiment PLAN [options]" } },267        .{ .build = .{ .step = "profile-experiment", .args = "PLAN [options]" } },268    },269    .options = experiment_options[0..],270};271272const iteration_help = pretty_usage.Help{273    .name = "tiny-profile-tests iteration",274    .summary = "Probe resident edit iteration against an isolated clean build.",275    .usages = &.{276        .{ .command = .{ .name = "tiny-profile-tests", .args = "iteration PLAN [options]" } },277        .{ .build = .{ .step = "profile-iteration", .args = "PLAN [options]" } },278    },279    .options = iteration_options[0..],280};281282const question_help = pretty_usage.Help{283    .name = "tiny-profile-tests question",284    .summary = "Route a performance question to the owning evidence collector.",285    .usages = &.{286        .{ .command = .{ .name = "tiny-profile-tests", .args = "question KIND [options]" } },287        .{ .build = .{ .step = "profile-question", .args = "KIND [options]" } },288    },289    .options = question_options[0..],290};291292const analyze_help = pretty_usage.Help{293    .name = "tiny-profile-tests analyze",294    .summary = "Analyze a captured monorepo profiling run.",295    .usages = &.{296        .{ .command = .{ .name = "tiny-profile-tests", .args = "analyze RUN [options]" } },297        .{ .build = .{ .step = "profile-analyze", .args = "RUN [options]" } },298    },299    .options = analyze_options[0..],300};301302const memory_help = pretty_usage.Help{303    .name = "tiny-profile-tests memory",304    .summary = "Report memory accountability for a captured profiling run.",305    .usages = &.{306        .{ .command = .{ .name = "tiny-profile-tests", .args = "memory RUN [options]" } },307        .{ .build = .{ .step = "profile-memory", .args = "RUN [options]" } },308    },309    .options = memory_options[0..],310};311312const cycle_help = pretty_usage.Help{313    .name = "tiny-profile-tests cycle",314    .summary = "Run one rolling profiling cycle: run the suite, analyze against the previous cycle, rotate the baseline, prune old cycle runs.",315    .usages = &.{316        .{ .command = .{ .name = "tiny-profile-tests", .args = "cycle [options] [-- forwarded args]" } },317        .{ .build = .{ .step = "profile-cycle", .args = "[options] [-- forwarded args]" } },318    },319    .options = cycle_options[0..],320};321322const baseline_help = pretty_usage.Help{323    .name = "tiny-profile-tests baseline",324    .summary = "Save or resolve profiling run baselines.",325    .usages = &.{326        .{ .command = .{ .name = "tiny-profile-tests", .args = "baseline save NAME RUN" } },327        .{ .command = .{ .name = "tiny-profile-tests", .args = "baseline show NAME" } },328        .{ .command = .{ .name = "tiny-profile-tests", .args = "baseline list" } },329        .{ .command = .{ .name = "tiny-profile-tests", .args = "baseline delete NAME" } },330        .{ .command = .{ .name = "tiny-profile-tests", .args = "baseline prune --keep-last N [--older-than 14d] [--dry-run]" } },331        .{ .build = .{ .step = "profile-baseline", .args = "save NAME RUN" } },332    },333    .options = baseline_options[0..],334};335336const check_help = pretty_usage.Help{337    .name = "tiny-profile-tests check",338    .summary = "Check the static catalog against selected package profiling build steps.",339    .usages = &.{340        .{ .command = .{ .name = "tiny-profile-tests", .args = "check PACKAGE [--json]" } },341        .{ .command = .{ .name = "tiny-profile-tests", .args = "check --all [--json]" } },342        .{ .build = .{ .step = "profile-check", .args = "PACKAGE [--json]" } },343        .{ .build = .{ .step = "profile-check-all", .args = "[--json]" } },344    },345    .options = check_options[0..],346};347348const code_layout_help = pretty_usage.Help{349    .name = "tiny-profile-tests code-layout",350    .summary = "Fingerprint executable ELF sections without build metadata.",351    .usages = &.{352        .{ .command = .{ .name = "tiny-profile-tests", .args = "code-layout BINARY... [--json]" } },353        .{ .build = .{ .step = "profile-tests", .args = "code-layout BINARY... [--json]" } },354    },355    .options = code_layout_options[0..],356};357358const recovery_options = [_]pretty_usage.Option{359    .{ .flags = "--slo-ms count", .summary = "Set the approved process-cold recovery SLO." },360    .{ .flags = "--project-file label=operation:path", .summary = "Add one file to a named store projection." },361    .{ .flags = "--project-bytes label=operation:count", .summary = "Add explicit bytes to a named store projection." },362    .{ .flags = "--json", .summary = "Render machine-readable capacity evidence." },363};364365const recovery_help = pretty_usage.Help{366    .name = "tiny-profile-tests recovery",367    .summary = "Derive bounded recovery capacities and reject unsafe store growth.",368    .usages = &.{369        .{ .command = .{ .name = "tiny-profile-tests", .args = "recovery CURVES --slo-ms COUNT [options]" } },370        .{ .build = .{ .step = "profile-tests", .args = "recovery CURVES --slo-ms COUNT [options]" } },371    },372    .options = recovery_options[0..],373};374375const web_help = pretty_usage.Help{376    .name = "tiny-profile-tests web",377    .summary = "Generate the static profiling web viewer from recorded run artifacts.",378    .usages = &.{379        .{ .command = .{ .name = "tiny-profile-tests", .args = "web [options]" } },380        .{ .build = .{ .step = "profile-web", .args = "[options]" } },381    },382    .options = web_options[0..],383};384385pub const help = pretty_usage.Help{386    .name = "tiny-profile-tests",387    .summary = "Plan, run, analyze, and compare monorepo profiling workloads.",388    .usages = &.{389        .{ .command = .{ .name = "tiny-profile-tests", .args = "<command> [args]" } },390        .{ .build = .{ .step = "profile-tests", .args = "<command> [args]" } },391    },392    .groups = &.{393        .{ .title = "Profiling", .commands = &.{394            .{ .name = "plan", .summary = "Print a suite plan.", .detail = &plan_help },395            .{ .name = "catalog", .summary = "Print the registered workload catalog.", .detail = &catalog_help },396            .{ .name = "run", .summary = "Run selected workload steps.", .detail = &run_help },397            .{ .name = "experiment", .summary = "Compare two immutable variants.", .detail = &experiment_help },398            .{ .name = "iteration", .summary = "Verify one resident edit/revert lane.", .detail = &iteration_help },399            .{ .name = "question", .summary = "Route a performance question.", .detail = &question_help },400            .{ .name = "cycle", .summary = "Run a rolling baseline cycle.", .detail = &cycle_help },401            .{ .name = "analyze", .summary = "Analyze captured run artifacts.", .detail = &analyze_help },402            .{ .name = "memory", .summary = "Report memory accountability.", .detail = &memory_help },403            .{ .name = "baseline", .summary = "Save and resolve run baselines.", .detail = &baseline_help },404            .{ .name = "check", .summary = "Check catalog drift.", .detail = &check_help },405            .{ .name = "code-layout", .summary = "Fingerprint executable code layout.", .detail = &code_layout_help },406            .{ .name = "recovery", .summary = "Derive recovery capacity gates.", .detail = &recovery_help },407            .{ .name = "compare", .summary = "Compare profile summaries.", .detail = &compare_help },408            .{ .name = "web", .summary = "Generate the static web viewer.", .detail = &web_help },409        } },410    },411    .examples = &.{412        .{ .command = "zig build profile-plan -- --suite standard", .summary = "Inspect the default suite." },413        .{ .command = "zig build profile-run -- --suite smoke --save-baseline main-smoke", .summary = "Run the smoke profiling lane and save a baseline." },414        .{ .command = "zig build profile-experiment -- experiment.json", .summary = "Run a paired experiment and save its audit receipt." },415        .{ .command = "zig build profile-iteration -- iteration.json", .summary = "Verify a semantic edit, clean equivalence, and exact revert." },416        .{ .command = "zig build profile-question -- hotspot --workload gpalloc.allocator", .summary = "Select the supported hotspot collection lane." },417        .{ .command = "zig build profile-cycle", .summary = "Run one rolling smoke cycle against the previous cycle." },418        .{ .command = "zig build profile-analyze -- zig-out/profiling/run-id --baseline main-smoke", .summary = "Analyze a run against a saved baseline." },419        .{ .command = "zig build profile-run -- --workload gpalloc.allocator --trace-allocations", .summary = "Capture allocation events for a memory report." },420        .{ .command = "zig build profile-memory -- zig-out/profiling/run-id", .summary = "Summarize memory accountability for a captured run." },421        .{ .command = "zig build profile-tests -- compare base.summary.json candidate.summary.json", .summary = "Compare two captured summaries." },422        .{ .command = "zig build profile-tests -- code-layout zig-out/bin/bench --json", .summary = "Fingerprint executable code sections." },423        .{ .command = "zig build profile-web", .summary = "Generate the web viewer and print the index path." },424        .{ .command = "zig build profile-web -- --serve", .summary = "Serve the web viewer locally and refresh as runs land." },425    },426};427428pub fn writeCommandHelp(allocator: Allocator, args: []const []const u8) !u8 {429    var stdout_buffer: [8192]u8 = undefined;430    var stdout_writer = sys.stdio.stdout().writer(std.Options.debug_io, &stdout_buffer);431    defer stdout_writer.interface.flush() catch {};432    var stderr_buffer: [8192]u8 = undefined;433    var stderr_writer = sys.stdio.stderr().writer(std.Options.debug_io, &stderr_buffer);434    defer stderr_writer.interface.flush() catch {};435    return try pretty_usage.writeCommandPathHelpOrError(436        allocator,437        &stdout_writer.interface,438        &stderr_writer.interface,439        help,440        args,441        .{442            .layout = .{ .width = 88 },443            .suggestions = .{ .enabled = true },444            .parent_fallback_help = true,445        },446    );447}

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