perf/Documentation/perf-top.txt

1 perf-top(1)
5 ----
6 perf-top - System profiling tool.
9 --------
11 'perf top' [-e <EVENT> | --event=EVENT] [<options>]
14 -----------
19 -------
20 -a::
21 --all-cpus::
22         System-wide collection.  (default)
24 -c <count>::
25 --count=<count>::
26 	Event period to sample.
28 -C <cpu-list>::
29 --cpu=<cpu>::
31 comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2.
32 Default is to monitor all CPUS.
34 -d <seconds>::
35 --delay=<seconds>::
38 -e <event>::
39 --event=<event>::
45 -E <entries>::
46 --entries=<entries>::
49 -f <count>::
50 --count-filter=<count>::
53 --group::
56 --group-sort-idx::
61 -F <freq>::
62 --freq=<freq>::
67 -i::
68 --inherit::
71 -k <path>::
72 --vmlinux=<path>::
75 --ignore-vmlinux::
78 --kallsyms=<file>::
81 -m <pages>::
82 --mmap-pages=<pages>::
84 	specification with appended unit character - B/K/M/G. The
87 -p <pid>::
88 --pid=<pid>::
91 -t <tid>::
92 --tid=<tid>::
95 -u::
96 --uid=::
99 -r <priority>::
100 --realtime=<priority>::
103 --sym-annotate=<symbol>::
106 -K::
107 --hide_kernel_symbols::
110 -U::
111 --hide_user_symbols::
114 --demangle-kernel::
117 -D::
118 --dump-symtab::
121 -v::
122 --verbose::
125 -z::
126 --zero::
129 -s::
130 --sort::
132 	local_weight, abort, in_tx, transaction, overhead, sample, period.
133 	Please see description of --sort in the perf-report man page.
135 --fields=::
136 	Specify output field - multiple keys can be specified in CSV format.
138 	overhead, overhead_sys, overhead_us, overhead_children, sample and period.
141 	By default, every sort keys not specified in --field will be appended
144 -n::
145 --show-nr-samples::
148 --show-total-period::
151 --dsos::
153 	percentage of the overhead column.  See --percentage for more info.
155 --comms::
157 	percentage of the overhead column.  See --percentage for more info.
159 --symbols::
161 	percentage of the overhead column.  See --percentage for more info.
163 -M::
164 --disassembler-style=:: Set disassembler style for objdump.
166 --prefix=PREFIX::
167 --prefix-strip=N::
172 --source::
173 	Interleave source code with assembly code. Enabled by default,
174 	disable with --no-source.
176 --asm-raw::
179 -g::
180 	Enables call-graph (stack chain/backtrace) recording.
182 --call-graph [mode,type,min[,limit],order[,key][,branch]]::
183 	Setup and enable call-graph (stack chain/backtrace) recording,
184 	implies -g.  See `--call-graph` section in perf-record and
185 	perf-report man pages for details.
187 --children::
190 	and will be sorted on the data.  It requires -g/--call-graph option
192 	Enabled by default, disable with --no-children.
194 --max-stack::
196 	beyond the specified depth will be ignored. This is a trade-off
200 	Default: /proc/sys/kernel/perf_event_max_stack when present, 127 otherwise.
202 --ignore-callees=<regex>::
205         function into one place in the call-graph tree.
207 --percent-limit::
209 	(Default: 0).
211 --percentage::
213 	Filters can be applied by --comms, --dsos and/or --symbols options and
220 -w::
221 --column-widths=<width[,width...]>::
223 	readability.  0 means no limit (default behavior).
225 --proc-map-timeout::
226 	When processing pre-existing threads /proc/XXX/mmap, it may take
229 	This option sets the time out limit. The default value is 500 ms.
232 -b::
233 --branch-any::
235 	This is a shortcut for --branch-filter any. See --branch-filter for more infos.
237 -j::
238 --branch-filter::
239 	Enable taken branch stack sampling. Each sample captures a series of consecutive
240 	taken branches. The number of branches captured with each sample depends on the
250 	The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k
253 --raw-trace::
256 --hierarchy::
259 --overwrite::
261 	machines such as Knights Landing/Mill, but right now is disabled by default as
267 	this situation, till then, this will remain disabled by default.
269 --force::
272 --num-thread-synthesize::
274 	By default, the number of threads equals to the number of online CPUs.
276 --namespaces::
280 --all-cgroups::
284 --switch-on EVENT_NAME::
291 		perf probe -L icmp_rcv
301 		perf top -e cycles,probe:icmp_rcv --switch-on=probe:icmp_rcv
303 	   Alternatively one can ask for --group and then two overhead columns
304            will appear, the first for cycles and the second for the switch-on event.
306 		perf top --group -e cycles,probe:icmp_rcv --switch-on=probe:icmp_rcv
309 	phase is over, i.e. insert a perf probe at that point and use the above
310 	examples replacing probe:icmp_rcv with the just-after-init probe.
312 --switch-off EVENT_NAME::
315 --show-on-off-events::
316 	Show the --switch-on/off events too. This has no effect in 'perf top' now
317 	but probably we'll make the default not to show the switch-on/off events
318         on the --group mode and if there is only one event besides the off/on ones,
322 --stitch-lbr::
324 	callgraph. The option must be used with --call-graph lbr recording.
325 	Disabled by default. In common cases with call stack overflows,
326 	it can recreate better call stacks than the default lbr call stack
333 --pfm-events events::
335 including support for event filters. For example '--pfm-events
338 events cannot be mixed together. The latter must be used with the -e
339 option. The -e option and this one can be mixed and matched.  Events
344 --------------------------
381 include::callchain-overhead-calculation.txt[]
384 --------
385 linkperf:perf-stat[1], linkperf:perf-list[1], linkperf:perf-report[1]