`mozpower` — Power-usage testing

Mozpower provides an interface through which power usage measurements can be done on any OS and CPU combination (auto-detected) that has been implemented within the module. It provides 2 methods to start and stop the measurement gathering as well as methods to get the result that can also be formatted into a perfherder data blob.

Basic Usage

Although multiple classes exist within the mozpower module, the only one that should be used is MozPower which is accessible from the top-level of the module. It handles which subclasses should be used depending on the detected OS and CPU combination.

from mozpower import MozPower

mp = MozPower(
    ipg_measure_duration=600,
    sampling_rate=1000,
    output_file_path='tempdir/dataprefix'
)
mp.initialize_power_measurements()

# Run test TEST_NAME

mp.finalize_power_measurements(
    test_name=TEST_NAME,
    output_dir_path=env['MOZ_UPLOAD_DIR']
)

# Get complete PERFHERDER_DATA
perfherder_data = mp.get_full_perfherder_data('raptor')

All the possible known errors that can occur are also provided at the top-level of the module.

from mozpower import MozPower, IPGExecutableMissingError, OsCpuComboMissingError

try:
    mp = MozPower(ipg_measure_duration=600, sampling_rate=1000)
except IPGExecutableMissingError as e:
    pass
except OsCpuComboMissingError as e:
    pass

MozPower Interface

The following class provides a basic interface to interact with the power measurement tools that have been implemented. The tool used to measure power depends on the OS and CPU combination, i.e. Intel-based MacOS machines would use Intel Power Gadget, while ARM64-based Windows machines would use the native Windows tool powercfg.

MozPower

class mozpower.MozPower(android=False, logger_name='mozpower', output_file_path='power-testing', **kwargs)

MozPower provides an OS and CPU independent interface for initializing, finalizing, and gathering power measurement data from OS+CPU combo-dependent measurement classes. The combo is detected automatically, and the correct class is instantiated based on the OSCPU_COMBOS list. If it cannot be found, an OsCpuComboMissingError will be raised.

If a newly added power measurer does not have the required functions initialize_power_measurements, finalize_power_measurements, or get_perfherder_data, then a NotImplementedError will be raised.

Android power measurements are currently not supported by this module.

from mozpower import MozPower

mp = MozPower(output_file_path='dir/power-testing')

mp.initialize_power_measurements()
# Run test...
mp.finalize_power_measurements(test_name='raptor-test-name')

perfherder_data = mp.get_perfherder_data()

Measurement methods

MozPower.initialize_power_measurements(self, **kwargs)

Starts the power measurements by calling the power measurer’s initialize_power_measurements function.

Parameters:: kwargs (dict) – keyword arguments for power measurer initialization function if they are needed.

MozPower.finalize_power_measurements(self, **kwargs)

Stops the power measurements by calling the power measurer’s finalize_power_measurements function.

Parameters:: kwargs (dict) – keyword arguments for power measurer finalization function if they are needed.

Informational methods

MozPower.get_perfherder_data(self)

Returns the partial perfherder data output produced by the measurer. For a complete perfherder data blob, see get_full_perfherder_data.

Returns:: dict

MozPower.get_full_perfherder_data(self, framework, lowerisbetter=True, alertthreshold=2.0)

Returns a list of complete perfherder data blobs compiled from the partial perfherder data blob returned from the measurer. Each key entry (measurement type) in the partial perfherder data is parsed into its own suite within a single perfherder data blob.

For example, a partial perfherder data blob such as:

{
    'utilization': {<perfherder_data>},
    'power-usage': {<perfherder_data>}
}

would produce two suites within a single perfherder data blobs - one for utilization, and one for power-usage.

Note that the ‘values’ entry must exist, otherwise the measurement type is skipped. Furthermore, if ‘name’, ‘unit’, or ‘type’ is missing we default to:

{
    'name': 'mozpower',
    'unit': 'mWh',
    'type': 'power'
}

Subtests produced for each sub-suite (measurement type), have the naming pattern: <measurement_type>-<measured_name>

Utilization of cpu would have the following name: ‘utilization-cpu’ Power-usage for cpu has the following name: ‘power-usage-cpu’

Parameters:

framework (str) – name of the framework being tested, i.e. ‘raptor’.
lowerisbetter (bool) – if set to true, low values are better than high ones.
alertthreshold (float) – determines the crossing threshold at which an alert is generated.

Returns:

dict

IPGEmptyFileError

exception mozpower.IPGEmptyFileError: IPGEmptyFileError is raised when a file path is given to _clean_ipg_file and it exists but it is empty (contains no results to clean).

IPGExecutableMissingError

exception mozpower.IPGExecutableMissingError: IPGExecutableMissingError is raised when we cannot find the executable for Intel Power Gadget at the expected location.

IPGMissingOutputFileError

exception mozpower.IPGMissingOutputFileError: IPGMissingOutputFile is raised when a file path is given to _clean_ipg_file but it does not exist or cannot be found at the expected location.

IPGTimeoutError

exception mozpower.IPGTimeoutError: IPGTimeoutError is raised when we cannot stop Intel Power Gadget from running. One possble cause of this is not calling stop_ipg through a finalize_power_measurements call. The other possiblity is that IPG failed to stop.

IPGUnknownValueTypeError

exception mozpower.IPGUnknownValueTypeError: IPGUnknownValueTypeError is raised when a value within a given results file (that was cleaned) cannot be converted to its column’s expected data type.

MissingProcessorInfoError

exception mozpower.MissingProcessorInfoError: MissingProcessorInfoError is raised when we cannot find the processor information on the machine. This is raised when the file is missing (mentioned in the error message) or if an exception occurs when we try to gather the information from the file.

OsCpuComboMissingError

exception mozpower.OsCpuComboMissingError: OsCpuComboMissingError is raised when we cannot find a class responsible for the OS, and CPU combination that was detected.

PlatformUnsupportedError

exception mozpower.PlatformUnsupportedError: PlatformUnsupportedError is raised when we cannot find an expected IPG path for the OS being tested.

mozpower — Power-usage testing