Profiler

Module for profiling executables within a project.

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

Bases: object

Class for profiling a build within a project.

Parameters:
class CustomLogger(logger, extra=None, merge_extra=False)

Bases: LoggerAdapter

Custom logger to add build and executable prefixes to log messages.

process(msg, kwargs)

Process the logging message and keyword arguments passed in to a logging call to insert contextual information. You can either manipulate the message itself, the keyword args or both. Return the message and kwargs modified (or not) to suit your needs.

Normally, you’ll only need to override this one method in a LoggerAdapter subclass for your specific needs.

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, max_number_of_executables=1, 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]

Runs 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.

Return type:

tuple[bool, str]

Should contain perf record file. :type working_directory: str

Returns:

error code and perf script output file name

Return type:

tuple[int,str]

Parameters:

  • filename (str)

  • working_directory (str)

save_stats()

Save collected statistics to a file. Merges with previous build statistics.

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

get_record_filename(executable: str) → str

Gets perf record output file name.

Parameters:

executable (str)

Return type:

str

get_archive_filename(executable: str) → str

Gets perf archive file name.

Parameters:

executable (str)

Return type:

str

get_script_filename(executable: str) → str

Gets perf script file name.

Parameters:

executable (str)

Return type:

str