tiny.profiling.analyze.model

1pub const ComparisonSupport = enum {2    supported,3    missing_optimize,4    optimize_mismatch,5    missing_host,6    os_mismatch,7    arch_mismatch,8    cpu_count_mismatch,9    hostname_mismatch,10    kernel_mismatch,11    cpu_model_mismatch,12    cpu_frequency_policy_missing,13    cpu_frequency_policy_mismatch,14    process_cpu_affinity_missing,15    process_cpu_affinity_mismatch,16    process_memory_affinity_missing,17    process_memory_affinity_mismatch,18};

1pub const ComparisonSupport = enum {2    supported,3    scope_mismatch,4    measurement_order_mismatch,5    warmup_design_mismatch,6    capture_mismatch,7    capture_perturbation_mismatch,8    perf_stat_summary_missing,9    perf_stat_events_mismatch,10    perf_stat_groups_mismatch,11    perf_stat_design_mismatch,12};

1pub const WorkloadComparison = struct {2    workload: []const u8,3    baseline_wall_ns: u64,4    candidate_wall_ns: u64,5    wall_percent_change: f64,6    baseline_wall_samples: usize = 1,7    candidate_wall_samples: usize = 1,8    baseline_wall_distribution: []const u8 = "point_estimate",9    candidate_wall_distribution: []const u8 = "point_estimate",10    wall_effect_low_percent: ?f64 = null,11    wall_effect_high_percent: ?f64 = null,12    wall_status: []const u8 = "point_regression_candidate",13    baseline_max_rss_kib: ?i64,14    candidate_max_rss_kib: ?i64,15    rss_percent_change: ?f64,16    wall_threshold_percent: f64,17    rss_threshold_percent: f64,18    kind: []const u8,19};

1pub const wall_statistic = "mean_per_execution";

