1PERF-TOP(1)                       perf Manual                      PERF-TOP(1)
2
3
4

NAME

6       perf-top - System profiling tool.
7

SYNOPSIS

9       perf top [-e <EVENT> | --event=EVENT] [<options>]
10

DESCRIPTION

12       This command generates and displays a performance counter profile in
13       real time.
14

OPTIONS

16       -a, --all-cpus
17           System-wide collection. (default)
18
19       -c <count>, --count=<count>
20           Event period to sample.
21
22       -C <cpu-list>, --cpu=<cpu>
23           Monitor only on the list of CPUs provided. Multiple CPUs can be
24           provided as a comma-separated list with no space: 0,1. Ranges of
25           CPUs are specified with -: 0-2. Default is to monitor all CPUS.
26
27       -d <seconds>, --delay=<seconds>
28           Number of seconds to delay between refreshes.
29
30       -e <event>, --event=<event>
31           Select the PMU event. Selection can be a symbolic event name (use
32           perf list to list all events) or a raw PMU event (eventsel+umask)
33           in the form of rNNN where NNN is a hexadecimal event descriptor.
34
35       -E <entries>, --entries=<entries>
36           Display this many functions.
37
38       -f <count>, --count-filter=<count>
39           Only display functions with more events than this.
40
41       --group
42           Put the counters into a counter group.
43
44       -F <freq>, --freq=<freq>
45           Profile at this frequency. Use max to use the currently maximum
46           allowed frequency, i.e. the value in the
47           kernel.perf_event_max_sample_rate sysctl.
48
49       -i, --inherit
50           Child tasks do not inherit counters.
51
52       -k <path>, --vmlinux=<path>
53           Path to vmlinux. Required for annotation functionality.
54
55       --ignore-vmlinux
56           Ignore vmlinux files.
57
58       --kallsyms=<file>
59           kallsyms pathname
60
61       -m <pages>, --mmap-pages=<pages>
62           Number of mmap data pages (must be a power of two) or size
63           specification with appended unit character - B/K/M/G. The size is
64           rounded up to have nearest pages power of two value.
65
66       -p <pid>, --pid=<pid>
67           Profile events on existing Process ID (comma separated list).
68
69       -t <tid>, --tid=<tid>
70           Profile events on existing thread ID (comma separated list).
71
72       -u, --uid=
73           Record events in threads owned by uid. Name or number.
74
75       -r <priority>, --realtime=<priority>
76           Collect data with this RT SCHED_FIFO priority.
77
78       --sym-annotate=<symbol>
79           Annotate this symbol.
80
81       -K, --hide_kernel_symbols
82           Hide kernel symbols.
83
84       -U, --hide_user_symbols
85           Hide user symbols.
86
87       --demangle-kernel
88           Demangle kernel symbols.
89
90       -D, --dump-symtab
91           Dump the symbol table used for profiling.
92
93       -v, --verbose
94           Be more verbose (show counter open errors, etc).
95
96       -z, --zero
97           Zero history across display updates.
98
99       -s, --sort
100           Sort by key(s): pid, comm, dso, symbol, parent, srcline, weight,
101           local_weight, abort, in_tx, transaction, overhead, sample, period.
102           Please see description of --sort in the perf-report man page.
103
104       --fields=
105           Specify output field - multiple keys can be specified in CSV
106           format. Following fields are available: overhead, overhead_sys,
107           overhead_us, overhead_children, sample and period. Also it can
108           contain any sort key(s).
109
110               By default, every sort keys not specified in --field will be appended
111               automatically.
112
113       -n, --show-nr-samples
114           Show a column with the number of samples.
115
116       --show-total-period
117           Show a column with the sum of periods.
118
119       --dsos
120           Only consider symbols in these dsos. This option will affect the
121           percentage of the overhead column. See --percentage for more info.
122
123       --comms
124           Only consider symbols in these comms. This option will affect the
125           percentage of the overhead column. See --percentage for more info.
126
127       --symbols
128           Only consider these symbols. This option will affect the percentage
129           of the overhead column. See --percentage for more info.
130
131       -M, --disassembler-style=
132           Set disassembler style for objdump.
133
134       --prefix=PREFIX, --prefix-strip=N
135           Remove first N entries from source file path names in executables
136           and add PREFIX. This allows to display source code compiled on
137           systems with different file system layout.
138
139       --source
140           Interleave source code with assembly code. Enabled by default,
141           disable with --no-source.
142
143       --asm-raw
144           Show raw instruction encoding of assembly instructions.
145
146       -g
147           Enables call-graph (stack chain/backtrace) recording.
148
149       --call-graph [mode,type,min[,limit],order[,key][,branch]]
150           Setup and enable call-graph (stack chain/backtrace) recording,
151           implies -g. See --call-graph section in perf-record and perf-report
152           man pages for details.
153
154       --children
155           Accumulate callchain of children to parent entry so that then can
156           show up in the output. The output will have a new "Children" column
157           and will be sorted on the data. It requires -g/--call-graph option
158           enabled. See the ‘overhead calculation’ section for more details.
159           Enabled by default, disable with --no-children.
160
161       --max-stack
162           Set the stack depth limit when parsing the callchain, anything
163           beyond the specified depth will be ignored. This is a trade-off
164           between information loss and faster processing especially for
165           workloads that can have a very long callchain stack.
166
167               Default: /proc/sys/kernel/perf_event_max_stack when present, 127 otherwise.
168
169       --ignore-callees=<regex>
170           Ignore callees of the function(s) matching the given regex. This
171           has the effect of collecting the callers of each such function into
172           one place in the call-graph tree.
173
174       --percent-limit
175           Do not show entries which have an overhead under that percent.
176           (Default: 0).
177
178       --percentage
179           Determine how to display the overhead percentage of filtered
180           entries. Filters can be applied by --comms, --dsos and/or --symbols
181           options and Zoom operations on the TUI (thread, dso, etc).
182
183               "relative" means it's relative to filtered entries only so that the
184               sum of shown entries will be always 100%. "absolute" means it retains
185               the original value before and after the filter is applied.
186
187       -w, --column-widths=<width[,width...]>
188           Force each column width to the provided list, for large terminal
189           readability. 0 means no limit (default behavior).
190
191       --proc-map-timeout
192           When processing pre-existing threads /proc/XXX/mmap, it may take a
193           long time, because the file may be huge. A time out is needed in
194           such cases. This option sets the time out limit. The default value
195           is 500 ms.
196
197       -b, --branch-any
198           Enable taken branch stack sampling. Any type of taken branch may be
199           sampled. This is a shortcut for --branch-filter any. See
200           --branch-filter for more infos.
201
202       -j, --branch-filter
203           Enable taken branch stack sampling. Each sample captures a series
204           of consecutive taken branches. The number of branches captured with
205           each sample depends on the underlying hardware, the type of
206           branches of interest, and the executed code. It is possible to
207           select the types of branches captured by enabling filters. For a
208           full list of modifiers please see the perf record manpage.
209
210               The option requires at least one branch type among any, any_call, any_ret, ind_call, cond.
211               The privilege levels may be omitted, in which case, the privilege levels of the associated
212               event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege
213               levels are subject to permissions.  When sampling on multiple events, branch stack sampling
214               is enabled for all the sampling events. The sampled branch type is the same for all events.
215               The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k
216               Note that this feature may not be available on all processors.
217
218       --raw-trace
219           When displaying traceevent output, do not use print fmt or plugins.
220
221       --hierarchy
222           Enable hierarchy output.
223
224       --overwrite
225           Enable this to use just the most recent records, which helps in
226           high core count machines such as Knights Landing/Mill, but right
227           now is disabled by default as the pausing used in this technique is
228           leading to loss of metadata events such as PERF_RECORD_MMAP which
229           makes perf top unable to resolve samples, leading to lots of
230           unknown samples appearing on the UI. Enable this if you are in such
231           machines and profiling a workload that doesn’t creates short lived
232           threads and/or doesn’t uses many executable mmap operations. Work
233           is being planed to solve this situation, till then, this will
234           remain disabled by default.
235
236       --force
237           Don’t do ownership validation.
238
239       --num-thread-synthesize
240           The number of threads to run when synthesizing events for existing
241           processes. By default, the number of threads equals to the number
242           of online CPUs.
243
244       --namespaces
245           Record events of type PERF_RECORD_NAMESPACES and display it with
246           the cgroup_id sort key.
247
248       --switch-on EVENT_NAME
249           Only consider events after this event is found.
250
251               E.g.:
252
253               Find out where broadcast packets are handled
254
255               perf probe -L icmp_rcv
256
257               Insert a probe there:
258
259               perf probe icmp_rcv:59
260
261               Start perf top and ask it to only consider the cycles events when a
262               broadcast packet arrives This will show a menu with two entries and
263               will start counting when a broadcast packet arrives:
264
265               perf top -e cycles,probe:icmp_rcv --switch-on=probe:icmp_rcv
266
267               Alternatively one can ask for --group and then two overhead columns
268               will appear, the first for cycles and the second for the switch-on event.
269
270               perf top --group -e cycles,probe:icmp_rcv --switch-on=probe:icmp_rcv
271
272               This may be interesting to measure a workload only after some initialization
273               phase is over, i.e. insert a perf probe at that point and use the above
274               examples replacing probe:icmp_rcv with the just-after-init probe.
275
276       --switch-off EVENT_NAME
277           Stop considering events after this event is found.
278
279       --show-on-off-events
280           Show the --switch-on/off events too. This has no effect in perf top
281           now but probably we’ll make the default not to show the
282           switch-on/off events on the --group mode and if there is only one
283           event besides the off/on ones, go straight to the histogram
284           browser, just like perf top with no events explicitely specified
285           does.
286

