DFTracer Comparator

Namespace: dftracer::utils::utilities::composites::dft::comparator

source

struct CollapsedMetrics

Per-(category, operation) collapsed metrics aggregated across processes and time windows.

Within each time window: max across processes. Across windows: mean +/- stdev of per-window max values.

Public Members

AggregationMetrics merged

DDSketch merged across all windows for percentile queries.

double count_mean

Mean of per-window max event counts.

double dur_mean_of_means

Mean of per-window mean durations.

double dur_stdev_of_means

Stdev of per-window mean durations.

double size_mean_of_means

Mean of per-window mean sizes.

double size_stdev_of_means

Stdev of per-window mean sizes.

double xfer_mean

Mean of per-window max transfer sizes.

double xfer_stdev

Stdev of per-window max transfer sizes.

double bw_mean

Mean of per-window max bandwidths.

double bw_stdev

Stdev of per-window max bandwidths.

std::size_t num_windows

Number of time windows contributing to these statistics.

source

struct ColumnWidths

Dynamically computed column widths for aligned table output.

Public Members

int left

Left column (metric/node name).

int baseline

Baseline value column.

int variant

Variant value column.

int delta

Delta column.

int change

Percentage change column.

source

struct ComparisonConfig

Top-level configuration for the comparison pipeline.

Constructed from CLI arguments via from_cli() or loaded from a JSON file via from_json_file(). Call resolve() after construction to propagate defaults down the node tree.

Public Functions

void resolve()

Resolve inheritance: compose queries and propagate defaults down the node tree. Must be called before using the config.

Public Members

std::string baseline

Baseline trace file or directory path.

std::string variant

Variant trace file or directory path.

ComparisonDefaults defaults

Default settings inherited by all nodes.

std::vector<ComparisonNode> nodes

Hierarchical comparison tree (top-level nodes).

std::vector<std::string> output_paths

Output file paths (CLI only, detect format by extension).

std::string format

Output format: “table” or “json”.

bool no_color

Disable ANSI color in table output.

bool compact

Collapse nodes with only negligible changes to a single line.

std::size_t executor_threads

Number of parallel threads (0 = auto-detect).

std::size_t checkpoint_size

Checkpoint size for index building (0 = default).

std::string baseline_index_dir

Directory for baseline .dftindex store (empty = co-located).

std::string variant_index_dir

Directory for variant .dftindex store (empty = co-located).

bool force_rebuild

Force rebuild of existing indexes.

Public Static Functions

static std::optional<ComparisonConfig> from_json_file(const std::string &path, std::string &error)

Parse a JSON config file. Returns nullopt and sets error on failure.

static ComparisonConfig from_cli(const std::string &baseline, const std::string &variant, const std::string &query, const std::string &group_by_str)

Build config from CLI arguments (quick mode without JSON). Creates a single root node with the given query and group-by.

static std::optional<ComparisonConfig> from_preset(const std::string &preset, const std::string &baseline, const std::string &variant)

Build a preset comparison config. Returns nullopt for unknown presets. Supported presets: “dlio”.

source

struct ComparisonDefaults

Default settings inherited by all comparison nodes unless overridden.

Public Members

std::vector<std::string> metrics

Metric groups to compare (count, duration, size, transfer_size, bandwidth).

std::vector<double> percentiles

Percentiles to compute from DDSketch (e.g. p50, p95, p99).

double threshold_pct

Hide changes below this percentage in the output.

double time_interval_ms

Time bucket width in milliseconds for aggregation windows.

std::string sort_by

Sort order for groups: “regression” sorts worst regressions first.

source

struct ComparisonNode

A node in the hierarchical comparison tree.

Each node carries a query that is AND’d with its parent’s query, and optional per-node overrides for metrics, percentiles, and threshold. Children inherit from their parent unless they override.

Public Members

std::string name

Display name for this node (e.g. “POSIX I/O”, “reads”).

std::string query

Additional query filter, AND’d with the parent’s composed query.

std::vector<std::string> group_by

Extra group-by keys beyond the default (cat, name).

std::optional<std::vector<std::string>> metrics

Per-node metric override (nullopt = inherit from parent).

std::optional<std::vector<double>> percentiles

Per-node percentile override (nullopt = inherit from parent).

