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