1perf-record(1)
2==============
3
4NAME
5----
6perf-record - Run a command and record its profile into perf.data
7
8SYNOPSIS
9--------
10[verse]
11'perf record' [-e <EVENT> | --event=EVENT] [-a] <command>
12'perf record' [-e <EVENT> | --event=EVENT] [-a] -- <command> [<options>]
13
14DESCRIPTION
15-----------
16This command runs a command and gathers a performance counter profile
17from it, into perf.data - without displaying anything.
18
19This file can then be inspected later on, using 'perf report'.
20
21
22OPTIONS
23-------
24<command>...::
25	Any command you can specify in a shell.
26
27-e::
28--event=::
29	Select the PMU event. Selection can be:
30
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
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_source/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_source/devices/<pmu>/format/*
45          param1 and param2 are defined as formats for the PMU in:
46          /sys/bus/event_source/devices/<pmu>/format/*
47
48	  There are also some parameters which are not defined in .../<pmu>/format/*.
49	  These params can be used to overload default config values per event.
50	  Here are some common parameters:
51	  - 'period': Set event sampling period
52	  - 'freq': Set event sampling frequency
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.
56	  - 'call-graph': Disable/enable callgraph. Acceptable str are "fp" for
57			 FP mode, "dwarf" for DWARF mode, "lbr" for LBR mode and
58			 "no" for disable callgraph.
59	  - 'stack-size': user stack size for dwarf mode
60	  - 'name' : User defined event name. Single quotes (') may be used to
61		    escape symbols in the name from parsing by shell and tool
62		    like this: name=\'CPU_CLK_UNHALTED.THREAD:cmask=0x1\'.
63
64          See the linkperf:perf-list[1] man page for more parameters.
65
66	  Note: If user explicitly sets options which conflict with the params,
67	  the value set by the parameters will be overridden.
68
69	  Also not defined in .../<pmu>/format/* are PMU driver specific
70	  configuration parameters.  Any configuration parameter preceded by
71	  the letter '@' is not interpreted in user space and sent down directly
72	  to the PMU driver.  For example:
73
74	  perf record -e some_event/@cfg1,@cfg2=config/ ...
75
76	  will see 'cfg1' and 'cfg2=config' pushed to the PMU driver associated
77	  with the event for further processing.  There is no restriction on
78	  what the configuration parameters are, as long as their semantic is
79	  understood and supported by the PMU driver.
80
81        - a hardware breakpoint event in the form of '\mem:addr[/len][:access]'
82          where addr is the address in memory you want to break in.
83          Access is the memory access type (read, write, execute) it can
84          be passed as follows: '\mem:addr[:[r][w][x]]'. len is the range,
85          number of bytes from specified addr, which the breakpoint will cover.
86          If you want to profile read-write accesses in 0x1000, just set
87          'mem:0x1000:rw'.
88          If you want to profile write accesses in [0x1000~1008), just set
89          'mem:0x1000/8:w'.
90
91        - a BPF source file (ending in .c) or a precompiled object file (ending
92          in .o) selects one or more BPF events.
93          The BPF program can attach to various perf events based on the ELF section
94          names.
95
96          When processing a '.c' file, perf searches an installed LLVM to compile it
97          into an object file first. Optional clang options can be passed via the
98          '--clang-opt' command line option, e.g.:
99
100            perf record --clang-opt "-DLINUX_VERSION_CODE=0x50000" \
101                        -e tests/bpf-script-example.c
102
103          Note: '--clang-opt' must be placed before '--event/-e'.
104
105	- a group of events surrounded by a pair of brace ("{event1,event2,...}").
106	  Each event is separated by commas and the group should be quoted to
107	  prevent the shell interpretation.  You also need to use --group on
108	  "perf report" to view group events together.
109
110--filter=<filter>::
111        Event filter. This option should follow an event selector (-e) which
112	selects either tracepoint event(s) or a hardware trace PMU
113	(e.g. Intel PT or CoreSight).
114
115	- tracepoint filters
116
117	In the case of tracepoints, multiple '--filter' options are combined
118	using '&&'.
119
120	- address filters
121
122	A hardware trace PMU advertises its ability to accept a number of
123	address filters	by specifying a non-zero value in
124	/sys/bus/event_source/devices/<pmu>/nr_addr_filters.
125
126	Address filters have the format:
127
128	filter|start|stop|tracestop <start> [/ <size>] [@<file name>]
129
130	Where:
131	- 'filter': defines a region that will be traced.
132	- 'start': defines an address at which tracing will begin.
133	- 'stop': defines an address at which tracing will stop.
134	- 'tracestop': defines a region in which tracing will stop.
135
136	<file name> is the name of the object file, <start> is the offset to the
137	code to trace in that file, and <size> is the size of the region to
138	trace. 'start' and 'stop' filters need not specify a <size>.
139
140	If no object file is specified then the kernel is assumed, in which case
141	the start address must be a current kernel memory address.
142
143	<start> can also be specified by providing the name of a symbol. If the
144	symbol name is not unique, it can be disambiguated by inserting #n where
145	'n' selects the n'th symbol in address order. Alternately #0, #g or #G
146	select only a global symbol. <size> can also be specified by providing
147	the name of a symbol, in which case the size is calculated to the end
148	of that symbol. For 'filter' and 'tracestop' filters, if <size> is
149	omitted and <start> is a symbol, then the size is calculated to the end
150	of that symbol.
151
152	If <size> is omitted and <start> is '*', then the start and size will
153	be calculated from the first and last symbols, i.e. to trace the whole
154	file.
155
156	If symbol names (or '*') are provided, they must be surrounded by white
157	space.
158
159	The filter passed to the kernel is not necessarily the same as entered.
160	To see the filter that is passed, use the -v option.
161
162	The kernel may not be able to configure a trace region if it is not
163	within a single mapping.  MMAP events (or /proc/<pid>/maps) can be
164	examined to determine if that is a possibility.
165
166	Multiple filters can be separated with space or comma.
167
168--exclude-perf::
169	Don't record events issued by perf itself. This option should follow
170	an event selector (-e) which selects tracepoint event(s). It adds a
171	filter expression 'common_pid != $PERFPID' to filters. If other
172	'--filter' exists, the new filter expression will be combined with
173	them by '&&'.
174
175-a::
176--all-cpus::
177        System-wide collection from all CPUs (default if no target is specified).
178
179-p::
180--pid=::
181	Record events on existing process ID (comma separated list).
182
183-t::
184--tid=::
185        Record events on existing thread ID (comma separated list).
186        This option also disables inheritance by default.  Enable it by adding
187        --inherit.
188
189-u::
190--uid=::
191        Record events in threads owned by uid. Name or number.
192
193-r::
194--realtime=::
195	Collect data with this RT SCHED_FIFO priority.
196
197--no-buffering::
198	Collect data without buffering.
199
200-c::
201--count=::
202	Event period to sample.
203
204-o::
205--output=::
206	Output file name.
207
208-i::
209--no-inherit::
210	Child tasks do not inherit counters.
211
212-F::
213--freq=::
214	Profile at this frequency. Use 'max' to use the currently maximum
215	allowed frequency, i.e. the value in the kernel.perf_event_max_sample_rate
216	sysctl. Will throttle down to the currently maximum allowed frequency.
217	See --strict-freq.
218
219--strict-freq::
220	Fail if the specified frequency can't be used.
221
222-m::
223--mmap-pages=::
224	Number of mmap data pages (must be a power of two) or size
225	specification with appended unit character - B/K/M/G. The
226	size is rounded up to have nearest pages power of two value.
227	Also, by adding a comma, the number of mmap pages for AUX
228	area tracing can be specified.
229
230--group::
231	Put all events in a single event group.  This precedes the --event
232	option and remains only for backward compatibility.  See --event.
233
234-g::
235	Enables call-graph (stack chain/backtrace) recording.
236
237--call-graph::
238	Setup and enable call-graph (stack chain/backtrace) recording,
239	implies -g.  Default is "fp".
240
241	Allows specifying "fp" (frame pointer) or "dwarf"
242	(DWARF's CFI - Call Frame Information) or "lbr"
243	(Hardware Last Branch Record facility) as the method to collect
244	the information used to show the call graphs.
245
246	In some systems, where binaries are build with gcc
247	--fomit-frame-pointer, using the "fp" method will produce bogus
248	call graphs, using "dwarf", if available (perf tools linked to
249	the libunwind or libdw library) should be used instead.
250	Using the "lbr" method doesn't require any compiler options. It
251	will produce call graphs from the hardware LBR registers. The
252	main limitation is that it is only available on new Intel
253	platforms, such as Haswell. It can only get user call chain. It
254	doesn't work with branch stack sampling at the same time.
255
256	When "dwarf" recording is used, perf also records (user) stack dump
257	when sampled.  Default size of the stack dump is 8192 (bytes).
258	User can change the size by passing the size after comma like
259	"--call-graph dwarf,4096".
260
261-q::
262--quiet::
263	Don't print any message, useful for scripting.
264
265-v::
266--verbose::
267	Be more verbose (show counter open errors, etc).
268
269-s::
270--stat::
271	Record per-thread event counts.  Use it with 'perf report -T' to see
272	the values.
273
274-d::
275--data::
276	Record the sample virtual addresses.
277
278--phys-data::
279	Record the sample physical addresses.
280
281-T::
282--timestamp::
283	Record the sample timestamps. Use it with 'perf report -D' to see the
284	timestamps, for instance.
285
286-P::
287--period::
288	Record the sample period.
289
290--sample-cpu::
291	Record the sample cpu.
292
293-n::
294--no-samples::
295	Don't sample.
296
297-R::
298--raw-samples::
299Collect raw sample records from all opened counters (default for tracepoint counters).
300
301-C::
302--cpu::
303Collect samples only on the list of CPUs provided. Multiple CPUs can be provided as a
304comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2.
305In per-thread mode with inheritance mode on (default), samples are captured only when
306the thread executes on the designated CPUs. Default is to monitor all CPUs.
307
308-B::
309--no-buildid::
310Do not save the build ids of binaries in the perf.data files. This skips
311post processing after recording, which sometimes makes the final step in
312the recording process to take a long time, as it needs to process all
313events looking for mmap records. The downside is that it can misresolve
314symbols if the workload binaries used when recording get locally rebuilt
315or upgraded, because the only key available in this case is the
316pathname. You can also set the "record.build-id" config variable to
317'skip to have this behaviour permanently.
318
319-N::
320--no-buildid-cache::
321Do not update the buildid cache. This saves some overhead in situations
322where the information in the perf.data file (which includes buildids)
323is sufficient.  You can also set the "record.build-id" config variable to
324'no-cache' to have the same effect.
325
326-G name,...::
327--cgroup name,...::
328monitor only in the container (cgroup) called "name". This option is available only
329in per-cpu mode. The cgroup filesystem must be mounted. All threads belonging to
330container "name" are monitored when they run on the monitored CPUs. Multiple cgroups
331can be provided. Each cgroup is applied to the corresponding event, i.e., first cgroup
332to first event, second cgroup to second event and so on. It is possible to provide
333an empty cgroup (monitor all the time) using, e.g., -G foo,,bar. Cgroups must have
334corresponding events, i.e., they always refer to events defined earlier on the command
335line. If the user wants to track multiple events for a specific cgroup, the user can
336use '-e e1 -e e2 -G foo,foo' or just use '-e e1 -e e2 -G foo'.
337
338If wanting to monitor, say, 'cycles' for a cgroup and also for system wide, this
339command line can be used: 'perf stat -e cycles -G cgroup_name -a -e cycles'.
340
341-b::
342--branch-any::
343Enable taken branch stack sampling. Any type of taken branch may be sampled.
344This is a shortcut for --branch-filter any. See --branch-filter for more infos.
345
346-j::
347--branch-filter::
348Enable taken branch stack sampling. Each sample captures a series of consecutive
349taken branches. The number of branches captured with each sample depends on the
350underlying hardware, the type of branches of interest, and the executed code.
351It is possible to select the types of branches captured by enabling filters. The
352following filters are defined:
353
354        - any:  any type of branches
355        - any_call: any function call or system call
356        - any_ret: any function return or system call return
357        - ind_call: any indirect branch
358        - call: direct calls, including far (to/from kernel) calls
359        - u:  only when the branch target is at the user level
360        - k: only when the branch target is in the kernel
361        - hv: only when the target is at the hypervisor level
362	- in_tx: only when the target is in a hardware transaction
363	- no_tx: only when the target is not in a hardware transaction
364	- abort_tx: only when the target is a hardware transaction abort
365	- cond: conditional branches
366	- save_type: save branch type during sampling in case binary is not available later
367
368+
369The option requires at least one branch type among any, any_call, any_ret, ind_call, cond.
370The privilege levels may be omitted, in which case, the privilege levels of the associated
371event are applied to the branch filter. Both kernel (k) and hypervisor (hv) privilege
372levels are subject to permissions.  When sampling on multiple events, branch stack sampling
373is enabled for all the sampling events. The sampled branch type is the same for all events.
374The various filters must be specified as a comma separated list: --branch-filter any_ret,u,k
375Note that this feature may not be available on all processors.
376
377--weight::
378Enable weightened sampling. An additional weight is recorded per sample and can be
379displayed with the weight and local_weight sort keys.  This currently works for TSX
380abort events and some memory events in precise mode on modern Intel CPUs.
381
382--namespaces::
383Record events of type PERF_RECORD_NAMESPACES.
384
385--transaction::
386Record transaction flags for transaction related events.
387
388--per-thread::
389Use per-thread mmaps.  By default per-cpu mmaps are created.  This option
390overrides that and uses per-thread mmaps.  A side-effect of that is that
391inheritance is automatically disabled.  --per-thread is ignored with a warning
392if combined with -a or -C options.
393
394-D::
395--delay=::
396After starting the program, wait msecs before measuring. This is useful to
397filter out the startup phase of the program, which is often very different.
398
399-I::
400--intr-regs::
401Capture machine state (registers) at interrupt, i.e., on counter overflows for
402each sample. List of captured registers depends on the architecture. This option
403is off by default. It is possible to select the registers to sample using their
404symbolic names, e.g. on x86, ax, si. To list the available registers use
405--intr-regs=\?. To name registers, pass a comma separated list such as
406--intr-regs=ax,bx. The list of register is architecture dependent.
407
408--user-regs::
409Capture user registers at sample time. Same arguments as -I.
410
411--running-time::
412Record running and enabled time for read events (:S)
413
414-k::
415--clockid::
416Sets the clock id to use for the various time fields in the perf_event_type
417records. See clock_gettime(). In particular CLOCK_MONOTONIC and
418CLOCK_MONOTONIC_RAW are supported, some events might also allow
419CLOCK_BOOTTIME, CLOCK_REALTIME and CLOCK_TAI.
420
421-S::
422--snapshot::
423Select AUX area tracing Snapshot Mode. This option is valid only with an
424AUX area tracing event. Optionally the number of bytes to capture per
425snapshot can be specified. In Snapshot Mode, trace data is captured only when
426signal SIGUSR2 is received.
427
428--proc-map-timeout::
429When processing pre-existing threads /proc/XXX/mmap, it may take a long time,
430because the file may be huge. A time out is needed in such cases.
431This option sets the time out limit. The default value is 500 ms.
432
433--switch-events::
434Record context switch events i.e. events of type PERF_RECORD_SWITCH or
435PERF_RECORD_SWITCH_CPU_WIDE.
436
437--clang-path=PATH::
438Path to clang binary to use for compiling BPF scriptlets.
439(enabled when BPF support is on)
440
441--clang-opt=OPTIONS::
442Options passed to clang when compiling BPF scriptlets.
443(enabled when BPF support is on)
444
445--vmlinux=PATH::
446Specify vmlinux path which has debuginfo.
447(enabled when BPF prologue is on)
448
449--buildid-all::
450Record build-id of all DSOs regardless whether it's actually hit or not.
451
452--aio[=n]::
453Use <n> control blocks in asynchronous (Posix AIO) trace writing mode (default: 1, max: 4).
454Asynchronous mode is supported only when linking Perf tool with libc library
455providing implementation for Posix AIO API.
456
457--affinity=mode::
458Set affinity mask of trace reading thread according to the policy defined by 'mode' value:
459  node - thread affinity mask is set to NUMA node cpu mask of the processed mmap buffer
460  cpu  - thread affinity mask is set to cpu of the processed mmap buffer
461
462--all-kernel::
463Configure all used events to run in kernel space.
464
465--all-user::
466Configure all used events to run in user space.
467
468--timestamp-filename
469Append timestamp to output file name.
470
471--timestamp-boundary::
472Record timestamp boundary (time of first/last samples).
473
474--switch-output[=mode]::
475Generate multiple perf.data files, timestamp prefixed, switching to a new one
476based on 'mode' value:
477  "signal" - when receiving a SIGUSR2 (default value) or
478  <size>   - when reaching the size threshold, size is expected to
479             be a number with appended unit character - B/K/M/G
480  <time>   - when reaching the time threshold, size is expected to
481             be a number with appended unit character - s/m/h/d
482
483             Note: the precision of  the size  threshold  hugely depends
484             on your configuration  - the number and size of  your  ring
485             buffers (-m). It is generally more precise for higher sizes
486             (like >5M), for lower values expect different sizes.
487
488A possible use case is to, given an external event, slice the perf.data file
489that gets then processed, possibly via a perf script, to decide if that
490particular perf.data snapshot should be kept or not.
491
492Implies --timestamp-filename, --no-buildid and --no-buildid-cache.
493The reason for the latter two is to reduce the data file switching
494overhead. You can still switch them on with:
495
496  --switch-output --no-no-buildid  --no-no-buildid-cache
497
498--switch-max-files=N::
499
500When rotating perf.data with --switch-output, only keep N files.
501
502--dry-run::
503Parse options then exit. --dry-run can be used to detect errors in cmdline
504options.
505
506'perf record --dry-run -e' can act as a BPF script compiler if llvm.dump-obj
507in config file is set to true.
508
509--tail-synthesize::
510Instead of collecting non-sample events (for example, fork, comm, mmap) at
511the beginning of record, collect them during finalizing an output file.
512The collected non-sample events reflects the status of the system when
513record is finished.
514
515--overwrite::
516Makes all events use an overwritable ring buffer. An overwritable ring
517buffer works like a flight recorder: when it gets full, the kernel will
518overwrite the oldest records, that thus will never make it to the
519perf.data file.
520
521When '--overwrite' and '--switch-output' are used perf records and drops
522events until it receives a signal, meaning that something unusual was
523detected that warrants taking a snapshot of the most current events,
524those fitting in the ring buffer at that moment.
525
526'overwrite' attribute can also be set or canceled for an event using
527config terms. For example: 'cycles/overwrite/' and 'instructions/no-overwrite/'.
528
529Implies --tail-synthesize.
530
531SEE ALSO
532--------
533linkperf:perf-stat[1], linkperf:perf-list[1]
534