1perf-report(1) 2============== 3 4NAME 5---- 6perf-report - Read perf.data (created by perf record) and display the profile 7 8SYNOPSIS 9-------- 10[verse] 11'perf report' [-i <file> | --input=file] 12 13DESCRIPTION 14----------- 15This command displays the performance counter profile information recorded 16via perf record. 17 18OPTIONS 19------- 20-i:: 21--input=:: 22 Input file name. (default: perf.data unless stdin is a fifo) 23 24-v:: 25--verbose:: 26 Be more verbose. (show symbol address, etc) 27 28-q:: 29--quiet:: 30 Do not show any warnings or messages. (Suppress -v) 31 32-n:: 33--show-nr-samples:: 34 Show the number of samples for each symbol 35 36--show-cpu-utilization:: 37 Show sample percentage for different cpu modes. 38 39-T:: 40--threads:: 41 Show per-thread event counters. The input data file should be recorded 42 with -s option. 43-c:: 44--comms=:: 45 Only consider symbols in these comms. CSV that understands 46 file://filename entries. This option will affect the percentage of 47 the overhead column. See --percentage for more info. 48--pid=:: 49 Only show events for given process ID (comma separated list). 50 51--tid=:: 52 Only show events for given thread ID (comma separated list). 53-d:: 54--dsos=:: 55 Only consider symbols in these dsos. CSV that understands 56 file://filename entries. This option will affect the percentage of 57 the overhead column. See --percentage for more info. 58-S:: 59--symbols=:: 60 Only consider these symbols. CSV that understands 61 file://filename entries. This option will affect the percentage of 62 the overhead column. See --percentage for more info. 63 64--symbol-filter=:: 65 Only show symbols that match (partially) with this filter. 66 67-U:: 68--hide-unresolved:: 69 Only display entries resolved to a symbol. 70 71-s:: 72--sort=:: 73 Sort histogram entries by given key(s) - multiple keys can be specified 74 in CSV format. Following sort keys are available: 75 pid, comm, dso, symbol, parent, cpu, socket, srcline, weight, 76 local_weight, cgroup_id, addr. 77 78 Each key has following meaning: 79 80 - comm: command (name) of the task which can be read via /proc/<pid>/comm 81 - pid: command and tid of the task 82 - dso: name of library or module executed at the time of sample 83 - dso_size: size of library or module executed at the time of sample 84 - symbol: name of function executed at the time of sample 85 - symbol_size: size of function executed at the time of sample 86 - parent: name of function matched to the parent regex filter. Unmatched 87 entries are displayed as "[other]". 88 - cpu: cpu number the task ran at the time of sample 89 - socket: processor socket number the task ran at the time of sample 90 - srcline: filename and line number executed at the time of sample. The 91 DWARF debugging info must be provided. 92 - srcfile: file name of the source file of the samples. Requires dwarf 93 information. 94 - weight: Event specific weight, e.g. memory latency or transaction 95 abort cost. This is the global weight. 96 - local_weight: Local weight version of the weight above. 97 - cgroup_id: ID derived from cgroup namespace device and inode numbers. 98 - cgroup: cgroup pathname in the cgroupfs. 99 - transaction: Transaction abort flags. 100 - overhead: Overhead percentage of sample 101 - overhead_sys: Overhead percentage of sample running in system mode 102 - overhead_us: Overhead percentage of sample running in user mode 103 - overhead_guest_sys: Overhead percentage of sample running in system mode 104 on guest machine 105 - overhead_guest_us: Overhead percentage of sample running in user mode on 106 guest machine 107 - sample: Number of sample 108 - period: Raw number of event count of sample 109 - time: Separate the samples by time stamp with the resolution specified by 110 --time-quantum (default 100ms). Specify with overhead and before it. 111 - code_page_size: the code page size of sampled code address (ip) 112 - ins_lat: Instruction latency in core cycles. This is the global instruction 113 latency 114 - local_ins_lat: Local instruction latency version 115 - p_stage_cyc: On powerpc, this presents the number of cycles spent in a 116 pipeline stage. And currently supported only on powerpc. 117 - addr: (Full) virtual address of the sampled instruction 118 - retire_lat: On X86, this reports pipeline stall of this instruction compared 119 to the previous instruction in cycles. And currently supported only on X86 120 - simd: Flags describing a SIMD operation. "e" for empty Arm SVE predicate. "p" for partial Arm SVE predicate 121 - type: Data type of sample memory access. 122 - typeoff: Offset in the data type of sample memory access. 123 - symoff: Offset in the symbol. 124 125 By default, comm, dso and symbol keys are used. 126 (i.e. --sort comm,dso,symbol) 127 128 If --branch-stack option is used, following sort keys are also 129 available: 130 131 - dso_from: name of library or module branched from 132 - dso_to: name of library or module branched to 133 - symbol_from: name of function branched from 134 - symbol_to: name of function branched to 135 - srcline_from: source file and line branched from 136 - srcline_to: source file and line branched to 137 - mispredict: "N" for predicted branch, "Y" for mispredicted branch 138 - in_tx: branch in TSX transaction 139 - abort: TSX transaction abort. 140 - cycles: Cycles in basic block 141 142 And default sort keys are changed to comm, dso_from, symbol_from, dso_to 143 and symbol_to, see '--branch-stack'. 144 145 When the sort key symbol is specified, columns "IPC" and "IPC Coverage" 146 are enabled automatically. Column "IPC" reports the average IPC per function 147 and column "IPC coverage" reports the percentage of instructions with 148 sampled IPC in this function. IPC means Instruction Per Cycle. If it's low, 149 it indicates there may be a performance bottleneck when the function is 150 executed, such as a memory access bottleneck. If a function has high overhead 151 and low IPC, it's worth further analyzing it to optimize its performance. 152 153 If the --mem-mode option is used, the following sort keys are also available 154 (incompatible with --branch-stack): 155 symbol_daddr, dso_daddr, locked, tlb, mem, snoop, dcacheline, blocked. 156 157 - symbol_daddr: name of data symbol being executed on at the time of sample 158 - dso_daddr: name of library or module containing the data being executed 159 on at the time of the sample 160 - locked: whether the bus was locked at the time of the sample 161 - tlb: type of tlb access for the data at the time of the sample 162 - mem: type of memory access for the data at the time of the sample 163 - snoop: type of snoop (if any) for the data at the time of the sample 164 - dcacheline: the cacheline the data address is on at the time of the sample 165 - phys_daddr: physical address of data being executed on at the time of sample 166 - data_page_size: the data page size of data being executed on at the time of sample 167 - blocked: reason of blocked load access for the data at the time of the sample 168 169 And the default sort keys are changed to local_weight, mem, sym, dso, 170 symbol_daddr, dso_daddr, snoop, tlb, locked, blocked, local_ins_lat, 171 see '--mem-mode'. 172 173 If the data file has tracepoint event(s), following (dynamic) sort keys 174 are also available: 175 trace, trace_fields, [<event>.]<field>[/raw] 176 177 - trace: pretty printed trace output in a single column 178 - trace_fields: fields in tracepoints in separate columns 179 - <field name>: optional event and field name for a specific field 180 181 The last form consists of event and field names. If event name is 182 omitted, it searches all events for matching field name. The matched 183 field will be shown only for the event has the field. The event name 184 supports substring match so user doesn't need to specify full subsystem 185 and event name everytime. For example, 'sched:sched_switch' event can 186 be shortened to 'switch' as long as it's not ambiguous. Also event can 187 be specified by its index (starting from 1) preceded by the '%'. 188 So '%1' is the first event, '%2' is the second, and so on. 189 190 The field name can have '/raw' suffix which disables pretty printing 191 and shows raw field value like hex numbers. The --raw-trace option 192 has the same effect for all dynamic sort keys. 193 194 The default sort keys are changed to 'trace' if all events in the data 195 file are tracepoint. 196 197-F:: 198--fields=:: 199 Specify output field - multiple keys can be specified in CSV format. 200 Following fields are available: 201 overhead, overhead_sys, overhead_us, overhead_children, sample and period. 202 Also it can contain any sort key(s). 203 204 By default, every sort keys not specified in -F will be appended 205 automatically. 206 207 If the keys starts with a prefix '+', then it will append the specified 208 field(s) to the default field order. For example: perf report -F +period,sample. 209 210-p:: 211--parent=<regex>:: 212 A regex filter to identify parent. The parent is a caller of this 213 function and searched through the callchain, thus it requires callchain 214 information recorded. The pattern is in the extended regex format and 215 defaults to "\^sys_|^do_page_fault", see '--sort parent'. 216 217-x:: 218--exclude-other:: 219 Only display entries with parent-match. 220 221-w:: 222--column-widths=<width[,width...]>:: 223 Force each column width to the provided list, for large terminal 224 readability. 0 means no limit (default behavior). 225 226-t:: 227--field-separator=:: 228 Use a special separator character and don't pad with spaces, replacing 229 all occurrences of this separator in symbol names (and other output) 230 with a '.' character, that thus it's the only non valid separator. 231 232-D:: 233--dump-raw-trace:: 234 Dump raw trace in ASCII. 235 236--disable-order:: 237 Disable raw trace ordering. 238 239-g:: 240--call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>:: 241 Display call chains using type, min percent threshold, print limit, 242 call order, sort key, optional branch and value. Note that ordering 243 is not fixed so any parameter can be given in an arbitrary order. 244 One exception is the print_limit which should be preceded by threshold. 245 246 print_type can be either: 247 - flat: single column, linear exposure of call chains. 248 - graph: use a graph tree, displaying absolute overhead rates. (default) 249 - fractal: like graph, but displays relative rates. Each branch of 250 the tree is considered as a new profiled object. 251 - folded: call chains are displayed in a line, separated by semicolons 252 - none: disable call chain display. 253 254 threshold is a percentage value which specifies a minimum percent to be 255 included in the output call graph. Default is 0.5 (%). 256 257 print_limit is only applied when stdio interface is used. It's to limit 258 number of call graph entries in a single hist entry. Note that it needs 259 to be given after threshold (but not necessarily consecutive). 260 Default is 0 (unlimited). 261 262 order can be either: 263 - callee: callee based call graph. 264 - caller: inverted caller based call graph. 265 Default is 'caller' when --children is used, otherwise 'callee'. 266 267 sort_key can be: 268 - function: compare on functions (default) 269 - address: compare on individual code addresses 270 - srcline: compare on source filename and line number 271 272 branch can be: 273 - branch: include last branch information in callgraph when available. 274 Usually more convenient to use --branch-history for this. 275 276 value can be: 277 - percent: display overhead percent (default) 278 - period: display event period 279 - count: display event count 280 281--children:: 282 Accumulate callchain of children to parent entry so that then can 283 show up in the output. The output will have a new "Children" column 284 and will be sorted on the data. It requires callchains are recorded. 285 See the `overhead calculation' section for more details. Enabled by 286 default, disable with --no-children. 287 288--max-stack:: 289 Set the stack depth limit when parsing the callchain, anything 290 beyond the specified depth will be ignored. This is a trade-off 291 between information loss and faster processing especially for 292 workloads that can have a very long callchain stack. 293 Note that when using the --itrace option the synthesized callchain size 294 will override this value if the synthesized callchain size is bigger. 295 296 Default: 127 297 298-G:: 299--inverted:: 300 alias for inverted caller based call graph. 301 302--ignore-callees=<regex>:: 303 Ignore callees of the function(s) matching the given regex. 304 This has the effect of collecting the callers of each such 305 function into one place in the call-graph tree. 306 307--pretty=<key>:: 308 Pretty printing style. key: normal, raw 309 310--stdio:: Use the stdio interface. 311 312--stdio-color:: 313 'always', 'never' or 'auto', allowing configuring color output 314 via the command line, in addition to via "color.ui" .perfconfig. 315 Use '--stdio-color always' to generate color even when redirecting 316 to a pipe or file. Using just '--stdio-color' is equivalent to 317 using 'always'. 318 319--tui:: Use the TUI interface, that is integrated with annotate and allows 320 zooming into DSOs or threads, among other features. Use of --tui 321 requires a tty, if one is not present, as when piping to other 322 commands, the stdio interface is used. 323 324--gtk:: Use the GTK2 interface. 325 326-k:: 327--vmlinux=<file>:: 328 vmlinux pathname 329 330--ignore-vmlinux:: 331 Ignore vmlinux files. 332 333--kallsyms=<file>:: 334 kallsyms pathname 335 336-m:: 337--modules:: 338 Load module symbols. WARNING: This should only be used with -k and 339 a LIVE kernel. 340 341-f:: 342--force:: 343 Don't do ownership validation. 344 345--symfs=<directory>:: 346 Look for files with symbols relative to this directory. 347 348-C:: 349--cpu:: Only report samples for the list of CPUs provided. Multiple CPUs can 350 be provided as a comma-separated list with no space: 0,1. Ranges of 351 CPUs are specified with -: 0-2. Default is to report samples on all 352 CPUs. 353 354-M:: 355--disassembler-style=:: Set disassembler style for objdump. 356 357--source:: 358 Interleave source code with assembly code. Enabled by default, 359 disable with --no-source. 360 361--asm-raw:: 362 Show raw instruction encoding of assembly instructions. 363 364--show-total-period:: Show a column with the sum of periods. 365 366-I:: 367--show-info:: 368 Display extended information about the perf.data file. This adds 369 information which may be very large and thus may clutter the display. 370 It currently includes: cpu and numa topology of the host system. 371 372-b:: 373--branch-stack:: 374 Use the addresses of sampled taken branches instead of the instruction 375 address to build the histograms. To generate meaningful output, the 376 perf.data file must have been obtained using perf record -b or 377 perf record --branch-filter xxx where xxx is a branch filter option. 378 perf report is able to auto-detect whether a perf.data file contains 379 branch stacks and it will automatically switch to the branch view mode, 380 unless --no-branch-stack is used. 381 382--branch-history:: 383 Add the addresses of sampled taken branches to the callstack. 384 This allows to examine the path the program took to each sample. 385 The data collection must have used -b (or -j) and -g. 386 387--addr2line=<path>:: 388 Path to addr2line binary. 389 390--objdump=<path>:: 391 Path to objdump binary. 392 393--prefix=PREFIX:: 394--prefix-strip=N:: 395 Remove first N entries from source file path names in executables 396 and add PREFIX. This allows to display source code compiled on systems 397 with different file system layout. 398 399--group:: 400 Show event group information together. It forces group output also 401 if there are no groups defined in data file. 402 403--group-sort-idx:: 404 Sort the output by the event at the index n in group. If n is invalid, 405 sort by the first event. It can support multiple groups with different 406 amount of events. WARNING: This should be used on grouped events. 407 408--demangle:: 409 Demangle symbol names to human readable form. It's enabled by default, 410 disable with --no-demangle. 411 412--demangle-kernel:: 413 Demangle kernel symbol names to human readable form (for C++ kernels). 414 415--mem-mode:: 416 Use the data addresses of samples in addition to instruction addresses 417 to build the histograms. To generate meaningful output, the perf.data 418 file must have been obtained using perf record -d -W and using a 419 special event -e cpu/mem-loads/p or -e cpu/mem-stores/p. See 420 'perf mem' for simpler access. 421 422--percent-limit:: 423 Do not show entries which have an overhead under that percent. 424 (Default: 0). Note that this option also sets the percent limit (threshold) 425 of callchains. However the default value of callchain threshold is 426 different than the default value of hist entries. Please see the 427 --call-graph option for details. 428 429--percentage:: 430 Determine how to display the overhead percentage of filtered entries. 431 Filters can be applied by --comms, --dsos and/or --symbols options and 432 Zoom operations on the TUI (thread, dso, etc). 433 434 "relative" means it's relative to filtered entries only so that the 435 sum of shown entries will be always 100%. "absolute" means it retains 436 the original value before and after the filter is applied. 437 438--header:: 439 Show header information in the perf.data file. This includes 440 various information like hostname, OS and perf version, cpu/mem 441 info, perf command line, event list and so on. Currently only 442 --stdio output supports this feature. 443 444--header-only:: 445 Show only perf.data header (forces --stdio). 446 447--time:: 448 Only analyze samples within given time window: <start>,<stop>. Times 449 have the format seconds.nanoseconds. If start is not given (i.e. time 450 string is ',x.y') then analysis starts at the beginning of the file. If 451 stop time is not given (i.e. time string is 'x.y,') then analysis goes 452 to end of file. Multiple ranges can be separated by spaces, which 453 requires the argument to be quoted e.g. --time "1234.567,1234.789 1235," 454 455 Also support time percent with multiple time ranges. Time string is 456 'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'. 457 458 For example: 459 Select the second 10% time slice: 460 461 perf report --time 10%/2 462 463 Select from 0% to 10% time slice: 464 465 perf report --time 0%-10% 466 467 Select the first and second 10% time slices: 468 469 perf report --time 10%/1,10%/2 470 471 Select from 0% to 10% and 30% to 40% slices: 472 473 perf report --time 0%-10%,30%-40% 474 475--switch-on EVENT_NAME:: 476 Only consider events after this event is found. 477 478 This may be interesting to measure a workload only after some initialization 479 phase is over, i.e. insert a perf probe at that point and then using this 480 option with that probe. 481 482--switch-off EVENT_NAME:: 483 Stop considering events after this event is found. 484 485--show-on-off-events:: 486 Show the --switch-on/off events too. This has no effect in 'perf report' now 487 but probably we'll make the default not to show the switch-on/off events 488 on the --group mode and if there is only one event besides the off/on ones, 489 go straight to the histogram browser, just like 'perf report' with no events 490 explicitly specified does. 491 492--itrace:: 493 Options for decoding instruction tracing data. The options are: 494 495include::itrace.txt[] 496 497 To disable decoding entirely, use --no-itrace. 498 499--full-source-path:: 500 Show the full path for source files for srcline output. 501 502--show-ref-call-graph:: 503 When multiple events are sampled, it may not be needed to collect 504 callgraphs for all of them. The sample sites are usually nearby, 505 and it's enough to collect the callgraphs on a reference event. 506 So user can use "call-graph=no" event modifier to disable callgraph 507 for other events to reduce the overhead. 508 However, perf report cannot show callgraphs for the event which 509 disable the callgraph. 510 This option extends the perf report to show reference callgraphs, 511 which collected by reference event, in no callgraph event. 512 513--stitch-lbr:: 514 Show callgraph with stitched LBRs, which may have more complete 515 callgraph. The perf.data file must have been obtained using 516 perf record --call-graph lbr. 517 Disabled by default. In common cases with call stack overflows, 518 it can recreate better call stacks than the default lbr call stack 519 output. But this approach is not foolproof. There can be cases 520 where it creates incorrect call stacks from incorrect matches. 521 The known limitations include exception handing such as 522 setjmp/longjmp will have calls/returns not match. 523 524--socket-filter:: 525 Only report the samples on the processor socket that match with this filter 526 527--samples=N:: 528 Save N individual samples for each histogram entry to show context in perf 529 report tui browser. 530 531--raw-trace:: 532 When displaying traceevent output, do not use print fmt or plugins. 533 534-H:: 535--hierarchy:: 536 Enable hierarchical output. In the hierarchy mode, each sort key groups 537 samples based on the criteria and then sub-divide it using the lower 538 level sort key. 539 540 For example: 541 In normal output: 542 543 perf report -s dso,sym 544 # Overhead Shared Object Symbol 545 50.00% [kernel.kallsyms] [k] kfunc1 546 20.00% perf [.] foo 547 15.00% [kernel.kallsyms] [k] kfunc2 548 10.00% perf [.] bar 549 5.00% libc.so [.] libcall 550 551 In hierarchy output: 552 553 perf report -s dso,sym --hierarchy 554 # Overhead Shared Object / Symbol 555 65.00% [kernel.kallsyms] 556 50.00% [k] kfunc1 557 15.00% [k] kfunc2 558 30.00% perf 559 20.00% [.] foo 560 10.00% [.] bar 561 5.00% libc.so 562 5.00% [.] libcall 563 564--inline:: 565 If a callgraph address belongs to an inlined function, the inline stack 566 will be printed. Each entry is function name or file/line. Enabled by 567 default, disable with --no-inline. 568 569--mmaps:: 570 Show --tasks output plus mmap information in a format similar to 571 /proc/<PID>/maps. 572 573 Please note that not all mmaps are stored, options affecting which ones 574 are include 'perf record --data', for instance. 575 576--ns:: 577 Show time stamps in nanoseconds. 578 579--stats:: 580 Display overall events statistics without any further processing. 581 (like the one at the end of the perf report -D command) 582 583--tasks:: 584 Display monitored tasks stored in perf data. Displaying pid/tid/ppid 585 plus the command string aligned to distinguish parent and child tasks. 586 587--percent-type:: 588 Set annotation percent type from following choices: 589 global-period, local-period, global-hits, local-hits 590 591 The local/global keywords set if the percentage is computed 592 in the scope of the function (local) or the whole data (global). 593 The period/hits keywords set the base the percentage is computed 594 on - the samples period or the number of samples (hits). 595 596--time-quantum:: 597 Configure time quantum for time sort key. Default 100ms. 598 Accepts s, us, ms, ns units. 599 600--total-cycles:: 601 When --total-cycles is specified, it supports sorting for all blocks by 602 'Sampled Cycles%'. This is useful to concentrate on the globally hottest 603 blocks. In output, there are some new columns: 604 605 'Sampled Cycles%' - block sampled cycles aggregation / total sampled cycles 606 'Sampled Cycles' - block sampled cycles aggregation 607 'Avg Cycles%' - block average sampled cycles / sum of total block average 608 sampled cycles 609 'Avg Cycles' - block average sampled cycles 610 611--skip-empty:: 612 Do not print 0 results in the --stat output. 613 614include::callchain-overhead-calculation.txt[] 615 616SEE ALSO 617-------- 618linkperf:perf-stat[1], linkperf:perf-annotate[1], linkperf:perf-record[1], 619linkperf:perf-intel-pt[1] 620