Commit | Line | Data |
---|---|---|
1d8c8b20 | 1 | perf-top(1) |
6e6b754f | 2 | =========== |
1d8c8b20 IM |
3 | |
4 | NAME | |
5 | ---- | |
83617983 | 6 | perf-top - System profiling tool. |
1d8c8b20 IM |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
83617983 | 11 | 'perf top' [-e <EVENT> | --event=EVENT] [<options>] |
1d8c8b20 IM |
12 | |
13 | DESCRIPTION | |
14 | ----------- | |
2e7a9881 | 15 | This command generates and displays a performance counter profile in real time. |
1d8c8b20 IM |
16 | |
17 | ||
18 | OPTIONS | |
19 | ------- | |
83617983 MG |
20 | -a:: |
21 | --all-cpus:: | |
22 | System-wide collection. (default) | |
23 | ||
24 | -c <count>:: | |
25 | --count=<count>:: | |
26 | Event period to sample. | |
27 | ||
c45c6ea2 SE |
28 | -C <cpu-list>:: |
29 | --cpu=<cpu>:: | |
2e7a9881 SB |
30 | Monitor only on the list of CPUs provided. Multiple CPUs can be provided as a |
31 | comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2. | |
c45c6ea2 | 32 | Default is to monitor all CPUS. |
83617983 MG |
33 | |
34 | -d <seconds>:: | |
35 | --delay=<seconds>:: | |
36 | Number of seconds to delay between refreshes. | |
1d8c8b20 | 37 | |
83617983 MG |
38 | -e <event>:: |
39 | --event=<event>:: | |
386b05e3 | 40 | Select the PMU event. Selection can be a symbolic event name |
4edb117e SD |
41 | (use 'perf list' to list all events) or a raw PMU event in the form |
42 | of rN where N is a hexadecimal value that represents the raw register | |
43 | encoding with the layout of the event control registers as described | |
8db43088 | 44 | by entries in /sys/bus/event_source/devices/cpu/format/*. |
1d8c8b20 | 45 | |
83617983 MG |
46 | -E <entries>:: |
47 | --entries=<entries>:: | |
48 | Display this many functions. | |
49 | ||
50 | -f <count>:: | |
51 | --count-filter=<count>:: | |
52 | Only display functions with more events than this. | |
53 | ||
df7deb2c JY |
54 | --group-sort-idx:: |
55 | Sort the output by the event at the index n in group. If n is invalid, | |
56 | sort by the first event. It can support multiple groups with different | |
57 | amount of events. WARNING: This should be used on grouped events. | |
58 | ||
83617983 MG |
59 | -F <freq>:: |
60 | --freq=<freq>:: | |
7831bf23 ACM |
61 | Profile at this frequency. Use 'max' to use the currently maximum |
62 | allowed frequency, i.e. the value in the kernel.perf_event_max_sample_rate | |
63 | sysctl. | |
83617983 MG |
64 | |
65 | -i:: | |
66 | --inherit:: | |
2376c67a | 67 | Child tasks do not inherit counters. |
83617983 MG |
68 | |
69 | -k <path>:: | |
70 | --vmlinux=<path>:: | |
71 | Path to vmlinux. Required for annotation functionality. | |
72 | ||
a8403912 ACM |
73 | --ignore-vmlinux:: |
74 | Ignore vmlinux files. | |
75 | ||
1b3aae90 ACM |
76 | --kallsyms=<file>:: |
77 | kallsyms pathname | |
78 | ||
83617983 MG |
79 | -m <pages>:: |
80 | --mmap-pages=<pages>:: | |
27050f53 JO |
81 | Number of mmap data pages (must be a power of two) or size |
82 | specification with appended unit character - B/K/M/G. The | |
83 | size is rounded up to have nearest pages power of two value. | |
83617983 MG |
84 | |
85 | -p <pid>:: | |
86 | --pid=<pid>:: | |
b52956c9 | 87 | Profile events on existing Process ID (comma separated list). |
2e7a9881 SB |
88 | |
89 | -t <tid>:: | |
90 | --tid=<tid>:: | |
b52956c9 | 91 | Profile events on existing thread ID (comma separated list). |
83617983 | 92 | |
0d37aa34 ACM |
93 | -u:: |
94 | --uid=:: | |
95 | Record events in threads owned by uid. Name or number. | |
96 | ||
83617983 MG |
97 | -r <priority>:: |
98 | --realtime=<priority>:: | |
99 | Collect data with this RT SCHED_FIFO priority. | |
100 | ||
83617983 | 101 | --sym-annotate=<symbol>:: |
6cff0e8d | 102 | Annotate this symbol. |
83617983 | 103 | |
2e7a9881 SB |
104 | -K:: |
105 | --hide_kernel_symbols:: | |
106 | Hide kernel symbols. | |
107 | ||
108 | -U:: | |
109 | --hide_user_symbols:: | |
110 | Hide user symbols. | |
111 | ||
763122ad AK |
112 | --demangle-kernel:: |
113 | Demangle kernel symbols. | |
114 | ||
2e7a9881 SB |
115 | -D:: |
116 | --dump-symtab:: | |
117 | Dump the symbol table used for profiling. | |
118 | ||
83617983 MG |
119 | -v:: |
120 | --verbose:: | |
121 | Be more verbose (show counter open errors, etc). | |
122 | ||
123 | -z:: | |
124 | --zero:: | |
125 | Zero history across display updates. | |
126 | ||
ab81f3fd ACM |
127 | -s:: |
128 | --sort:: | |
f5d05bce | 129 | Sort by key(s): pid, comm, dso, symbol, parent, srcline, weight, |
a2ce067e NK |
130 | local_weight, abort, in_tx, transaction, overhead, sample, period. |
131 | Please see description of --sort in the perf-report man page. | |
ab81f3fd | 132 | |
6fe8c26d NK |
133 | --fields=:: |
134 | Specify output field - multiple keys can be specified in CSV format. | |
135 | Following fields are available: | |
1432ec34 | 136 | overhead, overhead_sys, overhead_us, overhead_children, sample and period. |
6fe8c26d NK |
137 | Also it can contain any sort key(s). |
138 | ||
139 | By default, every sort keys not specified in --field will be appended | |
140 | automatically. | |
141 | ||
ab81f3fd ACM |
142 | -n:: |
143 | --show-nr-samples:: | |
144 | Show a column with the number of samples. | |
145 | ||
146 | --show-total-period:: | |
147 | Show a column with the sum of periods. | |
148 | ||
149 | --dsos:: | |
33db4568 NK |
150 | Only consider symbols in these dsos. This option will affect the |
151 | percentage of the overhead column. See --percentage for more info. | |
ab81f3fd ACM |
152 | |
153 | --comms:: | |
33db4568 NK |
154 | Only consider symbols in these comms. This option will affect the |
155 | percentage of the overhead column. See --percentage for more info. | |
ab81f3fd ACM |
156 | |
157 | --symbols:: | |
33db4568 NK |
158 | Only consider these symbols. This option will affect the |
159 | percentage of the overhead column. See --percentage for more info. | |
ab81f3fd | 160 | |
64c6f0c7 ACM |
161 | -M:: |
162 | --disassembler-style=:: Set disassembler style for objdump. | |
163 | ||
57594454 IR |
164 | --addr2line=<path>:: |
165 | Path to addr2line binary. | |
166 | ||
167 | --objdump=<path>:: | |
168 | Path to objdump binary. | |
169 | ||
3b0b16bf AK |
170 | --prefix=PREFIX:: |
171 | --prefix-strip=N:: | |
172 | Remove first N entries from source file path names in executables | |
173 | and add PREFIX. This allows to display source code compiled on systems | |
174 | with different file system layout. | |
175 | ||
64c6f0c7 ACM |
176 | --source:: |
177 | Interleave source code with assembly code. Enabled by default, | |
178 | disable with --no-source. | |
179 | ||
180 | --asm-raw:: | |
181 | Show raw instruction encoding of assembly instructions. | |
182 | ||
bf80669e | 183 | -g:: |
ae779a63 JO |
184 | Enables call-graph (stack chain/backtrace) recording. |
185 | ||
a2c10d39 | 186 | --call-graph [mode,type,min[,limit],order[,key][,branch]]:: |
ae779a63 | 187 | Setup and enable call-graph (stack chain/backtrace) recording, |
a2c10d39 NK |
188 | implies -g. See `--call-graph` section in perf-record and |
189 | perf-report man pages for details. | |
19d4ac3c | 190 | |
1432ec34 NK |
191 | --children:: |
192 | Accumulate callchain of children to parent entry so that then can | |
193 | show up in the output. The output will have a new "Children" column | |
194 | and will be sorted on the data. It requires -g/--call-graph option | |
dd309207 | 195 | enabled. See the `overhead calculation' section for more details. |
108a7c10 | 196 | Enabled by default, disable with --no-children. |
1432ec34 | 197 | |
5dbb6e81 WL |
198 | --max-stack:: |
199 | Set the stack depth limit when parsing the callchain, anything | |
200 | beyond the specified depth will be ignored. This is a trade-off | |
201 | between information loss and faster processing especially for | |
202 | workloads that can have a very long callchain stack. | |
203 | ||
4cb93446 | 204 | Default: /proc/sys/kernel/perf_event_max_stack when present, 127 otherwise. |
5dbb6e81 | 205 | |
b21484f1 GP |
206 | --ignore-callees=<regex>:: |
207 | Ignore callees of the function(s) matching the given regex. | |
208 | This has the effect of collecting the callers of each such | |
209 | function into one place in the call-graph tree. | |
210 | ||
fa5df943 NK |
211 | --percent-limit:: |
212 | Do not show entries which have an overhead under that percent. | |
213 | (Default: 0). | |
214 | ||
33db4568 NK |
215 | --percentage:: |
216 | Determine how to display the overhead percentage of filtered entries. | |
217 | Filters can be applied by --comms, --dsos and/or --symbols options and | |
218 | Zoom operations on the TUI (thread, dso, etc). | |
219 | ||
220 | "relative" means it's relative to filtered entries only so that the | |
221 | sum of shown entries will be always 100%. "absolute" means it retains | |
222 | the original value before and after the filter is applied. | |
223 | ||
cf59002f NK |
224 | -w:: |
225 | --column-widths=<width[,width...]>:: | |
226 | Force each column width to the provided list, for large terminal | |
227 | readability. 0 means no limit (default behavior). | |
228 | ||
9d9cad76 KL |
229 | --proc-map-timeout:: |
230 | When processing pre-existing threads /proc/XXX/mmap, it may take | |
231 | a long time, because the file may be huge. A time out is needed | |
232 | in such cases. | |
233 | This option sets the time out limit. The default value is 500 ms. | |
234 | ||
cf59002f | 235 | |
a18b027e AK |
236 | -b:: |
237 | --branch-any:: | |
238 | Enable taken branch stack sampling. Any type of taken branch may be sampled. | |
239 | This is a shortcut for --branch-filter any. See --branch-filter for more infos. | |
240 | ||
241 | -j:: | |
242 | --branch-filter:: | |
243 | Enable taken branch stack sampling. Each sample captures a series of consecutive | |
244 | taken branches. The number of branches captured with each sample depends on the | |
245 | underlying hardware, the type of branches of interest, and the executed code. | |
246 | It is possible to select the types of branches captured by enabling filters. | |
247 | For a full list of modifiers please see the perf record manpage. | |
248 | ||
249 | The option requires at least one branch type among any, any_call, any_ret, ind_call, cond. | |
250 | The privilege levels may be omitted, in which case, the privilege levels of the associated | |
251 | event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege | |
252 | levels are subject to permissions. When sampling on multiple events, branch stack sampling | |
253 | is enabled for all the sampling events. The sampled branch type is the same for all events. | |
254 | The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k | |
255 | Note that this feature may not be available on all processors. | |
256 | ||
5ef50613 AH |
257 | --branch-history:: |
258 | Add the addresses of sampled taken branches to the callstack. | |
259 | This allows to examine the path the program took to each sample. | |
260 | ||
053a3989 NK |
261 | --raw-trace:: |
262 | When displaying traceevent output, do not use print fmt or plugins. | |
263 | ||
7727d59d | 264 | -H:: |
c92fcfde | 265 | --hierarchy:: |
7727d59d NK |
266 | Enable hierarchical output. In the hierarchy mode, each sort key groups |
267 | samples based on the criteria and then sub-divide it using the lower | |
268 | level sort key. | |
269 | ||
270 | For example, in normal output: | |
271 | ||
272 | perf report -s dso,sym | |
273 | # | |
274 | # Overhead Shared Object Symbol | |
275 | # ........ ................. ........... | |
276 | 50.00% [kernel.kallsyms] [k] kfunc1 | |
277 | 20.00% perf [.] foo | |
278 | 15.00% [kernel.kallsyms] [k] kfunc2 | |
279 | 10.00% perf [.] bar | |
280 | 5.00% libc.so [.] libcall | |
281 | ||
282 | In hierarchy output: | |
283 | ||
284 | perf report -s dso,sym --hierarchy | |
285 | # | |
286 | # Overhead Shared Object / Symbol | |
287 | # .......... ...................... | |
288 | 65.00% [kernel.kallsyms] | |
289 | 50.00% [k] kfunc1 | |
290 | 15.00% [k] kfunc2 | |
291 | 30.00% perf | |
292 | 20.00% [.] foo | |
293 | 10.00% [.] bar | |
294 | 5.00% libc.so | |
295 | 5.00% [.] libcall | |
c92fcfde | 296 | |
4e303fbe | 297 | --overwrite:: |
218d6111 ACM |
298 | Enable this to use just the most recent records, which helps in high core count |
299 | machines such as Knights Landing/Mill, but right now is disabled by default as | |
300 | the pausing used in this technique is leading to loss of metadata events such | |
301 | as PERF_RECORD_MMAP which makes 'perf top' unable to resolve samples, leading | |
302 | to lots of unknown samples appearing on the UI. Enable this if you are in such | |
303 | machines and profiling a workload that doesn't creates short lived threads and/or | |
304 | doesn't uses many executable mmap operations. Work is being planed to solve | |
305 | this situation, till then, this will remain disabled by default. | |
4e303fbe | 306 | |
868a8329 KJ |
307 | --force:: |
308 | Don't do ownership validation. | |
309 | ||
0c6b4994 KL |
310 | --num-thread-synthesize:: |
311 | The number of threads to run when synthesizing events for existing processes. | |
312 | By default, the number of threads equals to the number of online CPUs. | |
868a8329 | 313 | |
a0c0a4ac NK |
314 | --namespaces:: |
315 | Record events of type PERF_RECORD_NAMESPACES and display it with the | |
316 | 'cgroup_id' sort key. | |
317 | ||
51f38242 JM |
318 | -G name:: |
319 | --cgroup name:: | |
320 | monitor only in the container (cgroup) called "name". This option is available only | |
321 | in per-cpu mode. The cgroup filesystem must be mounted. All threads belonging to | |
322 | container "name" are monitored when they run on the monitored CPUs. Multiple cgroups | |
323 | can be provided. Each cgroup is applied to the corresponding event, i.e., first cgroup | |
324 | to first event, second cgroup to second event and so on. It is possible to provide | |
325 | an empty cgroup (monitor all the time) using, e.g., -G foo,,bar. Cgroups must have | |
326 | corresponding events, i.e., they always refer to events defined earlier on the command | |
327 | line. If the user wants to track multiple events for a specific cgroup, the user can | |
328 | use '-e e1 -e e2 -G foo,foo' or just use '-e e1 -e e2 -G foo'. | |
329 | ||
f382842f NK |
330 | --all-cgroups:: |
331 | Record events of type PERF_RECORD_CGROUP and display it with the | |
332 | 'cgroup' sort key. | |
333 | ||
2f53ae34 ACM |
334 | --switch-on EVENT_NAME:: |
335 | Only consider events after this event is found. | |
336 | ||
337 | E.g.: | |
338 | ||
339 | Find out where broadcast packets are handled | |
340 | ||
341 | perf probe -L icmp_rcv | |
342 | ||
343 | Insert a probe there: | |
344 | ||
345 | perf probe icmp_rcv:59 | |
346 | ||
347 | Start perf top and ask it to only consider the cycles events when a | |
348 | broadcast packet arrives This will show a menu with two entries and | |
349 | will start counting when a broadcast packet arrives: | |
350 | ||
351 | perf top -e cycles,probe:icmp_rcv --switch-on=probe:icmp_rcv | |
352 | ||
5f8f9567 | 353 | Alternatively one can ask for a group and then two overhead columns |
2f53ae34 ACM |
354 | will appear, the first for cycles and the second for the switch-on event. |
355 | ||
5f8f9567 | 356 | perf top -e '{cycles,probe:icmp_rcv}' --switch-on=probe:icmp_rcv |
2f53ae34 ACM |
357 | |
358 | This may be interesting to measure a workload only after some initialization | |
359 | phase is over, i.e. insert a perf probe at that point and use the above | |
360 | examples replacing probe:icmp_rcv with the just-after-init probe. | |
361 | ||
362 | --switch-off EVENT_NAME:: | |
363 | Stop considering events after this event is found. | |
364 | ||
365 | --show-on-off-events:: | |
366 | Show the --switch-on/off events too. This has no effect in 'perf top' now | |
367 | but probably we'll make the default not to show the switch-on/off events | |
368 | on the --group mode and if there is only one event besides the off/on ones, | |
369 | go straight to the histogram browser, just like 'perf top' with no events | |
4d39c89f | 370 | explicitly specified does. |
2f53ae34 | 371 | |
13e0c844 KL |
372 | --stitch-lbr:: |
373 | Show callgraph with stitched LBRs, which may have more complete | |
374 | callgraph. The option must be used with --call-graph lbr recording. | |
375 | Disabled by default. In common cases with call stack overflows, | |
376 | it can recreate better call stacks than the default lbr call stack | |
4cbd5334 | 377 | output. But this approach is not foolproof. There can be cases |
13e0c844 KL |
378 | where it creates incorrect call stacks from incorrect matches. |
379 | The known limitations include exception handing such as | |
380 | setjmp/longjmp will have calls/returns not match. | |
a0c0a4ac | 381 | |
70943490 SE |
382 | ifdef::HAVE_LIBPFM[] |
383 | --pfm-events events:: | |
384 | Select a PMU event using libpfm4 syntax (see http://perfmon2.sf.net) | |
385 | including support for event filters. For example '--pfm-events | |
386 | inst_retired:any_p:u:c=1:i'. More than one event can be passed to the | |
387 | option using the comma separator. Hardware events and generic hardware | |
388 | events cannot be mixed together. The latter must be used with the -e | |
389 | option. The -e option and this one can be mixed and matched. Events | |
390 | can be grouped using the {} notation. | |
391 | endif::HAVE_LIBPFM[] | |
392 | ||
83617983 MG |
393 | INTERACTIVE PROMPTING KEYS |
394 | -------------------------- | |
395 | ||
396 | [d]:: | |
397 | Display refresh delay. | |
398 | ||
399 | [e]:: | |
400 | Number of entries to display. | |
401 | ||
402 | [E]:: | |
403 | Event to display when multiple counters are active. | |
404 | ||
405 | [f]:: | |
406 | Profile display filter (>= hit count). | |
407 | ||
408 | [F]:: | |
409 | Annotation display filter (>= % of total). | |
410 | ||
411 | [s]:: | |
412 | Annotate symbol. | |
413 | ||
414 | [S]:: | |
415 | Stop annotation, return to full profile display. | |
416 | ||
958964f8 SJ |
417 | [K]:: |
418 | Hide kernel symbols. | |
419 | ||
420 | [U]:: | |
421 | Hide user symbols. | |
422 | ||
83617983 MG |
423 | [z]:: |
424 | Toggle event count zeroing across display updates. | |
425 | ||
426 | [qQ]:: | |
427 | Quit. | |
428 | ||
429 | Pressing any unmapped key displays a menu, and prompts for input. | |
1d8c8b20 | 430 | |
dd309207 | 431 | include::callchain-overhead-calculation.txt[] |
1d8c8b20 | 432 | |
1d8c8b20 IM |
433 | SEE ALSO |
434 | -------- | |
a2ce067e | 435 | linkperf:perf-stat[1], linkperf:perf-list[1], linkperf:perf-report[1] |