Loading...
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. Use 'max' to use the currently maximum
59 allowed frequency, i.e. the value in the kernel.perf_event_max_sample_rate
60 sysctl.
61
62-i::
63--inherit::
64 Child tasks do not inherit counters.
65
66-k <path>::
67--vmlinux=<path>::
68 Path to vmlinux. Required for annotation functionality.
69
70--ignore-vmlinux::
71 Ignore vmlinux files.
72
73-m <pages>::
74--mmap-pages=<pages>::
75 Number of mmap data pages (must be a power of two) or size
76 specification with appended unit character - B/K/M/G. The
77 size is rounded up to have nearest pages power of two value.
78
79-p <pid>::
80--pid=<pid>::
81 Profile events on existing Process ID (comma separated list).
82
83-t <tid>::
84--tid=<tid>::
85 Profile events on existing thread ID (comma separated list).
86
87-u::
88--uid=::
89 Record events in threads owned by uid. Name or number.
90
91-r <priority>::
92--realtime=<priority>::
93 Collect data with this RT SCHED_FIFO priority.
94
95--sym-annotate=<symbol>::
96 Annotate this symbol.
97
98-K::
99--hide_kernel_symbols::
100 Hide kernel symbols.
101
102-U::
103--hide_user_symbols::
104 Hide user symbols.
105
106--demangle-kernel::
107 Demangle kernel symbols.
108
109-D::
110--dump-symtab::
111 Dump the symbol table used for profiling.
112
113-v::
114--verbose::
115 Be more verbose (show counter open errors, etc).
116
117-z::
118--zero::
119 Zero history across display updates.
120
121-s::
122--sort::
123 Sort by key(s): pid, comm, dso, symbol, parent, srcline, weight,
124 local_weight, abort, in_tx, transaction, overhead, sample, period.
125 Please see description of --sort in the perf-report man page.
126
127--fields=::
128 Specify output field - multiple keys can be specified in CSV format.
129 Following fields are available:
130 overhead, overhead_sys, overhead_us, overhead_children, sample and period.
131 Also it can contain any sort key(s).
132
133 By default, every sort keys not specified in --field will be appended
134 automatically.
135
136-n::
137--show-nr-samples::
138 Show a column with the number of samples.
139
140--show-total-period::
141 Show a column with the sum of periods.
142
143--dsos::
144 Only consider symbols in these dsos. This option will affect the
145 percentage of the overhead column. See --percentage for more info.
146
147--comms::
148 Only consider symbols in these comms. This option will affect the
149 percentage of the overhead column. See --percentage for more info.
150
151--symbols::
152 Only consider these symbols. This option will affect the
153 percentage of the overhead column. See --percentage for more info.
154
155-M::
156--disassembler-style=:: Set disassembler style for objdump.
157
158--source::
159 Interleave source code with assembly code. Enabled by default,
160 disable with --no-source.
161
162--asm-raw::
163 Show raw instruction encoding of assembly instructions.
164
165-g::
166 Enables call-graph (stack chain/backtrace) recording.
167
168--call-graph [mode,type,min[,limit],order[,key][,branch]]::
169 Setup and enable call-graph (stack chain/backtrace) recording,
170 implies -g. See `--call-graph` section in perf-record and
171 perf-report man pages for details.
172
173--children::
174 Accumulate callchain of children to parent entry so that then can
175 show up in the output. The output will have a new "Children" column
176 and will be sorted on the data. It requires -g/--call-graph option
177 enabled. See the `overhead calculation' section for more details.
178 Enabled by default, disable with --no-children.
179
180--max-stack::
181 Set the stack depth limit when parsing the callchain, anything
182 beyond the specified depth will be ignored. This is a trade-off
183 between information loss and faster processing especially for
184 workloads that can have a very long callchain stack.
185
186 Default: /proc/sys/kernel/perf_event_max_stack when present, 127 otherwise.
187
188--ignore-callees=<regex>::
189 Ignore callees of the function(s) matching the given regex.
190 This has the effect of collecting the callers of each such
191 function into one place in the call-graph tree.
192
193--percent-limit::
194 Do not show entries which have an overhead under that percent.
195 (Default: 0).
196
197--percentage::
198 Determine how to display the overhead percentage of filtered entries.
199 Filters can be applied by --comms, --dsos and/or --symbols options and
200 Zoom operations on the TUI (thread, dso, etc).
201
202 "relative" means it's relative to filtered entries only so that the
203 sum of shown entries will be always 100%. "absolute" means it retains
204 the original value before and after the filter is applied.
205
206-w::
207--column-widths=<width[,width...]>::
208 Force each column width to the provided list, for large terminal
209 readability. 0 means no limit (default behavior).
210
211--proc-map-timeout::
212 When processing pre-existing threads /proc/XXX/mmap, it may take
213 a long time, because the file may be huge. A time out is needed
214 in such cases.
215 This option sets the time out limit. The default value is 500 ms.
216
217
218-b::
219--branch-any::
220 Enable taken branch stack sampling. Any type of taken branch may be sampled.
221 This is a shortcut for --branch-filter any. See --branch-filter for more infos.
222
223-j::
224--branch-filter::
225 Enable taken branch stack sampling. Each sample captures a series of consecutive
226 taken branches. The number of branches captured with each sample depends on the
227 underlying hardware, the type of branches of interest, and the executed code.
228 It is possible to select the types of branches captured by enabling filters.
229 For a full list of modifiers please see the perf record manpage.
230
231 The option requires at least one branch type among any, any_call, any_ret, ind_call, cond.
232 The privilege levels may be omitted, in which case, the privilege levels of the associated
233 event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege
234 levels are subject to permissions. When sampling on multiple events, branch stack sampling
235 is enabled for all the sampling events. The sampled branch type is the same for all events.
236 The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k
237 Note that this feature may not be available on all processors.
238
239--raw-trace::
240 When displaying traceevent output, do not use print fmt or plugins.
241
242--hierarchy::
243 Enable hierarchy output.
244
245--force::
246 Don't do ownership validation.
247
248--num-thread-synthesize::
249 The number of threads to run when synthesizing events for existing processes.
250 By default, the number of threads equals to the number of online CPUs.
251
252INTERACTIVE PROMPTING KEYS
253--------------------------
254
255[d]::
256 Display refresh delay.
257
258[e]::
259 Number of entries to display.
260
261[E]::
262 Event to display when multiple counters are active.
263
264[f]::
265 Profile display filter (>= hit count).
266
267[F]::
268 Annotation display filter (>= % of total).
269
270[s]::
271 Annotate symbol.
272
273[S]::
274 Stop annotation, return to full profile display.
275
276[K]::
277 Hide kernel symbols.
278
279[U]::
280 Hide user symbols.
281
282[z]::
283 Toggle event count zeroing across display updates.
284
285[qQ]::
286 Quit.
287
288Pressing any unmapped key displays a menu, and prompts for input.
289
290include::callchain-overhead-calculation.txt[]
291
292SEE ALSO
293--------
294linkperf:perf-stat[1], linkperf:perf-list[1], linkperf:perf-report[1]
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 [mode,type,min[,limit],order[,key][,branch]]::
164 Setup and enable call-graph (stack chain/backtrace) recording,
165 implies -g. See `--call-graph` section in perf-record and
166 perf-report man pages for details.
167
168--children::
169 Accumulate callchain of children to parent entry so that then can
170 show up in the output. The output will have a new "Children" column
171 and will be sorted on the data. It requires -g/--call-graph option
172 enabled. See the `overhead calculation' section for more details.
173
174--max-stack::
175 Set the stack depth limit when parsing the callchain, anything
176 beyond the specified depth will be ignored. This is a trade-off
177 between information loss and faster processing especially for
178 workloads that can have a very long callchain stack.
179
180 Default: 127
181
182--ignore-callees=<regex>::
183 Ignore callees of the function(s) matching the given regex.
184 This has the effect of collecting the callers of each such
185 function into one place in the call-graph tree.
186
187--percent-limit::
188 Do not show entries which have an overhead under that percent.
189 (Default: 0).
190
191--percentage::
192 Determine how to display the overhead percentage of filtered entries.
193 Filters can be applied by --comms, --dsos and/or --symbols options and
194 Zoom operations on the TUI (thread, dso, etc).
195
196 "relative" means it's relative to filtered entries only so that the
197 sum of shown entries will be always 100%. "absolute" means it retains
198 the original value before and after the filter is applied.
199
200-w::
201--column-widths=<width[,width...]>::
202 Force each column width to the provided list, for large terminal
203 readability. 0 means no limit (default behavior).
204
205--proc-map-timeout::
206 When processing pre-existing threads /proc/XXX/mmap, it may take
207 a long time, because the file may be huge. A time out is needed
208 in such cases.
209 This option sets the time out limit. The default value is 500 ms.
210
211
212-b::
213--branch-any::
214 Enable taken branch stack sampling. Any type of taken branch may be sampled.
215 This is a shortcut for --branch-filter any. See --branch-filter for more infos.
216
217-j::
218--branch-filter::
219 Enable taken branch stack sampling. Each sample captures a series of consecutive
220 taken branches. The number of branches captured with each sample depends on the
221 underlying hardware, the type of branches of interest, and the executed code.
222 It is possible to select the types of branches captured by enabling filters.
223 For a full list of modifiers please see the perf record manpage.
224
225 The option requires at least one branch type among any, any_call, any_ret, ind_call, cond.
226 The privilege levels may be omitted, in which case, the privilege levels of the associated
227 event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege
228 levels are subject to permissions. When sampling on multiple events, branch stack sampling
229 is enabled for all the sampling events. The sampled branch type is the same for all events.
230 The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k
231 Note that this feature may not be available on all processors.
232
233--raw-trace::
234 When displaying traceevent output, do not use print fmt or plugins.
235
236--hierarchy::
237 Enable hierarchy output.
238
239INTERACTIVE PROMPTING KEYS
240--------------------------
241
242[d]::
243 Display refresh delay.
244
245[e]::
246 Number of entries to display.
247
248[E]::
249 Event to display when multiple counters are active.
250
251[f]::
252 Profile display filter (>= hit count).
253
254[F]::
255 Annotation display filter (>= % of total).
256
257[s]::
258 Annotate symbol.
259
260[S]::
261 Stop annotation, return to full profile display.
262
263[z]::
264 Toggle event count zeroing across display updates.
265
266[qQ]::
267 Quit.
268
269Pressing any unmapped key displays a menu, and prompts for input.
270
271include::callchain-overhead-calculation.txt[]
272
273SEE ALSO
274--------
275linkperf:perf-stat[1], linkperf:perf-list[1], linkperf:perf-report[1]