std::optional<double> threshold_pct

Per-node threshold override (nullopt = inherit from parent).

std::optional<std::string> sort_by

Per-node sort override (nullopt = inherit from parent).

std::vector<ComparisonNode> children

Child nodes forming the comparison hierarchy.

std::string composed_query

Full query including all ancestor queries, populated by resolve().

std::vector<std::string> resolved_metrics

Resolved metrics after inheritance, populated by resolve().

std::vector<double> resolved_percentiles

Resolved percentiles after inheritance, populated by resolve().

double resolved_threshold_pct

Resolved threshold after inheritance, populated by resolve().

std::string resolved_sort_by

Resolved sort order after inheritance, populated by resolve().

source

struct ComparisonOutput

Top-level output of the comparison pipeline.

Public Functions

common::arrow::ArrowExportResult to_arrow() const

Flatten the tree into a single Arrow record batch.

Columns: node_path, metric_group, metric_name, baseline, variant, baseline_stdev, variant_stdev, delta, pct_change, cohens_d, significance, is_regression. Rows with all-zero values are skipped.

Public Members

std::string baseline_path

Baseline file or directory path.

std::string variant_path

Variant file or directory path.

std::size_t baseline_file_count

Number of baseline trace files processed.

std::size_t variant_file_count

Number of variant trace files processed.

TraceMetadata baseline_meta

Metadata extracted from baseline traces.

TraceMetadata variant_meta

Metadata extracted from variant traces.

std::vector<NodeResult> nodes

Top-level comparison tree results.

double execution_time_ms

Total pipeline execution time in milliseconds.

source

class ComparisonUtility : public dftracer::utils::utilities::Utility<ComparisonUtilityInput, Result<ComparisonUtilityOutput>>

Joins baseline and variant aggregation outputs, builds the hierarchical comparison tree (root -> categories -> operations), and computes deltas with Cohen’s d significance classification.

Public Functions

coro::CoroTask<Result<ComparisonUtilityOutput>> process(const ComparisonUtilityInput &input) override

Run the comparison pipeline.

source

struct ComparisonUtilityInput

Input to ComparisonUtility::process().

Public Members

std::vector<ComparisonVisitorPair> visitors

Visitor pairs, one per flattened node in the tree.

ComparisonNode root_node

Root node of the comparison tree (for hierarchy reconstruction).

std::size_t baseline_file_count

Number of baseline trace files (for metadata).

std::size_t variant_file_count

Number of variant trace files (for metadata).

source

struct ComparisonUtilityOutput

Success payload from ComparisonUtility::process(); failures are reported via Result<ComparisonUtilityOutput>.

Public Members

NodeResult result

Hierarchical comparison result tree.

source

struct ComparisonVisitorPair

Paired baseline/variant aggregation outputs for a single comparison node.

Public Members

EventAggregatorOutput baseline

Aggregation output for the baseline run.

EventAggregatorOutput variant

Aggregation output for the variant run.

ComparisonNode node

Resolved config node for this visitor.

source

struct FormatterOptions

Options controlling the visual appearance of rendered output.

Public Members

bool use_color

Enable ANSI color escape codes in table output.

bool use_unicode

Use Unicode box-drawing characters for tree branches.

bool compact

Collapse nodes where all metrics are negligible to a single “(no

change)” line.

int top_regressions

Show top N regressions footer after the tree (0 = disabled).

source

struct GroupComparison

Comparison of all metrics for a single (category, operation) group.

Public Members

std::string label

Group label (e.g. “POSIX/read”, empty for summary).

bool baseline_present

Whether this group exists in the baseline.

bool variant_present

Whether this group exists in the variant.

std::vector<MetricComparison> metrics

Per-metric comparisons for this group.

double worst_pct_change

Worst percentage change across all metrics (for regression sorting).

source

struct MetricComparison

Comparison of a single metric between baseline and variant.

Public Members

std::string metric_name

Metric name (e.g. “count”, “dur_mean”, “dur_p50”, “size”).

double baseline_value

Baseline value (mean across time windows).

double variant_value

Variant value (mean across time windows).

double baseline_stdev

Baseline standard deviation across time windows (0 if N<=1).

double variant_stdev

Variant standard deviation across time windows.

double delta

