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.
46
47       -i, --inherit
48           Child tasks do not inherit counters.
49
50       -k <path>, --vmlinux=<path>
51           Path to vmlinux. Required for annotation functionality.
52
53       -m <pages>, --mmap-pages=<pages>
54           Number of mmap data pages (must be a power of two) or size
55           specification with appended unit character - B/K/M/G. The size is
56           rounded up to have nearest pages power of two value.
57
58       -p <pid>, --pid=<pid>
59           Profile events on existing Process ID (comma separated list).
60
61       -t <tid>, --tid=<tid>
62           Profile events on existing thread ID (comma separated list).
63
64       -u, --uid=
65           Record events in threads owned by uid. Name or number.
66
67       -r <priority>, --realtime=<priority>
68           Collect data with this RT SCHED_FIFO priority.
69
70       --sym-annotate=<symbol>
71           Annotate this symbol.
72
73       -K, --hide_kernel_symbols
74           Hide kernel symbols.
75
76       -U, --hide_user_symbols
77           Hide user symbols.
78
79       --demangle-kernel
80           Demangle kernel symbols.
81
82       -D, --dump-symtab
83           Dump the symbol table used for profiling.
84
85       -v, --verbose
86           Be more verbose (show counter open errors, etc).
87
88       -z, --zero
89           Zero history across display updates.
90
91       -s, --sort
92           Sort by key(s): pid, comm, dso, symbol, parent, srcline, weight,
93           local_weight, abort, in_tx, transaction, overhead, sample, period.
94           Please see description of --sort in the perf-report man page.
95
96       --fields=
97           Specify output field - multiple keys can be specified in CSV
98           format. Following fields are available: overhead, overhead_sys,
99           overhead_us, overhead_children, sample and period. Also it can
100           contain any sort key(s).
101
102               By default, every sort keys not specified in --field will be appended
103               automatically.
104
105       -n, --show-nr-samples
106           Show a column with the number of samples.
107
108       --show-total-period
109           Show a column with the sum of periods.
110
111       --dsos
112           Only consider symbols in these dsos. This option will affect the
113           percentage of the overhead column. See --percentage for more info.
114
115       --comms
116           Only consider symbols in these comms. This option will affect the
117           percentage of the overhead column. See --percentage for more info.
118
119       --symbols
120           Only consider these symbols. This option will affect the percentage
121           of the overhead column. See --percentage for more info.
122
123       -M, --disassembler-style=
124           Set disassembler style for objdump.
125
126       --source
127           Interleave source code with assembly code. Enabled by default,
128           disable with --no-source.
129
130       --asm-raw
131           Show raw instruction encoding of assembly instructions.
132
133       -g
134           Enables call-graph (stack chain/backtrace) recording.
135
136       --call-graph [mode,type,min[,limit],order[,key][,branch]]
137           Setup and enable call-graph (stack chain/backtrace) recording,
138           implies -g. See --call-graph section in perf-record and perf-report
139           man pages for details.
140
141       --children
142           Accumulate callchain of children to parent entry so that then can
143           show up in the output. The output will have a new "Children" column
144           and will be sorted on the data. It requires -g/--call-graph option
145           enabled. See the ‘overhead calculation’ section for more details.
146           Enabled by default, disable with --no-children.
147
148       --max-stack
149           Set the stack depth limit when parsing the callchain, anything
150           beyond the specified depth will be ignored. This is a trade-off
151           between information loss and faster processing especially for
152           workloads that can have a very long callchain stack.
153
154               Default: /proc/sys/kernel/perf_event_max_stack when present, 127 otherwise.
155
156       --ignore-callees=<regex>
157           Ignore callees of the function(s) matching the given regex. This
158           has the effect of collecting the callers of each such function into
159           one place in the call-graph tree.
160
161       --percent-limit
162           Do not show entries which have an overhead under that percent.
163           (Default: 0).
164
165       --percentage
166           Determine how to display the overhead percentage of filtered
167           entries. Filters can be applied by --comms, --dsos and/or --symbols
168           options and Zoom operations on the TUI (thread, dso, etc).
169
170               "relative" means it's relative to filtered entries only so that the
171               sum of shown entries will be always 100%. "absolute" means it retains
172               the original value before and after the filter is applied.
173
174       -w, --column-widths=<width[,width...]>
175           Force each column width to the provided list, for large terminal
176           readability. 0 means no limit (default behavior).
177
178       --proc-map-timeout
179           When processing pre-existing threads /proc/XXX/mmap, it may take a
180           long time, because the file may be huge. A time out is needed in
181           such cases. This option sets the time out limit. The default value
182           is 500 ms.
183
184       -b, --branch-any
185           Enable taken branch stack sampling. Any type of taken branch may be
186           sampled. This is a shortcut for --branch-filter any. See
187           --branch-filter for more infos.
188
189       -j, --branch-filter
190           Enable taken branch stack sampling. Each sample captures a series
191           of consecutive taken branches. The number of branches captured with
192           each sample depends on the underlying hardware, the type of
193           branches of interest, and the executed code. It is possible to
194           select the types of branches captured by enabling filters. For a
195           full list of modifiers please see the perf record manpage.
196
197               The option requires at least one branch type among any, any_call, any_ret, ind_call, cond.
198               The privilege levels may be omitted, in which case, the privilege levels of the associated
199               event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege
200               levels are subject to permissions.  When sampling on multiple events, branch stack sampling
201               is enabled for all the sampling events. The sampled branch type is the same for all events.
202               The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k
203               Note that this feature may not be available on all processors.
204
205       --raw-trace
206           When displaying traceevent output, do not use print fmt or plugins.
207
208       --hierarchy
209           Enable hierarchy output.
210
211       --force
212           Don’t do ownership validation.
213
214       --num-thread-synthesize
215           The number of threads to run when synthesizing events for existing
216           processes. By default, the number of threads equals to the number
217           of online CPUs.
218

