perf/Documentation/perf-report.txt

1 perf-report(1)
5 ----
6 perf-report - Read perf.data (created by perf record) and display the profile
9 --------
11 'perf report' [-i <file> | --input=file]
14 -----------
19 -------
20 -i::
21 --input=::
22         Input file name. (default: perf.data unless stdin is a fifo)
24 -v::
25 --verbose::
28 -q::
29 --quiet::
30 	Do not show any warnings or messages.  (Suppress -v)
32 -n::
33 --show-nr-samples::
36 --show-cpu-utilization::
37         Show sample percentage for different cpu modes.
39 -T::
40 --threads::
41 	Show per-thread event counters.  The input data file should be recorded
42 	with -s option.
43 -c::
44 --comms=::
47 	the overhead and latency columns.  See --percentage for more info.
48 --pid=::
51 --tid=::
53 -d::
54 --dsos=::
57 	the overhead and latency columns.  See --percentage for more info.
58 -S::
59 --symbols=::
62 	the overhead and latency columns.  See --percentage for more info.
64 --symbol-filter=::
67 -U::
68 --hide-unresolved::
71 --parallelism::
73         of threads that actively run on CPUs at the time of sample. The flag
74         accepts single number, comma-separated list, and ranges (for example:
75         "1", "7,8", "1,64-128"). This is useful in understanding what a program
76         is doing during sequential/low-parallelism phases as compared to
77         high-parallelism phases. This option will affect the percentage of
78         the overhead and latency columns. See --percentage for more info.
81 --latency::
82         Show latency-centric profile rather than the default
83         CPU-consumption-centric profile
84         (requires perf record --latency flag).
86 -s::
87 --sort=::
88 	Sort histogram entries by given key(s) - multiple keys can be specified
95 	- comm: command (name) of the task which can be read via /proc/<pid>/comm
96 	- pid: command and tid of the task
97 	- tgid: command and tgid of the task
98 	- dso: name of library or module executed at the time of sample
99 	- dso_size: size of library or module executed at the time of sample
100 	- symbol: name of function executed at the time of sample
101 	- symbol_size: size of function executed at the time of sample
102 	- parent: name of function matched to the parent regex filter. Unmatched
104 	- cpu: cpu number the task ran at the time of sample
105 	- socket: processor socket number the task ran at the time of sample
106 	- parallelism: number of running threads at the time of sample
107 	- srcline: filename and line number executed at the time of sample.  The
109 	- srcfile: file name of the source file of the samples. Requires dwarf
111 	- weight: Event specific weight, e.g. memory latency or transaction
113 	- local_weight: Local weight version of the weight above.
114 	- cgroup_id: ID derived from cgroup namespace device and inode numbers.
115 	- cgroup: cgroup pathname in the cgroupfs.
116 	- transaction: Transaction abort flags.
117 	- overhead: CPU overhead percentage of sample.
118 	- latency: latency (wall-clock) overhead percentage of sample.
120 	- overhead_sys: CPU overhead percentage of sample running in system mode
121 	- overhead_us: CPU overhead percentage of sample running in user mode
122 	- overhead_guest_sys: CPU overhead percentage of sample running in system mode
124 	- overhead_guest_us: CPU overhead percentage of sample running in user mode on
126 	- sample: Number of sample
127 	- period: Raw number of event count of sample
128 	- time: Separate the samples by time stamp with the resolution specified by
129 	--time-quantum (default 100ms). Specify with overhead and before it.
130 	- code_page_size: the code page size of sampled code address (ip)
131 	- ins_lat: Instruction latency in core cycles. This is the global instruction
133 	- local_ins_lat: Local instruction latency version
134 	- p_stage_cyc: On powerpc, this presents the number of cycles spent in a
136 	- addr: (Full) virtual address of the sampled instruction
137 	- retire_lat: On X86, this reports pipeline stall of this instruction compared
139 …- simd: Flags describing a SIMD operation. "e" for empty Arm SVE predicate. "p" for partial Arm SV…
140 	- type: Data type of sample memory access.
141 	- typeoff: Offset in the data type of sample memory access.
142 	- symoff: Offset in the symbol.
143 	- weight1: Average value of event specific weight (1st field of weight_struct).
144 	- weight2: Average value of event specific weight (2nd field of weight_struct).
145 	- weight3: Average value of event specific weight (3rd field of weight_struct).
147 	By default, overhead, comm, dso and symbol keys are used.
148 	(i.e. --sort overhead,comm,dso,symbol).
150 	If --branch-stack option is used, following sort keys are also
153 	- dso_from: name of library or module branched from
154 	- dso_to: name of library or module branched to
155 	- symbol_from: name of function branched from
156 	- symbol_to: name of function branched to
157 	- srcline_from: source file and line branched from
158 	- srcline_to: source file and line branched to
159 	- mispredict: "N" for predicted branch, "Y" for mispredicted branch
160 	- in_tx: branch in TSX transaction
161 	- abort: TSX transaction abort.
162 	- cycles: Cycles in basic block
164 	And default sort keys are changed to comm, dso_from, symbol_from, dso_to
165 	and symbol_to, see '--branch-stack'.
175 	If the --mem-mode option is used, the following sort keys are also available
176 	(incompatible with --branch-stack):
179 	- symbol_daddr: name of data symbol being executed on at the time of sample
180 	- dso_daddr: name of library or module containing the data being executed
181 	on at the time of the sample
182 	- locked: whether the bus was locked at the time of the sample
183 	- tlb: type of tlb access for the data at the time of the sample
184 	- mem: type of memory access for the data at the time of the sample
185 	- snoop: type of snoop (if any) for the data at the time of the sample
186 	- dcacheline: the cacheline the data address is on at the time of the sample
187 	- phys_daddr: physical address of data being executed on at the time of sample
188 	- data_page_size: the data page size of data being executed on at the time of sample
189 	- blocked: reason of blocked load access for the data at the time of the sample
191 	And the default sort keys are changed to local_weight, mem, sym, dso,
193 	see '--mem-mode'.
199 	- trace: pretty printed trace output in a single column
200 	- trace_fields: fields in tracepoints in separate columns
201 	- <field name>: optional event and field name for a specific field
213 	and shows raw field value like hex numbers.  The --raw-trace option
216 	The default sort keys are changed to 'trace' if all events in the data
219 -F::
220 --fields=::
221 	Specify output field - multiple keys can be specified in CSV format.
223 	overhead, latency, overhead_sys, overhead_us, overhead_children, sample,
230 	By default, every sort keys not specified in -F will be appended
234         field(s) to the default field order. For example: perf report -F +period,sample.
236 -p::
237 --parent=<regex>::
241 	defaults to "\^sys_|^do_page_fault", see '--sort parent'.
243 -x::
244 --exclude-other::
245         Only display entries with parent-match.
247 -w::
248 --column-widths=<width[,width...]>::
250 	readability.  0 means no limit (default behavior).
252 -t::
253 --field-separator=::
258 -D::
259 --dump-raw-trace::
262 --disable-order::
265 -g::
266 --call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>::
273 	- flat: single column, linear exposure of call chains.
274 	- graph: use a graph tree, displaying absolute overhead rates. (default)
275 	- fractal: like graph, but displays relative rates. Each branch of
277 	- folded: call chains are displayed in a line, separated by semicolons
278 	- none: disable call chain display.
281 	included in the output call graph.  Default is 0.5 (%).
286 	Default is 0 (unlimited).
289 	- callee: callee based call graph.
290 	- caller: inverted caller based call graph.
291 	Default is 'caller' when --children is used, otherwise 'callee'.
294 	- function: compare on functions (default)
295 	- address: compare on individual code addresses
296 	- srcline: compare on source filename and line number
299 	- branch: include last branch information in callgraph when available.
300 	          Usually more convenient to use --branch-history for this.
303 	- percent: display overhead percent (default)
304 	- period: display event period
305 	- count: display event count
307 --children::
312 	default, disable with --no-children.
314 --max-stack::
316 	beyond the specified depth will be ignored. This is a trade-off
319 	Note that when using the --itrace option the synthesized callchain size
322 	Default: 127
324 -G::
325 --inverted::
328 --ignore-callees=<regex>::
331         function into one place in the call-graph tree.
333 --pretty=<key>::
336 --stdio:: Use the stdio interface.
338 --stdio-color::
341 	Use '--stdio-color always' to generate color even when redirecting
342 	to a pipe or file. Using just '--stdio-color' is equivalent to
345 --tui:: Use the TUI interface, that is integrated with annotate and allows
346         zooming into DSOs or threads, among other features. Use of --tui
350 --gtk:: Use the GTK2 interface.
352 -k::
353 --vmlinux=<file>::
356 --ignore-vmlinux::
359 --kallsyms=<file>::
362 -m::
363 --modules::
364         Load module symbols. WARNING: This should only be used with -k and
367 -f::
368 --force::
371 --symfs=<directory>::
374 -C::
375 --cpu:: Only report samples for the list of CPUs provided. Multiple CPUs can
376 	be provided as a comma-separated list with no space: 0,1. Ranges of
377 	CPUs are specified with -: 0-2. Default is to report samples on all
380 -M::
381 --disassembler-style=:: Set disassembler style for objdump.
383 --source::
384 	Interleave source code with assembly code. Enabled by default,
385 	disable with --no-source.
387 --asm-raw::
390 --show-total-period:: Show a column with the sum of periods.
392 -I::
393 --show-info::
398 -b::
399 --branch-stack::
402 	perf.data file must have been obtained using perf record -b or
403 	perf record --branch-filter xxx where xxx is a branch filter option.
404 	perf report is able to auto-detect whether a perf.data file contains
406 	unless --no-branch-stack is used.
408 --branch-history::
410 	This allows to examine the path the program took to each sample.
411 	The data collection must have used -b (or -j) and -g.
414 	- Predicted: display the average percentage of predicated branches.
416 	- Abort: display the number of tsx aborted branches.
417 	- Cycles: cycles in basic block.
419 	- iterations: display the average number of iterations in callchain list.
421 --addr2line=<path>::
424 --objdump=<path>::
427 --prefix=PREFIX::
428 --prefix-strip=N::
433 --group::
437 --group-sort-idx::
442 --demangle::
443 	Demangle symbol names to human readable form. It's enabled by default,
444 	disable with --no-demangle.
446 --demangle-kernel::
449 --mem-mode::
452 	file must have been obtained using perf record -d -W and using a
453 	special event -e cpu/mem-loads/p or -e cpu/mem-stores/p. See
456 --percent-limit::
458 	(Default: 0).  Note that this option also sets the percent limit (threshold)
459 	of callchains.  However the default value of callchain threshold is
460 	different than the default value of hist entries.  Please see the
461 	--call-graph option for details.
463 --percentage::
465 	of filtered entries. Filters can be applied by --comms, --dsos, --symbols
466 	and/or --parallelism options and Zoom operations on the TUI (thread, dso, etc).
472 --header::
476 	--stdio output supports this feature.
478 --header-only::
479 	Show only perf.data header (forces --stdio).
481 --time::
487 	requires the argument to be quoted e.g. --time "1234.567,1234.789 1235,"
490 	'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'.
495 	  perf report --time 10%/2
499 	  perf report --time 0%-10%
503 	  perf report --time 10%/1,10%/2
507 	  perf report --time 0%-10%,30%-40%
509 --switch-on EVENT_NAME::
513 	phase is over, i.e. insert a perf probe at that point and then using this
516 --switch-off EVENT_NAME::
519 --show-on-off-events::
520 	Show the --switch-on/off events too. This has no effect in 'perf report' now
521 	but probably we'll make the default not to show the switch-on/off events
522         on the --group mode and if there is only one event besides the off/on ones,
526 --itrace::
531 	To disable decoding entirely, use --no-itrace.
533 --full-source-path::
536 --show-ref-call-graph::
538 	callgraphs for all of them. The sample sites are usually nearby,
540 	So user can use "call-graph=no" event modifier to disable callgraph
547 --stitch-lbr::
550 	perf record --call-graph lbr.
551 	Disabled by default. In common cases with call stack overflows,
552 	it can recreate better call stacks than the default lbr call stack
558 --socket-filter::
561 --samples=N::
565 --raw-trace::
568 -H::
569 --hierarchy::
571 	samples based on the criteria and then sub-divide it using the lower
577 	  perf report -s dso,sym
587 	  perf report -s dso,sym --hierarchy
598 --inline::
601 	default, disable with --no-inline.
603 --mmaps::
604 	Show --tasks output plus mmap information in a format similar to
608 	are include 'perf record --data', for instance.
610 --ns::
613 --stats::
615 	(like the one at the end of the perf report -D command)
617 --tasks::
621 --percent-type::
623 	  global-period, local-period, global-hits, local-hits
628 	on - the samples period or the number of samples (hits).
630 --time-quantum::
631 	Configure time quantum for time sort key. Default 100ms.
634 --total-cycles::
635 	When --total-cycles is specified, it supports sorting for all blocks by
639 	'Sampled Cycles%' - block sampled cycles aggregation / total sampled cycles
640 	'Sampled Cycles'  - block sampled cycles aggregation
641 	'Avg Cycles%'     - block average sampled cycles / sum of total block average
643 	'Avg Cycles'      - block average sampled cycles
644 	'Branch Counter'  - block branch counter histogram (with -v showing the number)
646 --skip-empty::
647 	Do not print 0 results in the --stat output.
649 include::cpu-and-latency-overheads.txt[]
651 include::callchain-overhead-calculation.txt[]
654 --------
655 linkperf:perf-stat[1], linkperf:perf-annotate[1], linkperf:perf-record[1],
656 linkperf:perf-intel-pt[1]