docs/performance/tools_power_rapl.md

   1 # tools/power/rapl
   2
   3 `tools/power/rapl` (or `rapl` for short) is a command-line utility in
   4 the Mozilla tree that periodically reads and prints all available Intel
   5 RAPL power estimates. These are machine-wide estimates, so if you want
   6 to estimate the power consumption of a single program you should
   7 minimize other activity on the machine while measuring.
   8
   9 **Note**: The [power profiling overview](power_profiling_overview.md) is
  10 worth reading at this point if you haven't already. It may make parts
  11 of this document easier to understand.
  12
  13 ## Invocation
  14
  15 First, do a [standard build of Firefox](/setup/index.rst).
  16
  17 ### Mac
  18
  19 On Mac, `rapl` can be run as follows.
  20
  21 ```bash
  22 $OBJDIR/dist/bin/rapl
  23 ```
  24
  25 ### Linux
  26
  27 On Linux, `rapl` can be run as root, as follows.
  28
  29     sudo $OBJDIR/dist/bin/rapl
  30
  31 Alternatively, it can be run without root privileges by setting the
  32 contents of
  33 [/proc/sys/kernel/perf_event_paranoid](http://unix.stackexchange.com/questions/14227/do-i-need-root-admin-permissions-to-run-userspace-perf-tool-perf-events-ar)
  34 to 0. Note that if you do change this file, its contents may reset when
  35 the machine is next rebooted.
  36
  37 You must be running Linux kernel version 3.14 or later for `rapl` to
  38 work. Otherwise, it will fail with an error message explaining this
  39 requirement.
  40
  41 ### Windows
  42
  43 Unfortunately, `rapl` does not work on Windows, and porting it would be
  44 difficult because Windows does not have APIs that allow easy access to
  45 the relevant model-specific registers.
  46
  47 ## Output
  48
  49 The following is 10 seconds of output from a default invocation of
  50 `rapl`.
  51
  52 ```bash
  53     total W = _pkg_ (cores + _gpu_ + other) + _ram_ W
  54 #01  5.17 W =  1.78 ( 0.12 +  0.10 +  1.56) +  3.39 W
  55 #02  9.43 W =  5.44 ( 1.44 +  1.20 +  2.80) +  3.98 W
  56 #03 14.26 W = 10.21 ( 5.47 +  0.19 +  4.55) +  4.04 W
  57 #04 10.02 W =  6.15 ( 2.62 +  0.43 +  3.10) +  3.86 W
  58 #05 14.63 W = 10.43 ( 4.41 +  0.81 +  5.22) +  4.19 W
  59 #06 11.16 W =  6.90 ( 1.91 +  1.68 +  3.31) +  4.26 W
  60 #07  5.40 W =  1.97 ( 0.20 +  0.10 +  1.67) +  3.44 W
  61 #08  5.17 W =  1.76 ( 0.07 +  0.08 +  1.60) +  3.41 W
  62 #09  5.17 W =  1.76 ( 0.09 +  0.08 +  1.58) +  3.42 W
  63 #10  8.13 W =  4.40 ( 1.55 +  0.11 +  2.74) +  3.73 W
  64 ```
  65
  66 Things to note include the following.
  67
  68 -   All measurements are in Watts.
  69 -   The first line indicates the meaning of each column.
  70 -   The underscores in `_pkg_`, `_gpu_` and `_ram_` are present so that
  71     each column's name has five characters.
  72 -   The total power is the sum of the package power and the RAM power.
  73 -   The package estimate is divided into three parts: cores, GPU, and
  74     \"other\". \"Other\" is computed as the package power minus the
  75     cores power and GPU power.
  76 -   If the processor does not support GPU or RAM estimates then
  77     \"` n/a `\" will be printed in the relevant column instead of a
  78     number, and it will contribute zero to the total.
  79
  80 Once sampling is finished --- either because the user interrupted it, or
  81 because the requested number of samples has been taken --- the following
  82 summary data is shown:
  83
  84 ```bash
  85 10 samples taken over a period of 10.000 seconds
  86
  87 Distribution of 'total' values:
  88             mean =  8.85 W
  89          std dev =  3.50 W
  90   0th percentile =  5.17 W (min)
  91   5th percentile =  5.17 W
  92  25th percentile =  5.17 W
  93  50th percentile =  8.13 W
  94  75th percentile = 11.16 W
  95  95th percentile = 14.63 W
  96 100th percentile = 14.63 W (max)
  97 ```
  98
  99 The distribution data is omitted if there was zero or one samples taken.
 100
 101 ## Options
 102
 103 -   `-i --sample-interval`. The length of each sample in milliseconds.
 104     Defaults to 1000. A warning is given if you set it below 50 because
 105     that is likely to lead to inaccurate estimates.
 106 -   `-n --sample-count`. The number of samples to take. The default is
 107     0, which is interpreted as \"unlimited\".
 108
 109 ## Combining with `powermetrics`
 110
 111 On Mac, you can use the [mach power](powermetrics.md#mach-power) command
 112 to run `rapl` in combination with `powermetrics` in a way that gives the
 113 most useful summary measurements for each of Firefox, Chrome and Safari.