]>
Commit | Line | Data |
---|---|---|
e33e0a43 | 1 | perf-record(1) |
c1c2365a | 2 | ============== |
e33e0a43 IM |
3 | |
4 | NAME | |
5 | ---- | |
23ac9cbe | 6 | perf-record - Run a command and record its profile into perf.data |
e33e0a43 IM |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | 'perf record' [-e <EVENT> | --event=EVENT] [-l] [-a] <command> | |
9e096753 | 12 | 'perf record' [-e <EVENT> | --event=EVENT] [-l] [-a] -- <command> [<options>] |
e33e0a43 IM |
13 | |
14 | DESCRIPTION | |
15 | ----------- | |
16 | This command runs a command and gathers a performance counter profile | |
23ac9cbe | 17 | from it, into perf.data - without displaying anything. |
e33e0a43 IM |
18 | |
19 | This file can then be inspected later on, using 'perf report'. | |
20 | ||
21 | ||
22 | OPTIONS | |
23 | ------- | |
24 | <command>...:: | |
25 | Any command you can specify in a shell. | |
26 | ||
27 | -e:: | |
28 | --event=:: | |
1b290d67 | 29 | Select the PMU event. Selection can be: |
e33e0a43 | 30 | |
1b290d67 FW |
31 | - a symbolic event name (use 'perf list' to list all events) |
32 | ||
33 | - a raw PMU event (eventsel+umask) in the form of rNNN where NNN is a | |
34 | hexadecimal event descriptor. | |
35 | ||
f9ab9c19 CS |
36 | - a symbolically formed PMU event like 'pmu/param1=0x3,param2/' where |
37 | 'param1', 'param2', etc are defined as formats for the PMU in | |
38 | /sys/bus/event_sources/devices/<pmu>/format/*. | |
39 | ||
40 | - a symbolically formed event like 'pmu/config=M,config1=N,config3=K/' | |
41 | ||
42 | where M, N, K are numbers (in decimal, hex, octal format). Acceptable | |
43 | values for each of 'config', 'config1' and 'config2' are defined by | |
44 | corresponding entries in /sys/bus/event_sources/devices/<pmu>/format/* | |
45 | param1 and param2 are defined as formats for the PMU in: | |
46 | /sys/bus/event_sources/devices/<pmu>/format/* | |
47 | ||
3d5d68aa | 48 | There are also some params which are not defined in .../<pmu>/format/*. |
ee4c7588 | 49 | These params can be used to overload default config values per event. |
3d5d68aa KL |
50 | Here is a list of the params. |
51 | - 'period': Set event sampling period | |
09af2a55 | 52 | - 'freq': Set event sampling frequency |
32067712 KL |
53 | - 'time': Disable/enable time stamping. Acceptable values are 1 for |
54 | enabling time stamping. 0 for disabling time stamping. | |
55 | The default is 1. | |
d457c963 | 56 | - 'call-graph': Disable/enable callgraph. Acceptable str are "fp" for |
f9db0d0f KL |
57 | FP mode, "dwarf" for DWARF mode, "lbr" for LBR mode and |
58 | "no" for disable callgraph. | |
d457c963 | 59 | - 'stack-size': user stack size for dwarf mode |
3d5d68aa KL |
60 | Note: If user explicitly sets options which conflict with the params, |
61 | the value set by the params will be overridden. | |
62 | ||
3741eb9f | 63 | - a hardware breakpoint event in the form of '\mem:addr[/len][:access]' |
1b290d67 FW |
64 | where addr is the address in memory you want to break in. |
65 | Access is the memory access type (read, write, execute) it can | |
3741eb9f JS |
66 | be passed as follows: '\mem:addr[:[r][w][x]]'. len is the range, |
67 | number of bytes from specified addr, which the breakpoint will cover. | |
1b290d67 FW |
68 | If you want to profile read-write accesses in 0x1000, just set |
69 | 'mem:0x1000:rw'. | |
3741eb9f JS |
70 | If you want to profile write accesses in [0x1000~1008), just set |
71 | 'mem:0x1000/8:w'. | |
08dbd7e3 | 72 | |
9a75606c NK |
73 | - a group of events surrounded by a pair of brace ("{event1,event2,...}"). |
74 | Each event is separated by commas and the group should be quoted to | |
75 | prevent the shell interpretation. You also need to use --group on | |
76 | "perf report" to view group events together. | |
77 | ||
08dbd7e3 | 78 | --filter=<filter>:: |
4ba1faa1 WN |
79 | Event filter. This option should follow a event selector (-e) which |
80 | selects tracepoint event(s). Multiple '--filter' options are combined | |
81 | using '&&'. | |
82 | ||
83 | --exclude-perf:: | |
84 | Don't record events issued by perf itself. This option should follow | |
85 | a event selector (-e) which selects tracepoint event(s). It adds a | |
86 | filter expression 'common_pid != $PERFPID' to filters. If other | |
87 | '--filter' exists, the new filter expression will be combined with | |
88 | them by '&&'. | |
08dbd7e3 | 89 | |
e33e0a43 | 90 | -a:: |
08dbd7e3 SB |
91 | --all-cpus:: |
92 | System-wide collection from all CPUs. | |
e33e0a43 | 93 | |
386c0b70 ACM |
94 | -p:: |
95 | --pid=:: | |
b52956c9 | 96 | Record events on existing process ID (comma separated list). |
08dbd7e3 SB |
97 | |
98 | -t:: | |
99 | --tid=:: | |
b52956c9 | 100 | Record events on existing thread ID (comma separated list). |
69e7e5b0 AH |
101 | This option also disables inheritance by default. Enable it by adding |
102 | --inherit. | |
386c0b70 | 103 | |
0d37aa34 ACM |
104 | -u:: |
105 | --uid=:: | |
106 | Record events in threads owned by uid. Name or number. | |
107 | ||
386c0b70 ACM |
108 | -r:: |
109 | --realtime=:: | |
110 | Collect data with this RT SCHED_FIFO priority. | |
563aecb2 | 111 | |
509051ea | 112 | --no-buffering:: |
acac03fa | 113 | Collect data without buffering. |
386c0b70 | 114 | |
386c0b70 ACM |
115 | -c:: |
116 | --count=:: | |
117 | Event period to sample. | |
118 | ||
119 | -o:: | |
120 | --output=:: | |
121 | Output file name. | |
122 | ||
123 | -i:: | |
2e6cdf99 SE |
124 | --no-inherit:: |
125 | Child tasks do not inherit counters. | |
386c0b70 ACM |
126 | -F:: |
127 | --freq=:: | |
128 | Profile at this frequency. | |
129 | ||
130 | -m:: | |
131 | --mmap-pages=:: | |
27050f53 JO |
132 | Number of mmap data pages (must be a power of two) or size |
133 | specification with appended unit character - B/K/M/G. The | |
134 | size is rounded up to have nearest pages power of two value. | |
e9db1310 AH |
135 | Also, by adding a comma, the number of mmap pages for AUX |
136 | area tracing can be specified. | |
386c0b70 | 137 | |
9a75606c NK |
138 | --group:: |
139 | Put all events in a single event group. This precedes the --event | |
140 | option and remains only for backward compatibility. See --event. | |
141 | ||
386c0b70 | 142 | -g:: |
09b0fd45 JO |
143 | Enables call-graph (stack chain/backtrace) recording. |
144 | ||
386c0b70 | 145 | --call-graph:: |
09b0fd45 | 146 | Setup and enable call-graph (stack chain/backtrace) recording, |
76a26549 | 147 | implies -g. Default is "fp". |
09b0fd45 JO |
148 | |
149 | Allows specifying "fp" (frame pointer) or "dwarf" | |
aad2b21c KL |
150 | (DWARF's CFI - Call Frame Information) or "lbr" |
151 | (Hardware Last Branch Record facility) as the method to collect | |
09b0fd45 JO |
152 | the information used to show the call graphs. |
153 | ||
154 | In some systems, where binaries are build with gcc | |
155 | --fomit-frame-pointer, using the "fp" method will produce bogus | |
156 | call graphs, using "dwarf", if available (perf tools linked to | |
76a26549 | 157 | the libunwind or libdw library) should be used instead. |
aad2b21c KL |
158 | Using the "lbr" method doesn't require any compiler options. It |
159 | will produce call graphs from the hardware LBR registers. The | |
160 | main limition is that it is only available on new Intel | |
161 | platforms, such as Haswell. It can only get user call chain. It | |
162 | doesn't work with branch stack sampling at the same time. | |
386c0b70 | 163 | |
76a26549 NK |
164 | When "dwarf" recording is used, perf also records (user) stack dump |
165 | when sampled. Default size of the stack dump is 8192 (bytes). | |
166 | User can change the size by passing the size after comma like | |
167 | "--call-graph dwarf,4096". | |
168 | ||
b44308f5 ACM |
169 | -q:: |
170 | --quiet:: | |
171 | Don't print any message, useful for scripting. | |
172 | ||
386c0b70 ACM |
173 | -v:: |
174 | --verbose:: | |
175 | Be more verbose (show counter open errors, etc). | |
176 | ||
177 | -s:: | |
178 | --stat:: | |
1f91d5fd NK |
179 | Record per-thread event counts. Use it with 'perf report -T' to see |
180 | the values. | |
386c0b70 ACM |
181 | |
182 | -d:: | |
183 | --data:: | |
56100321 | 184 | Record the sample addresses. |
386c0b70 | 185 | |
9c90a61c ACM |
186 | -T:: |
187 | --timestamp:: | |
56100321 PZ |
188 | Record the sample timestamps. Use it with 'perf report -D' to see the |
189 | timestamps, for instance. | |
190 | ||
191 | -P:: | |
192 | --period:: | |
193 | Record the sample period. | |
9c90a61c | 194 | |
386c0b70 ACM |
195 | -n:: |
196 | --no-samples:: | |
197 | Don't sample. | |
e33e0a43 | 198 | |
ec7ba4ea FW |
199 | -R:: |
200 | --raw-samples:: | |
bdef3b02 | 201 | Collect raw sample records from all opened counters (default for tracepoint counters). |
ec7ba4ea | 202 | |
c45c6ea2 SE |
203 | -C:: |
204 | --cpu:: | |
08dbd7e3 SB |
205 | Collect samples only on the list of CPUs provided. Multiple CPUs can be provided as a |
206 | comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2. | |
c45c6ea2 SE |
207 | In per-thread mode with inheritance mode on (default), samples are captured only when |
208 | the thread executes on the designated CPUs. Default is to monitor all CPUs. | |
209 | ||
7a29c087 NK |
210 | -B:: |
211 | --no-buildid:: | |
212 | Do not save the build ids of binaries in the perf.data files. This skips | |
213 | post processing after recording, which sometimes makes the final step in | |
214 | the recording process to take a long time, as it needs to process all | |
215 | events looking for mmap records. The downside is that it can misresolve | |
216 | symbols if the workload binaries used when recording get locally rebuilt | |
217 | or upgraded, because the only key available in this case is the | |
218 | pathname. You can also set the "record.build-id" config variable to | |
219 | 'skip to have this behaviour permanently. | |
220 | ||
a1ac1d3c SE |
221 | -N:: |
222 | --no-buildid-cache:: | |
96355f2c | 223 | Do not update the buildid cache. This saves some overhead in situations |
a1ac1d3c | 224 | where the information in the perf.data file (which includes buildids) |
7a29c087 NK |
225 | is sufficient. You can also set the "record.build-id" config variable to |
226 | 'no-cache' to have the same effect. | |
a1ac1d3c | 227 | |
023695d9 SE |
228 | -G name,...:: |
229 | --cgroup name,...:: | |
230 | monitor only in the container (cgroup) called "name". This option is available only | |
231 | in per-cpu mode. The cgroup filesystem must be mounted. All threads belonging to | |
232 | container "name" are monitored when they run on the monitored CPUs. Multiple cgroups | |
233 | can be provided. Each cgroup is applied to the corresponding event, i.e., first cgroup | |
234 | to first event, second cgroup to second event and so on. It is possible to provide | |
235 | an empty cgroup (monitor all the time) using, e.g., -G foo,,bar. Cgroups must have | |
236 | corresponding events, i.e., they always refer to events defined earlier on the command | |
237 | line. | |
238 | ||
bdfebd84 | 239 | -b:: |
a5aabdac SE |
240 | --branch-any:: |
241 | Enable taken branch stack sampling. Any type of taken branch may be sampled. | |
242 | This is a shortcut for --branch-filter any. See --branch-filter for more infos. | |
243 | ||
244 | -j:: | |
245 | --branch-filter:: | |
bdfebd84 RAV |
246 | Enable taken branch stack sampling. Each sample captures a series of consecutive |
247 | taken branches. The number of branches captured with each sample depends on the | |
248 | underlying hardware, the type of branches of interest, and the executed code. | |
249 | It is possible to select the types of branches captured by enabling filters. The | |
250 | following filters are defined: | |
251 | ||
a5aabdac | 252 | - any: any type of branches |
bdfebd84 RAV |
253 | - any_call: any function call or system call |
254 | - any_ret: any function return or system call return | |
2e49a948 | 255 | - ind_call: any indirect branch |
43e41adc | 256 | - call: direct calls, including far (to/from kernel) calls |
bdfebd84 RAV |
257 | - u: only when the branch target is at the user level |
258 | - k: only when the branch target is in the kernel | |
259 | - hv: only when the target is at the hypervisor level | |
0126d493 AK |
260 | - in_tx: only when the target is in a hardware transaction |
261 | - no_tx: only when the target is not in a hardware transaction | |
262 | - abort_tx: only when the target is a hardware transaction abort | |
3e39db4a | 263 | - cond: conditional branches |
bdfebd84 RAV |
264 | |
265 | + | |
3e39db4a | 266 | The option requires at least one branch type among any, any_call, any_ret, ind_call, cond. |
9c768207 | 267 | The privilege levels may be omitted, in which case, the privilege levels of the associated |
a5aabdac SE |
268 | event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege |
269 | levels are subject to permissions. When sampling on multiple events, branch stack sampling | |
270 | is enabled for all the sampling events. The sampled branch type is the same for all events. | |
271 | The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k | |
272 | Note that this feature may not be available on all processors. | |
bdfebd84 | 273 | |
05484298 AK |
274 | --weight:: |
275 | Enable weightened sampling. An additional weight is recorded per sample and can be | |
276 | displayed with the weight and local_weight sort keys. This currently works for TSX | |
277 | abort events and some memory events in precise mode on modern Intel CPUs. | |
278 | ||
475eeab9 AK |
279 | --transaction:: |
280 | Record transaction flags for transaction related events. | |
281 | ||
3aa5939d AH |
282 | --per-thread:: |
283 | Use per-thread mmaps. By default per-cpu mmaps are created. This option | |
284 | overrides that and uses per-thread mmaps. A side-effect of that is that | |
285 | inheritance is automatically disabled. --per-thread is ignored with a warning | |
286 | if combined with -a or -C options. | |
539e6bb7 | 287 | |
a6205a35 ACM |
288 | -D:: |
289 | --delay=:: | |
6619a53e AK |
290 | After starting the program, wait msecs before measuring. This is useful to |
291 | filter out the startup phase of the program, which is often very different. | |
292 | ||
4b6c5177 SE |
293 | -I:: |
294 | --intr-regs:: | |
295 | Capture machine state (registers) at interrupt, i.e., on counter overflows for | |
296 | each sample. List of captured registers depends on the architecture. This option | |
bcc84ec6 SE |
297 | is off by default. It is possible to select the registers to sample using their |
298 | symbolic names, e.g. on x86, ax, si. To list the available registers use | |
299 | --intr-regs=\?. To name registers, pass a comma separated list such as | |
300 | --intr-regs=ax,bx. The list of register is architecture dependent. | |
301 | ||
4b6c5177 | 302 | |
85c273d2 AK |
303 | --running-time:: |
304 | Record running and enabled time for read events (:S) | |
305 | ||
814c8c38 PZ |
306 | -k:: |
307 | --clockid:: | |
308 | Sets the clock id to use for the various time fields in the perf_event_type | |
309 | records. See clock_gettime(). In particular CLOCK_MONOTONIC and | |
310 | CLOCK_MONOTONIC_RAW are supported, some events might also allow | |
311 | CLOCK_BOOTTIME, CLOCK_REALTIME and CLOCK_TAI. | |
312 | ||
2dd6d8a1 AH |
313 | -S:: |
314 | --snapshot:: | |
315 | Select AUX area tracing Snapshot Mode. This option is valid only with an | |
316 | AUX area tracing event. Optionally the number of bytes to capture per | |
317 | snapshot can be specified. In Snapshot Mode, trace data is captured only when | |
318 | signal SIGUSR2 is received. | |
319 | ||
9d9cad76 KL |
320 | --proc-map-timeout:: |
321 | When processing pre-existing threads /proc/XXX/mmap, it may take a long time, | |
322 | because the file may be huge. A time out is needed in such cases. | |
323 | This option sets the time out limit. The default value is 500 ms. | |
324 | ||
b757bb09 AH |
325 | --switch-events:: |
326 | Record context switch events i.e. events of type PERF_RECORD_SWITCH or | |
327 | PERF_RECORD_SWITCH_CPU_WIDE. | |
328 | ||
7efe0e03 | 329 | --clang-path=PATH:: |
71dc2326 | 330 | Path to clang binary to use for compiling BPF scriptlets. |
7efe0e03 | 331 | (enabled when BPF support is on) |
71dc2326 | 332 | |
7efe0e03 | 333 | --clang-opt=OPTIONS:: |
71dc2326 | 334 | Options passed to clang when compiling BPF scriptlets. |
7efe0e03 HK |
335 | (enabled when BPF support is on) |
336 | ||
337 | --vmlinux=PATH:: | |
338 | Specify vmlinux path which has debuginfo. | |
339 | (enabled when BPF prologue is on) | |
71dc2326 | 340 | |
6156681b NK |
341 | --buildid-all:: |
342 | Record build-id of all DSOs regardless whether it's actually hit or not. | |
343 | ||
85723885 JO |
344 | --all-kernel:: |
345 | Configure all used events to run in kernel space. | |
346 | ||
347 | --all-user:: | |
348 | Configure all used events to run in user space. | |
349 | ||
eca857ab WN |
350 | --timestamp-filename |
351 | Append timestamp to output file name. | |
352 | ||
3c1cb7e3 WN |
353 | --switch-output:: |
354 | Generate multiple perf.data files, timestamp prefixed, switching to a new one | |
355 | when receiving a SIGUSR2. | |
356 | ||
357 | A possible use case is to, given an external event, slice the perf.data file | |
358 | that gets then processed, possibly via a perf script, to decide if that | |
359 | particular perf.data snapshot should be kept or not. | |
360 | ||
0c1d46a8 | 361 | Implies --timestamp-filename, --no-buildid and --no-buildid-cache. |
eca857ab | 362 | |
0aab2136 WN |
363 | --dry-run:: |
364 | Parse options then exit. --dry-run can be used to detect errors in cmdline | |
365 | options. | |
366 | ||
367 | 'perf record --dry-run -e' can act as a BPF script compiler if llvm.dump-obj | |
368 | in config file is set to true. | |
369 | ||
4ea648ae WN |
370 | --tail-synthesize:: |
371 | Instead of collecting non-sample events (for example, fork, comm, mmap) at | |
372 | the beginning of record, collect them during finalizing an output file. | |
373 | The collected non-sample events reflects the status of the system when | |
374 | record is finished. | |
375 | ||
626a6b78 WN |
376 | --overwrite:: |
377 | Makes all events use an overwritable ring buffer. An overwritable ring | |
378 | buffer works like a flight recorder: when it gets full, the kernel will | |
379 | overwrite the oldest records, that thus will never make it to the | |
380 | perf.data file. | |
381 | ||
382 | When '--overwrite' and '--switch-output' are used perf records and drops | |
383 | events until it receives a signal, meaning that something unusual was | |
384 | detected that warrants taking a snapshot of the most current events, | |
385 | those fitting in the ring buffer at that moment. | |
386 | ||
387 | 'overwrite' attribute can also be set or canceled for an event using | |
388 | config terms. For example: 'cycles/overwrite/' and 'instructions/no-overwrite/'. | |
389 | ||
4ea648ae WN |
390 | Implies --tail-synthesize. |
391 | ||
e33e0a43 IM |
392 | SEE ALSO |
393 | -------- | |
386b05e3 | 394 | linkperf:perf-stat[1], linkperf:perf-list[1] |