testing/mozbase/docs/mozpower.rst

   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