1PERF-REPORT(1)                    perf Manual                   PERF-REPORT(1)
2
3
4

NAME

6       perf-report - Read perf.data (created by perf record) and display the
7       profile
8

SYNOPSIS

10       perf report [-i <file> | --input=file]
11

DESCRIPTION

13       This command displays the performance counter profile information
14       recorded via perf record.
15

OPTIONS

17       -i, --input=
18           Input file name. (default: perf.data unless stdin is a fifo)
19
20       -v, --verbose
21           Be more verbose. (show symbol address, etc)
22
23       -q, --quiet
24           Do not show any message. (Suppress -v)
25
26       -n, --show-nr-samples
27           Show the number of samples for each symbol
28
29       --show-cpu-utilization
30           Show sample percentage for different cpu modes.
31
32       -T, --threads
33           Show per-thread event counters. The input data file should be
34           recorded with -s option.
35
36       -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
41       --pid=
42           Only show events for given process ID (comma separated list).
43
44       --tid=
45           Only show events for given thread ID (comma separated list).
46
47       -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
52       -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
57       --symbol-filter=
58           Only show symbols that match (partially) with this filter.
59
60       -U, --hide-unresolved
61           Only display entries resolved to a symbol.
62
63       -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
69               Each key has following meaning:
70
71           ·   comm: command (name) of the task which can be read via
72               /proc/<pid>/comm
73
74           ·   pid: command and tid of the task
75
76           ·   dso: name of library or module executed at the time of sample
77
78           ·   dso_size: size of library or module executed at the time of
79               sample
80
81           ·   symbol: name of function executed at the time of sample
82
83           ·   symbol_size: size of function executed at the time of sample
84
85           ·   parent: name of function matched to the parent regex filter.
86               Unmatched entries are displayed as "[other]".
87
88           ·   cpu: cpu number the task ran at the time of sample
89
90           ·   socket: processor socket number the task ran at the time of
91               sample
92
93           ·   srcline: filename and line number executed at the time of
94               sample. The DWARF debugging info must be provided.
95
96           ·   srcfile: file name of the source file of the samples. Requires
97               dwarf information.
98
99           ·   weight: Event specific weight, e.g. memory latency or
100               transaction abort cost. This is the global weight.
101
102           ·   local_weight: Local weight version of the weight above.
103
104           ·   cgroup_id: ID derived from cgroup namespace device and inode
105               numbers.
106
107           ·   transaction: Transaction abort flags.
108
109           ·   overhead: Overhead percentage of sample
110
111           ·   overhead_sys: Overhead percentage of sample running in system
112               mode
113
114           ·   overhead_us: Overhead percentage of sample running in user mode
115
116           ·   overhead_guest_sys: Overhead percentage of sample running in
117               system mode on guest machine
118
119           ·   overhead_guest_us: Overhead percentage of sample running in
120               user mode on guest machine
121
122           ·   sample: Number of sample
123
124           ·   period: Raw number of event count of sample
125
126           ·   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
130                   By default, comm, dso and symbol keys are used.
131                   (i.e. --sort comm,dso,symbol)
132
133                   If --branch-stack option is used, following sort keys are also
134                   available:
135
136           ·   dso_from: name of library or module branched from
137
138           ·   dso_to: name of library or module branched to
139
140           ·   symbol_from: name of function branched from
141
142           ·   symbol_to: name of function branched to
143
144           ·   srcline_from: source file and line branched from
145
146           ·   srcline_to: source file and line branched to
147
148           ·   mispredict: "N" for predicted branch, "Y" for mispredicted
149               branch
150
151           ·   in_tx: branch in TSX transaction
152
153           ·   abort: TSX transaction abort.
154
155           ·   cycles: Cycles in basic block
156
157                   And default sort keys are changed to comm, dso_from, symbol_from, dso_to
158                   and symbol_to, see '--branch-stack'.
159
160                   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
168                   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
172           ·   symbol_daddr: name of data symbol being executed on at the time
173               of sample
174
175           ·   dso_daddr: name of library or module containing the data being
176               executed on at the time of the sample
177
178           ·   locked: whether the bus was locked at the time of the sample
179
180           ·   tlb: type of tlb access for the data at the time of the sample
181
182           ·   mem: type of memory access for the data at the time of the
183               sample
184
185           ·   snoop: type of snoop (if any) for the data at the time of the
186               sample
187
188           ·   dcacheline: the cacheline the data address is on at the time of
189               the sample
190
191           ·   phys_daddr: physical address of data being executed on at the
192               time of sample
193
194                   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
197                   If the data file has tracepoint event(s), following (dynamic) sort keys
198                   are also available:
199                   trace, trace_fields, [<event>.]<field>[/raw]
200
201           ·   trace: pretty printed trace output in a single column
202
203           ·   trace_fields: fields in tracepoints in separate columns
204
205           ·   <field name>: optional event and field name for a specific
206               field
207
208                   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
217                   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
221                   The default sort keys are changed to 'trace' if all events in the data
222                   file are tracepoint.
223
224       -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
230               By default, every sort keys not specified in -F will be appended
231               automatically.
232
233               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
236       -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
243       -x, --exclude-other
244           Only display entries with parent-match.
245
246       -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
250       -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
256       -D, --dump-raw-trace
257           Dump raw trace in ASCII.
258
259       -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
267               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
275               threshold is a percentage value which specifies a minimum percent to be
276               included in the output call graph.  Default is 0.5 (%).
277
278               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
283               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
288               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
293               branch can be:
294               - branch: include last branch information in callgraph when available.
295                         Usually more convenient to use --branch-history for this.
296
297               value can be:
298               - percent: display overhead percent (default)
299               - period: display event period
300               - count: display event count
301
302       --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
309       --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
317               Default: 127
318
319       -G, --inverted
320           alias for inverted caller based call graph.
321
322       --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
327       --pretty=<key>
328           Pretty printing style. key: normal, raw
329
330       --stdio
331           Use the stdio interface.
332
333       --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
340       --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
346       --gtk
347           Use the GTK2 interface.
348
349       -k, --vmlinux=<file>
350           vmlinux pathname
351
352       --ignore-vmlinux
353           Ignore vmlinux files.
354
355       --kallsyms=<file>
356           kallsyms pathname
357
358       -m, --modules
359           Load module symbols. WARNING: This should only be used with -k and
360           a LIVE kernel.
361
362       -f, --force
363           Don’t do ownership validation.
364
365       --symfs=<directory>
366           Look for files with symbols relative to this directory.
367
368       -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
374       -M, --disassembler-style=
375           Set disassembler style for objdump.
376
377       --source
378           Interleave source code with assembly code. Enabled by default,
379           disable with --no-source.
380
381       --asm-raw
382           Show raw instruction encoding of assembly instructions.
383
384       --show-total-period
385           Show a column with the sum of periods.
386
387       -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
393       -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
402       --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
407       --objdump=<path>
408           Path to objdump binary.
409
410       --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
415       --group
416           Show event group information together. It forces group output also
417           if there are no groups defined in data file.
418
419       --demangle
420           Demangle symbol names to human readable form. It’s enabled by
421           default, disable with --no-demangle.
422
423       --demangle-kernel
424           Demangle kernel symbol names to human readable form (for C++
425           kernels).
426
427       --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
434       --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
441       --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
446               "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
450       --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
456       --header-only
457           Show only perf.data header (forces --stdio).
458
459       --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
468               Also support time percent with multiple time ranges. Time string is
469               'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'.
470
471               For example:
472               Select the second 10% time slice:
473
474               perf report --time 10%/2
475
476               Select from 0% to 10% time slice:
477
478               perf report --time 0%-10%
479
480               Select the first and second 10% time slices:
481
482               perf report --time 10%/1,10%/2
483
484               Select from 0% to 10% and 30% to 40% slices:
485
486               perf report --time 0%-10%,30%-40%
487
488       --switch-on EVENT_NAME
489           Only consider events after this event is found.
490
491               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
495       --switch-off EVENT_NAME
496           Stop considering events after this event is found.
497
498       --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
506       --itrace
507           Options for decoding instruction tracing data. The options are:
508
509               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
524               The default is all events i.e. the same as --itrace=ibxwpe,
525               except for perf script where it is --itrace=ce
526
527               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
530               i       instructions
531               t       ticks
532               ms      milliseconds
533               us      microseconds
534               ns      nanoseconds (default)
535
536               Also the call chain size (default 16, max. 1024) for instructions or
537               transactions events can be specified.
538
539               Also the number of last branch entries (default 64, max. 1024) for
540               instructions or transactions events can be specified.
541
542               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
545               --itrace=i0nss1000000
546
547               skips the first million instructions.
548
549               To disable decoding entirely, use --no-itrace.
550
551       --full-source-path
552           Show the full path for source files for srcline output.
553
554       --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
564       --socket-filter
565           Only report the samples on the processor socket that match with
566           this filter
567
568       --samples=N
569           Save N individual samples for each histogram entry to show context
570           in perf report tui browser.
571
572       --raw-trace
573           When displaying traceevent output, do not use print fmt or plugins.
574
575       --hierarchy
576           Enable hierarchical output.
577
578       --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
583       --mmaps
584           Show --tasks output plus mmap information in a format similar to
585           /proc/<PID>/maps.
586
587               Please note that not all mmaps are stored, options affecting which ones
588               are include 'perf record --data', for instance.
589
590       --ns
591           Show time stamps in nanoseconds.
592
593       --stats
594           Display overall events statistics without any further processing.
595           (like the one at the end of the perf report -D command)
596
597       --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
602       --percent-type
603           Set annotation percent type from following choices: global-period,
604           local-period, global-hits, local-hits
605
606               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
611       --time-quantum
612           Configure time quantum for time sort key. Default 100ms. Accepts s,
613           us, ms, ns units.
614
615       --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
620               '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

