0001 perf-report(1)
0002 ==============
0003
0004 NAME
0005 ----
0006 perf-report - Read perf.data (created by perf record) and display the profile
0007
0008 SYNOPSIS
0009 --------
0010 [verse]
0011 'perf report' [-i <file> | --input=file]
0012
0013 DESCRIPTION
0014 -----------
0015 This command displays the performance counter profile information recorded
0016 via perf record.
0017
0018 OPTIONS
0019 -------
0020 -i::
0021 --input=::
0022 Input file name. (default: perf.data unless stdin is a fifo)
0023
0024 -v::
0025 --verbose::
0026 Be more verbose. (show symbol address, etc)
0027
0028 -q::
0029 --quiet::
0030 Do not show any message. (Suppress -v)
0031
0032 -n::
0033 --show-nr-samples::
0034 Show the number of samples for each symbol
0035
0036 --show-cpu-utilization::
0037 Show sample percentage for different cpu modes.
0038
0039 -T::
0040 --threads::
0041 Show per-thread event counters. The input data file should be recorded
0042 with -s option.
0043 -c::
0044 --comms=::
0045 Only consider symbols in these comms. CSV that understands
0046 file://filename entries. This option will affect the percentage of
0047 the overhead column. See --percentage for more info.
0048 --pid=::
0049 Only show events for given process ID (comma separated list).
0050
0051 --tid=::
0052 Only show events for given thread ID (comma separated list).
0053 -d::
0054 --dsos=::
0055 Only consider symbols in these dsos. CSV that understands
0056 file://filename entries. This option will affect the percentage of
0057 the overhead column. See --percentage for more info.
0058 -S::
0059 --symbols=::
0060 Only consider these symbols. CSV that understands
0061 file://filename entries. This option will affect the percentage of
0062 the overhead column. See --percentage for more info.
0063
0064 --symbol-filter=::
0065 Only show symbols that match (partially) with this filter.
0066
0067 -U::
0068 --hide-unresolved::
0069 Only display entries resolved to a symbol.
0070
0071 -s::
0072 --sort=::
0073 Sort histogram entries by given key(s) - multiple keys can be specified
0074 in CSV format. Following sort keys are available:
0075 pid, comm, dso, symbol, parent, cpu, socket, srcline, weight,
0076 local_weight, cgroup_id.
0077
0078 Each key has following meaning:
0079
0080 - comm: command (name) of the task which can be read via /proc/<pid>/comm
0081 - pid: command and tid of the task
0082 - dso: name of library or module executed at the time of sample
0083 - dso_size: size of library or module executed at the time of sample
0084 - symbol: name of function executed at the time of sample
0085 - symbol_size: size of function executed at the time of sample
0086 - parent: name of function matched to the parent regex filter. Unmatched
0087 entries are displayed as "[other]".
0088 - cpu: cpu number the task ran at the time of sample
0089 - socket: processor socket number the task ran at the time of sample
0090 - srcline: filename and line number executed at the time of sample. The
0091 DWARF debugging info must be provided.
0092 - srcfile: file name of the source file of the samples. Requires dwarf
0093 information.
0094 - weight: Event specific weight, e.g. memory latency or transaction
0095 abort cost. This is the global weight.
0096 - local_weight: Local weight version of the weight above.
0097 - cgroup_id: ID derived from cgroup namespace device and inode numbers.
0098 - cgroup: cgroup pathname in the cgroupfs.
0099 - transaction: Transaction abort flags.
0100 - overhead: Overhead percentage of sample
0101 - overhead_sys: Overhead percentage of sample running in system mode
0102 - overhead_us: Overhead percentage of sample running in user mode
0103 - overhead_guest_sys: Overhead percentage of sample running in system mode
0104 on guest machine
0105 - overhead_guest_us: Overhead percentage of sample running in user mode on
0106 guest machine
0107 - sample: Number of sample
0108 - period: Raw number of event count of sample
0109 - time: Separate the samples by time stamp with the resolution specified by
0110 --time-quantum (default 100ms). Specify with overhead and before it.
0111 - code_page_size: the code page size of sampled code address (ip)
0112 - ins_lat: Instruction latency in core cycles. This is the global instruction
0113 latency
0114 - local_ins_lat: Local instruction latency version
0115 - p_stage_cyc: On powerpc, this presents the number of cycles spent in a
0116 pipeline stage. And currently supported only on powerpc.
0117
0118 By default, comm, dso and symbol keys are used.
0119 (i.e. --sort comm,dso,symbol)
0120
0121 If --branch-stack option is used, following sort keys are also
0122 available:
0123
0124 - dso_from: name of library or module branched from
0125 - dso_to: name of library or module branched to
0126 - symbol_from: name of function branched from
0127 - symbol_to: name of function branched to
0128 - srcline_from: source file and line branched from
0129 - srcline_to: source file and line branched to
0130 - mispredict: "N" for predicted branch, "Y" for mispredicted branch
0131 - in_tx: branch in TSX transaction
0132 - abort: TSX transaction abort.
0133 - cycles: Cycles in basic block
0134
0135 And default sort keys are changed to comm, dso_from, symbol_from, dso_to
0136 and symbol_to, see '--branch-stack'.
0137
0138 When the sort key symbol is specified, columns "IPC" and "IPC Coverage"
0139 are enabled automatically. Column "IPC" reports the average IPC per function
0140 and column "IPC coverage" reports the percentage of instructions with
0141 sampled IPC in this function. IPC means Instruction Per Cycle. If it's low,
0142 it indicates there may be a performance bottleneck when the function is
0143 executed, such as a memory access bottleneck. If a function has high overhead
0144 and low IPC, it's worth further analyzing it to optimize its performance.
0145
0146 If the --mem-mode option is used, the following sort keys are also available
0147 (incompatible with --branch-stack):
0148 symbol_daddr, dso_daddr, locked, tlb, mem, snoop, dcacheline, blocked.
0149
0150 - symbol_daddr: name of data symbol being executed on at the time of sample
0151 - dso_daddr: name of library or module containing the data being executed
0152 on at the time of the sample
0153 - locked: whether the bus was locked at the time of the sample
0154 - tlb: type of tlb access for the data at the time of the sample
0155 - mem: type of memory access for the data at the time of the sample
0156 - snoop: type of snoop (if any) for the data at the time of the sample
0157 - dcacheline: the cacheline the data address is on at the time of the sample
0158 - phys_daddr: physical address of data being executed on at the time of sample
0159 - data_page_size: the data page size of data being executed on at the time of sample
0160 - blocked: reason of blocked load access for the data at the time of the sample
0161
0162 And the default sort keys are changed to local_weight, mem, sym, dso,
0163 symbol_daddr, dso_daddr, snoop, tlb, locked, blocked, local_ins_lat,
0164 see '--mem-mode'.
0165
0166 If the data file has tracepoint event(s), following (dynamic) sort keys
0167 are also available:
0168 trace, trace_fields, [<event>.]<field>[/raw]
0169
0170 - trace: pretty printed trace output in a single column
0171 - trace_fields: fields in tracepoints in separate columns
0172 - <field name>: optional event and field name for a specific field
0173
0174 The last form consists of event and field names. If event name is
0175 omitted, it searches all events for matching field name. The matched
0176 field will be shown only for the event has the field. The event name
0177 supports substring match so user doesn't need to specify full subsystem
0178 and event name everytime. For example, 'sched:sched_switch' event can
0179 be shortened to 'switch' as long as it's not ambiguous. Also event can
0180 be specified by its index (starting from 1) preceded by the '%'.
0181 So '%1' is the first event, '%2' is the second, and so on.
0182
0183 The field name can have '/raw' suffix which disables pretty printing
0184 and shows raw field value like hex numbers. The --raw-trace option
0185 has the same effect for all dynamic sort keys.
0186
0187 The default sort keys are changed to 'trace' if all events in the data
0188 file are tracepoint.
0189
0190 -F::
0191 --fields=::
0192 Specify output field - multiple keys can be specified in CSV format.
0193 Following fields are available:
0194 overhead, overhead_sys, overhead_us, overhead_children, sample and period.
0195 Also it can contain any sort key(s).
0196
0197 By default, every sort keys not specified in -F will be appended
0198 automatically.
0199
0200 If the keys starts with a prefix '+', then it will append the specified
0201 field(s) to the default field order. For example: perf report -F +period,sample.
0202
0203 -p::
0204 --parent=<regex>::
0205 A regex filter to identify parent. The parent is a caller of this
0206 function and searched through the callchain, thus it requires callchain
0207 information recorded. The pattern is in the extended regex format and
0208 defaults to "\^sys_|^do_page_fault", see '--sort parent'.
0209
0210 -x::
0211 --exclude-other::
0212 Only display entries with parent-match.
0213
0214 -w::
0215 --column-widths=<width[,width...]>::
0216 Force each column width to the provided list, for large terminal
0217 readability. 0 means no limit (default behavior).
0218
0219 -t::
0220 --field-separator=::
0221 Use a special separator character and don't pad with spaces, replacing
0222 all occurrences of this separator in symbol names (and other output)
0223 with a '.' character, that thus it's the only non valid separator.
0224
0225 -D::
0226 --dump-raw-trace::
0227 Dump raw trace in ASCII.
0228
0229 --disable-order::
0230 Disable raw trace ordering.
0231
0232 -g::
0233 --call-graph=<print_type,threshold[,print_limit],order,sort_key[,branch],value>::
0234 Display call chains using type, min percent threshold, print limit,
0235 call order, sort key, optional branch and value. Note that ordering
0236 is not fixed so any parameter can be given in an arbitrary order.
0237 One exception is the print_limit which should be preceded by threshold.
0238
0239 print_type can be either:
0240 - flat: single column, linear exposure of call chains.
0241 - graph: use a graph tree, displaying absolute overhead rates. (default)
0242 - fractal: like graph, but displays relative rates. Each branch of
0243 the tree is considered as a new profiled object.
0244 - folded: call chains are displayed in a line, separated by semicolons
0245 - none: disable call chain display.
0246
0247 threshold is a percentage value which specifies a minimum percent to be
0248 included in the output call graph. Default is 0.5 (%).
0249
0250 print_limit is only applied when stdio interface is used. It's to limit
0251 number of call graph entries in a single hist entry. Note that it needs
0252 to be given after threshold (but not necessarily consecutive).
0253 Default is 0 (unlimited).
0254
0255 order can be either:
0256 - callee: callee based call graph.
0257 - caller: inverted caller based call graph.
0258 Default is 'caller' when --children is used, otherwise 'callee'.
0259
0260 sort_key can be:
0261 - function: compare on functions (default)
0262 - address: compare on individual code addresses
0263 - srcline: compare on source filename and line number
0264
0265 branch can be:
0266 - branch: include last branch information in callgraph when available.
0267 Usually more convenient to use --branch-history for this.
0268
0269 value can be:
0270 - percent: display overhead percent (default)
0271 - period: display event period
0272 - count: display event count
0273
0274 --children::
0275 Accumulate callchain of children to parent entry so that then can
0276 show up in the output. The output will have a new "Children" column
0277 and will be sorted on the data. It requires callchains are recorded.
0278 See the `overhead calculation' section for more details. Enabled by
0279 default, disable with --no-children.
0280
0281 --max-stack::
0282 Set the stack depth limit when parsing the callchain, anything
0283 beyond the specified depth will be ignored. This is a trade-off
0284 between information loss and faster processing especially for
0285 workloads that can have a very long callchain stack.
0286 Note that when using the --itrace option the synthesized callchain size
0287 will override this value if the synthesized callchain size is bigger.
0288
0289 Default: 127
0290
0291 -G::
0292 --inverted::
0293 alias for inverted caller based call graph.
0294
0295 --ignore-callees=<regex>::
0296 Ignore callees of the function(s) matching the given regex.
0297 This has the effect of collecting the callers of each such
0298 function into one place in the call-graph tree.
0299
0300 --pretty=<key>::
0301 Pretty printing style. key: normal, raw
0302
0303 --stdio:: Use the stdio interface.
0304
0305 --stdio-color::
0306 'always', 'never' or 'auto', allowing configuring color output
0307 via the command line, in addition to via "color.ui" .perfconfig.
0308 Use '--stdio-color always' to generate color even when redirecting
0309 to a pipe or file. Using just '--stdio-color' is equivalent to
0310 using 'always'.
0311
0312 --tui:: Use the TUI interface, that is integrated with annotate and allows
0313 zooming into DSOs or threads, among other features. Use of --tui
0314 requires a tty, if one is not present, as when piping to other
0315 commands, the stdio interface is used.
0316
0317 --gtk:: Use the GTK2 interface.
0318
0319 -k::
0320 --vmlinux=<file>::
0321 vmlinux pathname
0322
0323 --ignore-vmlinux::
0324 Ignore vmlinux files.
0325
0326 --kallsyms=<file>::
0327 kallsyms pathname
0328
0329 -m::
0330 --modules::
0331 Load module symbols. WARNING: This should only be used with -k and
0332 a LIVE kernel.
0333
0334 -f::
0335 --force::
0336 Don't do ownership validation.
0337
0338 --symfs=<directory>::
0339 Look for files with symbols relative to this directory.
0340
0341 -C::
0342 --cpu:: Only report samples for the list of CPUs provided. Multiple CPUs can
0343 be provided as a comma-separated list with no space: 0,1. Ranges of
0344 CPUs are specified with -: 0-2. Default is to report samples on all
0345 CPUs.
0346
0347 -M::
0348 --disassembler-style=:: Set disassembler style for objdump.
0349
0350 --source::
0351 Interleave source code with assembly code. Enabled by default,
0352 disable with --no-source.
0353
0354 --asm-raw::
0355 Show raw instruction encoding of assembly instructions.
0356
0357 --show-total-period:: Show a column with the sum of periods.
0358
0359 -I::
0360 --show-info::
0361 Display extended information about the perf.data file. This adds
0362 information which may be very large and thus may clutter the display.
0363 It currently includes: cpu and numa topology of the host system.
0364
0365 -b::
0366 --branch-stack::
0367 Use the addresses of sampled taken branches instead of the instruction
0368 address to build the histograms. To generate meaningful output, the
0369 perf.data file must have been obtained using perf record -b or
0370 perf record --branch-filter xxx where xxx is a branch filter option.
0371 perf report is able to auto-detect whether a perf.data file contains
0372 branch stacks and it will automatically switch to the branch view mode,
0373 unless --no-branch-stack is used.
0374
0375 --branch-history::
0376 Add the addresses of sampled taken branches to the callstack.
0377 This allows to examine the path the program took to each sample.
0378 The data collection must have used -b (or -j) and -g.
0379
0380 --objdump=<path>::
0381 Path to objdump binary.
0382
0383 --prefix=PREFIX::
0384 --prefix-strip=N::
0385 Remove first N entries from source file path names in executables
0386 and add PREFIX. This allows to display source code compiled on systems
0387 with different file system layout.
0388
0389 --group::
0390 Show event group information together. It forces group output also
0391 if there are no groups defined in data file.
0392
0393 --group-sort-idx::
0394 Sort the output by the event at the index n in group. If n is invalid,
0395 sort by the first event. It can support multiple groups with different
0396 amount of events. WARNING: This should be used on grouped events.
0397
0398 --demangle::
0399 Demangle symbol names to human readable form. It's enabled by default,
0400 disable with --no-demangle.
0401
0402 --demangle-kernel::
0403 Demangle kernel symbol names to human readable form (for C++ kernels).
0404
0405 --mem-mode::
0406 Use the data addresses of samples in addition to instruction addresses
0407 to build the histograms. To generate meaningful output, the perf.data
0408 file must have been obtained using perf record -d -W and using a
0409 special event -e cpu/mem-loads/p or -e cpu/mem-stores/p. See
0410 'perf mem' for simpler access.
0411
0412 --percent-limit::
0413 Do not show entries which have an overhead under that percent.
0414 (Default: 0). Note that this option also sets the percent limit (threshold)
0415 of callchains. However the default value of callchain threshold is
0416 different than the default value of hist entries. Please see the
0417 --call-graph option for details.
0418
0419 --percentage::
0420 Determine how to display the overhead percentage of filtered entries.
0421 Filters can be applied by --comms, --dsos and/or --symbols options and
0422 Zoom operations on the TUI (thread, dso, etc).
0423
0424 "relative" means it's relative to filtered entries only so that the
0425 sum of shown entries will be always 100%. "absolute" means it retains
0426 the original value before and after the filter is applied.
0427
0428 --header::
0429 Show header information in the perf.data file. This includes
0430 various information like hostname, OS and perf version, cpu/mem
0431 info, perf command line, event list and so on. Currently only
0432 --stdio output supports this feature.
0433
0434 --header-only::
0435 Show only perf.data header (forces --stdio).
0436
0437 --time::
0438 Only analyze samples within given time window: <start>,<stop>. Times
0439 have the format seconds.nanoseconds. If start is not given (i.e. time
0440 string is ',x.y') then analysis starts at the beginning of the file. If
0441 stop time is not given (i.e. time string is 'x.y,') then analysis goes
0442 to end of file. Multiple ranges can be separated by spaces, which
0443 requires the argument to be quoted e.g. --time "1234.567,1234.789 1235,"
0444
0445 Also support time percent with multiple time ranges. Time string is
0446 'a%/n,b%/m,...' or 'a%-b%,c%-%d,...'.
0447
0448 For example:
0449 Select the second 10% time slice:
0450
0451 perf report --time 10%/2
0452
0453 Select from 0% to 10% time slice:
0454
0455 perf report --time 0%-10%
0456
0457 Select the first and second 10% time slices:
0458
0459 perf report --time 10%/1,10%/2
0460
0461 Select from 0% to 10% and 30% to 40% slices:
0462
0463 perf report --time 0%-10%,30%-40%
0464
0465 --switch-on EVENT_NAME::
0466 Only consider events after this event is found.
0467
0468 This may be interesting to measure a workload only after some initialization
0469 phase is over, i.e. insert a perf probe at that point and then using this
0470 option with that probe.
0471
0472 --switch-off EVENT_NAME::
0473 Stop considering events after this event is found.
0474
0475 --show-on-off-events::
0476 Show the --switch-on/off events too. This has no effect in 'perf report' now
0477 but probably we'll make the default not to show the switch-on/off events
0478 on the --group mode and if there is only one event besides the off/on ones,
0479 go straight to the histogram browser, just like 'perf report' with no events
0480 explicitly specified does.
0481
0482 --itrace::
0483 Options for decoding instruction tracing data. The options are:
0484
0485 include::itrace.txt[]
0486
0487 To disable decoding entirely, use --no-itrace.
0488
0489 --full-source-path::
0490 Show the full path for source files for srcline output.
0491
0492 --show-ref-call-graph::
0493 When multiple events are sampled, it may not be needed to collect
0494 callgraphs for all of them. The sample sites are usually nearby,
0495 and it's enough to collect the callgraphs on a reference event.
0496 So user can use "call-graph=no" event modifier to disable callgraph
0497 for other events to reduce the overhead.
0498 However, perf report cannot show callgraphs for the event which
0499 disable the callgraph.
0500 This option extends the perf report to show reference callgraphs,
0501 which collected by reference event, in no callgraph event.
0502
0503 --stitch-lbr::
0504 Show callgraph with stitched LBRs, which may have more complete
0505 callgraph. The perf.data file must have been obtained using
0506 perf record --call-graph lbr.
0507 Disabled by default. In common cases with call stack overflows,
0508 it can recreate better call stacks than the default lbr call stack
0509 output. But this approach is not full proof. There can be cases
0510 where it creates incorrect call stacks from incorrect matches.
0511 The known limitations include exception handing such as
0512 setjmp/longjmp will have calls/returns not match.
0513
0514 --socket-filter::
0515 Only report the samples on the processor socket that match with this filter
0516
0517 --samples=N::
0518 Save N individual samples for each histogram entry to show context in perf
0519 report tui browser.
0520
0521 --raw-trace::
0522 When displaying traceevent output, do not use print fmt or plugins.
0523
0524 --hierarchy::
0525 Enable hierarchical output.
0526
0527 --inline::
0528 If a callgraph address belongs to an inlined function, the inline stack
0529 will be printed. Each entry is function name or file/line. Enabled by
0530 default, disable with --no-inline.
0531
0532 --mmaps::
0533 Show --tasks output plus mmap information in a format similar to
0534 /proc/<PID>/maps.
0535
0536 Please note that not all mmaps are stored, options affecting which ones
0537 are include 'perf record --data', for instance.
0538
0539 --ns::
0540 Show time stamps in nanoseconds.
0541
0542 --stats::
0543 Display overall events statistics without any further processing.
0544 (like the one at the end of the perf report -D command)
0545
0546 --tasks::
0547 Display monitored tasks stored in perf data. Displaying pid/tid/ppid
0548 plus the command string aligned to distinguish parent and child tasks.
0549
0550 --percent-type::
0551 Set annotation percent type from following choices:
0552 global-period, local-period, global-hits, local-hits
0553
0554 The local/global keywords set if the percentage is computed
0555 in the scope of the function (local) or the whole data (global).
0556 The period/hits keywords set the base the percentage is computed
0557 on - the samples period or the number of samples (hits).
0558
0559 --time-quantum::
0560 Configure time quantum for time sort key. Default 100ms.
0561 Accepts s, us, ms, ns units.
0562
0563 --total-cycles::
0564 When --total-cycles is specified, it supports sorting for all blocks by
0565 'Sampled Cycles%'. This is useful to concentrate on the globally hottest
0566 blocks. In output, there are some new columns:
0567
0568 'Sampled Cycles%' - block sampled cycles aggregation / total sampled cycles
0569 'Sampled Cycles' - block sampled cycles aggregation
0570 'Avg Cycles%' - block average sampled cycles / sum of total block average
0571 sampled cycles
0572 'Avg Cycles' - block average sampled cycles
0573
0574 --skip-empty::
0575 Do not print 0 results in the --stat output.
0576
0577 include::callchain-overhead-calculation.txt[]
0578
0579 SEE ALSO
0580 --------
0581 linkperf:perf-stat[1], linkperf:perf-annotate[1], linkperf:perf-record[1],
0582 linkperf:perf-intel-pt[1]
