1PERF-RECORD(1) perf Manual PERF-RECORD(1)
2
6 perf-record - Run a command and record its profile into perf.data
7
9 perf record [-e <EVENT> | --event=EVENT] [-a] <command>
10 perf record [-e <EVENT> | --event=EVENT] [-a] — <command> [<options>]
11
13 This command runs a command and gathers a performance counter profile
14 from it, into perf.data - without displaying anything.
15 This file can then be inspected later on, using perf report.
17
19 <command>...
20 Any command you can specify in a shell.
21 -e, --event=
23 Select the PMU event. Selection can be:
24 · a symbolic event name (use perf list to list all events)
26 · a raw PMU event (eventsel+umask) in the form of rNNN where NNN
28 is a hexadecimal event descriptor.
29 · a symbolically formed PMU event like pmu/param1=0x3,param2/
31 where param1, param2, etc are defined as formats for the PMU in
32 /sys/bus/event_source/devices/<pmu>/format/*.
33 · a symbolically formed event like
35 pmu/config=M,config1=N,config3=K/
36 where M, N, K are numbers (in decimal, hex, octal format). Acceptable
38 values for each of 'config', 'config1' and 'config2' are defined by
39 corresponding entries in /sys/bus/event_source/devices/<pmu>/format/*
40 param1 and param2 are defined as formats for the PMU in:
41 /sys/bus/event_source/devices/<pmu>/format/*
42 There are also some parameters which are not defined in .../<pmu>/format/*.
44 These params can be used to overload default config values per event.
45 Here are some common parameters:
46 - 'period': Set event sampling period
47 - 'freq': Set event sampling frequency
48 - 'time': Disable/enable time stamping. Acceptable values are 1 for
49 enabling time stamping. 0 for disabling time stamping.
50 The default is 1.
51 - 'call-graph': Disable/enable callgraph. Acceptable str are "fp" for
52 FP mode, "dwarf" for DWARF mode, "lbr" for LBR mode and
53 "no" for disable callgraph.
54 - 'stack-size': user stack size for dwarf mode
55 See the linkperf:perf-list[1] man page for more parameters.
57 Note: If user explicitly sets options which conflict with the params,
59 the value set by the parameters will be overridden.
60 Also not defined in .../<pmu>/format/* are PMU driver specific
62 configuration parameters. Any configuration parameter preceded by
63 the letter '@' is not interpreted in user space and sent down directly
64 to the PMU driver. For example:
65 perf record -e some_event/@cfg1,@cfg2=config/ ...
67 will see 'cfg1' and 'cfg2=config' pushed to the PMU driver associated
69 with the event for further processing. There is no restriction on
70 what the configuration parameters are, as long as their semantic is
71 understood and supported by the PMU driver.
72 · a hardware breakpoint event in the form of
74 \mem:addr[/len][:access] where addr is the address in memory
75 you want to break in. Access is the memory access type (read,
76 write, execute) it can be passed as follows:
77 \mem:addr[:[r][w][x]]. len is the range, number of bytes from
78 specified addr, which the breakpoint will cover. If you want to
79 profile read-write accesses in 0x1000, just set mem:0x1000:rw.
80 If you want to profile write accesses in [0x1000~1008), just
81 set mem:0x1000/8:w.
82 · a group of events surrounded by a pair of brace
84 ("{event1,event2,...}"). Each event is separated by commas and
85 the group should be quoted to prevent the shell interpretation.
86 You also need to use --group on "perf report" to view group
87 events together.
88 --filter=<filter>
90 Event filter. This option should follow a event selector (-e) which
91 selects either tracepoint event(s) or a hardware trace PMU (e.g.
92 Intel PT or CoreSight).
93 · tracepoint filters
95 In the case of tracepoints, multiple '--filter' options are combined
97 using '&&'.
98 · address filters
100 A hardware trace PMU advertises its ability to accept a number of
102 address filters by specifying a non-zero value in
103 /sys/bus/event_source/devices/<pmu>/nr_addr_filters.
104 Address filters have the format:
106 filter|start|stop|tracestop <start> [/ <size>] [@<file name>]
108 Where:
110 - 'filter': defines a region that will be traced.
111 - 'start': defines an address at which tracing will begin.
112 - 'stop': defines an address at which tracing will stop.
113 - 'tracestop': defines a region in which tracing will stop.
114 <file name> is the name of the object file, <start> is the offset to the
116 code to trace in that file, and <size> is the size of the region to
117 trace. 'start' and 'stop' filters need not specify a <size>.
118 If no object file is specified then the kernel is assumed, in which case
120 the start address must be a current kernel memory address.
121 <start> can also be specified by providing the name of a symbol. If the
123 symbol name is not unique, it can be disambiguated by inserting #n where
124 'n' selects the n'th symbol in address order. Alternately #0, #g or #G
125 select only a global symbol. <size> can also be specified by providing
126 the name of a symbol, in which case the size is calculated to the end
127 of that symbol. For 'filter' and 'tracestop' filters, if <size> is
128 omitted and <start> is a symbol, then the size is calculated to the end
129 of that symbol.
130 If <size> is omitted and <start> is '*', then the start and size will
132 be calculated from the first and last symbols, i.e. to trace the whole
133 file.
134 If symbol names (or '*') are provided, they must be surrounded by white
136 space.
137 The filter passed to the kernel is not necessarily the same as entered.
139 To see the filter that is passed, use the -v option.
140 The kernel may not be able to configure a trace region if it is not
142 within a single mapping. MMAP events (or /proc/<pid>/maps) can be
143 examined to determine if that is a possibility.
144 Multiple filters can be separated with space or comma.
146 --exclude-perf
148 Don’t record events issued by perf itself. This option should
149 follow a event selector (-e) which selects tracepoint event(s). It
150 adds a filter expression common_pid != $PERFPID to filters. If
151 other --filter exists, the new filter expression will be combined
152 with them by &&.
153 -a, --all-cpus
155 System-wide collection from all CPUs (default if no target is
156 specified).
157 -p, --pid=
159 Record events on existing process ID (comma separated list).
160 -t, --tid=
162 Record events on existing thread ID (comma separated list). This
163 option also disables inheritance by default. Enable it by adding
164 --inherit.
165 -u, --uid=
167 Record events in threads owned by uid. Name or number.
168 -r, --realtime=
170 Collect data with this RT SCHED_FIFO priority.
171 --no-buffering
173 Collect data without buffering.
174 -c, --count=
176 Event period to sample.
177 -o, --output=
179 Output file name.
180 -i, --no-inherit
182 Child tasks do not inherit counters.
183 -F, --freq=
185 Profile at this frequency.
186 -m, --mmap-pages=
188 Number of mmap data pages (must be a power of two) or size
189 specification with appended unit character - B/K/M/G. The size is
190 rounded up to have nearest pages power of two value. Also, by
191 adding a comma, the number of mmap pages for AUX area tracing can
192 be specified.
193 --group
195 Put all events in a single event group. This precedes the --event
196 option and remains only for backward compatibility. See --event.
197 -g
199 Enables call-graph (stack chain/backtrace) recording.
200 --call-graph
202 Setup and enable call-graph (stack chain/backtrace) recording,
203 implies -g. Default is "fp".
204 Allows specifying "fp" (frame pointer) or "dwarf"
206 (DWARF's CFI - Call Frame Information) or "lbr"
207 (Hardware Last Branch Record facility) as the method to collect
208 the information used to show the call graphs.
209 In some systems, where binaries are build with gcc
211 --fomit-frame-pointer, using the "fp" method will produce bogus
212 call graphs, using "dwarf", if available (perf tools linked to
213 the libunwind or libdw library) should be used instead.
214 Using the "lbr" method doesn't require any compiler options. It
215 will produce call graphs from the hardware LBR registers. The
216 main limitation is that it is only available on new Intel
217 platforms, such as Haswell. It can only get user call chain. It
218 doesn't work with branch stack sampling at the same time.
219 When "dwarf" recording is used, perf also records (user) stack dump
221 when sampled. Default size of the stack dump is 8192 (bytes).
222 User can change the size by passing the size after comma like
223 "--call-graph dwarf,4096".
224 -q, --quiet
226 Don’t print any message, useful for scripting.
227 -v, --verbose
229 Be more verbose (show counter open errors, etc).
230 -s, --stat
232 Record per-thread event counts. Use it with perf report -T to see
233 the values.
234 -d, --data
236 Record the sample virtual addresses.
237 --phys-data
239 Record the sample physical addresses.
240 -T, --timestamp
242 Record the sample timestamps. Use it with perf report -D to see the
243 timestamps, for instance.
244 -P, --period
246 Record the sample period.
247 --sample-cpu
249 Record the sample cpu.
250 -n, --no-samples
252 Don’t sample.
253 -R, --raw-samples
255 Collect raw sample records from all opened counters (default for
256 tracepoint counters).
257 -C, --cpu
259 Collect samples only on the list of CPUs provided. Multiple CPUs
260 can be provided as a comma-separated list with no space: 0,1.
261 Ranges of CPUs are specified with -: 0-2. In per-thread mode with
262 inheritance mode on (default), samples are captured only when the
263 thread executes on the designated CPUs. Default is to monitor all
264 CPUs.
265 -B, --no-buildid
267 Do not save the build ids of binaries in the perf.data files. This
268 skips post processing after recording, which sometimes makes the
269 final step in the recording process to take a long time, as it
270 needs to process all events looking for mmap records. The downside
271 is that it can misresolve symbols if the workload binaries used
272 when recording get locally rebuilt or upgraded, because the only
273 key available in this case is the pathname. You can also set the
274 "record.build-id" config variable to 'skip to have this behaviour
275 permanently.
276 -N, --no-buildid-cache
278 Do not update the buildid cache. This saves some overhead in
279 situations where the information in the perf.data file (which
280 includes buildids) is sufficient. You can also set the
281 "record.build-id" config variable to no-cache to have the same
282 effect.
283 -G name,..., --cgroup name,...
285 monitor only in the container (cgroup) called "name". This option
286 is available only in per-cpu mode. The cgroup filesystem must be
287 mounted. All threads belonging to container "name" are monitored
288 when they run on the monitored CPUs. Multiple cgroups can be
289 provided. Each cgroup is applied to the corresponding event, i.e.,
290 first cgroup to first event, second cgroup to second event and so
291 on. It is possible to provide an empty cgroup (monitor all the
292 time) using, e.g., -G foo,,bar. Cgroups must have corresponding
293 events, i.e., they always refer to events defined earlier on the
294 command line.
295 -b, --branch-any
297 Enable taken branch stack sampling. Any type of taken branch may be
298 sampled. This is a shortcut for --branch-filter any. See
299 --branch-filter for more infos.
300 -j, --branch-filter
302 Enable taken branch stack sampling. Each sample captures a series
303 of consecutive taken branches. The number of branches captured with
304 each sample depends on the underlying hardware, the type of
305 branches of interest, and the executed code. It is possible to
306 select the types of branches captured by enabling filters. The
307 following filters are defined:
308 · any: any type of branches
310 · any_call: any function call or system call
312 · any_ret: any function return or system call return
314 · ind_call: any indirect branch
316 · call: direct calls, including far (to/from kernel) calls
318 · u: only when the branch target is at the user level
320 · k: only when the branch target is in the kernel
322 · hv: only when the target is at the hypervisor level
324 · in_tx: only when the target is in a hardware transaction
326 · no_tx: only when the target is not in a hardware transaction
328 · abort_tx: only when the target is a hardware transaction abort
330 · cond: conditional branches
332 · save_type: save branch type during sampling in case binary is
334 not available later
335 The option requires at least one branch type among any, any_call,
337 any_ret, ind_call, cond. The privilege levels may be omitted, in
338 which case, the privilege levels of the associated event are
339 applied to the branch filter. Both kernel (k) and hypervisor (hv)
340 privilege levels are subject to permissions. When sampling on
341 multiple events, branch stack sampling is enabled for all the
342 sampling events. The sampled branch type is the same for all
343 events. The various filters must be specified as a comma separated
344 list: --branch-filter any_ret,u,k Note that this feature may not be
345 available on all processors.
346 --weight
348 Enable weightened sampling. An additional weight is recorded per
349 sample and can be displayed with the weight and local_weight sort
350 keys. This currently works for TSX abort events and some memory
351 events in precise mode on modern Intel CPUs.
352 --transaction
354 Record transaction flags for transaction related events.
355 --per-thread
357 Use per-thread mmaps. By default per-cpu mmaps are created. This
358 option overrides that and uses per-thread mmaps. A side-effect of
359 that is that inheritance is automatically disabled. --per-thread is
360 ignored with a warning if combined with -a or -C options.
361 -D, --delay=
363 After starting the program, wait msecs before measuring. This is
364 useful to filter out the startup phase of the program, which is
365 often very different.
366 -I, --intr-regs
368 Capture machine state (registers) at interrupt, i.e., on counter
369 overflows for each sample. List of captured registers depends on
370 the architecture. This option is off by default. It is possible to
371 select the registers to sample using their symbolic names, e.g. on
372 x86, ax, si. To list the available registers use --intr-regs=\?. To
373 name registers, pass a comma separated list such as
374 --intr-regs=ax,bx. The list of register is architecture dependent.
375 --user-regs
377 Capture user registers at sample time. Same arguments as -I.
378 --running-time
380 Record running and enabled time for read events (:S)
381 -k, --clockid
383 Sets the clock id to use for the various time fields in the
384 perf_event_type records. See clock_gettime(). In particular
385 CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW are supported, some events
386 might also allow CLOCK_BOOTTIME, CLOCK_REALTIME and CLOCK_TAI.
387 -S, --snapshot
389 Select AUX area tracing Snapshot Mode. This option is valid only
390 with an AUX area tracing event. Optionally the number of bytes to
391 capture per snapshot can be specified. In Snapshot Mode, trace data
392 is captured only when signal SIGUSR2 is received.
393 --proc-map-timeout
395 When processing pre-existing threads /proc/XXX/mmap, it may take a
396 long time, because the file may be huge. A time out is needed in
397 such cases. This option sets the time out limit. The default value
398 is 500 ms.
399 --switch-events
401 Record context switch events i.e. events of type PERF_RECORD_SWITCH
402 or PERF_RECORD_SWITCH_CPU_WIDE.
403 --buildid-all
405 Record build-id of all DSOs regardless whether it’s actually hit or
406 not.
407 --all-kernel
409 Configure all used events to run in kernel space.
410 --all-user
412 Configure all used events to run in user space.
413 --timestamp-filename Append timestamp to output file name.
415 --switch-output[=mode]
417 Generate multiple perf.data files, timestamp prefixed, switching to
418 a new one based on mode value: "signal" - when receiving a SIGUSR2
419 (default value) or <size> - when reaching the size threshold, size
420 is expected to be a number with appended unit character - B/K/M/G
421 <time> - when reaching the time threshold, size is expected to be a
422 number with appended unit character - s/m/h/d
423 Note: the precision of the size threshold hugely depends
425 on your configuration - the number and size of your ring
426 buffers (-m). It is generally more precise for higher sizes
427 (like >5M), for lower values expect different sizes.
428 A possible use case is to, given an external event, slice the perf.data
430 file that gets then processed, possibly via a perf script, to decide if
431 that particular perf.data snapshot should be kept or not.
432 Implies --timestamp-filename, --no-buildid and --no-buildid-cache. The
434 reason for the latter two is to reduce the data file switching
435 overhead. You can still switch them on with:
436 --switch-output --no-no-buildid --no-no-buildid-cache
438 --dry-run
440 Parse options then exit. --dry-run can be used to detect errors in
441 cmdline options.
442 perf record --dry-run -e can act as a BPF script compiler if
444 llvm.dump-obj in config file is set to true.
445 --tail-synthesize
447 Instead of collecting non-sample events (for example, fork, comm,
448 mmap) at the beginning of record, collect them during finalizing an
449 output file. The collected non-sample events reflects the status of
450 the system when record is finished.
451 --overwrite
453 Makes all events use an overwritable ring buffer. An overwritable
454 ring buffer works like a flight recorder: when it gets full, the
455 kernel will overwrite the oldest records, that thus will never make
456 it to the perf.data file.
457 When --overwrite and --switch-output are used perf records and drops
459 events until it receives a signal, meaning that something unusual was
460 detected that warrants taking a snapshot of the most current events,
461 those fitting in the ring buffer at that moment.
462 overwrite attribute can also be set or canceled for an event using
464 config terms. For example: cycles/overwrite/ and
465 instructions/no-overwrite/.
466 Implies --tail-synthesize.
468
470 perf-stat(1), perf-list(1)
471perf 06/18/2019 PERF-RECORD(1)