OVERHEAD CALCULATION

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
633       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
638       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
644       Consider the following example; there are three functions like below.
645
646
647           .ft C
648           void foo(void) {
649               /* do something */
650           }
651
652           void bar(void) {
653               /* do something */
654               foo();
655           }
656
657           int main(void) {
658               bar()
659               return 0;
660           }
661           .ft
662
663
664       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
668       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
672
673           .ft C
674           Overhead  Symbol
675           ........  .....................
676             60.00%  foo
677                     |
678                     --- foo
679                         bar
680                         main
681                         __libc_start_main
682
683             40.00%  bar
684                     |
685                     --- bar
686                         main
687                         __libc_start_main
688           .ft
689
690
691       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
696
697           .ft C
698           Children      Self  Symbol
699           ........  ........  ....................
700            100.00%     0.00%  __libc_start_main
701                     |
702                     --- __libc_start_main
703
704            100.00%     0.00%  main
705                     |
706                     --- main
707                         __libc_start_main
708
709            100.00%    40.00%  bar
710                     |
711                     --- bar
712                         main
713                         __libc_start_main
714
715             60.00%    60.00%  foo
716                     |
717                     --- foo
718                         bar
719                         main
720                         __libc_start_main
721           .ft
722
723
724       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
729       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
733       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

SEE ALSO

739       perf-stat(1), perf-annotate(1), perf-record(1)
740
741
742
743perf                              04/23/2020                    PERF-REPORT(1)
Impressum