tools/perf/Documentation/perf-report.txt

   1 perf-report(1)
   2 ==============
   3
   4 NAME
   5 ----
   6 perf-report - Read perf.data (created by perf record) and display the profile
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'perf report' [-i <file> | --input=file]
  12
  13 DESCRIPTION
  14 -----------
  15 This command displays the performance counter profile information recorded
  16 via perf record.
  17
  18 OPTIONS
  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
 495 include::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 --hierarchy::
 535         Enable hierarchical output.
 536
 537 --inline::
 538         If a callgraph address belongs to an inlined function, the inline stack
 539         will be printed. Each entry is function name or file/line. Enabled by
 540         default, disable with --no-inline.
 541
 542 --mmaps::
 543         Show --tasks output plus mmap information in a format similar to
 544         /proc/<PID>/maps.
 545
 546         Please note that not all mmaps are stored, options affecting which ones
 547         are include 'perf record --data', for instance.
 548
 549 --ns::
 550         Show time stamps in nanoseconds.
 551
 552 --stats::
 553         Display overall events statistics without any further processing.
 554         (like the one at the end of the perf report -D command)
 555
 556 --tasks::
 557         Display monitored tasks stored in perf data. Displaying pid/tid/ppid
 558         plus the command string aligned to distinguish parent and child tasks.
 559
 560 --percent-type::
 561         Set annotation percent type from following choices:
 562           global-period, local-period, global-hits, local-hits
 563
 564         The local/global keywords set if the percentage is computed
 565         in the scope of the function (local) or the whole data (global).
 566         The period/hits keywords set the base the percentage is computed
 567         on - the samples period or the number of samples (hits).
 568
 569 --time-quantum::
 570         Configure time quantum for time sort key. Default 100ms.
 571         Accepts s, us, ms, ns units.
 572
 573 --total-cycles::
 574         When --total-cycles is specified, it supports sorting for all blocks by
 575         'Sampled Cycles%'. This is useful to concentrate on the globally hottest
 576         blocks. In output, there are some new columns:
 577
 578         'Sampled Cycles%' - block sampled cycles aggregation / total sampled cycles
 579         'Sampled Cycles'  - block sampled cycles aggregation
 580         'Avg Cycles%'     - block average sampled cycles / sum of total block average
 581                             sampled cycles
 582         'Avg Cycles'      - block average sampled cycles
 583
 584 --skip-empty::
 585         Do not print 0 results in the --stat output.
 586
 587 include::callchain-overhead-calculation.txt[]
 588
 589 SEE ALSO
 590 --------
 591 linkperf:perf-stat[1], linkperf:perf-annotate[1], linkperf:perf-record[1],
 592 linkperf:perf-intel-pt[1]