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 message.  (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 column.  See --percentage for more info.
48 --pid=::
51 --tid=::
53 -d::
54 --dsos=::
57 	the overhead column.  See --percentage for more info.
58 -S::
59 --symbols=::
62 	the overhead column.  See --percentage for more info.
64 --symbol-filter=::
67 -U::
68 --hide-unresolved::
71 -s::
72 --sort=::
73 	Sort histogram entries by given key(s) - multiple keys can be specified
80 	- comm: command (name) of the task which can be read via /proc/<pid>/comm
81 	- pid: command and tid of the task
82 	- dso: name of library or module executed at the time of sample
83 	- dso_size: size of library or module executed at the time of sample
84 	- symbol: name of function executed at the time of sample
85 	- symbol_size: size of function executed at the time of sample
86 	- parent: name of function matched to the parent regex filter. Unmatched
88 	- cpu: cpu number the task ran at the time of sample
89 	- socket: processor socket number the task ran at the time of sample
90 	- srcline: filename and line number executed at the time of sample.  The
92 	- srcfile: file name of the source file of the samples. Requires dwarf
94 	- weight: Event specific weight, e.g. memory latency or transaction
96 	- local_weight: Local weight version of the weight above.
97 	- cgroup_id: ID derived from cgroup namespace device and inode numbers.
98 	- cgroup: cgroup pathname in the cgroupfs.
99 	- transaction: Transaction abort flags.
100 	- overhead: Overhead percentage of sample
101 	- overhead_sys: Overhead percentage of sample running in system mode
102 	- overhead_us: Overhead percentage of sample running in user mode
103 	- overhead_guest_sys: Overhead percentage of sample running in system mode
105 	- overhead_guest_us: Overhead percentage of sample running in user mode on
107 	- sample: Number of sample
108 	- period: Raw number of event count of sample
109 	- time: Separate the samples by time stamp with the resolution specified by
110 	--time-quantum (default 100ms). Specify with overhead and before it.
112 	By default, comm, dso and symbol keys are used.
113 	(i.e. --sort comm,dso,symbol)
115 	If --branch-stack option is used, following sort keys are also
118 	- dso_from: name of library or module branched from
119 	- dso_to: name of library or module branched to
120 	- symbol_from: name of function branched from
121 	- symbol_to: name of function branched to
122 	- srcline_from: source file and line branched from
123 	- srcline_to: source file and line branched to
124 	- mispredict: "N" for predicted branch, "Y" for mispredicted branch
125 	- in_tx: branch in TSX transaction
126 	- abort: TSX transaction abort.
127 	- cycles: Cycles in basic block
129 	And default sort keys are changed to comm, dso_from, symbol_from, dso_to
130 	and symbol_to, see '--branch-stack'.
140 	If the --mem-mode option is used, the following sort keys are also available
141 	(incompatible with --branch-stack):
144 	- symbol_daddr: name of data symbol being executed on at the time of sample
145 	- dso_daddr: name of library or module containing the data being executed
146 	on at the time of the sample
147 	- locked: whether the bus was locked at the time of the sample
148 	- tlb: type of tlb access for the data at the time of the sample
149 	- mem: type of memory access for the data at the time of the sample
150 	- snoop: type of snoop (if any) for the data at the time of the sample
151 	- dcacheline: the cacheline the data address is on at the time of the sample
152 	- phys_daddr: physical address of data being executed on at the time of sample
154 	And the default sort keys are changed to local_weight, mem, sym, dso,
155 	symbol_daddr, dso_daddr, snoop, tlb, locked, see '--mem-mode'.
161 	- trace: pretty printed trace output in a single column
162 	- trace_fields: fields in tracepoints in separate columns
163 	- <field name>: optional event and field name for a specific field
175 	and shows raw field value like hex numbers.  The --raw-trace option
178 	The default sort keys are changed to 'trace' if all events in the data
181 -F::
182 --fields=::
183 	Specify output field - multiple keys can be specified in CSV format.
185 	overhead, overhead_sys, overhead_us, overhead_children, sample and period.
188 	By default, every sort keys not specified in -F will be appended
192         field(s) to the default field order. For example: perf report -F +period,sample.
194 -p::
195 --parent=<regex>::
199 	defaults to "\^sys_|^do_page_fault", see '--sort parent'.
201 -x::
202 --exclude-other::
203         Only display entries with parent-match.
205 -w::
206 --column-widths=<width[,width...]>::
208 	readability.  0 means no limit (default behavior).
210 -t::
211 --field-separator=::
216 -D::
217 --dump-raw-trace::
220 -g::
221 --call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>::
228 	- flat: single column, linear exposure of call chains.
229 	- graph: use a graph tree, displaying absolute overhead rates. (default)
230 	- fractal: like graph, but displays relative rates. Each branch of
232 	- folded: call chains are displayed in a line, separated by semicolons
233 	- none: disable call chain display.
236 	included in the output call graph.  Default is 0.5 (%).
241 	Default is 0 (unlimited).
244 	- callee: callee based call graph.
245 	- caller: inverted caller based call graph.
246 	Default is 'caller' when --children is used, otherwise 'callee'.
249 	- function: compare on functions (default)
250 	- address: compare on individual code addresses
251 	- srcline: compare on source filename and line number
254 	- branch: include last branch information in callgraph when available.
255 	          Usually more convenient to use --branch-history for this.
258 	- percent: display overhead percent (default)
259 	- period: display event period
260 	- count: display event count
262 --children::
267 	default, disable with --no-children.
269 --max-stack::
271 	beyond the specified depth will be ignored. This is a trade-off
274 	Note that when using the --itrace option the synthesized callchain size
277 	Default: 127
279 -G::
280 --inverted::
283 --ignore-callees=<regex>::
286         function into one place in the call-graph tree.
288 --pretty=<key>::
291 --stdio:: Use the stdio interface.
293 --stdio-color::
296 	Use '--stdio-color always' to generate color even when redirecting
297 	to a pipe or file. Using just '--stdio-color' is equivalent to
300 --tui:: Use the TUI interface, that is integrated with annotate and allows
301         zooming into DSOs or threads, among other features. Use of --tui
305 --gtk:: Use the GTK2 interface.
307 -k::
308 --vmlinux=<file>::
311 --ignore-vmlinux::
314 --kallsyms=<file>::
317 -m::
318 --modules::
319         Load module symbols. WARNING: This should only be used with -k and
322 -f::
323 --force::
326 --symfs=<directory>::
329 -C::
330 --cpu:: Only report samples for the list of CPUs provided. Multiple CPUs can
331 	be provided as a comma-separated list with no space: 0,1. Ranges of
332 	CPUs are specified with -: 0-2. Default is to report samples on all
335 -M::
336 --disassembler-style=:: Set disassembler style for objdump.
338 --source::
339 	Interleave source code with assembly code. Enabled by default,
340 	disable with --no-source.
342 --asm-raw::
345 --show-total-period:: Show a column with the sum of periods.
347 -I::
348 --show-info::
353 -b::
354 --branch-stack::
357 	perf.data file must have been obtained using perf record -b or
358 	perf record --branch-filter xxx where xxx is a branch filter option.
359 	perf report is able to auto-detect whether a perf.data file contains
361 	unless --no-branch-stack is used.
363 --branch-history::
365 	This allows to examine the path the program took to each sample.
366 	The data collection must have used -b (or -j) and -g.
368 --objdump=<path>::
371 --prefix=PREFIX::
372 --prefix-strip=N::
377 --group::
381 --group-sort-idx::
386 --demangle::
387 	Demangle symbol names to human readable form. It's enabled by default,
388 	disable with --no-demangle.
390 --demangle-kernel::
393 --mem-mode::
396 	file must have been obtained using perf record -d -W and using a
397 	special event -e cpu/mem-loads/p or -e cpu/mem-stores/p. See
400 --percent-limit::
402 	(Default: 0).  Note that this option also sets the percent limit (threshold)
403 	of callchains.  However the default value of callchain threshold is
404 	different than the default value of hist entries.  Please see the
405 	--call-graph option for details.
407 --percentage::
409 	Filters can be applied by --comms, --dsos and/or --symbols options and
416 --header::
420 	--stdio output supports this feature.
422 --header-only::
423 	Show only perf.data header (forces --stdio).
425 --time::
431 	requires the argument to be quoted e.g. --time "1234.567,1234.789 1235,"
434 	'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'.
439 	  perf report --time 10%/2
443 	  perf report --time 0%-10%
447 	  perf report --time 10%/1,10%/2
451 	  perf report --time 0%-10%,30%-40%
453 --switch-on EVENT_NAME::
457 	phase is over, i.e. insert a perf probe at that point and then using this
460 --switch-off EVENT_NAME::
463 --show-on-off-events::
464 	Show the --switch-on/off events too. This has no effect in 'perf report' now
465 	but probably we'll make the default not to show the switch-on/off events
466         on the --group mode and if there is only one event besides the off/on ones,
470 --itrace::
475 	To disable decoding entirely, use --no-itrace.
477 --full-source-path::
480 --show-ref-call-graph::
482 	callgraphs for all of them. The sample sites are usually nearby,
484 	So user can use "call-graph=no" event modifier to disable callgraph
491 --stitch-lbr::
494 	perf record --call-graph lbr.
495 	Disabled by default. In common cases with call stack overflows,
496 	it can recreate better call stacks than the default lbr call stack
502 --socket-filter::
505 --samples=N::
509 --raw-trace::
512 --hierarchy::
515 --inline::
518 	default, disable with --no-inline.
520 --mmaps::
521 	Show --tasks output plus mmap information in a format similar to
525 	are include 'perf record --data', for instance.
527 --ns::
530 --stats::
532 	(like the one at the end of the perf report -D command)
534 --tasks::
538 --percent-type::
540 	  global-period, local-period, global-hits, local-hits
545 	on - the samples period or the number of samples (hits).
547 --time-quantum::
548 	Configure time quantum for time sort key. Default 100ms.
551 --total-cycles::
552 	When --total-cycles is specified, it supports sorting for all blocks by
556 	'Sampled Cycles%' - block sampled cycles aggregation / total sampled cycles
557 	'Sampled Cycles'  - block sampled cycles aggregation
558 	'Avg Cycles%'     - block average sampled cycles / sum of total block average
560 	'Avg Cycles'      - block average sampled cycles
562 include::callchain-overhead-calculation.txt[]
565 --------
566 linkperf:perf-stat[1], linkperf:perf-annotate[1], linkperf:perf-record[1],
567 linkperf:perf-intel-pt[1]