Absolute difference (variant - baseline).

double pct_change

Percentage change (e.g. 15.3 for +15.3%).

double cohens_d

Cohen’s d effect size.

Significance significance

Classified significance level.

bool is_regression

True if performance got worse (higher duration, lower bandwidth).

source

struct NodeResult

Result for a single node in the comparison tree.

Public Members

std::string name

Node name from the config.

std::string composed_query

Full composed query for this node.

std::vector<std::string> group_by

Group-by keys used.

std::vector<GroupComparison> groups

Per-group comparisons (empty if summary-only).

GroupComparison summary

Aggregate summary across all groups (always present).

std::vector<NodeResult> children

Child node results.

source

struct TraceMetadata

Metadata extracted from a trace run (baseline or variant).

Public Members

std::size_t file_count

Distinct data files accessed (unique fhash); falls back to trace-file count when no fhash is present.

std::size_t proc_file_count

Per-process file accesses (distinct pid + fhash). Equals file_count for file-per-process workloads; larger when processes share files.

std::size_t process_count

Number of unique process IDs.

std::size_t thread_count

Number of unique thread IDs.

double total_bytes

Total bytes transferred (I/O operations only).

double total_io_time_us

Sum of all event durations in microseconds.

double makespan_us

Wall-clock makespan in microseconds (max ts - min ts).

source

class TreeTableFormatter

Renders ComparisonOutput as an ASCII tree table or JSON.

The tree table uses dynamic column alignment with UTF-8 display width awareness. Nodes are rendered hierarchically with tree branch characters, and metrics are shown as leaves under each node.

Public Functions

explicit TreeTableFormatter(FormatterOptions options = {})

Construct a formatter with the given display options.

void render(std::FILE *out, const ComparisonOutput &output) const

Render the comparison output as a tree table to a FILE stream.

std::string render_json(const ComparisonOutput &output) const

Render the comparison output as a JSON string.

Free Functions

source

std::vector<MetricComparison> dftracer::utils::utilities::composites::dft::comparator::build_metadata_metrics(const TraceMetadata &baseline, const TraceMetadata &variant)

Build MetricComparison entries for trace-level metadata (file_count, process_count, thread_count, makespan, total_bytes, total_io_time). Intended for injection into the root SUMMARY.

source

Significance dftracer::utils::utilities::composites::dft::comparator::classify_significance(double cohens_d)

Classify a Cohen’s d value into a Significance level.

source

CollapsedMap dftracer::utils::utilities::composites::dft::comparator::collapse_by_group(const AggregationMap &aggregations)

Collapse aggregation output by grouping on (category, name) and merging across time windows.

source

std::vector<MetricComparison> dftracer::utils::utilities::composites::dft::comparator::compare_metrics(const CollapsedMetrics &baseline, const CollapsedMetrics &variant, const std::vector<std::string> &metrics, const std::vector<double> &percentiles)

Build MetricComparison entries for a pair of CollapsedMetrics, comparing the requested metrics and percentiles.

source

double dftracer::utils::utilities::composites::dft::comparator::compute_cohens_d(const MetricStats &baseline, std::uint64_t n_base, const MetricStats &variant, std::uint64_t n_var)

Compute Cohen’s d effect size from two MetricStats with sample counts.

source

TraceMetadata dftracer::utils::utilities::composites::dft::comparator::extract_metadata(const AggregationMap &aggregations, std::size_t file_count)

Extract trace metadata (unique PIDs, TIDs, makespan) from raw aggregation output.

source

bool dftracer::utils::utilities::composites::dft::comparator::is_atomic_metric(const std::string &name)

Metric-name classification, shared by the Arrow exporter and the tree formatter so the atomic-name set cannot drift between them. Atomic names are standalone metrics (e.g. “count”); others split into group + leaf, e.g. “dur_mean” -> group “dur”, leaf “mean”.

source

std::string dftracer::utils::utilities::composites::dft::comparator::metric_group(const std::string &name)

source

std::string dftracer::utils::utilities::composites::dft::comparator::metric_leaf(const std::string &name)

source

const char *dftracer::utils::utilities::composites::dft::comparator::significance_to_string(Significance s)

Human-readable name of an effect-size bucket (e.g. “MEDIUM”).