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 realtime. 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>:: 29 --cpu=<cpu>:: !! 29 --CPU=<cpu>:: 30 Monitor only on the list of CPUs provided. Mul !! 30 CPU to profile. 31 comma-separated list with no space: 0,1. Range << 32 Default is to monitor all CPUS. << 33 31 34 -d <seconds>:: 32 -d <seconds>:: 35 --delay=<seconds>:: 33 --delay=<seconds>:: 36 Number of seconds to delay between ref 34 Number of seconds to delay between refreshes. 37 35 38 -e <event>:: 36 -e <event>:: 39 --event=<event>:: 37 --event=<event>:: 40 Select the PMU event. Selection can be 38 Select the PMU event. Selection can be a symbolic event name 41 (use 'perf list' to list all events) o !! 39 (use 'perf list' to list all events) or a raw PMU 42 of rN where N is a hexadecimal value t !! 40 event (eventsel+umask) in the form of rNNN where NNN is a 43 encoding with the layout of the event !! 41 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 42 50 -E <entries>:: 43 -E <entries>:: 51 --entries=<entries>:: 44 --entries=<entries>:: 52 Display this many functions. 45 Display this many functions. 53 46 54 -f <count>:: 47 -f <count>:: 55 --count-filter=<count>:: 48 --count-filter=<count>:: 56 Only display functions with more event 49 Only display functions with more events than this. 57 50 58 --group-sort-idx:: << 59 Sort the output by the event at the in << 60 sort by the first event. It can suppor << 61 amount of events. WARNING: This should << 62 << 63 -F <freq>:: 51 -F <freq>:: 64 --freq=<freq>:: 52 --freq=<freq>:: 65 Profile at this frequency. Use 'max' t !! 53 Profile at this frequency. 66 allowed frequency, i.e. the value in t << 67 sysctl. << 68 54 69 -i:: 55 -i:: 70 --inherit:: 56 --inherit:: 71 Child tasks do not inherit counters. !! 57 Child tasks inherit counters, only makes sens with -p option. 72 58 73 -k <path>:: 59 -k <path>:: 74 --vmlinux=<path>:: 60 --vmlinux=<path>:: 75 Path to vmlinux. Required for annotat 61 Path to vmlinux. Required for annotation functionality. 76 62 77 --ignore-vmlinux:: << 78 Ignore vmlinux files. << 79 << 80 --kallsyms=<file>:: << 81 kallsyms pathname << 82 << 83 -m <pages>:: 63 -m <pages>:: 84 --mmap-pages=<pages>:: 64 --mmap-pages=<pages>:: 85 Number of mmap data pages (must be a p !! 65 Number of mmapped data pages. 86 specification in bytes with appended u << 87 The size is rounded up to the nearest << 88 66 89 -p <pid>:: 67 -p <pid>:: 90 --pid=<pid>:: 68 --pid=<pid>:: 91 Profile events on existing Process ID !! 69 Profile events on existing pid. 92 << 93 -t <tid>:: << 94 --tid=<tid>:: << 95 Profile events on existing thread ID ( << 96 << 97 -u:: << 98 --uid=:: << 99 Record events in threads owned by uid. << 100 70 101 -r <priority>:: 71 -r <priority>:: 102 --realtime=<priority>:: 72 --realtime=<priority>:: 103 Collect data with this RT SCHED_FIFO p 73 Collect data with this RT SCHED_FIFO priority. 104 74 >> 75 -s <symbol>:: 105 --sym-annotate=<symbol>:: 76 --sym-annotate=<symbol>:: 106 Annotate this symbol. !! 77 Annotate this symbol. Requires -k option. 107 << 108 -K:: << 109 --hide_kernel_symbols:: << 110 Hide kernel symbols. << 111 << 112 -U:: << 113 --hide_user_symbols:: << 114 Hide user symbols. << 115 << 116 --demangle-kernel:: << 117 Demangle kernel symbols. << 118 << 119 -D:: << 120 --dump-symtab:: << 121 Dump the symbol table used for profili << 122 78 123 -v:: 79 -v:: 124 --verbose:: 80 --verbose:: 125 Be more verbose (show counter open err 81 Be more verbose (show counter open errors, etc). 126 82 127 -z:: 83 -z:: 128 --zero:: 84 --zero:: 129 Zero history across display updates. 85 Zero history across display updates. 130 86 131 -s:: << 132 --sort:: << 133 Sort by key(s): pid, comm, dso, symbol << 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 << 146 -n:: << 147 --show-nr-samples:: << 148 Show a column with the number of sampl << 149 << 150 --show-total-period:: << 151 Show a column with the sum of periods. << 152 << 153 --dsos:: << 154 Only consider symbols in these dsos. << 155 percentage of the overhead column. Se << 156 << 157 --comms:: << 158 Only consider symbols in these comms. << 159 percentage of the overhead column. Se << 160 << 161 --symbols:: << 162 Only consider these symbols. This opt << 163 percentage of the overhead column. Se << 164 << 165 -M:: << 166 --disassembler-style=:: Set disassembler style << 167 << 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:: << 181 Interleave source code with assembly c << 182 disable with --no-source. << 183 << 184 --asm-raw:: << 185 Show raw instruction encoding of assem << 186 << 187 -g:: << 188 Enables call-graph (stack chain/backtr << 189 << 190 --call-graph [mode,type,min[,limit],order[,key << 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 << 397 INTERACTIVE PROMPTING KEYS 87 INTERACTIVE PROMPTING KEYS 398 -------------------------- 88 -------------------------- 399 89 400 [d]:: 90 [d]:: 401 Display refresh delay. 91 Display refresh delay. 402 92 403 [e]:: 93 [e]:: 404 Number of entries to display. 94 Number of entries to display. 405 95 406 [E]:: 96 [E]:: 407 Event to display when multiple counter 97 Event to display when multiple counters are active. 408 98 409 [f]:: 99 [f]:: 410 Profile display filter (>= hit count). 100 Profile display filter (>= hit count). 411 101 412 [F]:: 102 [F]:: 413 Annotation display filter (>= % of tot 103 Annotation display filter (>= % of total). 414 104 415 [s]:: 105 [s]:: 416 Annotate symbol. 106 Annotate symbol. 417 107 418 [S]:: 108 [S]:: 419 Stop annotation, return to full profil 109 Stop annotation, return to full profile display. 420 110 421 [K]:: !! 111 [w]:: 422 Hide kernel symbols. !! 112 Toggle between weighted sum and individual count[E]r profile. 423 << 424 [U]:: << 425 Hide user symbols. << 426 113 427 [z]:: 114 [z]:: 428 Toggle event count zeroing across disp 115 Toggle event count zeroing across display updates. 429 116 430 [qQ]:: 117 [qQ]:: 431 Quit. 118 Quit. 432 119 433 Pressing any unmapped key displays a menu, and 120 Pressing any unmapped key displays a menu, and prompts for input. 434 121 435 include::callchain-overhead-calculation.txt[] << 436 122 437 SEE ALSO 123 SEE ALSO 438 -------- 124 -------- 439 linkperf:perf-stat[1], linkperf:perf-list[1], !! 125 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-2.6.32.71)

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-2.6.32.71)

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