1PERF-REPORT(1) perf Manual PERF-REPORT(1)
2
6 perf-report - Read perf.data (created by perf record) and display the
7 profile
8
10 perf report [-i <file> | --input=file]
11
13 This command displays the performance counter profile information
14 recorded via perf record.
15
17 -i, --input=
18 Input file name. (default: perf.data unless stdin is a fifo)
19 -v, --verbose
21 Be more verbose. (show symbol address, etc)
22 -q, --quiet
24 Do not show any message. (Suppress -v)
25 -n, --show-nr-samples
27 Show the number of samples for each symbol
28 --show-cpu-utilization
30 Show sample percentage for different cpu modes.
31 -T, --threads
33 Show per-thread event counters. The input data file should be
34 recorded with -s option.
35 -c, --comms=
37 Only consider symbols in these comms. CSV that understands
38 file://filename entries. This option will affect the percentage of
39 the overhead column. See --percentage for more info.
40 --pid=
42 Only show events for given process ID (comma separated list).
43 --tid=
45 Only show events for given thread ID (comma separated list).
46 -d, --dsos=
48 Only consider symbols in these dsos. CSV that understands
49 file://filename entries. This option will affect the percentage of
50 the overhead column. See --percentage for more info.
51 -S, --symbols=
53 Only consider these symbols. CSV that understands file://filename
54 entries. This option will affect the percentage of the overhead
55 column. See --percentage for more info.
56 --symbol-filter=
58 Only show symbols that match (partially) with this filter.
59 -U, --hide-unresolved
61 Only display entries resolved to a symbol.
62 -s, --sort=
64 Sort histogram entries by given key(s) - multiple keys can be
65 specified in CSV format. Following sort keys are available: pid,
66 comm, dso, symbol, parent, cpu, socket, srcline, weight,
67 local_weight, cgroup_id.
68 Each key has following meaning:
70 · comm: command (name) of the task which can be read via
72 /proc/<pid>/comm
73 · pid: command and tid of the task
75 · dso: name of library or module executed at the time of sample
77 · dso_size: size of library or module executed at the time of
79 sample
80 · symbol: name of function executed at the time of sample
82 · symbol_size: size of function executed at the time of sample
84 · parent: name of function matched to the parent regex filter.
86 Unmatched entries are displayed as "[other]".
87 · cpu: cpu number the task ran at the time of sample
89 · socket: processor socket number the task ran at the time of
91 sample
92 · srcline: filename and line number executed at the time of
94 sample. The DWARF debugging info must be provided.
95 · srcfile: file name of the source file of the same. Requires
97 dwarf information.
98 · weight: Event specific weight, e.g. memory latency or
100 transaction abort cost. This is the global weight.
101 · local_weight: Local weight version of the weight above.
103 · cgroup_id: ID derived from cgroup namespace device and inode
105 numbers.
106 · transaction: Transaction abort flags.
108 · overhead: Overhead percentage of sample
110 · overhead_sys: Overhead percentage of sample running in system
112 mode
113 · overhead_us: Overhead percentage of sample running in user mode
115 · overhead_guest_sys: Overhead percentage of sample running in
117 system mode on guest machine
118 · overhead_guest_us: Overhead percentage of sample running in
120 user mode on guest machine
121 · sample: Number of sample
123 · period: Raw number of event count of sample
125 By default, comm, dso and symbol keys are used.
127 (i.e. --sort comm,dso,symbol)
128 If --branch-stack option is used, following sort keys are also
130 available:
131 · dso_from: name of library or module branched from
133 · dso_to: name of library or module branched to
135 · symbol_from: name of function branched from
137 · symbol_to: name of function branched to
139 · srcline_from: source file and line branched from
141 · srcline_to: source file and line branched to
143 · mispredict: "N" for predicted branch, "Y" for mispredicted
145 branch
146 · in_tx: branch in TSX transaction
148 · abort: TSX transaction abort.
150 · cycles: Cycles in basic block
152 And default sort keys are changed to comm, dso_from, symbol_from, dso_to
154 and symbol_to, see '--branch-stack'.
155 If the --mem-mode option is used, the following sort keys are also available
157 (incompatible with --branch-stack):
158 symbol_daddr, dso_daddr, locked, tlb, mem, snoop, dcacheline.
159 · symbol_daddr: name of data symbol being executed on at the time
161 of sample
162 · dso_daddr: name of library or module containing the data being
164 executed on at the time of the sample
165 · locked: whether the bus was locked at the time of the sample
167 · tlb: type of tlb access for the data at the time of the sample
169 · mem: type of memory access for the data at the time of the
171 sample
172 · snoop: type of snoop (if any) for the data at the time of the
174 sample
175 · dcacheline: the cacheline the data address is on at the time of
177 the sample
178 · phys_daddr: physical address of data being executed on at the
180 time of sample
181 And the default sort keys are changed to local_weight, mem, sym, dso,
183 symbol_daddr, dso_daddr, snoop, tlb, locked, see '--mem-mode'.
184 If the data file has tracepoint event(s), following (dynamic) sort keys
186 are also available:
187 trace, trace_fields, [<event>.]<field>[/raw]
188 · trace: pretty printed trace output in a single column
190 · trace_fields: fields in tracepoints in separate columns
192 · <field name>: optional event and field name for a specific
194 field
195 The last form consists of event and field names. If event name is
197 omitted, it searches all events for matching field name. The matched
198 field will be shown only for the event has the field. The event name
199 supports substring match so user doesn't need to specify full subsystem
200 and event name everytime. For example, 'sched:sched_switch' event can
201 be shortened to 'switch' as long as it's not ambiguous. Also event can
202 be specified by its index (starting from 1) preceded by the '%'.
203 So '%1' is the first event, '%2' is the second, and so on.
204 The field name can have '/raw' suffix which disables pretty printing
206 and shows raw field value like hex numbers. The --raw-trace option
207 has the same effect for all dynamic sort keys.
208 The default sort keys are changed to 'trace' if all events in the data
210 file are tracepoint.
211 -F, --fields=
213 Specify output field - multiple keys can be specified in CSV
214 format. Following fields are available: overhead, overhead_sys,
215 overhead_us, overhead_children, sample and period. Also it can
216 contain any sort key(s).
217 By default, every sort keys not specified in -F will be appended
219 automatically.
220 If the keys starts with a prefix '+', then it will append the specified
222 field(s) to the default field order. For example: perf report -F +period,sample.
223 -p, --parent=<regex>
225 A regex filter to identify parent. The parent is a caller of this
226 function and searched through the callchain, thus it requires
227 callchain information recorded. The pattern is in the extended
228 regex format and defaults to "^sys_|^do_page_fault", see --sort
229 parent.
230 -x, --exclude-other
232 Only display entries with parent-match.
233 -w, --column-widths=<width[,width...]>
235 Force each column width to the provided list, for large terminal
236 readability. 0 means no limit (default behavior).
237 -t, --field-separator=
239 Use a special separator character and don’t pad with spaces,
240 replacing all occurrences of this separator in symbol names (and
241 other output) with a . character, that thus it’s the only non
242 valid separator.
243 -D, --dump-raw-trace
245 Dump raw trace in ASCII.
246 -g,
248 --call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>
249 Display call chains using type, min percent threshold, print limit,
250 call order, sort key, optional branch and value. Note that ordering
251 is not fixed so any parameter can be given in an arbitrary order.
252 One exception is the print_limit which should be preceded by
253 threshold.
254 print_type can be either:
256 - flat: single column, linear exposure of call chains.
257 - graph: use a graph tree, displaying absolute overhead rates. (default)
258 - fractal: like graph, but displays relative rates. Each branch of
259 the tree is considered as a new profiled object.
260 - folded: call chains are displayed in a line, separated by semicolons
261 - none: disable call chain display.
262 threshold is a percentage value which specifies a minimum percent to be
264 included in the output call graph. Default is 0.5 (%).
265 print_limit is only applied when stdio interface is used. It's to limit
267 number of call graph entries in a single hist entry. Note that it needs
268 to be given after threshold (but not necessarily consecutive).
269 Default is 0 (unlimited).
270 order can be either:
272 - callee: callee based call graph.
273 - caller: inverted caller based call graph.
274 Default is 'caller' when --children is used, otherwise 'callee'.
275 sort_key can be:
277 - function: compare on functions (default)
278 - address: compare on individual code addresses
279 - srcline: compare on source filename and line number
280 branch can be:
282 - branch: include last branch information in callgraph when available.
283 Usually more convenient to use --branch-history for this.
284 value can be:
286 - percent: diplay overhead percent (default)
287 - period: display event period
288 - count: display event count
289 --children
291 Accumulate callchain of children to parent entry so that then can
292 show up in the output. The output will have a new "Children" column
293 and will be sorted on the data. It requires callchains are
294 recorded. See the ‘overhead calculation’ section for more details.
295 Enabled by default, disable with --no-children.
296 --max-stack
298 Set the stack depth limit when parsing the callchain, anything
299 beyond the specified depth will be ignored. This is a trade-off
300 between information loss and faster processing especially for
301 workloads that can have a very long callchain stack. Note that when
302 using the --itrace option the synthesized callchain size will
303 override this value if the synthesized callchain size is bigger.
304 Default: 127
306 -G, --inverted
308 alias for inverted caller based call graph.
309 --ignore-callees=<regex>
311 Ignore callees of the function(s) matching the given regex. This
312 has the effect of collecting the callers of each such function into
313 one place in the call-graph tree.
314 --pretty=<key>
316 Pretty printing style. key: normal, raw
317 --stdio
319 Use the stdio interface.
320 --stdio-color
322 always, never or auto, allowing configuring color output via the
323 command line, in addition to via "color.ui" .perfconfig. Use
324 --stdio-color always to generate color even when redirecting to a
325 pipe or file. Using just --stdio-color is equivalent to using
326 always.
327 --tui
329 Use the TUI interface, that is integrated with annotate and allows
330 zooming into DSOs or threads, among other features. Use of --tui
331 requires a tty, if one is not present, as when piping to other
332 commands, the stdio interface is used.
333 --gtk
335 Use the GTK2 interface.
336 -k, --vmlinux=<file>
338 vmlinux pathname
339 --ignore-vmlinux
341 Ignore vmlinux files.
342 --kallsyms=<file>
344 kallsyms pathname
345 -m, --modules
347 Load module symbols. WARNING: This should only be used with -k and
348 a LIVE kernel.
349 -f, --force
351 Don’t do ownership validation.
352 --symfs=<directory>
354 Look for files with symbols relative to this directory.
355 -C, --cpu
357 Only report samples for the list of CPUs provided. Multiple CPUs
358 can be provided as a comma-separated list with no space: 0,1.
359 Ranges of CPUs are specified with -: 0-2. Default is to report
360 samples on all CPUs.
361 -M, --disassembler-style=
363 Set disassembler style for objdump.
364 --source
366 Interleave source code with assembly code. Enabled by default,
367 disable with --no-source.
368 --asm-raw
370 Show raw instruction encoding of assembly instructions.
371 --show-total-period
373 Show a column with the sum of periods.
374 -I, --show-info
376 Display extended information about the perf.data file. This adds
377 information which may be very large and thus may clutter the
378 display. It currently includes: cpu and numa topology of the host
379 system.
380 -b, --branch-stack
382 Use the addresses of sampled taken branches instead of the
383 instruction address to build the histograms. To generate meaningful
384 output, the perf.data file must have been obtained using perf
385 record -b or perf record --branch-filter xxx where xxx is a branch
386 filter option. perf report is able to auto-detect whether a
387 perf.data file contains branch stacks and it will automatically
388 switch to the branch view mode, unless --no-branch-stack is used.
389 --branch-history
391 Add the addresses of sampled taken branches to the callstack. This
392 allows to examine the path the program took to each sample. The
393 data collection must have used -b (or -j) and -g.
394 --objdump=<path>
396 Path to objdump binary.
397 --group
399 Show event group information together. It forces group output also
400 if there are no groups defined in data file.
401 --demangle
403 Demangle symbol names to human readable form. It’s enabled by
404 default, disable with --no-demangle.
405 --demangle-kernel
407 Demangle kernel symbol names to human readable form (for C++
408 kernels).
409 --mem-mode
411 Use the data addresses of samples in addition to instruction
412 addresses to build the histograms. To generate meaningful output,
413 the perf.data file must have been obtained using perf record -d -W
414 and using a special event -e cpu/mem-loads/p or -e
415 cpu/mem-stores/p. See perf mem for simpler access.
416 --percent-limit
418 Do not show entries which have an overhead under that percent.
419 (Default: 0). Note that this option also sets the percent limit
420 (threshold) of callchains. However the default value of callchain
421 threshold is different than the default value of hist entries.
422 Please see the --call-graph option for details.
423 --percentage
425 Determine how to display the overhead percentage of filtered
426 entries. Filters can be applied by --comms, --dsos and/or --symbols
427 options and Zoom operations on the TUI (thread, dso, etc).
428 "relative" means it's relative to filtered entries only so that the
430 sum of shown entries will be always 100%. "absolute" means it retains
431 the original value before and after the filter is applied.
432 --header
434 Show header information in the perf.data file. This includes
435 various information like hostname, OS and perf version, cpu/mem
436 info, perf command line, event list and so on. Currently only
437 --stdio output supports this feature.
438 --header-only
440 Show only perf.data header (forces --stdio).
441 --time
443 Only analyze samples within given time window: <start>,<stop>.
444 Times have the format seconds.microseconds. If start is not given
445 (i.e., time string is ,x.y) then analysis starts at the beginning
446 of the file. If stop time is not given (i.e, time string is x.y,)
447 then analysis goes to end of file.
448 Also support time percent with multiple time range. Time string is
450 'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'.
451 For example:
453 Select the second 10% time slice:
454 perf report --time 10%/2
456 Select from 0% to 10% time slice:
458 perf report --time 0%-10%
460 Select the first and second 10% time slices:
462 perf report --time 10%/1,10%/2
464 Select from 0% to 10% and 30% to 40% slices:
466 perf report --time 0%-10%,30%-40%
468 --itrace
470 Options for decoding instruction tracing data. The options are:
471 i synthesize instructions events
473 b synthesize branches events
474 c synthesize branches events (calls only)
475 r synthesize branches events (returns only)
476 x synthesize transactions events
477 w synthesize ptwrite events
478 p synthesize power events
479 e synthesize error events
480 d create a debug log
481 g synthesize a call chain (use with i or x)
482 l synthesize last branch entries (use with i or x)
483 s skip initial number of events
484 The default is all events i.e. the same as --itrace=ibxwpe
486 In addition, the period (default 100000) for instructions events
488 can be specified in units of:
489 i instructions
491 t ticks
492 ms milliseconds
493 us microseconds
494 ns nanoseconds (default)
495 Also the call chain size (default 16, max. 1024) for instructions or
497 transactions events can be specified.
498 Also the number of last branch entries (default 64, max. 1024) for
500 instructions or transactions events can be specified.
501 It is also possible to skip events generated (instructions, branches, transactions,
503 ptwrite, power) at the beginning. This is useful to ignore initialization code.
504 --itrace=i0nss1000000
506 skips the first million instructions.
508 To disable decoding entirely, use --no-itrace.
510 --full-source-path
512 Show the full path for source files for srcline output.
513 --show-ref-call-graph
515 When multiple events are sampled, it may not be needed to collect
516 callgraphs for all of them. The sample sites are usually nearby,
517 and it’s enough to collect the callgraphs on a reference event. So
518 user can use "call-graph=no" event modifier to disable callgraph
519 for other events to reduce the overhead. However, perf report
520 cannot show callgraphs for the event which disable the callgraph.
521 This option extends the perf report to show reference callgraphs,
522 which collected by reference event, in no callgraph event.
523 --socket-filter
525 Only report the samples on the processor socket that match with
526 this filter
527 --raw-trace
529 When displaying traceevent output, do not use print fmt or plugins.
530 --hierarchy
532 Enable hierarchical output.
533 --inline
535 If a callgraph address belongs to an inlined function, the inline
536 stack will be printed. Each entry is function name or file/line.
537 Enabled by default, disable with --no-inline.
538 --mmaps
540 Show --tasks output plus mmap information in a format similar to
541 /proc/<PID>/maps.
542 Please note that not all mmaps are stored, options affecting which ones
544 are include 'perf record --data', for instance.
545 --stats
547 Display overall events statistics without any further processing.
548 (like the one at the end of the perf report -D command)
549 --tasks
551 Display monitored tasks stored in perf data. Displaying
552 pid/tid/ppid plus the command string aligned to distinguish parent
553 and child tasks.
554
556 The overhead can be shown in two columns as Children and Self when perf
557 collects callchains. The self overhead is simply calculated by adding
558 all period values of the entry - usually a function (symbol). This is
559 the value that perf shows traditionally and sum of all the self
560 overhead values should be 100%.
561 The children overhead is calculated by adding all period values of the
563 child functions so that it can show the total overhead of the higher
564 level functions even if they don’t directly execute much. Children here
565 means functions that are called from another (parent) function.
566 It might be confusing that the sum of all the children overhead values
568 exceeds 100% since each of them is already an accumulation of self
569 overhead of its child functions. But with this enabled, users can find
570 which function has the most overhead even if samples are spread over
571 the children.
572 Consider the following example; there are three functions like below.
574 .ft C
577 void foo(void) {
578 /* do something */
579 }
580 void bar(void) {
582 /* do something */
583 foo();
584 }
585 int main(void) {
587 bar()
588 return 0;
589 }
590 .ft
591 In this case foo is a child of bar, and bar is an immediate child of
594 main so foo also is a child of main. In other words, main is a parent
595 of foo and bar, and bar is a parent of foo.
596 Suppose all samples are recorded in foo and bar only. When it’s
598 recorded with callchains the output will show something like below in
599 the usual (self-overhead-only) output of perf report:
600 .ft C
603 Overhead Symbol
604 ........ .....................
605 60.00% foo
606 |
607 --- foo
608 bar
609 main
610 __libc_start_main
611 40.00% bar
613 |
614 --- bar
615 main
616 __libc_start_main
617 .ft
618 When the --children option is enabled, the self overhead values of
621 child functions (i.e. foo and bar) are added to the parents to
622 calculate the children overhead. In this case the report could be
623 displayed as:
624 .ft C
627 Children Self Symbol
628 ........ ........ ....................
629 100.00% 0.00% __libc_start_main
630 |
631 --- __libc_start_main
632 100.00% 0.00% main
634 |
635 --- main
636 __libc_start_main
637 100.00% 40.00% bar
639 |
640 --- bar
641 main
642 __libc_start_main
643 60.00% 60.00% foo
645 |
646 --- foo
647 bar
648 main
649 __libc_start_main
650 .ft
651 In the above output, the self overhead of foo (60%) was add to the
654 children overhead of bar, main and __libc_start_main. Likewise, the
655 self overhead of bar (40%) was added to the children overhead of main
656 and \_\_libc_start_main.
657 So \_\_libc_start_main and main are shown first since they have same
659 (100%) children overhead (even though they have zero self overhead) and
660 they are the parents of foo and bar.
661 Since v3.16 the children overhead is shown by default and the output is
663 sorted by its values. The children overhead is disabled by specifying
664 --no-children option on the command line or by adding report.children =
665 false or top.children = false in the perf config file.
666
668 perf-stat(1), perf-annotate(1), perf-record(1)
669perf 09/24/2019 PERF-REPORT(1)