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 same. 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                   By default, comm, dso and symbol keys are used.
127                   (i.e. --sort comm,dso,symbol)
128
129                   If --branch-stack option is used, following sort keys are also
130                   available:
131
132           ·   dso_from: name of library or module branched from
133
134           ·   dso_to: name of library or module branched to
135
136           ·   symbol_from: name of function branched from
137
138           ·   symbol_to: name of function branched to
139
140           ·   srcline_from: source file and line branched from
141
142           ·   srcline_to: source file and line branched to
143
144           ·   mispredict: "N" for predicted branch, "Y" for mispredicted
145               branch
146
147           ·   in_tx: branch in TSX transaction
148
149           ·   abort: TSX transaction abort.
150
151           ·   cycles: Cycles in basic block
152
153                   And default sort keys are changed to comm, dso_from, symbol_from, dso_to
154                   and symbol_to, see '--branch-stack'.
155
156                   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
160           ·   symbol_daddr: name of data symbol being executed on at the time
161               of sample
162
163           ·   dso_daddr: name of library or module containing the data being
164               executed on at the time of the sample
165
166           ·   locked: whether the bus was locked at the time of the sample
167
168           ·   tlb: type of tlb access for the data at the time of the sample
169
170           ·   mem: type of memory access for the data at the time of the
171               sample
172
173           ·   snoop: type of snoop (if any) for the data at the time of the
174               sample
175
176           ·   dcacheline: the cacheline the data address is on at the time of
177               the sample
178
179           ·   phys_daddr: physical address of data being executed on at the
180               time of sample
181
182                   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
185                   If the data file has tracepoint event(s), following (dynamic) sort keys
186                   are also available:
187                   trace, trace_fields, [<event>.]<field>[/raw]
188
189           ·   trace: pretty printed trace output in a single column
190
191           ·   trace_fields: fields in tracepoints in separate columns
192
193           ·   <field name>: optional event and field name for a specific
194               field
195
196                   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
205                   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
209                   The default sort keys are changed to 'trace' if all events in the data
210                   file are tracepoint.
211
212       -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
218               By default, every sort keys not specified in -F will be appended
219               automatically.
220
221               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
224       -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
231       -x, --exclude-other
232           Only display entries with parent-match.
233
234       -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
238       -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
244       -D, --dump-raw-trace
245           Dump raw trace in ASCII.
246
247       -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
255               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
263               threshold is a percentage value which specifies a minimum percent to be
264               included in the output call graph.  Default is 0.5 (%).
265
266               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
271               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
276               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
281               branch can be:
282               - branch: include last branch information in callgraph when available.
283                         Usually more convenient to use --branch-history for this.
284
285               value can be:
286               - percent: diplay overhead percent (default)
287               - period: display event period
288               - count: display event count
289
290       --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
297       --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
305               Default: 127
306
307       -G, --inverted
308           alias for inverted caller based call graph.
309
310       --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
315       --pretty=<key>
316           Pretty printing style. key: normal, raw
317
318       --stdio
319           Use the stdio interface.
320
321       --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
328       --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
334       --gtk
335           Use the GTK2 interface.
336
337       -k, --vmlinux=<file>
338           vmlinux pathname
339
340       --ignore-vmlinux
341           Ignore vmlinux files.
342
343       --kallsyms=<file>
344           kallsyms pathname
345
346       -m, --modules
347           Load module symbols. WARNING: This should only be used with -k and
348           a LIVE kernel.
349
350       -f, --force
351           Don’t do ownership validation.
352
353       --symfs=<directory>
354           Look for files with symbols relative to this directory.
355
356       -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
362       -M, --disassembler-style=
363           Set disassembler style for objdump.
364
365       --source
366           Interleave source code with assembly code. Enabled by default,
367           disable with --no-source.
368
369       --asm-raw
370           Show raw instruction encoding of assembly instructions.
371
372       --show-total-period
373           Show a column with the sum of periods.
374
375       -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
381       -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
390       --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
395       --objdump=<path>
396           Path to objdump binary.
397
398       --group
399           Show event group information together. It forces group output also
400           if there are no groups defined in data file.
401
402       --demangle
403           Demangle symbol names to human readable form. It’s enabled by
404           default, disable with --no-demangle.
405
406       --demangle-kernel
407           Demangle kernel symbol names to human readable form (for C++
408           kernels).
409
410       --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
417       --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
424       --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
429               "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
433       --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
439       --header-only
440           Show only perf.data header (forces --stdio).
441
442       --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
449               Also support time percent with multiple time range. Time string is
450               'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'.
451
452               For example:
453               Select the second 10% time slice:
454
455               perf report --time 10%/2
456
457               Select from 0% to 10% time slice:
458
459               perf report --time 0%-10%
460
461               Select the first and second 10% time slices:
462
463               perf report --time 10%/1,10%/2
464
465               Select from 0% to 10% and 30% to 40% slices:
466
467               perf report --time 0%-10%,30%-40%
468
469       --itrace
470           Options for decoding instruction tracing data. The options are:
471
472               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
485               The default is all events i.e. the same as --itrace=ibxwpe
486
487               In addition, the period (default 100000) for instructions events
488               can be specified in units of:
489
490               i       instructions
491               t       ticks
492               ms      milliseconds
493               us      microseconds
494               ns      nanoseconds (default)
495
496               Also the call chain size (default 16, max. 1024) for instructions or
497               transactions events can be specified.
498
499               Also the number of last branch entries (default 64, max. 1024) for
500               instructions or transactions events can be specified.
501
502               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
505               --itrace=i0nss1000000
506
507               skips the first million instructions.
508
509               To disable decoding entirely, use --no-itrace.
510
511       --full-source-path
512           Show the full path for source files for srcline output.
513
514       --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
524       --socket-filter
525           Only report the samples on the processor socket that match with
526           this filter
527
528       --raw-trace
529           When displaying traceevent output, do not use print fmt or plugins.
530
531       --hierarchy
532           Enable hierarchical output.
533
534       --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
539       --mmaps
540           Show --tasks output plus mmap information in a format similar to
541           /proc/<PID>/maps.
542
543               Please note that not all mmaps are stored, options affecting which ones
544               are include 'perf record --data', for instance.
545
546       --stats
547           Display overall events statistics without any further processing.
548           (like the one at the end of the perf report -D command)
549
550       --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