INTERACTIVE PROMPTING KEYS

288       [d]
289           Display refresh delay.
290
291       [e]
292           Number of entries to display.
293
294       [E]
295           Event to display when multiple counters are active.
296
297       [f]
298           Profile display filter (>= hit count).
299
300       [F]
301           Annotation display filter (>= % of total).
302
303       [s]
304           Annotate symbol.
305
306       [S]
307           Stop annotation, return to full profile display.
308
309       [K]
310           Hide kernel symbols.
311
312       [U]
313           Hide user symbols.
314
315       [z]
316           Toggle event count zeroing across display updates.
317
318       [qQ]
319           Quit.
320
321       Pressing any unmapped key displays a menu, and prompts for input.
322

OVERHEAD CALCULATION

324       The overhead can be shown in two columns as Children and Self when perf
325       collects callchains. The self overhead is simply calculated by adding
326       all period values of the entry - usually a function (symbol). This is
327       the value that perf shows traditionally and sum of all the self
328       overhead values should be 100%.
329
330       The children overhead is calculated by adding all period values of the
331       child functions so that it can show the total overhead of the higher
332       level functions even if they don’t directly execute much. Children here
333       means functions that are called from another (parent) function.
334
335       It might be confusing that the sum of all the children overhead values
336       exceeds 100% since each of them is already an accumulation of self
337       overhead of its child functions. But with this enabled, users can find
338       which function has the most overhead even if samples are spread over
339       the children.
340
341       Consider the following example; there are three functions like below.
342
343
344           .ft C
345           void foo(void) {
346               /* do something */
347           }
348
349           void bar(void) {
350               /* do something */
351               foo();
352           }
353
354           int main(void) {
355               bar()
356               return 0;
357           }
358           .ft
359
360
361       In this case foo is a child of bar, and bar is an immediate child of
362       main so foo also is a child of main. In other words, main is a parent
363       of foo and bar, and bar is a parent of foo.
364
365       Suppose all samples are recorded in foo and bar only. When it’s
366       recorded with callchains the output will show something like below in
367       the usual (self-overhead-only) output of perf report:
368
369
370           .ft C
371           Overhead  Symbol
372           ........  .....................
373             60.00%  foo
374                     |
375                     --- foo
376                         bar
377                         main
378                         __libc_start_main
379
380             40.00%  bar
381                     |
382                     --- bar
383                         main
384                         __libc_start_main
385           .ft
386
387
388       When the --children option is enabled, the self overhead values of
389       child functions (i.e. foo and bar) are added to the parents to
390       calculate the children overhead. In this case the report could be
391       displayed as:
392
393
394           .ft C
395           Children      Self  Symbol
396           ........  ........  ....................
397            100.00%     0.00%  __libc_start_main
398                     |
399                     --- __libc_start_main
400
401            100.00%     0.00%  main
402                     |
403                     --- main
404                         __libc_start_main
405
406            100.00%    40.00%  bar
407                     |
408                     --- bar
409                         main
410                         __libc_start_main
411
412             60.00%    60.00%  foo
413                     |
414                     --- foo
415                         bar
416                         main
417                         __libc_start_main
418           .ft
419
420
421       In the above output, the self overhead of foo (60%) was add to the
422       children overhead of bar, main and __libc_start_main. Likewise, the
423       self overhead of bar (40%) was added to the children overhead of main
424       and \_\_libc_start_main.
425
426       So \_\_libc_start_main and main are shown first since they have same
427       (100%) children overhead (even though they have zero self overhead) and
428       they are the parents of foo and bar.
429
430       Since v3.16 the children overhead is shown by default and the output is
431       sorted by its values. The children overhead is disabled by specifying
432       --no-children option on the command line or by adding report.children =
433       false or top.children = false in the perf config file.
434

SEE ALSO

436       perf-stat(1), perf-list(1), perf-report(1)
437
438
439
440perf                              04/23/2020                       PERF-TOP(1)
Impressum