Profiler

Module for profiling executables within a project.

class Profiler(project: Project, build: Build, ui: IUI = NULL_UI)

Bases: object

Class for profiling a build within a project.

Parameters:
cleanup()

Cleanup generated files from profiling.

profile_all(working_directory: str = '', test_executable: bool = True, execution_time: bool = True, stat_collect: bool = True, record_collect: bool = True, events: list[str] | None = None) → list[str]

Run profiling on every executable.

If build.executables is empty, finds executables in build.build_path.

Parameters:

  • working_directory (str) – absolute path to set working directory.

  • test_executable (bool) – Run an executable smoke test if True. Saves result in self.stats[EXECUTABLE][Stats.EXECUTABLE_RUN_SUCCESS].

  • execution_time (bool) – run an executable time measurement if True. Saves result in self.stats[EXECUTABLE] dictionary with keys Stats.REAL_TIME, Stats.USER_TIME, Stats.KERNEL_TIME.

  • stat_collect (bool) – collect perfomance counters if True. Saves result in self.stats[EXECUTABLE][Stats.PERF_STAT].

  • record_collect (bool) – collect counters using sampling if True. Saves perf.data into self.get_record_filename() file in the working directory.

  • events (list[str] | None)

Returns:

List of executables for which all profiler steps were completed successfully.

Return type:

list[str]

execution_time(executable: str, working_directory: str) → bool

Measure execution time: real, user, kernel.

Parameters:

  • executable (str) – relative to build_path path to executable

  • working_directory (str) – absolute path to set working directory.

Returns:

False if non-zero error code is returned. Otherwise True

Return type:

bool

test_executable(executable: str, working_directory: str) → bool

Checks if executable runs and returns no errors.

Updates self.stats[EXECUTABLE] dictionary with Stats.EXECUTABLE_RUN_SUCCESS key.

Parameters:

  • executable (str) – relative to build_path path to executable

  • working_directory (str) – absolute path to set working directory.

Returns:

True if the executable return 0. False if can’t run the executable or non-zero error code is returned.

Return type:

bool

perf_stat_collect(executable: str, working_directory: str, options: str = '-ddd') → bool

Collect performance statistics using perf stat.

Updates self.stats[EXECUTABLE] dictionary with Stats.PERF_STAT key.

Parameters:

  • executable (str) – relative to build_path path to executable

  • options (str) – perf stat additional options. Default “-ddd”

  • working_directory (str) – absolute path to set working directory.

Returns:

False if perf stat return non-zero error code. Otherwise True

Return type:

bool

perf_record_collect(executable: str, working_directory: str, options: str = '-g -F 1000', events: list[str] | None = None) → bool

Collect performance records using perf record.

Saves perf.data with archive of object files into self.get_record_filename() and self.get_record_filename().tar.bz2 file in the working directory.

Parameters:

  • executable (str) – relative to build_path path to executable

  • options (str) – perf record additional options. Default: “-g -F 1000”

  • working_directory (str) – absolute path to set working directory.

  • events (list[str]) – perf events to record. Default: [cycles, cache-misses, branch-misses]

Returns:

False if can’t collect samples. Otherwise True

Return type:

bool

perf_script(filename: str, working_directory: str) → tuple[bool, str]

Run perf script on the provided perf data file and saves to filename.txt.

Parameters:

  • filename (str) – the name of perf record file.

  • working_directory (str) – absolute path to set working directory. Should contain perf record file.

Returns:

error code and perf script output file name

Return type:

tuple[int,str]

save_stats(stats_file_format: StatsFileFormat = StatsFileFormat.JSON)

Save collected statistics to files.

Merges with previous build statistics.

Always saves a pickle file <project name>.pkl. Additionally saves human-readable statistics in JSON or YAML format. In the human-readable file the raw perf stat CSV output is converted to a list of dictionaries.

Structure: {“build1”:{“executable1”: ProfileStats, “executable2”: …}, “build2”: …}

Parameters:

stats_file_format (StatsFileFormat) – format of the additional human-readable stats file (JSON by default).

get_record_filename(executable: str) → str

Get perf record output file name.

Parameters:

executable (str)

Return type:

str

get_archive_filename(executable: str) → str

Get perf archive file name.

Parameters:

executable (str)

Return type:

str

get_script_filename(executable: str) → str

Get perf script file name.

Parameters:

executable (str)

Return type:

str