OVERHEAD CALCULATION

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
562       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
567       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
573       Consider the following example; there are three functions like below.
574
575
576           .ft C
577           void foo(void) {
578               /* do something */
579           }
580
581           void bar(void) {
582               /* do something */
583               foo();
584           }
585
586           int main(void) {
587               bar()
588               return 0;
589           }
590           .ft
591
592
593       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
597       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
601
602           .ft C
603           Overhead  Symbol
604           ........  .....................
605             60.00%  foo
606                     |
607                     --- foo
608                         bar
609                         main
610                         __libc_start_main
611
612             40.00%  bar
613                     |
614                     --- bar
615                         main
616                         __libc_start_main
617           .ft
618
619
620       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
625
626           .ft C
627           Children      Self  Symbol
628           ........  ........  ....................
629            100.00%     0.00%  __libc_start_main
630                     |
631                     --- __libc_start_main
632
633            100.00%     0.00%  main
634                     |
635                     --- main
636                         __libc_start_main
637
638            100.00%    40.00%  bar
639                     |
640                     --- bar
641                         main
642                         __libc_start_main
643
644             60.00%    60.00%  foo
645                     |
646                     --- foo
647                         bar
648                         main
649                         __libc_start_main
650           .ft
651
652
653       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
658       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
662       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

SEE ALSO

668       perf-stat(1), perf-annotate(1), perf-record(1)
669
670
671
672perf                              09/24/2019                    PERF-REPORT(1)
Impressum