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 samples. 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 · time: Separate the samples by time stamp with the resolution
127 specified by --time-quantum (default 100ms). Specify with
128 overhead and before it.
129 By default, comm, dso and symbol keys are used.
131 (i.e. --sort comm,dso,symbol)
132 If --branch-stack option is used, following sort keys are also
134 available:
135 · dso_from: name of library or module branched from
137 · dso_to: name of library or module branched to
139 · symbol_from: name of function branched from
141 · symbol_to: name of function branched to
143 · srcline_from: source file and line branched from
145 · srcline_to: source file and line branched to
147 · mispredict: "N" for predicted branch, "Y" for mispredicted
149 branch
150 · in_tx: branch in TSX transaction
152 · abort: TSX transaction abort.
154 · cycles: Cycles in basic block
156 And default sort keys are changed to comm, dso_from, symbol_from, dso_to
158 and symbol_to, see '--branch-stack'.
159 When the sort key symbol is specified, columns "IPC" and "IPC Coverage"
161 are enabled automatically. Column "IPC" reports the average IPC per function
162 and column "IPC coverage" reports the percentage of instructions with
163 sampled IPC in this function. IPC means Instruction Per Cycle. If it's low,
164 it indicates there may be a performance bottleneck when the function is
165 executed, such as a memory access bottleneck. If a function has high overhead
166 and low IPC, it's worth further analyzing it to optimize its performance.
167 If the --mem-mode option is used, the following sort keys are also available
169 (incompatible with --branch-stack):
170 symbol_daddr, dso_daddr, locked, tlb, mem, snoop, dcacheline.
171 · symbol_daddr: name of data symbol being executed on at the time
173 of sample
174 · dso_daddr: name of library or module containing the data being
176 executed on at the time of the sample
177 · locked: whether the bus was locked at the time of the sample
179 · tlb: type of tlb access for the data at the time of the sample
181 · mem: type of memory access for the data at the time of the
183 sample
184 · snoop: type of snoop (if any) for the data at the time of the
186 sample
187 · dcacheline: the cacheline the data address is on at the time of
189 the sample
190 · phys_daddr: physical address of data being executed on at the
192 time of sample
193 And the default sort keys are changed to local_weight, mem, sym, dso,
195 symbol_daddr, dso_daddr, snoop, tlb, locked, see '--mem-mode'.
196 If the data file has tracepoint event(s), following (dynamic) sort keys
198 are also available:
199 trace, trace_fields, [<event>.]<field>[/raw]
200 · trace: pretty printed trace output in a single column
202 · trace_fields: fields in tracepoints in separate columns
204 · <field name>: optional event and field name for a specific
206 field
207 The last form consists of event and field names. If event name is
209 omitted, it searches all events for matching field name. The matched
210 field will be shown only for the event has the field. The event name
211 supports substring match so user doesn't need to specify full subsystem
212 and event name everytime. For example, 'sched:sched_switch' event can
213 be shortened to 'switch' as long as it's not ambiguous. Also event can
214 be specified by its index (starting from 1) preceded by the '%'.
215 So '%1' is the first event, '%2' is the second, and so on.
216 The field name can have '/raw' suffix which disables pretty printing
218 and shows raw field value like hex numbers. The --raw-trace option
219 has the same effect for all dynamic sort keys.
220 The default sort keys are changed to 'trace' if all events in the data
222 file are tracepoint.
223 -F, --fields=
225 Specify output field - multiple keys can be specified in CSV
226 format. Following fields are available: overhead, overhead_sys,
227 overhead_us, overhead_children, sample and period. Also it can
228 contain any sort key(s).
229 By default, every sort keys not specified in -F will be appended
231 automatically.
232 If the keys starts with a prefix '+', then it will append the specified
234 field(s) to the default field order. For example: perf report -F +period,sample.
235 -p, --parent=<regex>
237 A regex filter to identify parent. The parent is a caller of this
238 function and searched through the callchain, thus it requires
239 callchain information recorded. The pattern is in the extended
240 regex format and defaults to "^sys_|^do_page_fault", see --sort
241 parent.
242 -x, --exclude-other
244 Only display entries with parent-match.
245 -w, --column-widths=<width[,width...]>
247 Force each column width to the provided list, for large terminal
248 readability. 0 means no limit (default behavior).
249 -t, --field-separator=
251 Use a special separator character and don’t pad with spaces,
252 replacing all occurrences of this separator in symbol names (and
253 other output) with a . character, that thus it’s the only non
254 valid separator.
255 -D, --dump-raw-trace
257 Dump raw trace in ASCII.
258 -g,
260 --call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>
261 Display call chains using type, min percent threshold, print limit,
262 call order, sort key, optional branch and value. Note that ordering
263 is not fixed so any parameter can be given in an arbitrary order.
264 One exception is the print_limit which should be preceded by
265 threshold.
266 print_type can be either:
268 - flat: single column, linear exposure of call chains.
269 - graph: use a graph tree, displaying absolute overhead rates. (default)
270 - fractal: like graph, but displays relative rates. Each branch of
271 the tree is considered as a new profiled object.
272 - folded: call chains are displayed in a line, separated by semicolons
273 - none: disable call chain display.
274 threshold is a percentage value which specifies a minimum percent to be
276 included in the output call graph. Default is 0.5 (%).
277 print_limit is only applied when stdio interface is used. It's to limit
279 number of call graph entries in a single hist entry. Note that it needs
280 to be given after threshold (but not necessarily consecutive).
281 Default is 0 (unlimited).
282 order can be either:
284 - callee: callee based call graph.
285 - caller: inverted caller based call graph.
286 Default is 'caller' when --children is used, otherwise 'callee'.
287 sort_key can be:
289 - function: compare on functions (default)
290 - address: compare on individual code addresses
291 - srcline: compare on source filename and line number
292 branch can be:
294 - branch: include last branch information in callgraph when available.
295 Usually more convenient to use --branch-history for this.
296 value can be:
298 - percent: display overhead percent (default)
299 - period: display event period
300 - count: display event count
301 --children
303 Accumulate callchain of children to parent entry so that then can
304 show up in the output. The output will have a new "Children" column
305 and will be sorted on the data. It requires callchains are
306 recorded. See the ‘overhead calculation’ section for more details.
307 Enabled by default, disable with --no-children.
308 --max-stack
310 Set the stack depth limit when parsing the callchain, anything
311 beyond the specified depth will be ignored. This is a trade-off
312 between information loss and faster processing especially for
313 workloads that can have a very long callchain stack. Note that when
314 using the --itrace option the synthesized callchain size will
315 override this value if the synthesized callchain size is bigger.
316 Default: 127
318 -G, --inverted
320 alias for inverted caller based call graph.
321 --ignore-callees=<regex>
323 Ignore callees of the function(s) matching the given regex. This
324 has the effect of collecting the callers of each such function into
325 one place in the call-graph tree.
326 --pretty=<key>
328 Pretty printing style. key: normal, raw
329 --stdio
331 Use the stdio interface.
332 --stdio-color
334 always, never or auto, allowing configuring color output via the
335 command line, in addition to via "color.ui" .perfconfig. Use
336 --stdio-color always to generate color even when redirecting to a
337 pipe or file. Using just --stdio-color is equivalent to using
338 always.
339 --tui
341 Use the TUI interface, that is integrated with annotate and allows
342 zooming into DSOs or threads, among other features. Use of --tui
343 requires a tty, if one is not present, as when piping to other
344 commands, the stdio interface is used.
345 --gtk
347 Use the GTK2 interface.
348 -k, --vmlinux=<file>
350 vmlinux pathname
351 --ignore-vmlinux
353 Ignore vmlinux files.
354 --kallsyms=<file>
356 kallsyms pathname
357 -m, --modules
359 Load module symbols. WARNING: This should only be used with -k and
360 a LIVE kernel.
361 -f, --force
363 Don’t do ownership validation.
364 --symfs=<directory>
366 Look for files with symbols relative to this directory.
367 -C, --cpu
369 Only report samples for the list of CPUs provided. Multiple CPUs
370 can be provided as a comma-separated list with no space: 0,1.
371 Ranges of CPUs are specified with -: 0-2. Default is to report
372 samples on all CPUs.
373 -M, --disassembler-style=
375 Set disassembler style for objdump.
376 --source
378 Interleave source code with assembly code. Enabled by default,
379 disable with --no-source.
380 --asm-raw
382 Show raw instruction encoding of assembly instructions.
383 --show-total-period
385 Show a column with the sum of periods.
386 -I, --show-info
388 Display extended information about the perf.data file. This adds
389 information which may be very large and thus may clutter the
390 display. It currently includes: cpu and numa topology of the host
391 system.
392 -b, --branch-stack
394 Use the addresses of sampled taken branches instead of the
395 instruction address to build the histograms. To generate meaningful
396 output, the perf.data file must have been obtained using perf
397 record -b or perf record --branch-filter xxx where xxx is a branch
398 filter option. perf report is able to auto-detect whether a
399 perf.data file contains branch stacks and it will automatically
400 switch to the branch view mode, unless --no-branch-stack is used.
401 --branch-history
403 Add the addresses of sampled taken branches to the callstack. This
404 allows to examine the path the program took to each sample. The
405 data collection must have used -b (or -j) and -g.
406 --objdump=<path>
408 Path to objdump binary.
409 --prefix=PREFIX, --prefix-strip=N
411 Remove first N entries from source file path names in executables
412 and add PREFIX. This allows to display source code compiled on
413 systems with different file system layout.
414 --group
416 Show event group information together. It forces group output also
417 if there are no groups defined in data file.
418 --demangle
420 Demangle symbol names to human readable form. It’s enabled by
421 default, disable with --no-demangle.
422 --demangle-kernel
424 Demangle kernel symbol names to human readable form (for C++
425 kernels).
426 --mem-mode
428 Use the data addresses of samples in addition to instruction
429 addresses to build the histograms. To generate meaningful output,
430 the perf.data file must have been obtained using perf record -d -W
431 and using a special event -e cpu/mem-loads/p or -e
432 cpu/mem-stores/p. See perf mem for simpler access.
433 --percent-limit
435 Do not show entries which have an overhead under that percent.
436 (Default: 0). Note that this option also sets the percent limit
437 (threshold) of callchains. However the default value of callchain
438 threshold is different than the default value of hist entries.
439 Please see the --call-graph option for details.
440 --percentage
442 Determine how to display the overhead percentage of filtered
443 entries. Filters can be applied by --comms, --dsos and/or --symbols
444 options and Zoom operations on the TUI (thread, dso, etc).
445 "relative" means it's relative to filtered entries only so that the
447 sum of shown entries will be always 100%. "absolute" means it retains
448 the original value before and after the filter is applied.
449 --header
451 Show header information in the perf.data file. This includes
452 various information like hostname, OS and perf version, cpu/mem
453 info, perf command line, event list and so on. Currently only
454 --stdio output supports this feature.
455 --header-only
457 Show only perf.data header (forces --stdio).
458 --time
460 Only analyze samples within given time window: <start>,<stop>.
461 Times have the format seconds.nanoseconds. If start is not given
462 (i.e. time string is ,x.y) then analysis starts at the beginning of
463 the file. If stop time is not given (i.e. time string is x.y,) then
464 analysis goes to end of file. Multiple ranges can be separated by
465 spaces, which requires the argument to be quoted e.g. --time
466 "1234.567,1234.789 1235,"
467 Also support time percent with multiple time ranges. Time string is
469 'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'.
470 For example:
472 Select the second 10% time slice:
473 perf report --time 10%/2
475 Select from 0% to 10% time slice:
477 perf report --time 0%-10%
479 Select the first and second 10% time slices:
481 perf report --time 10%/1,10%/2
483 Select from 0% to 10% and 30% to 40% slices:
485 perf report --time 0%-10%,30%-40%
487 --switch-on EVENT_NAME
489 Only consider events after this event is found.
490 This may be interesting to measure a workload only after some initialization
492 phase is over, i.e. insert a perf probe at that point and then using this
493 option with that probe.
494 --switch-off EVENT_NAME
496 Stop considering events after this event is found.
497 --show-on-off-events
499 Show the --switch-on/off events too. This has no effect in perf
500 report now but probably we’ll make the default not to show the
501 switch-on/off events on the --group mode and if there is only one
502 event besides the off/on ones, go straight to the histogram
503 browser, just like perf report with no events explicitely specified
504 does.
505 --itrace
507 Options for decoding instruction tracing data. The options are:
508 i synthesize instructions events
510 b synthesize branches events
511 c synthesize branches events (calls only)
512 r synthesize branches events (returns only)
513 x synthesize transactions events
514 w synthesize ptwrite events
515 p synthesize power events
516 o synthesize other events recorded due to the use
517 of aux-output (refer to perf record)
518 e synthesize error events
519 d create a debug log
520 g synthesize a call chain (use with i or x)
521 l synthesize last branch entries (use with i or x)
522 s skip initial number of events
523 The default is all events i.e. the same as --itrace=ibxwpe,
525 except for perf script where it is --itrace=ce
526 In addition, the period (default 100000, except for perf script where it is 1)
528 for instructions events can be specified in units of:
529 i instructions
531 t ticks
532 ms milliseconds
533 us microseconds
534 ns nanoseconds (default)
535 Also the call chain size (default 16, max. 1024) for instructions or
537 transactions events can be specified.
538 Also the number of last branch entries (default 64, max. 1024) for
540 instructions or transactions events can be specified.
541 It is also possible to skip events generated (instructions, branches, transactions,
543 ptwrite, power) at the beginning. This is useful to ignore initialization code.
544 --itrace=i0nss1000000
546 skips the first million instructions.
548 To disable decoding entirely, use --no-itrace.
550 --full-source-path
552 Show the full path for source files for srcline output.
553 --show-ref-call-graph
555 When multiple events are sampled, it may not be needed to collect
556 callgraphs for all of them. The sample sites are usually nearby,
557 and it’s enough to collect the callgraphs on a reference event. So
558 user can use "call-graph=no" event modifier to disable callgraph
559 for other events to reduce the overhead. However, perf report
560 cannot show callgraphs for the event which disable the callgraph.
561 This option extends the perf report to show reference callgraphs,
562 which collected by reference event, in no callgraph event.
563 --socket-filter
565 Only report the samples on the processor socket that match with
566 this filter
567 --samples=N
569 Save N individual samples for each histogram entry to show context
570 in perf report tui browser.
571 --raw-trace
573 When displaying traceevent output, do not use print fmt or plugins.
574 --hierarchy
576 Enable hierarchical output.
577 --inline
579 If a callgraph address belongs to an inlined function, the inline
580 stack will be printed. Each entry is function name or file/line.
581 Enabled by default, disable with --no-inline.
582 --mmaps
584 Show --tasks output plus mmap information in a format similar to
585 /proc/<PID>/maps.
586 Please note that not all mmaps are stored, options affecting which ones
588 are include 'perf record --data', for instance.
589 --ns
591 Show time stamps in nanoseconds.
592 --stats
594 Display overall events statistics without any further processing.
595 (like the one at the end of the perf report -D command)
596 --tasks
598 Display monitored tasks stored in perf data. Displaying
599 pid/tid/ppid plus the command string aligned to distinguish parent
600 and child tasks.
601 --percent-type
603 Set annotation percent type from following choices: global-period,
604 local-period, global-hits, local-hits
605 The local/global keywords set if the percentage is computed
607 in the scope of the function (local) or the whole data (global).
608 The period/hits keywords set the base the percentage is computed
609 on - the samples period or the number of samples (hits).
610 --time-quantum
612 Configure time quantum for time sort key. Default 100ms. Accepts s,
613 us, ms, ns units.
614 --total-cycles
616 When --total-cycles is specified, it supports sorting for all
617 blocks by Sampled Cycles%. This is useful to concentrate on the
618 globally hottest blocks. In output, there are some new columns:
619 'Sampled Cycles%' - block sampled cycles aggregation / total sampled cycles
621 'Sampled Cycles' - block sampled cycles aggregation
622 'Avg Cycles%' - block average sampled cycles / sum of total block average
623 sampled cycles
624 'Avg Cycles' - block average sampled cycles
625
627 The overhead can be shown in two columns as Children and Self when perf
628 collects callchains. The self overhead is simply calculated by adding
629 all period values of the entry - usually a function (symbol). This is
630 the value that perf shows traditionally and sum of all the self
631 overhead values should be 100%.
632 The children overhead is calculated by adding all period values of the
634 child functions so that it can show the total overhead of the higher
635 level functions even if they don’t directly execute much. Children here
636 means functions that are called from another (parent) function.
637 It might be confusing that the sum of all the children overhead values
639 exceeds 100% since each of them is already an accumulation of self
640 overhead of its child functions. But with this enabled, users can find
641 which function has the most overhead even if samples are spread over
642 the children.
643 Consider the following example; there are three functions like below.
645 .ft C
648 void foo(void) {
649 /* do something */
650 }
651 void bar(void) {
653 /* do something */
654 foo();
655 }
656 int main(void) {
658 bar()
659 return 0;
660 }
661 .ft
662 In this case foo is a child of bar, and bar is an immediate child of
665 main so foo also is a child of main. In other words, main is a parent
666 of foo and bar, and bar is a parent of foo.
667 Suppose all samples are recorded in foo and bar only. When it’s
669 recorded with callchains the output will show something like below in
670 the usual (self-overhead-only) output of perf report:
671 .ft C
674 Overhead Symbol
675 ........ .....................
676 60.00% foo
677 |
678 --- foo
679 bar
680 main
681 __libc_start_main
682 40.00% bar
684 |
685 --- bar
686 main
687 __libc_start_main
688 .ft
689 When the --children option is enabled, the self overhead values of
692 child functions (i.e. foo and bar) are added to the parents to
693 calculate the children overhead. In this case the report could be
694 displayed as:
695 .ft C
698 Children Self Symbol
699 ........ ........ ....................
700 100.00% 0.00% __libc_start_main
701 |
702 --- __libc_start_main
703 100.00% 0.00% main
705 |
706 --- main
707 __libc_start_main
708 100.00% 40.00% bar
710 |
711 --- bar
712 main
713 __libc_start_main
714 60.00% 60.00% foo
716 |
717 --- foo
718 bar
719 main
720 __libc_start_main
721 .ft
722 In the above output, the self overhead of foo (60%) was add to the
725 children overhead of bar, main and __libc_start_main. Likewise, the
726 self overhead of bar (40%) was added to the children overhead of main
727 and \_\_libc_start_main.
728 So \_\_libc_start_main and main are shown first since they have same
730 (100%) children overhead (even though they have zero self overhead) and
731 they are the parents of foo and bar.
732 Since v3.16 the children overhead is shown by default and the output is
734 sorted by its values. The children overhead is disabled by specifying
735 --no-children option on the command line or by adding report.children =
736 false or top.children = false in the perf config file.
737
739 perf-stat(1), perf-annotate(1), perf-record(1)
740perf 04/23/2020 PERF-REPORT(1)