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.
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 · symbol: name of function executed at the time of sample
79 · symbol_size: size of function executed at the time of sample
81 · parent: name of function matched to the parent regex filter.
83 Unmatched entries are displayed as "[other]".
84 · cpu: cpu number the task ran at the time of sample
86 · socket: processor socket number the task ran at the time of
88 sample
89 · srcline: filename and line number executed at the time of
91 sample. The DWARF debugging info must be provided.
92 · srcfile: file name of the source file of the same. Requires
94 dwarf information.
95 · weight: Event specific weight, e.g. memory latency or
97 transaction abort cost. This is the global weight.
98 · local_weight: Local weight version of the weight above.
100 · transaction: Transaction abort flags.
102 · overhead: Overhead percentage of sample
104 · overhead_sys: Overhead percentage of sample running in system
106 mode
107 · overhead_us: Overhead percentage of sample running in user mode
109 · overhead_guest_sys: Overhead percentage of sample running in
111 system mode on guest machine
112 · overhead_guest_us: Overhead percentage of sample running in
114 user mode on guest machine
115 · sample: Number of sample
117 · period: Raw number of event count of sample
119 By default, comm, dso and symbol keys are used.
121 (i.e. --sort comm,dso,symbol)
122 If --branch-stack option is used, following sort keys are also
124 available:
125 · dso_from: name of library or module branched from
127 · dso_to: name of library or module branched to
129 · symbol_from: name of function branched from
131 · symbol_to: name of function branched to
133 · srcline_from: source file and line branched from
135 · srcline_to: source file and line branched to
137 · mispredict: "N" for predicted branch, "Y" for mispredicted
139 branch
140 · in_tx: branch in TSX transaction
142 · abort: TSX transaction abort.
144 · cycles: Cycles in basic block
146 And default sort keys are changed to comm, dso_from, symbol_from, dso_to
148 and symbol_to, see '--branch-stack'.
149 If the --mem-mode option is used, the following sort keys are also available
151 (incompatible with --branch-stack):
152 symbol_daddr, dso_daddr, locked, tlb, mem, snoop, dcacheline.
153 · symbol_daddr: name of data symbol being executed on at the time
155 of sample
156 · dso_daddr: name of library or module containing the data being
158 executed on at the time of the sample
159 · locked: whether the bus was locked at the time of the sample
161 · tlb: type of tlb access for the data at the time of the sample
163 · mem: type of memory access for the data at the time of the
165 sample
166 · snoop: type of snoop (if any) for the data at the time of the
168 sample
169 · dcacheline: the cacheline the data address is on at the time of
171 the sample
172 · phys_daddr: physical address of data being executed on at the
174 time of sample
175 And the default sort keys are changed to local_weight, mem, sym, dso,
177 symbol_daddr, dso_daddr, snoop, tlb, locked, see '--mem-mode'.
178 If the data file has tracepoint event(s), following (dynamic) sort keys
180 are also available:
181 trace, trace_fields, [<event>.]<field>[/raw]
182 · trace: pretty printed trace output in a single column
184 · trace_fields: fields in tracepoints in separate columns
186 · <field name>: optional event and field name for a specific
188 field
189 The last form consists of event and field names. If event name is
191 omitted, it searches all events for matching field name. The matched
192 field will be shown only for the event has the field. The event name
193 supports substring match so user doesn't need to specify full subsystem
194 and event name everytime. For example, 'sched:sched_switch' event can
195 be shortened to 'switch' as long as it's not ambiguous. Also event can
196 be specified by its index (starting from 1) preceded by the '%'.
197 So '%1' is the first event, '%2' is the second, and so on.
198 The field name can have '/raw' suffix which disables pretty printing
200 and shows raw field value like hex numbers. The --raw-trace option
201 has the same effect for all dynamic sort keys.
202 The default sort keys are changed to 'trace' if all events in the data
204 file are tracepoint.
205 -F, --fields=
207 Specify output field - multiple keys can be specified in CSV
208 format. Following fields are available: overhead, overhead_sys,
209 overhead_us, overhead_children, sample and period. Also it can
210 contain any sort key(s).
211 By default, every sort keys not specified in -F will be appended
213 automatically.
214 If the keys starts with a prefix '+', then it will append the specified
216 field(s) to the default field order. For example: perf report -F +period,sample.
217 -p, --parent=<regex>
219 A regex filter to identify parent. The parent is a caller of this
220 function and searched through the callchain, thus it requires
221 callchain information recorded. The pattern is in the extended
222 regex format and defaults to "^sys_|^do_page_fault", see --sort
223 parent.
224 -x, --exclude-other
226 Only display entries with parent-match.
227 -w, --column-widths=<width[,width...]>
229 Force each column width to the provided list, for large terminal
230 readability. 0 means no limit (default behavior).
231 -t, --field-separator=
233 Use a special separator character and don’t pad with spaces,
234 replacing all occurrences of this separator in symbol names (and
235 other output) with a . character, that thus it’s the only non
236 valid separator.
237 -D, --dump-raw-trace
239 Dump raw trace in ASCII.
240 -g,
242 --call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>
243 Display call chains using type, min percent threshold, print limit,
244 call order, sort key, optional branch and value. Note that ordering
245 is not fixed so any parameter can be given in an arbitrary order.
246 One exception is the print_limit which should be preceded by
247 threshold.
248 print_type can be either:
250 - flat: single column, linear exposure of call chains.
251 - graph: use a graph tree, displaying absolute overhead rates. (default)
252 - fractal: like graph, but displays relative rates. Each branch of
253 the tree is considered as a new profiled object.
254 - folded: call chains are displayed in a line, separated by semicolons
255 - none: disable call chain display.
256 threshold is a percentage value which specifies a minimum percent to be
258 included in the output call graph. Default is 0.5 (%).
259 print_limit is only applied when stdio interface is used. It's to limit
261 number of call graph entries in a single hist entry. Note that it needs
262 to be given after threshold (but not necessarily consecutive).
263 Default is 0 (unlimited).
264 order can be either:
266 - callee: callee based call graph.
267 - caller: inverted caller based call graph.
268 Default is 'caller' when --children is used, otherwise 'callee'.
269 sort_key can be:
271 - function: compare on functions (default)
272 - address: compare on individual code addresses
273 - srcline: compare on source filename and line number
274 branch can be:
276 - branch: include last branch information in callgraph when available.
277 Usually more convenient to use --branch-history for this.
278 value can be:
280 - percent: diplay overhead percent (default)
281 - period: display event period
282 - count: display event count
283 --children
285 Accumulate callchain of children to parent entry so that then can
286 show up in the output. The output will have a new "Children" column
287 and will be sorted on the data. It requires callchains are
288 recorded. See the ‘overhead calculation’ section for more details.
289 Enabled by default, disable with --no-children.
290 --max-stack
292 Set the stack depth limit when parsing the callchain, anything
293 beyond the specified depth will be ignored. This is a trade-off
294 between information loss and faster processing especially for
295 workloads that can have a very long callchain stack. Note that when
296 using the --itrace option the synthesized callchain size will
297 override this value if the synthesized callchain size is bigger.
298 Default: /proc/sys/kernel/perf_event_max_stack when present, 127 otherwise.
300 -G, --inverted
302 alias for inverted caller based call graph.
303 --ignore-callees=<regex>
305 Ignore callees of the function(s) matching the given regex. This
306 has the effect of collecting the callers of each such function into
307 one place in the call-graph tree.
308 --pretty=<key>
310 Pretty printing style. key: normal, raw
311 --stdio
313 Use the stdio interface.
314 --stdio-color
316 always, never or auto, allowing configuring color output via the
317 command line, in addition to via "color.ui" .perfconfig. Use
318 --stdio-color always to generate color even when redirecting to a
319 pipe or file. Using just --stdio-color is equivalent to using
320 always.
321 --tui
323 Use the TUI interface, that is integrated with annotate and allows
324 zooming into DSOs or threads, among other features. Use of --tui
325 requires a tty, if one is not present, as when piping to other
326 commands, the stdio interface is used.
327 --gtk
329 Use the GTK2 interface.
330 -k, --vmlinux=<file>
332 vmlinux pathname
333 --kallsyms=<file>
335 kallsyms pathname
336 -m, --modules
338 Load module symbols. WARNING: This should only be used with -k and
339 a LIVE kernel.
340 -f, --force
342 Don’t do ownership validation.
343 --symfs=<directory>
345 Look for files with symbols relative to this directory.
346 -C, --cpu
348 Only report samples for the list of CPUs provided. Multiple CPUs
349 can be provided as a comma-separated list with no space: 0,1.
350 Ranges of CPUs are specified with -: 0-2. Default is to report
351 samples on all CPUs.
352 -M, --disassembler-style=
354 Set disassembler style for objdump.
355 --source
357 Interleave source code with assembly code. Enabled by default,
358 disable with --no-source.
359 --asm-raw
361 Show raw instruction encoding of assembly instructions.
362 --show-total-period
364 Show a column with the sum of periods.
365 -I, --show-info
367 Display extended information about the perf.data file. This adds
368 information which may be very large and thus may clutter the
369 display. It currently includes: cpu and numa topology of the host
370 system.
371 -b, --branch-stack
373 Use the addresses of sampled taken branches instead of the
374 instruction address to build the histograms. To generate meaningful
375 output, the perf.data file must have been obtained using perf
376 record -b or perf record --branch-filter xxx where xxx is a branch
377 filter option. perf report is able to auto-detect whether a
378 perf.data file contains branch stacks and it will automatically
379 switch to the branch view mode, unless --no-branch-stack is used.
380 --branch-history
382 Add the addresses of sampled taken branches to the callstack. This
383 allows to examine the path the program took to each sample. The
384 data collection must have used -b (or -j) and -g.
385 --objdump=<path>
387 Path to objdump binary.
388 --group
390 Show event group information together.
391 --demangle
393 Demangle symbol names to human readable form. It’s enabled by
394 default, disable with --no-demangle.
395 --demangle-kernel
397 Demangle kernel symbol names to human readable form (for C++
398 kernels).
399 --mem-mode
401 Use the data addresses of samples in addition to instruction
402 addresses to build the histograms. To generate meaningful output,
403 the perf.data file must have been obtained using perf record -d -W
404 and using a special event -e cpu/mem-loads/ or -e cpu/mem-stores/.
405 See perf mem for simpler access.
406 --percent-limit
408 Do not show entries which have an overhead under that percent.
409 (Default: 0). Note that this option also sets the percent limit
410 (threshold) of callchains. However the default value of callchain
411 threshold is different than the default value of hist entries.
412 Please see the --call-graph option for details.
413 --percentage
415 Determine how to display the overhead percentage of filtered
416 entries. Filters can be applied by --comms, --dsos and/or --symbols
417 options and Zoom operations on the TUI (thread, dso, etc).
418 "relative" means it's relative to filtered entries only so that the
420 sum of shown entries will be always 100%. "absolute" means it retains
421 the original value before and after the filter is applied.
422 --header
424 Show header information in the perf.data file. This includes
425 various information like hostname, OS and perf version, cpu/mem
426 info, perf command line, event list and so on. Currently only
427 --stdio output supports this feature.
428 --header-only
430 Show only perf.data header (forces --stdio).
431 --time
433 Only analyze samples within given time window: <start>,<stop>.
434 Times have the format seconds.microseconds. If start is not given
435 (i.e., time string is ,x.y) then analysis starts at the beginning
436 of the file. If stop time is not given (i.e, time string is x.y,)
437 then analysis goes to end of file.
438 --itrace
440 Options for decoding instruction tracing data. The options are:
441 i synthesize instructions events
443 b synthesize branches events
444 c synthesize branches events (calls only)
445 r synthesize branches events (returns only)
446 x synthesize transactions events
447 w synthesize ptwrite events
448 p synthesize power events
449 e synthesize error events
450 d create a debug log
451 g synthesize a call chain (use with i or x)
452 l synthesize last branch entries (use with i or x)
453 s skip initial number of events
454 The default is all events i.e. the same as --itrace=ibxwpe
456 In addition, the period (default 100000) for instructions events
458 can be specified in units of:
459 i instructions
461 t ticks
462 ms milliseconds
463 us microseconds
464 ns nanoseconds (default)
465 Also the call chain size (default 16, max. 1024) for instructions or
467 transactions events can be specified.
468 Also the number of last branch entries (default 64, max. 1024) for
470 instructions or transactions events can be specified.
471 It is also possible to skip events generated (instructions, branches, transactions,
473 ptwrite, power) at the beginning. This is useful to ignore initialization code.
474 --itrace=i0nss1000000
476 skips the first million instructions.
478 To disable decoding entirely, use --no-itrace.
480 --full-source-path
482 Show the full path for source files for srcline output.
483 --show-ref-call-graph
485 When multiple events are sampled, it may not be needed to collect
486 callgraphs for all of them. The sample sites are usually nearby,
487 and it’s enough to collect the callgraphs on a reference event. So
488 user can use "call-graph=no" event modifier to disable callgraph
489 for other events to reduce the overhead. However, perf report
490 cannot show callgraphs for the event which disable the callgraph.
491 This option extends the perf report to show reference callgraphs,
492 which collected by reference event, in no callgraph event.
493 --socket-filter
495 Only report the samples on the processor socket that match with
496 this filter
497 --raw-trace
499 When displaying traceevent output, do not use print fmt or plugins.
500 --hierarchy
502 Enable hierarchical output.
503 --inline
505 If a callgraph address belongs to an inlined function, the inline
506 stack will be printed. Each entry is function name or file/line.
507 Enabled by default, disable with --no-inline.
508
510 The overhead can be shown in two columns as Children and Self when perf
511 collects callchains. The self overhead is simply calculated by adding
512 all period values of the entry - usually a function (symbol). This is
513 the value that perf shows traditionally and sum of all the self
514 overhead values should be 100%.
515 The children overhead is calculated by adding all period values of the
517 child functions so that it can show the total overhead of the higher
518 level functions even if they don’t directly execute much. Children here
519 means functions that are called from another (parent) function.
520 It might be confusing that the sum of all the children overhead values
522 exceeds 100% since each of them is already an accumulation of self
523 overhead of its child functions. But with this enabled, users can find
524 which function has the most overhead even if samples are spread over
525 the children.
526 Consider the following example; there are three functions like below.
528 .ft C
531 void foo(void) {
532 /* do something */
533 }
534 void bar(void) {
536 /* do something */
537 foo();
538 }
539 int main(void) {
541 bar()
542 return 0;
543 }
544 .ft
545 In this case foo is a child of bar, and bar is an immediate child of
548 main so foo also is a child of main. In other words, main is a parent
549 of foo and bar, and bar is a parent of foo.
550 Suppose all samples are recorded in foo and bar only. When it’s
552 recorded with callchains the output will show something like below in
553 the usual (self-overhead-only) output of perf report:
554 .ft C
557 Overhead Symbol
558 ........ .....................
559 60.00% foo
560 |
561 --- foo
562 bar
563 main
564 __libc_start_main
565 40.00% bar
567 |
568 --- bar
569 main
570 __libc_start_main
571 .ft
572 When the --children option is enabled, the self overhead values of
575 child functions (i.e. foo and bar) are added to the parents to
576 calculate the children overhead. In this case the report could be
577 displayed as:
578 .ft C
581 Children Self Symbol
582 ........ ........ ....................
583 100.00% 0.00% __libc_start_main
584 |
585 --- __libc_start_main
586 100.00% 0.00% main
588 |
589 --- main
590 __libc_start_main
591 100.00% 40.00% bar
593 |
594 --- bar
595 main
596 __libc_start_main
597 60.00% 60.00% foo
599 |
600 --- foo
601 bar
602 main
603 __libc_start_main
604 .ft
605 In the above output, the self overhead of foo (60%) was add to the
608 children overhead of bar, main and __libc_start_main. Likewise, the
609 self overhead of bar (40%) was added to the children overhead of main
610 and \_\_libc_start_main.
611 So \_\_libc_start_main and main are shown first since they have same
613 (100%) children overhead (even though they have zero self overhead) and
614 they are the parents of foo and bar.
615 Since v3.16 the children overhead is shown by default and the output is
617 sorted by its values. The children overhead is disabled by specifying
618 --no-children option on the command line or by adding report.children =
619 false or top.children = false in the perf config file.
620
622 perf-stat(1), perf-annotate(1)
623perf 06/18/2019 PERF-REPORT(1)