1PERF-TOP(1) perf Manual PERF-TOP(1)
2
6 perf-top - System profiling tool.
7
9 perf top [-e <EVENT> | --event=EVENT] [<options>]
10
12 This command generates and displays a performance counter profile in
13 real time.
14
16 -a, --all-cpus
17 System-wide collection. (default)
18 -c <count>, --count=<count>
20 Event period to sample.
21 -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 -d <seconds>, --delay=<seconds>
28 Number of seconds to delay between refreshes.
29 -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 in the form of rN
33 where N is a hexadecimal value that represents the raw register
34 encoding with the layout of the event control registers as
35 described by entries in
36 /sys/bus/event_sources/devices/cpu/format/*.
37 -E <entries>, --entries=<entries>
39 Display this many functions.
40 -f <count>, --count-filter=<count>
42 Only display functions with more events than this.
43 --group
45 Put the counters into a counter group.
46 --group-sort-idx
48 Sort the output by the event at the index n in group. If n is
49 invalid, sort by the first event. It can support multiple groups
50 with different amount of events. WARNING: This should be used on
51 grouped events.
52 -F <freq>, --freq=<freq>
54 Profile at this frequency. Use max to use the currently maximum
55 allowed frequency, i.e. the value in the
56 kernel.perf_event_max_sample_rate sysctl.
57 -i, --inherit
59 Child tasks do not inherit counters.
60 -k <path>, --vmlinux=<path>
62 Path to vmlinux. Required for annotation functionality.
63 --ignore-vmlinux
65 Ignore vmlinux files.
66 --kallsyms=<file>
68 kallsyms pathname
69 -m <pages>, --mmap-pages=<pages>
71 Number of mmap data pages (must be a power of two) or size
72 specification with appended unit character - B/K/M/G. The size is
73 rounded up to have nearest pages power of two value.
74 -p <pid>, --pid=<pid>
76 Profile events on existing Process ID (comma separated list).
77 -t <tid>, --tid=<tid>
79 Profile events on existing thread ID (comma separated list).
80 -u, --uid=
82 Record events in threads owned by uid. Name or number.
83 -r <priority>, --realtime=<priority>
85 Collect data with this RT SCHED_FIFO priority.
86 --sym-annotate=<symbol>
88 Annotate this symbol.
89 -K, --hide_kernel_symbols
91 Hide kernel symbols.
92 -U, --hide_user_symbols
94 Hide user symbols.
95 --demangle-kernel
97 Demangle kernel symbols.
98 -D, --dump-symtab
100 Dump the symbol table used for profiling.
101 -v, --verbose
103 Be more verbose (show counter open errors, etc).
104 -z, --zero
106 Zero history across display updates.
107 -s, --sort
109 Sort by key(s): pid, comm, dso, symbol, parent, srcline, weight,
110 local_weight, abort, in_tx, transaction, overhead, sample, period.
111 Please see description of --sort in the perf-report man page.
112 --fields=
114 Specify output field - multiple keys can be specified in CSV
115 format. Following fields are available: overhead, overhead_sys,
116 overhead_us, overhead_children, sample and period. Also it can
117 contain any sort key(s).
118 By default, every sort keys not specified in --field will be appended
120 automatically.
121 -n, --show-nr-samples
123 Show a column with the number of samples.
124 --show-total-period
126 Show a column with the sum of periods.
127 --dsos
129 Only consider symbols in these dsos. This option will affect the
130 percentage of the overhead column. See --percentage for more info.
131 --comms
133 Only consider symbols in these comms. This option will affect the
134 percentage of the overhead column. See --percentage for more info.
135 --symbols
137 Only consider these symbols. This option will affect the percentage
138 of the overhead column. See --percentage for more info.
139 -M, --disassembler-style=
141 Set disassembler style for objdump.
142 --prefix=PREFIX, --prefix-strip=N
144 Remove first N entries from source file path names in executables
145 and add PREFIX. This allows to display source code compiled on
146 systems with different file system layout.
147 --source
149 Interleave source code with assembly code. Enabled by default,
150 disable with --no-source.
151 --asm-raw
153 Show raw instruction encoding of assembly instructions.
154 -g
156 Enables call-graph (stack chain/backtrace) recording.
157 --call-graph [mode,type,min[,limit],order[,key][,branch]]
159 Setup and enable call-graph (stack chain/backtrace) recording,
160 implies -g. See --call-graph section in perf-record and perf-report
161 man pages for details.
162 --children
164 Accumulate callchain of children to parent entry so that then can
165 show up in the output. The output will have a new "Children" column
166 and will be sorted on the data. It requires -g/--call-graph option
167 enabled. See the ‘overhead calculation’ section for more details.
168 Enabled by default, disable with --no-children.
169 --max-stack
171 Set the stack depth limit when parsing the callchain, anything
172 beyond the specified depth will be ignored. This is a trade-off
173 between information loss and faster processing especially for
174 workloads that can have a very long callchain stack.
175 Default: /proc/sys/kernel/perf_event_max_stack when present, 127 otherwise.
177 --ignore-callees=<regex>
179 Ignore callees of the function(s) matching the given regex. This
180 has the effect of collecting the callers of each such function into
181 one place in the call-graph tree.
182 --percent-limit
184 Do not show entries which have an overhead under that percent.
185 (Default: 0).
186 --percentage
188 Determine how to display the overhead percentage of filtered
189 entries. Filters can be applied by --comms, --dsos and/or --symbols
190 options and Zoom operations on the TUI (thread, dso, etc).
191 "relative" means it's relative to filtered entries only so that the
193 sum of shown entries will be always 100%. "absolute" means it retains
194 the original value before and after the filter is applied.
195 -w, --column-widths=<width[,width...]>
197 Force each column width to the provided list, for large terminal
198 readability. 0 means no limit (default behavior).
199 --proc-map-timeout
201 When processing pre-existing threads /proc/XXX/mmap, it may take a
202 long time, because the file may be huge. A time out is needed in
203 such cases. This option sets the time out limit. The default value
204 is 500 ms.
205 -b, --branch-any
207 Enable taken branch stack sampling. Any type of taken branch may be
208 sampled. This is a shortcut for --branch-filter any. See
209 --branch-filter for more infos.
210 -j, --branch-filter
212 Enable taken branch stack sampling. Each sample captures a series
213 of consecutive taken branches. The number of branches captured with
214 each sample depends on the underlying hardware, the type of
215 branches of interest, and the executed code. It is possible to
216 select the types of branches captured by enabling filters. For a
217 full list of modifiers please see the perf record manpage.
218 The option requires at least one branch type among any, any_call, any_ret, ind_call, cond.
220 The privilege levels may be omitted, in which case, the privilege levels of the associated
221 event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege
222 levels are subject to permissions. When sampling on multiple events, branch stack sampling
223 is enabled for all the sampling events. The sampled branch type is the same for all events.
224 The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k
225 Note that this feature may not be available on all processors.
226 --raw-trace
228 When displaying traceevent output, do not use print fmt or plugins.
229 --hierarchy
231 Enable hierarchy output.
232 --overwrite
234 Enable this to use just the most recent records, which helps in
235 high core count machines such as Knights Landing/Mill, but right
236 now is disabled by default as the pausing used in this technique is
237 leading to loss of metadata events such as PERF_RECORD_MMAP which
238 makes perf top unable to resolve samples, leading to lots of
239 unknown samples appearing on the UI. Enable this if you are in such
240 machines and profiling a workload that doesn’t creates short lived
241 threads and/or doesn’t uses many executable mmap operations. Work
242 is being planed to solve this situation, till then, this will
243 remain disabled by default.
244 --force
246 Don’t do ownership validation.
247 --num-thread-synthesize
249 The number of threads to run when synthesizing events for existing
250 processes. By default, the number of threads equals to the number
251 of online CPUs.
252 --namespaces
254 Record events of type PERF_RECORD_NAMESPACES and display it with
255 the cgroup_id sort key.
256 -G name, --cgroup name
258 monitor only in the container (cgroup) called "name". This option
259 is available only in per-cpu mode. The cgroup filesystem must be
260 mounted. All threads belonging to container "name" are monitored
261 when they run on the monitored CPUs. Multiple cgroups can be
262 provided. Each cgroup is applied to the corresponding event, i.e.,
263 first cgroup to first event, second cgroup to second event and so
264 on. It is possible to provide an empty cgroup (monitor all the
265 time) using, e.g., -G foo,,bar. Cgroups must have corresponding
266 events, i.e., they always refer to events defined earlier on the
267 command line. If the user wants to track multiple events for a
268 specific cgroup, the user can use -e e1 -e e2 -G foo,foo or just
269 use -e e1 -e e2 -G foo.
270 --all-cgroups
272 Record events of type PERF_RECORD_CGROUP and display it with the
273 cgroup sort key.
274 --switch-on EVENT_NAME
276 Only consider events after this event is found.
277 E.g.:
279 Find out where broadcast packets are handled
281 perf probe -L icmp_rcv
283 Insert a probe there:
285 perf probe icmp_rcv:59
287 Start perf top and ask it to only consider the cycles events when a
289 broadcast packet arrives This will show a menu with two entries and
290 will start counting when a broadcast packet arrives:
291 perf top -e cycles,probe:icmp_rcv --switch-on=probe:icmp_rcv
293 Alternatively one can ask for --group and then two overhead columns
295 will appear, the first for cycles and the second for the switch-on event.
296 perf top --group -e cycles,probe:icmp_rcv --switch-on=probe:icmp_rcv
298 This may be interesting to measure a workload only after some initialization
300 phase is over, i.e. insert a perf probe at that point and use the above
301 examples replacing probe:icmp_rcv with the just-after-init probe.
302 --switch-off EVENT_NAME
304 Stop considering events after this event is found.
305 --show-on-off-events
307 Show the --switch-on/off events too. This has no effect in perf top
308 now but probably we’ll make the default not to show the
309 switch-on/off events on the --group mode and if there is only one
310 event besides the off/on ones, go straight to the histogram
311 browser, just like perf top with no events explicitly specified
312 does.
313 --stitch-lbr
315 Show callgraph with stitched LBRs, which may have more complete
316 callgraph. The option must be used with --call-graph lbr recording.
317 Disabled by default. In common cases with call stack overflows, it
318 can recreate better call stacks than the default lbr call stack
319 output. But this approach is not full proof. There can be cases
320 where it creates incorrect call stacks from incorrect matches. The
321 known limitations include exception handing such as setjmp/longjmp
322 will have calls/returns not match.
323
325 [d]
326 Display refresh delay.
327 [e]
329 Number of entries to display.
330 [E]
332 Event to display when multiple counters are active.
333 [f]
335 Profile display filter (>= hit count).
336 [F]
338 Annotation display filter (>= % of total).
339 [s]
341 Annotate symbol.
342 [S]
344 Stop annotation, return to full profile display.
345 [K]
347 Hide kernel symbols.
348 [U]
350 Hide user symbols.
351 [z]
353 Toggle event count zeroing across display updates.
354 [qQ]
356 Quit.
357 Pressing any unmapped key displays a menu, and prompts for input.
359
361 The overhead can be shown in two columns as Children and Self when perf
362 collects callchains. The self overhead is simply calculated by adding
363 all period values of the entry - usually a function (symbol). This is
364 the value that perf shows traditionally and sum of all the self
365 overhead values should be 100%.
366 The children overhead is calculated by adding all period values of the
368 child functions so that it can show the total overhead of the higher
369 level functions even if they don’t directly execute much. Children here
370 means functions that are called from another (parent) function.
371 It might be confusing that the sum of all the children overhead values
373 exceeds 100% since each of them is already an accumulation of self
374 overhead of its child functions. But with this enabled, users can find
375 which function has the most overhead even if samples are spread over
376 the children.
377 Consider the following example; there are three functions like below.
379 .ft C
382 void foo(void) {
383 /* do something */
384 }
385 void bar(void) {
387 /* do something */
388 foo();
389 }
390 int main(void) {
392 bar()
393 return 0;
394 }
395 .ft
396 In this case foo is a child of bar, and bar is an immediate child of
399 main so foo also is a child of main. In other words, main is a parent
400 of foo and bar, and bar is a parent of foo.
401 Suppose all samples are recorded in foo and bar only. When it’s
403 recorded with callchains the output will show something like below in
404 the usual (self-overhead-only) output of perf report:
405 .ft C
408 Overhead Symbol
409 ........ .....................
410 60.00% foo
411 |
412 --- foo
413 bar
414 main
415 __libc_start_main
416 40.00% bar
418 |
419 --- bar
420 main
421 __libc_start_main
422 .ft
423 When the --children option is enabled, the self overhead values of
426 child functions (i.e. foo and bar) are added to the parents to
427 calculate the children overhead. In this case the report could be
428 displayed as:
429 .ft C
432 Children Self Symbol
433 ........ ........ ....................
434 100.00% 0.00% __libc_start_main
435 |
436 --- __libc_start_main
437 100.00% 0.00% main
439 |
440 --- main
441 __libc_start_main
442 100.00% 40.00% bar
444 |
445 --- bar
446 main
447 __libc_start_main
448 60.00% 60.00% foo
450 |
451 --- foo
452 bar
453 main
454 __libc_start_main
455 .ft
456 In the above output, the self overhead of foo (60%) was add to the
459 children overhead of bar, main and __libc_start_main. Likewise, the
460 self overhead of bar (40%) was added to the children overhead of main
461 and \_\_libc_start_main.
462 So \_\_libc_start_main and main are shown first since they have same
464 (100%) children overhead (even though they have zero self overhead) and
465 they are the parents of foo and bar.
466 Since v3.16 the children overhead is shown by default and the output is
468 sorted by its values. The children overhead is disabled by specifying
469 --no-children option on the command line or by adding report.children =
470 false or top.children = false in the perf config file.
471
473 perf-stat(1), perf-list(1), perf-report(1)
474perf 06/14/2022 PERF-TOP(1)