INTERACTIVE PROMPTING KEYS

220       [d]
221           Display refresh delay.
222
223       [e]
224           Number of entries to display.
225
226       [E]
227           Event to display when multiple counters are active.
228
229       [f]
230           Profile display filter (>= hit count).
231
232       [F]
233           Annotation display filter (>= % of total).
234
235       [s]
236           Annotate symbol.
237
238       [S]
239           Stop annotation, return to full profile display.
240
241       [z]
242           Toggle event count zeroing across display updates.
243
244       [qQ]
245           Quit.
246
247       Pressing any unmapped key displays a menu, and prompts for input.
248

OVERHEAD CALCULATION

250       The overhead can be shown in two columns as Children and Self when perf
251       collects callchains. The self overhead is simply calculated by adding
252       all period values of the entry - usually a function (symbol). This is
253       the value that perf shows traditionally and sum of all the self
254       overhead values should be 100%.
255
256       The children overhead is calculated by adding all period values of the
257       child functions so that it can show the total overhead of the higher
258       level functions even if they don’t directly execute much. Children here
259       means functions that are called from another (parent) function.
260
261       It might be confusing that the sum of all the children overhead values
262       exceeds 100% since each of them is already an accumulation of self
263       overhead of its child functions. But with this enabled, users can find
264       which function has the most overhead even if samples are spread over
265       the children.
266
267       Consider the following example; there are three functions like below.
268
269
270           .ft C
271           void foo(void) {
272               /* do something */
273           }
274
275           void bar(void) {
276               /* do something */
277               foo();
278           }
279
280           int main(void) {
281               bar()
282               return 0;
283           }
284           .ft
285
286
287       In this case foo is a child of bar, and bar is an immediate child of
288       main so foo also is a child of main. In other words, main is a parent
289       of foo and bar, and bar is a parent of foo.
290
291       Suppose all samples are recorded in foo and bar only. When it’s
292       recorded with callchains the output will show something like below in
293       the usual (self-overhead-only) output of perf report:
294
295
296           .ft C
297           Overhead  Symbol
298           ........  .....................
299             60.00%  foo
300                     |
301                     --- foo
302                         bar
303                         main
304                         __libc_start_main
305
306             40.00%  bar
307                     |
308                     --- bar
309                         main
310                         __libc_start_main
311           .ft
312
313
314       When the --children option is enabled, the self overhead values of
315       child functions (i.e. foo and bar) are added to the parents to
316       calculate the children overhead. In this case the report could be
317       displayed as:
318
319
320           .ft C
321           Children      Self  Symbol
322           ........  ........  ....................
323            100.00%     0.00%  __libc_start_main
324                     |
325                     --- __libc_start_main
326
327            100.00%     0.00%  main
328                     |
329                     --- main
330                         __libc_start_main
331
332            100.00%    40.00%  bar
333                     |
334                     --- bar
335                         main
336                         __libc_start_main
337
338             60.00%    60.00%  foo
339                     |
340                     --- foo
341                         bar
342                         main
343                         __libc_start_main
344           .ft
345
346
347       In the above output, the self overhead of foo (60%) was add to the
348       children overhead of bar, main and __libc_start_main. Likewise, the
349       self overhead of bar (40%) was added to the children overhead of main
350       and \_\_libc_start_main.
351
352       So \_\_libc_start_main and main are shown first since they have same
353       (100%) children overhead (even though they have zero self overhead) and
354       they are the parents of foo and bar.
355
356       Since v3.16 the children overhead is shown by default and the output is
357       sorted by its values. The children overhead is disabled by specifying
358       --no-children option on the command line or by adding report.children =
359       false or top.children = false in the perf config file.
360

SEE ALSO

362       perf-stat(1), perf-list(1), perf-report(1)
363
364
365
366perf                              06/18/2019                       PERF-TOP(1)
Impressum