Linux/tools/perf/Documentation/perf-top.txt

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

1 perf-top(1) 1 perf-top(1) 2 =========== 2 =========== 3 3 4 NAME 4 NAME 5 ---- 5 ---- 6 perf-top - System profiling tool. 6 perf-top - System profiling tool. 7 7 8 SYNOPSIS 8 SYNOPSIS 9 -------- 9 -------- 10 [verse] 10 [verse] 11 'perf top' [-e <EVENT> | --event=EVENT] [<opti 11 'perf top' [-e <EVENT> | --event=EVENT] [<options>] 12 12 13 DESCRIPTION 13 DESCRIPTION 14 ----------- 14 ----------- 15 This command generates and displays a performa 15 This command generates and displays a performance counter profile in real time. 16 16 17 17 18 OPTIONS 18 OPTIONS 19 ------- 19 ------- 20 -a:: 20 -a:: 21 --all-cpus:: 21 --all-cpus:: 22 System-wide collection. (default) 22 System-wide collection. (default) 23 23 24 -c <count>:: 24 -c <count>:: 25 --count=<count>:: 25 --count=<count>:: 26 Event period to sample. 26 Event period to sample. 27 27 28 -C <cpu-list>:: 28 -C <cpu-list>:: 29 --cpu=<cpu>:: 29 --cpu=<cpu>:: 30 Monitor only on the list of CPUs provided. Mul 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. Range 31 comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2. 32 Default is to monitor all CPUS. 32 Default is to monitor all CPUS. 33 33 34 -d <seconds>:: 34 -d <seconds>:: 35 --delay=<seconds>:: 35 --delay=<seconds>:: 36 Number of seconds to delay between ref 36 Number of seconds to delay between refreshes. 37 37 38 -e <event>:: 38 -e <event>:: 39 --event=<event>:: 39 --event=<event>:: 40 Select the PMU event. Selection can be 40 Select the PMU event. Selection can be a symbolic event name 41 (use 'perf list' to list all events) o !! 41 (use 'perf list' to list all events) or a raw PMU 42 of rN where N is a hexadecimal value t !! 42 event (eventsel+umask) in the form of rNNN where NNN is a 43 encoding with the layout of the event !! 43 hexadecimal event descriptor. 44 by entries in /sys/bus/event_source/de << 45 << 46 --filter=<filter>:: << 47 Event filter. This option should foll << 48 syntax see linkperf:perf-record[1]. << 49 44 50 -E <entries>:: 45 -E <entries>:: 51 --entries=<entries>:: 46 --entries=<entries>:: 52 Display this many functions. 47 Display this many functions. 53 48 54 -f <count>:: 49 -f <count>:: 55 --count-filter=<count>:: 50 --count-filter=<count>:: 56 Only display functions with more event 51 Only display functions with more events than this. 57 52 58 --group-sort-idx:: !! 53 -g:: 59 Sort the output by the event at the in !! 54 --group:: 60 sort by the first event. It can suppor !! 55 Put the counters into a counter group. 61 amount of events. WARNING: This should << 62 56 63 -F <freq>:: 57 -F <freq>:: 64 --freq=<freq>:: 58 --freq=<freq>:: 65 Profile at this frequency. Use 'max' t !! 59 Profile at this frequency. 66 allowed frequency, i.e. the value in t << 67 sysctl. << 68 60 69 -i:: 61 -i:: 70 --inherit:: 62 --inherit:: 71 Child tasks do not inherit counters. 63 Child tasks do not inherit counters. 72 64 73 -k <path>:: 65 -k <path>:: 74 --vmlinux=<path>:: 66 --vmlinux=<path>:: 75 Path to vmlinux. Required for annotat 67 Path to vmlinux. Required for annotation functionality. 76 68 77 --ignore-vmlinux:: << 78 Ignore vmlinux files. << 79 << 80 --kallsyms=<file>:: << 81 kallsyms pathname << 82 << 83 -m <pages>:: 69 -m <pages>:: 84 --mmap-pages=<pages>:: 70 --mmap-pages=<pages>:: 85 Number of mmap data pages (must be a p !! 71 Number of mmapped data pages. 86 specification in bytes with appended u << 87 The size is rounded up to the nearest << 88 72 89 -p <pid>:: 73 -p <pid>:: 90 --pid=<pid>:: 74 --pid=<pid>:: 91 Profile events on existing Process ID 75 Profile events on existing Process ID (comma separated list). 92 76 93 -t <tid>:: 77 -t <tid>:: 94 --tid=<tid>:: 78 --tid=<tid>:: 95 Profile events on existing thread ID ( 79 Profile events on existing thread ID (comma separated list). 96 80 97 -u:: 81 -u:: 98 --uid=:: 82 --uid=:: 99 Record events in threads owned by uid. 83 Record events in threads owned by uid. Name or number. 100 84 101 -r <priority>:: 85 -r <priority>:: 102 --realtime=<priority>:: 86 --realtime=<priority>:: 103 Collect data with this RT SCHED_FIFO p 87 Collect data with this RT SCHED_FIFO priority. 104 88 >> 89 -s <symbol>:: 105 --sym-annotate=<symbol>:: 90 --sym-annotate=<symbol>:: 106 Annotate this symbol. 91 Annotate this symbol. 107 92 108 -K:: 93 -K:: 109 --hide_kernel_symbols:: 94 --hide_kernel_symbols:: 110 Hide kernel symbols. 95 Hide kernel symbols. 111 96 112 -U:: 97 -U:: 113 --hide_user_symbols:: 98 --hide_user_symbols:: 114 Hide user symbols. 99 Hide user symbols. 115 100 116 --demangle-kernel:: << 117 Demangle kernel symbols. << 118 << 119 -D:: 101 -D:: 120 --dump-symtab:: 102 --dump-symtab:: 121 Dump the symbol table used for profili 103 Dump the symbol table used for profiling. 122 104 123 -v:: 105 -v:: 124 --verbose:: 106 --verbose:: 125 Be more verbose (show counter open err 107 Be more verbose (show counter open errors, etc). 126 108 127 -z:: 109 -z:: 128 --zero:: 110 --zero:: 129 Zero history across display updates. 111 Zero history across display updates. 130 112 131 -s:: 113 -s:: 132 --sort:: 114 --sort:: 133 Sort by key(s): pid, comm, dso, symbol !! 115 Sort by key(s): pid, comm, dso, symbol, parent, srcline, weight, local_weight. 134 local_weight, abort, in_tx, transactio << 135 Please see description of --sort in th << 136 << 137 --fields=:: << 138 Specify output field - multiple keys c << 139 Following fields are available: << 140 overhead, overhead_sys, overhead_us, o << 141 Also it can contain any sort key(s). << 142 << 143 By default, every sort keys not specif << 144 automatically. << 145 116 146 -n:: 117 -n:: 147 --show-nr-samples:: 118 --show-nr-samples:: 148 Show a column with the number of sampl 119 Show a column with the number of samples. 149 120 150 --show-total-period:: 121 --show-total-period:: 151 Show a column with the sum of periods. 122 Show a column with the sum of periods. 152 123 153 --dsos:: 124 --dsos:: 154 Only consider symbols in these dsos. !! 125 Only consider symbols in these dsos. 155 percentage of the overhead column. Se << 156 126 157 --comms:: 127 --comms:: 158 Only consider symbols in these comms. !! 128 Only consider symbols in these comms. 159 percentage of the overhead column. Se << 160 129 161 --symbols:: 130 --symbols:: 162 Only consider these symbols. This opt !! 131 Only consider these symbols. 163 percentage of the overhead column. Se << 164 132 165 -M:: 133 -M:: 166 --disassembler-style=:: Set disassembler style 134 --disassembler-style=:: Set disassembler style for objdump. 167 135 168 --addr2line=<path>:: << 169 Path to addr2line binary. << 170 << 171 --objdump=<path>:: << 172 Path to objdump binary. << 173 << 174 --prefix=PREFIX:: << 175 --prefix-strip=N:: << 176 Remove first N entries from source fil << 177 and add PREFIX. This allows to display << 178 with different file system layout. << 179 << 180 --source:: 136 --source:: 181 Interleave source code with assembly c 137 Interleave source code with assembly code. Enabled by default, 182 disable with --no-source. 138 disable with --no-source. 183 139 184 --asm-raw:: 140 --asm-raw:: 185 Show raw instruction encoding of assem 141 Show raw instruction encoding of assembly instructions. 186 142 187 -g:: !! 143 -G [type,min,order]:: 188 Enables call-graph (stack chain/backtr !! 144 --call-graph:: >> 145 Display call chains using type, min percent threshold and order. >> 146 type can be either: >> 147 - flat: single column, linear exposure of call chains. >> 148 - graph: use a graph tree, displaying absolute overhead rates. >> 149 - fractal: like graph, but displays relative rates. Each branch of >> 150 the tree is considered as a new profiled object. >> 151 >> 152 order can be either: >> 153 - callee: callee based call graph. >> 154 - caller: inverted caller based call graph. 189 155 190 --call-graph [mode,type,min[,limit],order[,key !! 156 Default: fractal,0.5,callee. 191 Setup and enable call-graph (stack cha << 192 implies -g. See `--call-graph` sectio << 193 perf-report man pages for details. << 194 << 195 --children:: << 196 Accumulate callchain of children to pa << 197 show up in the output. The output wil << 198 and will be sorted on the data. It re << 199 enabled. See the `overhead calculatio << 200 Enabled by default, disable with --no- << 201 << 202 --max-stack:: << 203 Set the stack depth limit when parsing << 204 beyond the specified depth will be ign << 205 between information loss and faster pr << 206 workloads that can have a very long ca << 207 << 208 Default: /proc/sys/kernel/perf_event_m << 209 << 210 --ignore-callees=<regex>:: << 211 Ignore callees of the function(s) matc << 212 This has the effect of collecting the << 213 function into one place in the call-gr << 214 << 215 --percent-limit:: << 216 Do not show entries which have an over << 217 (Default: 0). << 218 << 219 --percentage:: << 220 Determine how to display the overhead << 221 Filters can be applied by --comms, --d << 222 Zoom operations on the TUI (thread, ds << 223 << 224 "relative" means it's relative to filt << 225 sum of shown entries will be always 10 << 226 the original value before and after th << 227 << 228 -w:: << 229 --column-widths=<width[,width...]>:: << 230 Force each column width to the provide << 231 readability. 0 means no limit (defaul << 232 << 233 --proc-map-timeout:: << 234 When processing pre-existing threads / << 235 a long time, because the file may be h << 236 in such cases. << 237 This option sets the time out limit. T << 238 << 239 << 240 -b:: << 241 --branch-any:: << 242 Enable taken branch stack sampling. An << 243 This is a shortcut for --branch-filter << 244 << 245 -j:: << 246 --branch-filter:: << 247 Enable taken branch stack sampling. Ea << 248 taken branches. The number of branches << 249 underlying hardware, the type of branc << 250 It is possible to select the types of << 251 For a full list of modifiers please se << 252 << 253 The option requires at least one branc << 254 The privilege levels may be omitted, i << 255 event are applied to the branch filter << 256 levels are subject to permissions. Wh << 257 is enabled for all the sampling events << 258 The various filters must be specified << 259 Note that this feature may not be avai << 260 << 261 --branch-history:: << 262 Add the addresses of sampled taken bra << 263 This allows to examine the path the pr << 264 << 265 --raw-trace:: << 266 When displaying traceevent output, do << 267 << 268 -H:: << 269 --hierarchy:: << 270 Enable hierarchical output. In the hi << 271 samples based on the criteria and then << 272 level sort key. << 273 << 274 For example, in normal output: << 275 << 276 perf report -s dso,sym << 277 # << 278 # Overhead Shared Object Symbo << 279 # ........ ................. ..... << 280 50.00% [kernel.kallsyms] [k] k << 281 20.00% perf [.] f << 282 15.00% [kernel.kallsyms] [k] k << 283 10.00% perf [.] b << 284 5.00% libc.so [.] l << 285 << 286 In hierarchy output: << 287 << 288 perf report -s dso,sym --hierarchy << 289 # << 290 # Overhead Shared Object / Symbol << 291 # .......... ...................... << 292 65.00% [kernel.kallsyms] << 293 50.00% [k] kfunc1 << 294 15.00% [k] kfunc2 << 295 30.00% perf << 296 20.00% [.] foo << 297 10.00% [.] bar << 298 5.00% libc.so << 299 5.00% [.] libcall << 300 << 301 --overwrite:: << 302 Enable this to use just the most recen << 303 machines such as Knights Landing/Mill, << 304 the pausing used in this technique is << 305 as PERF_RECORD_MMAP which makes 'perf << 306 to lots of unknown samples appearing o << 307 machines and profiling a workload that << 308 doesn't uses many executable mmap oper << 309 this situation, till then, this will r << 310 << 311 --force:: << 312 Don't do ownership validation. << 313 << 314 --num-thread-synthesize:: << 315 The number of threads to run when synt << 316 By default, the number of threads equa << 317 << 318 --namespaces:: << 319 Record events of type PERF_RECORD_NAME << 320 'cgroup_id' sort key. << 321 << 322 -G name:: << 323 --cgroup name:: << 324 monitor only in the container (cgroup) called << 325 in per-cpu mode. The cgroup filesystem must be << 326 container "name" are monitored when they run o << 327 can be provided. Each cgroup is applied to the << 328 to first event, second cgroup to second event << 329 an empty cgroup (monitor all the time) using, << 330 corresponding events, i.e., they always refer << 331 line. If the user wants to track multiple even << 332 use '-e e1 -e e2 -G foo,foo' or just use '-e e << 333 << 334 --all-cgroups:: << 335 Record events of type PERF_RECORD_CGRO << 336 'cgroup' sort key. << 337 << 338 --switch-on EVENT_NAME:: << 339 Only consider events after this event << 340 << 341 E.g.: << 342 << 343 Find out where broadcast packets ar << 344 << 345 perf probe -L icmp_rcv << 346 << 347 Insert a probe there: << 348 << 349 perf probe icmp_rcv:59 << 350 << 351 Start perf top and ask it to only c << 352 broadcast packet arrives This will << 353 will start counting when a broadcas << 354 << 355 perf top -e cycles,probe:icmp_ << 356 << 357 Alternatively one can ask for a gro << 358 will appear, the first for cycles a << 359 << 360 perf top -e '{cycles,probe:icm << 361 << 362 This may be interesting to measure a w << 363 phase is over, i.e. insert a perf prob << 364 examples replacing probe:icmp_rcv with << 365 << 366 --switch-off EVENT_NAME:: << 367 Stop considering events after this eve << 368 << 369 --show-on-off-events:: << 370 Show the --switch-on/off events too. T << 371 but probably we'll make the default no << 372 on the --group mode and if there is on << 373 go straight to the histogram browser, << 374 explicitly specified does. << 375 << 376 --stitch-lbr:: << 377 Show callgraph with stitched LBRs, whi << 378 callgraph. The option must be used wit << 379 Disabled by default. In common cases w << 380 it can recreate better call stacks tha << 381 output. But this approach is not foolp << 382 where it creates incorrect call stacks << 383 The known limitations include exceptio << 384 setjmp/longjmp will have calls/returns << 385 << 386 ifdef::HAVE_LIBPFM[] << 387 --pfm-events events:: << 388 Select a PMU event using libpfm4 syntax (see h << 389 including support for event filters. For examp << 390 inst_retired:any_p:u:c=1:i'. More than one eve << 391 option using the comma separator. Hardware eve << 392 events cannot be mixed together. The latter mu << 393 option. The -e option and this one can be mixe << 394 can be grouped using the {} notation. << 395 endif::HAVE_LIBPFM[] << 396 157 397 INTERACTIVE PROMPTING KEYS 158 INTERACTIVE PROMPTING KEYS 398 -------------------------- 159 -------------------------- 399 160 400 [d]:: 161 [d]:: 401 Display refresh delay. 162 Display refresh delay. 402 163 403 [e]:: 164 [e]:: 404 Number of entries to display. 165 Number of entries to display. 405 166 406 [E]:: 167 [E]:: 407 Event to display when multiple counter 168 Event to display when multiple counters are active. 408 169 409 [f]:: 170 [f]:: 410 Profile display filter (>= hit count). 171 Profile display filter (>= hit count). 411 172 412 [F]:: 173 [F]:: 413 Annotation display filter (>= % of tot 174 Annotation display filter (>= % of total). 414 175 415 [s]:: 176 [s]:: 416 Annotate symbol. 177 Annotate symbol. 417 178 418 [S]:: 179 [S]:: 419 Stop annotation, return to full profil 180 Stop annotation, return to full profile display. 420 181 421 [K]:: << 422 Hide kernel symbols. << 423 << 424 [U]:: << 425 Hide user symbols. << 426 << 427 [z]:: 182 [z]:: 428 Toggle event count zeroing across disp 183 Toggle event count zeroing across display updates. 429 184 430 [qQ]:: 185 [qQ]:: 431 Quit. 186 Quit. 432 187 433 Pressing any unmapped key displays a menu, and 188 Pressing any unmapped key displays a menu, and prompts for input. 434 189 435 include::callchain-overhead-calculation.txt[] << 436 190 437 SEE ALSO 191 SEE ALSO 438 -------- 192 -------- 439 linkperf:perf-stat[1], linkperf:perf-list[1], !! 193 linkperf:perf-stat[1], linkperf:perf-list[1]

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

TOMOYO Linux Cross Reference
Linux/tools/perf/Documentation/perf-top.txt

Diff markup

Differences between /tools/perf/Documentation/perf-top.txt (Version linux-6.12-rc7) and /tools/perf/Documentation/perf-top.txt (Version linux-3.10.108)

TOMOYO Linux Cross Reference Linux/tools/perf/Documentation/perf-top.txt

Diff markup

Differences between /tools/perf/Documentation/perf-top.txt (Version linux-6.12-rc7) and /tools/perf/Documentation/perf-top.txt (Version linux-3.10.108)

TOMOYO Linux Cross Reference
Linux/tools/perf/Documentation/perf-top.txt