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       --source
135           Interleave source code with assembly code. Enabled by default,
136           disable with --no-source.
137
138       --asm-raw
139           Show raw instruction encoding of assembly instructions.
140
141       -g
142           Enables call-graph (stack chain/backtrace) recording.
143
144       --call-graph [mode,type,min[,limit],order[,key][,branch]]
145           Setup and enable call-graph (stack chain/backtrace) recording,
146           implies -g. See --call-graph section in perf-record and perf-report
147           man pages for details.
148
149       --children
150           Accumulate callchain of children to parent entry so that then can
151           show up in the output. The output will have a new "Children" column
152           and will be sorted on the data. It requires -g/--call-graph option
153           enabled. See the ‘overhead calculation’ section for more details.
154           Enabled by default, disable with --no-children.
155
156       --max-stack
157           Set the stack depth limit when parsing the callchain, anything
158           beyond the specified depth will be ignored. This is a trade-off
159           between information loss and faster processing especially for
160           workloads that can have a very long callchain stack.
161
162               Default: /proc/sys/kernel/perf_event_max_stack when present, 127 otherwise.
163
164       --ignore-callees=<regex>
165           Ignore callees of the function(s) matching the given regex. This
166           has the effect of collecting the callers of each such function into
167           one place in the call-graph tree.
168
169       --percent-limit
170           Do not show entries which have an overhead under that percent.
171           (Default: 0).
172
173       --percentage
174           Determine how to display the overhead percentage of filtered
175           entries. Filters can be applied by --comms, --dsos and/or --symbols
176           options and Zoom operations on the TUI (thread, dso, etc).
177
178               "relative" means it's relative to filtered entries only so that the
179               sum of shown entries will be always 100%. "absolute" means it retains
180               the original value before and after the filter is applied.
181
182       -w, --column-widths=<width[,width...]>
183           Force each column width to the provided list, for large terminal
184           readability. 0 means no limit (default behavior).
185
186       --proc-map-timeout
187           When processing pre-existing threads /proc/XXX/mmap, it may take a
188           long time, because the file may be huge. A time out is needed in
189           such cases. This option sets the time out limit. The default value
190           is 500 ms.
191
192       -b, --branch-any
193           Enable taken branch stack sampling. Any type of taken branch may be
194           sampled. This is a shortcut for --branch-filter any. See
195           --branch-filter for more infos.
196
197       -j, --branch-filter
198           Enable taken branch stack sampling. Each sample captures a series
199           of consecutive taken branches. The number of branches captured with
200           each sample depends on the underlying hardware, the type of
201           branches of interest, and the executed code. It is possible to
202           select the types of branches captured by enabling filters. For a
203           full list of modifiers please see the perf record manpage.
204
205               The option requires at least one branch type among any, any_call, any_ret, ind_call, cond.
206               The privilege levels may be omitted, in which case, the privilege levels of the associated
207               event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege
208               levels are subject to permissions.  When sampling on multiple events, branch stack sampling
209               is enabled for all the sampling events. The sampled branch type is the same for all events.
210               The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k
211               Note that this feature may not be available on all processors.
212
213       --raw-trace
214           When displaying traceevent output, do not use print fmt or plugins.
215
216       --hierarchy
217           Enable hierarchy output.
218
219       --overwrite
220           Enable this to use just the most recent records, which helps in
221           high core count machines such as Knights Landing/Mill, but right
222           now is disabled by default as the pausing used in this technique is
223           leading to loss of metadata events such as PERF_RECORD_MMAP which
224           makes perf top unable to resolve samples, leading to lots of
225           unknown samples appearing on the UI. Enable this if you are in such
226           machines and profiling a workload that doesn’t creates short lived
227           threads and/or doesn’t uses many executable mmap operations. Work
228           is being planed to solve this situation, till then, this will
229           remain disabled by default.
230
231       --force
232           Don’t do ownership validation.
233
234       --num-thread-synthesize
235           The number of threads to run when synthesizing events for existing
236           processes. By default, the number of threads equals to the number
237           of online CPUs.
238
239       --namespaces
240           Record events of type PERF_RECORD_NAMESPACES and display it with
241           the cgroup_id sort key.
242

INTERACTIVE PROMPTING KEYS

244       [d]
245           Display refresh delay.
246
247       [e]
248           Number of entries to display.
249
250       [E]
251           Event to display when multiple counters are active.
252
253       [f]
254           Profile display filter (>= hit count).
255
256       [F]
257           Annotation display filter (>= % of total).
258
259       [s]
260           Annotate symbol.
261
262       [S]
263           Stop annotation, return to full profile display.
264
265       [K]
266           Hide kernel symbols.
267
268       [U]
269           Hide user symbols.
270
271       [z]
272           Toggle event count zeroing across display updates.
273
274       [qQ]
275           Quit.
276
277       Pressing any unmapped key displays a menu, and prompts for input.
278

OVERHEAD CALCULATION

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

SEE ALSO

392       perf-stat(1), perf-list(1), perf-report(1)
393
394
395
396perf                              11/12/2019                       PERF-TOP(1)
Impressum