mozilla-central/docs/performance/tools_power_rapl.md

Source code

Revision control

Copy as Markdown

Other Tools

# tools/power/rapl
`tools/power/rapl` (or `rapl` for short) is a command-line utility in
the Mozilla tree that periodically reads and prints all available Intel
RAPL power estimates. These are machine-wide estimates, so if you want
to estimate the power consumption of a single program you should
minimize other activity on the machine while measuring.
**Note**: The [power profiling overview](power_profiling_overview.md) is
worth reading at this point if you haven't already. It may make parts
of this document easier to understand.
## Invocation
First, do a [standard build of Firefox](/setup/index.rst).
### Mac
On Mac, `rapl` can be run as follows.
```bash
$OBJDIR/dist/bin/rapl
```
### Linux
On Linux, `rapl` can be run as root, as follows.
sudo $OBJDIR/dist/bin/rapl
Alternatively, it can be run without root privileges by setting the
contents of
to 0. Note that if you do change this file, its contents may reset when
the machine is next rebooted.
You must be running Linux kernel version 3.14 or later for `rapl` to
work. Otherwise, it will fail with an error message explaining this
requirement.
### Windows
Unfortunately, `rapl` does not work on Windows, and porting it would be
difficult because Windows does not have APIs that allow easy access to
the relevant model-specific registers.
## Output
The following is 10 seconds of output from a default invocation of
`rapl`.
```bash
total W = _pkg_ (cores + _gpu_ + other) + _ram_ W
#01 5.17 W = 1.78 ( 0.12 + 0.10 + 1.56) + 3.39 W
#02 9.43 W = 5.44 ( 1.44 + 1.20 + 2.80) + 3.98 W
#03 14.26 W = 10.21 ( 5.47 + 0.19 + 4.55) + 4.04 W
#04 10.02 W = 6.15 ( 2.62 + 0.43 + 3.10) + 3.86 W
#05 14.63 W = 10.43 ( 4.41 + 0.81 + 5.22) + 4.19 W
#06 11.16 W = 6.90 ( 1.91 + 1.68 + 3.31) + 4.26 W
#07 5.40 W = 1.97 ( 0.20 + 0.10 + 1.67) + 3.44 W
#08 5.17 W = 1.76 ( 0.07 + 0.08 + 1.60) + 3.41 W
#09 5.17 W = 1.76 ( 0.09 + 0.08 + 1.58) + 3.42 W
#10 8.13 W = 4.40 ( 1.55 + 0.11 + 2.74) + 3.73 W
```
Things to note include the following.
- All measurements are in Watts.
- The first line indicates the meaning of each column.
- The underscores in `_pkg_`, `_gpu_` and `_ram_` are present so that
each column's name has five characters.
- The total power is the sum of the package power and the RAM power.
- The package estimate is divided into three parts: cores, GPU, and
\"other\". \"Other\" is computed as the package power minus the
cores power and GPU power.
- If the processor does not support GPU or RAM estimates then
\"` n/a `\" will be printed in the relevant column instead of a
number, and it will contribute zero to the total.
Once sampling is finished --- either because the user interrupted it, or
because the requested number of samples has been taken --- the following
summary data is shown:
```bash
10 samples taken over a period of 10.000 seconds
Distribution of 'total' values:
mean = 8.85 W
std dev = 3.50 W
0th percentile = 5.17 W (min)
5th percentile = 5.17 W
25th percentile = 5.17 W
50th percentile = 8.13 W
75th percentile = 11.16 W
95th percentile = 14.63 W
100th percentile = 14.63 W (max)
```
The distribution data is omitted if there was zero or one samples taken.
## Options
- `-i --sample-interval`. The length of each sample in milliseconds.
Defaults to 1000. A warning is given if you set it below 50 because
that is likely to lead to inaccurate estimates.
- `-n --sample-count`. The number of samples to take. The default is
0, which is interpreted as \"unlimited\".
## Combining with `powermetrics`
On Mac, you can use the [mach power](powermetrics.md#mach-power) command
to run `rapl` in combination with `powermetrics` in a way that gives the
most useful summary measurements for each of Firefox, Chrome and Safari.