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-n:: 29--show-nr-samples:: 30 Show the number of samples for each symbol 31 32--show-cpu-utilization:: 33 Show sample percentage for different cpu modes. 34 35-T:: 36--threads:: 37 Show per-thread event counters. The input data file should be recorded 38 with -s option. 39-c:: 40--comms=:: 41 Only consider symbols in these comms. CSV that understands 42 file://filename entries. This option will affect the percentage of 43 the overhead column. See --percentage for more info. 44--pid=:: 45 Only show events for given process ID (comma separated list). 46 47--tid=:: 48 Only show events for given thread ID (comma separated list). 49-d:: 50--dsos=:: 51 Only consider symbols in these dsos. CSV that understands 52 file://filename entries. This option will affect the percentage of 53 the overhead column. See --percentage for more info. 54-S:: 55--symbols=:: 56 Only consider these symbols. CSV that understands 57 file://filename entries. This option will affect the percentage of 58 the overhead column. See --percentage for more info. 59 60--symbol-filter=:: 61 Only show symbols that match (partially) with this filter. 62 63-U:: 64--hide-unresolved:: 65 Only display entries resolved to a symbol. 66 67-s:: 68--sort=:: 69 Sort histogram entries by given key(s) - multiple keys can be specified 70 in CSV format. Following sort keys are available: 71 pid, comm, dso, symbol, parent, cpu, socket, srcline, weight, local_weight. 72 73 Each key has following meaning: 74 75 - comm: command (name) of the task which can be read via /proc/<pid>/comm 76 - pid: command and tid of the task 77 - dso: name of library or module executed at the time of sample 78 - symbol: name of function executed at the time of sample 79 - parent: name of function matched to the parent regex filter. Unmatched 80 entries are displayed as "[other]". 81 - cpu: cpu number the task ran at the time of sample 82 - socket: processor socket number the task ran at the time of sample 83 - srcline: filename and line number executed at the time of sample. The 84 DWARF debugging info must be provided. 85 - srcfile: file name of the source file of the same. Requires dwarf 86 information. 87 - weight: Event specific weight, e.g. memory latency or transaction 88 abort cost. This is the global weight. 89 - local_weight: Local weight version of the weight above. 90 - transaction: Transaction abort flags. 91 - overhead: Overhead percentage of sample 92 - overhead_sys: Overhead percentage of sample running in system mode 93 - overhead_us: Overhead percentage of sample running in user mode 94 - overhead_guest_sys: Overhead percentage of sample running in system mode 95 on guest machine 96 - overhead_guest_us: Overhead percentage of sample running in user mode on 97 guest machine 98 - sample: Number of sample 99 - period: Raw number of event count of sample 100 101 By default, comm, dso and symbol keys are used. 102 (i.e. --sort comm,dso,symbol) 103 104 If --branch-stack option is used, following sort keys are also 105 available: 106 dso_from, dso_to, symbol_from, symbol_to, mispredict. 107 108 - dso_from: name of library or module branched from 109 - dso_to: name of library or module branched to 110 - symbol_from: name of function branched from 111 - symbol_to: name of function branched to 112 - mispredict: "N" for predicted branch, "Y" for mispredicted branch 113 - in_tx: branch in TSX transaction 114 - abort: TSX transaction abort. 115 - cycles: Cycles in basic block 116 117 And default sort keys are changed to comm, dso_from, symbol_from, dso_to 118 and symbol_to, see '--branch-stack'. 119 120 If the --mem-mode option is used, the following sort keys are also available 121 (incompatible with --branch-stack): 122 symbol_daddr, dso_daddr, locked, tlb, mem, snoop, dcacheline. 123 124 - symbol_daddr: name of data symbol being executed on at the time of sample 125 - dso_daddr: name of library or module containing the data being executed 126 on at the time of the sample 127 - locked: whether the bus was locked at the time of the sample 128 - tlb: type of tlb access for the data at the time of the sample 129 - mem: type of memory access for the data at the time of the sample 130 - snoop: type of snoop (if any) for the data at the time of the sample 131 - dcacheline: the cacheline the data address is on at the time of the sample 132 133 And the default sort keys are changed to local_weight, mem, sym, dso, 134 symbol_daddr, dso_daddr, snoop, tlb, locked, see '--mem-mode'. 135 136 If the data file has tracepoint event(s), following (dynamic) sort keys 137 are also available: 138 trace, trace_fields, [<event>.]<field>[/raw] 139 140 - trace: pretty printed trace output in a single column 141 - trace_fields: fields in tracepoints in separate columns 142 - <field name>: optional event and field name for a specific field 143 144 The last form consists of event and field names. If event name is 145 omitted, it searches all events for matching field name. The matched 146 field will be shown only for the event has the field. The event name 147 supports substring match so user doesn't need to specify full subsystem 148 and event name everytime. For example, 'sched:sched_switch' event can 149 be shortened to 'switch' as long as it's not ambiguous. Also event can 150 be specified by its index (starting from 1) preceded by the '%'. 151 So '%1' is the first event, '%2' is the second, and so on. 152 153 The field name can have '/raw' suffix which disables pretty printing 154 and shows raw field value like hex numbers. The --raw-trace option 155 has the same effect for all dynamic sort keys. 156 157 The default sort keys are changed to 'trace' if all events in the data 158 file are tracepoint. 159 160-F:: 161--fields=:: 162 Specify output field - multiple keys can be specified in CSV format. 163 Following fields are available: 164 overhead, overhead_sys, overhead_us, overhead_children, sample and period. 165 Also it can contain any sort key(s). 166 167 By default, every sort keys not specified in -F will be appended 168 automatically. 169 170-p:: 171--parent=<regex>:: 172 A regex filter to identify parent. The parent is a caller of this 173 function and searched through the callchain, thus it requires callchain 174 information recorded. The pattern is in the exteneded regex format and 175 defaults to "\^sys_|^do_page_fault", see '--sort parent'. 176 177-x:: 178--exclude-other:: 179 Only display entries with parent-match. 180 181-w:: 182--column-widths=<width[,width...]>:: 183 Force each column width to the provided list, for large terminal 184 readability. 0 means no limit (default behavior). 185 186-t:: 187--field-separator=:: 188 Use a special separator character and don't pad with spaces, replacing 189 all occurrences of this separator in symbol names (and other output) 190 with a '.' character, that thus it's the only non valid separator. 191 192-D:: 193--dump-raw-trace:: 194 Dump raw trace in ASCII. 195 196-g:: 197--call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>:: 198 Display call chains using type, min percent threshold, print limit, 199 call order, sort key, optional branch and value. Note that ordering of 200 parameters is not fixed so any parement can be given in an arbitraty order. 201 One exception is the print_limit which should be preceded by threshold. 202 203 print_type can be either: 204 - flat: single column, linear exposure of call chains. 205 - graph: use a graph tree, displaying absolute overhead rates. (default) 206 - fractal: like graph, but displays relative rates. Each branch of 207 the tree is considered as a new profiled object. 208 - folded: call chains are displayed in a line, separated by semicolons 209 - none: disable call chain display. 210 211 threshold is a percentage value which specifies a minimum percent to be 212 included in the output call graph. Default is 0.5 (%). 213 214 print_limit is only applied when stdio interface is used. It's to limit 215 number of call graph entries in a single hist entry. Note that it needs 216 to be given after threshold (but not necessarily consecutive). 217 Default is 0 (unlimited). 218 219 order can be either: 220 - callee: callee based call graph. 221 - caller: inverted caller based call graph. 222 Default is 'caller' when --children is used, otherwise 'callee'. 223 224 sort_key can be: 225 - function: compare on functions (default) 226 - address: compare on individual code addresses 227 228 branch can be: 229 - branch: include last branch information in callgraph when available. 230 Usually more convenient to use --branch-history for this. 231 232 value can be: 233 - percent: diplay overhead percent (default) 234 - period: display event period 235 - count: display event count 236 237--children:: 238 Accumulate callchain of children to parent entry so that then can 239 show up in the output. The output will have a new "Children" column 240 and will be sorted on the data. It requires callchains are recorded. 241 See the `overhead calculation' section for more details. 242 243--max-stack:: 244 Set the stack depth limit when parsing the callchain, anything 245 beyond the specified depth will be ignored. This is a trade-off 246 between information loss and faster processing especially for 247 workloads that can have a very long callchain stack. 248 Note that when using the --itrace option the synthesized callchain size 249 will override this value if the synthesized callchain size is bigger. 250 251 Default: /proc/sys/kernel/perf_event_max_stack when present, 127 otherwise. 252 253-G:: 254--inverted:: 255 alias for inverted caller based call graph. 256 257--ignore-callees=<regex>:: 258 Ignore callees of the function(s) matching the given regex. 259 This has the effect of collecting the callers of each such 260 function into one place in the call-graph tree. 261 262--pretty=<key>:: 263 Pretty printing style. key: normal, raw 264 265--stdio:: Use the stdio interface. 266 267--tui:: Use the TUI interface, that is integrated with annotate and allows 268 zooming into DSOs or threads, among other features. Use of --tui 269 requires a tty, if one is not present, as when piping to other 270 commands, the stdio interface is used. 271 272--gtk:: Use the GTK2 interface. 273 274-k:: 275--vmlinux=<file>:: 276 vmlinux pathname 277 278--kallsyms=<file>:: 279 kallsyms pathname 280 281-m:: 282--modules:: 283 Load module symbols. WARNING: This should only be used with -k and 284 a LIVE kernel. 285 286-f:: 287--force:: 288 Don't do ownership validation. 289 290--symfs=<directory>:: 291 Look for files with symbols relative to this directory. 292 293-C:: 294--cpu:: Only report samples for the list of CPUs provided. Multiple CPUs can 295 be provided as a comma-separated list with no space: 0,1. Ranges of 296 CPUs are specified with -: 0-2. Default is to report samples on all 297 CPUs. 298 299-M:: 300--disassembler-style=:: Set disassembler style for objdump. 301 302--source:: 303 Interleave source code with assembly code. Enabled by default, 304 disable with --no-source. 305 306--asm-raw:: 307 Show raw instruction encoding of assembly instructions. 308 309--show-total-period:: Show a column with the sum of periods. 310 311-I:: 312--show-info:: 313 Display extended information about the perf.data file. This adds 314 information which may be very large and thus may clutter the display. 315 It currently includes: cpu and numa topology of the host system. 316 317-b:: 318--branch-stack:: 319 Use the addresses of sampled taken branches instead of the instruction 320 address to build the histograms. To generate meaningful output, the 321 perf.data file must have been obtained using perf record -b or 322 perf record --branch-filter xxx where xxx is a branch filter option. 323 perf report is able to auto-detect whether a perf.data file contains 324 branch stacks and it will automatically switch to the branch view mode, 325 unless --no-branch-stack is used. 326 327--branch-history:: 328 Add the addresses of sampled taken branches to the callstack. 329 This allows to examine the path the program took to each sample. 330 The data collection must have used -b (or -j) and -g. 331 332--objdump=<path>:: 333 Path to objdump binary. 334 335--group:: 336 Show event group information together. 337 338--demangle:: 339 Demangle symbol names to human readable form. It's enabled by default, 340 disable with --no-demangle. 341 342--demangle-kernel:: 343 Demangle kernel symbol names to human readable form (for C++ kernels). 344 345--mem-mode:: 346 Use the data addresses of samples in addition to instruction addresses 347 to build the histograms. To generate meaningful output, the perf.data 348 file must have been obtained using perf record -d -W and using a 349 special event -e cpu/mem-loads/ or -e cpu/mem-stores/. See 350 'perf mem' for simpler access. 351 352--percent-limit:: 353 Do not show entries which have an overhead under that percent. 354 (Default: 0). Note that this option also sets the percent limit (threshold) 355 of callchains. However the default value of callchain threshold is 356 different than the default value of hist entries. Please see the 357 --call-graph option for details. 358 359--percentage:: 360 Determine how to display the overhead percentage of filtered entries. 361 Filters can be applied by --comms, --dsos and/or --symbols options and 362 Zoom operations on the TUI (thread, dso, etc). 363 364 "relative" means it's relative to filtered entries only so that the 365 sum of shown entries will be always 100%. "absolute" means it retains 366 the original value before and after the filter is applied. 367 368--header:: 369 Show header information in the perf.data file. This includes 370 various information like hostname, OS and perf version, cpu/mem 371 info, perf command line, event list and so on. Currently only 372 --stdio output supports this feature. 373 374--header-only:: 375 Show only perf.data header (forces --stdio). 376 377--itrace:: 378 Options for decoding instruction tracing data. The options are: 379 380include::itrace.txt[] 381 382 To disable decoding entirely, use --no-itrace. 383 384--full-source-path:: 385 Show the full path for source files for srcline output. 386 387--show-ref-call-graph:: 388 When multiple events are sampled, it may not be needed to collect 389 callgraphs for all of them. The sample sites are usually nearby, 390 and it's enough to collect the callgraphs on a reference event. 391 So user can use "call-graph=no" event modifier to disable callgraph 392 for other events to reduce the overhead. 393 However, perf report cannot show callgraphs for the event which 394 disable the callgraph. 395 This option extends the perf report to show reference callgraphs, 396 which collected by reference event, in no callgraph event. 397 398--socket-filter:: 399 Only report the samples on the processor socket that match with this filter 400 401--raw-trace:: 402 When displaying traceevent output, do not use print fmt or plugins. 403 404--hierarchy:: 405 Enable hierarchical output. 406 407include::callchain-overhead-calculation.txt[] 408 409SEE ALSO 410-------- 411linkperf:perf-stat[1], linkperf:perf-annotate[1] 412