351 lines
10 KiB
Plaintext
351 lines
10 KiB
Plaintext
perf-top(1)
|
|
===========
|
|
|
|
NAME
|
|
----
|
|
perf-top - System profiling tool.
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'perf top' [-e <EVENT> | --event=EVENT] [<options>]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
This command generates and displays a performance counter profile in real time.
|
|
|
|
|
|
OPTIONS
|
|
-------
|
|
-a::
|
|
--all-cpus::
|
|
System-wide collection. (default)
|
|
|
|
-c <count>::
|
|
--count=<count>::
|
|
Event period to sample.
|
|
|
|
-C <cpu-list>::
|
|
--cpu=<cpu>::
|
|
Monitor only on the list of CPUs provided. Multiple CPUs can be provided as a
|
|
comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2.
|
|
Default is to monitor all CPUS.
|
|
|
|
-d <seconds>::
|
|
--delay=<seconds>::
|
|
Number of seconds to delay between refreshes.
|
|
|
|
-e <event>::
|
|
--event=<event>::
|
|
Select the PMU event. Selection can be a symbolic event name
|
|
(use 'perf list' to list all events) or a raw PMU
|
|
event (eventsel+umask) in the form of rNNN where NNN is a
|
|
hexadecimal event descriptor.
|
|
|
|
-E <entries>::
|
|
--entries=<entries>::
|
|
Display this many functions.
|
|
|
|
-f <count>::
|
|
--count-filter=<count>::
|
|
Only display functions with more events than this.
|
|
|
|
--group::
|
|
Put the counters into a counter group.
|
|
|
|
-F <freq>::
|
|
--freq=<freq>::
|
|
Profile at this frequency. Use 'max' to use the currently maximum
|
|
allowed frequency, i.e. the value in the kernel.perf_event_max_sample_rate
|
|
sysctl.
|
|
|
|
-i::
|
|
--inherit::
|
|
Child tasks do not inherit counters.
|
|
|
|
-k <path>::
|
|
--vmlinux=<path>::
|
|
Path to vmlinux. Required for annotation functionality.
|
|
|
|
--ignore-vmlinux::
|
|
Ignore vmlinux files.
|
|
|
|
--kallsyms=<file>::
|
|
kallsyms pathname
|
|
|
|
-m <pages>::
|
|
--mmap-pages=<pages>::
|
|
Number of mmap data pages (must be a power of two) or size
|
|
specification with appended unit character - B/K/M/G. The
|
|
size is rounded up to have nearest pages power of two value.
|
|
|
|
-p <pid>::
|
|
--pid=<pid>::
|
|
Profile events on existing Process ID (comma separated list).
|
|
|
|
-t <tid>::
|
|
--tid=<tid>::
|
|
Profile events on existing thread ID (comma separated list).
|
|
|
|
-u::
|
|
--uid=::
|
|
Record events in threads owned by uid. Name or number.
|
|
|
|
-r <priority>::
|
|
--realtime=<priority>::
|
|
Collect data with this RT SCHED_FIFO priority.
|
|
|
|
--sym-annotate=<symbol>::
|
|
Annotate this symbol.
|
|
|
|
-K::
|
|
--hide_kernel_symbols::
|
|
Hide kernel symbols.
|
|
|
|
-U::
|
|
--hide_user_symbols::
|
|
Hide user symbols.
|
|
|
|
--demangle-kernel::
|
|
Demangle kernel symbols.
|
|
|
|
-D::
|
|
--dump-symtab::
|
|
Dump the symbol table used for profiling.
|
|
|
|
-v::
|
|
--verbose::
|
|
Be more verbose (show counter open errors, etc).
|
|
|
|
-z::
|
|
--zero::
|
|
Zero history across display updates.
|
|
|
|
-s::
|
|
--sort::
|
|
Sort by key(s): pid, comm, dso, symbol, parent, srcline, weight,
|
|
local_weight, abort, in_tx, transaction, overhead, sample, period.
|
|
Please see description of --sort in the perf-report man page.
|
|
|
|
--fields=::
|
|
Specify output field - multiple keys can be specified in CSV format.
|
|
Following fields are available:
|
|
overhead, overhead_sys, overhead_us, overhead_children, sample and period.
|
|
Also it can contain any sort key(s).
|
|
|
|
By default, every sort keys not specified in --field will be appended
|
|
automatically.
|
|
|
|
-n::
|
|
--show-nr-samples::
|
|
Show a column with the number of samples.
|
|
|
|
--show-total-period::
|
|
Show a column with the sum of periods.
|
|
|
|
--dsos::
|
|
Only consider symbols in these dsos. This option will affect the
|
|
percentage of the overhead column. See --percentage for more info.
|
|
|
|
--comms::
|
|
Only consider symbols in these comms. This option will affect the
|
|
percentage of the overhead column. See --percentage for more info.
|
|
|
|
--symbols::
|
|
Only consider these symbols. This option will affect the
|
|
percentage of the overhead column. See --percentage for more info.
|
|
|
|
-M::
|
|
--disassembler-style=:: Set disassembler style for objdump.
|
|
|
|
--source::
|
|
Interleave source code with assembly code. Enabled by default,
|
|
disable with --no-source.
|
|
|
|
--asm-raw::
|
|
Show raw instruction encoding of assembly instructions.
|
|
|
|
-g::
|
|
Enables call-graph (stack chain/backtrace) recording.
|
|
|
|
--call-graph [mode,type,min[,limit],order[,key][,branch]]::
|
|
Setup and enable call-graph (stack chain/backtrace) recording,
|
|
implies -g. See `--call-graph` section in perf-record and
|
|
perf-report man pages for details.
|
|
|
|
--children::
|
|
Accumulate callchain of children to parent entry so that then can
|
|
show up in the output. The output will have a new "Children" column
|
|
and will be sorted on the data. It requires -g/--call-graph option
|
|
enabled. See the `overhead calculation' section for more details.
|
|
Enabled by default, disable with --no-children.
|
|
|
|
--max-stack::
|
|
Set the stack depth limit when parsing the callchain, anything
|
|
beyond the specified depth will be ignored. This is a trade-off
|
|
between information loss and faster processing especially for
|
|
workloads that can have a very long callchain stack.
|
|
|
|
Default: /proc/sys/kernel/perf_event_max_stack when present, 127 otherwise.
|
|
|
|
--ignore-callees=<regex>::
|
|
Ignore callees of the function(s) matching the given regex.
|
|
This has the effect of collecting the callers of each such
|
|
function into one place in the call-graph tree.
|
|
|
|
--percent-limit::
|
|
Do not show entries which have an overhead under that percent.
|
|
(Default: 0).
|
|
|
|
--percentage::
|
|
Determine how to display the overhead percentage of filtered entries.
|
|
Filters can be applied by --comms, --dsos and/or --symbols options and
|
|
Zoom operations on the TUI (thread, dso, etc).
|
|
|
|
"relative" means it's relative to filtered entries only so that the
|
|
sum of shown entries will be always 100%. "absolute" means it retains
|
|
the original value before and after the filter is applied.
|
|
|
|
-w::
|
|
--column-widths=<width[,width...]>::
|
|
Force each column width to the provided list, for large terminal
|
|
readability. 0 means no limit (default behavior).
|
|
|
|
--proc-map-timeout::
|
|
When processing pre-existing threads /proc/XXX/mmap, it may take
|
|
a long time, because the file may be huge. A time out is needed
|
|
in such cases.
|
|
This option sets the time out limit. The default value is 500 ms.
|
|
|
|
|
|
-b::
|
|
--branch-any::
|
|
Enable taken branch stack sampling. Any type of taken branch may be sampled.
|
|
This is a shortcut for --branch-filter any. See --branch-filter for more infos.
|
|
|
|
-j::
|
|
--branch-filter::
|
|
Enable taken branch stack sampling. Each sample captures a series of consecutive
|
|
taken branches. The number of branches captured with each sample depends on the
|
|
underlying hardware, the type of branches of interest, and the executed code.
|
|
It is possible to select the types of branches captured by enabling filters.
|
|
For a full list of modifiers please see the perf record manpage.
|
|
|
|
The option requires at least one branch type among any, any_call, any_ret, ind_call, cond.
|
|
The privilege levels may be omitted, in which case, the privilege levels of the associated
|
|
event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege
|
|
levels are subject to permissions. When sampling on multiple events, branch stack sampling
|
|
is enabled for all the sampling events. The sampled branch type is the same for all events.
|
|
The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k
|
|
Note that this feature may not be available on all processors.
|
|
|
|
--raw-trace::
|
|
When displaying traceevent output, do not use print fmt or plugins.
|
|
|
|
--hierarchy::
|
|
Enable hierarchy output.
|
|
|
|
--overwrite::
|
|
Enable this to use just the most recent records, which helps in high core count
|
|
machines such as Knights Landing/Mill, but right now is disabled by default as
|
|
the pausing used in this technique is leading to loss of metadata events such
|
|
as PERF_RECORD_MMAP which makes 'perf top' unable to resolve samples, leading
|
|
to lots of unknown samples appearing on the UI. Enable this if you are in such
|
|
machines and profiling a workload that doesn't creates short lived threads and/or
|
|
doesn't uses many executable mmap operations. Work is being planed to solve
|
|
this situation, till then, this will remain disabled by default.
|
|
|
|
--force::
|
|
Don't do ownership validation.
|
|
|
|
--num-thread-synthesize::
|
|
The number of threads to run when synthesizing events for existing processes.
|
|
By default, the number of threads equals to the number of online CPUs.
|
|
|
|
--namespaces::
|
|
Record events of type PERF_RECORD_NAMESPACES and display it with the
|
|
'cgroup_id' sort key.
|
|
|
|
--switch-on EVENT_NAME::
|
|
Only consider events after this event is found.
|
|
|
|
E.g.:
|
|
|
|
Find out where broadcast packets are handled
|
|
|
|
perf probe -L icmp_rcv
|
|
|
|
Insert a probe there:
|
|
|
|
perf probe icmp_rcv:59
|
|
|
|
Start perf top and ask it to only consider the cycles events when a
|
|
broadcast packet arrives This will show a menu with two entries and
|
|
will start counting when a broadcast packet arrives:
|
|
|
|
perf top -e cycles,probe:icmp_rcv --switch-on=probe:icmp_rcv
|
|
|
|
Alternatively one can ask for --group and then two overhead columns
|
|
will appear, the first for cycles and the second for the switch-on event.
|
|
|
|
perf top --group -e cycles,probe:icmp_rcv --switch-on=probe:icmp_rcv
|
|
|
|
This may be interesting to measure a workload only after some initialization
|
|
phase is over, i.e. insert a perf probe at that point and use the above
|
|
examples replacing probe:icmp_rcv with the just-after-init probe.
|
|
|
|
--switch-off EVENT_NAME::
|
|
Stop considering events after this event is found.
|
|
|
|
--show-on-off-events::
|
|
Show the --switch-on/off events too. This has no effect in 'perf top' now
|
|
but probably we'll make the default not to show the switch-on/off events
|
|
on the --group mode and if there is only one event besides the off/on ones,
|
|
go straight to the histogram browser, just like 'perf top' with no events
|
|
explicitely specified does.
|
|
|
|
|
|
INTERACTIVE PROMPTING KEYS
|
|
--------------------------
|
|
|
|
[d]::
|
|
Display refresh delay.
|
|
|
|
[e]::
|
|
Number of entries to display.
|
|
|
|
[E]::
|
|
Event to display when multiple counters are active.
|
|
|
|
[f]::
|
|
Profile display filter (>= hit count).
|
|
|
|
[F]::
|
|
Annotation display filter (>= % of total).
|
|
|
|
[s]::
|
|
Annotate symbol.
|
|
|
|
[S]::
|
|
Stop annotation, return to full profile display.
|
|
|
|
[K]::
|
|
Hide kernel symbols.
|
|
|
|
[U]::
|
|
Hide user symbols.
|
|
|
|
[z]::
|
|
Toggle event count zeroing across display updates.
|
|
|
|
[qQ]::
|
|
Quit.
|
|
|
|
Pressing any unmapped key displays a menu, and prompts for input.
|
|
|
|
include::callchain-overhead-calculation.txt[]
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkperf:perf-stat[1], linkperf:perf-list[1], linkperf:perf-report[1]
|