Bug 1769952 - Fix running raptor on a Win10-64 VM r=sparky
[gecko.git] / docs / performance / powermetrics.md
blob614c669b443f71b5c72dacfdad55137266e1fc53
1 # powermetrics
3 `powermetrics` is a Mac-only command-line utility that provides many
4 high-quality power-related measurements. It is most useful for getting
5 CPU, GPU and wakeup measurements in a precise and easily scriptable
6 fashion (unlike [Activity Monitor and
7 top](activity_monitor_and_top.md))
8 especially in combination with
9 [rapl](tools_power_rapl.md) via the
10 `mach power` command. This document describes the version of
11 `powermetrics` that comes with Mac OS 10.10. The one that comes with
12 10.9 is less powerful.
14 **Note**: The [power profiling
15 overview](power_profiling_overview.md) is
16 worth reading at this point if you haven\'t already. It may make parts
17 of this document easier to understand.
19 ## Quick start
21 `powermetrics` provides a vast number of measurements. The following
22 command encompasses the most useful ones:
24 sudo powermetrics --samplers tasks --show-process-coalition --show-process-gpu -n 1 -i 5000
26 -   `--samplers tasks` tells it to just do per-process measurements.
27 -   `--show-process-coalition`` `tells it to group *coalitions* of
28     related processes, e.g. the Firefox parent process and child
29     processes.
30 -   `--show-process-gpu` tells it to show per-process GPU measurements.
31 -   `-n 1` tells it to take one sample and then stop.
32 -   `-i 5000` tells it to use a sample length of 5 seconds (5000 ms).
33     Change this number to get shorter or longer samples.
35 The following is example output from such an invocation:
37     *** Sampled system activity (Fri Sep  4 17:15:14 2015 +1000) (5009.63ms elapsed) ***
39     *** Running tasks ***
41     Name                               ID     CPU ms/s  User%  Deadlines (<2 ms, 2-5 ms)  Wakeups (Intr, Pkg idle)  GPU ms/s
42     com.apple.Terminal                 293    447.66                                      274.83  120.35            221.74
43       firefox                          84627  77.59     55.55  15.37   2.59               91.42   42.12             204.47
44       plugin-container                 84628  377.22    37.18  43.91   18.56              178.65  75.85             17.29
45       Terminal                         694    9.86      79.94  0.00    0.00               4.39    2.20              0.00
46       powermetrics                     84694  1.21      31.53  0.00    0.00               0.20    0.20              0.00
47     com.google.Chrome                  489    233.83                                      48.10   25.95             0.00
48       Google Chrome Helper             84688  181.57    92.81  0.00    0.00               23.95   12.77             0.00
49       Google Chrome                    84681  57.26     76.07  4.39    0.00               23.75   12.97             0.00
50       Google Chrome Helper             84685  0.13      48.08  0.00    0.00               0.40    0.20              0.00
51     kernel_coalition                   1      128.64                                      780.19  330.52            0.00
52       kernel_task                      0      109.97    0.00   0.20    0.00               779.47  330.35            0.00
53       launchd                          1      18.88     2.44   0.00    0.00               0.40    0.20              0.00
54     com.apple.Safari                   488    90.60                                       108.58  56.48             26.65
55       com.apple.WebKit.WebContent      84679  64.21     84.69  0.00    0.00               104.19  54.89             26.66
56       com.apple.WebKit.Networking      84678  26.89     58.89  0.40    0.00               1.60    0.00              0.00
57       Safari                           84676  1.56      55.74  0.00    0.00               2.59    1.40              0.00
58       com.apple.Safari.SearchHelper    84690  0.15      49.49  0.00    0.00               0.20    0.20              0.00
59     org.mozilla.firefox                482    76.56                                       124.34  63.47             0.00
60       firefox                          84496  76.70     89.18  10.58   5.59               124.55  63.48             0.00
62 This sample was taken while the following programs were running:
64 -   Firefox Beta (single process, invoked from the Mac OS dock, shown in
65     the `org.mozilla.firefox` coalition.)
66 -   Firefox Nightly (multi-process, invoked from the command line, shown
67     in the `com.apple.Terminal` coalition.)
68 -   Google Chrome.
69 -   Safari.
71 The grouping of parent and child processes (in coalitions) is obvious.
72 The meaning of the columns is as follows.
74 -   **Name**: Coalition/process name. Process names within coalitions
75     are indented.
76 -   **ID**: Coalition/process ID number.
77 -   **CPU ms/s**: CPU time used by the coalition/process, per second,
78     during the sample period. The sum of the process values typically
79     exceeds the coalition value slightly, for unknown reasons.
80 -   **User%**: Percentage of that CPU time spent in user space (as
81     opposed to kernel mode.)
82 -   **Deadlines (\<2 ms, 2-5 ms)**: These two columns count how many
83     \"short\" timers woke up threads in the process, per second, during
84     the sample period. High frequency timers, which typically have short
85     time-to-deadlines, can cause high power consumption and should be
86     avoided if possible.
87 -   **Wakeups (Intr, Pkg idle)**: These two columns count how many
88     wakeups occurred, per second, during the sample period. The first
89     column counts interrupt-level wakeups that resulted in a thread
90     being dispatched in the process. The second column counts \"package
91     idle exit\" wakeups, which wake up the entire package as opposed to
92     just a single core; such wakeups are particularly expensive, and
93     this count is a subset of the first column\'s count.
94 -   **GPU ms/s**: GPU time used by the coalition/process, per second,
95     during the sample period.
97 Other things to note.
99 -   Smaller is better --- i.e. results in lower power consumption ---
100     for all of these measurements.
101 -   There is some overlap between the two \"Deadlines\" columns and the
102     two \"Wakeups\" columns. For example, firing a single sub-2ms
103     deadline can also cause a package idle exit wakeup.
104 -   Many of these measurements are also obtainable by passing the
105     `TASK_POWER_INFO` flag and a `task_power_info` struct to the
106     `task_info` function.
107 -   By default, the coalitions/processes are sorted by a composite value
108     computed from several factors, though this can be changed via
109     command-line options.
111 ## Other measurements
113 `powermetrics` can also report measurements of backlight usage, network
114 activity, disk activity, interrupt distribution, device power states,
115 C-state residency, P-state residency, quality of service classes, and
116 thermal pressure. These are less likely to be useful for profiling
117 Firefox, however. Run with the `--show-all` to see all of these at once,
118 but note that you\'ll need a very wide window to see all the data.
120 Also note that `powermetrics -h` is a better guide to the the
121 command-line options than `man powermetrics`.
123 ## mach power
125 You can use the `mach power` command to run `powermetrics` in
126 combination with `rapl` in a way that gives the most useful summary
127 measurements for each of Firefox, Chrome and Safari. The following is
128 sample output.
130         total W = _pkg_ (cores + _gpu_ + other) + _ram_ W
131     #01 17.14 W = 14.98 ( 5.50 +  1.19 +  8.29) +  2.16 W
133     1 sample taken over a period of 30.000 seconds
135     Name                               ID     CPU ms/s  User%  Deadlines (<2 ms, 2-5 ms)  Wakeups (Intr, Pkg idle)  GPU ms/s
136     com.google.Chrome                  500    439.64                                      585.35  218.62            19.17
137       Google Chrome Helper             67319  284.75    83.03  296.67  0.00               454.05  172.74            0.00
138       Google Chrome Helper             67304  55.23     64.83  0.03    0.00               9.43    4.33              19.17
139       Google Chrome                    67301  63.77     68.09  29.46   0.13               76.11   22.26             0.00
140       Google Chrome Helper             67320  38.30     66.70  17.83   0.00               45.78   19.29             0.00
141     com.apple.WindowServer             68     102.58                                      112.36  43.15             80.52
142       WindowServer                     141    103.03    58.19  60.48   6.40               112.36  43.15             80.53
143     com.apple.Safari                   499    267.19                                      110.53  46.05             1.69
144       com.apple.WebKit.WebContent      67372  190.15    79.34  2.02    0.14               129.28  53.79             2.33
145       com.apple.WebKit.Networking      67292  65.23     52.74  0.07    0.00               4.33    1.40              0.00
146       Safari                           67290  29.09     77.65  0.23    0.00               7.13    3.37              0.00
147       com.apple.Safari.SearchHelper    67371  13.88     91.18  0.00    0.00               0.36    0.05              0.00
148       com.apple.WebKit.WebContent      67297  0.81      56.84  0.10    0.00               2.20    1.30              0.00
149       com.apple.WebKit.WebContent      67293  0.46      76.40  0.03    0.00               0.57    0.20              0.00
150       com.apple.WebKit.WebContent      67295  0.24      67.72  0.00    0.00               0.90    0.37              0.00
151       com.apple.WebKit.WebContent      67298  0.17      59.88  0.00    0.00               0.50    0.13              0.00
152       com.apple.WebKit.WebContent      67296  0.07      43.51  0.00    0.00               0.10    0.03              0.00
153     kernel_coalition                   1      111.76                                      724.80  213.09            0.12
154       kernel_task                      0      107.06    0.00   5.86    0.00               724.46  212.99            0.12
155     org.mozilla.firefox                498    92.17                                       212.69  75.67             1.81
156       firefox                          63865  61.00     87.18  1.00    0.87               25.79   9.00              1.81
157       plugin-container                 67269  31.49     72.46  1.80    0.00               186.90  66.68             0.00
158       com.apple.WebKit.Plugin.64       67373  55.55     74.38  0.74    0.00               9.51    3.13              0.02
159     com.apple.Terminal                 109    6.22                                        0.40    0.23              0.00
160       Terminal                         208    6.25      92.99  0.00    0.00               0.33    0.20              0.00 
162 The `rapl` output is first, then the `powermetrics` output. As well as
163 the browser processes, the `WindowServer` and kernel tasks are shown
164 because browsers often trigger significant load in them.
166 The default sample period is 30,000 milliseconds (30 seconds), but that
167 can be changed with the `-i` option.