]>
Commit | Line | Data |
---|---|---|
1 | perf-top(1) | |
2 | =========== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | perf-top - System profiling tool. | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | 'perf top' [-e <EVENT> | --event=EVENT] [<options>] | |
12 | ||
13 | DESCRIPTION | |
14 | ----------- | |
15 | This command generates and displays a performance counter profile in real time. | |
16 | ||
17 | ||
18 | OPTIONS | |
19 | ------- | |
20 | -a:: | |
21 | --all-cpus:: | |
22 | System-wide collection. (default) | |
23 | ||
24 | -c <count>:: | |
25 | --count=<count>:: | |
26 | Event period to sample. | |
27 | ||
28 | -C <cpu-list>:: | |
29 | --cpu=<cpu>:: | |
30 | Monitor only on the list of CPUs provided. Multiple CPUs can be provided as a | |
31 | comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2. | |
32 | Default is to monitor all CPUS. | |
33 | ||
34 | -d <seconds>:: | |
35 | --delay=<seconds>:: | |
36 | Number of seconds to delay between refreshes. | |
37 | ||
38 | -e <event>:: | |
39 | --event=<event>:: | |
40 | Select the PMU event. Selection can be a symbolic event name | |
41 | (use 'perf list' to list all events) or a raw PMU | |
42 | event (eventsel+umask) in the form of rNNN where NNN is a | |
43 | hexadecimal event descriptor. | |
44 | ||
45 | -E <entries>:: | |
46 | --entries=<entries>:: | |
47 | Display this many functions. | |
48 | ||
49 | -f <count>:: | |
50 | --count-filter=<count>:: | |
51 | Only display functions with more events than this. | |
52 | ||
53 | --group:: | |
54 | Put the counters into a counter group. | |
55 | ||
56 | -F <freq>:: | |
57 | --freq=<freq>:: | |
58 | Profile at this frequency. | |
59 | ||
60 | -i:: | |
61 | --inherit:: | |
62 | Child tasks do not inherit counters. | |
63 | ||
64 | -k <path>:: | |
65 | --vmlinux=<path>:: | |
66 | Path to vmlinux. Required for annotation functionality. | |
67 | ||
68 | -m <pages>:: | |
69 | --mmap-pages=<pages>:: | |
70 | Number of mmap data pages (must be a power of two) or size | |
71 | specification with appended unit character - B/K/M/G. The | |
72 | size is rounded up to have nearest pages power of two value. | |
73 | ||
74 | -p <pid>:: | |
75 | --pid=<pid>:: | |
76 | Profile events on existing Process ID (comma separated list). | |
77 | ||
78 | -t <tid>:: | |
79 | --tid=<tid>:: | |
80 | Profile events on existing thread ID (comma separated list). | |
81 | ||
82 | -u:: | |
83 | --uid=:: | |
84 | Record events in threads owned by uid. Name or number. | |
85 | ||
86 | -r <priority>:: | |
87 | --realtime=<priority>:: | |
88 | Collect data with this RT SCHED_FIFO priority. | |
89 | ||
90 | --sym-annotate=<symbol>:: | |
91 | Annotate this symbol. | |
92 | ||
93 | -K:: | |
94 | --hide_kernel_symbols:: | |
95 | Hide kernel symbols. | |
96 | ||
97 | -U:: | |
98 | --hide_user_symbols:: | |
99 | Hide user symbols. | |
100 | ||
101 | --demangle-kernel:: | |
102 | Demangle kernel symbols. | |
103 | ||
104 | -D:: | |
105 | --dump-symtab:: | |
106 | Dump the symbol table used for profiling. | |
107 | ||
108 | -v:: | |
109 | --verbose:: | |
110 | Be more verbose (show counter open errors, etc). | |
111 | ||
112 | -z:: | |
113 | --zero:: | |
114 | Zero history across display updates. | |
115 | ||
116 | -s:: | |
117 | --sort:: | |
118 | Sort by key(s): pid, comm, dso, symbol, parent, srcline, weight, | |
119 | local_weight, abort, in_tx, transaction, overhead, sample, period. | |
120 | Please see description of --sort in the perf-report man page. | |
121 | ||
122 | --fields=:: | |
123 | Specify output field - multiple keys can be specified in CSV format. | |
124 | Following fields are available: | |
125 | overhead, overhead_sys, overhead_us, overhead_children, sample and period. | |
126 | Also it can contain any sort key(s). | |
127 | ||
128 | By default, every sort keys not specified in --field will be appended | |
129 | automatically. | |
130 | ||
131 | -n:: | |
132 | --show-nr-samples:: | |
133 | Show a column with the number of samples. | |
134 | ||
135 | --show-total-period:: | |
136 | Show a column with the sum of periods. | |
137 | ||
138 | --dsos:: | |
139 | Only consider symbols in these dsos. This option will affect the | |
140 | percentage of the overhead column. See --percentage for more info. | |
141 | ||
142 | --comms:: | |
143 | Only consider symbols in these comms. This option will affect the | |
144 | percentage of the overhead column. See --percentage for more info. | |
145 | ||
146 | --symbols:: | |
147 | Only consider these symbols. This option will affect the | |
148 | percentage of the overhead column. See --percentage for more info. | |
149 | ||
150 | -M:: | |
151 | --disassembler-style=:: Set disassembler style for objdump. | |
152 | ||
153 | --source:: | |
154 | Interleave source code with assembly code. Enabled by default, | |
155 | disable with --no-source. | |
156 | ||
157 | --asm-raw:: | |
158 | Show raw instruction encoding of assembly instructions. | |
159 | ||
160 | -g:: | |
161 | Enables call-graph (stack chain/backtrace) recording. | |
162 | ||
163 | --call-graph [mode,type,min[,limit],order[,key][,branch]]:: | |
164 | Setup and enable call-graph (stack chain/backtrace) recording, | |
165 | implies -g. See `--call-graph` section in perf-record and | |
166 | perf-report man pages for details. | |
167 | ||
168 | --children:: | |
169 | Accumulate callchain of children to parent entry so that then can | |
170 | show up in the output. The output will have a new "Children" column | |
171 | and will be sorted on the data. It requires -g/--call-graph option | |
172 | enabled. See the `overhead calculation' section for more details. | |
173 | Enabled by default, disable with --no-children. | |
174 | ||
175 | --max-stack:: | |
176 | Set the stack depth limit when parsing the callchain, anything | |
177 | beyond the specified depth will be ignored. This is a trade-off | |
178 | between information loss and faster processing especially for | |
179 | workloads that can have a very long callchain stack. | |
180 | ||
181 | Default: /proc/sys/kernel/perf_event_max_stack when present, 127 otherwise. | |
182 | ||
183 | --ignore-callees=<regex>:: | |
184 | Ignore callees of the function(s) matching the given regex. | |
185 | This has the effect of collecting the callers of each such | |
186 | function into one place in the call-graph tree. | |
187 | ||
188 | --percent-limit:: | |
189 | Do not show entries which have an overhead under that percent. | |
190 | (Default: 0). | |
191 | ||
192 | --percentage:: | |
193 | Determine how to display the overhead percentage of filtered entries. | |
194 | Filters can be applied by --comms, --dsos and/or --symbols options and | |
195 | Zoom operations on the TUI (thread, dso, etc). | |
196 | ||
197 | "relative" means it's relative to filtered entries only so that the | |
198 | sum of shown entries will be always 100%. "absolute" means it retains | |
199 | the original value before and after the filter is applied. | |
200 | ||
201 | -w:: | |
202 | --column-widths=<width[,width...]>:: | |
203 | Force each column width to the provided list, for large terminal | |
204 | readability. 0 means no limit (default behavior). | |
205 | ||
206 | --proc-map-timeout:: | |
207 | When processing pre-existing threads /proc/XXX/mmap, it may take | |
208 | a long time, because the file may be huge. A time out is needed | |
209 | in such cases. | |
210 | This option sets the time out limit. The default value is 500 ms. | |
211 | ||
212 | ||
213 | -b:: | |
214 | --branch-any:: | |
215 | Enable taken branch stack sampling. Any type of taken branch may be sampled. | |
216 | This is a shortcut for --branch-filter any. See --branch-filter for more infos. | |
217 | ||
218 | -j:: | |
219 | --branch-filter:: | |
220 | Enable taken branch stack sampling. Each sample captures a series of consecutive | |
221 | taken branches. The number of branches captured with each sample depends on the | |
222 | underlying hardware, the type of branches of interest, and the executed code. | |
223 | It is possible to select the types of branches captured by enabling filters. | |
224 | For a full list of modifiers please see the perf record manpage. | |
225 | ||
226 | The option requires at least one branch type among any, any_call, any_ret, ind_call, cond. | |
227 | The privilege levels may be omitted, in which case, the privilege levels of the associated | |
228 | event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege | |
229 | levels are subject to permissions. When sampling on multiple events, branch stack sampling | |
230 | is enabled for all the sampling events. The sampled branch type is the same for all events. | |
231 | The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k | |
232 | Note that this feature may not be available on all processors. | |
233 | ||
234 | --raw-trace:: | |
235 | When displaying traceevent output, do not use print fmt or plugins. | |
236 | ||
237 | --hierarchy:: | |
238 | Enable hierarchy output. | |
239 | ||
240 | INTERACTIVE PROMPTING KEYS | |
241 | -------------------------- | |
242 | ||
243 | [d]:: | |
244 | Display refresh delay. | |
245 | ||
246 | [e]:: | |
247 | Number of entries to display. | |
248 | ||
249 | [E]:: | |
250 | Event to display when multiple counters are active. | |
251 | ||
252 | [f]:: | |
253 | Profile display filter (>= hit count). | |
254 | ||
255 | [F]:: | |
256 | Annotation display filter (>= % of total). | |
257 | ||
258 | [s]:: | |
259 | Annotate symbol. | |
260 | ||
261 | [S]:: | |
262 | Stop annotation, return to full profile display. | |
263 | ||
264 | [z]:: | |
265 | Toggle event count zeroing across display updates. | |
266 | ||
267 | [qQ]:: | |
268 | Quit. | |
269 | ||
270 | Pressing any unmapped key displays a menu, and prompts for input. | |
271 | ||
272 | include::callchain-overhead-calculation.txt[] | |
273 | ||
274 | SEE ALSO | |
275 | -------- | |
276 | linkperf:perf-stat[1], linkperf:perf-list[1], linkperf:perf-report[1] |