1const std = @import("std");2const capture = @import("capture");3const sys = @import("sys");4const baseline = @import("../root.zig").baseline;5const catalog = @import("../root.zig").catalog;6const coz = @import("../capture/root.zig").coz;7const environment = @import("../root.zig").environment;8const host = @import("../root.zig").host;9const json = @import("../root.zig").json;10const measurement = @import("../root.zig").measurement;11const memory = @import("../root.zig").memory;12const metric = @import("../root.zig").metric;13const order = @import("../root.zig").order;14const perturbation = @import("../root.zig").perturbation;15const priority = @import("../root.zig").priority;16const reducer = @import("../root.zig").reduction;1718pub const workload_wall_statistic = measurement.wall_statistic;1920pub const Options = struct {21    input: []const u8,22    baseline_input: ?[]const u8 = null,23    json: bool = false,24    top: usize = 10,25    regression_threshold_percent: f64 = 10,26};2728pub const Workload = struct {29    name: []const u8,30    package: []const u8,31    step: []const u8,32    surface: catalog.Surface = .profile,33    command_argv: []const []const u8 = &.{},34    command_cwd: ?[]const u8 = null,35    command_identity_recorded: bool = false,36    acquisition: order.Context = .{ .blocked = .{} },37    scope: []const u8 = host.scope,38    scope_recorded: bool = false,39    causal_enabled: bool = false,40    tracy_enabled: bool = false,41    allocations_enabled: bool = false,42    profiler_configuration_recorded: bool = false,43    status: []const u8,44    exit_code: i64,45    wall_ns: u64,46    total_wall_ns: u64 = 0,47    execution_count: usize = 1,48    executions: []const measurement.Execution = &.{},49    measurement_recorded: bool = false,50    wall_distribution: ?measurement.WallDistribution = null,51    warmup_count: usize = 0,52    warmups: []const measurement.Execution = &.{},53    warmup_recorded: bool = false,54    warmup_total_wall_ns: u64 = 0,55    warmup_distribution: ?measurement.WallDistribution = null,56    warmup_stdout_path: ?[]const u8 = null,57    warmup_stderr_path: ?[]const u8 = null,58    resource_usage_source: ?sys.process.ResourceUsageSource = null,59    max_rss_kib: ?i64 = null,60    user_s: ?f64 = null,61    system_s: ?f64 = null,62    minor_page_faults: ?f64 = null,63    major_page_faults: ?f64 = null,64    voluntary_context_switches: ?f64 = null,65    involuntary_context_switches: ?f64 = null,66    result_path: ?[]const u8,67    allocation_repetitions_path: ?[]const u8 = null,68    profiler_artifacts: ?measurement.ExecutionArtifacts = null,69    benchmark_process_domain: reducer.DomainDeclaration = .{70        .benchmark_surface = false,71        .direct_execution = false,72        .host_profiler = false,73        .tracy = false,74        .causal = false,75        .allocation_trace = false,76        .capture_control = false,77    },78    benchmark_process_reduction: reducer.Result = .{ .not_applicable = .{79        .reason = .fewer_than_two_executions,80        .process_count = 0,81    } },82    metrics: []const metric.Metric = &.{},83    memory_metrics: []const memory.Metric = &.{},84    causal: []const coz.Result = &.{},85    captures: []const host.Capture = &.{},86    perf_stat: ?capture.perfstat.Summary = null,87    capture_perturbation: ?perturbation.Measurement = null,88    capture_perturbation_summary: ?perturbation.Summary = null,8990    pub fn analysisArtifacts(self: Workload) ?measurement.ExecutionArtifacts {91        if (self.executions.len == 1) {92            if (self.executions[0].artifacts) |artifacts| return artifacts;93        }94        return self.profiler_artifacts;95    }9697    pub fn structuredAnalysisState(self: Workload) []const u8 {98        if (self.profiler_artifacts != null) return "profiler_capture_receipt";99        if (self.executions.len > 1) {100            return switch (self.benchmark_process_reduction) {101                .complete => "multiple_execution_receipts_reduced",102                .not_applicable => "unavailable",103            };104        }105        if (self.executions.len == 1 and self.executions[0].artifacts != null) {106            return "single_execution_receipt";107        }108        return "unavailable";109    }110};111112pub const CounterShift = struct {113    workload: []const u8,114    event: []const u8,115    baseline_value: f64,116    candidate_value: f64,117    percent_change: f64,118    threshold_percent: f64,119    status: []const u8,120};121122pub const EnergyShift = struct {123    workload: []const u8,124    event: []const u8,125    baseline_joules: f64,126    candidate_joules: f64,127    energy_percent_change: f64,128    baseline_watts: ?f64,129    candidate_watts: ?f64,130    power_percent_change: ?f64,131    baseline_energy_range_percent: ?f64,132    candidate_energy_range_percent: ?f64,133    baseline_power_range_percent: ?f64,134    candidate_power_range_percent: ?f64,135    threshold_percent: f64,136    status: []const u8,137};138139pub const Run = struct {140    ref: baseline.RunRef,141    suite: catalog.Suite = .all,142    filters: []const []const u8 = &.{},143    selection_known: bool = false,144    git_sha: ?[]const u8 = null,145    git_dirty: ?bool = null,146    optimize: ?[]const u8 = null,147    host: environment.Host = .{},148    workloads: []const Workload = &.{},149150    pub fn ran(self: Run) usize {151        return self.workloads.len;152    }153154    pub fn passed(self: Run) usize {155        var result: usize = 0;156        for (self.workloads) |workload| {157            if (workload.exit_code == 0) result += 1;158        }159        return result;160    }161162    pub fn failed(self: Run) usize {163        return self.ran() - self.passed();164    }165166    pub fn metricCount(self: Run) usize {167        var result: usize = 0;168        for (self.workloads) |workload| result += workload.metrics.len;169        return result;170    }171172    pub fn memoryMetricCount(self: Run) usize {173        var result: usize = 0;174        for (self.workloads) |workload| result += workload.memory_metrics.len;175        return result;176    }177178    pub fn causalCount(self: Run) usize {179        var result: usize = 0;180        for (self.workloads) |workload| result += workload.causal.len;181        return result;182    }183};184185pub const ComparisonSupport = environment.ComparisonSupport;186187pub const WorkloadComparisonSupport = measurement.ComparisonSupport;188189pub const WorkloadComparisonSkip = struct {190    workload: []const u8,191    support: WorkloadComparisonSupport,192    baseline_acquisition: order.Context,193    candidate_acquisition: order.Context,194    baseline_execution_count: usize,195    candidate_execution_count: usize,196    baseline_warmup_count: usize,197    candidate_warmup_count: usize,198};199200pub const OrderEffectSupport = enum {201    supported,202    environment_mismatch,203    code_identity_missing,204    code_identity_mismatch,205    dirty_code_identity,206    cohort_mismatch,207    workload_failure,208    command_identity_missing,209    command_identity_mismatch,210    execution_scope_missing,211    execution_scope_mismatch,212    warmup_design_missing,213    warmup_design_mismatch,214    profiler_configuration_missing,215    profiler_capture_present,216    repetition_design_mismatch,217    raw_measurements_missing,218};219220pub const OrderEffectRow = struct {221    workload: []const u8,222    fixed_acquisition: order.Context,223    random_acquisition: order.Context,224    fixed_count: usize,225    random_count: usize,226    fixed_mean_ns: ?f64,227    random_mean_ns: ?f64,228    mean_percent_change: ?f64,229    effect_low_percent: ?f64,230    effect_high_percent: ?f64,231    classification: order.contrast.Classification,232};233234pub const OrderEffectStatus = enum {235    unsupported,236    insufficient_repetitions,237    no_order_effect_observed,238    order_sensitive_candidate,239};240241pub const OrderEffects = struct {242    support: OrderEffectSupport,243    environment_support: ComparisonSupport,244    fixed_run_id: []const u8,245    random_run_id: []const u8,246    fixed_is_baseline: bool,247    status: OrderEffectStatus,248    rows: []const OrderEffectRow,249};250251pub const Comparison = priority.WorkloadComparison;252253pub fn sameOptionalString(left: ?[]const u8, right: ?[]const u8) bool {254    const actual_left = left orelse return right == null;255    const actual_right = right orelse return false;256    return std.mem.eql(u8, actual_left, actual_right);257}258259pub fn sameStrings(left: []const []const u8, right: []const []const u8) bool {260    if (left.len != right.len) return false;261    for (left, right) |left_value, right_value| {262        if (!std.mem.eql(u8, left_value, right_value)) return false;263    }264    return true;265}266267pub fn workloadWallDistribution(workload: Workload) measurement.WallDistribution {268    return workload.wall_distribution orelse269        measurement.pointWallDistribution(workload.wall_ns);270}271272pub const NamedCapture = struct {273    workload: []const u8,274    capture: host.Capture,275};276277pub fn percentChange(baseline_value: u64, candidate_value: u64) ?f64 {278    if (baseline_value == 0) return null;279    const base_float: f64 = @floatFromInt(baseline_value);280    const candidate_float: f64 = @floatFromInt(candidate_value);281    return ((candidate_float - base_float) / base_float) * 100;282}283284pub fn findWorkload(workloads: []const Workload, name: []const u8) ?Workload {285    for (workloads) |workload| {286        if (std.mem.eql(u8, workload.name, name)) return workload;287    }288    return null;289}

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