mozpower.rst (3193B)
1 :mod:`mozpower` --- Power-usage testing 2 ======================================= 3 4 Mozpower provides an interface through which power usage measurements 5 can be done on any OS and CPU combination (auto-detected) that has 6 been implemented within the module. It provides 2 methods to start 7 and stop the measurement gathering as well as methods to get the 8 result that can also be formatted into a perfherder data blob. 9 10 Basic Usage 11 ----------- 12 13 Although multiple classes exist within the mozpower module, 14 the only one that should be used is MozPower which is accessible 15 from the top-level of the module. It handles which subclasses 16 should be used depending on the detected OS and CPU combination. 17 18 .. code-block:: python 19 20 from mozpower import MozPower 21 22 mp = MozPower( 23 ipg_measure_duration=600, 24 sampling_rate=1000, 25 output_file_path='tempdir/dataprefix' 26 ) 27 mp.initialize_power_measurements() 28 29 # Run test TEST_NAME 30 31 mp.finalize_power_measurements( 32 test_name=TEST_NAME, 33 output_dir_path=env['MOZ_UPLOAD_DIR'] 34 ) 35 36 # Get complete PERFHERDER_DATA 37 perfherder_data = mp.get_full_perfherder_data('raptor') 38 39 All the possible known errors that can occur are also provided 40 at the top-level of the module. 41 42 .. code-block:: python 43 44 from mozpower import MozPower, IPGExecutableMissingError, OsCpuComboMissingError 45 46 try: 47 mp = MozPower(ipg_measure_duration=600, sampling_rate=1000) 48 except IPGExecutableMissingError as e: 49 pass 50 except OsCpuComboMissingError as e: 51 pass 52 53 54 .. automodule:: mozpower 55 56 .. _MozPower: 57 58 MozPower Interface 59 ------------------ 60 61 The following class provides a basic interface to interact with the 62 power measurement tools that have been implemented. The tool used 63 to measure power depends on the OS and CPU combination, i.e. Intel-based 64 MacOS machines would use Intel Power Gadget, while ARM64-based Windows 65 machines would use the native Windows tool powercfg. 66 67 MozPower 68 ```````` 69 70 .. autoclass:: mozpower.MozPower 71 72 Measurement methods 73 +++++++++++++++++++ 74 .. automethod:: MozPower.initialize_power_measurements(self, **kwargs) 75 .. automethod:: MozPower.finalize_power_measurements(self, **kwargs) 76 77 Informational methods 78 +++++++++++++++++++++ 79 .. automethod:: MozPower.get_perfherder_data(self) 80 .. automethod:: MozPower.get_full_perfherder_data(self, framework, lowerisbetter=True, alertthreshold=2.0) 81 82 IPGEmptyFileError 83 ````````````````` 84 .. autoexception:: mozpower.IPGEmptyFileError 85 86 IPGExecutableMissingError 87 ````````````````````````` 88 .. autoexception:: mozpower.IPGExecutableMissingError 89 90 IPGMissingOutputFileError 91 ````````````````````````` 92 .. autoexception:: mozpower.IPGMissingOutputFileError 93 94 IPGTimeoutError 95 ``````````````` 96 .. autoexception:: mozpower.IPGTimeoutError 97 98 IPGUnknownValueTypeError 99 ```````````````````````` 100 .. autoexception:: mozpower.IPGUnknownValueTypeError 101 102 MissingProcessorInfoError 103 ````````````````````````` 104 .. autoexception:: mozpower.MissingProcessorInfoError 105 106 OsCpuComboMissingError 107 `````````````````````` 108 .. autoexception:: mozpower.OsCpuComboMissingError 109 110 PlatformUnsupportedError 111 ```````````````````````` 112 .. autoexception:: mozpower.PlatformUnsupportedError