scope_profiler.diff

CLI entry point for scope-profiler diff: compare two profiling files.

Aligns region statistics between two merged HDF5 profiling files by region name and reports the change in one metric (default: total duration), so a regression - or an improvement - between two runs (two commits, two configs, two job sizes) shows up as a single table instead of two separate inspect runs a human has to cross-reference by eye.

Attributes

Name	Description
METRICS	No description.
SORT_KEYS	No description.

Functions

Name	Description
build_check_parser	Build the parser for scope-profiler check.
build_parser	Build the argument parser for scope-profiler diff.
check_files	Print a CI regression report and return 0 for pass, 1 for failure.
check_main	Entry point for scope-profiler check.
check_rows	Return rows that violate a performance regression budget.
diff_files	Print a region-by-region comparison of two profiling HDF5 files.
diff_rows	Build one comparison row per region present in either result set.
main	Entry point for scope-profiler diff.
print_diff_table	Print the aligned region comparison table built by :func:diff_rows.

METRICSattributemodule attribute#

View source

METRICS = (
  'gpu_total',
  'gpu_avg',
  'total',
  'avg',
  'min',
  'max',
  'p50',
  'p95',
  'p99',
  'imbalance',
  'calls'
)

Show moreShow less

SORT_KEYSattributemodule attribute#

View source

SORT_KEYS = ('delta', 'pct', 'name')

build_check_parserfunction#

View source

def build_check_parser() -> argparse.ArgumentParser

Build the parser for scope-profiler check.

build_parserfunction#

View source

def build_parser() -> argparse.ArgumentParser

Build the argument parser for scope-profiler diff.

check_filesfunction#

View source

def check_files(file_a, file_b, max_regression: float = 0.0, include=None, exclude=None, ranks=None, metric: str = 'total', fail_on_new: bool = False, stream=None) -> int

Print a CI regression report and return 0 for pass, 1 for failure.

check_mainfunction#

View source

def check_main(argv: list | None = None)

Entry point for scope-profiler check.

check_rowsfunction#

View source

def check_rows(results_a: ProfilingResults, results_b: ProfilingResults, max_regression: float = 0.0, include=None, exclude=None, ranks=None, metric: str = 'total', fail_on_new: bool = False) -> list

Return rows that violate a performance regression budget.

max_regression is a percentage. New regions have no meaningful percentage baseline and are only failures when fail_on_new is true.

diff_filesfunction#

View source

def diff_files(file_a, file_b, include=None, exclude=None, ranks=None, metric: str = 'total', sort: str = 'delta', threshold: float | None = None, stream=None) -> None

Print a region-by-region comparison of two profiling HDF5 files.

Parameters

file_a, file_b : str or Path The “before” and “after” merged profiling files. include, exclude, ranks, metric, sort, threshold See :func:diff_rows. stream : file-like, optional Where to write (default: stdout).

diff_rowsfunction#

View source

def diff_rows(results_a: ProfilingResults, results_b: ProfilingResults, include=None, exclude=None, ranks=None, metric: str = 'total', sort: str = 'delta', threshold: float | None = None) -> list

Build one comparison row per region present in either result set.

Parameters

results_a, results_b : ProfilingResults The “before” (a) and “after” (b) runs. include, exclude : list of str or str, optional Regex patterns selecting which regions to compare, matched as in :func:~scope_profiler.summary.region_rows. ranks : list of int, optional Restrict the statistics to these ranks (default: all). metric : str, optional Which per-region statistic to compare: one of :data:METRICS (default: total). sort : str, optional One of :data:SORT_KEYS: delta and pct sort by descending magnitude of change (default: delta), name alphabetically. threshold : float, optional Drop regions whose absolute percent change is below this many percent. Regions that only appear in one file always pass, since there is no baseline to compute a percentage against.

Returns

list of dict Each entry has name, a, b (the metric’s value in each file, or None when the region is missing - or timed no calls on the selected ranks - there), delta (b - a, treating a missing side as 0) and pct (percent change, or None when a is None or 0).

mainfunction#

View source

def main(argv: list | None = None)

Entry point for scope-profiler diff.

print_diff_tablefunction#

View source

def print_diff_table(rows, metric: str = 'total', title=None, stream=None) -> None

Print the aligned region comparison table built by :func:diff_rows.