1perf-report(1)
2==============
3
4NAME
5----
6perf-report - Read perf.data (created by perf record) and display the profile
7
8SYNOPSIS
9--------
10[verse]
11'perf report' [-i <file> | --input=file]
12
13DESCRIPTION
14-----------
15This command displays the performance counter profile information recorded
16via perf record.
17
18OPTIONS
19-------
20-i::
21--input=::
22        Input file name. (default: perf.data unless stdin is a fifo)
23
24-v::
25--verbose::
26        Be more verbose. (show symbol address, etc)
27
28-q::
29--quiet::
30	Do not show any message.  (Suppress -v)
31
32-n::
33--show-nr-samples::
34	Show the number of samples for each symbol
35
36--show-cpu-utilization::
37        Show sample percentage for different cpu modes.
38
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=::
45	Only consider symbols in these comms. CSV that understands
46	file://filename entries.  This option will affect the percentage of
47	the overhead column.  See --percentage for more info.
48--pid=::
49        Only show events for given process ID (comma separated list).
50
51--tid=::
52        Only show events for given thread ID (comma separated list).
53-d::
54--dsos=::
55	Only consider symbols in these dsos. CSV that understands
56	file://filename entries.  This option will affect the percentage of
57	the overhead column.  See --percentage for more info.
58-S::
59--symbols=::
60	Only consider these symbols. CSV that understands
61	file://filename entries.  This option will affect the percentage of
62	the overhead column.  See --percentage for more info.
63
64--symbol-filter=::
65	Only show symbols that match (partially) with this filter.
66
67-U::
68--hide-unresolved::
69        Only display entries resolved to a symbol.
70
71-s::
72--sort=::
73	Sort histogram entries by given key(s) - multiple keys can be specified
74	in CSV format.  Following sort keys are available:
75	pid, comm, dso, symbol, parent, cpu, socket, srcline, weight,
76	local_weight, cgroup_id.
77
78	Each key has following meaning:
79
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	- symbol: name of function executed at the time of sample
84	- symbol_size: size of function executed at the time of sample
85	- parent: name of function matched to the parent regex filter. Unmatched
86	entries are displayed as "[other]".
87	- cpu: cpu number the task ran at the time of sample
88	- socket: processor socket number the task ran at the time of sample
89	- srcline: filename and line number executed at the time of sample.  The
90	DWARF debugging info must be provided.
91	- srcfile: file name of the source file of the same. Requires dwarf
92	information.
93	- weight: Event specific weight, e.g. memory latency or transaction
94	abort cost. This is the global weight.
95	- local_weight: Local weight version of the weight above.
96	- cgroup_id: ID derived from cgroup namespace device and inode numbers.
97	- transaction: Transaction abort flags.
98	- overhead: Overhead percentage of sample
99	- overhead_sys: Overhead percentage of sample running in system mode
100	- overhead_us: Overhead percentage of sample running in user mode
101	- overhead_guest_sys: Overhead percentage of sample running in system mode
102	on guest machine
103	- overhead_guest_us: Overhead percentage of sample running in user mode on
104	guest machine
105	- sample: Number of sample
106	- period: Raw number of event count of sample
107
108	By default, comm, dso and symbol keys are used.
109	(i.e. --sort comm,dso,symbol)
110
111	If --branch-stack option is used, following sort keys are also
112	available:
113
114	- dso_from: name of library or module branched from
115	- dso_to: name of library or module branched to
116	- symbol_from: name of function branched from
117	- symbol_to: name of function branched to
118	- srcline_from: source file and line branched from
119	- srcline_to: source file and line branched to
120	- mispredict: "N" for predicted branch, "Y" for mispredicted branch
121	- in_tx: branch in TSX transaction
122	- abort: TSX transaction abort.
123	- cycles: Cycles in basic block
124
125	And default sort keys are changed to comm, dso_from, symbol_from, dso_to
126	and symbol_to, see '--branch-stack'.
127
128	If the --mem-mode option is used, the following sort keys are also available
129	(incompatible with --branch-stack):
130	symbol_daddr, dso_daddr, locked, tlb, mem, snoop, dcacheline.
131
132	- symbol_daddr: name of data symbol being executed on at the time of sample
133	- dso_daddr: name of library or module containing the data being executed
134	on at the time of the sample
135	- locked: whether the bus was locked at the time of the sample
136	- tlb: type of tlb access for the data at the time of the sample
137	- mem: type of memory access for the data at the time of the sample
138	- snoop: type of snoop (if any) for the data at the time of the sample
139	- dcacheline: the cacheline the data address is on at the time of the sample
140	- phys_daddr: physical address of data being executed on at the time of sample
141
142	And the default sort keys are changed to local_weight, mem, sym, dso,
143	symbol_daddr, dso_daddr, snoop, tlb, locked, see '--mem-mode'.
144
145	If the data file has tracepoint event(s), following (dynamic) sort keys
146	are also available:
147	trace, trace_fields, [<event>.]<field>[/raw]
148
149	- trace: pretty printed trace output in a single column
150	- trace_fields: fields in tracepoints in separate columns
151	- <field name>: optional event and field name for a specific field
152
153	The last form consists of event and field names.  If event name is
154	omitted, it searches all events for matching field name.  The matched
155	field will be shown only for the event has the field.  The event name
156	supports substring match so user doesn't need to specify full subsystem
157	and event name everytime.  For example, 'sched:sched_switch' event can
158	be shortened to 'switch' as long as it's not ambiguous.  Also event can
159	be specified by its index (starting from 1) preceded by the '%'.
160	So '%1' is the first event, '%2' is the second, and so on.
161
162	The field name can have '/raw' suffix which disables pretty printing
163	and shows raw field value like hex numbers.  The --raw-trace option
164	has the same effect for all dynamic sort keys.
165
166	The default sort keys are changed to 'trace' if all events in the data
167	file are tracepoint.
168
169-F::
170--fields=::
171	Specify output field - multiple keys can be specified in CSV format.
172	Following fields are available:
173	overhead, overhead_sys, overhead_us, overhead_children, sample and period.
174	Also it can contain any sort key(s).
175
176	By default, every sort keys not specified in -F will be appended
177	automatically.
178
179	If the keys starts with a prefix '+', then it will append the specified
180        field(s) to the default field order. For example: perf report -F +period,sample.
181
182-p::
183--parent=<regex>::
184        A regex filter to identify parent. The parent is a caller of this
185	function and searched through the callchain, thus it requires callchain
186	information recorded. The pattern is in the extended regex format and
187	defaults to "\^sys_|^do_page_fault", see '--sort parent'.
188
189-x::
190--exclude-other::
191        Only display entries with parent-match.
192
193-w::
194--column-widths=<width[,width...]>::
195	Force each column width to the provided list, for large terminal
196	readability.  0 means no limit (default behavior).
197
198-t::
199--field-separator=::
200	Use a special separator character and don't pad with spaces, replacing
201	all occurrences of this separator in symbol names (and other output)
202	with a '.' character, that thus it's the only non valid separator.
203
204-D::
205--dump-raw-trace::
206        Dump raw trace in ASCII.
207
208-g::
209--call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>::
210        Display call chains using type, min percent threshold, print limit,
211	call order, sort key, optional branch and value.  Note that ordering
212	is not fixed so any parameter can be given in an arbitrary order.
213	One exception is the print_limit which should be preceded by threshold.
214
215	print_type can be either:
216	- flat: single column, linear exposure of call chains.
217	- graph: use a graph tree, displaying absolute overhead rates. (default)
218	- fractal: like graph, but displays relative rates. Each branch of
219		 the tree is considered as a new profiled object.
220	- folded: call chains are displayed in a line, separated by semicolons
221	- none: disable call chain display.
222
223	threshold is a percentage value which specifies a minimum percent to be
224	included in the output call graph.  Default is 0.5 (%).
225
226	print_limit is only applied when stdio interface is used.  It's to limit
227	number of call graph entries in a single hist entry.  Note that it needs
228	to be given after threshold (but not necessarily consecutive).
229	Default is 0 (unlimited).
230
231	order can be either:
232	- callee: callee based call graph.
233	- caller: inverted caller based call graph.
234	Default is 'caller' when --children is used, otherwise 'callee'.
235
236	sort_key can be:
237	- function: compare on functions (default)
238	- address: compare on individual code addresses
239	- srcline: compare on source filename and line number
240
241	branch can be:
242	- branch: include last branch information in callgraph when available.
243	          Usually more convenient to use --branch-history for this.
244
245	value can be:
246	- percent: diplay overhead percent (default)
247	- period: display event period
248	- count: display event count
249
250--children::
251	Accumulate callchain of children to parent entry so that then can
252	show up in the output.  The output will have a new "Children" column
253	and will be sorted on the data.  It requires callchains are recorded.
254	See the `overhead calculation' section for more details. Enabled by
255	default, disable with --no-children.
256
257--max-stack::
258	Set the stack depth limit when parsing the callchain, anything
259	beyond the specified depth will be ignored. This is a trade-off
260	between information loss and faster processing especially for
261	workloads that can have a very long callchain stack.
262	Note that when using the --itrace option the synthesized callchain size
263	will override this value if the synthesized callchain size is bigger.
264
265	Default: 127
266
267-G::
268--inverted::
269        alias for inverted caller based call graph.
270
271--ignore-callees=<regex>::
272        Ignore callees of the function(s) matching the given regex.
273        This has the effect of collecting the callers of each such
274        function into one place in the call-graph tree.
275
276--pretty=<key>::
277        Pretty printing style.  key: normal, raw
278
279--stdio:: Use the stdio interface.
280
281--stdio-color::
282	'always', 'never' or 'auto', allowing configuring color output
283	via the command line, in addition to via "color.ui" .perfconfig.
284	Use '--stdio-color always' to generate color even when redirecting
285	to a pipe or file. Using just '--stdio-color' is equivalent to
286	using 'always'.
287
288--tui:: Use the TUI interface, that is integrated with annotate and allows
289        zooming into DSOs or threads, among other features. Use of --tui
290	requires a tty, if one is not present, as when piping to other
291	commands, the stdio interface is used.
292
293--gtk:: Use the GTK2 interface.
294
295-k::
296--vmlinux=<file>::
297        vmlinux pathname
298
299--kallsyms=<file>::
300        kallsyms pathname
301
302-m::
303--modules::
304        Load module symbols. WARNING: This should only be used with -k and
305        a LIVE kernel.
306
307-f::
308--force::
309        Don't do ownership validation.
310
311--symfs=<directory>::
312        Look for files with symbols relative to this directory.
313
314-C::
315--cpu:: Only report samples for the list of CPUs provided. Multiple CPUs can
316	be provided as a comma-separated list with no space: 0,1. Ranges of
317	CPUs are specified with -: 0-2. Default is to report samples on all
318	CPUs.
319
320-M::
321--disassembler-style=:: Set disassembler style for objdump.
322
323--source::
324	Interleave source code with assembly code. Enabled by default,
325	disable with --no-source.
326
327--asm-raw::
328	Show raw instruction encoding of assembly instructions.
329
330--show-total-period:: Show a column with the sum of periods.
331
332-I::
333--show-info::
334	Display extended information about the perf.data file. This adds
335	information which may be very large and thus may clutter the display.
336	It currently includes: cpu and numa topology of the host system.
337
338-b::
339--branch-stack::
340	Use the addresses of sampled taken branches instead of the instruction
341	address to build the histograms. To generate meaningful output, the
342	perf.data file must have been obtained using perf record -b or
343	perf record --branch-filter xxx where xxx is a branch filter option.
344	perf report is able to auto-detect whether a perf.data file contains
345	branch stacks and it will automatically switch to the branch view mode,
346	unless --no-branch-stack is used.
347
348--branch-history::
349	Add the addresses of sampled taken branches to the callstack.
350	This allows to examine the path the program took to each sample.
351	The data collection must have used -b (or -j) and -g.
352
353--objdump=<path>::
354        Path to objdump binary.
355
356--group::
357	Show event group information together.
358
359--demangle::
360	Demangle symbol names to human readable form. It's enabled by default,
361	disable with --no-demangle.
362
363--demangle-kernel::
364	Demangle kernel symbol names to human readable form (for C++ kernels).
365
366--mem-mode::
367	Use the data addresses of samples in addition to instruction addresses
368	to build the histograms.  To generate meaningful output, the perf.data
369	file must have been obtained using perf record -d -W and using a
370	special event -e cpu/mem-loads/ or -e cpu/mem-stores/. See
371	'perf mem' for simpler access.
372
373--percent-limit::
374	Do not show entries which have an overhead under that percent.
375	(Default: 0).  Note that this option also sets the percent limit (threshold)
376	of callchains.  However the default value of callchain threshold is
377	different than the default value of hist entries.  Please see the
378	--call-graph option for details.
379
380--percentage::
381	Determine how to display the overhead percentage of filtered entries.
382	Filters can be applied by --comms, --dsos and/or --symbols options and
383	Zoom operations on the TUI (thread, dso, etc).
384
385	"relative" means it's relative to filtered entries only so that the
386	sum of shown entries will be always 100%.  "absolute" means it retains
387	the original value before and after the filter is applied.
388
389--header::
390	Show header information in the perf.data file.  This includes
391	various information like hostname, OS and perf version, cpu/mem
392	info, perf command line, event list and so on.  Currently only
393	--stdio output supports this feature.
394
395--header-only::
396	Show only perf.data header (forces --stdio).
397
398--time::
399	Only analyze samples within given time window: <start>,<stop>. Times
400	have the format seconds.microseconds. If start is not given (i.e., time
401	string is ',x.y') then analysis starts at the beginning of the file. If
402	stop time is not given (i.e, time string is 'x.y,') then analysis goes
403	to end of file.
404
405--itrace::
406	Options for decoding instruction tracing data. The options are:
407
408include::itrace.txt[]
409
410	To disable decoding entirely, use --no-itrace.
411
412--full-source-path::
413	Show the full path for source files for srcline output.
414
415--show-ref-call-graph::
416	When multiple events are sampled, it may not be needed to collect
417	callgraphs for all of them. The sample sites are usually nearby,
418	and it's enough to collect the callgraphs on a reference event.
419	So user can use "call-graph=no" event modifier to disable callgraph
420	for other events to reduce the overhead.
421	However, perf report cannot show callgraphs for the event which
422	disable the callgraph.
423	This option extends the perf report to show reference callgraphs,
424	which collected by reference event, in no callgraph event.
425
426--socket-filter::
427	Only report the samples on the processor socket that match with this filter
428
429--raw-trace::
430	When displaying traceevent output, do not use print fmt or plugins.
431
432--hierarchy::
433	Enable hierarchical output.
434
435--inline::
436	If a callgraph address belongs to an inlined function, the inline stack
437	will be printed. Each entry is function name or file/line. Enabled by
438	default, disable with --no-inline.
439
440include::callchain-overhead-calculation.txt[]
441
442SEE ALSO
443--------
444linkperf:perf-stat[1], linkperf:perf-annotate[1]
445