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 warnings or messages. (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, addr.
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 • cgroup: cgroup pathname in the cgroupfs.
108 • transaction: Transaction abort flags.
110 • overhead: Overhead percentage of sample
112 • overhead_sys: Overhead percentage of sample running in system
114 mode
115 • overhead_us: Overhead percentage of sample running in user mode
117 • overhead_guest_sys: Overhead percentage of sample running in
119 system mode on guest machine
120 • overhead_guest_us: Overhead percentage of sample running in
122 user mode on guest machine
123 • sample: Number of sample
125 • period: Raw number of event count of sample
127 • time: Separate the samples by time stamp with the resolution
129 specified by --time-quantum (default 100ms). Specify with
130 overhead and before it.
131 • code_page_size: the code page size of sampled code address (ip)
133 • ins_lat: Instruction latency in core cycles. This is the global
135 instruction latency
136 • local_ins_lat: Local instruction latency version
138 • p_stage_cyc: On powerpc, this presents the number of cycles
140 spent in a pipeline stage. And currently supported only on
141 powerpc.
142 • addr: (Full) virtual address of the sampled instruction
144 By default, comm, dso and symbol keys are used.
146 (i.e. --sort comm,dso,symbol)
147 If --branch-stack option is used, following sort keys are also
149 available:
150 • dso_from: name of library or module branched from
152 • dso_to: name of library or module branched to
154 • symbol_from: name of function branched from
156 • symbol_to: name of function branched to
158 • srcline_from: source file and line branched from
160 • srcline_to: source file and line branched to
162 • mispredict: "N" for predicted branch, "Y" for mispredicted
164 branch
165 • in_tx: branch in TSX transaction
167 • abort: TSX transaction abort.
169 • cycles: Cycles in basic block
171 And default sort keys are changed to comm, dso_from, symbol_from, dso_to
173 and symbol_to, see '--branch-stack'.
174 When the sort key symbol is specified, columns "IPC" and "IPC Coverage"
176 are enabled automatically. Column "IPC" reports the average IPC per function
177 and column "IPC coverage" reports the percentage of instructions with
178 sampled IPC in this function. IPC means Instruction Per Cycle. If it's low,
179 it indicates there may be a performance bottleneck when the function is
180 executed, such as a memory access bottleneck. If a function has high overhead
181 and low IPC, it's worth further analyzing it to optimize its performance.
182 If the --mem-mode option is used, the following sort keys are also available
184 (incompatible with --branch-stack):
185 symbol_daddr, dso_daddr, locked, tlb, mem, snoop, dcacheline, blocked.
186 • symbol_daddr: name of data symbol being executed on at the time
188 of sample
189 • dso_daddr: name of library or module containing the data being
191 executed on at the time of the sample
192 • locked: whether the bus was locked at the time of the sample
194 • tlb: type of tlb access for the data at the time of the sample
196 • mem: type of memory access for the data at the time of the
198 sample
199 • snoop: type of snoop (if any) for the data at the time of the
201 sample
202 • dcacheline: the cacheline the data address is on at the time of
204 the sample
205 • phys_daddr: physical address of data being executed on at the
207 time of sample
208 • data_page_size: the data page size of data being executed on at
210 the time of sample
211 • blocked: reason of blocked load access for the data at the time
213 of the sample
214 And the default sort keys are changed to local_weight, mem, sym, dso,
216 symbol_daddr, dso_daddr, snoop, tlb, locked, blocked, local_ins_lat,
217 see '--mem-mode'.
218 If the data file has tracepoint event(s), following (dynamic) sort keys
220 are also available:
221 trace, trace_fields, [<event>.]<field>[/raw]
222 • trace: pretty printed trace output in a single column
224 • trace_fields: fields in tracepoints in separate columns
226 • <field name>: optional event and field name for a specific
228 field
229 The last form consists of event and field names. If event name is
231 omitted, it searches all events for matching field name. The matched
232 field will be shown only for the event has the field. The event name
233 supports substring match so user doesn't need to specify full subsystem
234 and event name everytime. For example, 'sched:sched_switch' event can
235 be shortened to 'switch' as long as it's not ambiguous. Also event can
236 be specified by its index (starting from 1) preceded by the '%'.
237 So '%1' is the first event, '%2' is the second, and so on.
238 The field name can have '/raw' suffix which disables pretty printing
240 and shows raw field value like hex numbers. The --raw-trace option
241 has the same effect for all dynamic sort keys.
242 The default sort keys are changed to 'trace' if all events in the data
244 file are tracepoint.
245 -F, --fields=
247 Specify output field - multiple keys can be specified in CSV
248 format. Following fields are available: overhead, overhead_sys,
249 overhead_us, overhead_children, sample and period. Also it can
250 contain any sort key(s).
251 By default, every sort keys not specified in -F will be appended
253 automatically.
254 If the keys starts with a prefix '+', then it will append the specified
256 field(s) to the default field order. For example: perf report -F +period,sample.
257 -p, --parent=<regex>
259 A regex filter to identify parent. The parent is a caller of this
260 function and searched through the callchain, thus it requires
261 callchain information recorded. The pattern is in the extended
262 regex format and defaults to "^sys_|^do_page_fault", see --sort
263 parent.
264 -x, --exclude-other
266 Only display entries with parent-match.
267 -w, --column-widths=<width[,width...]>
269 Force each column width to the provided list, for large terminal
270 readability. 0 means no limit (default behavior).
271 -t, --field-separator=
273 Use a special separator character and don’t pad with spaces,
274 replacing all occurrences of this separator in symbol names (and
275 other output) with a . character, that thus it’s the only non
276 valid separator.
277 -D, --dump-raw-trace
279 Dump raw trace in ASCII.
280 --disable-order
282 Disable raw trace ordering.
283 -g,
285 --call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>
286 Display call chains using type, min percent threshold, print limit,
287 call order, sort key, optional branch and value. Note that ordering
288 is not fixed so any parameter can be given in an arbitrary order.
289 One exception is the print_limit which should be preceded by
290 threshold.
291 print_type can be either:
293 - flat: single column, linear exposure of call chains.
294 - graph: use a graph tree, displaying absolute overhead rates. (default)
295 - fractal: like graph, but displays relative rates. Each branch of
296 the tree is considered as a new profiled object.
297 - folded: call chains are displayed in a line, separated by semicolons
298 - none: disable call chain display.
299 threshold is a percentage value which specifies a minimum percent to be
301 included in the output call graph. Default is 0.5 (%).
302 print_limit is only applied when stdio interface is used. It's to limit
304 number of call graph entries in a single hist entry. Note that it needs
305 to be given after threshold (but not necessarily consecutive).
306 Default is 0 (unlimited).
307 order can be either:
309 - callee: callee based call graph.
310 - caller: inverted caller based call graph.
311 Default is 'caller' when --children is used, otherwise 'callee'.
312 sort_key can be:
314 - function: compare on functions (default)
315 - address: compare on individual code addresses
316 - srcline: compare on source filename and line number
317 branch can be:
319 - branch: include last branch information in callgraph when available.
320 Usually more convenient to use --branch-history for this.
321 value can be:
323 - percent: display overhead percent (default)
324 - period: display event period
325 - count: display event count
326 --children
328 Accumulate callchain of children to parent entry so that then can
329 show up in the output. The output will have a new "Children" column
330 and will be sorted on the data. It requires callchains are
331 recorded. See the ‘overhead calculation’ section for more details.
332 Enabled by default, disable with --no-children.
333 --max-stack
335 Set the stack depth limit when parsing the callchain, anything
336 beyond the specified depth will be ignored. This is a trade-off
337 between information loss and faster processing especially for
338 workloads that can have a very long callchain stack. Note that when
339 using the --itrace option the synthesized callchain size will
340 override this value if the synthesized callchain size is bigger.
341 Default: 127
343 -G, --inverted
345 alias for inverted caller based call graph.
346 --ignore-callees=<regex>
348 Ignore callees of the function(s) matching the given regex. This
349 has the effect of collecting the callers of each such function into
350 one place in the call-graph tree.
351 --pretty=<key>
353 Pretty printing style. key: normal, raw
354 --stdio
356 Use the stdio interface.
357 --stdio-color
359 always, never or auto, allowing configuring color output via the
360 command line, in addition to via "color.ui" .perfconfig. Use
361 --stdio-color always to generate color even when redirecting to a
362 pipe or file. Using just --stdio-color is equivalent to using
363 always.
364 --tui
366 Use the TUI interface, that is integrated with annotate and allows
367 zooming into DSOs or threads, among other features. Use of --tui
368 requires a tty, if one is not present, as when piping to other
369 commands, the stdio interface is used.
370 --gtk
372 Use the GTK2 interface.
373 -k, --vmlinux=<file>
375 vmlinux pathname
376 --ignore-vmlinux
378 Ignore vmlinux files.
379 --kallsyms=<file>
381 kallsyms pathname
382 -m, --modules
384 Load module symbols. WARNING: This should only be used with -k and
385 a LIVE kernel.
386 -f, --force
388 Don’t do ownership validation.
389 --symfs=<directory>
391 Look for files with symbols relative to this directory.
392 -C, --cpu
394 Only report samples for the list of CPUs provided. Multiple CPUs
395 can be provided as a comma-separated list with no space: 0,1.
396 Ranges of CPUs are specified with -: 0-2. Default is to report
397 samples on all CPUs.
398 -M, --disassembler-style=
400 Set disassembler style for objdump.
401 --source
403 Interleave source code with assembly code. Enabled by default,
404 disable with --no-source.
405 --asm-raw
407 Show raw instruction encoding of assembly instructions.
408 --show-total-period
410 Show a column with the sum of periods.
411 -I, --show-info
413 Display extended information about the perf.data file. This adds
414 information which may be very large and thus may clutter the
415 display. It currently includes: cpu and numa topology of the host
416 system.
417 -b, --branch-stack
419 Use the addresses of sampled taken branches instead of the
420 instruction address to build the histograms. To generate meaningful
421 output, the perf.data file must have been obtained using perf
422 record -b or perf record --branch-filter xxx where xxx is a branch
423 filter option. perf report is able to auto-detect whether a
424 perf.data file contains branch stacks and it will automatically
425 switch to the branch view mode, unless --no-branch-stack is used.
426 --branch-history
428 Add the addresses of sampled taken branches to the callstack. This
429 allows to examine the path the program took to each sample. The
430 data collection must have used -b (or -j) and -g.
431 --objdump=<path>
433 Path to objdump binary.
434 --prefix=PREFIX, --prefix-strip=N
436 Remove first N entries from source file path names in executables
437 and add PREFIX. This allows to display source code compiled on
438 systems with different file system layout.
439 --group
441 Show event group information together. It forces group output also
442 if there are no groups defined in data file.
443 --group-sort-idx
445 Sort the output by the event at the index n in group. If n is
446 invalid, sort by the first event. It can support multiple groups
447 with different amount of events. WARNING: This should be used on
448 grouped events.
449 --demangle
451 Demangle symbol names to human readable form. It’s enabled by
452 default, disable with --no-demangle.
453 --demangle-kernel
455 Demangle kernel symbol names to human readable form (for C++
456 kernels).
457 --mem-mode
459 Use the data addresses of samples in addition to instruction
460 addresses to build the histograms. To generate meaningful output,
461 the perf.data file must have been obtained using perf record -d -W
462 and using a special event -e cpu/mem-loads/p or -e
463 cpu/mem-stores/p. See perf mem for simpler access.
464 --percent-limit
466 Do not show entries which have an overhead under that percent.
467 (Default: 0). Note that this option also sets the percent limit
468 (threshold) of callchains. However the default value of callchain
469 threshold is different than the default value of hist entries.
470 Please see the --call-graph option for details.
471 --percentage
473 Determine how to display the overhead percentage of filtered
474 entries. Filters can be applied by --comms, --dsos and/or --symbols
475 options and Zoom operations on the TUI (thread, dso, etc).
476 "relative" means it's relative to filtered entries only so that the
478 sum of shown entries will be always 100%. "absolute" means it retains
479 the original value before and after the filter is applied.
480 --header
482 Show header information in the perf.data file. This includes
483 various information like hostname, OS and perf version, cpu/mem
484 info, perf command line, event list and so on. Currently only
485 --stdio output supports this feature.
486 --header-only
488 Show only perf.data header (forces --stdio).
489 --time
491 Only analyze samples within given time window: <start>,<stop>.
492 Times have the format seconds.nanoseconds. If start is not given
493 (i.e. time string is ,x.y) then analysis starts at the beginning of
494 the file. If stop time is not given (i.e. time string is x.y,) then
495 analysis goes to end of file. Multiple ranges can be separated by
496 spaces, which requires the argument to be quoted e.g. --time
497 "1234.567,1234.789 1235,"
498 Also support time percent with multiple time ranges. Time string is
500 'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'.
501 For example:
503 Select the second 10% time slice:
504 perf report --time 10%/2
506 Select from 0% to 10% time slice:
508 perf report --time 0%-10%
510 Select the first and second 10% time slices:
512 perf report --time 10%/1,10%/2
514 Select from 0% to 10% and 30% to 40% slices:
516 perf report --time 0%-10%,30%-40%
518 --switch-on EVENT_NAME
520 Only consider events after this event is found.
521 This may be interesting to measure a workload only after some initialization
523 phase is over, i.e. insert a perf probe at that point and then using this
524 option with that probe.
525 --switch-off EVENT_NAME
527 Stop considering events after this event is found.
528 --show-on-off-events
530 Show the --switch-on/off events too. This has no effect in perf
531 report now but probably we’ll make the default not to show the
532 switch-on/off events on the --group mode and if there is only one
533 event besides the off/on ones, go straight to the histogram
534 browser, just like perf report with no events explicitly specified
535 does.
536 --itrace
538 Options for decoding instruction tracing data. The options are:
539 i synthesize instructions events
541 b synthesize branches events (branch misses for Arm SPE)
542 c synthesize branches events (calls only)
543 r synthesize branches events (returns only)
544 x synthesize transactions events
545 w synthesize ptwrite events
546 p synthesize power events (incl. PSB events for Intel PT)
547 o synthesize other events recorded due to the use
548 of aux-output (refer to perf record)
549 I synthesize interrupt or similar (asynchronous) events
550 (e.g. Intel PT Event Trace)
551 e synthesize error events
552 d create a debug log
553 f synthesize first level cache events
554 m synthesize last level cache events
555 M synthesize memory events
556 t synthesize TLB events
557 a synthesize remote access events
558 g synthesize a call chain (use with i or x)
559 G synthesize a call chain on existing event records
560 l synthesize last branch entries (use with i or x)
561 L synthesize last branch entries on existing event records
562 s skip initial number of events
563 q quicker (less detailed) decoding
564 A approximate IPC
565 Z prefer to ignore timestamps (so-called "timeless" decoding)
566 The default is all events i.e. the same as --itrace=ibxwpe,
568 except for perf script where it is --itrace=ce
569 In addition, the period (default 100000, except for perf script where it is 1)
571 for instructions events can be specified in units of:
572 i instructions
574 t ticks
575 ms milliseconds
576 us microseconds
577 ns nanoseconds (default)
578 Also the call chain size (default 16, max. 1024) for instructions or
580 transactions events can be specified.
581 Also the number of last branch entries (default 64, max. 1024) for
583 instructions or transactions events can be specified.
584 Similar to options g and l, size may also be specified for options G and L.
586 On x86, note that G and L work poorly when data has been recorded with
587 large PEBS. Refer linkperf:perf-intel-pt[1] man page for details.
588 It is also possible to skip events generated (instructions, branches, transactions,
590 ptwrite, power) at the beginning. This is useful to ignore initialization code.
591 --itrace=i0nss1000000
593 skips the first million instructions.
595 The 'e' option may be followed by flags which affect what errors will or
597 will not be reported. Each flag must be preceded by either '+' or '-'.
598 The flags are:
599 o overflow
600 l trace data lost
601 If supported, the 'd' option may be followed by flags which affect what
603 debug messages will or will not be logged. Each flag must be preceded
604 by either '+' or '-'. The flags are:
605 a all perf events
606 e output only on errors (size configurable - see linkperf:perf-config[1])
607 o output to stdout
608 If supported, the 'q' option may be repeated to increase the effect.
610 To disable decoding entirely, use --no-itrace.
612 --full-source-path
614 Show the full path for source files for srcline output.
615 --show-ref-call-graph
617 When multiple events are sampled, it may not be needed to collect
618 callgraphs for all of them. The sample sites are usually nearby,
619 and it’s enough to collect the callgraphs on a reference event. So
620 user can use "call-graph=no" event modifier to disable callgraph
621 for other events to reduce the overhead. However, perf report
622 cannot show callgraphs for the event which disable the callgraph.
623 This option extends the perf report to show reference callgraphs,
624 which collected by reference event, in no callgraph event.
625 --stitch-lbr
627 Show callgraph with stitched LBRs, which may have more complete
628 callgraph. The perf.data file must have been obtained using perf
629 record --call-graph lbr. Disabled by default. In common cases with
630 call stack overflows, it can recreate better call stacks than the
631 default lbr call stack output. But this approach is not full proof.
632 There can be cases where it creates incorrect call stacks from
633 incorrect matches. The known limitations include exception handing
634 such as setjmp/longjmp will have calls/returns not match.
635 --socket-filter
637 Only report the samples on the processor socket that match with
638 this filter
639 --samples=N
641 Save N individual samples for each histogram entry to show context
642 in perf report tui browser.
643 --raw-trace
645 When displaying traceevent output, do not use print fmt or plugins.
646 --hierarchy
648 Enable hierarchical output.
649 --inline
651 If a callgraph address belongs to an inlined function, the inline
652 stack will be printed. Each entry is function name or file/line.
653 Enabled by default, disable with --no-inline.
654 --mmaps
656 Show --tasks output plus mmap information in a format similar to
657 /proc/<PID>/maps.
658 Please note that not all mmaps are stored, options affecting which ones
660 are include 'perf record --data', for instance.
661 --ns
663 Show time stamps in nanoseconds.
664 --stats
666 Display overall events statistics without any further processing.
667 (like the one at the end of the perf report -D command)
668 --tasks
670 Display monitored tasks stored in perf data. Displaying
671 pid/tid/ppid plus the command string aligned to distinguish parent
672 and child tasks.
673 --percent-type
675 Set annotation percent type from following choices: global-period,
676 local-period, global-hits, local-hits
677 The local/global keywords set if the percentage is computed
679 in the scope of the function (local) or the whole data (global).
680 The period/hits keywords set the base the percentage is computed
681 on - the samples period or the number of samples (hits).
682 --time-quantum
684 Configure time quantum for time sort key. Default 100ms. Accepts s,
685 us, ms, ns units.
686 --total-cycles
688 When --total-cycles is specified, it supports sorting for all
689 blocks by Sampled Cycles%. This is useful to concentrate on the
690 globally hottest blocks. In output, there are some new columns:
691 'Sampled Cycles%' - block sampled cycles aggregation / total sampled cycles
693 'Sampled Cycles' - block sampled cycles aggregation
694 'Avg Cycles%' - block average sampled cycles / sum of total block average
695 sampled cycles
696 'Avg Cycles' - block average sampled cycles
697 --skip-empty
699 Do not print 0 results in the --stat output.
700
702 The overhead can be shown in two columns as Children and Self when perf
703 collects callchains. The self overhead is simply calculated by adding
704 all period values of the entry - usually a function (symbol). This is
705 the value that perf shows traditionally and sum of all the self
706 overhead values should be 100%.
707 The children overhead is calculated by adding all period values of the
709 child functions so that it can show the total overhead of the higher
710 level functions even if they don’t directly execute much. Children here
711 means functions that are called from another (parent) function.
712 It might be confusing that the sum of all the children overhead values
714 exceeds 100% since each of them is already an accumulation of self
715 overhead of its child functions. But with this enabled, users can find
716 which function has the most overhead even if samples are spread over
717 the children.
718 Consider the following example; there are three functions like below.
720 .ft C
723 void foo(void) {
724 /* do something */
725 }
726 void bar(void) {
728 /* do something */
729 foo();
730 }
731 int main(void) {
733 bar()
734 return 0;
735 }
736 .ft
737 In this case foo is a child of bar, and bar is an immediate child of
740 main so foo also is a child of main. In other words, main is a parent
741 of foo and bar, and bar is a parent of foo.
742 Suppose all samples are recorded in foo and bar only. When it’s
744 recorded with callchains the output will show something like below in
745 the usual (self-overhead-only) output of perf report:
746 .ft C
749 Overhead Symbol
750 ........ .....................
751 60.00% foo
752 |
753 --- foo
754 bar
755 main
756 __libc_start_main
757 40.00% bar
759 |
760 --- bar
761 main
762 __libc_start_main
763 .ft
764 When the --children option is enabled, the self overhead values of
767 child functions (i.e. foo and bar) are added to the parents to
768 calculate the children overhead. In this case the report could be
769 displayed as:
770 .ft C
773 Children Self Symbol
774 ........ ........ ....................
775 100.00% 0.00% __libc_start_main
776 |
777 --- __libc_start_main
778 100.00% 0.00% main
780 |
781 --- main
782 __libc_start_main
783 100.00% 40.00% bar
785 |
786 --- bar
787 main
788 __libc_start_main
789 60.00% 60.00% foo
791 |
792 --- foo
793 bar
794 main
795 __libc_start_main
796 .ft
797 In the above output, the self overhead of foo (60%) was add to the
800 children overhead of bar, main and __libc_start_main. Likewise, the
801 self overhead of bar (40%) was added to the children overhead of main
802 and \_\_libc_start_main.
803 So \_\_libc_start_main and main are shown first since they have same
805 (100%) children overhead (even though they have zero self overhead) and
806 they are the parents of foo and bar.
807 Since v3.16 the children overhead is shown by default and the output is
809 sorted by its values. The children overhead is disabled by specifying
810 --no-children option on the command line or by adding report.children =
811 false or top.children = false in the perf config file.
812
814 perf-stat(1), perf-annotate(1), perf-record(1), perf-intel-pt(1)
815perf 01/12/2023 PERF-REPORT(1)