1perf-top(1)
2===========
3
4NAME
5----
6perf-top - System profiling tool.
7
8SYNOPSIS
9--------
10[verse]
11'perf top' [-e <EVENT> | --event=EVENT] [<options>]
12
13DESCRIPTION
14-----------
15This command generates and displays a performance counter profile in real time.
16
17
18OPTIONS
19-------
20-a::
21--all-cpus::
22        System-wide collection.  (default)
23
24-c <count>::
25--count=<count>::
26	Event period to sample.
27
28-C <cpu-list>::
29--cpu=<cpu>::
30Monitor only on the list of CPUs provided. Multiple CPUs can be provided as a
31comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2.
32Default is to monitor all CPUS.
33
34-d <seconds>::
35--delay=<seconds>::
36	Number of seconds to delay between refreshes.
37
38-e <event>::
39--event=<event>::
40	Select the PMU event. Selection can be a symbolic event name
41	(use 'perf list' to list all events) or a raw PMU
42	event (eventsel+umask) in the form of rNNN where NNN is a
43	hexadecimal event descriptor.
44
45-E <entries>::
46--entries=<entries>::
47	Display this many functions.
48
49-f <count>::
50--count-filter=<count>::
51	Only display functions with more events than this.
52
53--group::
54        Put the counters into a counter group.
55
56-F <freq>::
57--freq=<freq>::
58	Profile at this frequency.
59
60-i::
61--inherit::
62	Child tasks do not inherit counters.
63
64-k <path>::
65--vmlinux=<path>::
66	Path to vmlinux.  Required for annotation functionality.
67
68-m <pages>::
69--mmap-pages=<pages>::
70	Number of mmap data pages (must be a power of two) or size
71	specification with appended unit character - B/K/M/G. The
72	size is rounded up to have nearest pages power of two value.
73
74-p <pid>::
75--pid=<pid>::
76	Profile events on existing Process ID (comma separated list).
77
78-t <tid>::
79--tid=<tid>::
80        Profile events on existing thread ID (comma separated list).
81
82-u::
83--uid=::
84        Record events in threads owned by uid. Name or number.
85
86-r <priority>::
87--realtime=<priority>::
88	Collect data with this RT SCHED_FIFO priority.
89
90--sym-annotate=<symbol>::
91        Annotate this symbol.
92
93-K::
94--hide_kernel_symbols::
95        Hide kernel symbols.
96
97-U::
98--hide_user_symbols::
99        Hide user symbols.
100
101--demangle-kernel::
102        Demangle kernel symbols.
103
104-D::
105--dump-symtab::
106        Dump the symbol table used for profiling.
107
108-v::
109--verbose::
110	Be more verbose (show counter open errors, etc).
111
112-z::
113--zero::
114	Zero history across display updates.
115
116-s::
117--sort::
118	Sort by key(s): pid, comm, dso, symbol, parent, srcline, weight,
119	local_weight, abort, in_tx, transaction, overhead, sample, period.
120	Please see description of --sort in the perf-report man page.
121
122--fields=::
123	Specify output field - multiple keys can be specified in CSV format.
124	Following fields are available:
125	overhead, overhead_sys, overhead_us, overhead_children, sample and period.
126	Also it can contain any sort key(s).
127
128	By default, every sort keys not specified in --field will be appended
129	automatically.
130
131-n::
132--show-nr-samples::
133	Show a column with the number of samples.
134
135--show-total-period::
136	Show a column with the sum of periods.
137
138--dsos::
139	Only consider symbols in these dsos.  This option will affect the
140	percentage of the overhead column.  See --percentage for more info.
141
142--comms::
143	Only consider symbols in these comms.  This option will affect the
144	percentage of the overhead column.  See --percentage for more info.
145
146--symbols::
147	Only consider these symbols.  This option will affect the
148	percentage of the overhead column.  See --percentage for more info.
149
150-M::
151--disassembler-style=:: Set disassembler style for objdump.
152
153--source::
154	Interleave source code with assembly code. Enabled by default,
155	disable with --no-source.
156
157--asm-raw::
158	Show raw instruction encoding of assembly instructions.
159
160-g::
161	Enables call-graph (stack chain/backtrace) recording.
162
163--call-graph::
164	Setup and enable call-graph (stack chain/backtrace) recording,
165	implies -g.
166
167--children::
168	Accumulate callchain of children to parent entry so that then can
169	show up in the output.  The output will have a new "Children" column
170	and will be sorted on the data.  It requires -g/--call-graph option
171	enabled.
172
173--max-stack::
174	Set the stack depth limit when parsing the callchain, anything
175	beyond the specified depth will be ignored. This is a trade-off
176	between information loss and faster processing especially for
177	workloads that can have a very long callchain stack.
178
179	Default: 127
180
181--ignore-callees=<regex>::
182        Ignore callees of the function(s) matching the given regex.
183        This has the effect of collecting the callers of each such
184        function into one place in the call-graph tree.
185
186--percent-limit::
187	Do not show entries which have an overhead under that percent.
188	(Default: 0).
189
190--percentage::
191	Determine how to display the overhead percentage of filtered entries.
192	Filters can be applied by --comms, --dsos and/or --symbols options and
193	Zoom operations on the TUI (thread, dso, etc).
194
195	"relative" means it's relative to filtered entries only so that the
196	sum of shown entries will be always 100%. "absolute" means it retains
197	the original value before and after the filter is applied.
198
199-w::
200--column-widths=<width[,width...]>::
201	Force each column width to the provided list, for large terminal
202	readability.  0 means no limit (default behavior).
203
204
205INTERACTIVE PROMPTING KEYS
206--------------------------
207
208[d]::
209	Display refresh delay.
210
211[e]::
212	Number of entries to display.
213
214[E]::
215	Event to display when multiple counters are active.
216
217[f]::
218	Profile display filter (>= hit count).
219
220[F]::
221	Annotation display filter (>= % of total).
222
223[s]::
224	Annotate symbol.
225
226[S]::
227	Stop annotation, return to full profile display.
228
229[z]::
230	Toggle event count zeroing across display updates.
231
232[qQ]::
233	Quit.
234
235Pressing any unmapped key displays a menu, and prompts for input.
236
237
238SEE ALSO
239--------
240linkperf:perf-stat[1], linkperf:perf-list[1], linkperf:perf-report[1]
241