'\" t
.\"     Title: perf-top
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 04/24/2018
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: English
.\"
.TH "PERF_3.16\-TOP" "1" "04/24/2018" "perf" "perf Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
perf-top \- System profiling tool\&.
.SH "SYNOPSIS"
.sp
.nf
\fIperf top\fR [\-e <EVENT> | \-\-event=EVENT] [<options>]
.fi
.SH "DESCRIPTION"
.sp
This command generates and displays a performance counter profile in real time\&.
.SH "OPTIONS"
.PP
\-a, \-\-all\-cpus
.RS 4
System\-wide collection\&. (default)
.RE
.PP
\-c <count>, \-\-count=<count>
.RS 4
Event period to sample\&.
.RE
.PP
\-C <cpu\-list>, \-\-cpu=<cpu>
.RS 4
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\&.
.RE
.PP
\-d <seconds>, \-\-delay=<seconds>
.RS 4
Number of seconds to delay between refreshes\&.
.RE
.PP
\-e <event>, \-\-event=<event>
.RS 4
Select the PMU event\&. Selection can be a symbolic event name (use
\fIperf list\fR
to list all events) or a raw PMU event (eventsel+umask) in the form of rNNN where NNN is a hexadecimal event descriptor\&.
.RE
.PP
\-E <entries>, \-\-entries=<entries>
.RS 4
Display this many functions\&.
.RE
.PP
\-f <count>, \-\-count\-filter=<count>
.RS 4
Only display functions with more events than this\&.
.RE
.PP
\-\-group
.RS 4
Put the counters into a counter group\&.
.RE
.PP
\-F <freq>, \-\-freq=<freq>
.RS 4
Profile at this frequency\&.
.RE
.PP
\-i, \-\-inherit
.RS 4
Child tasks do not inherit counters\&.
.RE
.PP
\-k <path>, \-\-vmlinux=<path>
.RS 4
Path to vmlinux\&. Required for annotation functionality\&.
.RE
.PP
\-m <pages>, \-\-mmap\-pages=<pages>
.RS 4
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\&.
.RE
.PP
\-p <pid>, \-\-pid=<pid>
.RS 4
Profile events on existing Process ID (comma separated list)\&.
.RE
.PP
\-t <tid>, \-\-tid=<tid>
.RS 4
Profile events on existing thread ID (comma separated list)\&.
.RE
.PP
\-u, \-\-uid=
.RS 4
Record events in threads owned by uid\&. Name or number\&.
.RE
.PP
\-r <priority>, \-\-realtime=<priority>
.RS 4
Collect data with this RT SCHED_FIFO priority\&.
.RE
.PP
\-\-sym\-annotate=<symbol>
.RS 4
Annotate this symbol\&.
.RE
.PP
\-K, \-\-hide_kernel_symbols
.RS 4
Hide kernel symbols\&.
.RE
.PP
\-U, \-\-hide_user_symbols
.RS 4
Hide user symbols\&.
.RE
.PP
\-D, \-\-dump\-symtab
.RS 4
Dump the symbol table used for profiling\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
Be more verbose (show counter open errors, etc)\&.
.RE
.PP
\-z, \-\-zero
.RS 4
Zero history across display updates\&.
.RE
.PP
\-s, \-\-sort
.RS 4
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\&.
.RE
.PP
\-\-fields=
.RS 4
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)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
By default, every sort keys not specified in \-\-field will be appended
automatically\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-n, \-\-show\-nr\-samples
.RS 4
Show a column with the number of samples\&.
.RE
.PP
\-\-show\-total\-period
.RS 4
Show a column with the sum of periods\&.
.RE
.PP
\-\-dsos
.RS 4
Only consider symbols in these dsos\&. This option will affect the percentage of the overhead column\&. See \-\-percentage for more info\&.
.RE
.PP
\-\-comms
.RS 4
Only consider symbols in these comms\&. This option will affect the percentage of the overhead column\&. See \-\-percentage for more info\&.
.RE
.PP
\-\-symbols
.RS 4
Only consider these symbols\&. This option will affect the percentage of the overhead column\&. See \-\-percentage for more info\&.
.RE
.PP
\-M, \-\-disassembler\-style=
.RS 4
Set disassembler style for objdump\&.
.RE
.PP
\-\-source
.RS 4
Interleave source code with assembly code\&. Enabled by default, disable with \-\-no\-source\&.
.RE
.PP
\-\-asm\-raw
.RS 4
Show raw instruction encoding of assembly instructions\&.
.RE
.PP
\-g
.RS 4
Enables call\-graph (stack chain/backtrace) recording\&.
.RE
.PP
\-\-call\-graph
.RS 4
Setup and enable call\-graph (stack chain/backtrace) recording, implies \-g\&.
.RE
.PP
\-\-children
.RS 4
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\&.
.RE
.PP
\-\-max\-stack
.RS 4
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Default: 127
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-\-ignore\-callees=<regex>
.RS 4
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\&.
.RE
.PP
\-\-percent\-limit
.RS 4
Do not show entries which have an overhead under that percent\&. (Default: 0)\&.
.RE
.PP
\-\-percentage
.RS 4
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)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
"relative" means it\*(Aqs 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\&.
.fi
.if n \{\
.RE
.\}
.RE
.SH "INTERACTIVE PROMPTING KEYS"
.PP
[d]
.RS 4
Display refresh delay\&.
.RE
.PP
[e]
.RS 4
Number of entries to display\&.
.RE
.PP
[E]
.RS 4
Event to display when multiple counters are active\&.
.RE
.PP
[f]
.RS 4
Profile display filter (>= hit count)\&.
.RE
.PP
[F]
.RS 4
Annotation display filter (>= % of total)\&.
.RE
.PP
[s]
.RS 4
Annotate symbol\&.
.RE
.PP
[S]
.RS 4
Stop annotation, return to full profile display\&.
.RE
.PP
[z]
.RS 4
Toggle event count zeroing across display updates\&.
.RE
.PP
[qQ]
.RS 4
Quit\&.
.RE
.sp
Pressing any unmapped key displays a menu, and prompts for input\&.
.SH "SEE ALSO"
.sp
\fBperf_3.16-stat\fR(1), \fBperf_3.16-list\fR(1), \fBperf_3.16-report\fR(1)