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