Commit | Line | Data |
---|---|---|
1d8c8b20 | 1 | perf-stat(1) |
6e6b754f | 2 | ============ |
1d8c8b20 IM |
3 | |
4 | NAME | |
5 | ---- | |
6 | perf-stat - Run a command and gather performance counter statistics | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
8c207692 SB |
11 | 'perf stat' [-e <EVENT> | --event=EVENT] [-a] <command> |
12 | 'perf stat' [-e <EVENT> | --event=EVENT] [-a] -- <command> [<options>] | |
4979d0c7 | 13 | 'perf stat' [-e <EVENT> | --event=EVENT] [-a] record [-o file] -- <command> [<options>] |
ba6039b6 | 14 | 'perf stat' report [-i file] |
1d8c8b20 IM |
15 | |
16 | DESCRIPTION | |
17 | ----------- | |
18 | This command runs a command and gathers performance counter statistics | |
19 | from it. | |
20 | ||
21 | ||
22 | OPTIONS | |
23 | ------- | |
24 | <command>...:: | |
25 | Any command you can specify in a shell. | |
26 | ||
4979d0c7 JO |
27 | record:: |
28 | See STAT RECORD. | |
20c84e95 | 29 | |
ba6039b6 JO |
30 | report:: |
31 | See STAT REPORT. | |
32 | ||
1d8c8b20 IM |
33 | -e:: |
34 | --event=:: | |
f9ab9c19 CS |
35 | Select the PMU event. Selection can be: |
36 | ||
37 | - a symbolic event name (use 'perf list' to list all events) | |
38 | ||
39 | - a raw PMU event (eventsel+umask) in the form of rNNN where NNN is a | |
40 | hexadecimal event descriptor. | |
41 | ||
42 | - a symbolically formed event like 'pmu/param1=0x3,param2/' where | |
43 | param1 and param2 are defined as formats for the PMU in | |
44 | /sys/bus/event_sources/devices/<pmu>/format/* | |
45 | ||
46 | - a symbolically formed event like 'pmu/config=M,config1=N,config2=K/' | |
47 | where M, N, K are numbers (in decimal, hex, octal format). | |
48 | Acceptable values for each of 'config', 'config1' and 'config2' | |
49 | parameters are defined by corresponding entries in | |
50 | /sys/bus/event_sources/devices/<pmu>/format/* | |
1d8c8b20 | 51 | |
20c84e95 | 52 | -i:: |
2e6cdf99 SE |
53 | --no-inherit:: |
54 | child tasks do not inherit counters | |
20c84e95 IM |
55 | -p:: |
56 | --pid=<pid>:: | |
b52956c9 | 57 | stat events on existing process id (comma separated list) |
8c207692 SB |
58 | |
59 | -t:: | |
60 | --tid=<tid>:: | |
b52956c9 | 61 | stat events on existing thread id (comma separated list) |
8c207692 | 62 | |
20c84e95 | 63 | |
1d8c8b20 | 64 | -a:: |
8c207692 SB |
65 | --all-cpus:: |
66 | system-wide collection from all CPUs | |
1d8c8b20 | 67 | |
b26bc5a7 | 68 | -c:: |
8c207692 SB |
69 | --scale:: |
70 | scale/normalize counter values | |
71 | ||
f594bae0 BP |
72 | -d:: |
73 | --detailed:: | |
74 | print more detailed statistics, can be specified up to 3 times | |
75 | ||
76 | -d: detailed events, L1 and LLC data cache | |
77 | -d -d: more detailed events, dTLB and iTLB events | |
78 | -d -d -d: very detailed events, adding prefetch events | |
79 | ||
8c207692 SB |
80 | -r:: |
81 | --repeat=<n>:: | |
a7e191c3 | 82 | repeat command and print average + stddev (max: 100). 0 means forever. |
1d8c8b20 | 83 | |
5af52b51 | 84 | -B:: |
8c207692 | 85 | --big-num:: |
5af52b51 SE |
86 | print large numbers with thousands' separators according to locale |
87 | ||
c45c6ea2 SE |
88 | -C:: |
89 | --cpu=:: | |
8c207692 SB |
90 | Count only on the list of CPUs provided. Multiple CPUs can be provided as a |
91 | comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2. | |
c45c6ea2 SE |
92 | In per-thread mode, this option is ignored. The -a option is still necessary |
93 | to activate system-wide monitoring. Default is to count on all CPUs. | |
94 | ||
f5b4a9c3 SE |
95 | -A:: |
96 | --no-aggr:: | |
97 | Do not aggregate counts across all monitored CPUs in system-wide mode (-a). | |
98 | This option is only valid in system-wide mode. | |
99 | ||
8c207692 SB |
100 | -n:: |
101 | --null:: | |
102 | null run - don't start any counters | |
103 | ||
104 | -v:: | |
105 | --verbose:: | |
106 | be more verbose (show counter open errors, etc) | |
107 | ||
d7470b6a SE |
108 | -x SEP:: |
109 | --field-separator SEP:: | |
110 | print counts using a CSV-style output to make it easy to import directly into | |
111 | spreadsheets. Columns are separated by the string specified in SEP. | |
112 | ||
023695d9 SE |
113 | -G name:: |
114 | --cgroup name:: | |
115 | monitor only in the container (cgroup) called "name". This option is available only | |
116 | in per-cpu mode. The cgroup filesystem must be mounted. All threads belonging to | |
117 | container "name" are monitored when they run on the monitored CPUs. Multiple cgroups | |
118 | can be provided. Each cgroup is applied to the corresponding event, i.e., first cgroup | |
119 | to first event, second cgroup to second event and so on. It is possible to provide | |
120 | an empty cgroup (monitor all the time) using, e.g., -G foo,,bar. Cgroups must have | |
121 | corresponding events, i.e., they always refer to events defined earlier on the command | |
122 | line. | |
123 | ||
4aa9015f | 124 | -o file:: |
56f3bae7 | 125 | --output file:: |
4aa9015f SE |
126 | Print the output into the designated file. |
127 | ||
128 | --append:: | |
129 | Append to the output file designated with the -o option. Ignored if -o is not specified. | |
130 | ||
56f3bae7 JC |
131 | --log-fd:: |
132 | ||
133 | Log output to fd, instead of stderr. Complementary to --output, and mutually exclusive | |
134 | with it. --append may be used here. Examples: | |
135 | 3>results perf stat --log-fd 3 -- $cmd | |
136 | 3>>results perf stat --log-fd 3 --append -- $cmd | |
137 | ||
1f16c575 PZ |
138 | --pre:: |
139 | --post:: | |
140 | Pre and post measurement hooks, e.g.: | |
141 | ||
142 | perf stat --repeat 10 --null --sync --pre 'make -s O=defconfig-build/clean' -- make -s -j64 O=defconfig-build/ bzImage | |
56f3bae7 | 143 | |
13370a9b SE |
144 | -I msecs:: |
145 | --interval-print msecs:: | |
19afd104 KL |
146 | Print count deltas every N milliseconds (minimum: 10ms) |
147 | The overhead percentage could be high in some cases, for instance with small, sub 100ms intervals. Use with caution. | |
148 | example: 'perf stat -I 1000 -e cycles -a sleep 5' | |
56f3bae7 | 149 | |
d4304958 | 150 | --per-socket:: |
d7e7a451 SE |
151 | Aggregate counts per processor socket for system-wide mode measurements. This |
152 | is a useful mode to detect imbalance between sockets. To enable this mode, | |
d4304958 | 153 | use --per-socket in addition to -a. (system-wide). The output includes the |
d7e7a451 SE |
154 | socket number and the number of online processors on that socket. This is |
155 | useful to gauge the amount of aggregation. | |
156 | ||
12c08a9f SE |
157 | --per-core:: |
158 | Aggregate counts per physical processor for system-wide mode measurements. This | |
159 | is a useful mode to detect imbalance between physical cores. To enable this mode, | |
160 | use --per-core in addition to -a. (system-wide). The output includes the | |
161 | core number and the number of online logical processors on that physical processor. | |
162 | ||
32b8af82 JO |
163 | --per-thread:: |
164 | Aggregate counts per monitored threads, when monitoring threads (-t option) | |
165 | or processes (-p option). | |
166 | ||
41191688 | 167 | -D msecs:: |
8f3dd2b0 | 168 | --delay msecs:: |
41191688 AK |
169 | After starting the program, wait msecs before measuring. This is useful to |
170 | filter out the startup phase of the program, which is often very different. | |
171 | ||
4cabc3d1 AK |
172 | -T:: |
173 | --transaction:: | |
174 | ||
175 | Print statistics of transactional execution if supported. | |
176 | ||
4979d0c7 JO |
177 | STAT RECORD |
178 | ----------- | |
179 | Stores stat data into perf data file. | |
180 | ||
181 | -o file:: | |
182 | --output file:: | |
183 | Output file name. | |
184 | ||
ba6039b6 JO |
185 | STAT REPORT |
186 | ----------- | |
187 | Reads and reports stat data from perf data file. | |
188 | ||
189 | -i file:: | |
190 | --input file:: | |
191 | Input file name. | |
192 | ||
89af4e05 JO |
193 | --per-socket:: |
194 | Aggregate counts per processor socket for system-wide mode measurements. | |
195 | ||
196 | --per-core:: | |
197 | Aggregate counts per physical processor for system-wide mode measurements. | |
198 | ||
199 | -A:: | |
200 | --no-aggr:: | |
201 | Do not aggregate counts across all monitored CPUs. | |
202 | ||
4979d0c7 | 203 | |
1d8c8b20 IM |
204 | EXAMPLES |
205 | -------- | |
206 | ||
20c84e95 | 207 | $ perf stat -- make -j |
1d8c8b20 | 208 | |
20c84e95 | 209 | Performance counter stats for 'make -j': |
1d8c8b20 | 210 | |
20c84e95 IM |
211 | 8117.370256 task clock ticks # 11.281 CPU utilization factor |
212 | 678 context switches # 0.000 M/sec | |
213 | 133 CPU migrations # 0.000 M/sec | |
214 | 235724 pagefaults # 0.029 M/sec | |
215 | 24821162526 CPU cycles # 3057.784 M/sec | |
216 | 18687303457 instructions # 2302.138 M/sec | |
217 | 172158895 cache references # 21.209 M/sec | |
218 | 27075259 cache misses # 3.335 M/sec | |
1d8c8b20 | 219 | |
20c84e95 | 220 | Wall-clock time elapsed: 719.554352 msecs |
1d8c8b20 IM |
221 | |
222 | SEE ALSO | |
223 | -------- | |
386b05e3 | 224 | linkperf:perf-top[1], linkperf:perf-list[1] |